rtp-rmarkdown-12-13-16.Rmd

---
title: "Everything R Markdown"
author: "Mine Cetinkaya-Rundel"
date: "December 13, 2016"
output: ioslides_presentation
---

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

# Welcome to R-Ladies RTP!

## Materials

- All source code at https://github.com/rladies/rtp_20161213_rmarkdown

- Slides at http://rpubs.com/minebocek/rladies-rmarkdown

- Demo materials at http://bit.ly/rladies-rmd-demo (will come up later)

- R Packages that we will use today: `dplyr`, `ggplot2`, `rmarkdown`, `knir`, `DT`, `flexdashboards`

```{r eval=FALSE}
packages <- c("dplyr", "ggplot2", "rmarkdown", "knir", 
              "DT", "flexdashboards")
install.packages(packages)
lapply(packages, library, character.only = TRUE)
```

# Recording and reporting your analysis

## Options

- Writing code in the Console -- error prone (especially typo prone!) and hard to keep track of

- R Script + LaTeX/Word -- can be reproducible with careful organization but still error prone

- R Markdown -- code, output, prose all in one place and fully reproducible, can call R scripts as well

## R Markdown

- R Markdown is an authoring format that enables easy creation of dynamic 
documents, presentations, and reports from R

- R Markdown documents are fully **reproducible**, they can be 
automatically regenerated whenever underlying R code or data changes

- File -> New File -> R Markdown...

- Important features:
    - An (optional) YAML header surrounded by ---s
    - R code chunks surrounded by ```s
    - Text mixed with simple markdown formatting
        - Human readable! (in RStudio -> Help -> Markdown Quick Reference)
        - Limited, so not too time consuming to master
    - Self contained workspace

## R Markdown installation

If you have not yet done so:

```{r eval=FALSE}
install.packages("rmarkdown")
library(rmarkdown)
```

# Reports

## How it works

(in case you're interested...)

![](img/RMarkdownFlow.png)

- When you knit, R Markdown feeds the .Rmd file to knitr, which executes all of the code chunks and creates a new markdown (.md) document which includes the code and its output.

- The markdown file generated by knitr is then processed by pandoc which is responsible for creating the finished format. 

## Demo

- If you have not yet done so:
    - Load the following packages:
    ```{r eval=FALSE}
    install.packages("ggplot2")
    install.packages("dplyr")
    ```
    
    - Go to http://bit.ly/rladies-rmd-demo,  download the zipped folder and unzip

- Open demo-template.Rmd in RStudio and Knit

<br><br>

**DEMO**

## Output options

- HTML - web ready

- PDF - requires TeX to be installed

- Word - can be useful if collaborators are Word users, but their changes cannot be easily integrated

# R code in R Markdown documents

## Two options:

- Code chunks

- Inline code

## Code chunks

- Inserting a new code chunk:
    + keyboard shortcut Ctrl + Alt + I (OS X: Cmd + Option + I)
    + the Insert command in the editor toolbar (see other languages as well)
    + typing the chunk delimiters (\`\`\`{r} to start, \`\`\` to end)

- When file is rendered R Markdown will run each code chunk and embed the results beneath the code chunk in your final report

## Chunk options

Chunk output can be customized with knitr options, arguments set in the {} of a chunk header.

Examples:

- `include = FALSE`: code runs and results be used by other chunks, but doesn't appear in finished file
- `echo = FALSE`:  prevents code, but not the results from appearing in the finished file (useful way to embed figures)
- `message = FALSE`: messages do not appear in the finished file
- `warning = FALSE`: warnings do not appear in the finished file
- `fig.cap = "..."` adds a caption to graphical results

See [R Markdown Reference Guide](https://www.rstudio.com/wp-content/uploads/2015/03/rmarkdown-reference.pdf) for all options.

## Caching

`cache = TRUE`

Tricky, but can be useful!

References:
- http://yihui.name/knitr/options/
- http://yihui.name/knitr/demo/cache/

## Inline code

Code results can be inserted directly into the text of a .Rmd file by enclosing the code with \` r\`

<br><br>

**DEMO**


# Tables

## Tables

Not super easy to customize, but there are some options that are easy to use and look good

## knitr::kable {.small}

```{r}
knitr::kable(mtcars[, 1:5])
```

## DT::datatable {.small}

```{r}
DT::datatable(mtcars[, 1:5], extensions = 'ColReorder', 
              options = list(colReorder = TRUE, 
                             pageLength = 5))
```

# Notebooks

## Notebook

- When you open an R Markdown file in the RStudio IDE, it becomes a notebook interface for R. 

- You can run each code chunk by clicking the green arrow icon. RStudio executes the code and display the results inline with your file.

- Other chunk actions...

<br><br>

**DEMO**

## Version control with notebooks

- One of the major advantages of R Notebooks compared to other notebook systems is that they are plain-text files and therefore work well with version control

- If using version control, check both the .Rmd and .nb.html files into version control so that both your source code and output are available to collaborators

- If you want each collaborator to work with their own private copies of the output check only the .Rmd file (with a .gitignore that excludes the .nb.html)

## More on Notebooks

See http://rmarkdown.rstudio.com/r_notebooks.html

# Dashboards

## flexdashboards

- Dashboards based on R Markdown: easy to compose and publish

- Intelligent resizing: to fill browser and display on mobile devices

- Support a wide variety of components: htmlwidgets, base, lattice, and grid graphics, tabular data, gauges and value boxes, and text

- Shiny compatible!

## Install

```{r eval=FALSE}
install.packages("flexdashboard")
library(flexdashboard)
```

## Get started

In RStudio:

File -> New File -> R Markdown... -> From Template -> Flex Dashboard

<br><br>

**DEMO**

## Layouts

http://rmarkdown.rstudio.com/flexdashboard/layouts.html

# Debugging

## Debugging tips for R Markdown

- Line number in error message -- note that this will refer to the beginning of the R chunk, hence shorter R chunks make debugging easier

- `knitr::knit_exit()`: stop knitting HERE

# More with R Markdown

## More with R Markdown

- Slide presentations
    + `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

- Websites: `rmarkdown::render_site`

- Interactive documents: with `htmlwidgets` or `Shiny`