-
Notifications
You must be signed in to change notification settings - Fork 133
/
README.Rmd
340 lines (253 loc) · 15.8 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
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
---
title : "<img src='tools/images/papaja_hex.png' align='right' height='150' />papaja: Prepare APA Journal Articles<br />with R Markdown"
output: github_document
# github_document:
# toc: true
# toc_depth: 2
---
```{r include = FALSE}
if(!requireNamespace("depgraph", quietly = TRUE)) remotes::install_github("crsh/depgraph")
```
<!-- README.md is generated from README.Rmd. Please edit that file -->
[]( https://cran.r-project.org/package=papaja) [](https://www.repostatus.org/#active)  [](https://github.com/crsh/papaja/actions/workflows/R-CMD-check.yaml) [](https://app.codecov.io/gh/crsh/papaja) [](https://github.com/crsh/papaja/issues?q=is%3Aopen+is%3Aissue+label%3Abug) [](https://stackoverflow.com/questions/tagged/papaja)
**Sections** [Example](#example) | [Installation](#installation) | [Usage](#usage) | [Getting help](#getting-help) | [Citation](#citation) | [papaja in the wild](#papaja-in-the-wild) | [Computational reproducibility](#computational-reproducibility) | [Contribute](#contribute) | [Related R packages](#related-r-packages) | [Package dependencies](#package-dependencies)
**papaja** is an [award-winning](https://improvingpsych.org/mission/awards/) R package that facilitates creating computationally reproducible, submission-ready manuscripts which conform to the American Psychological Association (APA) manuscript guidelines (6th Edition).
**papaja** provides
- an [R Markdown](https://rmarkdown.rstudio.com/) template that can be used with (or without) [RStudio](https://posit.co/) to create PDF documents (using the [apa6](http://www.ctan.org/pkg/apa6) LaTeX class) or Word documents (using a .docx-reference file).
- Functions to **typeset** the results from **statistical analyses**,
- functions to create **tables**, and
- functions to create **figures** in accordance with APA guidelines.
For a comprehensive introduction to **papaja**, see the current draft of the [manual](https://frederikaust.com/papaja_man/).
If you have a specific question that is not answered in the manual, feel free to ask a question on Stack Overflow [using the **papaja** tag](https://stackoverflow.com/questions/tagged/papaja).
If you believe you have found a bug or would like to request a new feature, [open an issue](https://github.com/crsh/papaja/issues) on Github and provide a [minimal complete verifiable example](https://stackoverflow.com/help/minimal-reproducible-example).
## Example
Take a look at the [source file](https://github.com/crsh/papaja/blob/master/vignettes/papaja.Rmd) of the package vignette and the resulting [PDF](https://raw.githubusercontent.com/crsh/papaja/master/vignettes/papaja.pdf).
The vignette also contains some basic instructions.
## Installation
To use **papaja** you need either a recent version of [RStudio](https://posit.co/) or [pandoc](https://pandoc.org/).
If you want to create PDF- in addition to DOCX-documents you additionally need a [TeX](https://en.wikipedia.org/wiki/TeX) distribution.
We recommend you use [TinyTex](https://yihui.org/tinytex/), which can be installed from within R:
```{r eval = FALSE}
if(!requireNamespace("tinytex", quietly = TRUE)) install.packages("tinytex")
tinytex::install_tinytex()
```
You may also consider [MikTeX](https://miktex.org/) for Windows, [MacTeX](https://tug.org/mactex/) for Mac, or [TeX Live](https://tug.org/texlive/) for Linux.
Please refer to the [**papaja** manual](https://frederikaust.com/papaja_man/introduction.html#getting-started) for detailed installation instructions.
**papaja** is available on CRAN but you can also install it from the GitHub repository:
```{r install_papapja, eval = FALSE}
# Install latest CRAN release
install.packages("papaja")
# Install remotes package if necessary
if(!requireNamespace("remotes", quietly = TRUE)) install.packages("remotes")
# Install the stable development version from GitHub
remotes::install_github("crsh/papaja")
```
## Usage
Once **papaja** is installed, you can select the APA template when creating a new R Markdown file through the RStudio menus.
To add citations, specify your bibliography-file in the YAML front matter of the document (`bibliography: my.bib`) and start citing (for details, see pandoc manual on the [citeproc extension](https://pandoc.org/MANUAL.html#extension-citations). You may also be interested in [**citr**](https://github.com/crsh/citr), an R Studio addin to swiftly insert Markdown citations and [R Studio's visual editor](https://rstudio.github.io/visual-markdown-editing/), which also enables swiftly [inserting citations](https://rstudio.github.io/visual-markdown-editing/citations.html).
### Typeset analysis results
The functions `apa_print()` and `apa_table()` facilitate reporting results of your analyses.
When you pass the an output object of a supported class, such as an `htest`- or `lm`-object, to `apa_print()`, it will return a list of character strings that you can use to report the results of your analysis.
```{r echo = FALSE, message = FALSE, warning = FALSE, results = 'hide'}
library("papaja")
```
```{r}
my_lm <- lm(
Sepal.Width ~ Sepal.Length + Petal.Width + Petal.Length
, data = iris
)
apa_lm <- apa_print(my_lm)
apa_lm$full_result$Sepal_Length
```
**papaja** currently provides methods for the following object classes:
```{r echo = FALSE, results = "asis"}
print_classes <- gsub("apa_print\\.", "", as.character(utils::methods("apa_print")))
print_classes <- print_classes[!grepl(",", print_classes)]
print_classes <- c(print_classes, rep(NA, (4 - length(print_classes) %% 4) * (length(print_classes) %% 4 > 0)))
print_classes <- matrix(print_classes, ncol = 4)
colnames(print_classes) <- apply(print_classes, 2, function(x) {
first_letters <- tolower(substr(x, 1, 1))
first_letters <- c(first_letters[1], tail(first_letters, 1))
first_letters[is.na(first_letters)] <- "z"
col_names <- if(first_letters[1] == first_letters[2]) first_letters[1] else paste(first_letters, collapse = "-")
toupper(col_names)
})
print_classes[is.na(print_classes)] <- ""
knitr::kable(print_classes)
```
### Create tables
`apa_table()` may be used to produce publication-ready tables in an R Markdown document.
For instance, you might want to report some condition means (with standard errors).
```{r message = FALSE, eval = FALSE}
npk |>
# Summarize data
dplyr::group_by(N, P) |>
dplyr::summarise(
mean = mean(yield)
, se = sd(yield) / sqrt(length(yield))
, .groups = "drop"
) |>
# Label columns
label_variables(
N = "Nitrogen"
, P = "Phosphate"
, mean = "*M*"
, se = "*SE*"
) |>
# Print table
apa_table(caption = "Mean pea yield (with standard errors)")
```
Table 1.
*Mean pea yield (with standard errors)*
```{r echo = FALSE, message = FALSE}
library("dplyr")
out <- npk %>%
group_by(N, P) %>%
summarise(mean = mean(yield), se = sd(yield) / sqrt(length(yield)), .groups = "drop")
colnames(out) <- c("Nitrogen", "Phosphate", "*M*", "*SE*")
knitr::kable(out, align = "c", digits = 2)
```
This is a fairly simple example, but `apa_table()` may be used to generate [more complex tables](https://osf.io/s4968/).
`apa_table()`, of course, plays nicely with the output from `apa_print()`.
Thus, it is possible to conveniently report complete regression tables, ANOVA tables, or the output from mixed-effects models.
```{r eval = FALSE}
lm(Sepal.Width ~ Sepal.Length + Petal.Width + Petal.Length, data = iris) |>
apa_print() |>
apa_table(caption = "Iris regression table.")
```
Table 2.
*Iris regression table.*
```{r echo = FALSE}
out <- lm(Sepal.Width ~ Sepal.Length + Petal.Width + Petal.Length, data = iris) |>
apa_print()
out$table$p.value <- gsub(" ", " ", out$table$p.value)
col_labels <- unlist(variable_labels(out$table))
col_labels["df"] <- "$df$"
colnames(out$table) <- gsub("\\$", "*", col_labels)
knitr::kable(out$table, align = "lrcrr")
```
### Create figures
**papaja** further provides functions to create publication-ready plots.
For example, you can use `apa_barplot()`, `apa_lineplot()`, and `apa_beeplot()` (or the general function `apa_factorial_plot()`) to visualize the results of factorial study designs:
```{r include = FALSE}
set.seed(42L)
x <- expand.grid(
id = seq_len(80L)
, congruency = c("Congruent", "Incongruent")
, load = c("High", "Low")
)
x[["response_time"]] <- rt(nrow(x), df = 20) * 80 +
(x$congruency == "Congruent") * - 80 +
(x$load == "High") * 40 +
500
variable_labels(x) <- list(
congruency = "Congruency"
, load = "Cognitive load"
, response_time = "Response time"
)
stroop_data <- x
```
```{r stroop-plot, fig.cap = "Response times from a simulated Stroop experiment. Large dots represent condition means, small dots represent individual participants' mean response time. Error bars represent 99% within-subjects confidence intervals."}
apa_beeplot(
data = stroop_data
, dv = "response_time"
, id = "id"
, factors = c("congruency", "load")
, ylim = c(0, 800)
, dispersion = wsci # within-subjects confidence intervals
, conf.level = .99
, las = 1
)
```
If you prefer `ggplot2`, try `theme_apa()`.
```{r stroop-ggplot}
library("ggplot2")
library("ggforce")
p <- ggplot(
stroop_data
, aes(x = congruency, y = response_time, shape = load, fill = load)
) +
geom_violin(alpha = 0.2, color = grey(0.6)) +
geom_sina(color = grey(0.6)) +
stat_summary(position = position_dodge2(0.95), fun.data = mean_cl_normal) +
lims(y = c(0, max(stroop_data$response_time))) +
scale_shape_manual(values = c(21, 22)) +
scale_fill_grey(start = 0.6, end = 1) +
labs(
x = "Congruency"
, y = "Response time"
, shape = "Cognitive load"
, fill = "Cognitive load"
)
p + theme_apa()
```
### Usage without RStudio
Don't use RStudio?
No problem.
Use the `rmarkdown::render` function to create articles:
``` r
# Create new R Markdown file
rmarkdown::draft(
"mymanuscript.Rmd"
, "apa6"
, package = "papaja"
, create_dir = FALSE
, edit = FALSE
)
# Render manuscript
rmarkdown::render("mymanuscript.Rmd")
```
## Getting help
[](https://stackoverflow.com/questions/tagged/papaja)
For a comprehensive introduction to **papaja**, check out the current draft of the [**papaja** manual](https://frederikaust.com/papaja_man/).
If you have a specific question that is not answered in the manual, feel free to ask a question on Stack Overflow [using the **papaja** tag](https://stackoverflow.com/questions/tagged/papaja).
If you believe you have found a bug or you want to request a new feature, [open an issue](https://github.com/crsh/papaja/issues) on Github and provide a [minimal complete verifiable example](https://stackoverflow.com/help/minimal-reproducible-example).
## Citation
Please cite **papaja** if you use it.
`r attr(unclass(citation("papaja"))[[1]], "textVersion")`
For convenience, you can [use `cite_r()`](https://frederikaust.com/papaja_man/writing.html#citing-r-and-its-packages) or copy the reference information returned by `citation('papaja')` to your BibTeX file:
~~~bibtex
```{r echo = FALSE, results = "asis"}
print(citation("papaja"), style = "Bibtex")
```
~~~
## papaja in the wild
If you are interested in seeing how others are using **papaja**, you can find a [collection of papers](https://frederikaust.com/papaja_man/published-manuscripts.html) and the corresponding R Markdown files in the manual.
If you have published a paper that was written with **papaja**, please add the reference to the [public Zotero group](https://www.zotero.org/groups/2202906/papaja) yourself or send us to me.
## Computational reproducibility
To ensure mid- to long-term computational reproducibility we highly recommend conserving the software environment used to write a manuscript (e.g. R and all R packages) either in a software container or a virtual machine.
This way you can be sure that your R code does not break because of updates to R or any R package.
For a brief primer on containers and virtual machines see [the supplementary material](https://psych-transparency-guide.uni-koeln.de/analytic-reproducibility.html#document-hardware-and-software-used-for-analyses) by Klein et al. (2018).
[Docker](https://www.docker.com/) is the most widely used containerization approach.
It is open source and free to use but requires some disk space.
[CodeOcean](https://codeocean.com/) is a commercial service that builds on Docker, facilitates setting up and sharing containers and lets you run computations in the cloud.
See the **papaja** manual on [how to get started using **papaja** with Docker or CodeOcean](https://frederikaust.com/papaja_man/tips-and-tricks.html#reproducible-software-environments) and [our Docker workflow](https://github.com/crsh/papaja_docker) tailored for easy use with **papaja**.
## Contribute
[](https://github.com/crsh/papaja/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) [](https://github.com/crsh/papaja/issues?q=is%3Aopen+is%3Aissue+label%3Adocumentation)
Like **papaja** and want to contribute?
We highly appreciate any contributions to the R package or its documentation.
Take a look at the [open issues](https://github.com/crsh/papaja/issues) if you need inspiration.
There are many additional analyses that we would like `apa_print()` to support.
Any new S3/S4-methods for this function are always appreciated (e.g., `factanal`, `fa`, `lavaan`).
For a primer on adding new `apa_print()`-methods, see the getting-started-vignette:
```r
vignette("extending_apa_print", package = "papaja")
```
Before working on a contribution, please review our brief [contributing guidelines](https://github.com/crsh/papaja/blob/main/.github/CONTRIBUTING.md) and [code of conduct](https://github.com/crsh/papaja/blob/main/CODE_OF_CONDUCT.md).
## Related R packages
By now, there are a couple of R packages that provide convenience functions to facilitate the reporting of statistics in accordance with APA guidelines.
- [**apa**](https://github.com/dgromer/apa): Format output of statistical tests in R according to APA guidelines
- [**APAstats**](https://github.com/achetverikov/APAstats): R functions for formatting results in APA style and other stuff
- [**apaTables**](https://github.com/dstanley4/apaTables): Create American Psychological Association (APA) Style Tables
- [**rempsyc**](https://github.com/RemPsyc/rempsyc): Convenience functions for psychology
- [**sigr**](https://github.com/WinVector/sigr): Concise formatting of significances in R
- [**apaquarto**](https://github.com/wjschne/apaquarto): A quarto extension for creating APA7 documents in .docx, .html, and .pdf formats
If you are looking for other journal article templates, you may be interested in the [**rticles**](https://github.com/rstudio/rticles) package.
## Package dependencies
```{r dep-plot, echo = FALSE, fig.width = 10, fig.height = 9, message = FALSE, warning = FALSE}
depgraph::plot_dependency_graph(
pkg = "."
, repos = "https://cran.rstudio.com/"
)
```