{"id":13858474,"url":"https://github.com/Rapporter/pander","last_synced_at":"2025-07-13T23:32:37.065Z","repository":{"id":3401079,"uuid":"4450786","full_name":"Rapporter/pander","owner":"Rapporter","description":"An R Pandoc Writer: Convert arbitrary R objects into markdown","archived":false,"fork":false,"pushed_at":"2025-03-01T00:36:31.000Z","size":27552,"stargazers_count":299,"open_issues_count":44,"forks_count":65,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-06-24T03:46:40.279Z","etag":null,"topics":["literate-programming","markdown","pandoc","pandoc-markdown","r","reproducible-research","rmarkdown"],"latest_commit_sha":null,"homepage":"http://rapporter.github.io/pander/","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"osl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Rapporter.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2012-05-25T22:35:05.000Z","updated_at":"2025-05-13T18:21:13.000Z","dependencies_parsed_at":"2022-07-08T05:24:31.048Z","dependency_job_id":null,"html_url":"https://github.com/Rapporter/pander","commit_stats":{"total_commits":1133,"total_committers":26,"mean_commits":43.57692307692308,"dds":0.5154457193292145,"last_synced_commit":"7d5d9dd1b2d8f927737b8bb1f469679450cef43c"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"purl":"pkg:github/Rapporter/pander","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rapporter%2Fpander","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rapporter%2Fpander/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rapporter%2Fpander/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rapporter%2Fpander/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Rapporter","download_url":"https://codeload.github.com/Rapporter/pander/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rapporter%2Fpander/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265221147,"owners_count":23729958,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["literate-programming","markdown","pandoc","pandoc-markdown","r","reproducible-research","rmarkdown"],"created_at":"2024-08-05T03:02:10.093Z","updated_at":"2025-07-13T23:32:37.050Z","avatar_url":"https://github.com/Rapporter.png","language":"R","funding_links":[],"categories":["R"],"sub_categories":[],"readme":"# [pander: An R Pandoc Writer](https://github.com/Rapporter/pander)\n\nThe main aim of the *pander* [R](https://www.r-project.org/) package is to provide a minimal and easy tool for rendering **R objects** into [Pandoc](https://johnmacfarlane.net/pandoc/)'s **markdown**. The package is also capable of exporting/converting complex Pandoc documents (reports) in [various ways](#creating-pandoc-documents). Regarding the difference between `pander` and other packages for exporting R objects to different file formats, please refer to this [section](#difference-from-other-rendering-packages).\n\nCurrent build and test coverage status: [![](https://codecov.io/github/Rapporter/pander/coverage.svg?branch=master)](https://app.codecov.io/github/Rapporter/pander?branch=master).\n\nSome CRAN statistics: [![](http://cranlogs.r-pkg.org/badges/pander)](https://cran.r-project.org/package=pander) [![](http://cranlogs.r-pkg.org/badges/grand-total/pander)](https://cran.r-project.org/package=pander)\n\n# Installation\n\nThe stable version [![](http://www.r-pkg.org/badges/version/pander)](https://cran.r-project.org/package=pander) can be installed easily in the `R` console like any other package:\n\n```r\ninstall.packages('pander')\n```\n\nOn 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](https://github.com/Rapporter/pander). To get the latest development version from [GitHub](https://github.com/Rapporter/pander) of the `devtools` package from [CRAN](https://cran.r-project.org/package=devtools):\n\n```r\ndevtools::install_github('Rapporter/pander')\n```\n\n## Dependencies\n\nFew cool packages from CRAN are needed for installing and/or using `pander`:\n\n * [digest](https://cran.r-project.org/package=digest) to compute hashes while caching,\n * [Rcpp](https://cran.r-project.org/package=Rcpp) to compile certain functions used by the package.\n\nAnd there are also a few optional suggested or supported R packages, such as:\n\n * [sylly](https://cran.r-project.org/package=sylly) to use hyphenation when splitting large table cells,\n * [lattice](https://cran.r-project.org/package=lattice) and [ggplot2](https://cran.r-project.org/package=ggplot2) for unified plot theme,\n * [logger](https://cran.r-project.org/package=logger) for logging capabilities inside `evals`,\n * [survival](https://cran.r-project.org/package=survival), [microbenchmark](https://cran.r-project.org/package=microbenchmark), [zoo](https://cran.r-project.org/package=zoo), [nlme](https://cran.r-project.org/package=nlme), [descr](https://cran.r-project.org/package=descr), [MASS](https://cran.r-project.org/package=MASS), [tables](https://cran.r-project.org/package=tables), [reshape](https://cran.r-project.org/package=reshape), [memisc](https://cran.r-project.org/package=memisc), [Epi](https://cran.r-project.org/package=Epi), [randomForest](https://cran.r-project.org/package=randomForest), [tseries](https://cran.r-project.org/package=tseries), [rms](https://cran.r-project.org/package=rms) packages include some supported R classes,\n * and *pander* can be also very useful inside of [knitr](https://cran.r-project.org/package=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](https://rapporter.github.io/pander/knitr.html).\n\n### Pandoc\n\n*pander* heavily builds on [Pandoc](https://johnmacfarlane.net/pandoc), which should be **pre-installed** before trying to convert your reports to [different formats](https://johnmacfarlane.net/pandoc/). Although **main functions work without Pandoc**, e.g. you can transform R objects into markdown or generate a markdown formatted report via [Pandoc.brew](#brew-to-pandoc) or the custom [reference class](#live-report-generation), but installing that great piece of software is suggested if you want to convert markdown to PDF/docx/HTML or other formats.\n\nStarting v0.98.932 [RStudio](https://posit.co/) comes with a bundled `Pandoc` binary, so one can save the tedious steps of installing Pandoc.\n\nIf you do not have RStudio installed, please refer to the [installation process of Pandoc](https://johnmacfarlane.net/pandoc/installing.html), 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` to [install from sources](https://johnmacfarlane.net/pandoc/installing.html#all-platforms)). Please do not forget to restart your R session to update your `PATH` after installation!\n\n# Helper functions\n\nThe 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`. For example `pandoc.table` is used for rendering tables in markdown. For a technical documentation, see the HTML help files of the package at [Rdocumentation](https://www.rdocumentation.org/packages/pander).\n\n\u003ca id=\"primitive-functions\"\u003e\u003c/a\u003e\n\nAll `pandoc` functions generally prints to console and do not return anything by default. If you want the opposite, to get markdown in a string, call each function ending in `.return`, for example `pandoc.table.return`. For more details, please see the official documentation in e.g. `?pandoc.strong`.\n\nThe full list of currently available primitive Pandoc-related functions are:\n\n  * pandoc.indent\n  * pandoc.p\n  * pandoc.strong\n  * pandoc.emphasis\n  * pandoc.strikeout\n  * pandoc.verbatim\n  * pandoc.link\n  * pandoc.image\n  * pandoc.date\n  * pandoc.formula\n  * pandoc.footnote\n  * pandoc.horizontal.rule\n  * pandoc.header\n  * pandoc.title\n\n\u003ca id=\"lists\"\u003e\u003c/a\u003e\nFor example there is a helper function rendering R **lists** into markdown:\n\n```r\n\u003e l \u003c- list(\n+        \"First list element\",\n+        paste0(1:5, '. subelement'),\n+        \"Second element\",\n+        list('F', 'B', 'I', c('phone', 'pad', 'talics')))\n\u003e pandoc.list(l, 'roman')\n```\nWhich command produces the following output:\n```\nI. First list element\n    I. 1. subelement\n    II. 2. subelement\n    III. 3. subelement\n    IV. 4. subelement\n    V. 5. subelement\nII. Second element\n    I. F\n    II. B\n    III. I\n        I. phone\n        II. pad\n        III. talics\n\n\u003c!-- end of list --\u003e\n\n```\n\n\u003ca id=\"tables\"\u003e\u003c/a\u003e\n\n# Markdown tables\n\nOne 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](https://rapporter.github.io/pander/pandoc_table.html).\n\nLet's start with a small example:\n\n```r\n\u003e pandoc.table(mtcars[1:3, 1:4])\n```\nWhich command produces the following output by default:\n```\n-------------------------------------------\n      \u0026nbsp;         mpg   cyl   disp   hp\n------------------- ----- ----- ------ ----\n   **Mazda RX4**     21     6    160   110\n\n **Mazda RX4 Wag**   21     6    160   110\n\n  **Datsun 710**    22.8    4    108    93\n-------------------------------------------\n\n```\n\n\u003ca id=\"style\"\u003e\u003c/a\u003e\u003ca id=\"styles\"\u003e\u003c/a\u003e\n\nPlease note that all below features are also supported by the more concise `pander` [generic S3 method](#generic-pander-method)!\n\n## Formats\n\nAll [four Pandoc formats](https://johnmacfarlane.net/pandoc/README.html#tables) 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:\n\n\u003ca id=\"multiline-table\"\u003e\u003c/a\u003e\n\nThe default style is the [`multiline` format](https://johnmacfarlane.net/pandoc/README.html#multiline-tables) (except for calling `pander` inside of a of a jupyter notebook) as most features (e.g. multi-line cells and alignment) are supported:\n\n```rout\n\u003e m \u003c- mtcars[1:2, 1:3]\n\u003e pandoc.table(m)\n\n--------------------------------------\n      \u0026nbsp;         mpg   cyl   disp\n------------------- ----- ----- ------\n   **Mazda RX4**     21     6    160\n\n **Mazda RX4 Wag**   21     6    160\n--------------------------------------\n\n```\n\nWhile [`simple` tables](https://johnmacfarlane.net/pandoc/README.html#simple-tables) are much more compact, but do not support line breaks in cells:\n\n```rout\n\u003e pandoc.table(m, style = \"simple\")\n\n      \u0026nbsp;         mpg   cyl   disp\n------------------- ----- ----- ------\n   **Mazda RX4**     21     6    160\n **Mazda RX4 Wag**   21     6    160\n\n```\n\nMy personal favorite, the [`grid` format](https://johnmacfarlane.net/pandoc/README.html#grid-tables) is really handy for [emacs](https://www.emacswiki.org/emacs/TableMode) users and it does support line breaks inside of cells, but cell alignment is not possible in most parsers:\n\n```rout\n\u003e pandoc.table(m, style = \"grid\")\n\n+---------------------+-------+-------+--------+\n|       \u0026nbsp;        |  mpg  |  cyl  |  disp  |\n+=====================+=======+=======+========+\n|    **Mazda RX4**    |  21   |   6   |  160   |\n+---------------------+-------+-------+--------+\n|  **Mazda RX4 Wag**  |  21   |   6   |  160   |\n+---------------------+-------+-------+--------+\n\n```\n\nAnd the so called `rmarkdown` or [pipe table format](https://johnmacfarlane.net/pandoc/README.html#pipe-tables) is often used directly with `knitr`, since it was supporters by the first versions of the `markdown` package:\n\n```rout\n\u003e pandoc.table(m, style = \"rmarkdown\")\n\n|       \u0026nbsp;        |  mpg  |  cyl  |  disp  |\n|:-------------------:|:-----:|:-----:|:------:|\n|    **Mazda RX4**    |  21   |   6   |  160   |\n|  **Mazda RX4 Wag**  |  21   |   6   |  160   |\n\n```\n\nBut once again, you should simply stick to the default [multiline table format](#multiline-table) in most cases. Otherwise, it's wise to update the default table format via [`panderOptions`](#pander-options).\n\n## Caption\n\nIt's really easy to add a **caption** to a table:\n\n```rout\n\u003e pandoc.table(m, style = \"grid\", caption = \"Hello caption!\")\n\n+---------------------+-------+-------+--------+\n|       \u0026nbsp;        |  mpg  |  cyl  |  disp  |\n+=====================+=======+=======+========+\n|    **Mazda RX4**    |  21   |   6   |  160   |\n+---------------------+-------+-------+--------+\n|  **Mazda RX4 Wag**  |  21   |   6   |  160   |\n+---------------------+-------+-------+--------+\n\nTable: Hello caption!\n\n```\n\nFor more convenient and flexible usage, you might be interested in the special `set.caption` helper function. Call the function at any time, and the next table or plot will catch up the provided caption:\n\n```rout\n\u003e set.caption(\"Hello caption!\")\n\u003e pandoc.table(m)\n\n--------------------------------------\n      \u0026nbsp;         mpg   cyl   disp\n------------------- ----- ----- ------\n   **Mazda RX4**     21     6    160\n\n **Mazda RX4 Wag**   21     6    160\n--------------------------------------\n\nTable: Hello caption!\n\n```\n\nUnless `permanent` option is set for `TRUE` (by default), caption will be set only for next table. To disable permanently set caption, just call `set.caption(NULL)` or call `set.caption` with `permanent` parameter being set to `FALSE`.\n\n\u003ca id=\"highlight-cells\"\u003e\u003c/a\u003e\n\n## Highlighting cells\n\nOne 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.\n\nThis can be achieved by calling `pandoc.table` directly and passing any (or more) of the following arguments **or** calling the R function with the same names before rendering a table with either the `pander` [generic S3 method](#generic-pander-method) or via `pandoc.table`:\n\n* emphasize.italics.rows\n* emphasize.italics.cols\n* emphasize.italics.cells\n* emphasize.strong.rows\n* emphasize.strong.cols\n* emphasize.strong.cells\n* emphasize.verbatim.rows\n* emphasize.verbatim.cols\n* emphasize.verbatim.cells\n\nThe `emphasize.italics` helpers would turn the affected cells to *italic*, `emphasize.strong` would apply a **bold** style to the cell and `emphasize.verbatim` would apply a `verbatim` style to the cell. A cell can be also *italic*,  **bold** and `verbatim` at the same time.\n\nThose functions and arguments ending in `rows` or `cols` take a vector (like which columns or rows to emphasize in a table), while the `cells` argument take either a vector (for one dimensional \"tables\") or an array-like data structure with two columns holding row and column indexes of cells to be emphasized -- just like what `which(..., arr.ind = TRUE)` returns. A quick-example:\n\n```rout\n\u003e t \u003c- mtcars[1:3, 1:5]\n\u003e emphasize.italics.cols(1)\n\u003e emphasize.italics.rows(1)\n\u003e emphasize.strong.cells(which(t \u003e 20, arr.ind = TRUE))\n\u003e pandoc.table(t)\n\n---------------------------------------------------------------\n      \u0026nbsp;           mpg      cyl    disp       hp      drat\n------------------- ---------- ----- --------- --------- ------\n   **Mazda RX4**     ***21***   *6*  ***160*** ***110*** *3.9*\n\n **Mazda RX4 Wag**   ***21***    6    **160**   **110**   3.9\n\n  **Datsun 710**    ***22.8***   4    **108**   **93**    3.85\n---------------------------------------------------------------\n\n```\n\nFor more examples, please see our \"[Highlight cells in markdown tables](http://blog.rapporter.net/2013/04/hihglight-cells-in-markdown-tables.html)\" blog post.\n\n## Cell alignment\n\nYou can specify the alignment of the cells (left, right or center/centre) in a table directly by setting the `justify` parameter:\n\n```rout\n\u003e pandoc.table(head(iris[,1:3], 2), justify = c('right', 'center', 'left'))\n\n-------------------------------------------\n  Sepal.Length  Sepal.Width  Petal.Length\n-------------- ------------- --------------\n           5.1      3.5      1.4\n\n           4.9       3       1.4\n-------------------------------------------\n\n```\n\nOr pre-define the alignment for (all future) `pandoc.table` or the `pander` [S3 generic method](#generic-pander-method) by a helper function:\n\n```rout\n\u003e set.alignment('left', row.names = 'right')\n\u003e pandoc.table(mtcars[1:2,  1:5])\n\n--------------------------------------------------\n             \u0026nbsp; mpg   cyl   disp   hp   drat\n------------------- ----- ----- ------ ---- ------\n      **Mazda RX4** 21    6     160    110  3.9\n\n  **Mazda RX4 Wag** 21    6     160    110  3.9\n--------------------------------------------------\n\n```\n\nJust like with [captions](#caption), you can also specify the `permanent` option to be `TRUE` to update the default cell alignment for all future tables. And beside using `set.alignment` helper function or passing parameters directly to `pandoc.table`, you may also set the default alignment styles with [`panderOptions`](#pander-options).\n\nWhat'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:\n\n```rout\n\u003e panderOptions('table.alignment.default',\n+   function(df)\n+     ifelse(sapply(df, mean) \u003e 2, 'left', 'right'))\n\u003e pandoc.table(head(iris[,1:3], 2))\n\n-------------------------------------------\nSepal.Length   Sepal.Width     Petal.Length\n-------------- ------------- --------------\n5.1            3.5                      1.4\n\n4.9            3                        1.4\n-------------------------------------------\n\n```\n\n## Table and cell width\n\n`pandoc.table` can also deal with the problem of really **wide tables**. Ever had an issue in LaTeX or MS Word when tried to print a correlation matrix of 40 variables? Not a problem any more as you can split up the table with auto-added captions. The `split.table` option defaults to 80 characters:\n\n```rout\n\u003e pandoc.table(mtcars[1:2, ], style = \"grid\", caption = \"Hello caption!\")\n\n+---------------------+-------+-------+--------+------+--------+-------+\n|       \u0026nbsp;        |  mpg  |  cyl  |  disp  |  hp  |  drat  |  wt   |\n+=====================+=======+=======+========+======+========+=======+\n|    **Mazda RX4**    |  21   |   6   |  160   | 110  |  3.9   | 2.62  |\n+---------------------+-------+-------+--------+------+--------+-------+\n|  **Mazda RX4 Wag**  |  21   |   6   |  160   | 110  |  3.9   | 2.875 |\n+---------------------+-------+-------+--------+------+--------+-------+\n\nTable: Hello caption! (continued below)\n\n+---------------------+--------+------+------+--------+--------+\n|       \u0026nbsp;        |  qsec  |  vs  |  am  |  gear  |  carb  |\n+=====================+========+======+======+========+========+\n|    **Mazda RX4**    | 16.46  |  0   |  1   |   4    |   4    |\n+---------------------+--------+------+------+--------+--------+\n|  **Mazda RX4 Wag**  | 17.02  |  0   |  1   |   4    |   4    |\n+---------------------+--------+------+------+--------+--------+\n\n```\n\nAnd too wide cells can also be split by line breaks. The maximum number of characters in a cell is specified by `split.cells` parameter (default to 30), can be a single value, vector (values for each column separately) and relative vector (percentages of `split.tables` parameter):\n\n```rout\n\u003e df \u003c- data.frame(a = 'Lorem ipsum', b = 'dolor sit', c = 'amet')\n\u003e pandoc.table(df, split.cells = 5)\n\n----------------\n  a     b    c\n----- ----- ----\nLorem dolor amet\nipsum  sit\n----------------\n\n\u003e pandoc.table(df, split.cells = c(5, 20, 5))\n\n--------------------\n  a       b      c\n----- --------- ----\nLorem dolor sit amet\nipsum\n--------------------\n\n\u003e pandoc.table(df, split.cells = c(\"80%\", \"10%\", \"10%\"))\n\n----------------------\n     a        b    c\n----------- ----- ----\nLorem ipsum dolor amet\n             sit\n----------------------\n\n```\n\nIf the `sylly` package is installed, `pandoc.table` can even split the cells with hyphening support:\n\n```rout\n\u003e pandoc.table(data.frame(baz = 'foobar'), use.hyphening = TRUE, split.cells = 3)\n\n-----\n baz\n-----\nfoo-\n bar\n-----\n\n```\n\n## Minor features\n\nFuntionality described in other sections is most notable, but `pander/pandoc.table` also has smaller nifty features that are worth mentioning:\n\n* `plain.ascii` - allows to have the output without `markdown` markup:\n\n```rout\n\u003e pandoc.table(mtcars[1:3, 1:4])\n\n-------------------------------------------\n      \u0026nbsp;         mpg   cyl   disp   hp\n------------------- ----- ----- ------ ----\n   **Mazda RX4**     21     6    160   110\n\n **Mazda RX4 Wag**   21     6    160   110\n\n  **Datsun 710**    22.8    4    108    93\n-------------------------------------------\n\n\u003e pandoc.table(mtcars[1:3, 1:4], plain.ascii = TRUE)\n\n-------------------------------------------\n                     mpg   cyl   disp   hp\n------------------- ----- ----- ------ ----\n     Mazda RX4       21     6    160   110\n\n   Mazda RX4 Wag     21     6    160   110\n\n    Datsun 710      22.8    4    108    93\n-------------------------------------------\n\n```\n\n* `missing` - set a string to replace missing values:\n\n```rout\n\u003e m \u003c- mtcars[1:3, 1:5]\n\u003e m$mpg \u003c- NA\n\u003e pandoc.table(m, missing = '?')\n\n--------------------------------------------------\n      \u0026nbsp;         mpg   cyl   disp   hp   drat\n------------------- ----- ----- ------ ---- ------\n   **Mazda RX4**      ?     6    160   110   3.9\n\n **Mazda RX4 Wag**    ?     6    160   110   3.9\n\n  **Datsun 710**      ?     4    108    93   3.85\n--------------------------------------------------\n\n```\n\n* `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.\n\n```rout\n\u003e m \u003c- data.frame(a=\"foo\\nbar\", b=\"pander\")\n\u003e pandoc.table(m)\n\n--------------\n   a      b\n------- ------\nfoo bar pander\n--------------\n\n\u003e pandoc.table(m, keep.line.breaks = TRUE)\n\n----------\n a    b\n--- ------\nfoo pander\nbar\n----------\n\n```\n\nTo see all possible options, please check [`?pandoc.table`](https://www.rdocumentation.org/packages/pander/functions/pandoc.table.return)\n\nAnd please note, that all above mentioned features are also supported by the `pander` [generic S3 method](#generic-pander-method) and defaults can be updated via [`panderOptions`](#pander-options) for permanent settings.\n\n# Generic pander method\n\n`pander` or `pandoc` (call as you wish) can deal with a bunch of R object types as being a pandocized `S3` generic method with a variety of already supported classes:\n\n\u003ca id=\"supported-r-classes\"\u003e\u003c/a\u003e\n\n```rout\n\u003e methods(pander)\n [1] pander.anova*           pander.aov*             pander.aovlist*         pander.Arima*           pander.call*\n [6] pander.cast_df*         pander.character*       pander.clogit*          pander.coxph*           pander.cph*\n[11] pander.CrossTable*      pander.data.frame*      pander.Date*            pander.default*         pander.density*\n[16] pander.describe*        pander.evals*           pander.factor*          pander.formula*         pander.ftable*\n[21] pander.function*        pander.glm*             pander.Glm*             pander.gtable*          pander.htest*\n[26] pander.image*           pander.irts*            pander.list*            pander.lm*              pander.lme*\n[31] pander.logical*         pander.lrm*             pander.manova*          pander.matrix*          pander.microbenchmark*\n[36] pander.mtable*          pander.name*            pander.nls*             pander.NULL*            pander.numeric*\n[41] pander.ols*             pander.orm*             pander.polr*            pander.POSIXct*         pander.POSIXlt*\n[46] pander.prcomp*          pander.randomForest*    pander.rapport*         pander.rlm*             pander.sessionInfo*\n[51] pander.smooth.spline*   pander.stat.table*      pander.summary.aov*     pander.summary.aovlist* pander.summary.glm*\n[56] pander.summary.lm*      pander.summary.lme*     pander.summary.manova*  pander.summary.nls*     pander.summary.polr*\n[61] pander.summary.prcomp*  pander.summary.rms*     pander.summary.survreg* pander.summary.table*   pander.survdiff*\n[66] pander.survfit*         pander.survreg*         pander.table*           pander.tabular*         pander.ts*\n[71] pander.zoo*\n```\n\nIf you think that pander lacks support for any other R class(es), please feel free to open a [ticket](https://github.com/Rapporter/pander/pulls) suggesting a new feature or submit [pull request](https://github.com/Rapporter/pander/issues) and we will be happy to extend the package.\n\nBesides the most basic R object types (vectors, matrices, tables or data frames), list-support might be interesting for you:\n\n```rout\n\u003e pander(list(a = 1, b = 2, c = table(mtcars$am), x = list(myname = 1, 2), 56))\n\n```\n\nA nested list can be seen above with a table and all (optional) list names. As a matter of fact, `pander.list` is the default method of `pander` too, when you call it on an unsupported R object class:\n\n```rout\n\u003e x \u003c- chisq.test(table(mtcars$am, mtcars$gear))\n\u003e class(x) \u003c- \"I've never heard of!\"\n\u003e pander(x)\n **WARNING**^[Chi-squared approximation may be incorrect]\n\n  * **statistic**:\n\n    -----------\n     X-squared\n    -----------\n       20.94\n    -----------\n\n  * **parameter**:\n\n    ----\n     df\n    ----\n     2\n    ----\n\n  * **p.value**: _2.831e-05_\n  * **method**: Pearson's Chi-squared test\n  * **data.name**: table(mtcars$am, mtcars$gear)\n  * **observed**:\n\n    -------------------\n    \u0026nbsp;   3   4   5\n    ------- --- --- ---\n     **0**  15   4   0\n\n     **1**   0   8   5\n    -------------------\n\n  * **expected**:\n\n    -------------------------\n    \u0026nbsp;    3     4     5\n    ------- ----- ----- -----\n     **0**  8.906 7.125 2.969\n\n     **1**  6.094 4.875 2.031\n    -------------------------\n\n  * **residuals**:\n\n    ----------------------------\n    \u0026nbsp;    3      4      5\n    ------- ------ ------ ------\n     **0**  2.042  -1.171 -1.723\n\n     **1**  -2.469 1.415  2.083\n    ----------------------------\n\n  * **stdres**:\n\n    ----------------------------\n    \u0026nbsp;    3      4      5\n    ------- ------ ------ ------\n     **0**  4.395  -2.323 -2.943\n\n     **1**  -4.395 2.323  2.943\n    ----------------------------\n\n\u003c!-- end of list --\u003e\n\n```\n\nSo `pander` showed a not known class in an (almost) user-friendly way. And we got some warnings too styled with [Pandoc **footnote**](https://johnmacfarlane.net/pandoc/README.html#footnotes)! If that document is exported to e.g. `HTML` or `pdf`, then the error/warning message could be found on the bottom of the page with a link. *Note*: there were two warnings in the above call - both captured and returned! Well, this is the feature of `Pandoc.brew`, see [below](#brew-to-pandoc).\n\nBut the output of different **statistical methods** are tried to be prettyfied. Some the above call normally returns like:\n\n```rout\n\u003e pander(chisq.test(table(mtcars$am, mtcars$gear)))\n\n-------------------------------------\n Test statistic   df      P value\n---------------- ---- ---------------\n     20.94        2   2.831e-05 * * *\n-------------------------------------\n\nTable: Pearson's Chi-squared test: `table(mtcars$am, mtcars$gear)`\n\n **WARNING**^[Chi-squared approximation may be incorrect]\n```\n\nA few other examples on the supported R classes:\n\n```rout\n\u003e pander(t.test(extra ~ group, data = sleep))\n\n---------------------------------------------------------\n Test statistic   df    P value   Alternative hypothesis\n---------------- ----- --------- ------------------------\n     -1.861      17.78  0.07939         two.sided\n---------------------------------------------------------\n\nTable: Welch Two Sample t-test: `extra` by `group`\n\n\u003e ## Dobson (1990) Page 93: Randomized Controlled Trial (examples from: ?glm)\n\u003e counts \u003c- c(18, 17, 15, 20, 10, 20, 25, 13, 12)\n\u003e outcome \u003c- gl(3, 1, 9)\n\u003e treatment \u003c- gl(3, 3)\n\u003e m \u003c- glm(counts ~ outcome + treatment, family = poisson())\n\u003e pander(m)\n\n--------------------------------------------------------------\n     \u0026nbsp;        Estimate   Std. Error   z value   Pr(\u003e|z|)\n----------------- ---------- ------------ --------- ----------\n **(Intercept)**    3.045       0.1709      17.81   5.427e-71\n\n  **outcome2**     -0.4543      0.2022     -2.247    0.02465\n\n  **outcome3**      -0.293      0.1927      -1.52     0.1285\n\n **treatment2**   1.338e-15      0.2      6.69e-15      1\n\n **treatment3**   1.421e-15      0.2      7.105e-15     1\n--------------------------------------------------------------\n\nTable: Fitting generalized (poisson/log) linear model: counts ~ outcome + treatment\n\n\u003e pander(anova(m))\n\n--------------------------------------------------------\n    \u0026nbsp;       Df   Deviance   Resid. Df   Resid. Dev\n--------------- ---- ---------- ----------- ------------\n   **NULL**      NA      NA          8         10.58\n\n  **outcome**    2     5.452         6         5.129\n\n **treatment**   2   2.665e-15       4         5.129\n--------------------------------------------------------\n\nTable: Analysis of Deviance Table\n\n\u003e pander(aov(m))\n\n-----------------------------------------------------------\n    \u0026nbsp;       Df   Sum Sq    Mean Sq   F value   Pr(\u003eF)\n--------------- ---- --------- --------- --------- --------\n  **outcome**    2     92.67     46.33     2.224    0.2242\n\n **treatment**   2   8.382e-31 4.191e-31 2.012e-32    1\n\n **Residuals**   4     83.33     20.83      NA        NA\n-----------------------------------------------------------\n\nTable: Analysis of Variance Model\n\n\u003e pander(prcomp(USArrests))\n\n-------------------------------------------------\n    \u0026nbsp;       PC1     PC2      PC3      PC4\n-------------- ------- -------- -------- --------\n  **Murder**   0.0417  -0.04482 0.07989  -0.9949\n\n **Assault**   0.9952  -0.05876 -0.06757 0.03894\n\n **UrbanPop**  0.04634  0.9769  -0.2005  -0.05817\n\n   **Rape**    0.07516  0.2007   0.9741  0.07233\n-------------------------------------------------\n\nTable: Principal Components Analysis\n\n\u003e pander(density(mtcars$hp))\n\n--------------------------------------------\n   \u0026nbsp;      Coordinates   Density values\n------------- ------------- ----------------\n  **Min.**       -32.12          5e-06\n\n **1st Qu.**      80.69        0.0004068\n\n **Median**       193.5         0.001665\n\n  **Mean**        193.5         0.002214\n\n **3rd Qu.**      306.3         0.00409\n\n  **Max.**        419.1         0.006051\n--------------------------------------------\n\nTable: Kernel density of *mtcars$hp* (bandwidth: 28.04104)\n\n\u003e ## Don't like scientific notation?\n\u003e panderOptions('round', 2)\n\u003e pander(density(mtcars$hp))\n\n--------------------------------------------\n   \u0026nbsp;      Coordinates   Density values\n------------- ------------- ----------------\n  **Min.**       -32.12            0\n\n **1st Qu.**      80.69            0\n\n **Median**       193.5            0\n\n  **Mean**        193.5            0\n\n **3rd Qu.**      306.3            0\n\n  **Max.**        419.1           0.01\n--------------------------------------------\n\nTable: Kernel density of *mtcars$hp* (bandwidth: 28.04104)\n\n```\n\nAnd 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`](#pander-options).\n\n# Creating Pandoc documents\n\nThe package is also capable of creating complex Pandoc documents (reports) from **R objects** in multiple ways:\n\n  * create somehow a markdown text file (e.g. with `brew`, `knitr` or any scripts of yours, maybe with `Pandoc.brew` - see just [below](#brew-to-pandoc)) and transform that to other formats (like HTML, odt, PDF, docx etc.) with `Pandoc.convert` - similarly to [`pandoc` function in knitr](https://yihui.org/knitr/demo/pandoc/). Basically this is a wrapper around a [Pandoc](https://johnmacfarlane.net/pandoc/) call, which has not much to do with R actually.\n\n  * users might write some reports with literate programming (similar to `knitr`) in a forked version of [brew](https://cran.r-project.org/package=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](#brew-to-pandoc) is that you do not have to transform your R objects to markdown manually, it's all handled automagically.\n\n    *Example*: this [`README.md`](https://github.com/Rapporter/pander/blob/master/README.md) is cooked with [`Pandoc.brew`](#brew-to-pandoc) based on [`inst/README.brew`](https://github.com/Rapporter/pander/blob/master/inst/README.brew) and also exported to [HTML](https://rapporter.github.io/pander/). Details can be found [below](#brew-to-pandoc) or head directly to [examples](#examples).\n\n\u003c!-- endlist --\u003e\n\n * 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](#live-report-generation).\n\n## Brew to Pandoc\n\nThe [brew](https://cran.r-project.org/package=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`:\n\n  * [slides on \"Building a reporting sytem with BREW\"](https://www.slideshare.net/xavierguardiola/building-a-reporting-sytem-with-brew)\n  * [learnr blogpost on brew](https://learnr.wordpress.com/2009/09/09/brew-creating-repetitive-reports/)\n\n**In short**: 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):\n\n  * `\u003c% ... %\u003e` stand for running inline R commands as usual,\n  * `\u003c%= ... %\u003e` 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.\n\nThis latter tries to be smart in some ways:\n\n  * A code chunk block (R commands between the tags) can return any number of values at any part of the block.\n  * 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.\n  * All warnings/messages and errors are recorded in the blocks and returned in the document as footnotes or inline messages.\n  * All heavy R commands (e.g. those taking more then 0.1 sec to evaluate) are [**cached**](#caching) so re`brew`ing a report would not result in a coffee break.\n\nBesides this, the custom `brew` function can do more and also less compared to the original [`brew` package](https://cran.r-project.org/package=brew). First of all, the internal caching mechanism of `brew` has been removed and rewritten for some extra profits besides improved caching.\n\nFor example now multiple R expressions can be passed between the `\u003c%= ... %\u003e` tags, and not only the text results, but **the evaluated R objects** are also (invisibly) returned in a structured list. This can be really useful while post-processing the results of `brew`. Quick example:\n\n```rout\n\u003e str(Pandoc.brew(text ='\n+   Pi equals to `\u003c%= pi %\u003e`.\n+   And here are some random data:\n+   `\u003c%= runif(10) %\u003e`\n+ '))\n\nPi equals to _3.142_.\nAnd here are some random data:\n_0.6631_, _0.849_, _0.06986_, _0.3343_, _0.5209_, _0.3471_, _0.866_, _0.05548_, _0.8933_ and _0.2121_\n\nList of 2\n $ :List of 4\n  ..$ type  : chr \"text\"\n  ..$ text  :List of 2\n  .. ..$ raw : chr \"Pi equals to _3.142_.\\nAnd here are some random data:\\n\"\n  .. ..$ eval: chr \"Pi equals to _3.142_.\\nAnd here are some random data:\\n\"\n  ..$ chunks:List of 2\n  .. ..$ raw : chr \"_3.142_\"\n  .. ..$ eval: chr \"_3.142_\"\n  ..$ msg   :List of 3\n  .. ..$ messages: NULL\n  .. ..$ warnings: NULL\n  .. ..$ errors  : NULL\n $ :List of 2\n  ..$ type   : chr \"block\"\n  ..$ robject:List of 6\n  .. ..$ src   : chr \"runif(10)\"\n  .. ..$ result: num [1:10] 0.6631 0.849 0.0699 0.3343 0.5209 ...\n  .. ..$ output: chr \"_0.6631_, _0.849_, _0.06986_, _0.3343_, _0.5209_, _0.3471_, _0.866_, _0.05548_, _0.8933_ and _0.2121_\"\n  .. ..$ type  : chr \"numeric\"\n  .. ..$ msg   :List of 3\n  .. .. ..$ messages: NULL\n  .. .. ..$ warnings: NULL\n  .. .. ..$ errors  : NULL\n  .. ..$ stdout: NULL\n  .. ..- attr(*, \"class\")= chr \"evals\"\n```\n\nThis document was generated by `Pandoc.brew` based on [`inst/README.brew`](https://github.com/Rapporter/pander/blob/master/inst/README.brew) so the above examples were generated automatically by running:\n\n```r\nPandoc.brew(system.file('README.brew', package = 'pander'))\n```\n\nThe output is set to `stdout` by default, which means that the resulting text is written to the R console. But setting the `output` to a text file and running Pandoc on that to create a `HTML`, `odt`, `docx` or other document in one go is also possible. To export a brewed file to other then Pandoc's markdown, please use the `convert` parameter. For example:\n\n```r\ntext \u003c- paste('# Header',\n              '',\n              'What a lovely list:\\n\u003c%= as.list(runif(10)) %\u003e',\n              'A wide table:\\n\u003c%= mtcars[1:3, ] %\u003e',\n              'And a nice chart:\\n\\n\u003c%= plot(1:10) %\u003e',\n          sep = '\\n')\nPandoc.brew(text = text, output = tempfile(), convert = 'html')\nPandoc.brew(text = text, output = tempfile(), convert = 'pdf')\n```\n\nSo to brew this README with all R chunks automatically converted to html, please run:\n\n```r\nPandoc.brew(system.file('README.brew', package='pander'), output = tempfile(), convert = 'html')\n```\n\n### Examples\n\nThe package bundles some examples for `Pandoc.brew` to let you check its features pretty fast. These are:\n\n  * [minimal.brew](https://github.com/Rapporter/pander/blob/master/inst/examples/minimal.brew)\n  * [short-code-long-report.brew](https://github.com/Rapporter/pander/blob/master/inst/examples/short-code-long-report.brew)\n  * [graphs.brew](https://github.com/Rapporter/pander/blob/master/inst/examples/graphs.brew)\n\nTo `brew` these examples on your machine, try to run the followings commands:\n\n```r\nPandoc.brew(system.file('examples/minimal.brew', package='pander'))\nPandoc.brew(system.file('examples/minimal.brew', package='pander'), output = tempfile(), convert = 'html')\n\nPandoc.brew(system.file('examples/short-code-long-report.brew', package='pander'))\nPandoc.brew(system.file('examples/short-code-long-report.brew', package='pander'), output = tempfile(), convert = 'html')\n\nPandoc.brew(system.file('examples/graphs.brew', package='pander'))\nPandoc.brew(system.file('examples/graphs.brew', package='pander'), output = tempfile(), convert = 'html')\n```\n\nFor easier access, I have uploaded some exported documents of the above examples as well:\n\n  * minimal.brew: [markdown](https://rapporter.github.io/pander/minimal.md) [html](https://rapporter.github.io/pander/minimal.html) [pdf](https://rapporter.github.io/pander/minimal.pdf) [odt](https://rapporter.github.io/pander/minimal.odt) [docx](https://rapporter.github.io/pander/minimal.docx)\n  * short-code-long-report.brew: [markdown](https://rapporter.github.io/pander/short-code-long-report.md) [html](https://rapporter.github.io/pander/short-code-long-report.html) [pdf](https://rapporter.github.io/pander/short-code-long-report.pdf) [odt](https://rapporter.github.io/pander/short-code-long-report.odt) [docx](https://rapporter.github.io/pander/short-code-long-report.docx)\n  * graphs.brew: [markdown](https://rapporter.github.io/pander/graphs.md) [html](https://rapporter.github.io/pander/graphs.html) [pdf](https://rapporter.github.io/pander/graphs.pdf) [odt](https://rapporter.github.io/pander/graphs.odt) [docx](https://rapporter.github.io/pander/graphs.docx)\n\nPlease check out `pdf`, `docx`, `odt` and other formats by changing the above `convert` option on your machine, and do not forget to [give some feedback](https://github.com/Rapporter/pander/issues)!\n\n## Live report generation\n\n`pander` package has a special reference class called `Pandoc` which could collect some blocks in a live R session and export the whole document to Pandoc/PDF/HTML etc. Without any serious further explanations, please check out the below (self-commenting) example:\n\n```r\n## Initialize a new Pandoc object\nmyReport \u003c- Pandoc$new()\n\n## Add author, title and date of document\nmyReport$author \u003c- 'Gergely Daróczi'\nmyReport$title  \u003c- 'Demo'\n\n## Or it could be done while initializing\nmyReport \u003c- Pandoc$new('Gergely Daróczi', 'Demo')\n\n## Add some free text\nmyReport$add.paragraph('Hello there, this is a really short tutorial!')\n\n## Add maybe a header for later stuff\nmyReport$add.paragraph('# Showing some raw R objects below')\n\n## Adding a short matrix\nmyReport$add(matrix(5,5,5))\n\n## Or a table with even\nmyReport$add.paragraph('Hello table:')\nmyReport$add(table(mtcars$am, mtcars$gear))\n\n## Or a \"large\" data frame which barely fits on a page\nmyReport$add(mtcars)\n\n## And a simple linear model with Anova tables\nml \u003c- with(lm(mpg ~ hp + wt), data = mtcars)\nmyReport$add(ml)\nmyReport$add(anova(ml))\nmyReport$add(aov(ml))\n\n## And do some principal component analysis at last\nmyReport$add(prcomp(USArrests))\n\n## Sorry, I did not show how Pandoc deals with plots:\nmyReport$add(plot(1:10))\n\n## Want to see the report? Just print it:\nmyReport\n\n## Exporting to PDF (default)\nmyReport$export()\n\n## Or to docx in tempdir():\nmyReport$format \u003c- 'docx'\nmyReport$export(tempfile())\n\n## You do not want to see the generated report after generation?\nmyReport$export(open = FALSE)\n```\n\n# Capturing evaluation information with evals\n\nWhen working on the [rapport package](https://rapporter.github.io/rapport/), 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](https://rapporter.github.io/pander/evals.html).\n\nBut probably it's easier to explain what `evals` can do with a simple example:\n\n```rout\n\u003e evals('1:10')\n[[1]]\n$src\n[1] \"1:10\"\n\n$result\n [1]  1  2  3  4  5  6  7  8  9 10\n\n$output\n[1] \" [1]  1  2  3  4  5  6  7  8  9 10\"\n\n$type\n[1] \"integer\"\n\n$msg\n$msg$messages\nNULL\n\n$msg$warnings\nNULL\n\n$msg$errors\nNULL\n\n$stdout\nNULL\n\nattr(,\"class\")\n[1] \"evals\"\n```\n\nSo `evals` can evaluate a character vector of R expressions, and it returns a list of captured stuff while running those:\n\n * `src` holds the R expression,\n * `result` contains the raw R object as is,\n * `output` represents how the R object is printed to the standard output,\n * `type` is the `class` of the returned R object,\n * `msg` is a list of possible messages captured while running the R expression and\n * `stdout` contains if anything was written to the standard output.\n\nBesides capturing this nifty list of important circumstances, `evals` can automatically identify if an R expression is returning anything to a graphical device, and can save the resulting image in a variety of file formats along with some extra options, like applying a custom theme on base, `lattice` or `ggplot2` plots:\n\n```rout\n\u003e evals('hist(mtcars$hp)')[[1]]$result\n![](plots/plot-1.png)\n```\n\nSo instead of a captured R object (which would be `NULL` in this situation by the way), we get the path of the image where the plot was saved:\n\n![](https://raw.githubusercontent.com/Rapporter/pander/gh-pages/plots/graphs-1.png)\n\nWell, this is not a standard histogram usually returned by the `hist` function, right? As mentioned before, `evals` have some extra features like applying the user defined theme on various plots automatically. Please see the `graphs.brew` example [above](#examples) for further details, or check the related [global options](#evals-options). If you do not like this feature, simply add `evalsOptions('graph.unify', FALSE)` to your `.Rprofile`.\n\nFurther features are described in the [technical docs](https://www.rdocumentation.org/packages/pander/functions/evals), and now I'll only give a brief introduction to another important feature of `evals`.\n\n## Caching\n\nAs `pander::evals` is using a **custom caching algorithm** in the means of evaluating R expressions, it might be worthwhile to give a short summary of what is going on in the background when you are running e.g. [`Pandoc.brew`](#brew-to-pandoc), the [\"live report generation\"](#live-report-generation) engine or `evals` directly:\n\n  * Each passed R chunk is `parse`d to single R expressions.\n  * 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).\n  * 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.\n  * 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.\n  * If [`evals`](#evals) can find the cached results in an environment of `pander`'s namespace (if `cache.mode` set to `enviroment` - see [below](#pander-options)) 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.*\n  * 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](#evals-options)).\n\n\u003ca id=\"in-practice\"\u003e\u003c/a\u003e\n\nAs `pander` does not cache based on raw sources of chunks and there is no easy way of enabling/disabling caching on a chunk basis, the users have to live with some *great advantages* and some *minor tricky situations* - which latter cannot be solved theoretically in my opinion, but [I'd love to hear your feedback](https://github.com/Rapporter/pander/issues).\n\nThe 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**:\n\n```r\nx \u003c- mtcars$hp\ny \u003c- 1e3\nevals('sapply(rep(x, y), mean)')\n```\n\nIt took a while, huh? :)\n\nLet us create some custom functions and variables, which are not identical to the above call:\n\n```r\nf \u003c- sapply\ng \u003c- rep\nh \u003c- mean\nX \u003c- mtcars$hp * 1\nY \u003c- 1000\n```\n\nAnd now try to run something like:\n\n```r\nevals('f(g(X, Y), h)')\n```\n\nYes, it was returned from cache!\n\nAbout the **kickback**:\n\nAs `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):\n\n```r\nevals('x \u003c- sapply(rep(mtcars$hp, 1e3), mean)')\n```\n\nIt is cached, just run again, you will see.\n\nBut 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.:\n\n```r\nx \u003c- 'foobar'\nevals('x \u003c- sapply(rep(mtcars$hp, 1e3), mean)')\n```\n\nI 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`](http://dirk.eddelbuettel.com/code/littler.html) - 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.\n\nOther cases when the hash of a call will not match cached hashes:\n\n  * a number is replaced by a variable holding the number, e.g.: `evals('1:5')` vs. `x \u003c- 1:5;evals('x')`\n  * a part of an R object is replaced by a variable holding that, e.g.: `evals('mean(mtcars$hp)')` vs. `x \u003c- mtcars$hp;evals('mean(x)')`\n\nBut the e.g. following do work from cache fine:\n\n```\nx  \u003c- mtcars$hp\nxx \u003c- mtcars$hp*1\nevals('mean(x)')\nevals('mean(xx)')\n```\n\n\u003ca id='pander-options'\u003e\u003c/a\u003e\u003ca id='panderoptions'\u003e\u003c/a\u003e\n\n# General options\n\nThe 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:\n\n  * `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.\n  * `decimal.mark`: string (default: `.`) passed to `format`\n  * `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 `:`.\n  * `big.mark`: string (default: `''`) passed to `format`\n  * `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.\n  * `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)\n  * `keep.line.breaks`: boolean (default: `FALSE`) to keep or remove line breaks from cells in a table\n  * `missing`: string (default: `NA`) to replace missing values in vectors, tables etc.\n  * `date`: string (default: `'%Y/%m/%d %X'`) passed to `format` when printing dates (`POSIXct` or `POSIXt`)\n  * `header.style`: `'atx'` or `'setext'` passed to `pandoc.header`\n  * `list.style`: `'bullet'` (default), `'ordered'` or `'roman'` passed to `pandoc.list`. Please not that this has no effect on `pander` methods.\n  * `table.style`: `'multiline'`, `'grid'` or `'simple'` passed to `pandoc.table`\n  * `table.emphasize.rownames`: boolean (default: `TRUE`) if row names should be highlighted\n  * `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 :)\n  * `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.\n  * `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 `:`.\n  * `table.continues`: string (default: `Table continues below`) passed to `pandoc.table` to be used as caption for long (split) without a use defined caption\n  * `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\n  * `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`\n  * `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`\n  * `use.hyphening`: boolean (default: `FALSE`) if try to use hyphening when splitting large cells according to table.split.cells. Requires `sylly` package.\n  * `evals.messages`: boolean (default: `TRUE`) passed to `evals`' `pander` method specifying if messages should be rendered\n  * `p.wrap`: a string (default:`'_'`) to wrap vector elements passed to `p` function\n  * `p.sep`: a string (default: `', '`) with the main separator passed to `p` function\n  * `p.copula`: a string (default: `'and'`) a string with ending separator passed to `p` function\n  * `plain.ascii`: boolean (default: FALSE) to define if output should be in plain ascii or not\n  * `graph.nomargin`: boolean (default: `TRUE`) if trying to keep plots' margins at minimal\n  * `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.\n  * `graph.fontcolor`: string (default: `'black'`) specifying the default font color\n  * `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.\n  * `graph.grid`: boolean (default: `TRUE`) if a grid should be added to the plot\n  * `graph.grid.minor`: boolean (default: `TRUE`) if a miner grid should be also rendered\n  * `graph.grid.color`: string (default: `'grey'`) specifying the color of the rendered grid\n  * `graph.grid.lty`: string (default: `'dashed'`) specifying the line type of grid\n  * `graph.boxes`: boolean (default: `FALSE`) if to render a border around of plot (and e.g. around strip)\n  * `graph.legend.position`: string (default: `'right'`) specifying the position of the legend: 'top', 'right', 'bottom' or 'left'\n  * `graph.background`: string (default: `'white'`) specifying the plots main background's color\n  * `graph.panel.background`: string (default: `'transparent'`) specifying the plot's main panel background. Please *note*, that this option is not supported with `base` graphics.\n  * `graph.colors`: character vector of default color palette (defaults to a [colorblind theme](https://jfly.uni-koeln.de/color/)). Please *note* that this update work with `base` plots by appending the `col` argument to the call if not set.\n  * `graph.color.rnd`: boolean (default: `FALSE`) specifying if the palette should be reordered randomly before rendering each plot to get colorful images\n  * `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:\n\n      *  `1`: parallel to the axis,\n      *  `2`: horizontal,\n      *  `3`: perpendicular to the axis or\n      *  `4`: vertical.\n\n  * `graph.symbol`: numeric (default: `1`) specifying a symbol (see the `pch` parameter of `par`)\n  * `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`.\n\n\u003ca id='evals-options'\u003e\u003c/a\u003e\u003ca id='evalsoptions'\u003e\u003c/a\u003e\n\nBesides 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](#caching) or the format of rendered image files. You can query/update those with the `evalsOptions` function as the main backend of `pander` calls is a custom evaluation function called [`evals`](#evals).\n\nThe list of possible options are:\n\n  * `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`](#evals) would not try to parse R code, it would get evaluated in separate runs - as provided. Please see the documentation of [`evals`](#evals).\n  * `cache`: [caching](#caching) the result of R calls if set to `TRUE`\n  * `cache.mode`: cached results could be stored in an `environment` in _current_ R session or let it be permanent on `disk`.\n  * `cache.dir`: path to a directory holding cache files if `cache.mode` set to `disk`. Default set to `.cache` in current working directory.\n  * `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).\n  * `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.\n  * `classes`: a vector or list of classes which should be returned. If set to `NULL` (by default) all R objects will be returned.\n  * `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`](#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!\n  * `length`: any R object exceeding the specified length will not be returned. The default value (`Inf`) does not filter out any R objects.\n  * `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`](#evals).\n  * `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 :)\n  * `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.\n  * `graph.dir`: path to a directory where to place generated images. If the directory does not exist, [`evals`](#evals) try to create that. Default set to `plots` in current working directory.\n  * `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.\n  * `width`: width of generated plot in pixels for even vector formats\n  * `height`: height of generated plot in pixels for even vector formats\n  * `res`: nominal resolution in `ppi`. The height and width of vector images will be calculated based in this.\n  * `hi.res`: generate high resolution plots also? If set to `TRUE`, each R code parts resulting an image would be run twice.\n  * `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.\n  * `graph.env`: save the environments in which plots were generated to distinct files (based on `graph.name`) with `env` extension?\n  * `graph.recordplot`: save the plot via `recordPlot` to distinct files (based on `graph.name`) with `recodplot` extension?\n  * `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?\n  * `log`: `NULL` or an optionally passed *namespace* for `logger` to record all info, trace, debug and error messages.\n\n# Difference from other rendering packages\n\nHow does `pander` differ from Sweave, brew, knitr, R2HTML and the other tools of literate programming? First of all `pander` can be used as a helper with any other literate programming solution, so **you can call `pander` inside of `knitr` chunks**.\n\nBut if you stick with `pander`'s literate programming engine, then there's not much need for calling `ascii`, `xtable`, `Hmisc`, `tables` etc. or even `pander` in the R command chunks to **transform R objects** into markdown, HTML, tex etc. as `Pandoc.brew` automatically results in Pandoc's markdown, which can be converted to almost any text document format. Conversion can be done automatically after calling `pander` reporting functions ([Pander.brew](#brew-to-pandoc) or [Pandoc](#live-report-generation)).\n\nBased on the fact that `pander` transforms R objects into markdown, **no \"traditional\" R console output is shown** in the resulting document (nor in markdown, nor in exported docs), but **all R objects are transformed to tables, list etc**. Well, there is an option (`show.src`) to show the original R commands before the formatted output, and `pander` calls can be also easily tweaked to return the printed version of the R objects - if you would need that in some strange situation - like writing an R tutorial. But  really think that nor R code, nor raw R results have anything to do with an exported report.\n\nOf course **all warnings, messages and errors are captured** while evaluating R expressions just like `stdout` besides the **raw R objects**. So the resulting report also includes the raw R objects for further edits if needed - which is a very unique feature.\n\n**Graphs and plots are automatically identified** in code chunks and saved to disk in a `png` file linked in the resulting document. This means that if you create a report (e.g. `brew` a text file) and export it to PDF/docx etc. all the plots/images would be there. There are some parameters to specify the resolution of the image and also the type (e.g. `jpg`, `svg` or `pdf`) besides a **wide variety of [theme options](#pander-options)**. About the latter, please check the `graphs.brew` example [above](#examples).\n\nAnd `pander` uses its built-in (IMHO quite decent) [**caching**](#caching) engine. This means that if the evaluation of some R commands takes too long time (which can be set by option/parameter), then the results are saved in a file and returned from there on next similar R code's evaluation. This caching algorithm tries to be smart, as it not only  checks the passed R sources, but the content of all variables and functions, and saves the hash of those. This is a quite secure way of caching (see details [above](#caching)), but if you would encounter any issues, just switch off the cache. I've not seen any issues for years :)\n\n# ESS\n\nI 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](https://github.com/Rapporter/pander/blob/master/inst/pander.el), feel free to personalize.\n\nAs time passed these small functions grew heavier (with my Emacs knowledge) so I ended up with a small library:\n\n## pander-mode\n\nI am currently working on `pander-mode` which is a small *minor-mode* for Emacs. There are a few (but useful) functions with default keybindings:\n\n  * `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.\n  * `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.\n  * `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.\n\nFew options of `pander-mode`: `M-x customize-group pander`\n\n  * `pander-clipboard`: If non-nil then the result of `pander-*` functions would be copied to clipboard.\n  * `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.\n\nTo use this small lib, just type: `M-x pander-mode` on any document. It might be useful to add a hook to `markdown-mode` if you find this useful.\n\n\u003cscript type=\"text/javascript\"\u003e\n    $(document).ready(function() {\n        $('#logo').empty();\n        $('img[src=\"https://travis-ci.org/Rapporter/pander.png?branch=master\"]').css('border', 'none').css('padding', '0px').parent().parent().css('text-align', 'justify');\n        $('img[src=\"https://coveralls.io/repos/Rapporter/pander/badge.svg?branch=master\"]').css('border', 'none').css('padding', '0px').parent().parent().css('text-align', 'justify');\n        $('nav').css('height', '100%');\n        $(\"img\").unbind(\"click\");\n    });\n\u003c/script\u003e\n\u003ca href=\"https://github.com/Rapporter/pander\"\u003e\u003cimg style=\"position: fixed; top: -5px; right: -5px; border: 0;\" src=\"https://camo.githubusercontent.com/38ef81f8aca64bb9a64448d0d70f1308ef5341ab/68747470733a2f2f73332e616d617a6f6e6177732e636f6d2f6769746875622f726962626f6e732f666f726b6d655f72696768745f6461726b626c75655f3132313632312e706e67\" data-canonical-src=\"https://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png\"\u003e\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FRapporter%2Fpander","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FRapporter%2Fpander","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FRapporter%2Fpander/lists"}