An Introduction to the printr Package

In printr: Automatically Print R Objects to Appropriate Formats According to the 'knitr' Output Format

options(width = 80)

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 as well as installation instructions 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)
head(iris)

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')

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

When help pages are really long, we can use the chunk option printr.help.sections to select a few sections to display, e.g. we only show the sections description and usage of the paste() function:

?paste

Vignette/dataset lists

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

vignette(package = 'rpart')
vignette(package = c('rpart', 'knitr'))
data(package = 'lattice')
data(package = c('rpart', 'lattice'))
data(package = 'knitr')  # no datasets here
browseVignettes(package = 'knitr')

Package info

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

library(help = 'printr')

printr documentation built on March 31, 2023, 9:04 p.m.