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).

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 (Bem, 2011; e.g., James, 1890). 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():

---
output:
  papaja::apa6_pdf:
    citation_package: biblatex
---

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.

library("citr")
md_cite("bem", bib_file = "references.bib")

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

3.2.3 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.4 Referencing 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(file = "r-references.bib")
my_citations <- cite_r(file = "r-references.bib")

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.4.4; R Core Team, 2016) and the R-packages afex (Version 0.20.1; Singmann et al., 2016), bindrcpp (Version 0.2; Müller, 2017), car (Version 2.1.6; Fox & Weisberg, 2011), citr (Version 0.2.0.9055; Aust, 2016), DiagrammeR (Version 0.9.2; Sveidqvist et al., 2016), dplyr (Version 0.7.4; Wickham & Francois, 2016), estimability (Version 1.3; Lenth, 2015), ez (Version 4.4.0; Lawrence, 2016), knitr (Version 1.20; Xie, 2015), lme4 (Version 1.1.15; Bates et al., 2015), lsmeans (Version 2.27.61; Lenth, 2016), Matrix (Version 1.2.14; Bates & Maechler, 2016), papaja (Version 0.1.0.9735; Aust & Barth, 2016), reshape2 (Version 1.4.3; Wickham, 2007), rmarkdown (Version 1.9.15; Allaire et al., 2017), shiny (Version 1.1.0; Chang et al., 2016), and wordcountaddin (Version 0.2.0; 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).

my_citations <- cite_r(
  file = "r-references.bib"
  , pkgs = c("afex", "lsmeans", "papaja")
  , withhold = FALSE
)

R (Version 3.4.4; R Core Team, 2016) and the R-packages afex (Version 0.20.1; Singmann et al., 2016), lsmeans (Version 2.27.61; Lenth, 2016), and papaja (Version 0.1.0.9735; Aust & Barth, 2016)

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

my_citations <- cite_r(file = "r-references.bib", footnote = TRUE)

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.4.4; 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.

3.5 Appendices

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

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

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

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.20.1; Singmann et al., 2016), bindrcpp (Version 0.2; Müller, 2017), car (Version 2.1.6; Fox & Weisberg, 2011), citr (Version 0.2.0.9055; Aust, 2016), DiagrammeR (Version 0.9.2; Sveidqvist et al., 2016), dplyr (Version 0.7.4; Wickham & Francois, 2016), estimability (Version 1.3; Lenth, 2015), ez (Version 4.4.0; Lawrence, 2016), knitr (Version 1.20; Xie, 2015), lme4 (Version 1.1.15; Bates et al., 2015), lsmeans (Version 2.27.61; Lenth, 2016), Matrix (Version 1.2.14; Bates & Maechler, 2016), papaja (Version 0.1.0.9735; Aust & Barth, 2016), reshape2 (Version 1.4.3; Wickham, 2007), rmarkdown (Version 1.9.15; Allaire et al., 2017), shiny (Version 1.1.0; Chang et al., 2016), and wordcountaddin (Version 0.2.0; Marwick, n.d.).

Comments and Questions


Icons by Icons8
https://crsh.github.io/papaja_man/writing.html
crsh.github.io
crawl=CC-MAIN-2018-30
42963
application/http; msgtype=response
sha1:466RZNDNKBA2ZASTK3SF5XUFCNQL6CHZ
<urn:uuid:ae5ff73e-1048-4113-9433-15e5f1f735f8>
2018-07-20T06:52:23Z
185.199.109.153
text/html
sha1:2DRCK75OFXP64WTBAKENPY5PLRP7EYCZ
<urn:uuid:b86b42a4-8f99-411b-8dda-a2df9d66ec00>
https://crsh.github.io/papaja_man/writing.html
response
<urn:uuid:5a15ca35-9633-48b4-8b8c-ec1340cb0426>
robots: classic
hostname: ip-10-143-24-180.ec2.internal
software: Nutch 1.6 (CC)
isPartOf: CC-MAIN-2018-30
operator: Common Crawl Admin
description: Wide crawl of the web for July 2018
publisher: Common Crawl
format: WARC File Format 1.0
conformsTo: http://bibnum.bnf.fr/WARC/WARC_ISO_28500_version1_latestdraft.pdf