May 30, 2014 @ Great Plains R-Users Group Conference

About me

  • http://yihui.name
  • first language: Chinese
  • second language: R (10 years)
  • third language: English

Dynamic Documents

I know you click, click, copy and paste

But imagine you hear these words after you finished a project

Please do that again! (sorry we made a mistake in the data, want to change a parameter, and yada yada)

Basic idea

  • 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

knitr

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

What keeps us busy?

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

Or a graphical comparison

LaTeX

Markdown

RPubs

Original Markdown

  • primarily for HTML
  • paragraphs, # headers, > blockquotes
  • phrase _emphasis_
  • - lists
  • [links](url)
  • ![images](url)
  • code blocks

Is Markdown too simple?

probably, but the real question is

How much do you want?

do you really want that word to be in \textbf{\textsf{}}?

To print or not to print, that is the question

  • LaTeX is for printing
  • HTML is not as powerful in terms of typsetting (not bad either!), but is excellent for interaction
  • examples

R Markdown

FAQ: How can I convert Markdown to Word?

We used to tell them "go to Pandoc".

R Markdown v2

Now we go to Pandoc and solve the problem directly.

Markdown with Pandoc

Pandoc's Markdown extensions

  • tables
  • LaTeX math $\sum_{i=1}^n \alpha_i$ = \(\sum_{i=1}^n \alpha_i\)
  • YAML metadata
  • raw HTML/LaTeX

    <div class="my-class">
      ![image](url)
    </div>
    
    _emphasis_ and \emph{emphasis}
  • footnotes ^[A footnote here.]
  • citations [@joe2014]

Pandoc's Markdown Output

  • LaTeX/PDF
  • beamer
  • HTML
  • ioslides
  • reveal.js
  • Word (MS Word, OpenOffice)
  • E-books

rmarkdown

The rmarkdown package

  • do you want to mess with
    • Pandoc's 73 command line arguments?
    • knitr's 49 chunk options?
  • rmarkdown provides wrappers that produce reasonably beautiful output by default

Installation and usage

  • http://rmarkdown.rstudio.com
  • rmarkdown and Pandoc are currently shipped with RStudio preview version
  • can be used as a standalone package as well (require separate Pandoc installation)

    library(rmarkdown)
    render('input.Rmd')
    render('input.Rmd', pdf_document())
    render('input.Rmd', word_document())
    render('input.Rmd', beamer_presentation())
    render('input.Rmd', ioslides_presentation())

YAML metadata

---
title: "Sample Document"
output:
  html_document:
    toc: true
    theme: united
---

This is equivalent to:

rmarkdown::render('input.Rmd',
    html_document(toc = TRUE, theme = 'united'))

RStudio IDE support

You do not have to remember everything

  • new markdown document wizard
  • setting YAML metadata
  • one-click compilation
  • navigation between Rmd source and slides

Demo

Interactive Reports

Shiny

Where shiny meets knitr

  • a document is both dynamic and interactive
  • knitr: R Markdown –> Markdown
  • rmarkdown: Markdown –> HTML
  • shiny: HTML <–> R
  • demo

The goal

You have done the hard work of research, data collection, and analysis, etc. We hope the last step can be easier.