← Previous Tutorial useR! 2016 Tutorials

Post-tutorial notes

The materials used in the tutorial are available here.

Tutorial Description

This is an intermediate/advanced level tutorial on dynamic documents with R Markdown. It starts with the basic idea of literate programming as well as its role in reproducible research. Among all document formats that knitr supports, we will only focus on R Markdown (.Rmd). We will give an overview of existing output formats in rmarkdown, and explain how to customize them. We will show how to build new output format functions by extending exising formats. The packages tufte and bookdown will be used as examples. We will mention other applications related to R Markdown such as HTML widgets [Vaidyanathan et al., 2015], Shiny documents [Chang et al., 2015], and how to run code from other languages (C, C++, and so on).

Goals

Markdown is a fairly simple language, but it has a lot potential when combined with the power of Pandoc and R. Basically we want attendees to be able to create sophisticated applications based on this simple language. The goals of this tutorial include:

• learn the basic idea of literate programming and apply it to data analysis using dynamic documents
• learn how to use and customize existing output formats in rmarkdown
• learn how to create new output formats based on existing formats
• learn how to author a long-form document such as a book using bookdown
• understand how HTML widgets and Shiny apps work in R Markdown

Tutorial Outline

First hour: An intermediate introduction to R Markdown.

• Pandoc’s Markdown syntax, e.g. how to write citations, tables, rawLaTeX/HTML, etc
• An overview of R Markdown output formats (HTML, PDF, Word, presentations, and so on)
• How to customize existing output formats
  • Basic format options, e.g. TOC, numbered/unnumbered sections, etc
  • Pandoc templates (how to write a template and apply it, how to pass variables to Pandoc templates)
  • Customize CSS for HTML output
  • Build websites from R Markdown and host them (e.g. on Github)
  • Customize LaTeX preamble for PDF output
  • Customize Word templates (header/footer, font styles, etc)

Second hour: Build new output formats based on existing formats.

• A closer look at the structure of an output format object
  • knitr options (chunk options, hooks, etc)
  • Pandoc options
  • pre/post-processor functions
• Examples of new formats, e.g. html_vignette() and the tufte package (tufte::tufte_html(), and tufte::tufte_handout())
• How to author a long-form document using bookdown
  • Cross-references of figures/tables/sections
  • Separate HTML pages for chapters

Third hour: Other applications.

• HTML widgets: port JavaScript libraries into R using the htmlwidgets package, and how to render them in R Markdown
• Interactive Shiny documents: embed shiny apps in R Markdown
• Run code from other languages in R Markdown (C, C++, Python, and so on)
• Build completely new output formats such as e-books

Background Knowledge

The attendees should know the basics of knitr and R Markdown. This is not an introductory tutorial, so we are not going to talk about basic concepts such as the syntax of code chunks and Markdown. To benefit as much as possible from the tutorial, the attendees should have some knowledge about HTML/CSS, JavaScript, and LaTeX.

Instructor Biography

Yihui Xie (http://yihui.name) is currently a software engineer at RStudio (http://www.rstudio.com). He earned his PhD from the Department of Statistics, Iowa State University. As an active R user, he has authored several R packages, including animation, knitr, formatR, fun, mime, highr, servr, and Rd2roxygen, among which the animation package won the 2009 John M. Chambers Statistical Software Award (ASA), and the knitr package was awarded the “Honorable Mention” prize in the “Applications of R in Business Contest 2012” (Revolution Analytics). In 2006, he founded the “Capital of Statistics” (http://cos.name), which has grown into a large online community on statistics in China. He initiated the first Chinese R conference in 2008, and has been organizing R conferences in China since then. In recent years, R conferences in China can attract more than 3,000 attendees. During his PhD training at Iowa State University, he won the Vince Sposito Statistical Computing Award (2011) and the Snedecor Award (2012) in the Department of Statistics.

He gave a tutorial “Dynamic Documents with R and knitr” at useR! 2014 (UCLA, http://user2014.stat.ucla.edu), and about 50 people attended the tutorial. He is the main author of the R packages knitr, tufte, and bookdown, and a co-author of rmarkdown. The tutorial will cover all these packages. He has published a book “Dynamic Documents with R and knitr”, and has given talks about knitr and R Markdown many times (http://yihui.name/en/vitae/).