Learn how to use R Markdown to combine writing and code

📝 Create new R project

📝 Create, edit, and compile .Rmd file

📝 Create & edit helper.R file to feed to your .Rmd

Recap: Console and script panes in RStudio

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

More options…

title: "Changes in voice acoustics along a speech rate continuum
        in Parkinson's disease"
author: "Thea Knowles, Scott G. Adams, Mandar Jog"
date: Last updated `r Sys.Date()`
output:
  bookdown::word_document2:
    reference_docx: "../rmd_templates/custom_reference.docx"
  redoc::redoc:
    highlight_outputs: FALSE
    margins: 1
    line_numbers: FALSE
bibliography: references.bib
csl: "csl_files/apa7.csl"

• 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

• Let’s say we want to include a code chunk that assigns x the value of 10.
• Here are some ways we can do that.

First, insert a new R chunk by

• Typing Alt + Cmd/Ctrl + i OR
• Clicking Code >> Insert Chunk from the R Studio menu

Bare R code chunk (no labels or options)

```{r}
x <- 10
```

Give it a label (“my-chunk”)

```{r my-chunk}
x <- 10
```

⚠️ Chunk labels CANNOT contain spaces, underscores, or special characters, but CAN contain hyphens.

Tell RMarkdown what to do with it (Set chunk options)

```{r my-chunk, echo = FALSE}
x <- 10
```

In this example, we set the echo option:

• echo = TRUE: show the code in the rendered Rmd document
• echo = FALSE: don’t show the code in the output, but DO run it in the background

➡️RMarkdown cheat sheet

➡️RStudio lesson

➡️Knitr book chapter

Let’s say you want to set default behavior for all of your code chunks. You can do this using the knitr package in a special chunk at the beginning of your document.

When you create a new Rmarkdown document from the default template, this is included for you:

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

```{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): set echo = TRUE for all chunks (you can still set echo = FALSE in individual chunks later if you want)

Tables written like this:

First Header  | Second Header
------------- | -------------
Content Cell  | Content Cell
Content Cell  | Content Cell

• See Tables Generator website

• See remedy and beautifyR R packages/RStudio addins for dealing with markdown tables

• Data frames can be turned into tables without manual modification

  • See kable and flextable R packages

You can refer to variables stored in R in your code using the syntax: `r [r code here!]`

Example:

Earlier in your code you have assigned x <- 5 in an R chunk

x <- 5

Typing

In the Rmarkdown document you created from the default template…

• do my data cleaning/exploration in a separate .R script (“helper.R”)
• source my helper.R file in my RMarkdown document and use code chunks to polish figures/tables
• include in-line R code that refers back to R objects made in helper.R

First: make sure simulated_vot_data.csv is in your project folder (same level as the .RProject). Then:

1. Create a new .R script
2. Add the following code
3. Save it as helper.R in your project folder (same level as your .RProject for now)

Try to run the code in the R console.

🐛 We can pause to diagnose any errors people run into!

Open your .Rmd file and insert a new code chunk below the setup chunk

```{r source-helper}
    source("helper.R")
    
    min(vot$VOT)
    max(vot$VOT)
```

Knit the .Rmd document. What do you see?

🐛 We can pause to diagnose any errors people run into!

Below your R chunk, add the following lines:

The mean VOT is `r vot_m`.

The mean VOT is `r min(vot$VOT)` and the max VOT is `r max(vot$VOT)`.

Add another code chunk:

```{r vot-distribution}
    hist(vot$VOT)
```

The ability to refer to your code in your document becomes EXTREMELY helpful once you start creating multiple figures, reporting summary variables and tables of statistics

Build your skill set to tailor to your goals: Some guiding suggestions based on my own experience

• Start with using R Markdown to tell the story of your data to you, to your supervisor (summary reports)
• If dissertating - start early! Use RMarkdown as a way to keep track of your data. Compile frequently and read up on project management
• Write an article in RMarkdown & learn how to use templates, reference management integration, and .RData files
• Present your data using RMarkdown
  • This presentation uses the ioslides_presentation output, but xaringan is an extremely powerful & popular tool for RMarkdown presentations

• RStudio v1.4 released a mode to edit markdown more easily - the result is a word processor-style experience
• I still recommend getting the basics down first, but this is an exciting development

Read more about Visual R Markdown Editing Mode here

• R Markdown: The Definitive Guide
• R Markdown Cookbook
• R-Ladies #LdnOnt guide to dissertating with R Markdown and bookdown
• Page Piccinini’s R for Publication Lessons
• A curated/quasirandom list of other very helpful resources

here are some of the additional “extras” we talked about

• More on snippets: Autocomplete text shortcuts for common strings of text.
• RData vs. RDS: Load in your environment or specific R objects for faster rendering
• tjmisc::ggpreview(): preview your plots before knitting
• RMarkdown: notebooks vs. documents: Notebooks allow a special execution mode of R Markdown that allows you to see the results of your chunks in the Source pane as you go. All .Rmd files can be rendered as notebooks and vice versa.