Reproducible Reports

Getting Started

1. Create a project in RStudio

• In RStudio, click File -> New Project -> New Directory -> New Project.

• Give your project directory a clear name, preferably without spaces.

• Make sure your project directory/folder is created in an accessible place on your system.

• Select Open project in a new session.

2. Create a project structure suited for reproducible work

• Once your project has been opened in a new session, you can generate a basic directory structure by running the following piece of code in you R console:

dir.create("data", recursive = TRUE)
dir.create("docs", recursive = TRUE)
dir.create("R", recursive = TRUE)

library(usethis)

usethis::use_readme_md(open = rlang::is_interactive())
usethis::use_mit_license(copyright_holder = NULL)

You can adapt the above code to create additional folders that you may need.

3. Create a R Markdown document for your manuscript.

• In RStudio, click File -> New File -> R Markdown

• Provide a title, author, date and specify the output option as HTML.

• A R Markdown template will show up in RStudio, make sure to save the R Markdown file in the R folder.

5. Familiarize yourself with the R Markdown document and associated files

• An (optional) YAML header surrounded by ---s.
• R code chunks surrounded by ```s.
• Text mixed with simple text formatting in Markdown syntax.

Writing

The body of the document is where you will do your writing, which will primarily be in the Markdown format (LaTeX and HTML would also work, depending on the output format).

Markdown Syntax

If you’re not familiar with Markdown, you can familiarize yourself with it in a couple of minutes using the following link: https://learnxinyminutes.com/docs/markdown/.

Additionally, you can use the Visual Editor option in RStudio to see Markdown syntax previewed in it’s final format as you write.

Some things you can do with Markdown:

• Headings can be created for sections and subsections using the # hashtag character. So # Heading 1 for a top-level heading and ## Heading 2 for a second-level heading and so on.

Markdown Syntax	Output
# Header 1	Header 1
## Header 2	Header 2
### Header 3	Header 3
#### Header 4	Header 4
##### Header 5	Header 5
###### Header 6	Header 6

• Text can be formatted in italic or bold using the * asterisk character.

Markdown Syntax	Output
*italics*, **bold**, ***bold italics***	italics, bold, bold italics
superscript^2^ / subscript~2~	superscript2 / subscript2
~~strikethrough~~	strikethrough
`verbatim code`	verbatim code

• Bullet point lists can be created with a - hyphen or * asterisk for each line in the list.

Markdown Syntax	Output
* unordered list + sub-item 1 + sub-item 2 - sub-sub-item 1	unordered list sub-item 1 sub-item 2 sub-sub-item 1

There’s more!

• Links can be embedded by writing in the following way: insert text which should be hyperlinked

• Plain code can be embedded in text using the ``` backtick character. R code can be embedded as well, but we will cover that in the next section.

Some additional Markdown resources:

• https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax

• https://quarto.org/docs/authoring/markdown-basics.html

Rendering

You can render the R Markdown document to it’s specified output format using the Knit button in RStudio’s editor toolbar.

You can also use the render function documented in the following page: https://pkgs.rstudio.com/rmarkdown/reference/render.html

Output Formats & Options

R Markdown enables numerous output formats, of which the most relevant are:

• pdf_document

• html_document

• word_document

The output formats can be specified in the YAML header.

In a reproducible project, the human-generated content (manuscript) is kept separate from the project-generated content (result). Adding the code below to the end of your YAML header will ensure that your R Markdown document is rendered to the docs folder.

knit: (function(input, ...) {
    rmarkdown::render(
      input,
      output_dir = "../../docs"
    )
  })

Moreover, it is possible to specify multiple output formats for simulatenous rendering. The code chunk below specifies R Markdown’s default pdf & Word documents as the output formats.

output: 
  pdf_document: default 
  word_document: default
knit: (function(input, ...) {
    rmarkdown::render(
      input,
      output_format = "all",
      output_dir = "../../docs"
    )
  })

Analysis

Unlike regular R scripts, code in R Markdown documents is run within so-called code chunks to separate text from code.

You can insert code chunks by:

• using the Add Chunk button in RStudio’s editor toolbar,

• using keyboard shortcuts Ctrl + Alt + I on Windows and Cmd + Option + I on MacOS,

• or by typing the chunk delimiters {r} and.

If the default code chunk options are in place, rendering your R Markdown file will involve each code chunk being run and the results being embedded beneath the code chunk in the final document.

Code Chunk Options

Chunks can be customized using the following options:

• include = FALSE prevents code and results from appearing in the finished file. R Markdown still runs the code in the chunk, and the results can be used by other chunks.

• echo = FALSE prevents code, but not the results from appearing in the finished file. This is a useful way to embed figures.

• message = FALSE prevents messages that are generated by code from appearing in the finished file.

• warning = FALSE prevents warnings that are generated by code from appearing in the finished.

• fig.cap = "..." adds a caption to graphical results.

The code chunk option has to be specified within the top chunk delimiter: ```{r}

For example, ```{r echo=FALSE, warning=TRUE}

Inline Code

Code results or quick calculations can be inserted directly into the text of a R Markdown by enclosing the code with r. When the document is rendered, the results of the inline code will be displayed but not the code itself. There will be no additional text formatting either, which makes the inline code output indistinguishable from surrounding text.

Inline code is a great option for reporting results in text in a reproducible way, while minimizing errors.

Resources

You can read more about code chunks and inline code in the following pages:

• https://rmarkdown.rstudio.com/lesson-4.html

• https://bookdown.org/yihui/rmarkdown-cookbook/r-code.html

Referencing

Now that we know how to write in Markdown and run analyses in code chunks, let’s learn about referencing using BibTex keys!

Working with BibTex keys

R Markdown works with bibliographies in the form of .bib files. .bib files stand for BibTeX Bibliographical Database files. They are text files which contain a list of references in the form of BibTex keys.

A typical BibTex key might look like the following:

@article{nash51,
  author  = "Nash, John",
  title   = "Non-cooperative Games",
  journal = "Annals of Mathematics",
  year    = 1951,
  volume  = "54",
  number  = "2",
  pages   = "286--295"
}

Here is an example BibTex key for a reference used for this section:

@misc{RMarkdownWritingReproducible,
    title = {{RMarkdown} for writing reproducible scientific papers},
    url = {https://libscie.github.io/rmarkdown-workshop/handout.html},
    urldate = {2023-04-18},
    file = {RMarkdown for writing reproducible scientific papers:C\:\\Users\\Moope001\\Zotero\\storage\\SJITSZZI\\handout.html:text/html},
}

The .bib file should be in the same folder as the R project and the YAML header in the R Markdown file should be updated to refer to it.

In practice, your .bib file should be updated along the way to include the BibTex keys for all your references. Once the the .bib file contains the BibTex key you want referenced, you can cite a specific reference while writing using the the @ character with the key/idenitifier in the first line of the entry.

For the above examples, it would be @nash51 and @RMarkdownWritingReproducible as non-bracketed references and [@nash51] and [@RMarkdownWritingReproducible] for bracketed references.

Where do I get BibTex keys?

The efficient way to manage your BibTex keys would be to use Zotero and Better BibTex for Zotero, which you then integrate with R. Instructions for this are presented (briefly) below, but if you need a quicker way to get BibTex keys - we also have instructions for obtaining them via Google Scholar.

Google Scholar

• To download BibTeX citation, go to Google Scholar and search for a publication.

• Click the Cite button below the search result and you will see a pop-up dialog with formatted citations for MLA, APA, and Chicago styles.

• At the bottom of the pop-up dialog, there is an option for BibTex - clicking that will open a new tab with the Bibtex key for that publication.

• Copy the BibTex key and paste it into the .bib file for your project.

Using Zotero & Better BibTex for Zotero

1. Set up Zotero

   • Install Zotero on your computer

   • Install the Zotero connector with Chrome (unless you want to input your papers manually)

   • Create a Zotero account (Zotero webpage)

   • Sync your account with your local Zotero installation (in Zotero preferences -> sync)

2. Install the “Better Bibtex” plugin

   • Download the Zotero-better-bibtex-6.7.75.xpi file from here: https://github.com/retorquere/zotero-better-bibtex/releases/tag/v6.7.75

   • Follow the installation instructions here: https://retorque.re/zotero-better-bibtex/installation/

3. Set up your library and collect bibliography material

   • Create a new folder inside your Zotero library to collect all the materials relevant to your study

   • Collect studies in your new folder using Zotero connector or adding the material manually to your library

4. Create a .bib file (bibliography file)

   • In your Zotero local app, right click on your new folder -> Export Collection

   • Choose format BibText and click Okay

   • Choose a destination folder. The destination folder MUST be the same of your R Markdown file

5. Include the .bib file into your R Markdown and quote studies

   • In the YAML lines (the ones between ———) of your R markdown template look for the keyword “bibliography”. Write your just created .bib file (without quotes) after “:”

   • When you need to quote a material, look inside the bib file, look at the first line after the very first left curly bracket “{“ and, in the markdown text, write @, where is the line of text after “{“. NOTE: this very first line of text does not appear in the bibliography printed on your final paper, it is a sort of nickname you use to quote paper and it can be set up to whatever word/sentence you like (but try to avoid empty space and use underscores _ instead)

   • Alternatively, when using the Visual Editor option - you can use the citation dialog/option to insert citations directly.