course
/
r4ds
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Complete pass through formats

This commit is contained in:
hadley 2016-08-23 08:59:08 -05:00
parent 0875f55510
commit c2cc5bf3c5
2 changed files with 139 additions and 72 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
DESCRIPTION
View File

@ -22,6 +22,7 @@ Imports:
htmlwidgets,
jpeg,
jsonlite,
leaflet,
Lahman,
lubridate,
knitr,
@ -33,6 +34,7 @@ Imports:
pryr,
purrr,
readr,
shiny,
stringr,
tibble,
tidyr,

209
rmarkdown-formats.Rmd
View File

@ -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:
@ -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()`
@ -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.
* `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
* `word_document` for Microsoft Word documents (`.docx`).
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:
* `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.
1. Reactive components made with Shiny.
#### htmlwidgets
[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.
```{r, echo = FALSE, out.width = "100%"}
knitr::include_graphics("images/interactive-1-htmlwidget.png")
```{r, eval = FALSE}
knitr::opts_chunk$set(echo = FALSE)
```
Htmlwidgets create *client side* interactions. Since htmlwidgets are exported in JavaScript, any common web browser can execute the interactions.
For `html_document` another option is to make the code chunks hidden by default, but visible with a click:
Learn more about packages that build htmlwidgets at [www.htmlwidgets.org](http://www.htmlwidgets.org/showcase_leaflet.html).
#### Shiny
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).
```{r, echo = FALSE, out.width = "100%"}
knitr::include_graphics("images/interactive-2-shiny.png")
```yaml
output:
html_document:
code_folding: hide
```
Since web browsers cannot execute R code, Shiny interactions occur on the *server side*. This has several benefits:
## Notebooks
* 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
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:
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.
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.
Learn more about Shiny at the [Shiny Development Center](http://shiny.rstudio.com/).
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.
## Presentations (slides)
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.
R Markdown can generate four presentations formats:
```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. `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:
Create bullet points that display incrementally with `>-`. Here is a version of 1-example.Rmd displayed as a reveal.js slide presentation.
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")
@ -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/>.
## 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
Use `rmarkdown::render_site()` to render collections of R Markdown documents into a website. Each website requires, in a single directory,
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`, which provides the navigation for the site, e.g.
* a YAML file named `_site.yml` provides the navigation for the site, e.g.
```{r echo = FALSE, comment = ""}
cat(htmltools::includeText("rmarkdown-demos/12-website/_site.yml"))
cat(readr::read_file("rmarkdown-demos/12-website/_site.yml"))
```
* a .Rmd file named `index.Rmd`, which provides the content for the home page of your website
* a .Rmd file named `index.Rmd` provides the content for the home page of
your website
* other .Rmd files to include in the site. Each .Rmd file becomes a page in the 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.
* any support material
Execute `rmarkdown::render_site("<path to directory>")` to build `_site`, a directory of files ready to deploy as a standalone static website.
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
```{r, echo = FALSE, out.width = "100%"}
knitr::include_graphics("images/website-2-website.png")
```
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,