A tour through knitr

1. remember what I did in Excel, and repeat that after this talk;
2. remember the analysis I did, and repeat it after I correct a wrong data point, or repeat it over 100 similar datasets;

• a large collection of examples on Github: https://github.com/yihui/knitr-examples
• R + LaTeX: 002-minimal.Rnw
• R + Markdown: 001-minimal.Rmd

• http://rpubs.com
• tons of reports (R Markdown + knitr + RStudio)

library(knitr)
# knit('input_file.ext'); for example
knit("whatever.Rmd")  # ==> whatever.md
knit("whatever.Rnw")  # ==> whatever.tex

• RStudio (well supported)
  • interactively run R code chunks
  • auto-completion
  • Rnw/PDF forward/backward search
  • error navigation
• LyX (LaTeX wrapper)
• Emacs/ESS

• any computing language (not yet)
  • R, Python, Perl, C++, shell scripts, awk, sed, CoffeeScript, Julia, …
  • even SAS
• any authoring language
  • LaTeX, HTML, Markdown, reSructuredText, AsciiDoc

• .Rnw: R/… + LaTeX
• .Rmd: R/… + Markdown
• .Rhtml: R/… + HTML
• .Rrst: R/… + reStructuredText
• .Rascii: R/… + AsciiDoc
• some quick examples

• a special R script
• text in #', and code as usual
• optional chunk headers in #+
  • system.file('examples', 'knitr-spin.R', package = 'knitr')

#' 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)

• eval, echo, results
• tidy, highlight
• comment
• message, warning, error
• include

• graphical device
• figure size, output size
• alignment
• animation
• figure path

• if you do not change anything, just load the old results
• lazyLoad(): do not load unless it is really used anywhere
• dependencies: how to properly invalidate cache
  • dependson: chunk B depends on chunk A
  • dep_prev()

• reuse code chunks, referenced by chunk labels
  • use empty chunks with the same label
  • use <<label>> to embed one chunk into another
  • use the chunk option ref.label
• reuse documents
  • the chunk option child

• you can decide how to wrap up the output
  • source, output, warning, message, error, plot, chunk
  • control by knit_hooks$set(hook_name = function(x, options) { whatever you want})
• you can run additional tasks before/after a chunk
  • knit_hooks$set(new_name = function(before, options, envir) { whatever you want })
  • e.g. you can send a twitter message after a chunk has been finished

• use the engine option, e.g. engine = 'python', engine = 'awk'
• see knitr-examples/.*engine.*.Rmd (e.g. 023)
• almost all features present in R also apply to these foreign languages
  • echo, eval, results, cache, …

• construct a dynamic document
  • knit(text = 'construct your document here')
  • see example 021
• externalize R code
  • write code chunks under # ---- label, options ----
  • and read_chunk()
  • then use cross references

• RStudio 0.98 (not released yet)

• 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

• tables
• Docco

browseVignettes(package = "knitr")

you will tell your colleagues

stop cut-and-paste! let's use knitr!

• documentation: https://yihui.org/knitr (video)
• development: https://github.com/yihui/knitr
• examples: https://github.com/yihui/knitr-examples
• questions go to StackOverflow