dust: Dust Table Construction

In pixiedust: Tables so Beautifully Fine-Tuned You Will Believe It's Magic

Dust Table Construction

Description

Dust tables consist of four primary components that are built together to create a full table. Namely, the head, the body, the interfoot, and the foot. Dust tables also contain a table-wide attributes border_collapse and longtable as well as a print_method element.

Usage

dust(object, ...)

## Default S3 method:
dust(
  object,
  ...,
  tidy_df = FALSE,
  keep_rownames = FALSE,
  glance_foot = FALSE,
  glance_stats = NULL,
  col_pairs = 2,
  byrow = FALSE,
  descriptors = "term",
  numeric_level = c("term", "term_plain", "label"),
  label = NULL,
  caption = NULL,
  caption_number = getOption("pixied_caption_number", TRUE),
  justify = getOption("pixie_justify", "center"),
  float = getOption("pixie_float", TRUE),
  longtable = getOption("pixie_longtable", FALSE),
  hhline = getOption("pixie_hhline", FALSE),
  bookdown = getOption("pixie_bookdown", FALSE),
  border_collapse = getOption("pixie_border_collapse", "collapse"),
  tabcolsep = getOption("pixie_tabcolsep", 6),
  fixed_header = getOption("pixie_fixed_header", FALSE),
  html_preserve = getOption("pixie_html_preserve", TRUE)
)

## S3 method for class 'grouped_df'
dust(object, ungroup = TRUE, ...)

## S3 method for class 'list'
dust(object, ...)

redust(x, table, part = c("head", "foot", "interfoot", "body"))

## Default S3 method:
redust(x, table, part = c("head", "foot", "interfoot", "body"))

## S3 method for class 'dust_list'
redust(x, table, part = c("head", "foot", "interfoot", "body"))

Arguments

object	An object that has a tidy method in broom
...	Additional arguments to pass to tidy
tidy_df	When object is an object that inherits the data.frame class, the default behavior is to assume that the object itself is the basis of the table. If the summarized table is desired, set to TRUE.
keep_rownames	When tidy_df is FALSE, setting keep_rownames binds the row names to the data frame as the first column, allowing them to be preserved in the tabulated output. This is only to data frame like objects, as the broom::tidy.matrix method performs this already.
glance_foot	Arrange the glance statistics for the foot of the table. (Not scheduled for implementation until version 0.4.0)
glance_stats	A character vector giving the names of the glance statistics to put in the output. When NULL, the default, all of the available statistics are retrieved. In addition to controlling which statistics are printed, this also controls the order in which they are printed.
col_pairs	An integer indicating the number of column-pairings for the glance output. This must be less than half the total number of columns, as each column-pairing includes a statistic name and value. See the full documentation for the unexported function glance_foot.
byrow	A logical, defaulting to FALSE, that indicates if the requested statistics are placed with priority to rows or columns. See the full documentation for the unexported function glance_foot.
descriptors	A character vector indicating the descriptors to be used in the table. Acceptable inputs are "term", "term_plain", "label", "level", and "level_detail". These may be used in any combination and any order, with the descriptors appearing in the table from left to right in the order given. The default, "term", returns only the term descriptor and is identical to the output provided by broom::tidy methods. See Details for a full explanation of each option and the Examples for sample output. See the full documentation for the unexported function tidy_levels_labels.
numeric_level	A character string that determines which descriptor is used for numeric variables in the "level_detail" descriptor when a numeric has an interaction with a factor. Acceptable inputs are "term", "term_plain", and "label". See the full documentation for the unexported function tidy_levels_labels.
label	character(1). An optional string for assigning labels with which tables can be referenced elsewhere in the document. If NULL, pixiedust attempts to name the label tab:[chunk-name], where [chunk-name] is the name of the knitr chunk. If this also resolves to NULL (for instance, when you aren't using knitr, the label tab:pixie-[n] is assigned, where [n] is the current value of options()$pixie_count. Note that rendering multiple tables in a chunk without specifying a label will result in label conflicts.
caption	A character string giving the caption for the table.
caption_number	logical(1). Should the table caption be prefixed with the table number?
justify	character(1). Specifies the justification of the table on the page. May be "center" (default), "left", or "right".
float	A logical used only in LaTeX output. When TRUE, the table is set within a table environment. The default is TRUE, as with xtable.
longtable	Allows the user to print a table in multiple sections. This is useful when a table has more rows than will fit on a printed page. Acceptable inputs are FALSE, indicating that only one table is printed (default); TRUE that the table should be split into multiple tables with the default number of rows per table (see "Longtable"); or a positive integer indicating how many rows per table to include. All other values are interpreted as FALSE. In LaTeX output, remember that after each section, a page break is forced. This setting may also be set from sprinkle.
hhline	Logical. When FALSE, the default, horizontal LaTeX cell borders are drawn using the \cline command. These don't necessarily play well with cell backgrounds, however. Using hhline = TRUE prints horizontal borders using the \hhline command. While the hhline output isn't disrupted by cell backgrounds, it may require more careful coding of the desired borders. In hhline, cells with adjoining borders tend to double up and look thicker than when using cline.
bookdown	Logical. When TRUE, bookdown style labels are generated. Defaults to FALSE.
border_collapse	character(1). One of "collapse", "separate", "initial", or "inherit".
tabcolsep	integerish(1). For LaTeX output, the distance in pt between columns of the table.
fixed_header	logical(1). For HTML tables, should the header rows be fixed in place over a scrollable body.
html_preserve	logical(1). When TRUE, HTML output is returned wrapped in htmltools::htmlPreserve. If using LaTeX style equations in an HTML table, it may be necessary to set this to FALSE. Do this at your own risk; this has not been thoroughly field tested.
ungroup	Used when a grouped_df object is passed to dust. When TRUE (the default), the object is ungrouped and dusted as a single table. When FALSE, the object is split and each element is dusted separately.
x	A dust object
table	A data frame of similar dimensions of the part being replaced.
part	The part of the table to replace with table

Details

The head object describes what each column of the table represents. By default, the head is a single row, but multi row headers may be provided. Note that multirow headers may not render in markdown or console output as intended, though rendering in HTML and LaTeX is fairly reliable. In longtables (tables broken over multiple pages), the head appears at the top of each table portion.

The body object gives the main body of information. In long tables, this section is broken into portions, ideally with one portion per page.

The interfoot object is an optional table to be placed at the bottom of longtable portions with the exception of the last portion. A well designed interfoot can convey to the user that the table continues on the next page.

The foot object is the table that appears at the end of the completed table. For model objects, it is recommended that the glance statistics be used to display model fit statistics.

The border_collapse object applies to an entire HTML table. It indicates if the borders should form a single line or distinct lines.

The longtable object determines how many rows per page are printed. By default, all content is printed as a single table. Using the longtable argument in the sprinkle function can change this setting.

The table_width element is specific to LaTeX tables. This is a reference value for when column widths are specified in terms of the % units. For example, a column width of 20% will be defined as table_width * .20. The value in table_width is assumed to be in inches and defaults to 6.

The tabcolsep object determines the spacing between columns in a LaTeX table in pt. By default, it is set at 6.

The print_method object determines how the table is rendered when the print method is invoked. The default is to print to the console.

Many of these options may be set globally. See pixiedust for a complete list of package options.

Value

Returns an object of class dust

Symbols and Greek Letters

When using markdown, math symbols and greek letters may be employed as they would within a markdown document. For example, "$\alpha$" will render as the lower case Greek alpha. Math symbols may be rendered in the same manner.

Author(s)

Benjamin Nutter

See Also

tidy glance_foot tidy_levels_labels pixiedust

get_dust_part for extracting parts of the dust object in order to build custom headers and/or footers.

Examples

x <- dust(lm(mpg ~ qsec + factor(am), data = mtcars))
x

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