sprinkle: Define Customizations to a Table

View source: R/sprinkle.R

sprinkleR Documentation

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

## Default S3 method:
sprinkle(
  x,
  rows = NULL,
  cols = NULL,
  ...,
  part = c("body", "head", "foot", "interfoot", "table"),
  fixed = FALSE,
  recycle = c("none", "rows", "cols", "columns")
)

## S3 method for class '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")
)

## Default S3 method:
sprinkle_print_method(
  x,
  print_method = c("console", "markdown", "html", "latex", "docx")
)

## S3 method for class 'dust_list'
sprinkle_print_method(
  x,
  print_method = c("console", "markdown", "html", "latex")
)

sprinkle_table(x, cols = NULL, ..., part = "table")

## Default S3 method:
sprinkle_table(x, cols = NULL, ..., part = "table")

## S3 method for class '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".

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.

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(s)

Benjamin Nutter

Source

Altering the number of rows in a LaTeX longtable
http://tex.stackexchange.com/questions/19710/how-can-i-set-the-maximum-number-of-rows-in-a-page-for-longtable

Vertical dashed cell borders in LaTeX table
http://www.latex-community.org/forum/viewtopic.php?f=45&t=3149

Colored Cell border
http://tex.stackexchange.com/questions/40666/how-to-change-line-color-in-tabular

See Also

sprinkle_colnames for changing column names in a table.

Examples

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)


pixiedust documentation built on Oct. 10, 2023, 9:07 a.m.