March 5, 2014

Dynamic Documents

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]`.

One world, many dreams

worse, one world == one (MS) Word?

\section{Introduction}

We did a \emph{cool} study.
<h1>Introduction</h1>

<p>We did a <em>cool</em> study.</p>

Markup Languages

Two extremes

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

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{}}?

Why R Markdown v2?

R Markdown v1: 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

  • we used to call knitr and Pandoc separately

    # in R
    library(knitr)
    knit('input.Rmd')
    # in command line
    pandoc -to beamer -o output.pdf –smart input.md
  • 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://www.rstudio.com/ide/download/preview
  • https://github.com/rstudio/rmarkdown
  • 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'))

What is html_document()

str(rmarkdown::html_document(), 2)
## List of 5
##  $ knitr           :List of 3
##   ..$ opts_knit : NULL
##   ..$ opts_chunk:List of 5
##   ..$ knit_hooks: NULL
##  $ pandoc          :List of 3
##   ..$ to  : chr "html"
##   ..$ from: chr "markdown+autolink_bare_uris+ascii_identifiers+tex_math_single_backslash-implicit_figures"
##   ..$ args: chr [1:5] "–section-divs" "–smart" "–self-contained" "–template" …
##  $ clean_supporting: logi TRUE
##  $ format_filter   :function (output_format, files_dir, input_lines)
##  $ post_processor  : NULL
##  - attr(*, "class")= chr "rmarkdown_output_format"

Output format is extensible

title: "Sample Document"
output:
  my_nice_document:
    fig_width: 8
    toc: true

my_nice_document() is your own function that returns a list of knitr and Pandoc options.

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

The goal

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