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 be added to each citation by adding them inside the brackets ([e.g., @bem_2011]). Note that prefixes divide a set of citations into subgroups; automatic (alphabetical) sorting of citations is done only within each subgroup. For example, there are three subgroups of citations in Disagreements abound [@Xylax2016; see also @Yi2014; @Ang2017; for a contrary view, see @Mutt2012]:

  1. @Xylax2016
  2. @Yi2014; @Ang2017 (will be printed in reverse order)
  3. @Mutt2012

Conveniently, the citations in subgroup 2 will be reordered but the order of the prefixed subgroups is preserved:

Disagreements abound (Xylax, 2016; see also Ang, 2017; Yi, 2014; for a contrary view, see Mutt, 2012)

This ensures that the reordering citations doesn’t distort the semantics implied by the prefixes.

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.

---
csl: mystyle.csl
---

3.2.2 Works ‘in press’

Bibliographic entries that are missing the year field will be rendered without a date. For example, the following entry in the bibliography file will be printed as Aust & Barth (n.d.).

@article{R-papaja,
  author = {Frederik Aust and Marius Barth},
  title = {{papaja}: {Create} {APA} manuscripts with {R Markdown}}
}

When refering to works that are missing a date because they are not yet published (e.g., works that are under review or accepted for but awaiting publication), the publication state can be included in the citation and reference via the pubstate field:

@article{R-papaja,
  author = {Frederik Aust and Marius Barth},
  title = {{papaja}: {Create} {APA} manuscripts with {R Markdown}},
  pubstate = {in press}
}

Now, this entry will be printed as Aust & Barth (in press).

3.2.3 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.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 BibTeX 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 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.

papaja provides an APA CSL file that enables adding annotations to the bibliography. To use this variant insert the following into YAML front matter.

annotate_references: yes

Any references that has an annote field will be preceded by the contents of that field, e.g. *.

@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},
  annote = {*}
}

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

nocite: @aust_memory-based_2018

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.

\begingroup
\setlength{\parindent}{-0.5in}
\setlength{\leftskip}{0.5in}

References marked with an asterisk indicate studies included in the meta-analysis.

<div id = "refs"></div>

\endgroup

If you prefer \(\LaTeX\) to render the bibliographic information, you can add the following to the YAML front matter:

biblio-style      : "apa"

output:
  papaja::apa6_pdf:
    citation_package: biblatex

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

header-includes:
  - \DeclareLanguageMapping{english}{english-apa}
  - \DeclareBibliographyCategory{asterisk}
  - \renewbibmacro*{begentry}{\ifcategory{asterisk}{\ensuremath{\ast}}{}}
  - \newcommand*{\nocitemeta}[1]{\nocite{#1}\addtocategory{asterisk}{#1}}

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

\nocitemeta{aust_memory-based_2018}

No entry in the annote 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.

\defbibnote{asterisk}{References marked with an asterisk indicate studies included in the meta-analysis.}
\printbibliography[title=References,prenote=asterisk]
\renewcommand{\printbibliography}{}

3.2.5 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(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 4.0.3; R Core Team, 2016) and the R-packages afex (Version 0.27.2; Singmann, Bolker, Westfall, & Aust, 2016), bindrcpp (Müller, 2017), car (Version 3.0.8; Fox & Weisberg, 2011; Fox, Weisberg, & Price, 2018), carData (Version 3.0.4; Fox, Weisberg, & Price, 2018), citr (Version 0.3.2; Aust, 2016), DiagrammeR (Version 1.0.6.1; Sveidqvist et al., 2016), dplyr (Version 1.0.1; Wickham & Francois, 2016), estimability (Version 1.3; Lenth, 2015), ez (Lawrence, 2016), ggplot2 (Version 3.3.3; Wickham, 2009), knitr (Version 1.30; Xie, 2015), lme4 (Version 1.1.23; Bates, Mächler, Bolker, & Walker, 2015), lsmeans (Version 2.30.0; Lenth, 2016), Matrix (Version 1.2.18; Bates & Maechler, 2016), papaja (Version 0.1.0.9997; Aust & Barth, 2016), reshape2 (Version 1.4.4; Wickham, 2007), rmarkdown (Version 2.6.6; Allaire et al., 2017), shiny (Version 1.5.0; Chang, Cheng, Allaire, Xie, & McPherson, 2016), tinylabels (Version 0.1.0; Barth, 2021), 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).

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

R (Version 4.0.3; R Core Team, 2016) and the R-packages afex (Version 0.27.2; Singmann, Bolker, Westfall, & Aust, 2016), lsmeans (Version 2.30.0; Lenth, 2016), and papaja (Version 0.1.0.9997; 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 4.0.3; 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)

  • Chunk labels must not contain underscores (_) for this to work.
  • Precede by non-breaking spaces, e.g.
    Figure\ \@ref(fig:chunk-label)
  • If you want to reference sections (i.e., “in Section 1, we describe in more detail…”), make sure that your sections are actually numbered by setting numbersections: yes in the document’s yaml header.

3.5 Appendices

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

  • One level-1 heading
  • No YAML front matter
---
appendix: "appendix.Rmd"
---

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

Multiple appendices are possible

---
appendix:
  - "appendix_a.Rmd"
  - "appendix_b.Rmd"
---

3.6 Counting words

To get an accurate word count papaja uses the Lua word count filter in rmdfiltr, which yields counts that are comparable to other methods. Words are counted separately for the body of the text (excluding captions) and the reference section. Every time the document is knitted the current word count is printed to the R Markdown pane in RStudio or the console:

5138 words in text body
624 words in reference section

3.7 Comparing document versions

In revisions, it can be helpful to highlight all changes.

  • for DOCX, use the Microsoft Word combine feature
  • for PDF, use latexdiff on \(\LaTeX\) source documents
    1. Create \(\LaTeX\) file with highlighted changes
    2. Compile to PDF in RStudio

Notes on PDF method:

The .tex files are generated when you knit your .rmd document. Make sure you save the .tex file from before you make any modifications.

You can now visit latexdiff and copy/paste in the contents of manuscript_old.tex and manuscript_new.tex, or (if you are a command line ninja install latexdiff on your own system). This will generate output which you can copy/paste into a file manuscript_with_changes.tex.

Now open this file manuscript_with_changes.tex in RStudio and click “Compile to PDF” in the top bar.

N.B. Will not track changes in the front matter (affiliations, abstract)

  1. We, furthermore, used the R-packages afex (Version 0.27.2; Singmann, Bolker, Westfall, & Aust, 2016), bindrcpp (Müller, 2017), car (Version 3.0.8; Fox & Weisberg, 2011; Fox, Weisberg, & Price, 2018), carData (Version 3.0.4; Fox, Weisberg, & Price, 2018), citr (Version 0.3.2; Aust, 2016), DiagrammeR (Version 1.0.6.1; Sveidqvist et al., 2016), dplyr (Version 1.0.1; Wickham & Francois, 2016), estimability (Version 1.3; Lenth, 2015), ez (Lawrence, 2016), ggplot2 (Version 3.3.3; Wickham, 2009), knitr (Version 1.30; Xie, 2015), lme4 (Version 1.1.23; Bates, Mächler, Bolker, & Walker, 2015), lsmeans (Version 2.30.0; Lenth, 2016), Matrix (Version 1.2.18; Bates & Maechler, 2016), papaja (Version 0.1.0.9997; Aust & Barth, 2016), reshape2 (Version 1.4.4; Wickham, 2007), rmarkdown (Version 2.6.6; Allaire et al., 2017), shiny (Version 1.5.0; Chang, Cheng, Allaire, Xie, & McPherson, 2016), tinylabels (Version 0.1.0; Barth, 2021), and wordcountaddin (Marwick, n.d.).↩︎

Comments and Questions


Icons by Icons8