---
title: "Flexible, Dynamic, Interactive Reports with knitr and R Markdown"
author: "Carson Sievert"
date: "`r Sys.Date()`"
output:
ioslides_presentation:
transition: default
widescreen: true
css: styles.css
---
```{r, echo = FALSE, message = FALSE}
knitr::opts_chunk$set(message = FALSE, warning = FALSE, comment = "#>")
# thanks Ramnath -- https://ramnathv.github.io/posts/verbatim-chunks-knitr/
knitr::knit_hooks$set(source = function(x, options){
if (!is.null(options$verbatim) && options$verbatim){
opts = gsub(",\\s*verbatim\\s*=\\s*TRUE\\s*", "", options$params.src)
bef = sprintf('\n\n ```{r %s}\n', opts, "\n")
stringr::str_c(
bef,
knitr:::indent_block(paste(x, collapse = '\n'), " "),
"\n ```\n"
)
} else {
stringr::str_c("\n\n```", tolower(options$engine), "\n",
paste(x, collapse = '\n'), "\n```\n\n"
)
}
})
library(ggplot2)
```
## Hello R Markdown!
## Choose your output format!!
## Be the great mediator
## But, be careful what you wish for!
## _Why_ R Markdown?
> - It's __simple__. Focus on writing, rather than debugging silly errors (I'm looking at you _LaTeX_).
> - It's __flexible__. Markdown was created to simplify writing HTML, but thanks to [pandoc](http://pandoc.org/), Markdown converts to many different formats!
> - It's __dynamic__. Find a critical error? Get a new dataset? Regenerate your report without copy/paste hell!
> - Encourages __transparency__. Collaborators (including your future self) will thank you for integrating your analysis & report.
> - Enables __interactivity/reactivity__. Allow your audience to explore the analysis (rather than passively read it).
## First things first, _what_ is Markdown?
> - Markdown is a particular type of markup language.
> - Markup languages are designed produce documents from plain text.
> - Some of you may be familiar with _LaTeX_. This is another (less human friendly) markup language for creating pdf documents.
> - _LaTeX_ gives you much greater control, but it is restricted to pdf and has a __much__ greater learning curve.
> - Markdown is becoming a standard. Many websites will generate HTML from Markdown (e.g. GitHub, Stack Overflow, reddit).
## _Who_ is using R Markdown, and _for what_?
* The [R Markdown website](http://rmarkdown.rstudio.com/) is built with R Markdown.
* The [new edition of the ggplot2 book](https://github.com/hadley/ggplot2-book/) uses it.
* R package vignettes (for example, [I made this for plotly](http://cpsievert.github.io/plotly/pipe-dsl/)).
* [Many](http://lincolnmullen.com/projects/dh-r/index.html) great [tutorials](http://renkun.me/learnR/) use R markdown add-ons such as [Rgitbook](http://jason.bryer.org/Rgitbook/).
* People are [blogging with it](http://cpsievert.github.io/knitr-jekyll//2015/04/jekyll-tufte-servr.html).
* I, for one, am _trying_ to write my dissertation with it.
## What is _R_ Markdown?
* Straight from the [R Markdown home page](http://rmarkdown.rstudio.com/):
> R Markdown is an authoring format that enables easy creation of dynamic documents, presentations, and reports from R. It combines the core syntax of __markdown__ (an easy-to-write plain text format) __with embedded R code chunks__ that are run so their output can be included in the final document. R Markdown documents are fully reproducible (they can be automatically regenerated whenever underlying R code or data changes).
## Your Turn
Study the first page of the [R Markdown Reference Guide](rmarkdown-reference.pdf).
Yes, the _entire_ markdown syntax can be described in one page!
Can you think of anything that is missing from the syntax (that you might want when creating documents)?
## Markdown doesn't natively support...
> - Stuff you'd find in academic publications:
* Figure/table referencing
* Table of contents
> - Many, many appearance related things (image/figure alignment, coloring, font families, etc.)
---
## There is hope...
> - You don't _have to_ restrict yourself to markdown. You can always include HTML/`LaTeX` markup, but don't expect it to convert between output formats.
> - There are many efforts to extend Markdown (but, then again, keeping it simple is the point!)
> - Awesome people tend to create awesome templates.
## Your Turn
Have a look at R Markdown presentations and templates.
__Pro tip__: run `devtools::install_github("rstudio/rticles")` to get more templates
## Yaml Front Matter
The stuff at the top of the .Rmd file (called yaml front matter) tells __rmarkdown__ what output format you want.
```
---
title: "Untitled"
date: "June 9, 2015"
output: html_document
---
```
In this case, when you click "Knit HTML", RStudio calls `rmarkdown::render("file.Rmd", html_document())`. You can certainly change these default values (see the [source of this presentation](https://raw.githubusercontent.com/cpsievert/slides/gh-pages/rmd/index.Rmd)).
## What is a code chunk?
A code chunk is a concept borrowed from the [knitr](http://yihui.name/knitr/) package (which, in turn, was inspired by [literate programming](http://en.wikipedia.org/wiki/Literate_programming)). In .Rmd files, you can start/end a code chunk with three back-ticks.
```{r chunk1, verbatim = TRUE}
1 + 1
```
Want to run a command in another language?
```{r chunk2, engine = 'python', verbatim = TRUE}
print "a" + "b"
```
## Code chunk options
There are a plethora of [chunk options](http://yihui.name/knitr/options/) in __knitr__ (engine is one of them). Here are some that I typically use:
* `echo`: Show the code?
* `eval`: Run the code?
* `message`: Relay messages?
* `warning`: Relay warnings?
* `fig.width` and `fig.height`: Change size of figure output.
* `cache`: Save the output of this chunk (so we don't have to run it next time)?
## Your Turn
Study the second page of the [R Markdown Reference Guide](rmarkdown-reference.pdf) and go back to the [Hello R Markdown example](hello_rmarkdown.Rmd)
__Easy__: Modify the figure sizing and alignment.
__Medium__: Add a figure caption.
__Hard__: Can you create an animation? (Hint: look at the `fig.show` chunk option -- you might need to the __animation__ package for this)
__Pro Tip__: Don't like the default chunk option value? Change it at the top of the document:
```{r setup, verbatim = TRUE}
knitr::opts_chunk$set(message = FALSE, warning = FALSE)
```
## Chunk hooks
* From [the documentation](http://yihui.name/knitr/hooks/)
> Chunk hooks are functions to be called before or after a code chunk when the chunk option
```{r hook, verbatim = TRUE}
library(knitr)
knit_hooks$set(small.mar = function(before, options, envir) {
if (before) par(mar = c(4, 4, .1, .1)) # smaller margin on top and right
})
```
Then use it like this:
```{r histogram, small.mar = TRUE, verbatim = TRUE}
hist(rnorm(100), main = '')
```
## Your Turn
Copy/paste the chunk hook (on the previous slide) into your R Markdown file. Notice the difference in margins.
## Formatting R output
```{r}
m <- lm(mpg ~ disp, data = mtcars)
summary(m) # output isn't very attractive
```
---
[pander](http://rapporter.github.io/pander/) is one great option.
```{r}
library(pander)
pander(m)
```
---
```{r}
a <- anova(m)
a
```
---
```{r}
pander(a)
```
## Pander knows about a lot of stuff!
```{r}
methods(pander)
```
## Your Turn
* Look through the list of pander methods. Can you apply any of the methods that we haven't discussed? We just saw `pander.lm` and `pander.anova`.
## Interactive Stuff
```{r}
d <- diamonds[sample(nrow(diamonds), 1000), ]
DT::datatable(d)
```
---
```{r}
library(plotly)
p <- ggplot(data = d, aes(x = carat, y = price, colour = clarity)) +
geom_point(aes(text = cut), size = 3) + geom_smooth() + facet_wrap(~ clarity)
ggplotly(p)
```
## Reactive documents with shiny!