Skip to content

Commit

Permalink
Complete pass through formats
Browse files Browse the repository at this point in the history
  • Loading branch information
@hadley
hadley committed Aug 23, 2016
1 parent 0875f55 commit c2cc5bf
Show file tree
Hide file tree
Showing 2 changed files with 135 additions and 68 deletions.
2 changes: 2 additions & 0 deletions DESCRIPTION
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ Imports:
htmlwidgets,
jpeg,
jsonlite,
leaflet,
Lahman,
lubridate,
knitr,
Expand All @@ -33,6 +34,7 @@ Imports:
pryr,
purrr,
readr,
shiny,
stringr,
tibble,
tidyr,
Expand Down
201 changes: 133 additions & 68 deletions rmarkdown-formats.Rmd
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# 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:
Expand All @@ -26,6 +28,12 @@ RStudio's knit button renders a file to the first format listed in its `output`
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()`
Expand Down Expand Up @@ -57,88 +65,88 @@ output:
pdf_document: default
```

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

## Documents and notebooks
## 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 will
automatically render the markdown to HTML for you.

### Notebooks

The chief difference between `html_document` and `html_notebook` is that `html_notebok` also generates `.nb.html` file. This is a self-contained HTML file that contains code and outputs. You can publish it to a website, or share it with other RStudio users. If you open it from RStudio, it will extract and open the .Rmd file that underlies the nb.html file.

To share this experience with colleagues, simply share your .Rmd file for them to open in their RStudio IDE. If your colleagues do not use R, you can recreate the notebook interface by rendering your file to an HTML notebook with `output: html_notebook`.

I consider good practice to check in both the input (i.e. the `.Rmd` file) and the output (i.e. the `.html` file) when using git for data analysis. That makes it easier to see when the outputs of the analyis change. That's particularly important if you're rerunning analyses as the data changes.

### Interactivity

HTML is an interactive format and you can take advantage of that interactivty from R Markdown in two ways:

1. Interactive JavaScript visualizations based on htmlwidgets.
* `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

1. Reactive components made with Shiny.
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:

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

[Htmlwidgets](http://www.htmlwidgets.org/) are R functions that return JavaScript visualizations. You do not need to know any JavaScript to use htmlwidgets. The R functions take care of all of the coding for you. The [document below](http://github.com/hadley/r4ds/tree/master/rmarkdown-demos/13-htmlwidget.Rmd) uses a [leaflet](http://rstudio.github.io/leaflet/) htmlwidget to create an interactive map.
For `html_document` another option is to make the code chunks hidden by default, but visible with a click:

```{r, echo = FALSE, out.width = "100%"}
knitr::include_graphics("images/interactive-1-htmlwidget.png")
```yaml
output:
html_document:
code_folding: hide
```

Htmlwidgets create *client side* interactions. Since htmlwidgets are exported in JavaScript, any common web browser can execute the interactions.
## Notebooks

Learn more about packages that build htmlwidgets at [www.htmlwidgets.org](http://www.htmlwidgets.org/showcase_leaflet.html).
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:

#### Shiny
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.

The [Shiny](http://shiny.rstudio.com/) package helps developers build interactive web apps powered by R. You can use components from the Shiny package to turn your R Markdown into such an app. To call Shiny code from an R Markdown document, add `runtime: shiny` to the header, like in [this document](http://github.com/hadley/r4ds/tree/master/rmarkdown-demos/14-shiny.Rmd).
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.

```{r, echo = FALSE, out.width = "100%"}
knitr::include_graphics("images/interactive-2-shiny.png")
```

Since web browsers cannot execute R code, Shiny interactions occur on the *server side*. This has several benefits:
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.

* you can control access to the app
* you can keep private the data used in the app
* you can increase processing speed by augmenting the server
```yaml
output:
html_notebook: default
github_document: default
```

But it also introduces a logistical issue: Shiny apps require a special server, known as a Shiny Server, when hosted online. You can also run Shiny powered documents on your local computer by rendering them in your local R session.
`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.

Learn more about Shiny at the [Shiny Development Center](http://shiny.rstudio.com/).
## Presentations

## Presentations (slides)
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 can generate four presentations formats:
R Markdown comes with three presentations formats built-in:

1. `ioslides_presentation` - HTML presentation with ioslides

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

1. `slidy_presentation` - HTML presentation with W3C Slidy

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

Each format will intuitively divide 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.
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

Create bullet points that display incrementally with `>-`. Here is a version of 1-example.Rmd displayed as a reveal.js slide presentation.
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")
Expand Down Expand Up @@ -166,36 +174,93 @@ 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/>.

## Websites
## Interactivity

Use `rmarkdown::render_site()` to render collections of R Markdown documents into a website. Each website requires, in a single directory,
Any HTML format (document, notebook, dashboard, or presentation), can contain interactive components.

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

```{r echo = FALSE, comment = ""}
cat(htmltools::includeText("rmarkdown-demos/12-website/_site.yml"))
```
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.

* a .Rmd file named `index.Rmd`, which provides the content for the home page of your website
```{r}
library(leaflet)
leaflet() %>%
setView(174.764, 36.877, zoom = 16) %>%
addTiles() %>%
addMarkers(174.764, 36.877, popup = "Maunga Whau")
```

* other .Rmd files to include in the site. Each .Rmd file becomes a page in the website
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.

* any support material
There are many packages that provide htmlwidgets, including:

Execute `rmarkdown::render_site("<path to directory>")` to build `_site`, a directory of files ready to deploy as a standalone static website.
* __dygraphs__, <http://rstudio.github.io/dygraphs/>, for interactive time
series visualisations.

Better yet, create an [RStudio Project](https://support.rstudio.com/hc/en-us/articles/200526207-Using-Projects) for your website directory. RStudio will add a Build tab to the IDE that you can use to build and preview your site. [This collection of files](http://github.com/hadley/r4ds/tree/master/rmarkdown-demos/12-website.zip) creates the simple site below
* __DT__, <http://rstudio.github.io/DT/>, for interactive tables.

```{r, echo = FALSE, out.width = "100%"}
knitr::include_graphics("images/website-2-website.png")
* __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,
Expand Down

0 comments on commit c2cc5bf

Please sign in to comment.