Skip to content
This repository
branch: master
Fetching contributors…

Cannot retrieve contributors at this time

file 110 lines (80 sloc) 10.193 kb

Build Status

knitcitations

knitcitations is an R package designed to add dynamic citations to dynamic documents created with Yihui's knitr package.

Installation

Install the development version directly from Github

library(devtools)
install_github("knitcitations", "cboettig")

Or install the current release from your CRAN mirror with install.packages("knitcitations").

Quick start: rmarkdown (pandoc) mode

Start by loading the library. It is usually good to also clear the bibliographic environment after loading the library, in case any citations are already stored there:

library("knitcitations")
cleanbib()

Cite by DOI

Cite an article by DOI and the full citation information is gathered automatically. By default this now generates a citation in pandoc-flavored-markdown format. We use the inline command citep("10.1890/11-0011.1") to create this citation (Abrams et al. 2012).

An in-text citation is generated with citet, such as citet("10.1098/rspb.2013.1372") creating the citation to Boettiger and Hastings (2013).

Cite by URL

Not all the literature we may wish to cite includes DOIs, such as arXiv preprints, Wikipedia pages, or other academic blogs. Even when a DOI is present it is not always trivial to locate. With version 0.4-0, knitcitations can produce citations given any URL using the Greycite API. For instance, we can use the call citep("http://knowledgeblog.org/greycite") to generate the citation to the Greycite tool (Lord 2012).

Cite bibtex and bibentry objects directly

We can also use bibentry objects such as R provides for citing packages (using R's citation() function): citep(citation("knitr") produces (Xie 2013a, 2013b, 2014). Note that this package includes citations to three objects, and pandoc correctly avoids duplicating the author names. In pandoc mode, we can still use traditional pandoc-markdown citations like @Boettiger2013 which will render as Boettiger and Hastings (2013) without any R code, provided the citation is already in the .bib file we name (see below).

Re-using Keys

When the citation is called, a key in the format FirstAuthorsLastNameYear is automatically created for this citation, so we can now continue to cite this article without remembering the DOI, using the command citep("Abrams2012") creates the citation (Abrams et al. 2012) without mistaking it for a new article.

Displaying the final bibliography

At the end of the document, include a chunk containing the command:

write.bibtex(file="references.bib")

Use the chunk option echo=FALSE to hide the chunk command. This creates a Bibtex file with the name given. Pandoc can then be used to compile the markdown into HTML, MS Word, LaTeX, PDF, or many other formats, each with the desired journal styling. Pandoc is now integrated with RStudio through the rmarkdown package. Pandoc appends these references to the end of the markdown document automatically. In this example, we have added a yaml header to our Rmd file which indicates the name of the bib file being used:

---
output: 
  html_document:
    pandoc_args: [
      "--biblio", "references.bib",
      "--csl", "ecology.csl"
      ]
---

Then calling rmarkdown::render("tutorial.Rmd") from R on the tutorial compiles the output markdown, with references in the format of the ESA journals.

References

Abrams, P. A., L. Ruokolainen, B. J. Shuter, and K. S. McCann. 2012. Harvesting creates ecological traps: consequences of invisible mortality risks in predator–prey metacommunities. Ecology 93:281–293.

Boettiger, C., and A. Hastings. 2013. no early warning signals for stochastic transitions: insights from large deviation theory. Proceedings of The Royal Society B: Biological Sciences 280:20131372–20131372.

Lord, P. 2012. Greycite. http://knowledgeblog.org/greycite.

Xie, Y. 2013a. knitr: a general-purpose package for dynamic report generation in r.

Xie, Y. 2013b. Dynamic documents with R and knitr. Chapman; Hall/CRCBoca Raton, Florida.

Xie, Y. 2014. knitr: a comprehensive tool for reproducible research in R. in V. Stodden, F. Leisch, and R. D. Peng, editors. Implementing reproducible computational research. Chapman; Hall/CRC.

Something went wrong with that request. Please try again.