Pre-lecture materials

Read ahead

Before class, you can prepare by reading the following materials:

Authoring in R Markdown from RStudio
Citations from Reproducible Research in R from the Monash Data Fluency initiative
Bibliography from R Markdown Cookbook

Acknowledgements

Material for this lecture was borrowed and adopted from

Learning objectives

At the end of this lesson you will:

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 the 'rmarkdown' package in publications, please use:

  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 (2022). rmarkdown: Dynamic
  Documents for R. R package version 2.15. URL
  https://rmarkdown.rstudio.com.

  Yihui Xie and J.J. Allaire and Garrett Grolemund (2018). R Markdown:
  The Definitive Guide. Chapman and Hall/CRC. ISBN 9781138359338. URL
  https://bookdown.org/yihui/rmarkdown.

  Yihui Xie and Christophe Dervieux and Emily Riederer (2020). R
  Markdown Cookbook. Chapman and Hall/CRC. ISBN 9780367563837. URL
  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:

https://rmarkdown.rstudio.com/authoring_bibliographies_and_citations.html

Citation management software

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

knitr::write_bib("rmarkdown", file = "my-refs.bib")

Now we can see we have the file saved locally.

list.files()

[1] "index.qmd"       "index.rmarkdown" "my-refs.bib"

If you open up the my-refs.bib file, you will see

@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_document
bibliography: my-refs.bib
---

You can include multiple reference files using the following syntax, alternatively you can concatenate two bib files into one.

---
bibliography: ["my-refs1.bib", "my-refs2.bib"]
---

Inline citation

Now we can start using those bib keys that we have learned just before, using the following syntax

[@key] for single citation
[@key1; @key2] multiple citation can be separated by semi-colon
[-@key] in order to suppress author name, and just display the year
[see @key1 p 12; also this ref @key2] is also a valid syntax

Let’s start by citing the rmarkdown package using the following code and press Knit button:

I have been using the amazing Rmarkdown package (Allaire et al. 2022)! I should also go and read (Xie, Allaire, and Grolemund 2018; and Xie, Dervieux, and Riederer 2020) books.

Pretty cool, eh??

Citation styles

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_document
bibliography: my-refs.bib
csl: 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:

https://bookdown.org/yihui/rmarkdown-cookbook/bibliography.html

Other useful tips

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]....

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.

Additional Resources

Tip

Add here.

rtistry

[Add here.]

References

Allaire, JJ, Yihui Xie, Jonathan McPherson, Javier Luraschi, Kevin Ushey, Aron Atkins, Hadley Wickham, Joe Cheng, Winston Chang, and Richard Iannone. 2022. 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.

Xie, Yihui, Christophe Dervieux, and Emily Riederer. 2020. R Markdown Cookbook. Boca Raton, Florida: Chapman; Hall/CRC. https://bookdown.org/yihui/rmarkdown-cookbook.