May 15, 2014

About me

  • http://yihui.name
  • first language: Chinese
  • second language: R (10 years)
  • third language: English
  • graduated from Iowa State Univ (Stats, 2013)
  • joined RStudio
  • (co-)author and maintainer of some R packages (e.g. animation, knitr, cranvas, formatR, testit, highr, Rd2roxygen, fun, servr, tikzDevice, shiny, evaluate, markdown)
  • initiated the Chinese R Conference in 2008 (7th this year)
  • Capital of Statistics (http://cos.name)

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

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

Original Markdown

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

Pandoc's Markdown

  • 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 (cont'd)

  • types of output document
    • 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.

Try it yourself!

Don't just believe everything I said…