3 Citations and cross-references

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.³ 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 (Shea et al. 2014; Lottridge et al. 2012).

3.1.1 PDF output

In PDF output, the bibliography is handled by the OxThesis LaTeX template. If you set bib-humanities: true in index.Rmd, then in-text references will be formatted as author-year; otherwise references will be shown as numbers.

If you choose author-year formatting, 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
- This: [see @Shea2014, pp. 33-35; also @Wu2016, ch. 1]
- Becomes: Blah blah (see Shea et al. 2014, 33–35; also Wu 2016, ch. 1).

3.1.2 Gitbook output

In gitbook output, citations are by default inserted in the Chicago author-date format.

To change the format, add csl: some-other-style.csl in index.Rmd’s YAML header. You can browse through and download styles at zotero.org/styles.

3.1.3 Insert references easily with the `citr` add-in

For an easy way to insert citations, try the citr RStudio add-in (Figure 3.1). You can install this add-in by typing install.packages("citr") in the R Console.

Figure 3.1: The citr add-in

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/captain.jpeg")

Figure 3.2: A marvel-lous meme

We refer to this image with \@ref(fig:captain). So Figure 3.2 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 Customising your thesis’ front matter ’n stuff

3.3.1 Shorten captions shown in the list of figures (PDF)

You might want your list of figures (which follows the table of contents) to have shorter (or just different) figure descriptions than the actual figure captions.

Do this using the chunk option fig.scap (‘short caption’), for example {r captain-image, fig.cap="A very long and descriptive (and potentially boring) caption that doesn't fit in the list of figures, but helps the reader understand what the figure communicates.", fig.scap="A concise description for the list of figures"

3.3.2 Shorten captions shown in the list of tables (PDF)

You might want your list of tables (which follows the list of figures in your thesis front matter) to have shorter (or just different) table descriptions than the actual table captions.

If you are using knitr::kable to generate a table, you can do this with the argument caption.short, e.g.:

knitr::kable(mtcars,
              caption = "A very long and descriptive (and potentially
              boring) caption that doesn't fit in the list of figures,
              but helps the reader understand what the figure 
              communicates.",
              caption.short = "A concise description for the list of tables")

3.3.3 Shorting the running header (PDF)

You might want a chapter’s running header (i.e. the header showing the title of the current chapter at the top of page) to be shorter (or just different) to the actual chapter title.

Do this by adding the latex command \chaptermark{My shorter version} after your chapter title.

For example, this chapter’s running header is simply ‘Cites and cross-refs,’ because it begins like this:

# Citations and cross-references {#cites-and-refs}
\chaptermark{Cites and cross-refs}

2 Adding code

4 Tables