15 R Markdown documents
R Markdown documents (.Rmd) are a special kind of Markdown document that lets you insert chunks of code. When knitted, they are turned into another file with the code chunk replaced by nicely formatted code and its output.
The output code be what appears in your console if you were to run the code, or it could be a table or figure. Code chunks can contain many types of code, including R code.
R Markdown documents can be knitted to a variety of file types including Markdown, (.md), web page (.html), PDF (.pdf), Microsoft Word (.docx), and many more.
15.1 Components of an R Markdown document
There are three main components to an R Markdown document:
- A YAML header
- Narrative text
- Chunks of R code that R will run when you “knit” the document
Let’s look at each component in more depth.
15.1.1 YAML header
You will notice some header information at the top, between two sets of three dashes, that looks like this:
When you knit the document, R will use the title as the page title and will put the author and date on the next line.
Notice that instead of writing the date in text, there is some R code. This is called inline R code in an R Markdown document. When you want to insert something generated by R into your text, you can use this kind of code. Inline code should start with a backtick and the letter r `r and end with another backtick `. Here is another example of inline code:
One plus one is
2
When R knits that it will appear as
One plus one is 2
15.1.2 Narrative text
This includes thinks like paragraphs of text, headings, lists, quoted text, etc. Think of this as the body of the report.
This is written in the Markdown language, a simple way to tell places like R and GitHub how it should look on the screen.
You can learn more about how to format your text in Markdown using these resources:
- In the Go to the Help menu in RStudio and select Markdown Quick Reference
- Basic Syntax on the Markdown Guide website
The new version of RStudio (version 1.4) has a very handy WYSIWYG (what you see is what you get) editor for R Markdown which allows you to write R Markdown documents like a word processor like Microsoft Word. To make use of this, download and install the newest version of RStudio.
15.1.3 Code Chunks
Code chunks are bits of R code that are executed when you knit the document. In the resulting Markdown (or other type) of document, the code is replaced by its output, which usually consist of text, tables or figures.
15.1.3.1 Parts of a code chunk
A code chunk looks like the following:
```{r chunk-name-with-no-spaces}
```Always put a blank line before a code chunk to separate it from the preceding text, otherwise knitr will think it is just a continuation of the previous content and will not render it correctly.
The three backticks at the beginning and end, like this, ``` indicate where the chunk begins and ends.
Inside the curly braces {} the first word indicated what kind of code to expect and the next word is the name of the code chunk, which may not contain spaces. Names are not required, but they can be useful can be useful for advanced knitting options and debugging errors when you try to knit your document. If you don’t want to give your chunk a name, just end the curly brackts like this: {r}
Code goes between the beginning and ending lines, for example:
```{r print-x}
x <- 1 # x gets a value of 1
x # print the value of x
```Anything you can write in an R script, you can write in an R code chunk, including comments, as seen above.
15.1.3.2 Chunk arguments
You can modify the way the chunk gets turned into code or figures using chunk arguments.
For example, the argument eval=FALSE will prevent R from evaluating the code. In the output document, the code will be shown but no output will be produced.
To add a chunk argument, put a comma after the language or chunk name, if there is one, and the name of the argument followed by an equal sign and the value for the argument. Spaces can be added but are not required. Many arguments require TRUE or FALSE as values, and these must be in all caps.
```{r show-code-only, eval=FALSE}
x <- 1 # x gets a value of 1
x # print the value of x
```An alternative way to set arguments in RStudio is to click the gear icon on the right side of a code chunk.
For more information, read about Options on the knitr website.
15.1.3.3 Run a code chunk
You can run code in an R chunk in two ways:
Like you do in an R script: place your cursor on a line or highlight several lines and use the keyboard shortcut Ctrl+Enter / Cmd+Return
Run the entire chunk: Go to the Run menu in the source window toolbar and select an appropriate option like Run Current Chunk. There are also options for running all previous chunks
15.2 Knitting
When you are ready to have RStudio create the final product from your R Markdown document, click the Knit button on the source tab toolbar (it looks like a ball of blue yarn with a needle).
RStudio will switch to the R Markdown tab in the bottom left pane. If it finds no errors in the document, a preview window will pop up showing you approximately what the final product will look like. Check it over to make sure it looks fine. Note that links to other documents will likely not work at this stage.