What is R Markdown?

“R Markdown is a file format for making dynamic documents with R. An R Markdown document is written in markdown (an easy-to-write plain text format) and contains chunks of embedded R code.”

- Garret Grolemund from R Studio

R Markdown supports a variety of document formats and makes it easy to create amazing reports, presentation slides, or even websites to share your findings in R with others.

Why use R Markdown?

There are many benefits of using R Markdown.

First, it is a great way to incorporate your R code into a document. It not only shows your code to make it transparent, but also runs it as the document is rendered so that the resulting output is always true to the code. This is particularly useful when the code is used to compute certain key values or create tables/plots using data.

Second, R Markdown makes it easy to generate various formats of documents for the same contents–an HTML document, a PDF report, presentation slides, etc.–with little to no changes to the R Markdown script.

R Markdown’s ability to incorporate R code makes the rendered document and its content largely reproducible. If the data changes and we have to compute certain values again, we simply re-render the document using the modified data.

Finally, the report generating process can be largely automated with rmarkdown tools.

Getting started

To get started with R Markdown, we first have to install rmakrdown package. If you are using RStudio IDE (which you should), this is already taken care of.

Creating a new R Markdown file is easily done using RStudio IDE. Go to its menu bar, and click File > New File > R Markdown.

Onces we have our R Markdown file ready to be rendered, we “Knit” the R Markdown file into a document in the desired format.

The following screenshots show how this is done:

On the RStuido IDE menu, click “File > New File > R Markdown”.

Alternatively, you can click a button right below File menu, which is for creating a new file. When you clikc the button, you will see various options for a new file. Click “R Markdown”.

When you click “R Markdown”, you will see a small window for specifying a few options, including “Title”, “Author”, and “Default Output format”.

Onces you click “OK”, a new R Markdown script shows up on the script pane of RStudio IDE. Now we are ready to work on our R Markdown file!

R Markdown structure

Markdown basics

We will take a quick tour of markdown basics. More specifically, we will see the markdown syntax for the following elements:

• Headers
• Font types (italic, bold, strikethrough, superscript)
• Lists (ordered, unordered)
• Hyperlinks
• Images
• Blackquotes
• Horizontal line/page break
• Math equations (using LaTeX)
• Code/R code (chunk, in-line)

# Header 1

## Header 2

### Header 3

_italic_  __bold__

*italic*  **bold**


~~strikethrough~~


superscript^2^

Unordered list  |  Ordered list
                | 
* Item 1        |  1. Item 1
    * Item 1a   |      1. Item 1a
* Item 2        |  2. Item 2
    + Item 2a   |      1. Item 2a
    - Item 2b   |      2. Item 2b

Mixed list

1. Item 1
    * Item 1a
* Item 2
    1. Item 2a
    + Item 2b

[text with hyperlink](http://link.path)

![](http://image.path/example.png)

![optional caption text](image/example.png)

> A line of text following the "> " is a blockquote.

More then three asteriks or dashs

***

******

------

Inline math equations look like: $y = (x + 1)^2$

A block of math equations look like:

$$y = x^2 + 2x + 1$$

knitr options

knitr package offers various options to control the knitted output of code chunks. There are global options and local options.

# use the following to control global options
knitr::opts_chunk$set(eval = TRUE, echo = TRUE, ...)

Global options act as the default settings for the whole document. This can be specified using opts_chunk$set() function

_```{r eval = FALSE, echo = FALSE, ...}

Local options per code chunk are only applied to the specific code chunck. They can specified in the curly braces {} at the beginning of the code chunk. Local options overide the global options if relevant.

See here for full documentation of knitr chunk options.

Tables

There are often cases where we want to generate a table using R code and include it in the R Markdown output. There are different options for printing a table:

• Printing basic data frame object
• Proper (HTML) tables with knitr::kable()
• Interactive tables with DT::datatable()

my_table <- data.frame(
  my_fruits = c("apple", "banana", "clementine"),
  my_animals = c("dogs", "cats", "llamas"),
  my_flavors = c("chocolate", "vanila", "cookie dough"),
  my_colors = c("red", "green", "orange"),
  my_cities = c("Chicago", "New Work", "Los Angeles")
)

my_table

##    my_fruits my_animals   my_flavors my_colors   my_cities
## 1      apple       dogs    chocolate       red     Chicago
## 2     banana       cats       vanila     green    New Work
## 3 clementine     llamas cookie dough    orange Los Angeles

knitr::kable(my_table)

DT::datatable(my_table)

R Markdown output formats

R Markdown supports various output formats, including HTML, PDF, Microsoft Word, and more.

Output format can be specified using output in the YAML header. R Markdown is not limited to generate a single format for the given file. In order words, depending on the YAML output setting, the same file can be rendered in multiple formats.

Different output format has different YAML render options. Refer the page 2 of R Markdown cheat sheet on RStudio’s Cheat Sheets page for a full list.

R Notebooks

“An R Notebook is an R Markdown document with chunks that can be executed independently and interactively, with output visible immediately beneath the input.”
- “R Notebooks”, RStudio

While all other R Markdown formats requires “knitting” to see the final output, an R notebook document is automatically re-rendered each time the source file (.Rmd) is saved. This offers a more interactive workflow.

htmlwidgets for R

• There are many R packages (90+) for taking full advantage of the interactivity that web can offer.
• With these packages, we can easily incorporate interactive widgets into HTML documents generated using R Markdown
• Examples of htmlwidgets include:
  • plotly and highcharter for interactive visualizations
  • leaflet for interactive maps
  • DT for interactive data tables
• Visit htmlwidgets for R website to find out more

RPubs

“RPubs is a quick and easy way to disseminate data analysis and R code and do ad-hoc collaboration with peers.”
- RStudio Team

Publishing an R Markdown output on RPubs is as easy as clicking the “publish” button on RStudio. You may consider RPubs as something comparable to Tableau Public’s Gallery website, although there are some differences.

Click the image below to view what others have shared:

Creating presentation slides

RStudio supports many options for creating presentation slides that are both modern-looking and highly customizable.

Popular ways to create slides using R include:

• R Markdown formats:
  • ioslides_presentation (HTML)
  • revealjs::revealjs_presentation (HTML)
  • slidy_presentation (HTML)
  • beamer_presentation (PDF)
• R Presentation (HTML)

ioslides

---
title: "My first ioslide presentation"
output: ioslides_presentation
---

ioslides output format is built into RStudio. ioslides fully integrates R Markdown syntax. For example, creating new slides is as easy as using # and ## headings.

To learn more about ioslides, read the “Presentations with ioslides” article on RStudio.

---
title: "My first ioslide presentation"
author: Bobae Kang
date: April 18, 2018
output: ioslides_presentation
---
  
# First section


## Normal slide

- Item one
- Item two

## Another slide | With a subtitle

This slide has a two-column layout

----

![picture saying hello](images/hello.png)

revealjs

---
title: "My first revealjs presentation"
output: revealjs::revealjs_presentation
---

With revealjs R package, it is possible to use R Markdown (and its syntax) to generate slides using reveal.js, a JavaScript library for interactive slides in HTML. Try this demo slides generated using reveal.js to see how its slides look like.

Creating slides with revealjs is mostly the same as using ioslides, except for certain options that are available only with revealjs. To learn more about revealjs, read the “Presentations with reveal.js” article on RStudio.

Other formats

There are more options for creating presentation slides via R Markdown, including the following:

• HTML presentations with slidy
  • Use output: slidy_presentation in the YAML header
  • See the “Presentations with Slidy” article on RStudio
• PDF presentations with beamer
  • Use output: beamer_presentation
  • See the “Presentations with Beamer” article on RStudio
• HTML presentations with xaringan
  • Use output: xaringan::moon_reader
  • Visit the package GitHub repository for more

R Presentation

R Presentation is another file format for an interactive HTML slides that are built on amazing reveal.js. All Workshop slides are generated using R Presentation with some customizing work.

Unlike what we have seen abvoe, R Presentation is not a R Markdown document and has its own file extension (.RPres). Similar to R Notebook, R Presentation offers an interactive “Preview” which gets automatically re-rendered each time the source file (.RPres) is saved. This can support a more interactive workflow for creating slides.

Unfortunately, R Presentation is no longer in active development.

To learn more about R Presentation, visit relevant pages on RStudio Support website.

What is Shiny?

“Shiny is an open source R package that provides an elegant and powerful web framework for building web applications using R. Shiny helps you turn your analyses into interactive web applications without requiring HTML, CSS, or JavaScript knowledge.”
- RStudio.com

To get a feel for what Shiny is capable of, try my ICJIA Uniform Crime Report Data dashboard app here.

Also, check out more examples on RStudio’s “Shiny User Showcase” page.

Shiny opens up a whole new world of opportunities. Two common “applications” of Shiny include building dashboards and generating interactive documents.

Dashboards

A data dashboard is a visual interface to data to allow its viewers for gain key insights. It is often an interactive application that provides viewers with options to explore data from multiple angles interactively. A Shiny application is perfectly capable of making a great dashboard.

Interactive documents

Shiny can be used to generate interactive documents with Shiny app widgets embedded. An interactive document can be created by knitting an R Markdown file with the YAML head including runtime: shiny and output: html_document or output: ioslids_presentation. Embedded Shiny R code chunks will render a mini application, which can offer your readers yet another way to gain insights from your work.

Structure of an interactive document

The following figure offers a visual illustration of the structure of an interactive document powered by Shiny.

Source: “Introduction to interactive documents”. Shiny from R Studio

Getting started

install.pacakges("shiny")
library(shiny)

runExample("01_hello")

Shiny is a package, so you first have to install and import it. Once the package is imported to your R environment, try a simple built-in example for Shiny application!

Parts of Shiny application

A Shiny app consists of two parts, server and ui.

They can be separated into two files, server.R and ui.R. In this case, both files must be located in the same directory, typically named “app”.

Alternatively, both parts can live in a single file, app.R.

For interactive documents, the R Markdown document serves as the user interface, so there is no need for a serarate ui file.

function(input, output, session) {
  ## R code for server logic
}

fluidPage(
  ## R code for user interface
)

library(shiny)

server <- function(input, output) {
  # server-side logic
}

ui <- fluidPage(
  # user interface
)

shinyApp(ui, server)

More on Shiny development

Developing a Shiny app takes much practice, planning and pain experiment. However, the reward is YUGE!

You can get started with Shiny using these tutorials by RStudio. Also, follow along these articles by RStudio to hone your Shiny skills.

If you need examples and inspirations for your own projects, visit Shiny Gallery and check out featured applications and widgets.

Deploying Shiny apps

Shiny applications, including the interactive documents, can be deployed for use in the following ways:

• Via shinyapps.io
• Via Shiny Server
• Via ShinyProxy

Static websites

A collection R Markdown documents in HTML format can be made into a website.

To do so, we need a _site.yml file in the same folder as individual documents to be put together. _site.yml specifies the name and the routing structure of the resulting website.

With _site.yml and all HTML documents ready, run rstudio::render_site() to generate the website.

For details, see the “R Markdown Websites” article on RStudio website.

name: ICJIA R Workshop
output_dir: '.'
navbar:
  title: ICJIA R WORKSHOP
  right:
  - text: Home
    href: index.html
  - text: Modules
    href: modules.html
  - text: About
    href: about.html
output:
  html_document:
    includes:
      after_body: include_footer.html
    css: css/style.css
    lib_dir: site_libs
    self_contained: no

Books with blogdown

bookdown package, built on R Markdown, facilitates writing books and long articles/reports. A bookdown publication is made downloadable in PDF, EPUB and MOBI formats, making it more like a real electronic “book” than just an online documentation website.

Check out bookdown package website to find out more.

Also, read Xie, Y. (2018). bookdown: Authoring Books and Technical Documents with R Markdown for a comprehensive guide for bookdown. The book itself is generated using bookdown.

Blogs with blogdown

blogdown is a package to generate static websites using R Markdown and the Hugo, a popular open-source static website generator.

You can visit Awesome Blogdown website for a curated list of blogdown examples.

Also, read Xie, Y. et al. (2018). blogdown: Creating Websites with R Markdown for a comprehensive guide for blogdown.

The following are examples of blogs/websites built using blogdown: