Saturday, April 14, 2018

M is for R Markdown Files

Today's A to Z of R will be a bit different from previous ones in that the focus is not on how to code something in R, but how to use a feature in R Studio to create documents, such as HTML and PDF. Either of these types of documents - and others - can be easily created thanks to R Markdown files. In this post, I'll show you how to set up your computer and R Studio so that you can create an R Markdown file and "knit" it into a PDF or HTML document. In the future, I'd love to dig into some of the other types of documents you can create with Markdown - from Shiny apps to ebooks. And as an added example, almost all of my posts this month have been created with an R Markdown file knitted into HTML.

Here's what you need to install to get started: if you haven't been using R Studio, you'll want to install it now. Don't worry - it's free for individual users. You'll also want to install pandoc, and a TeX system, such as MiKTeX or MacTeX. (Also free to install.) In R, you'll want to install the rmarkdown package; you'll also need the knitr package, which should have come with your install of R Studio. You can easily verify whether a package is installed in R Studio by clicking on the Packages tab in the lower right corner.


If you need to install a package, you can do so with install.packages("packagename"). Note that package names are case sensitive.

Once you're finished installing everything, open R Studio and create a new R Markdown document. On the far left, just below the menu, is a button that looks like a blank page with a plus sign on it and a black down arrow next to it. Click on the arrow and select R Markdown.


You'll see this dialogue box pop up.


We'll start by creating an HTML document - note that you can easily switch to another file type. At the top of the new R Markdown file, you can update title, author, and date. It's also currently set for an output of HTML document. But we could switch that to PDF if we'd like. Let's stick with HTML for now.

Code chunks appear as grey boxes that begin with ```{r. This where you type in any R code, at the point in the document you want the code and/or output to appear. Each R code chunk can be given a descriptive name. Leave the first R code chunk alone - this is setup for when you knit the final document together.

Under that, you can begin typing the information for your document. For plain text, just type. Text with # signs in front of it will appear as headers. The level of the header is equal to the number of # signs, so a level 1 header (the largest) is created with 1 #, level 2 with ##, and so on up to 6.

Bulleted lists are created with asterisks * for level 1 items and pluses + for level 2. Create an ordered list by simply typing in the numbers and adding line breaks at the end of each item.

Add inline equations by putting a $ on each side and equation blocks with $$. R Markdown will also replace text names of mathematical symbols, such as pi, with the actual symbol.

You can create tables with ASCII characters | and - to create the borders, and the tables will be formatted automatically, and much more prettily. Or you can create your tables with R code and add in commands to format it.

But really, let's get into the best part about R Markdown, which is that you can include your code and output automatically. Add new code chunks where you want them to go by placing your cursor at that point in the document, then clicking Insert just above the R Markdown document.


Any code you type in the code chunk will automatically appear along with any output it produces. If you only want output, but no code, add , echo = FALSE after the name of the R code chunk. And if you want code but no output, type it in as plain text but add ` on either side of the code.

Some R packages automatically give you warnings, such as when a function of one package is being masked from another, which happened when I loaded the QuantPsyc package. I can hide those from my final R Markdown file by adding , warning=FALSE after the name of the R code chunk.

These are the features I use most frequently in R Markdown, but you can get all of this and more on the R Markdown Cheatsheet.

I've created an example R Markdown file and a version rendered into HTML, which recreates the analyses I performed in the B is for Beta post. After I finished creating my document, I rendered it into an HTML file by clicking the Knit button.


Then published it by clicking on the publish button, which looks a little like a blue eyeball. Note that you'll need to create an account on rpubs.com and that anything you publish will be public.

But I could very easily render it into a PDF as well, by clicking on the black down arrow next to knit and selecting PDF document. If you'd like to see what that looks like, check it out here.

1 comment: