\[ %% % Add your macros here; they'll be included in pdf and html output. %% \newcommand{\R}{\mathbb{R}} % reals \newcommand{\E}{\mathbb{E}} % expectation \renewcommand{\P}{\mathbb{P}} % probability \]

Technical notes

Peter Ralph

June 2, 2015

It might help to have an up-to-date pandoc. You can probably get an installer for the most recent version here.

pandoc invocation

General

Slides

For presentations

See the documentation

Other notes on making slides

A paragraph with three dots:

. . .

makes a pause.

Other styles of presentation

There are various styles of presentation available.

I ended up using reveal.js, so it’s included as a submodule, but slidy looked pretty good, too. Here’s notes on getting the prerequisites. There are rules in the Makefile to build the rest of these.

  1. reveal.js : pandoc 1.12 works only with reveal.js <= 2.6.2.

    So, if your pandoc is old, do this:

  2. S5 :

  3. dzslides : No setup, but seems to be broken.

  4. slidy : No setup, downloads from [w3c.org]

  5. slideous : Doesn’t seem to produce a slideshow?

knitr and such

Options for rendering using R

There are methods in the Makefile for rendering with each of these methods.

Codeblocks and knitr

knitr just uses a regular expression to identify chunks of code to parse:

knitr::all_patterns$md$chunk.begin
## "^[\t >]*```+\\s*\\{[.]?([a-zA-Z]+.*)\\}\\s*$"

knitr::all_patterns$md$chunk.end
## [1] "^[\t >]*```+\\s*$"

Yihui’s trick for getting around this is to use R to insert an "" into the preamble, like so:

 ``r ""```

Parsed that?

Here’s an inline example:

inline `R` code (`` ``r "r nrow(data)"`` ``)

Alternatively, you can make the patterns knitr uses to catch code blocks more strict. Here’s from the Makefile for this presentation:

KNITR_PATTERNS = list( chunk.begin="^```+\\s*\\{[.]?(r[a-zA-Z]*.*)\\}\\s*$$", chunk.end="^```+\\s*$$", inline.code="`r +([^`]+)\\s*`")

%.md : %.Rmd
    cd $$(dirname $<); Rscript -e 'knitr::knit_patterns[["set"]]($(KNITR_PATTERNS)); knitr::knit(basename("$<"),output=basename("$@"))'

Knitr and working directories

Yihui says that setwd() is evil, because it is not reproducible. knit() works from the directory the .Rmd file is in. You can change the directory knitr works in using

opts_knit$set(root.dir=NEW.DIR)

Since this is interpreted relative to the working directory of the R session that calls knitr, it may be best to always set

opts_knit$set(root.dir=".")

in templates. (But, beware of any dependencies!)

Note: some people try to call setwd() within their .Rmd file. But, knitr resets this for each chunk (and, chastises you!).

knitr and for loops

If knitr doesn’t always make plots/output every time around the for loop, the problem might be there’s an error or something early on?

Tables

One option: use xtable + results="asis".

 ```{r results="asis"}
 library(xtable)
 dtab <- xtable( table( sample( letters, 300, replace=TRUE ) ) )
 print(dtab,type='html')
 ```

More on templates

Currently (8/17/2015), rmarkdown’s render function cannot be used for templates that might be compiled at the same time with different data. There is no workaround. This is too bad, because render parses the YAML header, and makes the resulting html look nice. Let’s look under the hood to see how to replicate it. Here’s the call to pandoc:

pandoc:

We can trim this down to

MATHJAX=/usr/share/javascript/mathjax/MathJax.js  # for local mathjax
PANDOC_OPTS="--to html --from markdown-implicit_figures \\
    --standalone --self-contained --section-divs --template template.html \\
    --variable 'theme:bootstrap' --include-in-header resources/header-scripts.html \\
    --mathjax --variable mathjax-url:$MATHJAX?config=TeX-AMS-MML_HTMLorMML'"

So, now to turn input.Rmd into output.html, in a safe way, we need to get the header-scripts file and then run

R --vanilla -e 'knitr::knit("input.Rmd",output="output.md")'
pandoc output.md ${PANDOC_OPTS} --output output.html

Formatting and layout

Customization

Options:

About math rendering

There are many options, but probably --mathjax is the best?

Note that it is supposed to render as far as possible with unicode, but this m\(a\)y depend on the proper fonts being installed?

Other types of text: line blocks

These are just markdown except it pays attention to linebreaks.

| Molecular & Computational Biology
| University of Southern California
| 1050 Child Way, RRI 201 (MCB)
| Los Angeles, CA 90089-2910

produces

Molecular & Computational Biology
University of Southern California
1050 Child Way, RRI 201 (MCB)
Los Angeles, CA 90089-2910

Other types of text: definition lists

To make a definition list

Each term must fit on one line, which may optionally be followed by a blank line, and must be followed by one or more definitions. A definition begins with a colon or tilde, which may be indented one or two spaces.

A term may have multiple definitions, and each definition may consist of one or more block elements (paragraph, code block, list, etc.), each indented four spaces or one tab stop. The body of the definition (including the first line, aside from the colon or tilde) should be indented four spaces.

Self-contained documents

HTML documents can stitch together lots of different pieces: images, css, javascript, etcetera. These are not nice to email.

But: pandoc can produce self-contained documents, that are email-ready. rmarkdown does this by default.

Warning: the best way of displaying math relies on mathjax, which is a “large” javascript library, and is not included. If you use LaTeX math, you need to host a local copy of mathjax.

Other technicalities