pander 0.5.0: the next generation of markdown tables in R

A new version of pander was just released on CRAN with 200+ commits of new features, major performance updates and some minor fixes [changelog]. One of the minor technical changes, which might be major good news for the knitr users, is that there is no further need to specify asis in knitr chunks when calling pander – please see the related post for more details. The package now ships with two open-source licenses due to some user requests: now you can use either of “Open Software License” or “Affero General Public License“, which practically means the very same, but the newly added OSL license is more explicit on the legal requirements of using any derivatives of pander in services. In short: you are free to use and modify the package, but please share your modifications (and not your linked product) back to the community. One of the new features is that pander can now render multidimensional tabular data with the help of ftable. Previously, the package was limited to 2 dimensional tables based on the markdown specification. A quick example on the workaround:

> library(pander)
> pander(with(mtcars, table(gear, am, carb)), style = 'simple')
------ ---- ------ --- --- --- --- --- ---
            "carb" "1" "2" "3" "4" "6" "8"
"gear" "am"                               
 "3"   "0"          3   4   3   5   0   0 
       "1"          0   0   0   0   0   0 
 "4"   "0"          0   2   0   2   0   0 
       "1"          4   2   0   2   0   0 
 "5"   "0"          0   0   0   0   0   0 
       "1"          0   2   0   1   1   1 
------ ---- ------ --- --- --- --- --- ---

Special thanks goes to +Roman Tsegelskyi, who was working on the package in GSoC 2014. He eliminated some bottlenecks of the package by rewriting some internal parts with Rcpp. He also added support for a bunch of new R object types in pander, so this new release supports more than 50 R classes to be converted to Pandoc’s markdown with a simple call to the generic S3 method. A quick demo on one of the those:

> library(zoo)
> demo <- zoo(
+     cbind(foo = sample(1:1e3, 5),
+           bar = sample(rownames(mtcars), 5)),
+     Sys.time() - runif(5) * 3600)
> pander(demo)
-------------------------------------------
        Period          foo       bar      
---------------------- ----- --------------
2014/10/30 10:24:14 PM  727   Lotus Europa 

2014/10/30 10:40:35 PM  216   Merc 450SLC  

2014/10/30 11:02:34 PM  974  Toyota Corolla

2014/10/30 11:08:25 PM  318    Camaro Z28  

2014/10/30 11:09:42 PM  683   Ferrari Dino 
-------------------------------------------

Any feedback and suggestion on the current implementation and/or feature requests on further R classes is highly welcomed, please submit an issue on GH. Besides the performance tweaks and new methods, some extra options were also introduced with this release. Now you can not only specify your preferences for table formatting (like markdown format, cell alignment, decimal mark etc.) or plot styles (such as color palette, default grid and axis angle, family and sizes etc.), now you can generate markdown tables with manually defined column width or you can hyphenate the content of any cell that is to be split due to the limited cell width. What’s next? Now I’m working on adding logging support to Pandoc.brew, so when you are brewing a R-flavoured text document into markdown/HTML/docx/PDF or similar format, you can get a detailed log of what’s happenning in the code chunks. A preliminary (but already working) demo:

## install the development version of pander with logging support
devtools::install_github('rapporter/pander@log')
## load the logger package to setup a log file
library(futile.logger)
## define the log file's
t <- tempfile()
flog.appender(appender.file(t), name = 'evals')
flog.threshold(TRACE, 'evals')
## tell the pander package that we're logging
evalsOptions('log', 'evals')
## brew something into markdown
Pandoc.brew(system.file('examples/minimal.brew', package='pander'))

The result of Pandoc.brew had not changed of course, but let’s see what we find in t:

INFO [2014-10-31 00:19:36] Command run: pi
DEBUG [2014-10-31 00:19:36] Returned object: class = numeric, length = 1, dim = , size = 48 bytes
INFO [2014-10-31 00:19:36] Command run: mtcars[1:5, ]
DEBUG [2014-10-31 00:19:36] Returned object: class = data.frame, length = 11, dim = 5/11, size = 2656 bytes
INFO [2014-10-31 00:19:36] Command run: chisq.test(mtcars$am, mtcars$gear)
WARN [2014-10-31 00:19:36] Chi-squared approximation may be incorrect
DEBUG [2014-10-31 00:19:36] Returned object: class = htest, length = 9, dim = , size = 6808 bytes
INFO [2014-10-31 00:19:36] Command run: if (require(lattice, quietly = TRUE)) { histogram(mtcars$hp) }
TRACE [2014-10-31 00:19:36] Image file written: /tmp/Rtmp4TJoLV/plots/1ddd33ad7a3.png
INFO [2014-10-31 00:19:36] Command run: hist(mtcars$hp)
TRACE [2014-10-31 00:19:36] Image file written: /tmp/Rtmp4TJoLV/plots/1ddd6354c4f4.png
INFO [2014-10-31 00:19:36] Command run: if (require(ggplot2, quietly = TRUE)) { ggplot(mtcars) + geom_histogram(aes(x = hp)) }
TRACE [2014-10-31 00:19:37] Image file written: /tmp/Rtmp4TJoLV/plots/1ddd1497e7e9.png
INFO [2014-10-31 00:19:37] Command run: temp <- panderOptions("graph.grid.color")
INFO [2014-10-31 00:19:37] Command run: panderOptions("graph.grid.color", "red")
INFO [2014-10-31 00:19:37] Command run: set.caption("This is a caption, right?")
INFO [2014-10-31 00:19:37] Command run: histogram(mtcars$hp)
TRACE [2014-10-31 00:19:37] Image file written: /tmp/Rtmp4TJoLV/plots/1ddd7647f3ec.png
INFO [2014-10-31 00:19:37] Command run: panderOptions("graph.grid.color", temp)
INFO [2014-10-31 00:19:37] Command run: set.caption("Here goes the first two lines of USArrests")
INFO [2014-10-31 00:19:37] Command run: USArrests[1:2, ]
DEBUG [2014-10-31 00:19:37] Returned object: class = data.frame, length = 4, dim = 2/4, size = 1552 bytes
INFO [2014-10-31 00:19:37] Command run: list(1:5)
DEBUG [2014-10-31 00:19:37] Returned object: class = list, length = 1, dim = , size = 120 bytes
INFO [2014-10-31 00:19:37] Command run: list(pi)
DEBUG [2014-10-31 00:19:37] Returned object: class = list, length = 1, dim = , size = 96 bytes
INFO [2014-10-31 00:19:37] Command run: list(mtcars$hp)
DEBUG [2014-10-31 00:19:37] Returned object: class = list, length = 1, dim = , size = 344 bytes
INFO [2014-10-31 00:19:37] Command run: mean(unknown.R.object)
ERROR [2014-10-31 00:19:37] object 'unknown.R.object' not found

Please let me know how you like this log!