R Markdown

Students cheer on the Redhawks during a sporting event at Miami University.

R Markdown makes formatted documents, reports, and presentations in R. Regular text, headings, code, and output can all be included in the document. Rather than having to copy and paste code and images into a Word document or some other file, RMarkdown allows a user to create a complete report in a single environment. This means that formatting text to look like code, as well as other format types, can be made with little effort once you familiarize yourself with the R Markdown syntax. In addition, even though this is an R package, R Markdown can be used with Python or SQL

To begin a new R Markdown file, click File -> New File -> R Markdown. From the new window that appears, you can choose to create a document, a presentation, a Shiny app, or a custom template. We will be describing how to create a document in this tutorial, so we need to supply a title and author as well as select an output format. Upon clicking OK, you will then be given a default template where you are the author along with other standard settings and example elements already inserted into the document. To see what the default example looks like in html form, you can "Knit" it by clicking the Knit tab from the options bar. Because this is a new file, you will be prompted to save the file first. Upon saving the file, you will see code being processed in the Console of RStudio and then the rendered html appear in the Viewer window. Typically, when creating a new document you would leave the topmost setup content for the title, author, date, and output (commonly know as the yaml settings) alone and simply delete all of the example elements so you can supply your own content. Next, we will discuss some of the main parts of a document.

Document Parts

There are three different, though related, parts of an R Markdown file:

  • The YAML header (Yet Another Markup Language), which is seen at the top of the document. It needs, and only should be, supplied at the very beginning of the document. Though the title, author, and date are straight forward to edit and even delete if desired, the output setting can be sensitive to syntax error (meaning that the addition of spaces between characters and use of new lines of code can influence the results).
 ===
title: "RMarkdown"
author: "Center for Analytics and Data Science Miami University"
date: "9/12/2017"
output: html_document
===
  • R code chunks, which are inserted by typing three consecutive backticks before and after a chunk of code (the shortcut to insert a code chunk on Mac is option-Cmd-I, and on Windows is Ctrl-Alt-I). Note in the example below that in addition to the backticks there are a set of curly brackets after the first series of backticks. These are used to indicate options for code chunks. The example below is using {r } to indicate that we want R to run the code. That is, load the two R packages for our example. Had we not supplied the {r } option and only used the backticks, the document would simply display the text in between the backticks inside a code box.
 '''{r }
library(knitr)
library(xtable)
'''
  • The rest of the document is plain text or a use of R Markdown syntax for formatting plain text as headers, website links, bolded font. etc. Nothing special signifies a line of text, so any line that isn't marked as code chunks or a YAML header is automatically considered plain text. Also, since we are using an html format for the document then the code for internally visible comments is <!-- regular html comment -->

Different Nuances of R Markdown

Here are a few of of the nuances of R Markdown:

  • To begin a new line in your document, put two spaces at the end of the previous line and press enter on your keyboard. Pressing enter again results in a blank line.
  • Italics are created with a star followed by text and another star (for example, *italics*)
  • Bold is denoted by two stars on each side instead of one (for example, **bold**)
  • Bullet points are created by starting a new line, then putting a star with a space followed by the text
    • Sub bullet points are created by starting a new line, hitting tab twice, then adding the star and space 
  • R code can be shown and run by using an R code chunk from the insert menu on the top right of this editor
    • The echo option can be set to TRUE or FALSE, which will either display the code used or conceal it
    • The eval option can be set to TRUE or FALSE, which will dictate whether the code should or should not be evaluated (i.e. run)
    • Simply using backticks without any {r } options is not the same as using {r eval=FALSE}. The latter will provide additional formatting of the text that resembles what you would actually see in R.

If you want to learn more of the functionalities in R Markdown, there is a cheat sheet in RStudio. You can click Help -> Cheat sheets -> R Markdown Cheat Sheet.

Embed

To insert an image into a document you use the following general syntax:

![Your Caption](C:\Filepath\To\Picture\PictureName.extension)

As an example, to insert a jpeg image such as the Miami logo shown below, you would state the caption inside the brackets and then provide the filepath to the image. Keep in mind that your R Markdown script will assume that the image will remain in this particular directory until you tell it otherwise. If you move the location of the image file, you will need to update the filepath in your script.

this is a Miami university logo

Two ways of making a table are shown below. Both of them use the xtable package, so be sure to download and install the package before using the following.

library(xtable)
kable(mtcars)

The html code to embed a YouTube video is below:

iframe width="Number" height="Number" src="URL" frameborder="Number" allowfullscreen/iframe

Need a Refresher?

Go back to the beginner tutorials.