• You’re familiar with the basic mechanics of R

This is intended to be a hands-on workshop, so also:

• You have R (and probably RStudio) installed
• You have the rmarkdown package installed

Note: this presentation doesn’t (yet) cover the newer Quarto publishing system, but will provide a good foundation for learning it.

Here we are in Word:

We have no idea where these numbers came from.

Copy-and-paste into word processing documents sucks, and it’s easy to make mistakes (not update numbers, copy the wrong number, etc).

What if I want to generate 100 formatted reports for 100 different datasets?

The R Markdown Cookbook

What do we have? A text document (the R Markdown file).

What happened?

# A big header
## A smaller one
### Smaller still
A [link](https://daringfireball.net/projects/markdown/).
A sentence with _italics_ in it. **Boldface.**

A link. A sentence with italics in it. Boldface.

https://xkcd.com/1285/

R code in Markdown documents can be inline or in code chunks.

Inline code uses backticks, inside of which is an R expression that starts with “r”. It is typically used for something short:

• These slides were made with `r R.version.string`.

• These slides were made with R version 4.1.3 (2022-03-10).

• Two plus two equals `r 2+2`.

• Two plus two equals 4.

You can also easily insert equations like \(\sum_{n=1}^{10} n^2\)

The other mechanism to include R code in your document is via code chunks. These are evaluated by knitr and the results inserted into your document.

Let’s try this!

Two important notes:

• You can give chunks individual names, which makes it easier to navigate around longer documents.
• RStudio has nice controls for running individual chunks.

Side note: code chunks don’t have to be in R!

ls *.Rmd

## Advanced_RMarkdown.Rmd
## Getting-data-into-R.Rmd
## Introduction_to_RMarkdown.Rmd
## R-data-manipulation.Rmd
## ggplot2-basics1.Rmd
## ggplot2-basics2.Rmd
## ggplot2-intermediate.Rmd

We can control the behavior of code chunks by using chunk options (settings). Some common ones include:

Try inserting a new chunk with the code dim(iris).

What happens if you set eval=FALSE? What about echo=FALSE?

Why?

Say we have a figure we want to include:

library(gapminder)

p <- gapminder %>%
  filter(year == 1977) %>%
  ggplot(aes(gdpPercap, lifeExp, size = pop, color = continent)) +
  geom_point() +
  scale_x_log10() +
  ggtitle("gapminder 1977")

print(p)

Let’s add a graph to your document.

Note there are chunk options fig.cap, fig.width, and fig.height you can change.

Tables can be made by hand (see the Markdown help page), but usually we have a data frame that we want to display.

The simplest method uses knitr’s built-in kable() function:

We haven’t really talked about pandoc, the software that transforms Markdown into an output format of our choice.

Use the Knit menu button, or the output: line in the YAML header, to change the output format to e.g. `word_document” or “pdf_document”.

These may require extra software to be installed.

For reproducibility, it is a good practice to call sessionInfo() at the end of your document. Like this:

sessionInfo()

## R version 4.1.3 (2022-03-10)
## Platform: x86_64-apple-darwin17.0 (64-bit)
## Running under: macOS Big Sur/Monterey 10.16
## 
## Matrix products: default
## BLAS:   /Library/Frameworks/R.framework/Versions/4.1/Resources/lib/libRblas.0.dylib
## LAPACK: /Library/Frameworks/R.framework/Versions/4.1/Resources/lib/libRlapack.dylib
## 
## locale:
## [1] en_US.UTF-8/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## 
## other attached packages:
## [1] gapminder_0.3.0 ggplot2_3.4.0   dplyr_1.0.9    
## 
## loaded via a namespace (and not attached):
##  [1] highr_0.9        pillar_1.8.1     bslib_0.3.1      compiler_4.1.3  
##  [5] jquerylib_0.1.4  tools_4.1.3      digest_0.6.29    jsonlite_1.8.0  
##  [9] evaluate_0.15    lifecycle_1.0.3  tibble_3.1.8     gtable_0.3.0    
## [13] pkgconfig_2.0.3  rlang_1.0.6      cli_3.4.1        rstudioapi_0.13 
## [17] yaml_2.3.5       xfun_0.30        fastmap_1.1.0    withr_2.5.0     
## [21] stringr_1.4.0    knitr_1.38       generics_0.1.3   vctrs_0.5.1     
## [25] sass_0.4.1       grid_4.1.3       tidyselect_1.1.2 glue_1.6.2      
## [29] R6_2.5.1         fansi_1.0.3      rmarkdown_2.18   farver_2.1.0    
## [33] purrr_0.3.4      magrittr_2.0.3   scales_1.2.1     htmltools_0.5.2 
## [37] colorspace_2.0-3 labeling_0.4.2   utf8_1.2.2       stringi_1.7.6   
## [41] munsell_0.5.0

This takes one two lines of code in RMarkdown. Example based on this post.

In a subsequent paper [@Bond-Lamberty2009-py], we used the same model 
outputs to examine the _hydrological_ implications of these wildfire 
regime shifts [@Nolan2014-us].

In a subsequent paper (Bond-Lamberty et al. 2009), we used the same model outputs to examine the hydrological implications of these wildfire regime shifts (Nolan et al. 2014).

References

Bond-Lamberty, Ben, Scott D Peckham, Stith T Gower, and Brent E Ewers. 2009. “Effects of Fire on Regional Evapotranspiration in the Central Canadian Boreal Forest.” Glob. Chang. Biol. 15 (5): 1242–54.

Nolan, Rachael H, Patrick N J Lane, Richard G Benyon, Ross A Bradstock, and Patrick J Mitchell. 2014. “Changes in Evapotranspiration Following Wildfire in Resprouting Eucalypt Forests.” Ecohydrol. 6 (January). Wiley Online Library.

Good resources:

• The R Markdown Cheat Sheet
• The R Markdown Cookbook
• 15 Tips on Making Better Use of R Markdown
• Stack Overflow of course
• Allison Hill’s How I Teach R Markdown
• How to Make Beautiful Tables in R