An Introduction to the printr Package

Yihui Xie

2023-03-08

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.

1 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:

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.

2 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)
## Registered S3 method overwritten by 'printr':
##   method                from     
##   knit_print.data.frame rmarkdown

2.1 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
-0.5605 1.7151 1.2241 1.7869 -1.0678 -1.6867 0.4265 0.6886
-0.2302 0.4609 0.3598 0.4979 -0.2180 0.8378 -0.2951 0.5539
1.5587 -1.2651 0.4008 -1.9666 -1.0260 0.1534 0.8951 -0.0619
0.0705 -0.6869 0.1107 0.7014 -0.7289 -1.1381 0.8781 -0.3060
0.1293 -0.4457 -0.5558 -0.4728 -0.6250 1.2538 0.8216 -0.3805
# with colunm names
dimnames(x) = list(NULL, head(LETTERS, ncol(x)))
x
A B C D E F G H
-0.5605 1.7151 1.2241 1.7869 -1.0678 -1.6867 0.4265 0.6886
-0.2302 0.4609 0.3598 0.4979 -0.2180 0.8378 -0.2951 0.5539
1.5587 -1.2651 0.4008 -1.9666 -1.0260 0.1534 0.8951 -0.0619
0.0705 -0.6869 0.1107 0.7014 -0.7289 -1.1381 0.8781 -0.3060
0.1293 -0.4457 -0.5558 -0.4728 -0.6250 1.2538 0.8216 -0.3805
# further customization via kable(), e.g. digits and captions
knitr::kable(x, digits = 2, caption = 'A table produced by printr.')
A table produced by printr.
A B C D E F G H
-0.56 1.72 1.22 1.79 -1.07 -1.69 0.43 0.69
-0.23 0.46 0.36 0.50 -0.22 0.84 -0.30 0.55
1.56 -1.27 0.40 -1.97 -1.03 0.15 0.90 -0.06
0.07 -0.69 0.11 0.70 -0.73 -1.14 0.88 -0.31
0.13 -0.45 -0.56 -0.47 -0.63 1.25 0.82 -0.38
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, 10)
Sepal.Length Sepal.Width Petal.Length Petal.Width Species
5.1 3.5 1.4 0.2 setosa
4.9 3.0 1.4 0.2 setosa
4.7 3.2 1.3 0.2 setosa
4.6 3.1 1.5 0.2 setosa
5.0 3.6 1.4 0.2 setosa
5.4 3.9 1.7 0.4 setosa
4.6 3.4 1.4 0.3 setosa
5.0 3.4 1.5 0.2 setosa
4.4 2.9 1.4 0.2 setosa
4.9 3.1 1.5 0.1 setosa

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)
a b c
320 331 349
table(x1, x2)
x1/x2 a b c
a 103 109 108
b 108 115 108
c 123 103 123
table(x1, x2, x3)
x1 x2 x3 Freq
a a a 41
b 26
c 36
b a 34
b 31
c 44
c a 34
b 33
c 41
b a a 37
b 36
c 35
b a 40
b 31
c 44
c a 36
b 38
c 34
c a a 31
b 46
c 46
b a 25
b 35
c 43
c a 46
b 46
c 31

2.2 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
Package Topic Title
grDevices xyTable Multiplicities of (x,y) Points, e.g., for a Sunflower Plot
graphics sunflowerplot Produce a Sunflower Scatter Plot
help.search('contourplot')
Package Topic Type Title
MSG ChinaPop demo symbols characterizing the Chinese population based on a contour plot
MSG contourPop demo a contour plot of the data ChinaLifeEdu
MSG volcano demo a filled contour plot of the volcano data
graphics filled.contour help Level (Contour) Plots
lattice levelplot help Level plots and contour plots
lattice panel.levelplot help Panel Functions for levelplot and contourplot
help.search('foo', package = 'base')
Package Topic Title
base is.things Explore some properties of R objects and is.FOO() functions. Not for newbies!
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.

2.3 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
coefR Documentation

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, ...)
## Default S3 method:
coef(object, complete = TRUE, ...)
## S3 method for class 'aov'
coef(object, complete = FALSE, ...)

Arguments

object

an object for which the extraction of model coefficients is meaningful.

complete

for the default (used for lm, etc) and aov methods: logical indicating if the full coefficient vector should be returned also in case of an over-determined system where some coefficients will be set to NA, see also alias. Note that the default differs for lm() and aov() results.

...

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

The "aov" method does not report aliased coefficients (see alias) by default where complete = FALSE.

The complete argument also exists for compatibility with vcov methods, and coef and aov methods for other classes should typically also keep the complete = * behavior in sync. By that, with p <- length(coef(obj, complete = TF)), dim(vcov(obj, complete = TF)) == c(p,p) will be fulfilled for both complete settings and the default.

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 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
pasteR Documentation

Concatenate Strings

Description

Concatenate vectors after converting to character.

Usage

paste (..., sep = " ", collapse = NULL, recycle0 = FALSE)
paste0(...,            collapse = NULL, recycle0 = FALSE)

2.4 Vignette/dataset lists

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

vignette(package = 'rpart')
Vignettes in rpart
Item Title
longintro Introduction to Rpart (source, pdf)
usercode User Written Split Functions (source, pdf)
vignette(package = c('rpart', 'knitr'))
Vignettes
Package Item Title
rpart longintro Introduction to Rpart (source, pdf)
rpart usercode User Written Split Functions (source, pdf)
knitr knitr-html An R HTML Vignette with knitr (source, html)
knitr knitr-markdown An R Markdown Vignette with knitr (source, html)
knitr knit_print Custom Print Methods (source, html)
knitr datatables Display Tables with the JavaScript Library DataTables (source, html)
knitr knitr-intro Not an Introduction to knitr (source, html)
knitr docco-classic R Markdown with the Docco Classic Style (source, html)
knitr docco-linear R Markdown with the Docco Linear Style (source, html)
knitr knit_expand Templating with knit_expand() (source, html)
knitr knitr-refcard knitr Reference Card (source, html)
data(package = 'lattice')
Data sets in lattice
Item Title
USMortality Mortality Rates in US by Cause and Gender
USRegionalMortality Mortality Rates in US by Cause and Gender
barley Yield data from a Minnesota barley trial
environmental Atmospheric environmental conditions in New York City
ethanol Engine exhaust fumes from burning ethanol
melanoma Melanoma skin cancer incidence
singer Heights of New York Choral Society singers
data(package = c('rpart', 'lattice'))
Data sets
Package Item Title
rpart car.test.frame Automobile Data from ‘Consumer Reports’ 1990
rpart car90 Automobile Data from ‘Consumer Reports’ 1990
rpart cu.summary Automobile Data from ‘Consumer Reports’ 1990
rpart kyphosis Data on Children who have had Corrective Spinal Surgery
rpart solder Soldering of Components on Printed-Circuit Boards
rpart solder.balance (solder) Soldering of Components on Printed-Circuit Boards
rpart stagec Stage C Prostate Cancer
lattice USMortality Mortality Rates in US by Cause and Gender
lattice USRegionalMortality Mortality Rates in US by Cause and Gender
lattice barley Yield data from a Minnesota barley trial
lattice environmental Atmospheric environmental conditions in New York City
lattice ethanol Engine exhaust fumes from burning ethanol
lattice melanoma Melanoma skin cancer incidence
lattice singer Heights of New York Choral Society singers
data(package = 'knitr')  # no datasets here
## Data sets not found
browseVignettes(package = 'knitr')
Vignette Title
knitr-html.html An R HTML Vignette with knitr
knitr-markdown.html An R Markdown Vignette with knitr
knit_print.html Custom Print Methods
datatables.html Display Tables with the JavaScript Library DataTables
knitr-intro.html Not an Introduction to knitr
docco-classic.html R Markdown with the Docco Classic Style
docco-linear.html R Markdown with the Docco Linear Style
knit_expand.html Templating with knit_expand()
knitr-refcard.html knitr Reference Card

2.5 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 to Appropriate Formats According to the
                   'knitr' Output Format
Version:           0.3
Authors@R:         c( person("Yihui", "Xie", role = c("aut", "cre"), email =
                   "xie@yihui.name", comment = c(ORCID = "0000-0003-0645-5666")) )
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.31)
Suggests:          tools, rmarkdown
License:           GPL
URL:               https://yihui.org/printr/
BugReports:        https://github.com/yihui/printr/issues
VignetteBuilder:   knitr
RoxygenNote:       7.2.3
Encoding:          UTF-8
Author:            Yihui Xie [aut, cre] (<https://orcid.org/0000-0003-0645-5666>)
Maintainer:        Yihui Xie <xie@yihui.name>
Built:             R 4.2.2; ; 2023-03-08 19:27:17 UTC; unix

Index:

printr                  Print R objects in 'knitr' documents nicely