Skip to main content

oxforddown:
An Oxford University Thesis
Template for R Markdown

3 Citations, cross-references, and collaboration

3.1 Citations

The usual way to include citations in an R Markdown document is to put references in a plain text file with the extension .bib, in BibTex format.3 Then reference the path to this file in index.Rmd’s YAML header with bibliography: example.bib.

Most reference managers can create a .bib file with you references automatically. However, the by far best reference manager to use with R Markdown is Zotero with the Better BibTex plug-in, because the citr plugin for RStudio (see below) can read references directly from your Zotero library!

Here is an example of an entry in a .bib file:

@article{Shea2014,
  author =        {Shea, Nicholas and Boldt, Annika},
  journal =       {Trends in Cognitive Sciences},
  pages =         {186--193},
  title =         {{Supra-personal cognitive control}},
  volume =        {18},
  year =          {2014},
  doi =           {10.1016/j.tics.2014.01.006},
}

In this entry highlighed section, ‘Shea2014’ is the citation identifier. To default way to cite an entry in your text is with this syntax: [@citation-identifier].

So I might cite some things (Lottridge et al., 2012; Mill, 1965 [1843]; Shea et al., 2014).

3.1.1 Appearance of citations and references section (pandoc)

By default, oxforddown lets Pandoc handle how citations are inserted in your text and the references section. You can change the appearance of citations and references by specifying a CSL (Citation Style Language) file in the csl metadata field of index.Rmd. By default, oxforddown by the Americal Psychological Association (7th Edition), which is an author-year format.

With this style, a number of variations on the citation syntax are useful to know:

  • Put author names outside the parenthesis
    • This: @Shea2014 says blah.
    • Becomes: Shea et al. (2014) says blah.
  • Include only the citation-year (in parenthesis)
    • This: Shea et al. says blah [-@Shea2014]
    • Becomes: Shea et al. says blah (2014)
  • Add text and page or chapter references to the citation

If you want a numerical citation style instead, try csl: bibliography/transactions-on-computer-human-interaction.csl or just have a browse through the Zotero Style Repository and look for one you like. For convenience, you can set the line spacing and the space between the bibliographic entries in the reference section directly from the YAML header in index.Rmd.

If you prefer to use biblatex or natbib to handle references, see this chapter.

3.1.2 Insert references easily with RStudio’s Visual Editor

For an easy way to insert citations, use RStudio’s Visual Editor. Make sure you have the latest version of RStudio – the visual editor was originally really buggy, especially in relation to references, but as per v2022.02.0, it’s great!

3.2 Cross-referencing

We can make cross-references to sections within our document, as well as to figures (images and plots) and tables.

The general cross-referencing syntax is \@ref(label)

3.2.1 Section references

Headers are automatically assigned a reference label, which is the text in lower caps separated by dashes. For example, # My header is automatically given the label my-header. So # My header can be referenced with \@ref(my-section)

Remember what we wrote in section 3.1?

We can also use hyperlink syntax and add # before the label, though this is only guaranteed to work properly in HTML output:

  • So if we write Remember what we wrote up in [the previous section](#citations)?
  • It becomes Remember what we wrote up in the previous section?

3.2.1.1 Creating custom labels

It is a very good idea to create custom labels for our sections. This is because the automatically assigned labels will change when we change the titles of the sections - to avoid this, we can create the labels ourselves and leave them untouched if we change the section titles.

We create custom labels by adding {#label} after a header, e.g. # My section {#my-label}. See our chapter title for an example. That was section 3.

3.2.2 Figure (image and plot) references

  • To refer to figures (i.e. images and plots) use the syntax \@ref(fig:label)
  • GOTCHA: Figures and tables must have captions if you wish to cross-reference them.

Let’s add an image:

knitr::include_graphics("figures/sample-content/captain.jpeg")
A marvel-lous meme

Figure 3.1: A marvel-lous meme

We refer to this image with \@ref(fig:captain). So Figure 3.1 is this image.

And in Figure 2.4 we saw a cars plot.

3.2.3 Table references

  • To refer to tables use the syntax \@ref(tab:label)

Let’s include a table:

knitr::kable(cars[1:5,],
            caption="Stopping cars")
Table 3.1: Stopping cars
speed dist
4 2
4 10
7 4
7 22
8 16

We refer to this table with \@ref(tab:cars-table2). So Table 3.1 is this table.

And in Table 2.1 we saw more or less the same cars table.

3.2.4 Including page numbers

Finally, in the PDF output we might also want to include the page number of a reference, so that it’s easy to find in physical printed output. LaTeX has a command for this, which looks like this: \pageref{fig/tab:label} (note: curly braces, not parentheses)

When we output to PDF, we can use raw LaTeX directly in our .Rmd files. So if we wanted to include the page of the cars plot we could write:

  • This: Figure \@ref(fig:cars-plot) on page \pageref(fig:cars-plot)
  • Becomes: Figure 2.4 on page

3.2.4.1 Include page numbers only in PDF output

A problem here is that LaTeX commands don’t display in HTML output, so in the gitbook output we’d see simply “Figure 2.4 on page”.

One way to get around this is to use inline R code to insert the text, and use an ifelse statement to check the output format and then insert the appropriate text.

  • So this: `r ifelse(knitr::is_latex_output(), "Figure \\@ref(fig:cars-plot) on page \\pageref{fig:cars-plot}", "")`
  • Inserts this (check this on both PDF and gitbook):

Note that we need to escape the backslash with another backslash here to get the correct output.

3.3 Collaborative writing

Best practices for collaboration and change tracking when using R Markdown are still an open question. In the blog post One year to dissertate by Lucy D’Agostino, which I highly recommend, the author notes that she knits .Rmd files to a word document, then uses the googledrive R package to send this to Google Drive for comments / revisions from co-authors, then incorporates Google Drive suggestions by hand into the .Rmd source files. This is a bit clunky, and there are ongoing discussions among the R Markdown developers about what the best way is to handle collaborative writing (see issue #1463 on GitHub, where CriticMarkup is among the suggestions).

For now, this is an open question in the community of R Markdown users. I often knit to a format that can easily be imported to Google Docs for comments, then go over suggested revisions and manually incorporate them back in to the .Rmd source files. For articles, I sometimes upload a near-final draft to Overleaf, then collaboratively make final edits to the LaTeX file there. I suspect some great solution will be developed in the not-to-distant future, probably by the RStudio team.

3.4 Additional resources