r4ds/rmarkdown-formats.Rmd

# R Markdown formats

## Introduction

So far you've seen R Markdown used to produce long-format HTML documents. But there are many other types of output that you can make. This chapter gives a brief overview of some of the most important alternate formats. Even more are available in add-on packages, some of which are listed at <http://rmarkdown.rstudio.com/formats.html> (or will be by the time the book is published).

There are two ways to set the output of a document:

1.  Permanently, by modifying the the YAML header: 
    
    ```yaml
    title: "Viridis Demo"
    output: html_document
    ```
    
1.  Transiently, by calling `rmarkdown::render()` by hand:
    
    ```{r eval = FALSE}
    rmarkdown::render("1-example.Rmd", output_format = "word_document")
    ```
    
    This is useful if you want to programmatically produce multiple types of
    output.

RStudio's knit button renders a file to the first format listed in its `output` field. You can render to additional formats by clicking the dropdown menu beside the knit button.

```{r, echo = FALSE, out.width = "70%"}
knitr::include_graphics("images/outputs-2-pdf.png")
```

This chapter will give you a broad overview of some of the output options, 

### Prerequisites

Again, the only package you need for this chapter is rmarkdown, which RStudio will install and load for you as needed.

## Output options
    
Each output format is an R function. If you don't specify a package, the default is assumed to be `rmarkdown`. That means you can get help about the parameters to the format with, e.g., `?rmarkdown:html_document()`

You can customize a format, pass arguments to the output function as sub-values of the `output` field. For example, we can change [1-example.Rmd](http://github.com/hadley/r4ds/tree/master/rmarkdown-demos/1-example.Rmd) to render with a floating table of contents,

Change the default output from:

```yaml
output: html_document
```

To:

```yaml
output:
  html_document:
    toc: true
    toc_float: true
```

You can even render to multiple outputs at one time:

```yaml
output:
  html_document:
    toc: true
    toc_float: true
  pdf_document: default
```

Note the special syntax if you don't want to override any of the default options.

## Documents

The previous chapter focussed on the default `html_document` output. There are number of basic variations on that theme, generating different types of documents:

*   `pdf_document` makes a PDF. That happens via LaTeX (another open 
    source document layout system), which you'll need to install. RStudio will
    prompt you if you don't already have it.
  
*   `word_document` for Microsoft Word documents (`.docx`).
  
*   `odt_document` for OpenDocument Text documents (`.odt`).
  
*   `rtf_document` for Rich Text Format (`.rtf`) documents.
  
*   `md_document` for a Markdown document. This isn't typically useful by itself,
    but you can (for example), commit it to git and share on github. 
    
*   `github_document`: this is a tailored version of `md_document` 
    designed specifically for GitHub. It's useful if you want to check in
    a simple output document that 

Remember, when generating a document to share with decision makes, you can turn off the default display of code by setting global options in the setup chunk:

```{r, eval = FALSE}
knitr::opts_chunk$set(echo = FALSE)
```

For `html_document` another option is to make the code chunks hidden by default, but visible with a click:

```yaml
output:
  html_document:
    code_folding: hide
```

## Notebooks

Notebooks are a variation on documents. The rendered output of the HTML notebook, `html_notebook`, is very similar to the rendered output of the HTML document, `html_document`. The difference is in the purpose: a document is focussed on communicating with decisions makers, while a notebook is focussed on collaborating with other data scientists. The difference in goals leads to storing different things in the HTML output. Both HTML outputs will contain the fully rendered output, but the notebook also contains the full source code. That means you can use the `.nb.html` generated by the notebook in two ways:

1. You can view it in a web browser, and view the rendered output. Unlike
   the `html_document` this rendering always includes an embedded copy of 
   the source code that generated it.

1. You can edit it in RStudio. When you open an `.nb.html` file, RStudio will
   automatically recreate `.Rmd` file that generated it. In the future, you 
   will  also be able contain supporting files (e.g. `.csv` data files), that 
   will be automatically extracted when needed. 

Emailing `.nb.html` files is a simple way to share analyses with your colleagues. The main problem will then be integrating their changes with yours. If this starts to happen a lot, you will soon want to learn Git and Github because it makes collaboration much easier. As mentioned early, Git & GitHub is outside the scope of the book, but there's one tip that's useful if you're already using them: use both `html_notebook` and `github_document` outputs.

```yaml
output:
  html_notebook: default
  github_document: default
```

`html_notebook` gives you a local preview, and a file that you can share via email. `github_document` creates a minimal md file that is easily diffed, and that GitHub will render for you. Checking in the rendered results of a data analysis is good practice because it makes it very easy to see what has changed between runs of an analysis.

## Presentations

You can also use R Markdown to produce presentations. You get less visual control that with a tool like Keynote or Powerpoint, but automatically inserting the results of your R code into a presentation can save a huge amount of time. Presentations work by dividig your content into slides, with a new slide beginning at each first (`#`) or second (`##`) level header. You can also insert a horizontal rule (`***`) to create a new slide without a header. 

R Markdown comes with three presentations formats built-in:

1.  `ioslides_presentation` - HTML presentation with ioslides

1.  `slidy_presentation` - HTML presentation with W3C Slidy

1.  `beamer_presentation` - PDF presentation with LaTeX Beamer.

Two other popular formats are provided by packages:

1.  `revealjs::revealjs_presentation` - HTML presentation with reveal.js. 
    Requires the __revealjs__ package.

1.  __rmdshower__, <https://github.com/MangoTheCat/rmdshower>, provides a 
    wrapper around the __shower__, <https://github.com/shower/shower>, 
    presentation engine

Here is a version of 1-example.Rmd displayed as a reveal.js slide presentation.

```{r, echo = FALSE, out.width = "100%"}
knitr::include_graphics("images/slides-1-viridis.png")
```

## Dashboards

Dashboards are a useful way to communicate large amounts of information visually and quickly. Flexdashboard makes it particularly easy to create dashboards using R Markdown and a convention for how the headers affect the layout:

* Each level 1 header (`#`) begins a new page in the dashboard.
* Each level 2 header (`##`) begins a new column.
* Each level 3 header (`###`) begins a new row.

For example, you can produce this dashboard:

```{r, echo = FALSE, out.width = NULL}
knitr::include_graphics("screenshots/rmarkdown-flexdashboard.png")
```

Using this code:

```{r comment = "", echo = FALSE, out.width = "70%"}
cat(readr::read_file("rmarkdown-demos/11-dashboard.Rmd"))
```

Flexdashboard also provides simple tools for creating sidebars, tabsets, value boxes, and gauges. To learn more about flexdashboard visit <http://rmarkdown.rstudio.com/flexdashboard/>.

## Interactivity

Any HTML format (document, notebook, dashboard, or presentation), can contain interactive components.

### htmlwidgets

HTML is an interactive format, and you can take advantage of that interactivity with __htmlwidgets__, R functions that produce interactivce html visualizations. For example, take the __leaflet__ map below. If you're viewing this page on the web, you can drag the map around, zoom in and out, etc. You obviously can't do that on a book, so rmarkdown automatically inserts a static screenshot for you.

```{r}
library(leaflet)
leaflet() %>%
  setView(174.764, 36.877, zoom = 16) %>% 
  addTiles() %>%
  addMarkers(174.764, 36.877, popup = "Maunga Whau") 
```

The great thing about htmlwidgets is that you don't need to know anything about HTML or javascipt to use them. All the details are wrapped inside the package so you don't need to worry about it.  

There are many packages that provide htmlwidgets, including:

* __dygraphs__, <http://rstudio.github.io/dygraphs/>, for interactive time 
  series visualisations.

* __DT__, <http://rstudio.github.io/DT/>, for interactive tables.

* __threejs__, <https://github.com/bwlewis/rthreejs> for interactive 3d plots.

* __DiagrammeR__, <http://rich-iannone.github.io/DiagrammeR/> for diagrams
  (like flow charts and simple node-link digrams).

To learn more about htmlwidgets and see a more complete list of packages that provide them visit <http://www.htmlwidgets.org/>.

### Shiny

htmlwidgets provide __client-side__ interactivity --- all the interactive happens in the browser, independently of R. On one hand, that's great because you can distribute the HTML file without any connection to R. However, that fundamentally limits what you can do to things that have been implemented in HTML and javascript.  An alternative approach is to use __shiny__, a package that allows you to creative interactivity using R code, not javascript.

To call Shiny code from an R Markdown document, add `runtime: shiny` to the header:

```yaml
title: "Shiny Web App"
output: html_document
runtime: shiny
```

Then you can use the "input" functions to add interactive components to the document:

```{r, message = FALSE, collapse = FALSE}
library(shiny)

textInput("name", "What is your name?")
numericInput("age", "How old are you?", NA, min = 0, max = 150)
```

You can then refer to them in your document as `input$name` and `input$age`, and the code that uses will be automatically re-run. This is a bit of simplification, but in essence, the job of shiny is to figure out the minimal amount of code that needs to be rerun when the inputs change.

I can't show you a live shiny app here because shiny interations occur on the __server-side__. This means you can write interactive apps without knowing javascript, but it means that you need a server to run it on. This introduces a logistical issue: Shiny apps need a Shiny server to be run online. When you run shiny apps on your own computer, shiny automatically sets up a shiny server for you, but you need a public facing shiny server if you want to publish this sort of interactivity online. That's the fundamental trade-off of shiny: you can do anything in a shiny document that you can do in R, but it that requires someone to be running R.

Learn more about Shiny <http://shiny.rstudio.com/>.

## Websites

With a little additional infrastructure you can use R Markdown to generate a complete website. Once you have multiple document in a single directory, you can `rmarkdown::render_site()` to render them all simultaneously. A few other files provide additional control:

* a YAML file named `_site.yml` provides the navigation for the site, e.g.

    ```{r echo = FALSE, comment = ""}
    cat(readr::read_file("rmarkdown-demos/12-website/_site.yml"))
    ```

* a .Rmd file named `index.Rmd` provides the content for the home page of
  your website

Execute `rmarkdown::render_site()` to build `_site`, a directory of files ready to deploy as a standalone static website, or if you use an RStudio Project for your website directory. RStudio will add a Build tab to the IDE that you can use to build and preview your site. 

Read more at <http://rmarkdown.rstudio.com/rmarkdown_websites.html>.

## Other formats

The bookdown package extends R Markdown to create book length documents, like *R for Data Science*, which was written with R Markdown and bookdown. To learn more about bookdown, see the free ebook [Authoring Books with R Markdown](https://bookdown.org/yihui/bookdown/) or [www.bookdown.org](www.bookdown.org).

There are a few Journal specific formats bundled together in the __rticles__ package, <https://github.com/rstudio/rticles>.

You can also create your own formats <http://rmarkdown.rstudio.com/developer_custom_formats.html>.

## Learning more

To learn more about communcating in thse different formats I recommend:

* To improve your presentation skills, I recommend 
  [_Presentation Patterns_](https://amzn.com/0321820800), by Neal Ford,
  Matthew McCollough, and Nathaniel Schutta. It provides a set of effective
  patterns (both low- and high-level) that you can imply to improve your 
  presentations.
  
* If you give academic talks, I recommend reading the [_Leek group guide
  to giving talks_](https://github.com/jtleek/talkguide).
  
* I haven't taken it personally, but I've heard good things about Matt 
  McGarrity's online course on public speaking: 
  <https://www.coursera.org/learn/public-speaking>.

* Finally, effectively communicating your ideas often benefits from some
  knowledge of graphic design. [_The Non-Designer's Design
  Book_](http://amzn.com/0133966151) is a great place to start.