This lecture, as the rest of the course, is adapted from the version Stephanie C. Hicks designed and maintained in 2021 and 2022. Check the recent changes to this file through the GitHub history.
Pre-lecture materials
Read ahead
Read ahead
Before class, you can prepare by reading the following materials:
Know what types of bibliography file formats can be used in a R Markdown file
Learn how to add citations to a R Markdown file
Know how to change the citation style (e.g. APA, Chicago, etc)
Introduction
For almost any data analysis, especially if it is meant for publication in the academic literature, you will have to cite other people’s work and include the references (bibliographies or citations) in your work. In this class, you are likely to need to include references and cite other people’s work like in a regular research paper.
R provides nice function citation() that helps us generating citation blob for R packages that we have used. Let’s try generating citation text for rmarkdown package by using the following command
citation("rmarkdown")
To cite package 'rmarkdown' in publications use:
Allaire J, Xie Y, Dervieux C, McPherson J, Luraschi J, Ushey K,
Atkins A, Wickham H, Cheng J, Chang W, Iannone R (2023). _rmarkdown:
Dynamic Documents for R_. R package version 2.24,
<https://github.com/rstudio/rmarkdown>.
Xie Y, Allaire J, Grolemund G (2018). _R Markdown: The Definitive
Guide_. Chapman and Hall/CRC, Boca Raton, Florida. ISBN
9781138359338, <https://bookdown.org/yihui/rmarkdown>.
Xie Y, Dervieux C, Riederer E (2020). _R Markdown Cookbook_. Chapman
and Hall/CRC, Boca Raton, Florida. ISBN 9780367563837,
<https://bookdown.org/yihui/rmarkdown-cookbook>.
To see these entries in BibTeX format, use 'print(<citation>,
bibtex=TRUE)', 'toBibtex(.)', or set
'options(citation.bibtex.max=999)'.
I assume you are familiar with how citing references works, and hopefully, you are already using a reference manager. If not, let me know in the discussion boards.
To have something that plays well with R Markdown, you need file format that stores all the references. Click here to learn more other possible file formats available to you to use within a R Markdown file:
As you can see, there are ton of file formats including .medline (MEDLINE), .bib (BibTeX), .ris (RIS), .enl (EndNote).
I will not discuss underlying citational management software itself, but I will talk briefly how you might create one of these file formats.
If you recall the output from citation("rmarkdown") above, we might consider manually copying and pasting the output into a citation management software, but instead we can use write_bib() function from knitr package to create a bibliography file ending in .bib.
Let’s run the following code in order to generate a my-refs.bib file
@Manual{R-rmarkdown,
title = {rmarkdown: Dynamic Documents for R},
author = {JJ Allaire and Yihui Xie and Jonathan McPherson and Javier Luraschi and Kevin Ushey and Aron Atkins and Hadley Wickham and Joe Cheng and Winston Chang and Richard Iannone},
year = {2021},
note = {R package version 2.8},
url = {https://CRAN.R-project.org/package=rmarkdown},
}
@Book{rmarkdown2018,
title = {R Markdown: The Definitive Guide},
author = {Yihui Xie and J.J. Allaire and Garrett Grolemund},
publisher = {Chapman and Hall/CRC},
address = {Boca Raton, Florida},
year = {2018},
note = {ISBN 9781138359338},
url = {https://bookdown.org/yihui/rmarkdown},
}
@Book{rmarkdown2020,
title = {R Markdown Cookbook},
author = {Yihui Xie and Christophe Dervieux and Emily Riederer},
publisher = {Chapman and Hall/CRC},
address = {Boca Raton, Florida},
year = {2020},
note = {ISBN 9780367563837},
url = {https://bookdown.org/yihui/rmarkdown-cookbook},
}
Note there are three keys that we will use later on:
R-rmarkdown
rmarkdown2018
rmarkdown2020
Linking .bib file with .rmd (and .qmd) files
In order to use references within a R Markdown file, you will need to specify the name and a location of a bibliography file using the bibliography metadata field in a YAML metadata section. For example:
---title:"My top ten favorite R packages"output: html_documentbibliography: my-refs.bib---
You can include multiple reference files using the following syntax, alternatively you can concatenate two bib files into one.
By default, Pandoc will use a Chicago author-date format for citations and references.
To use another style, you will need to specify a CSL (Citation Style Language) file in the csl metadata field, e.g.,
---title:"My top ten favorite R packages"output: html_documentbibliography: my-refs.bibcsl: biomed-central.csl---
To find your required formats, we recommend using the Zotero Style Repository, which makes it easy to search for and download your desired style.
CSL files can be tweaked to meet custom formatting requirements. For example, we can change the number of authors required before “et al.” is used to abbreviate them. This can be simplified through the use of visual editors such as the one available at https://editor.citationstyles.org.
Other cool features
Add an item to a bibliography without using it
By default, the bibliography will only display items that are directly referenced in the document. If you want to include items in the bibliography without actually citing them in the body text, you can define a dummy nocite metadata field and put the citations there.
---nocite: | @item1, @item2---
Add all items to the bibliography
If we do not wish to explicitly state all of the items within the bibliography but would still like to show them in our references, we can use the following syntax:
---nocite:'@*'---
This will force all items to be displayed in the bibliography.
You can also have an appendix appear after bibliography. For more on this, see:
We have learned that inside your file that contains all your references (e.g. my-refs.bib), typically each reference gets a key, which is a shorthand that is generated by the reference manager or you can create yourself.
For instance, I use a format of lower-case first author last name followed by 4 digit year for each reference followed by a keyword (e.g name of a software package). Alternatively, you can omit the keyword. But note that if I cite a paper by the same first author that was published in the same year, then a lower case letter is added to the end. For instance, for a paper that I wrote as 1st author in 2010, my bibtex key might be hicks2022 or hicks2022a. You can decide what scheme to use, just pick one and use it forever.
In your R Markdown document, you can then cite the reference by adding the key, such as ...in the paper by Hicks et al. [@hicks2022]....
SciWheel
I use SciWheel for managing citations and writing papers on Google Docs as documented at https://lcolladotor.github.io/bioc_team_ds/writing-papers.html. I mention it here because you can import \(BibTeX\) files (.bib) on SciWheel, which can make your life easier if you want to import R package citations that way.
Post-lecture materials
Practice
Here are some post-lecture tasks to practice some of the material discussed.
Questions
Try out the following:
What do you notice that’s different when you run citation("tidyverse") (compared to citation("rmarkdown"))?
Install the following packages:
install.packages(c("bibtex", "RefManageR"))
What do they do? How might they be helpful to you in terms of reference management?
Instead of using a .bib file, try using a different bibliography file format in an R Markdown document.
Practice using a different CSL file to change the citation style.
Allaire, JJ, Yihui Xie, Christophe Dervieux, Jonathan McPherson, Javier Luraschi, Kevin Ushey, Aron Atkins, et al. 2023. Rmarkdown: Dynamic Documents for r. https://CRAN.R-project.org/package=rmarkdown.
Xie, Yihui, J. J. Allaire, and Garrett Grolemund. 2018. R Markdown: The Definitive Guide. Boca Raton, Florida: Chapman; Hall/CRC. https://bookdown.org/yihui/rmarkdown.