88 Introduction to R Markdown
Written by Shirley Deng and last updated on 7 October 2021.
88.1 Introduction
Have you ever found yourself typing up a report in Microsoft Word and tried to insert code, code output, images or math? It can be pretty cumbersome!
But it’s not a problem anymore…
R Markdown documents allow you to not only type up reports, as you would in a Word document, but allow you to embed R, Python and SQL code with (hopefully) a little less fuss.
88.1.1 Why use R Markdown?
R Markdown allows for our files to be reproducible - if you or someone else finds an error in your code, or there’s a figure you want to fix, or there’s just a typo with a symbol - there’s no need to remake a new document from scratch.
Instead, you can edit the .Rmd file and “knit” (or compile) it to make your new html, .pdf or Word document. You can think of R Markdown as writing reports with code.
88.2 Creating a R Markdown file
To start a .Rmd file in RStudio, click File, then New File, and select R Markdown…
From there, we can select if we want our report to be in the form of an HTML page, pdf, or Word document, and give our report a title and author name.
RStudio will then generate a .Rmd file with a little template for us
88.2.1 YAML Header Chunk
We notice that the template starts off with something like the following chunk:
---
title: "A Good, Creative Title"
author: "Shirley Deng"
date: "01/01/2021"
output: pdf_document
---As you might guess, this creates a header for your report with the title, author and date specified.
We can also change the output option if we have a change of heart and would prefer an HTML page or Word document:
output: pdf_documentoutput: word_document
88.3 Markdown
Following the header chunk, we see a little section on R Markdown.
Markdown is a way for us to format our report text, and the sections below will outline how to use it.
88.3.1 Sections
The two pound signs, #, in front of R Markdown indicate that that line of text will be a header.
Whenever we use the pound sign to denote a header, this also creates a section in our final report document. We can view these sections by toggling the document outline with the following keyboard shortcuts:
-
Cmd+Shift+Oon Mac -
Ctrl+Shift+Oon Windows and Linux
For each #, the smaller the header. We can use smaller headers to denote subsections.
88.3.2 Paragraphs
To indicate a new paragraph, place two spaces at the end of the line.
For example, this line ends with two spaces…
And this text follows it.
88.3.3 Bold Text
We can bold text by putting a pair of asterisks, **, around it.
For example, we can write bold with **bold**.
88.3.4 Italicized Text
We can make text italicized by either using a single asterisk, *, around it.
Alternatively, we can also use an underscore, _, instead of the asterisk.
For example, we can write italics with *italics* or _italics_.
88.3.5 Superscript
We can make superscript by using a caret, ^, around it.
For example, we can write this superscript with s^uperscript^.
88.3.6 Subscript
We can make subscript the same way we make superscript, except with a tilde, ~, instead of a caret.
For example, we can write this subscript with s~ubscript~.
88.3.7 Lists
We can make lists by either using thr asterisk, *, dash, -, or plus sign, +, as bullets.
For example…
* this
* would
* makethe following list:
- this
- would
- make
And,
- this
- also
- makesthis list:
- this
- also
- makes
And,
+ so
+ does
+ thisthis list:
- so
- does
- this
88.3.8 Sublists
We can also use an indent to create a sublist.
For example,
- this
- makes a sublistlike so:
- this
- makes a sublist
88.3.9 Ordered lists
We can also makew numbered lists, simply by numbering each item.
For example,
1. this
2. is
3. numberedLike this:
- this
- is
- numbered
88.3.10 Hyperlinks
We can make a hyperlink by using the syntax [text here](link url here)
For example,
[this makes a link to the RStudio website](https://www.rstudio.com/)like this:
88.3.11 Images
We can embed images (with caption!) similar to how we make hyperlinks.
We just add an exclaimation point, !, in front of the hyperlink syntax.
For example,
like this:
this embeds a picture of the RStudio icon like so
88.3.12 Hyperlinked images
If you want to get real fancy, we can hyperlink images using a combination of the syntax we introduced above.
For example,
[](https://d33wubrfki0l68.cloudfront.net/521a038ed009b97bf73eb0a653b1cb7e66645231/8e3fd/assets/img/rstudio-icon.png)
88.4 Math environments
Writing math in R Markdown is probably one of its best features. To do so, we use another format - LaTeX.
Like how R Markdown can be likened to writing reports with code, we can liken LaTeX to writing mathematical equations with code.
88.4.1 Delimiters
Say we wanted to write the Pythagorean theorem, \(x^2 + y^2 = z^2\).
We need to work in a math environment, or math mode, in order to write math using LaTeX.
88.4.1.1 Inline
Sometimes we want to write a little bit of math in the middle of some text. In this case, we’d want our math in line with the rest of our text.
If we want our Pythagorean theorem inline, like above, we can write it as this: \(x^2 + y^2 = z^2 \)
to get this: \(x^2 + y^2 = z^2\)
88.4.1.2 Centred Display
But sometimes we want to showcase our math. Say, in the case we’re introducing an important equation.
If we have some math we’d like on its own line and centred, we can write this: \[ x^2 + y^2 = z^2 \]
to get this: \[ x^2 + y^2 = z^2 \]
Alternatively, we can also write this: $$ x^2 + y^2 = z^2 $$
to get this too: \[ x^2 + y^2 = z^2 \]
88.4.1.3 Aligned
What if we have multiple lines of math that we want to showcase? Like this:
\[\begin{aligned} a = 1 \\ b = 2 \end{aligned}\]It would be pretty inconvenient to type $$ around every line:
$$ a = 1 $$
$$ b = 2 $$Instead, we can use the aligned delimiters around our math, using \\ to end each line.
\begin{aligned}
a = 1 \\
b = 2
\end{aligned}However, it’s not neccessary to end the last line with \\.
This:
\begin{aligned}
a = 1 \\
b = 2 \\
\end{aligned} \[\begin{aligned} a = 1 \\ b = 2 \\ \end{aligned}\]
Too.
88.4.2 Superscript
Recall from our Markdown section that we use carets, ^, for superscript.
For example, we can write this superscript with s^uperscript^.
We also use carets when we want superscript in math environments, albeit slightly differently.
Instead of wrapping the superscripted text with the carets, we use a single caret, followed with the text wrapped in curly brackets, {}.
For example, let’s try using the inline delimiters \(\) to write \(s^{uperscript}\):
\(s^{uperscript}\) yields \(s^{uperscript}\)
88.4.3 Subscript
The same way superscripts and subscripts are paralled in Markdown applies to math environments.
For example, \(s_{uperscript}\) yields \(s_{uperscript}\),
And without curly brackets, \( s_uperscript \) yields \(s_uperscript\)
88.4.4 Math escapes: brackets and dolla dolla bill $ignz
What happens when we want to use brackets in math environments?
| In order to write this… | we’d have to write this |
|---|---|
| \(\$\) | \$ |
| \(\&\) | \& |
| \(\%\) | \% |
| \(\##\) | \## |
| \(\_\) | \_ |
| \(\{\) | \{ |
For example, we can write a spicy \(\$pi\_c\) by using \( \$pi\_c \).
88.4.5 Other syntax
There’s specific syntax for a lot of the more complex mathematical symbols we might find ourselves using!
88.4.5.1 Note: For the rest of the Math environments section, we will be making use of the inline delimiters \( \) unless otherwise specified.
88.4.5.2 Fractions:
We can use \frac{numerator}{denominator} to get \(\frac{numerator}{denominator}\).
88.4.5.3 Binomials:
We often see \({n \choose k}\) when working in combinatorics or probability.
Similar to the fraction syntax, we can use \binom{top}{bottom} to get \(\binom{top}{bottom}\).
Alternatively, we can use {top \choose bottom} to get \({top \choose bottom}\) as well.
88.4.5.4 Integrals
88.4.5.4.1 Indefinite
To get a plain Jane, indefinite integral, we can simply use \int to get \(\int\).
If we have multiple integrals, we just add an i for each additional one, as so:
| In order to write this… | we can write this |
|---|---|
| \(\int\) | \int |
| \(\iint\) | \iint |
| \(\iiint\) | \iiint |
| \(\iiiint\) | \iiiint |
What if we wanted more space between our integrals? Then simply use \int multiple times.
For example, \int\int would give us \(\int\int\).
88.4.5.4.2 Definite
We can make use of the superscript and subscript syntax in order to make our indefinite integrals into definite integrals.
For example, \int_a^b would give us \(\int_a^b\).
What if we had something more complex, like \(\int_{a+b}^{c-d}\)? We could use curly brackets, like so: \int_{a+b}^{c-d}
88.4.5.5 Sums
Like with integrals, we can get just the sigma for summation, \(\sum\), with \sum.
To get the indices, once again we make use of the syntax we’ve learned already.
For example, \sum_{i=1}^{n} would give us \(\sum_{i=1}^{n}\).
88.4.6 Spaces
Spaces created by pressing the space bar don’t really work in math mode!
Instead, we have several options for writing spaces in math environments.
| We see that this… | will give us this |
|---|---|
poo poo |
\(poo poo\) |
poo \; poo |
\(poo \; poo\) |
poo \: poo |
\(poo \: poo\) |
poo \, poo |
\(poo \, poo\) |
poo \! poo |
\(poo \! poo\) |
88.5 Code
Another handy feature of R Markdown is that we can display and run code in its own code-y font.
88.5.1 Displaying
88.5.1.1 Inline
Say we just want to indicate that something is code, without actually providing the full section it came from, let alone run it.
To display a bit of code inline with the rest of our text, we can wrap the code with a pair of backticks, ``.
For example, we can write this with `this`
88.5.2 Running
To run R code in our R Markdown file, we need to insert a code chunk.
We can do so with the following keyboard shortcuts:
-
Cmd+Option+Ion Mac -
Ctrl+Alt+Ion Windows and Linux
From there, we can fill the code chunk with our code.
For example,
This:
```{r}
x <- 1
```
Yields this:
x <- 188.5.3 Chunk options
There are some commong chunk options we make use of to adjust what we want to happen when we compile, or knit, our R Markdown documents.
By default, any output from our code chunks will be shown in the document once knit. What if we don’t want the code itself to show, only the output? Then we can use the echo option.
For example, this:
```{r, echo=F}
x <- 1
x
```
Yields this:
#> [1] 1We can also have only the code show, but no output, using the eval option.
For example, this:
```{r, eval=F}
x <- 1
x
```
Yields this:
x <- 1
xMore code chunk options can be found here.