• 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

packages <- c("dplyr", "ggplot2", "rmarkdown", "knir", 
              "DT", "flexdashboards")
install.packages(packages)
lapply(packages, library, character.only = TRUE)

• 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 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

If you have not yet done so:

install.packages("rmarkdown")
library(rmarkdown)

(in case you're interested…)

• 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.

• If you have not yet done so:
  • Load the following packages:

  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

DEMO

• 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

• Code chunks

• Inline code

• 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 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 for all options.

cache = TRUE

Tricky, but can be useful!

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

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

DEMO

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

• 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…

DEMO

• 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)

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

• 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.packages("flexdashboard")
library(flexdashboard)

In RStudio:

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

DEMO

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

• 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

• 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