-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.Rmd
154 lines (108 loc) · 7.32 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
---
output: github_document
editor_options:
markdown:
wrap: 72
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# cocoon <a href="https://jeffreyrstevens.github.io/cocoon/"><img src="man/figures/logo.png" align="right" height="139" alt="cocoon website" /></a>
<!-- badges: start -->
[](https://www.repostatus.org/#active)
[](https://lifecycle.r-lib.org/articles/stages.html#stable)
[](https://cran.r-project.org/package=cocoon)
[](https://CRAN.R-project.org/package=cocoon)
[](https://app.codecov.io/gh/JeffreyRStevens/cocoon)
[](https://github.com/JeffreyRStevens/cocoon/actions/workflows/R-CMD-check.yaml)
<!-- badges: end -->
The goal of `{cocoon}` is to provide functions that flexibly format statistical
output in a way that can be inserted into R Markdown or Quarto documents.
This is analogous to the
[`apa_print()`](https://frederikaust.com/papaja_man/reporting.html#statistical-models-and-tests)
functions in the [`{papaja}`](https://github.com/crsh/papaja) package, but
functions in `{cocoon}` can print Markdown or LaTeX syntax. If your output
document is a PDF, this doesn't matter. But if your output document is a Word
document (as required by many journal publishers), Markdown syntax generates
editable output instead of an image of output.
The default style for statistical output follows [American
Psychological Association style](https://apastyle.apa.org/), but many
defaults can be over-ridden to flexibly format output.
## Installation
You can install the stable released version of `{cocoon}` from [CRAN](https://cran.r-project.org/package=cocoon) with:
```{r eval = FALSE}
install.packages("cocoon")
```
You can install the development version of `{cocoon}` from
[GitHub](https://github.com/) with:
```{r eval = FALSE}
# install.packages("remotes")
remotes::install_github("JeffreyRStevens/cocoon")
```
## Example
For an example, we'll create a correlation from the `mtcars` data set.
```{r example}
library(cocoon)
(cars_corr <- cor.test(mtcars$mpg, mtcars$disp))
```
Now we can apply the `format_stats()` function to `cars_corr` to create a
Markdown-formatted character string for the statistical results. We can
embed this as inline R Markdown code to generate the results.
#### Code
``Fuel efficiency and engine displacement were highly correlated (`r knitr::inline_expr('format_stats(cars_corr)')`). ``
#### Output
Fuel efficiency and engine displacement were highly correlated
(`r format_stats(cars_corr)`).
### Control formatting
We can also alter the output to allow other formatting. For instance, we may not like APA's silly rule to remove leading zeros before a value that cannot exceed 1 (like correlations and p-values). And we may not want to include the confidence limits around the correlation coefficient. Finally, maybe we don't want the statistics labels to be italicized.
#### Code
``Fuel efficiency and engine displacement were highly correlated (`r knitr::inline_expr('format_stats(cars_corr, pzero = TRUE, full = FALSE, italics = FALSE)')`). ``
#### Output
Fuel efficiency and engine displacement were highly correlated
(`r format_stats(cars_corr, pzero = TRUE, full = FALSE, italics = FALSE)`).
## Functions and formatting types
* `format_stats()`: Statistical objects
- Correlations (output from `cor.test()` and `correlation::correlation()`,
including Pearson's, Kendall's, and Spearman's correlations)
- Student t-tests, Wilcoxon rank sum, and signed rank tests (output
from `t.test()` and `wilcox.test()`, including one-sample, two-sample
independent, and paired tests)
- ANOVAs from `aov()`
- Linear models from `lm()`, generalized linear models from `glm()`, linear
mixed models from `lme4::lmer()` and `lmerTest::lmer()`, and generalized linear mixed models from
`lme4::glmer()`
- Bayes factors (output from [`{BayesFactor}`](https://cran.r-project.org/package=BayesFactor) package)
* `format_summary()`: Means and error (calculates from vector or uses vector
of mean and error interval or mean, lower error limit, and upper error limit)
* `format_p()`: P-values
* `format_bf()`: Bayes factors (numerics)
* `format_scientific()`: Scientific notation
* `format_num()`: Other numbers
* `format_chr()`: Italicize character strings
## Related packages
* [`{papaja}`](https://github.com/crsh/papaja) - This package uses the `apa_print()` function to convert a number of R statistical objects into R Markdown output. However, it only outputs LaTeX syntax and only generates APA formatted output with minimal flexibility to alter the output.
* [`{apa}`](https://github.com/dgromer/apa) - This package also converts some R statistical objects to R Markdown output. While it allows other output format such as Markdown, it also only generates APA formatted output with minimal flexibility to alter the output.
* [`{insight}`](https://easystats.github.io/insight/) - This package extracts information from model objects. It includes `format_p()` and `format_bf()` functions that achieves similar goals as in this package, but they do not allow as much control over formatting of the labels or values.
## Citation
To cite `{cocoon}`, use:
> Stevens, Jeffrey R. (2024). cocoon: Extract, format, and print statistical output.
> (version 0.1.0)
> <https://github.com/JeffreyRStevens/cocoon>
## Contributing
[Contributions](https://jeffreyrstevens.github.io/cocoon/CONTRIBUTING.html) to `{cocoon}` are most welcome! Feel free to check out [open issues](https://github.com/JeffreyRStevens/cocoon/issues) for ideas. And [pull requests](https://github.com/JeffreyRStevens/cocoon/pulls) are encouraged, but you may want to [raise an issue](https://github.com/JeffreyRStevens/cocoon/issues/new/choose) or [contact the maintainer](mailto:[email protected]) first.
Please note that the cocoon project is released with a [Contributor Code of Conduct](https://jeffreyrstevens.github.io/cocoon/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms.
## Package name
The package name `{cocoon}` captures the main goal of transforming statistical inputs into nicely formatted outputs. This mirrors cocoons, which caterpillars build to transform into beautiful adult insects. [Cocoons](https://en.wikipedia.org/wiki/Pupa) are formally defined as a case that the larvae of moths spin around their pupa. So cocoons are cases built by moths and some other insects, whereas butterflies produce a chrysalis, which forms from their skin.
```{r}
#| echo: false
#| fig.alt: Three white moths on fuzzy white cocoons.
#| out.width: 600
knitr::include_graphics("man/figures/silkmoths.png")
```
Photo source: Silk moths from [Wikimedia Commons](https://commons.wikimedia.org/wiki/File:6_Monster_Silk_Moths.jpg)