Writing and Citing in RStudio
For this example I am using a new R Markdown file, created using the RStudio template as demonstrated previously, but with everything deleted except the YAML header. I have titled the document “Our Friend the Catbird” and have also deleted the YAML author and date fields to keep things simple. I have named the file citations.Rmd, but any file name will do as long as you use the .Rmd filename extension.
Thus the YAML header currently looks like this:
---
title: "Our Friend the Catbird"
output: html_document
---In RStudio, inserting literature citations and creating formatted bibliographies in R Markdown documents is facilitated by an R package called citr. To install it, go to the Packages tab in RStudio, click the Install button, enter citr into the search bar, be sure that Install dependencies is checked, and then click Install:
If you then click the Addins button on the main RStudio toolbar, you should see an entry for Insert citations:
If you don’t see Insert citations, be sure that citr is checked in the list of installed packages in the Packages tab. You might have to restart RStudio after checking citr in the package list.
Before we can use citr, we need a BibTeX bibliography file.
Here’s one: references.bib.
To follow along with this example, click the above link and download references.bib to your RStudio working directory, or some other location where you can find it.
BibTeX files are plain text and can be created by the major reference manager applications, such as RefWorks, EndNote, Mendeley, and Zotero. Many other reference manager applications, e.g. JabRef, use BibTeX as their native format; see Comparison of reference management software. The BibTeX format is widely used and has been around for a long time.
A BibTeX reference entry looks like this:
@article{marsh_adaptations_1984,
title = {Adaptations of the {{Gray Catbird}} to Long Distance Migration: Flight Muscle Hypertrophy Associated with Elevated Body Mass},
volume = {57},
timestamp = {2016-03-12T15:29:37Z},
number = {1},
journaltitle = {Physiological Zoology},
author = {Marsh, R. L.},
date = {1984},
pages = {105--117}
}All reference manager applications break bibliographic citations into a series of fields that can be reassembled into any citation style desired, such as that of the journal Ecology:
Marsh, R. L. 1984. Adaptations of the Gray Catbird to long distance migration: Flight muscle hypertrophy associated with elevated body mass. Physiological Zoology 57:105–117.The references.bib file used in this example was created by exporting references from Zotero using the BibTeX export translator.
The YAML header can contain the name of a BibTeX file to use for literature citations. Thus we add bibliography: references.bib to our YAML header so that it now looks something like this:
---
title: "Our Friend the Catbird"
output: html_document
bibliography: references.bib
---This assumes that references.bib is in the same folder as the R Markdown file. But you could also store references.bib in some other location, as long as you provide the complete path to the file, for example:
bibliography: /User/rlent/Desktop/references.bibYou can also provide multiple BibTeX files in the YAML header by listing them like this:
bibliography: [statistics.bib, graphics.bib]And so, with bibliography: references.bib added to the YAML header of citations.Rmd, and with the references.bib file residing in the same folder as citations.Rmd, click Addins, then select Insert citations. A dialog box should appear:
Note that we get an acknowledgement that references.bib was found in the YAML header. An error message will appear in the search bar if there was a problem finding the bibliography file. If you click in the search bar, where it says Search terms, you should see a scrollable list of the references contained in references.bib:
You can select one or more references from the list, by clicking on them, and the selected references will be added to a separate box above the scrollable list:
When you are finished selecting references to cite, click in a blank area of the dialog box, and citr will build a citation marker to insert into your text:
The citation marker consists of one or more BibTeX citation keys, each beginning with the @ symbol, each separated by semicolons, with everything enclosed in square brackets. The citr tool takes care of this in-text formatting automatically; all you have to do is select the references you want to cite.
Each reference in a BibTeX file contains a citation key at the beginning of the entry:
The citation key uniquely identifies each reference in the BibTeX file and is used as a place marker for in-text citations in the R Markdown file.
By default, RStudio will use a Chicago author-date format for citations and references. To use another style, you need to specify a CSL (Citation Style Language) style file in a csl metadata field in your YAML header. CSL styles are plain-text and are written in XML. You can select and download over 8300 CSL bibliographic styles from the Zotero Style Repository.
Let’s first try citing using the default style. This means that our YAML header looks like this:
---
title: "Our Friend the Catbird"
output: html_document
bibliography: references.bib
---Here the YAML header only specifies the BibTeX file, and does not specify a particular CSL style file. Therefore the default Chicago author-date style will be used.
We type some text, and leave our cursor at the point in the text where we want to insert a citation:
We then click Addins|Insert citations, and search for a reference to cite:
Be sure In parentheses is checked (this puts in the square brackets), click Insert citation, and the citation marker will be inserted into your text at the current cursor position:
The catbird is one of our most beloved songbirds [@bent_life_1948].Now, if we knit the R Markdown document to HTML, it looks like this:
RStudio, via the citr package and another application called pandoc (automatically installed with RStudio; see also Pandoc Markdown), has changed the citation marker to the appropriate in-text citation style (in this case, the default Chicago author-date style) and has created a formatted bibliography, also in the Chicago style. The bibliography is always placed at the end of the document; I had already inserted a Markdown heading (#### Literature Cited) to create a Literature Cited section.
If we want a specific bibliographic style other than the default Chicago style, we need to add a csl metadata entry to our YAML header:
---
title: "Our Friend the Catbird"
output: html_document
bibliography: references.bib
csl: nature.csl
---The csl: nature.csl YAML entry points to a CSL style file called nature.csl that was downloaded from the Zotero Style Repository. This is the style used in the journal Nature.
(Here is nature.csl if you want to download it for this example.)
Now, when we knit to HTML, we get:
The rendered HTML has been reformatted to follow the bibliographic style specified by nature.csl. In-text citations are now numbered superscripts, and the bibliography is also numbered and organized in citation order instead of alphabetically by author’s last name. (This would be more obvious if we had more than one citation.)
See Bibliographies and Citations for more information on citing and creating bibliographies in RStudio. For example, using an author-date style like Chicago, if you put a minus sign before the opening @ of a citation key in the text, like this:
[-@bent_life_1948]you can suppress the author’s name in the citation. Now we can write a sentence that reads:
Arthur Bent (1948) said that the catbird is one of our most beloved songbirds. An R Markdown Template for Academic Manuscripts provides more useful tips on YAML and R Markdown documents.