Skip to main content

Summer R Bootcamp

Module 11

 

R Markdown Files

R Markdown provides an easy way to produce a rich, fully-documented reproducible analysis. It combines your code, results, commentary, and all metadata needed to reproduce your analysis in R. It allows to include chunks of code in the file along with text. R Markdown supports many output formats such as PDF, Word, slideshows, presentations etc.

R Markdown files can be used in many ways. For instance, it can be utilized for communicating to decision makers, who wants to focus on the conclusions, not the code behind the analysis; for collaborating with other data analysts, who are interested in both your conclusions and how your reached them. In addition, it can be used as an environment in which we do analysis.

Even these modules are written using R Markdown files. In this module we will learn how to create an R Markdown file and its basic functionalities.

Creating R Markdown Files

R Markdown files have .Rmd extensions. To create R Markdown files, you need the rmarkdown package. But you don’t need to explicitly install and load this package, as RStudio automatically does both when needed.

You can create a new R Markdown file with File > New File > R Markdown… (on the top panel; top left corner)

As mentioned earlier, R Markdown can produce files of various formats (PDF, Word, HTML etc.). In this bootcamp, we will focus on the PDF output format. PDF output format requires installing LaTex distribution on your machine. There are several traditional options including MikTeX, MacTeX, and TeX Live, but it is recommended to use TinyTeX.

You can install TinyTeX with the R package tinytex. Run the following code in your console:

tinytex:: install_tinytex()

R Markdown File Components

YAML

The top part of the R Markdown file is called the YAML header. It is surrounded by --s and it stores the metadata needed for the document (for example, file title, author, output format etc.)

Text Formatting with Markdown

Fonts

Markdown is designed to be easy to read, write, and learn. Below you can find the basic guide that will help you format texts in your document:

  • If you need to type a plain text, do it like in a word document (just type it).

  • Use the ** ** operator to change the font type to bold. For instance, Hello was typed as **Hello**.

  • Use the _ _ operator to use italics font. For example, Hello was typed as _Hello_.

  • Use the ~~ ~~ operator to cross the words out. For example, Hello was typed as ~~Hello~~.

Headers

You can create headers in your text using # operator and control their size by simply adding one or more # in front of the text you would like to denote the header.


# Top Level Header (For example, Question 1)

## Second Level Header (For example, Question 1 part a)

### Third Level Header

#### and so on
Block Quotes

You can create a block quote using > operator. For example the line below


> Your first block quote

will produce the following result:

Your first block quote

Lists

In R Markdown you can create both ordered and unordered lists. To create an unordered list, use * operator:

* Bullet point 1

* Bullet point 2

  * bullet point 2a

  * bullet point 2b
  • Bullet point 1
  • Bullet point 2
    • bullet point 2 a
    • bullet point 2 b

To create an ordered lists, simply use numbers:

1. Bullet point 1

2. Bullet point 2
   * bullet point 2a
   * bullet point 2b
  1. Bullet point 1
  2. Bullet point 2
    • bullet point 2a
    • bullet point 2b
Tables

Use the following formatting style to create tables in R Markdown:

First Header  | Second Header
------------- | -------------
Content Cell  | Content Cell
Content Cell  | Content Cell
First Header Second Header
Content Cell Content Cell
Content Cell Content Cell
Inline Equations

Use $ $ operator to include equations in your text. For example, \(A = \pi*r^{2}\) was typed as $A = \pi*r^{2}$.

Line Breaks

In order to start a new paragraph or new line, you will need to be sure that white space exists between the two paragraphs/line:

This is the first lines.


And here we have another line.

This is the first lines.

And here we have another line.

Another useful way to divide up different parts of your file is by including horizontal lines. We can achieve it by using *** operator:

***

It will produce the horizontal line below.

Finally, if you want start a paragraph or a line on a new page, use \newpage command:

\newpage

R Chunks of Code

In addition to a plain text, you can also run R codes inside the file and include them in it along with the plain text to show what code you used to produce the results.

You can run and include the R code by manually typing the chunk deliminiters ```{r} and ```. It will display the code you used and the results that this code produced. For example, the following chunk will run the code specified inside of it and will produce corresponding output:

```{r}

print(2 + 2)

``` 
#> [1] 4
Options

Chunk can be customized with options, that is, arguments supplied to chunk header. There are nearly 60 options that you can use to customize your code, but in this module we will discuss the most important and commonly used options:

  • eval = FALSE prevents code from being evaluated. As a results, the code will not run and no results will be produced. This is useful for displaying example code.
```{r, eval = FALSE}
print(2 + 2)
```
  • include = FALSE runs the code, but doesn’t show the code or results in the final document.
```{r, include = FALSE}
print(2 + 2)
```
  • echo = FALSE prevents code, but not the results from appearing in the finished file.
```{r, echo = FALSE}
print(2 + 2)
```
  • results = 'hide' prevents results, but not the code from appearing in the finished file.
```{r, results = 'hide'}
print(2 + 2)
```

Generating R Markdown Files

Once you are done with the text and code that you want to include in your file, you can generate R Markdown files by clicking knit button on the top of the editor pane. It has a drop-down menu and allows you to pick output formats. It is recommended to use HTML format while you are preparing the file and fixing error. It will display the file in the Viewer tab nicely and conveniently. When you finalize your code and text, you can generate your file by clicking knit button once again and selecting PDF output format.

Additional Resources

We discussed basic and crucial parts of R Markdown files such as creating, formatting, and generating files. Of course, R Markdown allows you to do much more. Unfortunately, this is beyond the scope of this bootcamp and we don’t have enough time to cover all topics. In case you are interested in exploring this topic further, below you can find a list of useful links and resources.