6 Markdown

Writing code and the associated text around the analyses and your data is an odd job that munges together some programming skills, a lot of copy-and-paste, saving images, menu jujitsu (Insert \(\to\) Image \(\to\) From Computer…), etc. One of the things that we should strive to do is to minimize the amount of stoooopid work that we have to do in our daily lives, right? Markdown is a way to create textual output that can be magically turned into many types of output. In this section, we start looking at some markdown examples that integrate our data, analysis code, and output into a single document that makes our lives suck just a little bit less .

6.1 Markdown

Consider the case where you are making a report using a word processor like Word or Pages. The most basic part of that document is the actual text that you use in the document. Certain parts of that text represent different ‘landmarks’ in the paper, titles and headers are typically of a different typeface, images are saved from a different program, etc. If you are to include code, results from analyses, images of output and other stuff that isn’t directly typed into the document, you must do that outside the word processor and somehow insert it into that document. This moving between the processor where you are typing the actual content and other external sources of content and mushing them together is pretty much common place.

In addition to this work flow, at the end of the day you spend a lot of time working on presentation style. Images and tables moving between page breaks, manually renumbering equations and figures, trying to figure out where captions and figure legends go, and at the end of the day, making sure the statistical work that you did stays in sync with how you are presenting the output in the document. One change in your analysis may percolate to many changes throughout the document that you must manually fix. Perhaps more importantly though, at the end of the day, you are left with a single Word document. What if you want to take those analyses and make a presentation, poster, website, docbook, or pdf out of it? What if you want to make automatic reports on continuous data sources? You have to do this over and over again manually because you are stuck using a word processor that only makes one kind of output. Markdown was designed as a way to create content and display it in many different formats, from the same kind of source. It is a very simple way of creating content that allows you to present it in a wide variety of output formats.

Markdown is, at a bare minimum, just text. Anyone can write it using any editor you like. For our purposes, RStudio is a nice editor and the one we will use. A markdown file is saved with the extension .Rmd (or .rmd). To make a markdown document in RStudio, select File \(\to\) New File \(\to\) RMarkdown… and you will be give a dialog of potential types of markdown templates to start from that look like the following image. The main categories on the left are:

  • Document: This is the main category of documents you can prepare.
  • Presentation: You can make html and pdf presentations using markdown.
  • Shiny: Shiny is a way to make interactive graphics and data ‘dashboards’ in R that are hosted on a web server (free ones are available or you can host one on your own server if you have one).
  • Templates: This is where specific themed templates are stored for any of the above type of markdown document.

RMarkdown Dialog For the time being, lets stick with documents and keep the default setting for HTML. As noted in the dialog, we can switch to the other formats later without a problem and HTML output is perhaps the most versatile for using while we are creating the document.

6.2 Marking up Text

In a markdown document, it is all text. As such, we need to do typographic things like make headings, bold, italics, etc. Markdown accomplishes these by using symbols around the textual items you are changing. Here are some examples as an image (if I typed them into this document, which is RMarkdown, they would be converted so you wouldn’t see them).

There are a lot more markup options (footnotes, links, citations, etc.) that can be found by selecting Help \(\to\) Markdown Quick Reference in RStudio.

6.3 Inserting R Code Chunks

In markdown, code is contained with what is called a ‘chunk’. This chunk can be a block of code (encompassing some kind of data analysis or the creation of some kind of graphical output) or it can be a bit that is inserted inline with your text (e.g., something like P < 0.0323 may be computed and inserted on the fly).

You can insert a chunk of code by selecting the R option from the Insert menu just above the editor (see below). There is also a keyboard shortcut that can be used to insert a chunk without going to the menu (and it is much faster), though they are platform dependent.

Once you insert a chunk, RStudio provides a highlighted section within which you can insert your code. Everything within the chunk itself is going to be interpreted just as if it were written in a normal R script.

6.3.1 Chunk Options

There are several options you can specify that determine the behavior of the chunk. These are inserted within the curly brackets at the top of the chunk. Some of the more common ones include:

  • eval=TRUE/FALSE Determine if the code is actually run. Perhaps you are just demonstrating the code.
  • echo=TRUE/FALSE Determine if the code is shown in the output. We can hide a lot of code ‘behind the scenes’ in our documents and only provide the output as appropriate (e.g., you’d never show the code for the analysis in your manuscript but it can be embedded in the document directly and serve up the results when you compile it).
  • fig.cap="" Caption for figures and tables.
  • warning=TRUE/FALSE, message=TRUE/FALSE, error=TRUE/FALSE Toggle the visibility of warnings, messages, and errors in the output in the final document.

There are many additional options that can be found in the documentation for knitr (the package that actually does the magic of turning the markdown into something else) at http://yihui.name/knitr/options/

6.4 Variables in Text

Variables and values from the R code in your document can be inserted into the text as well. To do this, you enclose the R code you are using in between a backslash plus the letter r (“r") and a trailing backslash ("”). Here is an image of an example

and the output:

My all time favorite number is 8 and always has been.