Rendering in R Studio

Assuming you have the document you’re working on open in the text editor, click the button that says “knit”.

Rendering in R without using R Studio

See the render command in the package rmarkdown.

Paragraph Breaks and Forced Line Breaks

To insert a break between paragraphs, include a single completely blank line.

To force a line break, put two blank
spaces at the end of a line.

To insert a break between paragraphs, include a single completely blank line.

To force a line break, put _two_ blank  
spaces at the end of a line.

Headers

The character # at the beginning of a line means that the rest of the line is interpreted as a section header. The number of #s at the beginning of the line indicates whether it is treated as a section, sub-section, sub-sub-section, etc. of the document. For instance, Basic Formatting in R Markdown above is preceded by a single #, but Headers at the start of this paragraph was preceded by ###. Do not interrupt these headers by line-breaks.

Italics, Boldface

Text to be italicized goes inside a single set of underscores or asterisks. Text to be boldfaced goes inside a double set of underscores or asterisks.

Text to be _italicized_ goes inside _a single set of underscores_ or *asterisks*.  Text to be **boldfaced** goes inside a __double set of underscores__  or **asterisks**.

Quotations

Set-off quoted paragraphs are indicated by an initial >:

In fact, all epistemological value of the theory of probability is based on this: that large-scale random phenomena in their collective action create strict, nonrandom regularity. [Gnedenko and Kolmogorov, Limit Distributions for Sums of Independent Random Variables, p. 1]

> In fact, all epistemological value of the theory of probability is based on this: that large-scale random phenomena in their collective action create strict, nonrandom regularity.  [Gnedenko and Kolmogorov, _Limit Distributions for Sums of Independent Random Variables_, p. 1]

Computer Type

Text to be printed in a fixed-width font, without further interpretation, goes in paired left-single-quotes, a.k.a. “back-ticks”, without line breaks in your typing. (Thus R vs. R.) If you want to display multiple lines like this, start them with three back ticks in a row on a line by themselves, and end them the same way:

Text to be printed in a fixed-width font, without further interpretation,
goes in paired left-single-quotes, a.k.a. "back-ticks", without line breaks
in your typing.  (Thus `R` vs. R.)

Bullet Lists

• This is a list marked where items are marked with bullet points.
• Each item in the list should start with a * (asterisk) character, or a single dash (-).
• Each item should also be on a new line.
  • Indent lines and begin them with + for sub-bullets.
  • Sub-sub-bullet aren’t really a thing in R Markdown.

Numbered lists

1. Lines which begin with a numeral (0–9), followed by a period, will usually be interpreted as items in a numbered list.
2. R Markdown handles the numbering in what it renders automatically.
3. This can be handy when you lose count or don’t update the numbers yourself when editing. (Look carefully at the .Rmd file for this item.)
   1. Sub-lists of numbered lists, with letters for sub-items, are a thing.
   2. They are however a fragile thing, which you’d better not push too hard.

Title, Author, Date, Output Format, Table of Contents

You can specify things like title, author and date in the header of your R Markdown file. This goes at the very beginning of the file, preceded and followed by lines containing three dashes. Thus the beginning of this file looks like so:

---
title: Using R Markdown for Class Reports
author: A Student
date: 12 January 2018
---

You can also use the header to tell R Markdown whether you want it to render to HTML (the default), PDF, or something else. To have this turned into PDF, for instance, I’d write

---
title: Using R Markdown for Class Reports
author: A Student
date: 12 January 2018
output: pdf_document
---

Adding a table of contents is done as an option to the output type.

---
title: Using R Markdown for Class Reports
author: A Student
date: 12 January 2018
output:
  html_document:
    toc: true
---

• To create PDF, a program called LaTeX (see below) has to be installed on your computer. LaTeX is already installed on RStudio Cloud.
• Other output formats may be available. See help(render) in the rmarkdown package.
• There are many, many other formatting options which can be given in the header; see the main R Markdown help files online.

Hyperlinks

Hyperlinks anchored by URLs are easy: just type the URL, as, e.g., to get the source file for this document.

Hyperlinks anchored to text have the anchor in square brackets, then the link in parentheses.

[anchor in square brackets, then the link
in parentheses]()

Images

Images begin with an exclamation mark, then the text to use if the image can’t be displayed, then either the file address of the image (in the same directory as your document) or a URL. Here are two examples, one for an image in the directory and one for a URL.

![A local image](r-project.png)


![A remote image](https://upload.wikimedia.org/wikipedia/commons/b/ba/Sagrada_Familia_nave_roof_detail.jpg)

There doesn’t seem to be a way of re-sizing images using these Markdown commands. Since you are using R Markdown, however, you can use the following hack:

```{r, fig.retina=NULL, out.width=100, echo=FALSE}
knitr::include_graphics("https://upload.wikimedia.org/wikipedia/commons/b/ba/Sagrada_Familia_nave_roof_detail.jpg")
```

This calls an R command included in the knitr package, with some options about how the R is run (described below).

Code Chunks and Their Results

A code chunk is simply an off-set piece of code by itself. It is preceded by ```{r} on a line by itself, and ended by a line which just says ```. The code itself goes in between. Here, for instance, is some code which loads a data set from a library, and makes a scatter plot.

```{r}
library(tidyverse)
library(mdsr)
SAT_2010 %>% ggplot(aes(write,..density..)) + geom_histogram() + geom_density() + theme_minimal() + labs(title = "SAT Writing Scores")
```

library(tidyverse)
library(mdsr)
SAT_2010 %>% ggplot(aes(write,..density..)) + geom_histogram() + geom_density() + theme_minimal() + labs(title = "SAT Writing Scores")

First, notice how the code is included, nicely formatted, in the document. Second, notice how the output of the code is also automatically included in the document. If your code outputs numbers or text, those can be included too:

knitr::kable(head(SAT_2010))

Inline Code

Code output can also be seamlessly incorporated into the text, using inline code. This is code not set off on a line by itself, but beginning with `r and ending with `. Using inline code is how this document knows that the SAT_2010 data set contains 50 rows (contains 50 rows), and that the median SAT writing score was 511.5 (511.5).

Notice that inline code does not display the commands run, just their output.

Seen But Not Heard

Code chunks (but not inline code) can take a lot of options which modify how they are run, and how they appear in the document. These options go after the initial r and before the closing } that announces the start of a code chunk. One of the most common options turns off printing out the code, but leaves the results alone: ```{r, echo=FALSE}

Another runs the code, but includes neither the text of the code nor its output. ```{r, include=FALSE} This might seem pointless, but it can be useful for code chunks which do set-up like loading data files, or initial model estimates, etc.

Another option prints the code in the document, but does not run it: ```{r, eval=FALSE} This is useful if you want to talk about the (nicely formatted) code.

Tables

The default print-out of matrices, tables, etc. from R Markdown is frankly ugly. The knitr package contains a very basic command, kable, which will format an array or data frame more nicely for display.

Compare:

coefficients(summary(lm(write ~ salary, data = SAT_2010)))

##                  Estimate   Std. Error   t value     Pr(>|t|)
## (Intercept) 600.018506474 3.780370e+01 15.871950 9.930929e-21
## salary       -0.001445845 6.841402e-04 -2.113376 3.979291e-02

with

library(knitr) # Only need this the first time!
kable(coefficients(summary(lm(write ~ salary, data = SAT_2010))))

— Of course, R’s defaults print out a crazy number of decimal places, but this isn’t the time to discuss significant digits, or the signif function.

“Caching” Code Chunks (Re-Running Only When Changed)

By default, R Markdown will re-run all of your code every time you render your document. If some of your code is slow, this can add up to a lot of time. You can, however, ask R Markdown to keep track of whether a chunk of code has changed, and only re-run it if it has. This is called caching the chunk.

lm(write ~ salary, data = SAT_2010)

## 
## Call:
## lm(formula = write ~ salary, data = SAT_2010)
## 
## Coefficients:
## (Intercept)       salary  
##  600.018506    -0.001446

One issue is that a chunk of code which hasn’t changed itself might call on results of earlier, modified chunks, and then we would want to re-run the downstream chunks. There are options for manually telling R Markdown “this chunk depends on this earlier chunk”, but it’s generally easier to let it take care of that, by setting the autodep=TRUE option.

1. If you load a package with the library() or require() commands, R Markdown isn’t smart enough to check whether the package has changed (or indeed been installed, if you were missing it). So that won’t trigger an automatic re-running of a cached code chunk.
2. To manually force re-running all code chunks, the easiest thing to do is to delete the directory R Markdown will create (named something like filename_cache) which it uses to store the state of all code chunks.

Setting Defaults for All Chunks

You can tell R to set some defaults to apply to all chunks where you don’t specifically over-ride them. Here are the ones I generally use:

# Need the knitr package to set chunk options
library(knitr)

# Set knitr options for knitting code into the report:
# - Don't print out code (echo)
# - Save results so that code blocks aren't re-run unless code changes (cache),
# _or_ a relevant earlier code block changed (autodep), but don't re-run if the
# only thing that changed was the comments (cache.comments)
# - Don't clutter R output with messages or warnings (message, warning)
  # This _will_ leave error messages showing up in the knitted report
opts_chunk$set(echo=FALSE,
               cache=TRUE, autodep=TRUE, cache.comments=FALSE,
               message=FALSE, warning=FALSE)

This sets some additional options beyond the ones I’ve discussed, like not re-running a chunk if only the comments have changed (cache.comments = FALSE), and leaving out messages and warnings. (I’d only recommend suppressing warnings once you’re sure your code is in good shape.) I would typically give this set-up chunk itself the option include=FALSE.

You can over-ride these defaults by setting options for individual chunks.

More Options

See [http://yihui.name/knitr/options/] for a complete listing of possible chunk options.

Elements of Math Mode

• Most letters will be rendered in italics (compare: a vs. a vs. \(a\); only the last is in math mode). The spacing between letters also follows the conventions for math, so don’t treat it as just another way of getting italics. (Compare speed, in simple italics, with \(speed\), in math mode.)
• Greek letters can be accessed with the slash in front of their names, as \alpha for \(\alpha\). Making the first letter upper case gives the upper-case letter, as in \Gamma for \(\Gamma\) vs. \gamma for \(\gamma\). (Upper-case alpha and beta are the same as Roman A and B, so no special commands for them.)
• There are other “slashed” (or “escaped”) commands for other mathematical symbols:
  • \times for \(\times\)
  • \cdot for \(\cdot\)
  • \leq and \geq for \(\leq\) and \(\geq\)
  • \subset and \subseteq for \(\subset\) and \(\subseteq\)
  • \leftarrow, \rightarrow, \Leftarrow, \Rightarrow for \(\leftarrow\), \(\rightarrow\), \(\Leftarrow\), \(\Rightarrow\)
  • \approx, \sim, \equiv for \(\approx\), \(\sim\), \(\equiv\)
  • See, e.g., http://web.ift.uib.no/Teori/KURS/WRK/TeX/symALL.html for a fuller listing of available symbols. (http://tug.ctan.org/info/symbols/comprehensive/symbols-a4.pdf lists all symbols available in LaTeX, including many non-mathematical special chracters)
• Subscripts go after an underscore character, _, and superscripts go after a caret, ^, as \beta_1 for \(\beta_1\) or a^2 for \(a^2\).
• Curly braces are used to create groupings that should be kept together, e.g., a_{ij} for \(a_{ij}\) (vs. a_ij for \(a_ij\)).
• If you need something set in ordinary (Roman) type within math mode, use \mathrm, as t_{\mathrm{in}}^2 for \(t_{\mathrm{in}}^2\).
• If you’d like something set in an outline font (“blackboard bold”), use \mathbb, as \mathbb{R} for \(\mathbb{R}\).

• For bold face, use \mathbf, as

  (\mathbf{x}^T\mathbf{x})^{-1}\mathbf{x}^T\mathbf{y}

  for \[ (\mathbf{x}^T\mathbf{x})^{-1}\mathbf{x}^T\mathbf{y} \]
• Accents on characters work rather like changes of font: \vec{a} produces \(\vec{a}\), \hat{a} produces \(\hat{a}\). Some accents, particularly hats, work better if they space out, as with \widehat{\mathrm{Var}} producing \(\widehat{\mathrm{Var}}\).
• Function names are typically written in romans, and spaced differently: thus \(\log{x}\), not \(log x\). LaTeX, and therefore R Markdown, knows about a lot of such functions, and their names all begin with \. For instance: \log, \sin, \cos, \exp, \min, etc. Follow these function names with the argument in curly braces; this helps LaTeX figure out what exactly the argument is, and keep it grouped together with the function name when it’s laying out the text. Thus \log{(x+1)} is better than \log (x+1).

• Fractions can be created with \frac, like so:

  \frac{a+b}{b} = 1 + \frac{a}{b}

  produces \[ \frac{a+b}{b} = 1 + \frac{a}{b} \]

• Sums can be written like so:

  \sum_{i=1}^{n}{x_i^2}

  will produce \[ \sum_{i=1}^{n}{x_i^2} \] The lower and upper limits of summation after the \sum are both optional. Products and integrals work similarly, only with \prod and \int: \[ n! = \prod_{i=1}^{n}{i} \] \[ \log{b} - \log{a} = \int_{x=a}^{x=b}{\frac{1}{x} dx} \] \sum, \prod and \int all automatically adjust to the size of the expression being summed, producted or integrated.

• “Delimiters”, like parentheses or braces, can automatically re-size to match what they’re surrounding. To do this, you need to use \left and \right, as

  \left( \sum_{i=1}^{n}{i} \right)^2 = \left( \frac{n(n-1)}{2}\right)^2 = \frac{n^2(n-1)^2}{4}

  renders as \[ \left( \sum_{i=1}^{n}{i} \right)^2 = \left( \frac{n(n-1)}{2}\right)^2 = \frac{n^2(n-1)^2}{4} \]
• To use curly braces as delimiters, precede them with slashes, as \{ and \} for \(\{\) and \(\}\).

• Multiple equations, with their equals signs lined up, can be created using eqnarray, as follows.

  \[
  \begin{eqnarray}
  X & \sim & \mathrm{N}(0,1)\\
  Y & \sim & \chi^2_{n-p}\\
  R & \equiv & X/Y \sim t_{n-p}
  \end{eqnarray}
  \]

\[ \begin{eqnarray} X & \sim & \mathrm{N}(0,1)\\ Y & \sim & \chi^2_{n-p}\\ R & \equiv & X/Y \sim t_{n-p} \end{eqnarray} \] Notice that & surrounds what goes in the middle on each line, and each line (except the last) is terminated with \\. The left or right hand side of the equation can be blank, and space will be made:

\[
\begin{eqnarray}
P(|X-\mu| > k) & = & P(|X-\mu|^2 > k^2)\\
& \leq & \frac{\mathbb{E}\left[|X-\mu|^2\right]}{k^2}\\
& \leq & \frac{\mathrm{Var}[X]}{k^2}
\end{eqnarray}
\]

\[ \begin{eqnarray} P(|X-\mu| > k) & = & P(|X-\mu|^2 > k^2)\\ & \leq & \frac{\mathbb{E}\left[|X-\mu|^2\right]}{k^2}\\ & \leq & \frac{\mathrm{Var}[X]}{k^2} \end{eqnarray} \]

(In full LaTeX, \begin{eqnarray} automatically enters math mode, but R Markdown needs the hint.)

Translating Math into LaTeX

LaTeX is designed so that every part of a mathematical expression has a reasonably straightforward counterpart in what you write. Still, it can be a bit intimidating at first. What many people find useful to to start by taking some page of printed or hand-written math and then deliberately translate that, line by line, into LaTeX, and then rendering it to see whether it came out right (and, if not, where to fix things). If you need to do any math for an assignment, it can be a good idea to write the math out by hand, and then turn it into LaTeX, whether the class requires it (like this one) or not. Eventually, with practice, the translation will become quite automatic, and some people even do new math by writing out the LaTeX.

LaTeX Does Not Check Correctness

LaTeX does not check whether your math is right; it just checks whether it can figure out what you’re trying to say well enough to type-set it. Thus for instance it has no problem at all with the following:

\[ \begin{eqnarray} (n+1)(n-1) & = & n^2\\ n^2 -1 & = & n^2\\ -1 & = & 0\\ 1 & = & 0\\ -1 & = & 1 \end{eqnarray} \]

(There are computer programs for doing symbolic mathematics which, in effect, do check whether your math is right, at least if you’re working in the sub-area of math they’re designed to handle. So far as I know, no one has ever really combined them with LaTeX.)

Installing LaTeX

If you are producing a PDF report on RStudio Cloud then you can skip this section.

If you render your R Markdown document to HTML, you do not need to install LaTeX on your computer. This is because the HTML includes instructions to browsers, which say (as it were) “Send the funny-looking bits with all the slashes to mathjax.org, and it will send you back pretty pictures of equations”. The website actually runs the LaTeX.

If you want to produce PDF on your own computer then you need to install LaTeX. How you actually do this depends on the precise kind of computer. For Macs, I recommend using the MacTeX package, available from https://tug.org/mactex/mactex-download.html. For other systems, follow the links from http://www.tug.org/begin.html.

Acknowledgments

This document borrows heavily from Prof. Cozma Shalizi’s Using R Markdown for Class Reports.

R Markdown source for this page