• https://yihui.org
• first language: Chinese
• second language: R (10 years, authored a few R packages)
• third language: English
• graduated from Iowa State U
• working for RStudio

This is an intermediate level tutorial on dynamic reporting with R and the knitr package (https://yihui.org/knitr). It covers the basic idea of literate programming as well as its role in reproducible research.

A variety of document formats will be introduced, including R LaTeX (.Rnw) and R Markdown (.Rmd). We will show useful features of knitr, such as creating tables and plots from data, caching, and cross references.

We will also provide examples of advanced features such as chunk hooks, and calling foreign languages (shell scripts, Python, C++, Julia, …).

• learn the basic idea of literate programming and apply it to data analysis using dynamic documents
• know the basics about knitr
• understand the meanings of common chunk options
• learn how to extend knitr using chunk hooks and other languages
• create projects and build (web) applications based on knitr

• code + narratives = report

• i.e. computing languages + authoring languages

  We built a linear regression model.
  
  ```{r}
  fit <- lm(dist ~ speed, data = cars)
  b   <- coef(fit)
  plot(fit)
  ```
  
  The slope of the regression is `r b[1]`.

• an example

• WEB (Donald Knuth, Literate Programming)
  • Pascal + LaTeX
• Noweb (Norman Ramsey)
• Sweave (Friedrich Leisch and R-core)
  • R + LaTeX
  • extensible, in the sense that you copy 700 lines of code to extend 3 lines
  • cacheSweave, pgfSweave, weaver, …
• knitr (me and contributors)
• odfWeave (Max Kuhn, OpenOffice)
• rapport/pander (Aleksandar Blagotić and Gergely Daróczi, Markdown/Pandoc)
• slidify (Ramnath Vaidyanathan, knitr/R Markdown)

• Org-mode (Emacs)
• SASweave
• Python tools
  • IPython
  • Dexy
  • PythonTeX

• an R package (install.packages('knitr'))
• document formats
  • .Rnw (R + LaTeX)
  • .Rmd (R + Markdown)
  • any computing language + any authoring language (in theory)
• editors
  • RStudio
  • LyX (example later)
  • …
• resources
  • https://yihui.org/knitr
  • Dynamic Documents with R and knitr (Chapman & Hall, 2013)

if (!require("knitr")) install.packages("knitr")
library(knitr)
knit("your-document.Rmd")  # compiles a document

• report = text (prose, narrative) + code
• code chunk = chunk header (chunk options) + code
• 02-minimal.Rmd
• 03-minimal.Rnw
• https://github.com/yihui/knitr-examples/
• the RStudio support
• the LyX editor (04-knitr-minimal.lyx)

• give me an R script, and I give you a report

• internally converted to R Markdown/LaTeX/…

  #' today I built a model
  fit = lm(dist ~ speed, data = cars)
  
  #' and I got the slope `r coef(fit)[2]`
  
  #+ dist-speed, fig.width=5, fig.height=4
  plot(cars)
  abline(fit)

• demo: knitr::spin('05-knitr-spin.R')

• insert an R script in a predefined template
• LaTeX, HTML or Markdown
• demo: knitr::stitch('06-stitch-test.R')

• echo: TRUE/FALSE, c(i1, i2, …), -i3
• results: markup, hide, hold, asis
• collapse: TRUE/FALSE
• warning, error, message
• strip.white
• include
• demo: 07-test.Rmd

• dev, dev.args, fig.ext
  • PDF, PNG, …
  • tikz
• fig.width, fig.height
• out.width, out.height, fig.retina
• fig.cap
• fig.path
• fig.keep
• fig.show
• demo: 08-graphics.Rmd

• basic idea: use cache if source is not modified
• implementation: digest
• demo: 09-cache.Rmd

• embed chunks with <<label>>
• reuse whole chunks using the same label
• use ref.label
• demo: 10-references.Rmd

• the chunk option child
• the function knit_child()
• demo: 11-main.Rmd

• additional tasks attached to chunk options

  knit_hooks$set(opt_name = function(before, options) {
      if (before) 
          do_something() else do_something_else()
  })

• set the chunk option opt_name to a non-NULL value to activate the chunk hook

• the chunk option engine
• shell scripts
• Python

• Julia (experimental)

  names(knitr::knit_engines$get())

  ##  [1] "awk"       "bash"      "coffee"    "gawk"      "haskell"  
  ##  [6] "perl"      "python"    "Rscript"   "ruby"      "sas"      
  ## [11] "scala"     "sed"       "sh"        "zsh"       "highlight"
  ## [16] "Rcpp"      "tikz"      "dot"       "c"         "fortran"  
  ## [21] "asy"       "cat"       "asis"

• the runr package (experimental)

• demo: 12-python.Rmd, 14-julia.Rmd

• the UCLA R Tutorial website
  • e.g. http://www.ats.ucla.edu/stat/r/modules/prob_dist.htm
• Jekyll
  • blog like a hacker
  • based on Markdown, supported by Github
  • Rcpp gallery: http://gallery.rcpp.org
  • Vistat: http://vis.supstat.com
• WordPress
  • https://yihui.org/knitr/demo/wordpress/
  • the shinyWP package (under development) https://github.com/yihui/shinyWP

• Gentleman and Temple Lang (2004)
• one R package to rule them all!
• data, R, man, tests, demo, src, vignettes
• VignetteBuilder: knitr in DESCRIPTION
• \VignetteEngine{knitr::knitr} in vignettes
• see details

# see list of vignettes
help(package = "knitr", help_type = "html")
# Docco Classic Style

• LyX + knitr
• https://github.com/yihui/knitr-book
• Why LyX: https://yihui.org/en/2012/10/lyx-vs-latex/
• writing a book: https://yihui.org/en/2013/06/tips-for-writing-an-r-book/
• reproducibility: https://yihui.org/en/2013/09/cannot-reproduce-my-own-book/

• courses, blog posts, workshops, papers, R packages, …
• https://yihui.org/knitr/demo/showcase/

• keyword: automation
• the Duke Saga: http://www.economist.com/node/21528593
• not easy for large projects

• Reproducible package management for R
• J.J. Allaire, Packrat - A Dependency Management System for R, Session 5 Wednesday, 16:00, Kaleidoscope

• LaTeX: precise control, full complexity, horrible readability
• Markdown: simple, simple, simple

\section{Introduction}

We did a \emph{cool} study,
and our main findings:


\begin{enumerate}
\item You can never remember
  how to escape backslashes.
\item A dollar sign is \$,
  an ampersand \&, and
  a \textbackslash{}.
\item How about ~? Use $\sim$.
\end{enumerate}

# Introduction

We did a _cool_ study, and
our main findings:

1. You do not need to remember
  a lot of rules.
2. A dollar sign is $,
  an ampersand is &, and
  a backslash \.
3. A tilde is ~.

Write content instead of
markup languages.

• http://rpubs.com
• forget about reproducible research, because you are doing it unconsiously

• LaTeX is for printing
• HTML is not as powerful in terms of typesetting (not bad either!), but is excellent for interaction
• examples
  • the docco_classic style
  • gitbook

• the power of Pandoc and its Markdown extensions
• Jeff Allen, The Next Generation of R Markdown, Session 6 Thursday, 10:00, Kaleidoscope