Rendering markdown with pander

knitr::opts_chunk$set(collapse = T, comment = "#>")
library(pander)
library(tables)
panderOptions('knitr.auto.asis', FALSE)
panderOptions('plain.ascii', TRUE)

Pander is designed to provide a minimal and easy tool for rendering R objects into Pandoc's markdown. This vignette aims to introduce the pander package and its core pieces of functionality. It is intended to be a general overview with pointers to places with detailed information. This vignette will talk about:

Rendering R objects

The core functionality of pander is centered around rendering R objects into Pandoc's markdown. Let's dive in to a demo of the most common usage of pander:

pander(head(iris))
pander(head(mtcars[1:5]))
pander(tabular( (Species + 1) ~ (n=1) + Format(digits=2)*
         (Sepal.Length + Sepal.Width)*(mean + sd), data=iris ))

As you have probably guessed, this is achieved via the generic pander S3 method. Out of the box, pander supports a variety of classes:

methods(pander)

If you think that pander lacks support for any other R class(es), please feel free to open a ticket suggesting a new feature or submit pull request and we will be happy to extend the package.

Under the hood, pander S3 methods rely on different pandoc.* methods, where most of functionality is implemented in pandoc.table which is used for rendering tables. pandoc.table provides functionality similar to knitr::kable in rendering markdown, but also adds a truly rich functionality with a variety of rendering options inherited from pander. For more usage/implementation details and examples, please refer to the pandoc.table vignette, which can be accessed by vignette('pandoc_table') (and is also available online).

Evals

The pander package was originally developed in conjunction with rapport package, when a need arose for a function that could evaluate R expressions while also capturing errors and warnings. So evals emerged and soon some further feature requests arose, like identifying if an R expression results in a plot, etc.

But probably it's easier to explain what evals can do with a simple example:

evals('1:10')

evals is aimed at collecting as much information as possible while evaluating R code. It can evaluate a character vector of R expressions, and it returns a list of information captured while running them:

For more usage/implementation details and examples, please refer to the evals vignette, which can be accessed by vignette('evals') (also available online).

Brew to Pandoc

The brew package, a templating framework for report generation, has not been updated since 2011, but it's still some of R projects based on its simple design and useful literate programming features. For a quick overview, please see the following documents if you are not familiar with brew:

A brew document is a simple text file with some special tags. Pandoc.brew uses only two of them (as building on a personalized version of Jeff's really great brew function):

The latter tries to be smart in some ways:

Besides this, the custom brew function can do more and also less compared to the original brew package. First of all, the internal caching mechanism of brew has been rewritten for benefits besides improved caching. Quick example:

str(Pandoc.brew(text ='Pi equals to `<%= pi %>`. And here are some random data: `<%= runif(10)%>`'))

The package bundles some examples for Pandoc.brew to let you quickly check its features. To brew these examples on your machine, run the following commands:

Pandoc.brew(system.file('examples/minimal.brew', package='pander'))
Pandoc.brew(system.file('examples/minimal.brew', package='pander'),
            output = tempfile(), convert = 'html')

Pandoc.brew(system.file('examples/short-code-long-report.brew', package='pander'))
Pandoc.brew(system.file('examples/short-code-long-report.brew', package='pander'),
                        output = tempfile(), convert = 'html')

Pandoc.brew(system.file('examples/graphs.brew', package='pander'))
Pandoc.brew(system.file('examples/graphs.brew', package='pander'),
                        output = tempfile(), convert = 'html')

General Options

The package comes with a variety of globally adjustable options that have an effect on the result of your reports. A full list of options can be viewed by calling ?panderOptions or in the online readme.

You can query and update these options with the panderOptions function:

pots <- panderOptions("table.style")
panderOptions("table.style", "simple")
pander(mtcars[1:3, 1:4])
pander(head(iris))
panderOptions("table.style", "grid")
pander(head(iris))
panderOptions("table.style", pots)


Try the pander package in your browser

Any scripts or data that you put into this service are public.

pander documentation built on Aug. 6, 2017, 5:05 p.m.