rapport-package: rapport: an R engine for reproducible template generation

Description

rapport is an R package that facilitates creation of reproducible statistical report templates. Once created, rapport templates can be exported to various external formats: HTML, LaTeX, PDF, ODT, etc.

Arguments

Details

For detailed introductions please check out our homepage: http://rapport-package.info.

You may use the package-bundled templates with a minimal R knowledge - a quick tutorial is shown in the package demo: demo(rapport).

Apart from R, all you need to know to start writing your own templates is pandoc markup syntax, and several rapport-specific conventions that allow the reproducibility of the template. rapport uses brew-like tags to support dynamic inline and/or block evaluation of R code. Unlike many other report-writing conventions in R (Sweave, brew, knitr), rapport converts generated output to a convenient form via ascii package and appropriate preprocessing backend tools. rapport also comes with support for plots: images are automatically saved to temporary file, and image path is returned or redrawn on demand.

The output of rapport command depends on various package-specific options. Please skim through the summary of following options:

tpl.user: a (user)name to show in exported report (defaults to"Anonymous")
tpl.email: a user's e-mail address to show in exported report (defaults to an empty string).
rapport.modedefines the manner in whichrapportevaluates the templates - by default it is set tonormal. Innormalmodelink{rapport}would check all non-strict templates (see:tpl.check) "linewise", and that can cause huge overhead, whileperformancemode would not perform cautious checks and evaluate all commands at once. That is not a problem if you writestricttemplates, which is really advised.debugmode is appropriate for developers, as it will interrupt the execution if template contains any errors.
By defaultrapportfunction saves plots to image files (see the settings below) andprintmethod just shows the path(s) of the generated image(s). If you would like to see the plot(s) when callingrapportfunction from an interactive R console, please setgraph.recordandgraph.replayoptions toTRUEbeforehand. In that case all generated plots will be displayed after printing therapportobject. These options are set toFALSEby default although we find these settings really handy, as you can resize the images on the fly and export resized images to HTML/ODT/DOCX/PDF etc. If you would even like to save the actual environment of each generated plot (variables, data sets etc.) as anRDatafile, please setgraph.save.envtoTRUE.
rapportalso has some options to set formatting style of numbers, characters and dates. The decimals needed for automatic rounding is defined inrp.decimalandrp.decimal.shortoptions which are by default set to4and2, respectively. Inline numeric values are presented in a short form, while the tables use the long form. The decimal mark can be set easily to e.g.","inrp.decimal.markoption, and the date format can be specified in POSIX format viarp.date.formatoption.
the exported graphs can be customised via following options:
- The most basic option isstyle.themewhich points to alattice/trellistheme, and uses defaultrapporttheme:theme.rapport. If you do not like this minimalistic bluish theme, you might reconsider using e.g.standard.theme()fromlattice,ggplot2like()ortheEconomist.theme()themes available inlatticeExtrapackage or eithercustom.theme.black()fromlatticistpackage. Of course, custom theme might be provided too - check out the?custom.themefromlatticeExtrapackage or head directly to:trellis.par.get.
- theme.rapportcan deal with a great number of colour palettes. By default it usesdefaulttheme specified instyle.color.paletteoption, which is both print and colourblind-friendly palette (visithttp://jfly.iam.u-tokyo.ac.jp/color/for details). Of course, other palettes can be specified there, just check outbrewer.pal.info. If you would like to get really colourful plots, you might consider settingstyle.colorizeoption toTRUEas it will choose random colours from a given palette for each plot.
- By defaultrapporttries to generate images with Helvetica font family as it's a neat, OS independent font. If you don't like that, you can change thestyle.fontoption. Note that you might need to set the font family afterwards, especially on Windows machines (seewindowsFontsfor details).
- While the most graph functions inrapportcan "decide" if showing a grid in the background is a good idea or not, there is a global option for all other graph functions:graph.grid. It is possible to render a grid for both axes ("both") or separate axes only ("x"or"y")."none"results in a blank background.
- The plots are saved to disk withrapportfunction, and the resulting files can be customised with several options:
  - graph.formatoption holds the plot output format:"png","jpg","bmp","tiff","svg"or"pdf"
  - graph.widthandgraph.heightoptions hold settings for plot width and height, respectively
  - graph.ressets the default resolution in points per inch (ppi). If you would like to export images to high resolution regardless of the specified dimensions, setgraph.hi.resoption toTRUE. That can be really handy in HTML exports as the images get "zoomable" on click. Note: generating high resolution images has some overhead as plots are generated twice.
pfunction concatenates vector values to a nicely formatted string by using the values from global options (see help page forpfor details).
Developers might find the list of options inrp.tagsinteresting, as it lets users to specify custom tags forrapportchunks. By changing the default values you may create custom reports and use your own syntax in custom templates. However,rapport