Easy citations in RMarkdown with RefManageR

It’s Monday (or at least it was when I started writing this), so what better way to make the week’s most boring day even more boring than to write about citations? Managing and formatting references for your research is, well, about as fun as it sounds. Fortunately, gone are the days of manually curating these lists and cut/pasting your way to an alphabetical bibliography. In this post, I’ll demonstrate how to use the RefManageR package to manage your references and easily automate citations and bibliographies in RMarkdown documents.

Using A Reference Manager

Zotero, EndNote, and Mendeley are all excellent reference managers, each with their own variety of browser plug-ins and desktop apps that make saving, searching, and inserting references slightly more enjoyable. I personally use Zotero. I have the Safari plug in that makes it easy to save references directly to my Zotero library from journal websites. The desktop app is a convenient way to browse the references and open up PDFs when needed, and it will also retrieve the metadata for a PDF you add to it, removing the need to enter that info yourself (author, year, journal, etc.).

All reference manager platforms should allow you to export your bibliography as a variety of file types, which can subsequently be used by RMarkdown (and LaTeX and most word processors) to insert citations and a bibliography in a consistent format. I’ll be talking about .bib files, which is a style-independent text-based file format (essentially just a formatted list of your references), but the same process should work for other file types.

Using .bib files has numerous advantages:

  • Easily switch between citation formats
  • Create and update bibliographies automatically
  • Compatible across platforms
  • Easy to share with coauthors

All of these benefits can take a bit of the sting out of adjusting your paper’s citations to the next journal as those rejection letters pile up. Using .bib files in RMarkdown documents is really straight forward. Simply save the .bib file in your directory of choice and then point to it in the front matter of your RMarkdown document:

---
title: "Crazy awesome paper that's definitely getting accepted"
output: html_document
bibliography: bibliography.bib
---

Citations in RMarkdown

We’re now ready to start inserting citations in our RMarkdown document by placing the reference id within square brackets and using the @ symbol, e.g, [@costello16]. Check out the RMarkdown documentation for more information on inserting citations using .bib (or other) bibliography files.

Citations with RefManageR and Zotero

A disadvantage to using physical .bib files is the need to update the .bib file when you want to include new references. Fortunately, the RefManageR package makes it easy for us to cut out the middle man. I’ll demonstrate how to use RefManageR to interface with Zotero directly to access our reference list.

First, we’ll load the tidyverse and RefManageR packages.

# Packages
library(tidyverse)
library(RefManageR)

Next, we need two pieces of information, the first of which is a Zotero user id. Your Zotero user id can be found by logging in and navigating to Settings > Feeds / API.

The second required piece of information is a collection id. Collections are another great thing about Zotero, allowing you to easily organize your references for each paper. They appear as sub-folders that you simply drag references to from My Library (Zotero will not keep a copy in My Library).

For this example, we’ll link to my collection of articles about interactions between aquaculture (fish farming) and wild fisheries. The collection id is just the last character set after collectionKey/ at the end of the collection’s URL.

With the user id and collection id, we can connect to Zotero directly to get our reference information using the ReadZotero() function.

biblio <- ReadZotero(user = <user_id>, .params = list(collection = '<collection_id>'))

ReadZotero() will return a list of references, which I’ve called biblio here. At this point, we can start directly inserting citations in our RMarkdown document using Cite() and providing the index for the reference in biblio we want to cite. For example, Cite(biblio[[1]]) will insert a citation for the first reference in our reference list - (Sugimoto, San Diego-McGlone, Paciencia, Milan, Tomas, Ramírez, Echavez, Gabatin, Fortes, and Nadaoka, 2016).

ReadZotero() names each list index using an informative key string and we can make a look-up data frame with the reference titles and list element names to make indexing easier.

# Find article keys to reference when in citations
refs <- biblio %>% {
  .$title
} %>%
  bind_rows() %>%
  gather(key = 'key', value = 'title', 1:19)

Now, each time we need to insert a citation we just look up its key in our refs data frame and use it with Cite(biblio['reference_key']).

Examples

China, Indonesia, India, Chile, Vietnam, and Myanmar are top-10 producers for both capture fisheries and aquaculture (FAO, 2016).

Aquaculture regulations in numerous regions tend to be reactive, with many newcomers (e.g. Myanmar and Vietnam) promoting economic development at the expense of more restrictive policies like those imposed by incumbents, such as Thailand and the Philippines (Hishamunda, Ridler, Bueno, and Yap, 2009).

In the absence of effective regulations, producers may adopt unsustainable practices that maximize their short-term profits but cause negative environmental and social damage that they are not held accountable for (Subasinghe, Soto, and Jia, 2009).

Finally, when we’re all done writing, inserting a bibliography at the end of our paper is just one line of code using the PrintBibliography(biblio) function embedded in a code chunk. Be sure to set the code chunk option results = 'asis'.

References

[1] FAO, ed. Contributing to food security and nutrition for all. Eng. The state of world fisheries and aquaculture 2016. OCLC: 957090850. Rome: Food and Agriculture Organization of the United Nations, 2016. ISBN: 978-92-5-109185-2.

[2] N. Hishamunda, N. B. Ridler, P. Bueno, et al. “Commercial aquaculture in Southeast Asia: Some policy lessons”. In: Food Policy. Collective Action for Smallholder Market Access 34.1 (Feb. 2009), pp. 102-107. ISSN: 0306-9192. DOI: 10.1016/j.foodpol.2008.06.006. <URL: http://www.sciencedirect.com/science/article/pii/S0306919208000584> (visited on 09/16/2016).

[3] R. Subasinghe, D. Soto and J. Jia. “Global aquaculture and its role in sustainable development”. En. In: Reviews in Aquaculture 1.1 (Mar. 2009), pp. 2-9. ISSN: 1753-5131. DOI: 10.1111/j.1753-5131.2008.01002.x. <URL: http://onlinelibrary.wiley.com/doi/10.1111/j.1753-5131.2008.01002.x/abstract> (visited on 09/16/2016).

[4] A. Sugimoto, M. L. San Diego-McGlone, F. Paciencia, et al. “Comanagement for aquaculture: Suggestions from a comparative study between two major production areas of milkfish in the Philippines”. In: Journal of Applied Aquaculture 28.4 (Oct. 2016), pp. 298-313. ISSN: 1045-4438. DOI: 10.1080/10454438.2016.1209712. <URL: http://www-tandfonline-com.proxy.library.ucsb.edu:2048/doi/full/10.1080/10454438.2016.1209712> (visited on 02/15/2017).

That’s it, we’re all setup and ready to start writing and citing our way to publication glory!

comments powered by Disqus