# sprinkle

0th

Percentile

##### Define Customizations to a Table

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

##### 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 or http://nutterb.github.io/pixiedust/colors.html. 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 or http://nutterb.github.io/pixiedust/colors.html. 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 or http://nutterb.github.io/pixiedust/colors.html. 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

(Read more about pixiedust with LaTeX at http://nutterb.github.io/pixiedust/latex-configuration.html)

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}

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

sprinkle_colnames for changing column names in a table.

##### Aliases
• sprinkle
• sprinkle.default
• sprinkle.dust_list
• sprinkle_print_method
• sprinkle_print_method.default
• sprinkle_print_method.dust_list
• sprinkle_table
• sprinkle_table.default
• sprinkle_table.dust_list
##### Examples
# NOT RUN {
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)

# }

Documentation reproduced from package pixiedust, version 0.8.5, License: GPL (>= 2)

### Community examples

Looks like there are no examples yet.