The printr (read “printer” or “print R”) package is a companion package to knitr. Its main purpose is to extend the S3 generic function knit_print() in knitr, which is the default value of the chunk option render, as explained in the vignette knit_print.html.

Overview

To enable the printing methods defined in this package, just library(printr) or loadNamespace('printr') in a code chunk (in the beginning) of your knitr document. Then some objects will be printed differently with what you would have seen in a normal R console. For example:

• matrices, data frames, and contingency tables are printed as tables (LaTeX, HTML, or Markdown, depending on your output format)
• the help page (from ?foo or help(foo)) can be rendered as HTML, LaTeX, or plain text, and you can also specify which section(s) of the help page to include in the output
• the results from browseVignettes(), help.search(), data(), and vignette() are rendered as tables
• the package information from library(help = 'foo') is rendered as plain text

To disable the printing methods in this package, you can call detach('package:printr', unload = TRUE) if you attached the package via library(printr) before, or unloadNamespace('printr') if you loaded it via loadNamespace('printr').

This package aims to be portable in the sense that it should work in most document formats, including *.Rnw (R + LaTeX), *.Rmd (R Markdown), and *.Rhtml (R + HTML) files, etc.

You can find the package source on Github, and you are welcome to contribute code via pull requests, or file feature requests and bug reports via Github issues.

Examples

First we take a look at a quick example of printing some R objects in the R console:

> # R uses plain text representation for data frames/matrices/...
> head(mtcars)

                   mpg cyl disp  hp drat    wt  qsec vs am gear carb
Mazda RX4         21.0   6  160 110 3.90 2.620 16.46  0  1    4    4
Mazda RX4 Wag     21.0   6  160 110 3.90 2.875 17.02  0  1    4    4
Datsun 710        22.8   4  108  93 3.85 2.320 18.61  1  1    4    1
Hornet 4 Drive    21.4   6  258 110 3.08 3.215 19.44  1  0    3    1
Hornet Sportabout 18.7   8  360 175 3.15 3.440 17.02  0  0    3    2
Valiant           18.1   6  225 105 2.76 3.460 20.22  1  0    3    1

> head(iris)

  Sepal.Length Sepal.Width Petal.Length Petal.Width Species
1          5.1         3.5          1.4         0.2  setosa
2          4.9         3.0          1.4         0.2  setosa
3          4.7         3.2          1.3         0.2  setosa
4          4.6         3.1          1.5         0.2  setosa
5          5.0         3.6          1.4         0.2  setosa
6          5.4         3.9          1.7         0.4  setosa

Then we attach the printr package in this R session, and see how things change later:

library(printr)

Matrices/data frames/tables

Matrices and data frames are printed as tables using the kable() function in knitr:

options(digits = 4)
set.seed(123)
x = matrix(rnorm(40), 5)
x

# with colunm names
dimnames(x) = list(NULL, head(LETTERS, ncol(x)))
x

# further customization via kable(), e.g. digits and captions
knitr::kable(x, digits = 2, caption = 'A table produced by printr.')

head(mtcars)

head(iris, 10)

For contingency tables, 1-d tables are printed as a 1-row matrix, 2-d tables are printed an \(n \times m\) matrix, and tables of higher dimensions are printed as data frames with frequencies.

x1 = sample(letters[1:3], 1000, TRUE)
x2 = sample(letters[1:3], 1000, TRUE)
x3 = sample(letters[1:3], 1000, TRUE)
table(x1)

table(x1, x2)

table(x1, x2, x3)

Search results from help.search()

Here are some examples demonstrating the results of help.search(), or you can also use ?? to search for a string.

??sunflower

help.search('contourplot')

help.search('foo', package = 'base')

help.search('foooooooo', package = 'utils')

## No results found

In a normal R session, the results will be displayed as an HTML page by default, but normally these functions are meant to be called in an interactive R session, and knitr documents are often compiled in non-interactive R sessions, so we changed the printing behavior of these results, and readers will get the basic idea of these functions when reading the knitr output. If they want to run these functions by themselves, they can do it in an interactive R session.

Help pages

When you want to read the help page of a certain R object, you normally use ? or help(), which will launch a separate help page from the R session, and require human interaction. Again, we may not desire human interactions in knitr documents, so the help pages are printed as static documents here.

?coef

## Extract Model Coefficients
## 
## Description:
## 
##      'coef' is a generic function which extracts model coefficients
##      from objects returned by modeling functions.  'coefficients' is an
##      _alias_ for it.
## 
## Usage:
## 
##      coef(object, ...)
##      coefficients(object, ...)
##      
## Arguments:
## 
##   object: an object for which the extraction of model coefficients is
##           meaningful.
## 
##      ...: other arguments.
## 
## Details:
## 
##      All object classes which are returned by model fitting functions
##      should provide a 'coef' method or use the default one.  (Note that
##      the method is for 'coef' and not 'coefficients'.)
## 
##      Class '"aov"' has a 'coef' method that does not report aliased
##      coefficients (see 'alias').
## 
## Value:
## 
##      Coefficients extracted from the model object 'object'.
## 
##      For standard model fitting classes this will be a named numeric
##      vector.  For '"maov"' objects (produced by 'aov') it will be a
##      matrix.
## 
## References:
## 
##      Chambers, J. M. and Hastie, T. J. (1992) _Statistical Models in
##      S_.  Wadsworth & Brooks/Cole.
## 
## See Also:
## 
##      'fitted.values' and 'residuals' for related methods; 'glm', 'lm'
##      for model fitting.
## 
## Examples:
## 
##      x <- 1:5; coef(lm(c(1:3, 7, 6) ~ x))
## 

When help pages are really long, we can use the chunk option render.args$help$sections^[The $ notation here means the chunk option should be of the form render.args = list(help = list(sections = VALUES)).] to select a few sections to display, e.g. we only show the sections description and usage of the paste() function:

?paste

## Concatenate Strings
## 
## Description:
## 
##      Concatenate vectors after converting to character.
## 
## Usage:
## 
##      paste (..., sep = " ", collapse = NULL)
##      paste0(..., collapse = NULL)
## 

Vignette/dataset lists

We can print the lists of vignettes and datasets in packages using vignette() and data(), respectively.

vignette(package = 'rpart')

## Error in kable(x, options$printr.table.format, caption = options$printr.table.caption, : formal argument "caption" matched by multiple actual arguments

vignette(package = c('rpart', 'knitr'))

## Error in kable(x, options$printr.table.format, caption = options$printr.table.caption, : formal argument "caption" matched by multiple actual arguments

data(package = 'lattice')

## Error in kable(x, options$printr.table.format, caption = options$printr.table.caption, : formal argument "caption" matched by multiple actual arguments

data(package = c('rpart', 'lattice'))

## Error in kable(x, options$printr.table.format, caption = options$printr.table.caption, : formal argument "caption" matched by multiple actual arguments

data(package = 'knitr')  # no datasets here

## Data sets not found

browseVignettes(package = 'knitr')

Package info

A description of a package can be printed via library(help = 'foo'):

library(help = 'printr')

        Information on package 'printr'

Description:

Package:           printr
Type:              Package
Title:             Automatically Print R Objects According to knitr Output Format
Version:           0.0.7
Date:              2014-09-04
Author:            Yihui Xie
Maintainer:        Yihui Xie <xie@yihui.name>
Description:       Extends the S3 generic function knit_print() in knitr to automatically
                   print some objects using an appropriate format such as Markdown or
                   LaTeX. For example, data frames are automatically printed as tables,
                   and the help() pages can also be rendered in knitr documents.
Imports:           knitr (>= 1.11)
Suggests:          tools, rmarkdown
License:           GPL
URL:               http://yihui.name/printr
BugReports:        https://github.com/yihui/printr/issues
VignetteBuilder:   knitr
LazyData:          TRUE
RoxygenNote:       6.0.1
Built:             R 3.3.3; ; 2017-05-18 20:19:46 UTC; unix

Index:

printr                  Print R objects in 'knitr' documents nicely