Using R markdown for notebooks and documents
Last updated on 2023-01-24 | Edit this page
Overview
Questions
- How do you write a notebook or document using R Markdown?
Objectives
- Explain how to use markdown documents and notebooks
- Demonstrate how to include a header, markdown elements, pieces of code and code outputs
- Discuss how to render documents and notebooks
Do I need to do this lesson?
If you can answer the following questions, you can skip this lesson.
- What does a R markdown header look like?
- How do you insert headings in an R markdown file?
- How do you insert chunks in an R markdown file, and what do they look like?
- What is the difference between an R markdown document and notebook?
- How do you render an R markdown file?
- It looks something like this
YAML
---
title: "Habits"
author: Jane Doe
date: March 22, 2005
output: html_document
---- Use one two four hashes (
#) at the start of the line. - Insert code blocks by typing them manually, in the menu bar under Code > Insert Chunk, or with the shortcut Cmd/Ctrl + Option + i. They look like this:
MARKDOWN
```{r chunk-name}
y <- 2
print(y)
```- For a notebook, an output is generated every time you save it. A document is only rendered when you Knit it.
- Use the Knit or Preview buttons, or use the function
rmarkdown::render(). For notebooks, just save the file to automatically render the file with any outputs that currently appear in Rstudio.
Rmarkdown for reproducible, documented analyis
For a long time, most R code was written in scripts. These are just plain old text files, usually with the file extension .R, which contain R code. Any documentation in these scripts was in the form of comments, and any graphic generated had to be saved to file (or viewed in a window, then closed).
This paradigm worked, but it was lacking an integrated view of the results of the analysis. This is the problem that knitr and R markdown were developed to address.
R markdown allows the user to create notebooks and documents that contain text elements (formatted using markdown), and R code. If I’ve ever sent you a .html file containing some results, this is how I generated it. Other formats are possible for data export, including .pdf, but I tend to always use .html for it’s interactive elements.
Documents you create are rendered into the final output format that you’ve specified, by running all the code and combining the outputs it with your markdown text.
Although simple, this approach is powerful; I wrote all the content on this website using R markdown files.
Rmarkdown header
R markdown files always start with a header, which is formatted in YAML, and at it’s most basic looks something like this:
YAML
---
title: "R Notebook"
output: html_notebook
---That’s it: just a title and an output.
Output types
When you create a .Rmd file, you’ll have to choose if you want it to be a notebook (output: html_notebook), a document (output: html_document), or some other output type (for example, output: pdf_document).
Notebooks and documents are very similar, and the only difference between html documents and notebooks is that a .html file is created with your analysis every time you save a notebook, whereas an output file will only be created for a document when you tell RStudio to render it.
If you want, you can add an author and a date, for example:
YAML
---
title: "Habits"
author: Jane Doe
date: "22 November 2022"
output: html_document
---Sometimes I want the date to be updated every time I render the document. You can do this by replacing the date with some R code.
YAML
---
title: "Habits"
author: Jane Doe
date: "`r Sys.Date()`"
output: html_document
---There are also lots of options for html documents and notebooks. I often use:
YAML
---
title: "Habits"
author: Jane Doe
date: "`r Sys.Date()`"
output:
html_document:
keep_md: true
df_print: paged
toc: true
toc_float:
collapsed: false
smooth_scroll: false
code_folding: hide
---You can also add parameters in your header that you can use throughout your code:
YAML
---
title: "Habits"
author: Jane Doe
date: "`r Sys.Date()`"
output:
html_document:
keep_md: true
df_print: paged
toc: true
toc_float:
collapsed: false
smooth_scroll: false
code_folding: hide
params:
test: true
species: "human"
---You can then refer to these parameters using the syntax params$test and params$species.
Markdown
Writing the markdown part of the file is are pretty simple. Use # for headings.
MARKDOWN
# Largest heading
## Large heading
### Medium heading
#### Small headingTo create paragraphs, leave at least one blank line between text.
MARKDOWN
This is a paragraph.
This is a different paragraph.To add a line break (to prevent sentences from running on from one another), add two spaces at the end of the line.
MARKDOWN
This is a line.
This is another line.To add emphasis, use * or _.
MARKDOWN
This text is **bold**.
This text is __also bold__.
This text is in *italics*.
This text is also in _italics_.
This text is both ***bold and in italics***.
___Same here___.To create a block quote, add > to the start of each line.
MARKDOWN
> This will be a quote
>
> that's all in the same blockTo make a list, use numbers or dashes.
MARKDOWN
This is an unordered list:
- element a
- element b
- element c
This is an ordered list:
1. element 1
2. element 2
3. element 3
If you want to display code, use backticks:
MARKDOWN
This is `inline` code.
```r
print("this is an R code block")
```To add images, use this syntax:
MARKDOWN
You can add links using parentheses and brackets:
MARKDOWN
You can read more in the [documentation](https://www.markdownguide.org/basic-syntax/)Adding code
Adding code blocks is also easy. Use the shortcut Cmd/ctrl + Option + i. You can also check what the shortcut is on your machine in the menu bar under Code > Insert Chunk.
Code blocks look like this:
MARKDOWN
```{r chunk-name}
y <- 2
print(y)
```There are lots of options to control how the code block and it’s output is displayed. For example:
MARKDOWN
```{r chunk-name2, echo=FALSE}
print("this code block won't appear in the output, but its output will")
```MARKDOWN
```{r chunk-name3, include=FALSE}
print("this code block won't appear in the output, and neither will it's output")
```If your code block produces a plot, the plot will appear in the report. You can change the size of the plot with options as well.
MARKDOWN
```{r chunk-name4, fig.width=8, fig.height=8}
tibble(
group = c("A", "A", "B", "B"),
y = runif(4)
) %>%
ggplot(aes(x=group, y = y)) +
geom_point()
```You can also apply options to all chunks using knitr::set_opts() at the top of your file.
MD
```r
knitr::opts_chunk$set(
echo=FALSE, fig.width = 6, fig.height = 6
)
```Inline code
You can also insert inline code in R markdown by using the syntax r my_expression. However, I don’t tend to do this much in documents because every time I re-open the file, using variables in these code blocks cause problems (because they don’t exist yet).
If you’re going to use inline code a lot, I’d recommend you stick to using R markdown documents instead of notebooks.
Rendering notebooks
There are a few different ways you can render your R markdown file. The easiest is to use the dedicated button in Rstudio. For documents, it’ at the top of your document and looks like this:
For notebooks, you don’t need to manually render - every time you save the file, R will knit it for you. But if you want to see what the notebook will look like, you can press the preview button:
You can also render your notebook using code:
R
rmarkdown::render("/path/to/file.Rmd")
If you set parameters, you can change them when you render the notebook:
R
rmarkdown::render("/path/to/file.Rmd", params = list(test=FALSE, speces="macaque"))
Other file types
There are also a number of other outputs you can produce from your R markdown other than html notebooks and documents. In particular, I’ve been playing around with slides using Quatro and ioslides. They can be a little tricky compared to power point, and a bit slow to render if your analysis is compute-heavy, but I think they’re worth considering!
This area is actively being developed, so it’s worth trying out new technologies when they are available.