March 6, 2018

Writing reports and manuscripts in R Markdown

Agenda

  • Make an RProject where we will store all of our files for today
  • Quick refresher of R and R Markdown basics
  • Navigate a workflow to:
    • Load in our data to a plain .R script
    • Write an informal summary report in R Markdown
    • Write a manuscript draft in R Markdown

Why R Markdown?

  • Easy to integrate data directly into other documents
  • No copy/paste -> less margin for error
  • Much simpler to learn compared to other tools/languages, like LaTex
  • Reference management integration: easy to cite relevant papers and autogenerate bibliographies

Knitting

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

Getting set up

Installation

Have installed the following software

Required:

Installation

Other software to be aware of:

  • Pandoc
    • If you have RStudio installed, Pandoc is automatically installed too
    • Pandoc does the converting from .Rmd to .md, .docx, .pdf, .html, etc.
    • It's working hard behind the scenes, but we don't interact with it too much
  • Latex
    • Necessary to install if you want to output PDFs
    • We won't do this today

RProjects

EXERCISE 1

Make a new R Project for this workshop

  • Make a new directory for this workshop
  • Put the workshop contents in the same directory

Install the following packages

Copy and paste this code into your R console and run it

  • install.packages(c("rmarkdown","knitr","bookdown"))
  • You can also do this manually in the Packages pane

Create a new R Markdown file

EXCERCISE 1

Recap

  1. Make new R Project
  2. install.packages(c("rmarkdown","knitr","bookdown"))
  3. Creat new R Markdown document

Essential parts of any R Markdown document

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:
     name: Thea Knowles
     affiliation: Western University
     name: Scott Adams
     affiliation: Western University
     affiliation: University Hospital
date: "09 March, 2018"

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

Set chunk options

  • Chunks are sections that will include R code. By setting defaults at the beginning of your document, you can specify what you want most of your chunks to do.
  • In each chunk, you can specify options in the form tag=value in the chunk header.
    • For example, in the following, the tag include is set to FALSE, indicating that we don't want the contents of this chunk included in the output

This is the default chunk options set when you create a new .RMD (R Markdown) file.

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
```

Set chunk options

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
```

This chunk provides the following information for "knitting" the document:

  • setup: the name of the chunk You shouldn't have two chunks with the same name, unless they are unnamed (in which case they just get numbered automatically during the knit process)
  • include = false: the chunk will not be included in the output after knitting.
  • knitr::opts_chunk$set(echo = TRUE): the default behavior for chunks is to "echo;" you will see the actual code printed in the final output. You can set this to false if you don't want the actual code included by default.

Set chunk options

  • You don't have to change this unless you want to
  • You can assign different values on a chunk-by-chunk basis
  • More on this in a minute!

Essential parts of any R Markdown document