January 14, 2020

Academic writing with R Markdown and Bookdown

Agenda

  1. The tools we’ll be using
  2. Getting set up
  3. Writing a summary report
  4. Writing a manuscript
  5. Writing a thesis

1. Tools

Why R Markdown?

  • Integrate R code directly into writing using basic Markdown syntax
  • Reference management integration
  • Reproducibility
  • Accessible learning curve

https://rmarkdown.rstudio.com/

Why bookdown?

Knitting with knitr

When you run R Markdown, you are knitting together plain Markdown text and R code.

knitr is the engine.

Materials for today

We will generate the following files:

  • Helper R script (helper.R)
  • Summary report (starwars_summary.Rmd)
  • Manuscript (starwars_manuscript.Rmd)
  • Thesis (starwars_thesis.Rmd)

We will also use the following files

  • custom_reference.docx
  • apa.csl
  • starwars_refs.bib

2. Getting set up

Setting up: Software

  • R
  • RStudio
    • Recent versions of RStudio also include Pandoc, which is required to compile documents
  • Latex for Mac or Windows (if you want to compile to PDF).
    • Alternatively, install TinyTex, the Latex distribution created and recommended by Yihui Xie, creator of RMarkdown and bookdown[^139][^1032].

Setting up: R packages

  • bookdown R package.
  • Installing bookdown will automatically import knitr and rmarkdown pacakges as well. Install it by entering the following code into your R console:
  • Not necessary, but awfully helpful for data analysis in R in general, is the tidyverse R package
install.packages(c("bookdown", "tidyverse"))
# includes rmarkdown, knitr

Setting up: Git & GitHub

  • We won’t go over this in today’s presentation, but git is a very handy version control system that helps you back up your projects, and has easy integration with RStudio.
  • Recommended reading: Happy Git with R

Setting up: Recommended workflow for a new project

R Markdown document components

YAML

YAML (rhymes with camel): The header that tells R Markdown how to generate your document. Indentation and spacing are very important.

  • Permits the following to happen when you knit:
    • .Rmd -> knitr -> .md -> Pandoc -> output
    • Output can be .docx, .html, .pdf, and many others
  • YAML: “YAML Ain’t Markup Language”

Basic:

title: "Untitled"
author: "Thea Knowles"
date: '2018-02-18'
output: word_document

YAML

Gettin’ fancy

title: "A very important title"
subtitle: "A less important subtitle"
author:
- Thea Knowles^1^, Thea Knowles' Alter Ego^2^
- ^1^Western University, ^2^University of Western Ontario
date: "14 January, 2020"
output:
  bookdown::word_document2:
    fig_caption: yes
    md_extensions: +footnotes
    reference_docx: custom_reference.docx
    toc: yes
date: "Last updated: ` r format(Sys.time(), '%d %B, %Y')`"

YAML

Even fancier:

  • output extensions
  • template
  • bibliography file
  • csl (references style guide)
  • css (supreme customization!)

Different options for:

Essential parts of any R Markdown document