Pander
is designed to provide a minimal and easy tool for rendering R
objects into Pandoc’s markdown. This vignette aims to introduce pander
package and it’s core pieces of functionality. It is intented to be a general overview with pointers to places with detailed information. This vignette will talk about:
Pandoc
’s markdown with generic S3 pander method.The core functionality of pander
is centered around rendering R
objects into Pandoc
’s markdown. Let’s dive in the demo of the most common usage of pander
:
pander(head(iris))
#>
#> -------------------------------------------------------------------
#> Sepal.Length Sepal.Width Petal.Length Petal.Width Species
#> -------------- ------------- -------------- ------------- ---------
#> 5.1 3.5 1.4 0.2 setosa
#>
#> 4.9 3 1.4 0.2 setosa
#>
#> 4.7 3.2 1.3 0.2 setosa
#>
#> 4.6 3.1 1.5 0.2 setosa
#>
#> 5 3.6 1.4 0.2 setosa
#>
#> 5.4 3.9 1.7 0.4 setosa
#> -------------------------------------------------------------------
pander(head(mtcars[1:5]))
#>
#> ------------------------------------------------------
#> 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
#>
#> Hornet 4 Drive 21.4 6 258 110 3.08
#>
#> Hornet Sportabout 18.7 8 360 175 3.15
#>
#> Valiant 18.1 6 225 105 2.76
#> ------------------------------------------------------
pander(tabular( (Species + 1) ~ (n=1) + Format(digits=2)*
(Sepal.Length + Sepal.Width)*(mean + sd), data=iris ))
#>
#> ----------------------------------------------------------
#> Sepal.Length Sepal.Width
#> Species n mean sd mean sd
#> ---------- ---- ---------------- ---- --------------- ----
#> setosa 50 5.01 0.35 3.43 0.38
#>
#> versicolor 50 5.94 0.52 2.77 0.31
#>
#> virginica 50 6.59 0.64 2.97 0.32
#>
#> All 150 5.84 0.83 3.06 0.44
#> ----------------------------------------------------------
As you have probably guess, this is achieved via generic pander
S3
method. Out of the box, pander
supports a variety of classes:
methods(pander)
#> [1] pander.anova* pander.aov*
#> [3] pander.aovlist* pander.Arima*
#> [5] pander.call* pander.cast_df*
#> [7] pander.character* pander.clogit*
#> [9] pander.coxph* pander.cph*
#> [11] pander.CrossTable* pander.data.frame*
#> [13] pander.Date* pander.default*
#> [15] pander.density* pander.describe*
#> [17] pander.evals* pander.factor*
#> [19] pander.formula* pander.ftable*
#> [21] pander.function* pander.glm*
#> [23] pander.Glm* pander.gtable*
#> [25] pander.htest* pander.image*
#> [27] pander.irts* pander.list*
#> [29] pander.lm* pander.lme*
#> [31] pander.logical* pander.lrm*
#> [33] pander.manova* pander.matrix*
#> [35] pander.microbenchmark* pander.mtable*
#> [37] pander.name* pander.nls*
#> [39] pander.NULL* pander.numeric*
#> [41] pander.ols* pander.orm*
#> [43] pander.polr* pander.POSIXct*
#> [45] pander.POSIXlt* pander.prcomp*
#> [47] pander.randomForest* pander.rapport*
#> [49] pander.rlm* pander.sessionInfo*
#> [51] pander.smooth.spline* pander.stat.table*
#> [53] pander.summary.aov* pander.summary.aovlist*
#> [55] pander.summary.glm* pander.summary.lm*
#> [57] pander.summary.lme* pander.summary.manova*
#> [59] pander.summary.nls* pander.summary.polr*
#> [61] pander.summary.prcomp* pander.summary.rms*
#> [63] pander.summary.survreg* pander.summary.table*
#> [65] pander.survdiff* pander.survfit*
#> [67] pander.survreg* pander.table*
#> [69] pander.tabular* pander.ts*
#> [71] pander.zoo*
#> see '?methods' for accessing help and source code
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 similar to knitr::kable
functionality in rendering markdown, but also adds a truly rich functionality with many different rendering options that pander
inherits. For more usage/implementation details and examples, please refer to specialized vignette, which can be accessed by vignette('pandoc_table')
or available online here.
As pander
package was originally developed in conjunction with rapport package, there was a needed for functionality that can evaluate R
expression along with 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')
#> INFO [2015-11-21 21:54:06] Command run: 1:10
#> TRACE [2015-11-21 21:54:06] Cached result
#> DEBUG [2015-11-21 21:54:06] Returned object: class = integer, length = 10, dim = , size = 88 bytes
#> [[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"
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 captured information 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 evaluating the R expression and. Among other messages, warnings/errors will appear here.stdout
contains if anything was written to the standard output.For more usage/implementation details and examples, please refer to specialized vignette, which can be accessed by vignette('evals')
or available online here.
The brew package, which is 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 features in literate programming. 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):
<% ... %>
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:
R
commands between the tags) can return any number of values at any part of the block.R
commands (e.g. those taking more then 0.1 sec to evaluate) are cached so rebrewing a report would not result in a coffee break.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 removed and rewritten for some extra profits besides improved caching. Quick example:
str(Pandoc.brew(text ='
+ Pi equals to `<%= pi %>`.
+ And here are some random data:
+ `<%= runif(10) %>`
+ '))
#>
#> + Pi equals to `INFO [2015-11-21 21:54:06] Command run: pi
#> TRACE [2015-11-21 21:54:06] Cached result
#> DEBUG [2015-11-21 21:54:06] Returned object: class = numeric, length = 1, dim = , size = 48 bytes
#> _3.142_`.
#> + And here are some random data:
#> + `INFO [2015-11-21 21:54:06] Command run: runif(10)
#> TRACE [2015-11-21 21:54:06] Cached result
#> DEBUG [2015-11-21 21:54:06] Returned object: class = numeric, length = 10, dim = , size = 168 bytes
#> _0.6509_, _0.258_, _0.4785_, _0.7663_, _0.08425_, _0.8753_, _0.3391_, _0.8394_, _0.3467_ and _0.3338_`
#> +
#> List of 1
#> $ :List of 4
#> ..$ type : chr "text"
#> ..$ text :List of 2
#> .. ..$ raw : chr "\n+ Pi equals to `<%=pi%>`.\n+ And here are some random data:\n+ `<%=runif(10)%>`\n+ \n"
#> .. ..$ eval: chr "\n+ Pi equals to `_3.142_`.\n+ And here are some random data:\n+ `_0.6509_, _0.258_, _0.4785_, _0.7663_, _0.08425_, _0.87"| __truncated__
#> ..$ chunks:List of 2
#> .. ..$ raw : chr [1:2] "<%=pi%>" "<%=runif(10)%>"
#> .. ..$ eval: chr [1:2] "_3.142_" "_0.6509_, _0.258_, _0.4785_, _0.7663_, _0.08425_, _0.8753_, _0.3391_, _0.8394_, _0.3467_ and _0.3338_"
#> ..$ msg :List of 3
#> .. ..$ messages: NULL
#> .. ..$ warnings: NULL
#> .. ..$ errors : NULL
The package bundles some examples for Pandoc.brew
to let you check its features pretty fast. To brew these examples on your machine, try to run the followings 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')
The package comes with a variety of globally adjustable options, which have an effect on the result of your reports. 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:
panderOptions("table.style", "simple")
pander(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
pander(head(iris))
#>
#>
#> Sepal.Length Sepal.Width Petal.Length Petal.Width Species
#> -------------- ------------- -------------- ------------- ---------
#> 5.1 3.5 1.4 0.2 setosa
#> 4.9 3 1.4 0.2 setosa
#> 4.7 3.2 1.3 0.2 setosa
#> 4.6 3.1 1.5 0.2 setosa
#> 5 3.6 1.4 0.2 setosa
#> 5.4 3.9 1.7 0.4 setosa
panderOptions("table.style", "grid")
pander(head(iris))
#>
#>
#> +----------------+---------------+----------------+---------------+-----------+
#> | Sepal.Length | Sepal.Width | Petal.Length | Petal.Width | Species |
#> +================+===============+================+===============+===========+
#> | 5.1 | 3.5 | 1.4 | 0.2 | setosa |
#> +----------------+---------------+----------------+---------------+-----------+
#> | 4.9 | 3 | 1.4 | 0.2 | setosa |
#> +----------------+---------------+----------------+---------------+-----------+
#> | 4.7 | 3.2 | 1.3 | 0.2 | setosa |
#> +----------------+---------------+----------------+---------------+-----------+
#> | 4.6 | 3.1 | 1.5 | 0.2 | setosa |
#> +----------------+---------------+----------------+---------------+-----------+
#> | 5 | 3.6 | 1.4 | 0.2 | setosa |
#> +----------------+---------------+----------------+---------------+-----------+
#> | 5.4 | 3.9 | 1.7 | 0.4 | setosa |
#> +----------------+---------------+----------------+---------------+-----------+