sprinkle: Define Customizations to a Table

Description

Customizations to a dust table are added by "sprinkling" with a little extra pixie dust. Sprinkles are a collection of attributes to be applied over a subset of table cells. They may be added to any part of the table, or to the table as a whole.

Usage

sprinkle(
  x,
  rows = NULL,
  cols = NULL,
  ...,
  part = c("body", "head", "foot", "interfoot", "table")
)
# S3 method for default
sprinkle(
  x,
  rows = NULL,
  cols = NULL,
  ...,
  part = c("body", "head", "foot", "interfoot", "table"),
  fixed = FALSE,
  recycle = c("none", "rows", "cols", "columns")
)
# S3 method for dust_list
sprinkle(
  x,
  rows = NULL,
  cols = NULL,
  ...,
  part = c("body", "head", "foot", "interfoot", "table")
)
sprinkle_print_method(
  x,
  print_method = c("console", "markdown", "html", "latex")
)
# S3 method for default
sprinkle_print_method(
  x,
  print_method = c("console", "markdown", "html", "latex", "docx")
)
# S3 method for dust_list
sprinkle_print_method(
  x,
  print_method = c("console", "markdown", "html", "latex")
)
sprinkle_table(x, cols = NULL, ..., part = "table")
# S3 method for default
sprinkle_table(x, cols = NULL, ..., part = "table")
# S3 method for dust_list
sprinkle_table(x, cols = NULL, ..., part = "table")

Arguments

x: A dust object
rows: A numeric vector specifying the rows of the table to sprinkle. See details for more about sprinkling.
cols: A numeric (or character) vector specifying the columns (or column names) to sprinkle. See details for more about sprinkling.
...: named arguments, each of length 1, defining the customizations for the given cells. See "Sprinkles" for a listing of these arguments.
part: A character string denoting which part of the table to modify.
fixed: logical(1) indicating if the values in rows and cols should be read as fixed coordinate pairs. By default, sprinkles are applied at the intersection of rows and cols, meaning that the arguments do not have to share the same length. When fixed = TRUE, they must share the same length.
recycle: A character one that determines how sprinkles are managed when the sprinkle input doesn't match the length of the region to be sprinkled. By default, recycling is turned off. Recycling may be performed across rows first (left to right, top to bottom), or down columns first (top to bottom, left to right).
print_method: A character string giving the print method for the table. Note: "docx" is synonymous with "markdown".

Sprinkles

The following table describes the valid sprinkles that may be defined in the ... dots argument. All sprinkles may be defined for any output type, but only sprinkles recognized by that output type will be applied when printed. A more readable format of this information is available in vignette("sprinkles", package = "pixiedust").

bg
	action	Modifies the background color of a cell.
	default
	accepts	dvips color names; rgb(R,G,B); rgba(R,G,B,A);
		#RRGGBB; #RRGGBBAA. See the "Colors" section
		for further details.
	console	Not recognized
	markdown	Not recognized
	html	Accepts any of the listed formats;
		recognizes transparency
	latex	Accepts any of the listed formats,
		but ignores transparency
bg_pattern
	action	Generates a pattern of background colors.
		Can be used to make striping
		by rows or by columns.
	default	c("#FFFFFF", "#DDDDDD")
	accepts	A vector of color names:
		dvips color names; rgb(R,G,B); rgba(R,G,B,A);
		#RRGGBB; #RRGGBBAA
	console	Not recognized
	markdown	Not recognized
	html	Accepts any of the listed formats;
		recognizes transparency
	latex	Accepts any of the listed formats,
		but ignores transparency
bg_pattern_by
	action	Determines if a `bg_pattern` is patterned
		by row or by columns.
	default	"rows"
	accepts	"rows", "columns", "cols"
	console	Not recognized
	markdown	Not recognized
	html	Recognized
	latex	Recognized
bold
	action	Renders text within a cell in bold.
	default	FALSE
	accepts	logical(1)
	console	Recognized; rendered as double asterisks on either
		side of the text
	markdown	Recognized
	html	Recognized
	latex	Recognized
border_collapse
	action	Sets the `border-collapse` property in an
		HTML table. The property sets whether the
		table borders are collapsed into a
		single border or detached as in standard HTML.
	default	TRUE
	accepts	logical(1)
	console	Not recognized
	markdown	Not recognized
	html	Recognized
	latex	Not recognized
border
	action	Sets a border on the specified side of a cell.
	default
	accepts	Any combination of "all", "bottom", "left", "top",
		"right". Using "all" results in all borders
		being drawn, regardless of what other values are
		passed with it.
	console	Not recognized
	markdown	Not recognized
	html	Recognized
	latex	Recognized
border_color
	action	Sets the color of the borders specified for a cell.
	default	"Black"
	accepts	character(1)
		dvips color names; rgb(R,G,B); rgba(R,G,B,A);
		#RRGGBB; #RRGGBBAA. See the "Colors" section
		for further details.
	console	Not recognized
	markdown	Not recognized
	html	Recognized
	latex	Recognized
border_style
	action	Sets the border style for a specified cell
	default	"solid"
	accepts	character(1)
		"solid", "dashed", "dotted", "double", "groove",
		"ridge", "inset", "outset", "hidden", "none"
	console	Not recognized
	markdown	Not recognized
	html	Accepts any of the values listed.
	latex; hhline = FALSE	accepts "solid", "dashed", "dotted",
		"hidden", "none"
		"dotted" is silently changed to "dashed"
		"hidden" and "none" are equivalent.
	latex; hhline = TRUE	accepts "solid", "double", "hidden", "none"
		"hidden" and "none" are equivalent.
border_thickness
	action	Sets the thickness of the specified border
	default	1
	accepts	numeric(1)
	console	Not recognized
	markdown	Not recognized
	html	Recognized
	latex	Recognized
border_units
	action	Sets the unit of measure for the specified border
		thickness
	default	"pt"
	accepts	"pt", "px"
	console	Not recognized
	markdown	Not recognized
	html	Recognized
	latex	Silently changes "px" to "pt"
caption
	action	Adds or alters the `caption` property
	default
	accepts	character(1)
	console	Recognized
	markdown	Recognized
	html	Recognized
	latex	Recognized
discrete
	action	Adds distinct background colors based on
		discrete values in the selected region.
		May not be used concurrently with `bg`.
		`"font"` is an alias for `"font_color"`
		and `"border"` is an alias for
		all borders.
	default	"bg"
	accepts	"bg", "font", "font_color", "border",
		"left_border", "top_border", "right_border",
		"bottom_border"
	console	Not recognized
	markdown	Not recognized
	html	Recognized
	latex	Recognized
discrete_color
	action	Sets the color palette from which `discrete`
		selects background colors. If `NULL`
		colors are automatically selected using
		the `scales` package.
	default	`getOption("pixie_discrete_pal", NULL)`
	accepts	character
	console	Not recognized
	markdown	Not recognized
	html	Recognized
	latex	Recognized
float
	action	Sets the `float` property
	default	TRUE
	accepts	logical(1)
	console	Not recognized
	markdown	Not recognized
	html	Not recognized
	latex	Recognized
fn
	action	Applies a function to the value of a cell.
		The function should be an
		expression that acts on the variable `value`.
		For example, `quote(format(value, nsmall = 3))`
	default
	accepts	call
	console	Recognized
	markdown	Recognized
	html	Recognized
	latex	Recognized
font_color
	action	Sets the color of the cell text
	default	Black
	accepts	dvips color names; rgb(R,G,B); rgba(R,G,B,A);
		#RRGGBB; #RRGGBBAA. See the "Colors" section
		for further details.
	console	Not recognized
	markdown	Not recognized
	html	Recognized; transparency recognized
	latex	Recognized; transparency ignored
font_family
	action	Sets the font for the text
	default	Times New Roman
	accepts	character(1)
		http://www.w3schools.com/cssref/css_websafe_fonts.asp
	console	Not recognized
	markdown	Not recognized
	html	Recognized
	latex	Not recognized
font_size
	action	Sets the size of the font in the cell
	default
	accepts	numeric(1)
	console	Not recognized
	markdown	Not recognized
	html	Recognized
	latex	Recognized
font_size_units
	action	Determines the units in which `font_size`
		is measured
	default	"px"
	accepts	"px", "pt", "%", "em"
	console	Not recognized
	markdown	Not recognized
	html	Recognized
	latex	Only recognizes "pt" and "em".
		All others are coerced to "pt"
gradient
	action	Adds distinct background colors based on
		progressively increasing values in the
		selected region. May not be used concurrently
		with `bg`.
		`"font"` is an alias for `"font_color"`
		and `"border"` is an alias for
		all borders.
	default	"bg"
	accepts	"bg", "font", "font_color", "border",
		"left_border", "top_border", "right_border",
		"bottom_border"
	console	Not recognized
	markdown	Not recognized
	html	Recognized
	latex	Recognized
gradient_colors
	action	Provides the colors between which to
		shade gradients.
	default	`getOptions("pixie_gradient_pal", NULL)`
	accepts	character
	console	Not recognized
	markdown	Not recognized
	html	Recognized
	latex	Recognized
gradient_cut
	action	Determines the breaks points for the
		gradient shading. When `NULL`
		equally spaced quantiles are used, the
		number of which are determined by
		`gradient_n`.
	default	NULL
	accepts	numeric
	console	Not recognized
	markdown	Not recognized
	html	Recognized
	latex	Recognized
gradient_n
	action	Determines the number of shades to use
		between the colors in `gradient_colors`.
	default	10
	accepts	numeric
	console	Not recognized
	markdown	Not recognized
	html	Recognized
	latex	Recognized
gradient_na
	action	Sets the color of NA values when gradients
		are shaded.
	default	grey
	accepts	character(1)
	console	Not recognized
	markdown	Not recognized
	html	Recognized
	latex	Recognized
halign
	action	Sets the horizontal alignment of the text in
		the cell
	default
	accepts	"left", "center", "right"
	console	Not recognized
	markdown	Recognized; numeric values will auto align to the
		right if no value given.
	html	Recognized. Does not currently employ auto
		alignment of numeric values, but this may change.
	latex	Recognized; numeric values will auto align to
		the right if no value given.
height
	action	Sets the height of the cell
	default
	accepts	numeric(1)
	console	Not recognized
	markdown	Not recognized
	html	Recognized
	latex	Recognized
height_units
	action	Determines the units in which `height` is measured
	default	"pt"
	accepts	"px", "pt", "cm", "in", "%"
	console	Not recognized
	markdown	Not recognized
	html	Recognized
	latex	Recognized; "px" is coerced to "pt"
hhline
	action	Toggles the option for cell border drawing with
		the `hhline` LaTeX package
	default	FALSE
	accepts	logical(1)
	console	Not recognized
	markdown	Not recognized
	html	Not recognized
	latex	Recognized. When `FALSE` double borders are
		not available.
		When `TRUE`, colored and dashed borders are not
		available. This is usually the better option
		when using colored backgrounds in table cells.
italic
	action	Renders the text in the cell in italic
	default	FALSE
	accepts	logical(1)
	console	Recognized; rendered as an underscore on either
		side of the text.
	markdown	Recognized
	html	Recognized
	latex	Recognized
justify
	action	Justifies the entire table on the page.
	default	"center"
	accepts	character(1)
	console	Not recognized
	markdown	Not recognized
	html	Recognized
	latex	Recognizes "center", but both "left" and "right"
		are rendered as left justified. This may change
		if a satisfactory solution is found.
		Usually, tables are best left centered.
longtable
	action	Toggles the use of the LaTeX `longtable` style
		tables, namely allowing long tables to be broken
		into multiple sections. The table header appears
		at the top of each section. The table interfoot
		appears at the bottom of each section, except
		for the last.
		The table foot appears at the bottom of the
		last section.
		May accept either a logical or a numerical value.
		If numerical, each section will have the specified
		number of rows.
	default	FALSE
	accepts	logical(1); numeric(1)
	console	Recognized; when `TRUE`, defaults to 25 rows
		per section.
	markdown	Recognized; when `TRUE`, defaults to 25 rows
		per section.
	html	Recognized; when `TRUE`, defaults to 25 rows
		per section.
	latex	Recognized; when `TRUE`, `longtable`'s own algorithm
		will determine the number of rows per section.
		When numeric, breaks are forced at the specified
		number of rows.
merge
	action	Merges cells in the specified range into a
		single cell. In cases where
		either `merge_rowval` or `merge_colval` is
		specified, they will only be
		honored if `merge = TRUE`. You must opt in to
		this action.
	default	FALSE
	accepts	logical(1)
	console	Recognized
	markdown	Recognized
	html	Recognized
	latex	Recognized
merge_rowval
	action	Specifies the row value of the merged range to
		print in the table
	default	minimum row value of the merged range
	accepts	numeric(1)
	console	Recognized
	markdown	Recognized
	html	Recognized
	latex	Recognized
merge_colval
	action	Specifies the column value of the merged range
		to print in the table
	default	minimum col value of the merged range
	accepts	numeric(1)
	console	Recognized
	markdown	Recognized
	html	Recognized
	latex	Recognized
na_string
	action	Designates the character string to use in place
		of missing values
	default	NA
	accepts	character(1)
	console	Recognized
	markdown	Recognized
	html	Recognized
	latex	Recognized
pad
	action	Designates the padding to place between cell
		text and boundaries
		Measured in pixels.
	default	0
	accepts	numeric(1)
	console	Not recognized
	markdown	Not recognized
	html	Recognized
	latex	Not recognized
replace
	action	Replaces existing cell values with user-specified
		content. Replacement occurs moving down columns
		from left to right.
	default
	accepts	character vector of the same length as the number
		of cells being replaced.
	console	Recognized
	markdown	Recognized
	html	Recognized
	latex	Recognized
rotate_degree
	action	Rotates text in cells by the designated angle
		in degrees
	default
	accepts	numeric(1)
	console	Not recognized
	markdown	Not recognized
	html	Recognized
	latex	Recognized
round
	action	Applies the `round` function to values in the
		cell. Skips any character values it encounters.
	default	`getOption("digits")`
	accepts	numeric(1)
	console	Recognized
	markdown	Recognized
	html	Recognized
	latex	Recognized
sanitize
	action	Sanitizes character values that may cause
		difficulties for the rendered format.
	default	FALSE
	accepts	logical(1)
	console	Not recognized
	markdown	Not recognized
	html	Not recognized
	latex	Recognized. Sanitization is performed using
		`latexTranslate`
sanitize_args
	action	Passes additional arguments to `latexTranslate`
	default	`list()`
	accepts	list. See documentation for `latexTranslate`
		for details
	console	Not recognized
	markdown	Not recognized
	html	Not recognized
	latex	Recognized
tabcolsep
	action	Modifies the LaTeX `tabcolsep` parameter of tables
		This is similar to `pad` for HTML tables, but only
		affects the space between columns. Measured in "pt"
	default	6
	accepts	numeric(1)
	console	Not recognized
	markdown	Not recognized
	html	Not recognized
	latex	Recognized
valign
	action	Designates the vertical alignment of a cell.
	default
	accepts	"top", "middle", "bottom"
	console	Not recognized
	markdown	Not recognized
	html	Recognized
	latex	Recognized
width
	action	Sets the width of the cell
	default
	accepts	numeric(1)
	console	Not recognized
	markdown	Not recognized
	html	Recognized
	latex	Recognized
width_units
	action	Determines the units in which `width` is measured
	default	"pt"
	accepts	"px", "pt", "cm", "in", "%"
	console	Not recognized
	markdown	Not recognized
	html	Recognized
	latex	Recognized; "px" is coerced to "pt"

Longtable

The longtable feature is named for the LaTeX package used to break very large tables into multiple pages.

When using the longtable=TRUE option, the default number of rows per table is 25 for console, HTML, and markdown output. For LaTeX output, the number of rows is determined by the LaTeX longtable package's algorithm. The number of rows per table only considers the content in the body of the table. Consideration for the number of rows in the head and foot are the responsibility of the user.

Whenever a table is broken into multiple parts, each part retains the table head. If any interfoot is provided, it is appended to the bottom of each section, with the exception of the last section. The last section has the foot appended.

Colors

Colors may be declared as any of the color names in colors(), as rgb character strings such as "rgb(rrr,ggg,bbb)" or as hexadecimal character strings such as "#rrggbb".

Transparency is also recognized by HTML output, and may be indicated in the rgba format "rgba(rrr,ggg,bbb,aa)", where aa is a number between 0 and 1, inclusive. Alternative, transparency may be given as "#rrggbbAA", where AA is a hexadecimal representation of transparency with "00" being completely transparent and "FF" being completely opaque.

LaTeX output does not recognize transparency and will quietly drop the transparency parameter.

All colors are internally translated into rgb format and are case insensitive.

Required LaTeX Packages

If you will be using the LaTeX output, some sprinkles will require you to include additional LaTeX packages in your document preamble. In .Rnw files, additional packages can be included with the \usepackage{[package]} syntax. In markdown, additional packages are included using header-includes: in the YAML front matter with a line of the format \usepackage{[package]} for each package to be used. Sprinkles that require additional packages, and the LaTeX packages required, are listed below:

Sprinkle	LaTeX Package(s)
`font_color`	`\usepackage[dvipsnames]{xcolor}`
`bg, bg_pattern`	`\usepackage[dvipsnames,table]{xcolor}`
`border_style`	`\usepackage{arydshln}`
	`\usepackage{amssymb}`
	`\usepackage{hhline}`
(with vertical dashed lines)	\usepackage{graphicx}
	`\makeatletter`
	`\newcommand*\vdashline{\rotatebox[origin=c]{90}{\$\dabar@\dabar@\dabar@\$}}`
	`\makeatother`
`longtable`	`\usepackage{longtable}`
	(Must be loaded before `arydshln`)
`merge`	`\usepackage{multirow}`
`captions` for non floats	`\usepackage{caption}`

Note that hhline is used to make horizontal lines when options(pixiedust_latex_hhline = TRUE) (the package default is FALSE), otherwise the cline command is used.

Use of cline permits colored borders and dashed borders, but borders around cells with background colors are sometimes (often) lost.

Use of hhline preserves borders around cells with background colors and permits double borders, but colored and dashed borders are not available.

In order to ensure all features are available, the recommended code block (accounting for the proper order to load packages) is:

header-includes:
- \usepackage{amssymb}
- \usepackage{arydshln}
- \usepackage{caption}
- \usepackage{graphicx}
- \usepackage{hhline}
- \usepackage{longtable}
- \usepackage{multirow}
- \usepackage[dvipsnames,table]{xcolor}
- \makeatletter
- \newcommand*\vdashline{\rotatebox[origin=c]{90}{\$\dabar@\dabar@\dabar@\$}}
- \makeatother

Author

Benjamin Nutter

Details

Sprinkling is done over the intersection of rows and columns (unless fixed = TRUE. If rows but no columns are specified, sprinkling is performed over all columns of the given given rows. The reverse is true for when columns but no rows are specified. If neither columns nor rows are specified, the attribute is applied over all of the cells in the table part denoted in part.

If at least one of border, border_thickness, border_units, border_style or border_color is specified, the remaining unspecified attributes assume their default values.

Other sprinkle pairings are height and height_units; width and width_units; font_size and font_size_units; bg_pattern and bg_pattern_by

The sprinkles bg and bg_pattern may not be used together.

A more detailed demonstration of the use of sprinkles is available in vignette("pixiedust", package = "pixiedust")

Using sprinkle_table, sprinkles may be applied to the columns of multiple tables. Table parts are required to have the same number of columns, but not necessarily the same number of rows, which is why the rows argument is not available for the sprinkle_table. In contrast to sprinkle, the part argument in sprinkle_table will accept multiple parts. If any of the named parts is "table", the sprinkle will be applied to the columns of all of the parts.

Examples

Run this code

x <- dust(lm(mpg ~ qsec + factor(am), data = mtcars))
x %>% sprinkle(cols = 2:4, round = 3) %>% 
  sprinkle(cols = 5, fn = quote(pvalString(value))) %>% 
  sprinkle(rows = 2, bold = TRUE)

Run the code above in your browser using DataLab