What is R Markdown?

If you didn’t know about R Markdown and you want to create a document that included text and computer output (graphs, numerical calculations, etc.), you would likely create the computer output in some software and then copy and paste things into a word processor like Word or Google Docs. This is relatively easy, but …

Copy and paste is not a worklow!

Any time you change a calculation or a figure, you need to copy and paste all over again. This is laborious and error prone. Furthermore, unless you keep separate notes, you will have no record of what you did. It would be much nicer if the document could redo that work for you and contained a record of all the steps involved. That’s just what happens when you use R Markdown.

Strucuture of an R Markdown File

R Markdown files have 3 types of chunks.

  1. The YAML header (YAML = Yet Another Markup Language)

    The YAML header is the first few lines of the file and it explains how the file is to be processed and sets some default values for things like figure sizes. Edit this carefully. If you break this part you will get an error message mentioning YAML and nothing will work. If you use the template, you will see places to put in your name and the assignment. Mostly, you can leave the rest alone.

  2. Text Chunks

    This is where you type “regular” text. Actually, you can be a little bit fancier. The markdown part of R Markdown provides a simple way to create things like bold, italics, section headers, mathematical notation, etc. For example, to put something in italics or bold, you surround it with one or two asterisks like this: *italics* or **bold**.

    Here’s a longer example.

    Some text with **bold** and *italics* and even some mathematics: 
$f(x) = \int_0^x t^2 \; dt$.

    becomes

    Some text with bold and italics and even some mathematics: \(f(x) = \int_0^x t^2 \; dt\).

    For more on mathematical notation in R markdown, see this document: [HTML] [PDF]

  3. R Chunks (or more generally code chunks – you can use C++, python, SQL, etc.)

    In between the text chunks, you can insert R chunks. These chunks contain R code. When the file is processed, these chunks are run and the code and results are inserted into the document.1 Processing an R Markdown file is called knitting because it knits together the text, R code, and R output into a single document.

    You can produce HTML, PDF, Word, or Powerpoint documents from R Markdown. (But be warned, if you subsequently edit those documents, the R Markdown document won’t know about it, and your workflow will be broken again.)

Creating an R Markdown Document in RStudio

Creating an R Markdown document in RStudio is pretty easy.

  1. Choose File > New File > R Markdown

  2. In the ensuing menu, select From Template and Template for Stat 343 Homework.

  1. This will open up a new R Markdown file in an editor.

    You now have a complete R Markdown document. If you hit the knit button (looks like a ball of yarn with needles in it), the chunks will be knit together.

Editing your R Markdown Document

  1. YAML header

    You will want to edit (carefully) the author and title fields of the YAML header. The rest of the YAML header you can leave be for now.

  2. Text

    The text chunks have a white background. You can type any text you like in these sections.

  3. R

    The R chunks have a gray background. In these chunks, you may write R code.

    To add a new R chunk, place your cursor on an empty line and choose Insert > R.

You’re (mostly) good to go

That’s really all there is to it for starters. But there are a few otehr things you might like to know.

Setting the preview location

The default in RStudio is to open a new window with the HTML document each time you knit. I prefer to have it show up in the viewer tab. If you want this behavior, choose Tools > Global Options > R Markdown and choose the preview location of your choice from the drop down menu.

There are many other options you can set here too. Feel free to look around.

Choosing output type

Next to the knit button is a little triangle. Click on that to choose between HTML and PDF or Word. I like to create documents in HTML because the preview is easier, then make a PDF at the end because the output is nicer.

There are some other output types as well (like powerpoint and other types of slide decks), but they require a different choice when initially creating the file.

Running your code “locally”

You can run code in an individual code chunk without knitting the document. Just push the play button. This is useful for debugging. The results are shown right inside your document.

But there is a small catch. This code is run in the console and in the order you click. When you knit the document, the code is run in a fresh environment and in the order of the file. So it is possible to get different results – especially if you computed things in the console that are not computed in your R Markdown document.

This is a good feature. We want our documents to be self-contained and reproducible. If they depended on the console, each time we knit the document, we might get a different result.

There is also a Run menu that gives you the option to run all the chunks in your document. If you clear your environment (little broom in the environment tab) and then run all the chunks in your document, that is pretty similar to knitting, but runs in the console in case you want to interact with things a bit.

Footnotes

  1. You can optionally hide the code and/or the output. For a class it is good to show both. If you are writing a report for a client, you will usually hide the R code and only show the results.↩︎