A tour through knitr

Yihui Xie
2013/07/29 @ VTN Stats Meeting

Two challenges

  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;

The knitr book

Outline

  • simple examples
  • editors
  • document formats
  • text output
  • graphics
  • cache
  • cross references
  • hooks
  • language engines
  • some tricks
  • what's new

Simple examples

RPubs

How does it work

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

Editors

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

Document formats

  • 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

Conventional file extensions

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

spin()

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

Text output

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

Graphics

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

Cache

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

Cross references

  • 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

Hooks

  • 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

Engines

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

Tricks

  • 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

R Presentations (RStudio)

Package vignettes

Nice themes

  • tables
  • Docco
browseVignettes(package = "knitr")

I hope after this tour, ...

you will tell your colleagues

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

Questions?