pander: An R Pandoc Writer

The main aim of the pander R package is to provide a minimal and easy tool for rendering R objects into Pandoc's markdown. The package is also capable of exporting/converting complex Pandoc documents (reports) in various ways. Regarding the difference between

pander

Current build and test coverage status: .

Some CRAN statistics:

Installation

The stable version can be installed easily in the

R

install.packages('pander')

On the other hand, I welcome everyone to use the most recent version of the package with quick-fixes, new features and probably new bugs. It's currently hosted on GitHub. To get the latest development version from GitHub of the

devtools

devtools::install_github('Rapporter/pander')

Or download the sources and build manually. If you're running R on Windows, you will need to install Rtools.

Dependencies

Few cool packages from CRAN are needed for installing and/or using

pander

• digest to compute hashes while caching,
• Rcpp to compile certain functions used by the package.

And there are also a few optional suggested or supported R packages, such as:

• sylly to use hyphenation when splitting large table cells,
• lattice and ggplot2 for unified plot theme,
• futile.logger for logging capabilities inside

  evals

  ,
• survival, microbenchmark, zoo, nlme, descr, MASS, tables, reshape, memisc, Epi, randomForest, tseries, rms packages include some supported R classes,
• and pander can be also very useful inside of knitr. More information about how to use pander and knitr can be found specialized vignette, which can be accessed by

  vignette('knitr', package = 'pander')

  or available online here.

Pandoc

pander heavily builds on Pandoc, which should be pre-installed before trying to convert your reports to different formats. Although main functions work without Pandoc, e.g. you can transform R objects into markdown or generate a markdown formatted report via Pandoc.brew or the custom reference class, but installing that great piece of software is suggested if you want to convert markdown to PDF/docx/HTML or other formats.

Starting v0.98.932 RStudio comes with a bundled

Pandoc

If you do not have RStudio installed, please refer to the installation process of Pandoc, which is quite straightforward on most-popular operating systems: download and run the binary (a few megabytes), and get a full-blown document converter in a few seconds/minutes. On some Linux distributions, it might be a bit more complicated (as repositories tend to provide out-dated versions of Pandoc, so you would need

cabal-install

PATH

Helper functions

The package contains numerous helper functions, which render user specified inputs in Pandoc's markdown format or apply some extra formatting on it. All Pandoc-related functions' names are starting with

pandoc

pandoc.table

All

pandoc

.return

pandoc.table.return

?pandoc.strong

The full list of currently available primitive Pandoc-related functions are:

• pandoc.indent
• pandoc.p
• pandoc.strong
• pandoc.emphasis
• pandoc.strikeout
• pandoc.verbatim
• pandoc.link
• pandoc.image
• pandoc.date
• pandoc.formula
• pandoc.footnote
• pandoc.horizontal.rule
• pandoc.header
• pandoc.title

For example there is a helper function rendering R lists into markdown:

> l  pandoc.list(l, 'roman')

Which command produces the following output: ``` I. First list element I. 1. subelement II. 2. subelement III. 3. subelement IV. 4. subelement V. 5. subelement
II. Second element I. F II. B III. I I. phone II. pad III. talics

# Markdown tables

One of the most popular feature in *pander* is `pandoc.table`, rendering most tabular R objects into markdown tables with various options and settings (e.g. [style](#style), [caption](#caption), [cell highlighting](#highlight-cells), [cell alignment](#cell-alignment), [width](#table-and-cell-width)). This section aims to provide quick introduction to most common options, but for more usage/implementation details and examples, please refer to specialized vignette, which can be accessed by `vignette('pandoc_table')` or available online [here](http://rapporter.github.io/pander/pandoc_table.html).

Let's start with a small example:

```r
> pandoc.table(mtcars[1:3, 1:4])

Which command produces the following output by default:

```

            mpg   cyl   disp   hp 

Mazda RX4 21 6 160 110

Mazda RX4 Wag 21 6 160 110

Datsun 710 22.8 4 108 93

Please note that all below features are also supported by the more concise pander generic S3 method!
Formats
All four Pandoc formats are supported by pander. From those (multiline, simple, grid, pipe/rmarkdown), I'd suggest sticking to the default multiline format with the most features, except when using rmarkdown v1.0 or jupyter notebook, where multiline is not supported (for this end the default table format is rmarkdown when pander is called inside of a jupyter notebook). Please see a few examples below:

The default style is the multiline format (except for calling pander inside of a of a jupyter notebook) as most features (e.g. multi-line cells and alignment) are supported:
```rout
> m  pandoc.table(m)

            mpg   cyl   disp 

   Mazda RX4     21     6    160  
 Mazda RX4 Wag   21     6    160  

While

simple

> pandoc.table(m, style = "simple")

            mpg   cyl   disp 

   Mazda RX4     21     6    160
 Mazda RX4 Wag   21     6    160  

My personal favorite, the

grid

> pandoc.table(m, style = "grid")

+---------------------+-------+-------+--------+
|                |  mpg  |  cyl  |  disp  |
+=====================+=======+=======+========+
|    Mazda RX4    |  21   |   6   |  160   |
+---------------------+-------+-------+--------+
|  Mazda RX4 Wag  |  21   |   6   |  160   |
+---------------------+-------+-------+--------+

And the so called

rmarkdown

knitr

markdown

> pandoc.table(m, style = "rmarkdown")





mpg
cyl
disp



Mazda RX4
21
6
160


Mazda RX4 Wag
21
6
160

But once again, you should simply stick to the default multiline table format in most cases. Otherwise, it's wise to update the default table format via

panderOptions

Caption

It's really easy to add a caption to a table:

> pandoc.table(m, style = "grid", caption = "Hello caption!")

+---------------------+-------+-------+--------+
|                |  mpg  |  cyl  |  disp  |
+=====================+=======+=======+========+
|    Mazda RX4    |  21   |   6   |  160   |
+---------------------+-------+-------+--------+
|  Mazda RX4 Wag  |  21   |   6   |  160   |
+---------------------+-------+-------+--------+
Table: Hello caption!

For more convenient and flexible usage, you might be interested in the special

set.caption

> set.caption("Hello caption!")
> pandoc.table(m)


            mpg   cyl   disp 

   Mazda RX4     21     6    160  
 Mazda RX4 Wag   21     6    160  
Table: Hello caption!

Unless

permanent

TRUE

set.caption(NULL)

set.caption

permanent

FALSE

Highlighting cells

One of the fanciest features in pander is the ease of highlighting rows, columns or any cells in a table. This is a real markdown feature without custom HTML or LaTeX-only tweaks, so all HTML/PDF/MS Word/OpenOffice etc. formats are supported.

This can be achieved by calling

pandoc.table

pander

pandoc.table

• emphasize.italics.rows
• emphasize.italics.cols
• emphasize.italics.cells
• emphasize.strong.rows
• emphasize.strong.cols
• emphasize.strong.cells
• emphasize.verbatim.rows
• emphasize.verbatim.cols
• emphasize.verbatim.cells

The

emphasize.italics

emphasize.strong

emphasize.verbatim

verbatim

verbatim

Those functions and arguments ending in

rows

cols

cells

which(..., arr.ind = TRUE)

> t  emphasize.italics.cols(1)
> emphasize.italics.rows(1)
> emphasize.strong.cells(which(t > 20, arr.ind = TRUE))
> pandoc.table(t)


              mpg      cyl    disp       hp      drat 

   Mazda RX4     21   6  160 110 3.9 
 Mazda RX4 Wag   21    6    160   110   3.9  
  Datsun 710    22.8   4    108   93    3.85 

For more examples, please see our "Highlight cells in markdown tables" blog post.

Cell alignment

You can specify the alignment of the cells (left, right or center/centre) in a table directly by setting the

justify

> pandoc.table(head(iris[,1:3], 2), justify = c('right', 'center', 'left'))


  Sepal.Length  Sepal.Width  Petal.Length  

       5.1      3.5      1.4           

       4.9       3       1.4           

Or pre-define the alignment for (all future)

pandoc.table

pander

> set.alignment('left', row.names = 'right')
> pandoc.table(mtcars[1:2,  1:5])


           mpg   cyl   disp   hp   drat  

  **Mazda RX4** 21    6     160    110  3.9   
  Mazda RX4 Wag 21    6     160    110  3.9   

Just like with captions, you can also specify the

permanent

TRUE

set.alignment

pandoc.table

panderOptions

What's even more fun, you can specify a function that takes the R object as its argument to compute some unique alignment for your table based on e.g. column values or variable types:

> panderOptions('table.alignment.default',
+   function(df)
+     ifelse(sapply(df, mean) > 2, 'left', 'right'))
> pandoc.table(head(iris[,1:3], 2))


Sepal.Length   Sepal.Width     Petal.Length

5.1            3.5                      1.4
4.9            3                        1.4

Table and cell width

pandoc.table

split.table

> pandoc.table(mtcars[1:2, ], style = "grid", caption = "Hello caption!")

+---------------------+-------+-------+--------+------+--------+-------+
|                |  mpg  |  cyl  |  disp  |  hp  |  drat  |  wt   |
+=====================+=======+=======+========+======+========+=======+
|    Mazda RX4    |  21   |   6   |  160   | 110  |  3.9   | 2.62  |
+---------------------+-------+-------+--------+------+--------+-------+
|  Mazda RX4 Wag  |  21   |   6   |  160   | 110  |  3.9   | 2.875 |
+---------------------+-------+-------+--------+------+--------+-------+
Table: Hello caption! (continued below)
+---------------------+--------+------+------+--------+--------+
|                |  qsec  |  vs  |  am  |  gear  |  carb  |
+=====================+========+======+======+========+========+
|    Mazda RX4    | 16.46  |  0   |  1   |   4    |   4    |
+---------------------+--------+------+------+--------+--------+
|  Mazda RX4 Wag  | 17.02  |  0   |  1   |   4    |   4    |
+---------------------+--------+------+------+--------+--------+

And too wide cells can also be split by line breaks. The maximum number of characters in a cell is specified by

split.cells

split.tables

> df  pandoc.table(df, split.cells = 5)


  a     b    c  

Lorem dolor amet
ipsum  sit      

> pandoc.table(df, split.cells = c(5, 20, 5))

  a       b      c  

Lorem dolor sit amet
ipsum               

> pandoc.table(df, split.cells = c("80%", "10%", "10%"))

 a        b    c  

Lorem ipsum dolor amet
             sit      

If the

sylly

pandoc.table

> pandoc.table(data.frame(baz = 'foobar'), use.hyphening = TRUE, split.cells = 3)


 baz 
foo- 
 bar 

Minor features

Funtionality described in other sections is most notable, but

pander/pandoc.table

• plain.ascii

  - allows to have the output without

  markdown

  markup:

> pandoc.table(mtcars[1:3, 1:4])


            mpg   cyl   disp   hp 

   Mazda RX4     21     6    160   110 
 Mazda RX4 Wag   21     6    160   110 
  Datsun 710    22.8    4    108    93 
> pandoc.table(mtcars[1:3, 1:4], plain.ascii = TRUE)

                 mpg   cyl   disp   hp 

 Mazda RX4       21     6    160   110 
   Mazda RX4 Wag     21     6    160   110 
Datsun 710      22.8    4    108    93 

• missing

  - set a string to replace missing values:

> m  m$mpg  pandoc.table(m, missing = '?')


            mpg   cyl   disp   hp   drat 

   Mazda RX4      ?     6    160   110   3.9  
 Mazda RX4 Wag    ?     6    160   110   3.9  
  Datsun 710      ?     4    108    93   3.85 

• keep.line.breaks

  - allows to preserve line breaks inside cells. Not that by default

  pandoc.table

  automatically omits all line breaks found in each table cell to be able to apply the

  table.split

  functionality.

> m  pandoc.table(m)


   a      b   

foo bar pander
> pandoc.table(m, keep.line.breaks = TRUE)

 a    b   

foo pander
bar       

To see all possible options, please check

?pandoc.table

And please note, that all above mentioned features are also supported by the

pander

panderOptions

Generic pander method

pander

pandoc

S3

> methods(pander)
 [1] pander.anova*           pander.aov*             pander.aovlist*         pander.Arima*           pander.call*
 [6] pander.cast_df*         pander.character*       pander.clogit*          pander.coxph*           pander.cph*
[11] pander.CrossTable*      pander.data.frame*      pander.Date*            pander.default*         pander.density*
[16] pander.describe*        pander.evals*           pander.factor*          pander.formula*         pander.ftable*
[21] pander.function*        pander.glm*             pander.Glm*             pander.gtable*          pander.htest*
[26] pander.image*           pander.irts*            pander.list*            pander.lm*              pander.lme*
[31] pander.logical*         pander.lrm*             pander.manova*          pander.matrix*          pander.microbenchmark*
[36] pander.mtable*          pander.name*            pander.nls*             pander.NULL*            pander.numeric*
[41] pander.ols*             pander.orm*             pander.polr*            pander.POSIXct*         pander.POSIXlt*
[46] pander.prcomp*          pander.randomForest*    pander.rapport*         pander.rlm*             pander.sessionInfo*
[51] pander.smooth.spline*   pander.stat.table*      pander.summary.aov*     pander.summary.aovlist* pander.summary.glm*
[56] pander.summary.lm*      pander.summary.lme*     pander.summary.manova*  pander.summary.nls*     pander.summary.polr*
[61] pander.summary.prcomp*  pander.summary.rms*     pander.summary.survreg* pander.summary.table*   pander.survdiff*
[66] pander.survfit*         pander.survreg*         pander.table*           pander.tabular*         pander.ts*
[71] pander.zoo*

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.

Besides the most basic R object types (vectors, matrices, tables or data frames), list-support might be interesting for you:

> pander(list(a = 1, b = 2, c = table(mtcars$am), x = list(myname = 1, 2), 56))

A nested list can be seen above with a table and all (optional) list names. As a matter of fact,

pander.list

pander

> x  class(x)  pander(x)
 **WARNING**^[Chi-squared approximation may be incorrect]


statistic:

 X-squared
   20.94

parameter:

 df
 2

p.value: 2.831e-05

method: Pearson's Chi-squared test

data.name: table(mtcars$am, mtcars$gear)

observed:

    3   4   5

 0  15   4   0
 1   0   8   5

expected:

     3     4     5

 0  8.906 7.125 2.969
 1  6.094 4.875 2.031

residuals:

     3      4      5

 0  2.042  -1.171 -1.723
 1  -2.469 1.415  2.083

stdres:

     3      4      5

 0  4.395  -2.323 -2.943
 1  -4.395 2.323  2.943

So

pander

HTML

pdf

Pandoc.brew

But the output of different statistical methods are tried to be prettyfied. Some the above call normally returns like:

> pander(chisq.test(table(mtcars$am, mtcars$gear)))


 Test statistic   df      P value    

 20.94        2   2.831e-05 * * *

Table: Pearson's Chi-squared test: table(mtcars$am, mtcars$gear)
 WARNING^[Chi-squared approximation may be incorrect]

A few other examples on the supported R classes:

> pander(t.test(extra ~ group, data = sleep))


 Test statistic   df    P value   Alternative hypothesis 

 -1.861      17.78  0.07939         two.sided        

Table: Welch Two Sample t-test: extra by group
> ## Dobson (1990) Page 93: Randomized Controlled Trial (examples from: ?glm)
> counts  outcome  treatment  m  pander(m)

          Estimate   Std. Error   z value   Pr(>|z|) 

 (Intercept)    3.045       0.1709      17.81   5.427e-71 
  outcome2     -0.4543      0.2022     -2.247    0.02465  
  outcome3      -0.293      0.1927      -1.52     0.1285  
 treatment2   1.338e-15      0.2      6.69e-15      1     
 treatment3   1.421e-15      0.2      7.105e-15     1     
Table: Fitting generalized (poisson/log) linear model: counts ~ outcome + treatment
> pander(anova(m))

        Df   Deviance   Resid. Df   Resid. Dev 

   NULL      NA      NA          8         10.58    
  outcome    2     5.452         6         5.129    
 treatment   2   2.665e-15       4         5.129    
Table: Analysis of Deviance Table
> pander(aov(m))

        Df   Sum Sq    Mean Sq   F value   Pr(>F) 

  outcome    2     92.67     46.33     2.224    0.2242 
 treatment   2   8.382e-31 4.191e-31 2.012e-32    1    
 Residuals   4     83.33     20.83      NA        NA   
Table: Analysis of Variance Model
> pander(prcomp(USArrests))

        PC1     PC2      PC3      PC4   

  Murder   0.0417  -0.04482 0.07989  -0.9949 
 Assault   0.9952  -0.05876 -0.06757 0.03894 
 UrbanPop  0.04634  0.9769  -0.2005  -0.05817
   Rape    0.07516  0.2007   0.9741  0.07233 
Table: Principal Components Analysis
> pander(density(mtcars$hp))

          Coordinates   Density values 

  Min.       -32.12          5e-06      
 1st Qu.      80.69        0.0004068    
 Median       193.5         0.001665    
  Mean        193.5         0.002214    
 3rd Qu.      306.3         0.00409     
  Max.        419.1         0.006051    
Table: Kernel density of mtcars$hp (bandwidth: 28.04104)
> ## Don't like scientific notation?
> panderOptions('round', 2)
> pander(density(mtcars$hp))

          Coordinates   Density values 

  Min.       -32.12            0        
 1st Qu.      80.69            0        
 Median       193.5            0        
  Mean        193.5            0        
 3rd Qu.      306.3            0        
  Max.        419.1           0.01      
Table: Kernel density of mtcars$hp (bandwidth: 28.04104)

And of course tables are formatted (e.g. auto add of line breaks, splitting up tables, hyphenation support or markdown format) based on the user specified

panderOptions

Creating Pandoc documents

The package is also capable of creating complex Pandoc documents (reports) from R objects in multiple ways:

• create somehow a markdown text file (e.g. with

  brew

  ,

  knitr

  or any scripts of yours, maybe with

  Pandoc.brew

  - see just below) and transform that to other formats (like HTML, odt, PDF, docx etc.) with

  Pandoc.convert

  - similarly to

  pandoc

  function in knitr. Basically this is a wrapper around a Pandoc call, which has not much to do with R actually.

• users might write some reports with literate programming (similar to

  knitr

  ) in a forked version of brew syntax resulting. This means that the user can include R code chunks in a document, and brewing that results in a pretty Pandoc's markdown document and also in a bunch of other formats (like HTML, odt, PDF, docx etc.). The great advantage of this function is that you do not have to transform your R objects to markdown manually, it's all handled automagically.

  Example: this

  README.md

  is cooked with

  Pandoc.brew

  based on

  inst/README.brew

  and also exported to HTML. Details can be found below or head directly to examples.

• and users might create a report in a live R session by adding some R objects and paragraphs to a

  Pandoc

  reference class object. Details can be found below.

Brew to Pandoc

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

brew

• slides on "Building a reporting sytem with BREW"
• learnr blogpost on brew

In short: a

brew

Pandoc.brew

brew

• stand for running inline R commands as usual,

• does pretty much the same but applies

  pander

  to the returning R object (instead of

  cat

  like the original

  brew

  function does). So putting there any R object, it would return in a nice Pandoc's markdown format with all possible error/warning messages etc.

This latter tries to be smart in some ways:

• A code chunk block (R commands between the tags) can return any number of values at any part of the block.
• Plots and images are grabbed in the document, rendered to a

  png

  file and

  pander

  method would result in a Pandoc markdown formatted image link. This means that the image would be rendered/shown/included in the exported document.
• All warnings/messages and errors are recorded in the blocks and returned in the document as footnotes or inline messages.
• All heavy R commands (e.g. those taking more then 0.1 sec to evaluate) are cached so re

  brew

  ing a report would not result in a coffee break.

Besides this, the custom

brew

brew

brew

For example now multiple R expressions can be passed between the

brew

> str(Pandoc.brew(text ='
+   Pi equals to ``.
+   And here are some random data:
+   ``
+ '))

Pi equals to 3.142.
And here are some random data:
0.6631, 0.849, 0.06986, 0.3343, 0.5209, 0.3471, 0.866, 0.05548, 0.8933 and 0.2121
List of 2
 $ :List of 4
  ..$ type  : chr "text"
  ..$ text  :List of 2
  .. ..$ raw : chr "Pi equals to 3.142.\nAnd here are some random data:\n"
  .. ..$ eval: chr "Pi equals to 3.142.\nAnd here are some random data:\n"
  ..$ chunks:List of 2
  .. ..$ raw : chr "3.142"
  .. ..$ eval: chr "3.142"
  ..$ msg   :List of 3
  .. ..$ messages: NULL
  .. ..$ warnings: NULL
  .. ..$ errors  : NULL
 $ :List of 2
  ..$ type   : chr "block"
  ..$ robject:List of 6
  .. ..$ src   : chr "runif(10)"
  .. ..$ result: num [1:10] 0.6631 0.849 0.0699 0.3343 0.5209 ...
  .. ..$ output: chr "0.6631, 0.849, 0.06986, 0.3343, 0.5209, 0.3471, 0.866, 0.05548, 0.8933 and 0.2121"
  .. ..$ type  : chr "numeric"
  .. ..$ msg   :List of 3
  .. .. ..$ messages: NULL
  .. .. ..$ warnings: NULL
  .. .. ..$ errors  : NULL
  .. ..$ stdout: NULL
  .. ..- attr(*, "class")= chr "evals"

This document was generated by

Pandoc.brew

inst/README.brew

Pandoc.brew(system.file('README.brew', package = 'pander'))

The output is set to

stdout

output

HTML

odt

docx

convert

text ',
              'A wide table:\n',
              'And a nice chart:\n\n',
          sep = '\n')
Pandoc.brew(text = text, output = tempfile(), convert = 'html')
Pandoc.brew(text = text, output = tempfile(), convert = 'pdf')

So to brew this README with all R chunks automatically converted to html, please run:

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

Examples

The package bundles some examples for

Pandoc.brew

• minimal.brew
• short-code-long-report.brew
• graphs.brew

To

brew

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')

For easier access, I have uploaded some exported documents of the above examples as well:

• minimal.brew: markdown html pdf odt docx
• short-code-long-report.brew: markdown html pdf odt docx
• graphs.brew: markdown html pdf odt docx

Please check out

pdf

docx

odt

convert

Live report generation

pander

Pandoc

## Initialize a new Pandoc object
myReport 
Capturing evaluation information with evals

When working on the rapport package, I really needed some nifty R function that can evaluate R expression along with capturing errors and warnings. Unfortunately the 
evaluate
 package had only limited features at that time, as it could not return the raw R object, but only the standard output with messages. So I wrote my own function, and soon some further feature requests arose, like identifying if an R expression results in a plot etc. This section aims to give a quick introduction to the functionality of 
evals
, but for more usage/implementation details, please refer to specialized vignette, which can be accessed by 
vignette('evals', package='pander')
 or available online here.

But probably it's easier to explain what 
evals
 can do with a simple example:
> evals('1:10')
[[1]]
$src
[1] "1:10"

$result
 [1]  1  2  3  4  5  6  7  8  9 10
$output
[1] " [1]  1  2  3  4  5  6  7  8  9 10"
$type
[1] "integer"
$msg
$msg$messages
NULL
$msg$warnings
NULL
$msg$errors
NULL
$stdout
NULL
attr(,"class")
[1] "evals"

So 
evals
 can evaluate a character vector of R expressions, and it returns a list of captured stuff while running those:

• src

  holds the R expression,

• result

  contains the raw R object as is,

• output

  represents how the R object is printed to the standard output,

• type

  is the

  class

  of the returned R object,

• msg

  is a list of possible messages captured while running the R expression and

• stdout

  contains if anything was written to the standard output.

Besides capturing this nifty list of important circumstances,

evals

lattice

ggplot2

> evals('hist(mtcars$hp)')[[1]]$result
![](plots/plot-1.png)

So instead of a captured R object (which would be

NULL

Well, this is not a standard histogram usually returned by the

hist

evals

graphs.brew

evalsOptions('graph.unify', FALSE)

.Rprofile

Further features are described in the technical docs, and now I'll only give a brief introduction to another important feature of

evals

Caching

As

pander::evals

Pandoc.brew

evals

• Each passed R chunk is

  parse

  d to single R expressions.
• Each parsed expression's part (let it be a function, variable, constant etc.) is evaluated (as

  name

  ) separately to a

  list

  . This list describes the unique structure and the content of the passed R expressions. This has some really great benefits (see below).
• A hash is computed of each list element and cached too in

  pander

  's local environments. This is useful if you are using large data frames, just imagine: the caching algorithm would have to compute the hash for the same data frame each time it's touched! This way the hash is recomputed only if the R object with the given name is changed.
• The list of such R objects is serialized, then an

  SHA-1

  hash is computed, which is unique and there is no real risk of collision.
• If

  evals

  can find the cached results in an environment of

  pander

  's namespace (if

  cache.mode

  set to

  enviroment

  - see below) or in a file named to the computed hash (if

  cache.mode

  set to

  disk

  ), then it is returned on the spot. The objects modified/created by the cached code are also updated.
• Otherwise the call is evaluated and the results and the modified R objects of the environment are optionally saved to cache (e.g. if

  cache

  is active and if the

  proc.time()

  of the evaluation is higher then it is defined in

  cache.time

  - see details in evals' options).

As

pander

The caching hash is computed based on the structure and content of the R commands instead of the used variable names or R expressions, so let us make some POC example to show the greatest asset:

x 
It took a while, huh? :)

Let us create some custom functions and variables, which are not identical to the above call:
f 
And now try to run something like:
evals('f(g(X, Y), h)')

Yes, it was returned from cache!

About the kickback:

As 
pander
 (or rather: 
evals
) does not really deal with what is written in the provided sources but rather checks what is inside that, there might be some tricky situations where you would expect the cache to work, but it would not. Short example: we are computing and saving to a variable something heavy in a chunk (please run these in a clean R session to avoid conflicts):
evals('x 
It is cached, just run again, you will see.

But if you would create 
x
 in your global environment with any value (which has nothing to do with the special environment of the report!) and 
x
 was not defined in the report before this call (and you had no 
x
 value in your global environment before), then the content of 
x
 would result in a new hash for the cache - so caching would not work. E.g.:
x 
I really think this is a minor issue (with very special coincidences) which cannot be addressed cleverly - but could be avoided with some cautions (e.g. run 
Pandoc.brew
 in a clean R session like with 
Rscript
 or 
littler - if you are really afraid of this issue). And after all: you loose nothing, just the cache would not work for that only line and only once in most of the cases.

Other cases when the hash of a call will not match cached hashes:

• a number is replaced by a variable holding the number, e.g.:

  evals('1:5')

  vs.

  x 

• a part of an R object is replaced by a variable holding that, e.g.:

  evals('mean(mtcars$hp)')

  vs.

  x 

But the e.g. following do work from cache fine:

x  


General options

The package comes with a variety of globally adjustable options, which have an effect on the result of your reports. You can query and update these options with the 
panderOptions
 function:

• digits

  : numeric (default:

  2

  ) passed to

  format

  . Can be a vector specifying values for each column (has to be the same length as number of columns). Values for non-numeric columns will be disregarded.

• decimal.mark

  : string (default:

  .

  ) passed to

  format

• formula.caption.prefix

  : string (default:

  Formula:

  ) passed to

  pandoc.formula

  to be used as caption prefix. Be sure about what you are doing if changing to other than

  Formula:

  or

  :

  .

• big.mark

  : string (default:

  ''

  ) passed to

  format

• round

  : numeric (default:

  Inf

  ) passed to

  round

  . Can be a vector specifying values for each column (has to be the same length as number of columns). Values for non-numeric columns will be disregarded.

• keep.trailing.zeros

  : boolean (default:

  FALSE

  ) show or remove trailing zeros in numbers (e.g. in numeric vectors or in columns of tables with numeric values)

• keep.line.breaks

  : boolean (default:

  FALSE

  ) to keep or remove line breaks from cells in a table

• missing

  : string (default:

  NA

  ) to replace missing values in vectors, tables etc.

• date

  : string (default:

  '%Y/%m/%d %X'

  ) passed to

  format

  when printing dates (

  POSIXct

  or

  POSIXt

  )

• header.style

  :

  'atx'

  or

  'setext'

  passed to

  pandoc.header

• list.style

  :

  'bullet'

  (default),

  'ordered'

  or

  'roman'

  passed to

  pandoc.list

  . Please not that this has no effect on

  pander

  methods.

• table.style

  :

  'multiline'

  ,

  'grid'

  or

  'simple'

  passed to

  pandoc.table

• table.emphasize.rownames

  : boolean (default:

  TRUE

  ) if row names should be highlighted

• table.split.table

  : numeric passed to

  pandoc.table

  and also affects

  pander

  methods. This option tells

  pander

  where to split too wide tables. The default value (

  80

  ) suggests the conventional number of characters used in a line, feel free to change (e.g. to

  Inf

  to disable this feature) if you are not using a VT100 terminal any more :)

• table.split.cells

  : numeric (default: 30) passed to

  pandoc.table

  and also affects pander methods. This option tells pander where to split too wide cells with line breaks. Set

  Inf

  ` to disable.

• table.caption.prefix

  : string (default:

  Table:

  ) passed to

  pandoc.table

  to be used as caption prefix. Be sure about what you are doing if changing to other than

  Table:

  or

  :

  .

• table.continues

  : string (default:

  Table continues below

  ) passed to

  pandoc.table

  to be used as caption for long (split) without a use defined caption

• table.continues.affix

  : string (default:

  (continued below)

  ) passed to

  pandoc.table

  to be used as an affix concatenated to the user defined caption for long (split) tables

• table.alignment.default

  : string (default:

  centre

  ) that defines the default alignment of cells. Can be

  left

  ,

  right

  or

  centre

  that latter can be also spelled as

  center

• table.alignment.rownames

  : string (default:

  centre

  ) that defines the alignment of rownames in tables. Can be

  left

  ,

  right

  or

  centre

  that latter can be also spelled as

  center

• use.hyphening

  : boolean (default:

  FALSE

  ) if try to use hyphening when splitting large cells according to table.split.cells. Requires

  sylly

  package.

• evals.messages

  : boolean (default:

  TRUE

  ) passed to

  evals

  '

  pander

  method specifying if messages should be rendered

• p.wrap

  : a string (default:

  '_'

  ) to wrap vector elements passed to

  p

  function

• p.sep

  : a string (default:

  ', '

  ) with the main separator passed to

  p

  function

• p.copula

  : a string (default:

  'and'

  ) a string with ending separator passed to

  p

  function

• plain.ascii

  : boolean (default: FALSE) to define if output should be in plain ascii or not

• graph.nomargin

  : boolean (default:

  TRUE

  ) if trying to keep plots' margins at minimal

• graph.fontfamily

  : string (default:

  'sans'

  ) specifying the font family to be used in images. Please note, that using a custom font on Windows requires

  grDevices:::windowsFonts

  first.

• graph.fontcolor

  : string (default:

  'black'

  ) specifying the default font color

• graph.fontsize

  : numeric (default:

  12

  ) specifying the base font size in pixels. Main title is rendered with

  1.2

  and labels with

  0.8

  multiplier.

• graph.grid

  : boolean (default:

  TRUE

  ) if a grid should be added to the plot

• graph.grid.minor

  : boolean (default:

  TRUE

  ) if a miner grid should be also rendered

• graph.grid.color

  : string (default:

  'grey'

  ) specifying the color of the rendered grid

• graph.grid.lty

  : string (default:

  'dashed'

  ) specifying the line type of grid

• graph.boxes

  : boolean (default:

  FALSE

  ) if to render a border around of plot (and e.g. around strip)

• graph.legend.position

  : string (default:

  'right'

  ) specifying the position of the legend: 'top', 'right', 'bottom' or 'left'

• graph.background

  : string (default:

  'white'

  ) specifying the plots main background's color

• graph.panel.background

  : string (default:

  'transparent'

  ) specifying the plot's main panel background. Please note, that this option is not supported with

  base

  graphics.

• graph.colors

  : character vector of default color palette (defaults to a colorblind theme). Please note that this update work with

  base

  plots by appending the

  col

  argument to the call if not set.

• graph.color.rnd

  : boolean (default:

  FALSE

  ) specifying if the palette should be reordered randomly before rendering each plot to get colorful images

• graph.axis.angle

  : numeric (default:

  1

  ) specifying the angle of axes' labels. The available options are based on

  par(les)

  and sets if the labels should be:

  • 1

    : parallel to the axis,

  • 2

    : horizontal,

  • 3

    : perpendicular to the axis or

  • 4

    : vertical.

• graph.symbol

  : numeric (default:

  1

  ) specifying a symbol (see the

  pch

  parameter of

  par

  )

• knitr.auto.asis

  : boolean (default:

  TRUE

  ) if the results of

  pander

  should be considered as

  asis

  in

  knitr

  . Equals to specifying

  results='asis'

  in the R chunk, so thus there is no need to do so if set to

  TRUE

  .

Besides localization of numeric formats or the styles of tables, lists and plots, there are some technical options as well, which would effect e.g. caching or the format of rendered image files. You can query/update those with the

evalsOptions

pander

evals

The list of possible options are:

• parse

  : if

  TRUE

  the provided

  txt

  elements would be merged into one string and parsed to logical chunks. This is useful if you would want to get separate results of your code parts - not just the last returned value, but you are passing the whole script in one string. To manually lock lines to each other (e.g. calling a

  plot

  and on next line adding an

  abline

  or

  text

  to it), use a plus char (

  +

  ) at the beginning of each line which should be evaluated with the previous one(s). If set to

  FALSE

  ,

  evals

  would not try to parse R code, it would get evaluated in separate runs - as provided. Please see the documentation of

  evals

  .

• cache

  : caching the result of R calls if set to

  TRUE

• cache.mode

  : cached results could be stored in an

  environment

  in current R session or let it be permanent on

  disk

  .

• cache.dir

  : path to a directory holding cache files if

  cache.mode

  set to

  disk

  . Default set to

  .cache

  in current working directory.

• cache.time

  : number of seconds to limit caching based on

  proc.time

  . If set to

  0

  , all R commands, if set to

  Inf

  , none is cached (despite the

  cache

  parameter).

• cache.copy.images

  : copy images to new file names if an image is returned from the disk cache? If set to

  FALSE

  (default), the cached path would be returned.

• classes

  : a vector or list of classes which should be returned. If set to

  NULL

  (by default) all R objects will be returned.

• hooks

  : list of hooks to be run for given classes in the form of

  list(class = fn)

  . If you would also specify some parameters of the function, a list should be provided in the form of

  list(fn, param1, param2=NULL)

  etc. So the hooks would become

  list(class1=list(fn, param1, param2=NULL), ...)

  . See example of

  evals

  for more details. A default hook can be specified too by setting the class to

  'default'

  . This can be handy if you do not want to define separate methods/functions to each possible class, but automatically apply the default hook to all classes not mentioned in the list. You may also specify only one element in the list like:

  hooks=list('default' = pander_return)

  . Please note, that nor error/warning messages, nor stdout is captured (so: updated) while running hooks!

• length

  : any R object exceeding the specified length will not be returned. The default value (

  Inf

  ) does not filter out any R objects.

• output

  : a character vector of required returned values. This might be useful if you are only interested in the

  result

  , and do not want to save/see e.g.

  messages

  or

  print

  ed

  output

  . See examples of

  evals

  .

• graph.unify

  : should

  evals

  try to unify the style of (

  base

  ,

  lattice

  and

  ggplot2

  ) plots? If set to

  TRUE

  , some

  panderOptions()

  would apply. By default this is disabled not to freak out useRs :)

• graph.name

  : set the file name of saved plots which is

  %s

  by default. A simple character string might be provided where

  %d

  would be replaced by the index of the generating

  txt

  source,

  %n

  with an incremented integer in

  graph.dir

  with similar file names and

  %t

  by some unique random characters. When used in a

  brew

  file,

  %i

  is also available which would be replaced by the chunk number.

• graph.dir

  : path to a directory where to place generated images. If the directory does not exist,

  evals

  try to create that. Default set to

  plots

  in current working directory.

• graph.output

  : set the required file format of saved plots. Currently it could be any of

  grDevices

  :

  png

  ,

  bmp

  ,

  jpeg

  ,

  jpg

  ,

  tiff

  ,

  svg

  or

  pdf

  . Set to

  NA

  not to save plots at all and tweak that setting with

  capture.plot()

  on demand.

• width

  : width of generated plot in pixels for even vector formats

• height

  : height of generated plot in pixels for even vector formats

• res

  : nominal resolution in

  ppi

  . The height and width of vector images will be calculated based in this.

• hi.res

  : generate high resolution plots also? If set to

  TRUE

  , each R code parts resulting an image would be run twice.

• hi.res.width

  : width of generated high resolution plot in pixels for even vector formats. The

  height

  and

  res

  of high resolution image is automatically computed based on the above options to preserve original plot aspect ratio.

• graph.env

  : save the environments in which plots were generated to distinct files (based on

  graph.name

  ) with

  env

  extension?

• graph.recordplot

  : save the plot via

  recordPlot

  to distinct files (based on

  graph.name

  ) with

  recodplot

  extension?

• graph.RDS

  save the raw R object returned (usually with

  lattice

  or

  ggplot2

  ) while generating the plots to distinct files (based on

  graph.name

  ) with

  RDS

  extension?

• log

  :

  NULL

  or an optionally passed logger name from

  futile.logger

  to record all info, trace, debug and error messages.

Difference from other rendering packages

How does

pander

pander

pander

knitr

But if you stick with

pander

ascii

xtable

Hmisc

tables

pander

Pandoc.brew

pander

Based on the fact that

pander

show.src

pander

Of course all warnings, messages and errors are captured while evaluating R expressions just like

stdout

Graphs and plots are automatically identified in code chunks and saved to disk in a

png

brew

jpg

svg

pdf

graphs.brew

And

pander

ESS

I have created some simple LISP functions which would be handy if you are using the best damn IDE for R. These functions and default key-bindings are shipped with the package, feel free to personalize.

As time passed these small functions grew heavier (with my Emacs knowledge) so I ended up with a small library:

pander-mode

I am currently working on

pander-mode

• pander-brew

  (

  C-c p b

  ): Run

  Pandoc.brew

  on current buffer or region (if mark is active), show results in ess-output and (optionally) copy results to clipboard while setting working directory to

  tempdir()

  temporary.

• pander-brew-export

  (

  C-c p B

  ): Run

  Pandoc.brew

  on current buffer or region (if mark is active) and export results to specified (auto-complete in minibuffer) format. Also tries to open exported document.

• pander-eval

  (

  C-c p e

  ): Run

  pander

  on (automatically evaluated) region or current chunk (if marker is not set), show results (of last returned R object) in

  *ess-output*

  and (optionally) copy those to clipboard while setting working directory to

  tempdir()

  temporary.

Few options of

pander-mode

M-x customize-group pander

• pander-clipboard

  : If non-nil then the result of

  pander-*

  functions would be copied to clipboard.

• pander-show-source

  : If non-nil then the source of R commands would also show up in generated documents while running 'pander-eval'. This would not affect

  brew

  functions ATM.

To use this small lib, just type:

M-x pander-mode

markdown-mode