Compartmentalized Documented Extendible Reproducible Robust

Overview

This session will introduce writing reports using R Markdown. There are many on-line tutorials for R Markdown which will cover the basics. I’ll focus on some of the aspects of R Markdown that can really speed up your work: automating the making of tables and graphs. Our work often involves making tables that process some data and then report that in tables. When the data change (which happens often), we have to remake tables (and graphs). This is very time-consuming and creates errors. I’ll show you how to automate this process so you are not manually remaking tables for reports. You can output your file in many formats: html, PDF, Word, presentations.

This session will exploring a small slice of R Markdown. When you are ready to explore more, go to this great R Markdown resource R Markdown for Scientists. The R Markdown Definitive Guide is also a good resource.

This material was covered in the 2020 NWFSC workshops:

Set-up

If you want to try out the things I am showing, you will need R and RStudio. If you have never made an R Markdown file, there are some packages that you’ll need.

Build your first R Markdown file

  • Open RStudio, and click File > New File > R Markdown… .
  • Select the default (document) and click ok. This will open a template R Markdown document.
  • Save the file and then click ‘Knit’ in the nav bar above your template.
  • Download the necessary packages if RStudio complains and won’t build.

Note, to make PDF files you will need a LaTeX installation. If you don’t have one already (if you are not sure, then you don’t), you can install tinytex. Run these lines:

install.packages('tinytex')
tinytex::install_tinytex()

Note the first time you make a PDF, tinytex will load any needed packages and it can take a long time. You’ll see a spinning wheel on the R Markdown tab.

Templates

I have made a repository Rmarkdown-Tutorial with some template Rmd files for you to look at. For this week, you just need the material; you don’t to make a repository yourself (linked to GitLab or GitHub).

To get the material:

  • You can download a zip of the repository. The download button is on the repository link (above) and is a green button that says ‘Clone or download’. Unzip that file and then do New Project > Existing Directory and navigate to the directory from the zip file.
  • If you have Git installed, click the blue cube with R in the top right corner. New Project > Version Control > Git and then paste in the URL. Note you won’t be able to push changes since you cloned from my repository.
  • You can also clone to a GitLab or GitHub repo (New Project or Repo > Import from URL) and then pull your clone on GitLab or GitHub into RStudio via New Project > Version Control.

Basic Rmd file

Open up Basic.Rmd.

At the top you see

---
title: "Basic"
author: "EE Holmes"
date: "9/2/2018"
output: html_document
---

This is the yaml which gives the instructions about how to process your R Markdown file. The yaml file is sensitive to spaces. Do not add or subtract spaces. This yaml is very simple, but the yaml can be complex for some applications. We will only be working with simple examples.

After the yaml is the content. To see a summary of R Markdown formating, click ‘Help’ menu and then ‘Markdown Quick Reference’.

Create output

We can create documents in different formats from this Rmd file. Click the drop-down menu next to the ‘knit’ button.

  • HTML Select ‘knit to HTML’ to create a web document.
  • Word Select ‘knit to Word’ to create a Word document.
  • PDF Select ‘knit to PDF’ to create a PDF. Note need for a LaTeX installation (easiest is tinytex).

Getting help

In RStudio, click the ‘Help’ tab in the top nav bar. You will see ‘Markdown Quick Reference’. That has basic markdown syntax. You can also click ‘Cheatsheets’ and there are two references sheets. Using Google, you can also find answers to any questions that the RStudio help files doesn’t answer. See also R Markdown for Scientists.

Tips:

  • Markdown is sensitive to leading spaces. " ## Topic" will not produce a header while “## Topic” will. " ```{r}" (note leading space) will not be interpreted as R code.
  • Markdown is sensitive to line returns. If you are tying to make a list, “1. item”, then you must have two line returns before the “1. item”.

Start a new Rmarkdown file using RStudio template

Click the File tab, then select New File > R Markdown. This will open a template R Markdown file. You will be asked for a title and whether to have the output be html, PDF, or Word.

Other example Rmds

  • Figures Figures.Rmd
  • Tables Table.Rmd
  • Tables for Word, html, or latex Table_Extras.Rmd
  • Math Math.Rmd
  • Table of contents and Code folding Extras.Rmd
  • Presentations
    • ioslidy_presentation.Rmd Chose File > New > R Markdown > ioslidy presentation to create this presentation template.
    • xaringan_presentation.Rmd You will need to install the xaringan package.
  • Making tables using a function. This allows you to make the same table but with different data. A common example would be making a standard table for each species or each population in a dataset. Report with Tables shows you how to do that. Start with the README file.

Accessibility

Knitting in RStudio by clicking the Knit button uses rmarkdown::render() which will automatically produce an html document that is more accessible than other ways that you might knit a R Markdown document. However you’ll need to do some special things to add alt info to figure in the html, specifically add a figure caption.

Adding figure alt text

If you don’t need to have figure captions or if you are ok with the figure legend and alt text being the same, they adding alt text for figures is quite easy.

Figure caption displayed and alt text will be the same

plot(1:10)
This will be the alt text

This will be the alt text

No figure caption displayed

Add this to the top of your Rmd (or save to a css file and put that in the yaml) and the figure caption will not show up in your html.

<style>
    .caption {
        display:none;
    }
</style>

Use html

Another approach is to have R Markdown save your figures, and then insert those with html. Then you have full control over the caption, alt text and can add the longdesc tag also.

Adding table captions

You can use caption= with knitr::kable() to add captions.

knitr::kable(cars[,1:2], caption="This will be the Table caption")
This will be the Table caption
speed dist
4 2
4 10
7 4
7 22
8 16
9 10
10 18
10 26
10 34
11 17
11 28
12 14
12 20
12 24
12 28
13 26
13 34
13 34
13 46
14 26
14 36
14 60
14 80
15 20
15 26
15 54
16 32
16 40
17 32
17 40
17 50
18 42
18 56
18 76
18 84
19 36
19 46
19 68
20 32
20 48
20 52
20 56
20 64
22 66
23 54
24 70
24 92
24 93
24 120
25 85

No table caption displayed

Add this to the top of your Rmd (or save to a css file and put that in the yaml) and the table caption will not show up in your displayed html but will still be there for accessibility.

<style>
    caption {
        display:none;
    }
</style>

Accessibility resources

https://r-resources.massey.ac.nz/rmarkdown/

Latex (PDF)*

Making accessible PDFs is harder in LaTeX. You might look at the tagpdf.

Another option is to have R Markdown save the figures, and use LaTeX:

\begin{figure}
    \centering
    \includegraphics{fig1.png}
   \Description[short desc]{long description}
   \caption{the caption}
   \label{fig:fig1}
\end{figure}

More Rmd uses

  • Websites: The workshop website is built off Rmd files. See the website tutorial to learn how to do this. It is super easy.
  • Online books using bookdown: Books like this one for our time-series course are easy to make using Rmds. See the bookdown tutorial to learn how to do this. Again super easy.
  • Create a spiffy landing page for your repository: Like this one for our MARSS package. This is literally a couple clicks on GitHub (not sure if this is possible on GitLab).
  • A journal article repo. Journal Article This shows you a realistic repository for a journal article. I’ve cut out many paragraphs here and there to shorten it, but it is still has all the parts. The repository is a self-contained paper with all the data and the analyses are redone completely whenever Main.Rmd is re-knit. So if the data change, all the analyses will be updated.
  • Making tables using a function. This allows you to make the same table but with different data. A common example would be making a standard table for each species or each population in a dataset. Report with Tables shows you how to do that. Start with the README file.

Figure and Table numbering

Automatic figures and table numbering for a paper or a report is a hassle with R Markdown. Here is my solution. The Journal Article repo uses this method.

NWFSC Math Bio Program