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

Starting to work on formats chapter

This commit is contained in:
hadley 2016-08-22 17:28:29 -05:00
parent 5de327e367
commit 0875f55510
4 changed files with 153 additions and 215 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

118
rmarkdown-demos/11-dashboard.Rmd
View File

@ -1,118 +1,42 @@
---
title: "Review Dashboard"
output:
flexdashboard::flex_dashboard:
orientation: columns
title: "Diamonds distribution dashboard"
output: flexdashboard::flex_dashboard
---
```{r include = FALSE}
library(viridis)
```{r setup, include = FALSE}
library(ggplot2)
library(marmap)
library(dplyr)
knitr::opts_chunk$set(fig.width = 5, fig.asp = 1/3)
```
# Intro {.sidebar}
This dashboard covers several topics:
* The marmap package
* The viridis package
* Miscellaneous material
# Marmap Package
## Column 1
### Florida
### Carat
```{r echo = FALSE}
data(florida)
autoplot(florida)
```{r}
ggplot(diamonds, aes(carat)) + geom_histogram(binwidth = 0.1)
```
The [marmap](https://cran.r-project.org/web/packages/marmap/index.html) package provides tools and data for visualizing the ocean floor. Here is an example contour plot of marmap's `florida` dataset.
### Cut
## Column 2
### Hawaii
```{r echo = FALSE}
data(hawaii)
autoplot(hawaii)
```{r}
ggplot(diamonds, aes(cut)) + geom_bar()
```
### Alaska
### Colour
```{r echo = FALSE}
data(aleutians)
autoplot(aleutians)
```
# Viridis Package
## Column 1
### Viridis colors
```{r fig.cap="Maunga Whao, Auckland, NZ"}
image(volcano, col = viridis(200))
```
### Magma colors
```{r fig.cap="Maunga Whao, Auckland, NZ"}
image(volcano, col = viridis(200, option = "A"))
```{r}
ggplot(diamonds, aes(color)) + geom_bar()
```
## Column 2
### Inferno colors
### The largest diamonds
```{r fig.cap="Maunga Whao, Auckland, NZ"}
image(volcano, col = viridis(200, option = "B"))
```{r}
diamonds %>%
arrange(desc(carat)) %>%
head(100) %>%
select(carat, cut, color, price) %>%
DT::datatable()
```
### Plasma colors
```{r fig.cap="Maunga Whao, Auckland, NZ"}
image(volcano, col = viridis(200, option = "C"))
```
# Miscellaneous
## Column 1 {data-width=300}
### Bash support
```{bash}
ls *.Rmd
```
***
This chunk executes bash code.
### Python support
```{python}
x = 'hello, python world!'
print(x.split(' '))
```
***
This chunk executes python code.
## Column 2 {data-width=700}
### Tables with Kable
```{r echo = FALSE, results = 'asis'}
library(knitr)
kable(mtcars[1:5, ], caption = "A knitr kable.")
```
***
It is very easy to make tables with knitr's `kable` function.

248
rmarkdown-formats.Rmd
View File

@ -1,116 +1,170 @@
# R Markdown formats
```{r setup, include = FALSE}
chunk <- "```"
```
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).
## Output Formats
There are two ways to set the output of a document:
Set the `output_format` argument of `render()` to render your .Rmd file into any of R Markdown's supported formats. For example, the code below renders [1-example.Rmd](http://github.com/hadley/r4ds/tree/master/rmarkdown-demos/1-example.Rmd) to a Microsoft Word 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.
```{r eval = FALSE}
library(rmarkdown)
render("1-example.Rmd", output_format = "word_document")
```
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.
If you do not select a format, R Markdown renders the file to its default format, which you can set in the `output` field of a .Rmd file's header. The header of [1-example.Rmd](http://github.com/hadley/r4ds/tree/master/rmarkdown-demos/1-example.Rmd) shows that it renders to an HTML file by default:
```{r eval = FALSE}
---
title: "Viridis Demo"
output: html_document
---
```
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 = "100%"}
```{r, echo = FALSE, out.width = "70%"}
knitr::include_graphics("images/outputs-2-pdf.png")
```
The menu contains a list of formats that are similar to the default format. To update the list, change the default format in your YAML. The following output formats are available to use with R Markdown.
## 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()`
### Documents
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,
* `html_notebook` - Interactive R Notebooks
* `html_document` - HTML document w/ Bootstrap CSS
* `pdf_document` - PDF document (via LaTeX template)
* `word_document` - Microsoft Word document (docx)
* `odt_document` - OpenDocument Text document
* `rtf_document` - Rich Text Format document
* `md_document` - Markdown document (various flavors)
Change the default output from:
### Presentations (slides)
* `ioslides_presentation` - HTML presentation with ioslides
* `revealjs::revealjs_presentation` - HTML presentation with reveal.js. Requires the revealjs package.
* `slidy_presentation` - HTML presentation with W3C Slidy
* `beamer_presentation` - PDF presentation with LaTeX Beamer
### More
* `flexdashboard::flex_dashboard` - Administrative dashboards. Requires the flexdashboard package.
* `tufte::tufte_handout` - PDF handouts in the style of Edward Tufte. Requires the tufte package.
* `tufte::tufte_html` - HTML handouts in the style of Edward Tufte. Requires the tufte package.
* `tufte::tufte_book` - PDF books in the style of Edward Tufte. Requires the tufte package.
* `html_vignette` - R package vignette (HTML)
* `github_document` - GitHub Flavored Markdown document
You can also build books, websites, and interactive documents with R Markdown, as described in the sections below.
### Output Options
Each output format is implemented as a function in R, e.g. `html_document()`. To 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,
```{r, echo = FALSE, out.width = "100%"}
knitr::include_graphics("images/outputs-3-toc.png")
```yaml
output: html_document
```
To learn which arguments a format takes, read the format's help page in R, e.g. `?html_document`.
To:
## HTML Notebooks
```yaml
output:
html_document:
toc: true
toc_float: true
```
In How It Works, you learned that R Markdown files provide a notebook interface for editing that makes it easy to test and iterate your code.
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 and notebooks
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`.
R Markdown will create a `nb.html` version of your file; a self-contained HTML file that contains all current chunk outputs (suitable for display on a website). You can view the .nb.html file in any ordinary web browser, or open it in RStudio. In this case, RStudio will extract and open the .Rmd file that underlies the nb.html file.
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.
### Version Control
### Interactivity
One of the major advantages of R Markdown notebooks compared to other notebook systems is that they are plain-text files and therefore work well with version control. I recommend checking in both the .Rmd and .nb.html files into version control so that both your source code and output are available to collaborators. However, you can choose to include only the .Rmd file (with a .gitignore that excludes the .nb.html) if you want each collaborator to work with their own private copies of the output.
HTML is an interactive format and you can take advantage of that interactivty from R Markdown in two ways:
## Slide Presentations
1. Interactive JavaScript visualizations based on htmlwidgets.
R Markdown renders to four presentation formats:
1. Reactive components made with Shiny.
* beamer_presentation - PDF presentations with beamer
* ioslides_presentation - HTML presentations with ioslides
* slidy_presentation - HTML presentations with slidy
* revealjs::revealjs_presentation - HTML presentations with reveal.js (requires the revealjs package)
#### htmlwidgets
Each format will intuitively divide your content into slides, with a new slide beginning at each first or second level header.
[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.
Insert a horizontal rule (`***`) into your document to create a manual slide break. Create bullet points that display incrementally with `>-`. 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/interactive-1-htmlwidget.png")
```
Htmlwidgets create *client side* interactions. Since htmlwidgets are exported in JavaScript, any common web browser can execute the interactions.
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")
```
Since web browsers cannot execute R code, Shiny interactions occur on the *server side*. This has several benefits:
* 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
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.
Learn more about Shiny at the [Shiny Development Center](http://shiny.rstudio.com/).
## Presentations (slides)
R Markdown can generate four presentations formats:
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.
Create bullet points that display incrementally with `>-`. 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. Create one with the `flex_dashboard` output format of the flexdashboard package, as in the [.Rmd file below](http://github.com/hadley/r4ds/tree/master/rmarkdown-demos/11-dashboard.Rmd):
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:
Flexdashboard makes it easy to organize your content into a visual 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.
* 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 box.
For example, you can produce this dashboard:
You can further modify elements with attributes, as in the `{.sidebar}` above.
```{r, echo = FALSE, out.width = NULL}
knitr::include_graphics("screenshots/rmarkdown-flexdashboard.png")
```
Flexdashboard also provides simple tools for creating tabsets, value boxes, and gauges. To learn more about flexdashboard visit <http://rmarkdown.rstudio.com/flexdashboard/>.
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/>.
## Websites
@ -136,50 +190,10 @@ Better yet, create an [RStudio Project](https://support.rstudio.com/hc/en-us/art
knitr::include_graphics("images/website-2-website.png")
```
## Interactive Documents
R Markdown documents are a useful platform for interactive content. You can make your documents interactive in two ways. Add:
1. Interactive JavaScript visualizations based on [htmlwidgets](http://www.htmlwidgets.org/), or
2. Reactive components made with [Shiny](http://shiny.rstudio.com/)
### 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")
```
Htmlwidgets create *client side* interactions. Since htmlwidgets are exported in JavaScript, any common web browser can execute the interactions.
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")
```
Since web browsers cannot execute R code, Shiny interactions occur on the *server side*. This has several benefits:
* 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
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.
Learn more about Shiny at the [Shiny Development Center](http://shiny.rstudio.com/).
## Books
## 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).
## Learning more

2
rmarkdown.Rmd
View File

@ -68,7 +68,7 @@ When you __knit__ the document R Markdown sends the .Rmd file to [knitr](http://
knitr::include_graphics("images/RMarkdownFlow.png")
```
To get started with your own `.Rmd` file, select *File > New File > R Markdown...* in the menubar. RStudio will launch a wizard that you can use to pre-populate your file with useful content thatreminds you how the key features of R Markdown work.
To get started with your own `.Rmd` file, select *File > New File > R Markdown...* in the menubar. RStudio will launch a wizard that you can use to pre-populate your file with useful content that reminds you how the key features of R Markdown work.
The following sections dives into the three components of an R Markdown document in more details: the markdown text, the code chunks, and the YAML header.

BIN
screenshots/rmarkdown-flexdashboard.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 115 KiB