5 Tips and Tricks

  • Spell check functionality in RStudio

Although often overlooked, RStudio can check your spelling

  • New line for each sentence

5.1 Global chunk options

It can be useful to set chunk options globally for all (following) chunks to avoid retyping or copy-and-pasting

# Save all plots as 600 DPI TIFF-files
knitr::opts_chunk$set(dev = "tiff", dpi = 600)

# Do not evaluate subsequent chunks (debugging or fine-tuning)
knitr::opts_chunk$set(eval = FALSE)

See the knitr chunk options and package options for an overview of settings

5.2 Meaningful chunk names

5.3 Useful RStudio Addins

  • citr: Insert Markdown Citations
  • remedy: Keyboard shortcuts for Markdown formatting
  • splitChunk: Split R Markdown code chunks
  • gramr: Write-good linter
  • wordcount: Word counts and readability statistics

Set up keyboard shortcuts via
Tools > Modify keyboard shortcuts

Suggested keyboard shortcuts

Package Addin Keyboard shortcut
citr Insert citation Shift + Alt+R
wordcount Word count Shift + Alt+C
splitChunk Chunk split Shift + Alt+S
remedy Bold Shift + Alt+B
Italic Shift + Alt+I
Backtick Shift + Alt+P
URL Shift + Alt+U
  • statcheck: Extract Statistics from Articles and Recompute p Values
  • retractcheck: Check DOIs in a paper for retractions

5.4 Author name disambiguation

As per APA style, citations in papaja documents will be disambiguated if the bibliography file contains multiple authors with the same family but different given names. This can be a nuisance if the bibliographic information is not maintained meticulously. Entries such as author = {John Doe} and author = {J. Doe} are taken to be different authors and will be disambiguated (i.e. “John Doe (1986)” and “J. Doe (1986)”).

Disabling author name disambiguation is possible (although it is somewhat beyond the scope of papaja). The definition of the citation style used in papaja is given in a citation style language file (CSL, see [Additional-rendering-options]). We have created a variant of the widely available APA CSL file without author name disambiguation. To use this variant insert the following into YAML front matter:

csl: https://tinyurl.com/apa6-no-disambiguation

Alternatively, you can download the file and use the location on your hard drive instead of the above URL. Note that using this style can create the false impression that two works are authored by the same author when really they were not. For example, author = {John Doe} and author = {Jane Doe} will be displayed as “Doe (1986a)” and “Doe (1986b)”.

If you prefer \(\LaTeX\) to generate the bibliographic information, we recommend the following approach to disable author name disambiguation:

lang              : "en-EN" # Optional, added for clarity

biblio-style      : "apa"
biblatexoptions   : "uniquename=false"
header-includes:
  - \DeclareLanguageMapping{english}{english-apa}

output:
  papaja::apa6_pdf:
    citation_package: biblatex

Specifying lang is optional in this case, because en-EN is the default. pandoc converts en-EN to english and inserts it into the document preamble. Hence, english needs to be mapped to english-apa. Similarly, if you want, say, British english you would have to adapt the above as follows:

lang              : "en-GB" # Required
header-includes:
  - \DeclareLanguageMapping{british}{british-apa}

A general drawback to this approach is that biblatex does not operate on any text in the YAML front matter. This can be a problem when, for example, the abstract contains citations. This problem can be addressed with the text references feature in bookdown. Replace the text of the abstract in the YAML front matter by

abstract: (ref:abstract)

(ref:abstract) is a placeholder for text that you can now define in the body of the R Markdown document (e.g., right after the YAML front matter):

(ref:abstract)
This is the abstract [@doe1986].

This text will now be processed and citations will be generated as expected.

5.5 Reproducible software environment

  • sessionInfo()
  • packrat
  • checkpoint
  • liftr & docker

5.6 RStudio

  1. Document outline

RStudio provides a handy document outline view

5.7 Splitting an R Markdown document

Some authors may prefer to split long manuscripts into multiple component files for better clarity. There are two basic strategies to split R Markdown documents that can be combined or used in isolation: sourcing R scripts and splitting the R Markdown document. If the R Markdown document contains a lot of code, it may be helpful to disincorporate parts of the code, such as reading, merging, restructuring, and relabeling data files. The R scripts can then be executed at the respective section of the document using source().

Some authors may prefer to split long manuscripts into a master or parent document and multiple children. The master document, for example, consists of the YAML front matter and includes the children, which are themselves R Markdown documents without a YAML front matter. To include a child document, insert an empty chunk and provide the path to the R Markdown document in the chunk option child.

It may be preferable to split long documents into multiple files

```{r child = “introduction.Rmd”}
```

```{r child = “method.Rmd”}
```

```{r child = “results.Rmd”}
```

```{r child = “discussion.Rmd”}
```

Search all files with Ctrl + Shift+F

5.8 Workflow

  • Don’t edit raw data
  • Don’t set a working directory
  • Generate graphics from R code
  • Don’t edit word documents
  • Relative paths

5.9 Adjusting line spacing

According to the APA guidelines, “Tables may be submitted either single- or double-spaced.” (p. 141; American Psychological Association, 2010). Adjusting the line spacing of table contents is currently not supported in papaja. However, as usual it is possible to adjust the spacing in PDF documents by including additional \(\LaTeX\) code. If you use apa_able(), including the following in the YAML front matter will result in single-spaced tables with double-spaced caption and table note:

header-includes:
  - \usepackage{setspace}
  - \AtBeginEnvironment{tabular}{\singlespacing}
  - \AtBeginEnvironment{lltable}{\singlespacing}
  - \AtBeginEnvironment{tablenotes}{\doublespacing}
  - \captionsetup[table]{font={stretch=1.5}}
  - \captionsetup[figure]{font={stretch=1.5}}

Similarly, the line spacing of figure captions can be adjusted as follows:

header-includes:
  - \usepackage{setspace}
  - \AtBeginEnvironment{tabular}{\doublespacing}
  - \AtBeginEnvironment{lltable}{\doublespacing}
  - \AtBeginEnvironment{tablenotes}{\doublespacing}
  - \captionsetup[table]{font={stretch=1.5}}
  - \captionsetup[figure]{font={stretch=1}}

5.9.1 Comparing documents

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

5.9.2 Counting words

  1. wordcount
    • RStudio addin counts words in R Markdown documents
    • Rough estimate; cannot, for example, count rendered citations
    • Good for quick use
  2. texcount
    • Counts words in TeX documents
    • More precise and informative
  3. Microsoft Word word count

If you are using pandoc-citeproc for references, exclude the reference section before counting words

5.10 Best practices

  1. Load all R packages in the first code chunk
    • Never include install.packages()
  2. Set a seed for random number generators
    (e.g., set.seed())
  3. Never use setwd()!
  4. Use relative paths or load files from a permanent location
  5. Use meaningful chunk names
  6. Keep R code close to the corresponding prose
  7. Document R and R-package versions
    (e.g., devtools::session_info())
  8. Make sure you can knit without errors before going home

5.11 Troubleshooting

5.11.1 R

Fixing bugs in R Markdown documents can be challenging

  • The code is run in a new non-interactive R session
  • Try is to recreate the problem in your interactive session
    1. Restart R (Session > Restart R or
      Ctrl + Shift + F10)
    2. Run all chunks (Ctrl + Alt + R)
    3. Compare the working directories (e.g., use getwd() in a code chunk)

References

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

Comments and Questions


Icons by Icons8