3 Writing

  • RStudio
    • Section overview
    • Spell check

3.1 Markdown text formatting

A comprehensive overview of the supported Markdown syntax is provided by RStudio’s R Markdown documentation.

3.2 Citations

If you are not already using a reference manager, such as Zotero, I strongly suggest you start doing so. Reference managers are like iTunes for your literature; they help you search, download, and organize papers. Most importantly, with a few clicks you can export a collection of references you need for a paper into a .bib-file.

By default, citations in R Markdown are formatted by pandoc-citeproc, a filter that pandoc applies as it renders the final document. The advantage of using pandoc-citeproc is that it works equally well for both PDF and Microsoft Word documents. To start citing, supply a Bib(La)TeX (or for example EndNote, RIS, Medline) file to the bibliography parameter in the YAML front matter (bibliography: my.bib). Once the R Markdown file knows where to look for reference [@james_1890] will create a citation within parentheses (James, 1890). Multiple citations must be separated by ; (e.g., [@james_1890; @bem_2011]) and are ordered alphabetically as per APA style (Bem, 2011; James, 1890). To cite a source in text simply omit the brackets; for example, write @james_1890 to cite James (1890).

Citation type Syntax Rendered citation
Citation within parentheses [@james_1890] (James, 1890)
Multiple citations [@james_1890; @bem_2011] (Bem, 2011; James, 1890)
In-text citations @james_1890 James (1890)
Year only [-@bem_2011] (2011)

Additional information can be added to citations as pre- or postfixes. Pre- and postfixes can simply be added to each citation by writing inside the brackets ([e.g., @bem_2011]). Note that pre- and postfixes are bound to the enclosed citation, not to the set of all citations. Hence, a prefix will be reorder together with its citation, which may be undesirable. For example, [e.g., @james_1890; @bem_2011] yields (e.g., James, 1890; Bem, 2011). There is no way to prevent this behavior, so mind the alphabetical order of citations.

Further customizations, such as citing only a publications year ([-@bem_2011]) are available, see RStudio’s overview of the R Markdown citation syntax. If you are not interested in creating Microsoft Word documents it’s possible to use NatBib or Bib(La)TeX for reference formatting, which grant a little more flexibility than pandoc-citeproc. To do so, an additional argument has to be supplied to apa6_pdf():

3.2.1 Citation styles

The citation style is automatically set to APA style. Other styles can be set in the YAML front matter by specifying a CSL, or Citations Style Language, file. You can use either one of the large number of existing CSL files, customize an existing CSL file, or create a new one entirely. To change the citation style, add a csl: mystyle.csl to the YAML front matter. See the R Markdown documentation and Citation Style Language for further details.

3.2.2 Conveniently inserting citations with citr

citr is an R package that provides functions to search Bib(La)TeX-files to create and insert formatted Markdown citations into the current document. If you use RStudio, the package supplies an easy-to-use RStudio add-in that facilitates inserting citations (Figure 3.1). The references for the inserted citations are automatically added to the documents reference section.

Demonstration of the RStudio addin from the `citr` package that inserts R Markdown citations.

Figure 3.1: Demonstration of the RStudio addin from the citr package that inserts R Markdown citations.

Once citr is installed (install.packages("citr")) and you have restarted your R session, the addin appears in the menus and you can define a keyboard shortcut to call the addin (we suggest Alt+Shift+R).

The addin will automatically look up the Bib(La)TeX-file(s) specified in the YAML front matter. If the document does not contain a YAML front matter the addin will attempt to locate a parent document and look up the Bib(La)TeX-file specified therein. That is, the addin works its automagic even if you edit R Markdown documents that are included in another R Markdown document (see Splitting an R Markdown document). The expected names of a parent document default to c("index.Rmd", "master.Rmd"), but those can be customized (e.g., options(citr.parent_documents = "my_parent.Rmd")).

citr can also be used without RStudio, albeit it is less convenient. The following call searches a Bib(La)TeX-file and creates formatted Markdown citations for the results.

md_cite() searches the author, year, title, and journal fields of your references.

3.2.2.1 Working with a reference manager

If you use Zotero or Juris-M citr can access your reference database without previous export. For this to work, you need to install the Better Bib(La)TeX extension, which we recommend even if you don’t intend to use citr. Once the extension is installed and the reference manager is running, citr will automatically access all your references and keep the Bib(La)Tex-file specified in the current R Markdown file up-to-date. If you dislike this behavior, you can disable the automatic access to the reference manager by setting options(citr.use_betterbiblatex = FALSE).

3.2.3 Meta-analysis references

When reporting meta-analyses APA guidelines require that studies included in the meta analysis are included in the reference section and preceeded by an asterisk (p. 138, American Psychological Association, 2010). There are two approaches to mark meta-analysis references.

First, we have created a variant of the widely available APA CSL file that enables adding the required asteriskes. To use this variant insert the following into YAML front matter.

Alternatively, you can download the file and use the location on your hard drive instead of the above URL. Now any refernces that has an annotation field will be preceeded by an asterisk.

@article{aust_memory-based_2018,
  author = {Aust, Frederik and Haaf, Julia M. and Stahl, Christoph},
  title = {A Memory-Based Judgment Account of Expectancy-Liking Dissociations in Evaluative Conditioning.},
  date = {2018},
  journaltitle = {Journal of Experimental Psychology: Learning, Memory, and Cognition},
  doi = {10.1037/xlm0000600},
  annotation = {meta-analysis}
}

To include references that are not explicitly cited in the paper, you can use the nocite field of the YAML front matter.

Finally, the APA guidelines require a note at the start of the reference section that explains what an asterisk means. This note can be added at the end of the document as follows.

Second, if you prefer \(\LaTeX\) to generate the bibliographic information, we recommend you use biblatex-apa by adding the following to the YAML front matter.

Additionally, you need to define a language mapping and to define a custom \(LaTeX\) command that can be used to add meta-analysis references.

In the document you can use this custom command to add meta-analysis references.

No entry in the annotation field of the reference is required. As usual, any non-meta-analysis citation can be added using the pandoc-citeproc syntax, e.g. [@R-papaja]. The note that explains what an asterisk means can be added at the end of the document as follows.

3.2.4 Citing R and its packages

A lot of R packages are developed by academics free of charge. As citations are the currency of science, it’s easy to compensate volunteers for their work by citing the R packages we use. Howerver, citing software is rarely done arguebly because it is tedious work. papaja therefore supplies two functions that make citing R and its packages easy.

r_refs() creates a BibTeX file containing citations for R and packages that are in use at the time the function is executed. cite_r() takes these citations and turns them into readily reportable text. my_citations now contains the following text that you can use in your document:

R (Version 3.5.1; R Core Team, 2016) and the R-packages afex (Version 0.21.2; Singmann et al., 2016), bindrcpp (Version 0.2.2; Müller, 2017), car (Version 3.0.0; Fox & Weisberg, 2011; Fox et al., 2018), carData (Version 3.0.1; Fox et al., 2018), citr (Version 0.2.0.9055; Aust, 2016), DiagrammeR (Version 1.0.0; Sveidqvist et al., 2016), dplyr (Version 0.7.7; Wickham & Francois, 2016), estimability (Version 1.3; Lenth, 2015), ez (Lawrence, 2016), ggplot2 (Version 3.0.0; Wickham, 2009), knitr (Version 1.20; Xie, 2015), lme4 (Version 1.1.17; Bates et al., 2015), lsmeans (Version 2.27.62; Lenth, 2016), Matrix (Version 1.2.14; Bates & Maechler, 2016), papaja (Version 0.1.0.9842; Aust & Barth, 2016), reshape2 (Version 1.4.3; Wickham, 2007), rmarkdown (Version 1.10; Allaire et al., 2017), shiny (Version 1.2.0; Chang et al., 2016), and wordcountaddin (Marwick, n.d.)

If you prefer to cite only a subset of these packages, package names can be specified either as a blacklist, so they won’t be cited (withhold = TRUE), or as a whitelist, so only these packages will be cited (withhold = FALSE).

R (Version 3.5.1; R Core Team, 2016) and the R-packages afex (Version 0.21.2; Singmann et al., 2016), lsmeans (Version 2.27.62; Lenth, 2016), and papaja (Version 0.1.0.9842; Aust & Barth, 2016)

Another option is to cite R in text but move the list of R packges into a footnote.

This way you can reference R in the running text using my_citations$r and place the footnote syntax including the package list my_citations$pkgs in a new paragraph.

R (Version 3.5.1; R Core Team, 2016)2

3.3 Equations

If you need to report formulas, you can use the flexible \(\LaTeX\) syntax (it will work in Word documents, too). Inline math must be enclosed in $ or \( and \) and the result will look like this: \(d' = z(\mathrm{H}) - z(\mathrm{FA})\). For larger formulas displayed equations are more appropriate; they are enclosed in $$ or \[and \],

\[ d' = \frac{\mu_{old} - \mu_{new}}{\sqrt{0.5(\sigma^2_{old} + \sigma^2_{new})}}. \]

3.4 Cross-referencing

papaja builds on the document formats pdf_document2() and word_document2() from the bookdown package. This enables the use of bookdown cross-referencing syntax including automatically generated table and figure labels as detailed in the bookdown documentation.

To cross-reference figures and tables use \@ref(fig:chunk-label) or
\@ref(tab:chunk-label)

  • Only works if chunk labels don’t contain _
  • Precede by non-breaking spaces, e.g.
    Figure\ \@ref(fig:chunk-label)

3.5 Appendices

Appendices should be in a separate file
(e.g., appendix.Rmd)

  • One level-1 heading
  • No YAML front matter

The R code is executed after the main document; all packages and variables from the main document should be available.

Multiple appendices are possible

References

James, W. (1890). The principles of psychology. Holt: New York.

Bem, D. J. (2011). Feeling the future: Experimental evidence for anomalous retroactive influences on cognition and affect. Journal of Personality and Social Psychology, 100(3), 407—425. doi:10.1037/a0021524

American Psychological Association. (2010). Publication Manual of the American Psychological Association (6th edition.). Washington, DC: American Psychological Association.

R Core Team. (2016). R: A language and environment for statistical computing. Vienna, Austria: R Foundation for Statistical Computing. Retrieved from https://www.R-project.org/

Singmann, H., Bolker, B., Westfall, J., & Aust, F. (2016). Afex: Analysis of factorial experiments. Retrieved from https://CRAN.R-project.org/package=afex

Müller, K. (2017). Bindrcpp: An ’rcpp’ interface to active bindings. Retrieved from https://CRAN.R-project.org/package=bindrcpp

Fox, J., & Weisberg, S. (2011). An R companion to applied regression (Second.). Thousand Oaks CA: Sage. Retrieved from http://socserv.socsci.mcmaster.ca/jfox/Books/Companion

Fox, J., Weisberg, S., & Price, B. (2018). CarData: Companion to applied regression data sets. Retrieved from https://CRAN.R-project.org/package=carData

Aust, F. (2016). Citr: ’RStudio’ add-in to insert markdown citations. Retrieved from https://CRAN.R-project.org/package=citr

Sveidqvist, K., Bostock, M., Pettitt, C., Daines, M., Kashcha, A., & Iannone, R. (2016). DiagrammeR: Create graph diagrams and flowcharts using r. Retrieved from https://CRAN.R-project.org/package=DiagrammeR

Wickham, H., & Francois, R. (2016). Dplyr: A grammar of data manipulation. Retrieved from https://CRAN.R-project.org/package=dplyr

Lenth, R. V. (2015). Estimability: Tools for assessing estimability of linear predictions. Retrieved from https://CRAN.R-project.org/package=estimability

Lawrence, M. A. (2016). Ez: Easy analysis and visualization of factorial experiments. Retrieved from https://CRAN.R-project.org/package=ez

Wickham, H. (2009). Ggplot2: Elegant graphics for data analysis. Springer-Verlag New York. Retrieved from http://ggplot2.org

Xie, Y. (2015). Dynamic documents with R and knitr (2nd ed.). Boca Raton, Florida: Chapman; Hall/CRC. Retrieved from http://yihui.name/knitr/

Bates, D., Mächler, M., Bolker, B., & Walker, S. (2015). Fitting linear mixed-effects models using lme4. Journal of Statistical Software, 67(1), 1–48. doi:10.18637/jss.v067.i01

Lenth, R. V. (2016). Least-squares means: The R package lsmeans. Journal of Statistical Software, 69(1), 1–33. doi:10.18637/jss.v069.i01

Bates, D., & Maechler, M. (2016). Matrix: Sparse and dense matrix classes and methods. Retrieved from https://CRAN.R-project.org/package=Matrix

Aust, F., & Barth, M. (2016). Papaja: Create apa manuscripts with rmarkdown. Retrieved from https://github.com/crsh/papaja

Wickham, H. (2007). Reshaping data with the reshape package. Journal of Statistical Software, 21(12), 1–20. Retrieved from http://www.jstatsoft.org/v21/i12/

Allaire, J., Xie, Y., McPherson, J., Luraschi, J., Ushey, K., Atkins, A., … Chang, W. (2017). Rmarkdown: Dynamic documents for r. Retrieved from https://CRAN.R-project.org/package=rmarkdown

Chang, W., Cheng, J., Allaire, J., Xie, Y., & McPherson, J. (2016). Shiny: Web application framework for r. Retrieved from http://shiny.rstudio.com


  1. We, furthermore, used the R-packages afex (Version 0.21.2; Singmann et al., 2016), bindrcpp (Version 0.2.2; Müller, 2017), car (Version 3.0.0; Fox & Weisberg, 2011; Fox et al., 2018), carData (Version 3.0.1; Fox et al., 2018), citr (Version 0.2.0.9055; Aust, 2016), DiagrammeR (Version 1.0.0; Sveidqvist et al., 2016), dplyr (Version 0.7.7; Wickham & Francois, 2016), estimability (Version 1.3; Lenth, 2015), ez (Lawrence, 2016), ggplot2 (Version 3.0.0; Wickham, 2009), knitr (Version 1.20; Xie, 2015), lme4 (Version 1.1.17; Bates et al., 2015), lsmeans (Version 2.27.62; Lenth, 2016), Matrix (Version 1.2.14; Bates & Maechler, 2016), papaja (Version 0.1.0.9842; Aust & Barth, 2016), reshape2 (Version 1.4.3; Wickham, 2007), rmarkdown (Version 1.10; Allaire et al., 2017), shiny (Version 1.2.0; Chang et al., 2016), and wordcountaddin (Marwick, n.d.).

Comments and Questions


Icons by Icons8