summary_rows: Add groupwise summary rows using aggregation functions

Description

Add summary rows to one or more row groups by using the table data and any suitable aggregation functions. You choose how to format the values in the resulting summary cells by use of a formatter function (e.g, fmt_number, etc.) and any relevant options.

Usage

summary_rows(
  data,
  groups = NULL,
  columns = everything(),
  fns,
  missing_text = "---",
  formatter = fmt_number,
  ...
)

Value

An object of class gt_tbl.

Arguments

data: A table object that is created using the gt() function.
groups: The groups to consider for generation of groupwise summary rows. By default this is set to NULL, which results in the formation of grand summary rows (a grand summary operates on all table data). Providing the names of row groups in c() will create a groupwise summary and generate summary rows for the specified groups. Setting this to TRUE indicates that all available groups will receive groupwise summary rows.
columns: The columns for which the summaries should be calculated.
fns: Functions used for aggregations. This can include base functions like mean, min, max, median, sd, or sum or any other user-defined aggregation function. The function(s) should be supplied within a list(). Within that list, we can specify the functions by use of function names in quotes (e.g., "sum"), as bare functions (e.g., sum), or as one-sided R formulas using a leading ~. In the formula representation, a . serves as the data to be summarized (e.g., sum(., na.rm = TRUE)). The use of named arguments is recommended as the names will serve as summary row labels for the corresponding summary rows data (the labels can derived from the function names but only when not providing bare function names).
missing_text: The text to be used in place of NA values in summary cells with no data outputs.
formatter: A formatter function name. These can be any of the fmt_*() functions available in the package (e.g., fmt_number(), fmt_percent(), etc.), or a custom function using fmt(). The default function is fmt_number() and its options can be accessed through ....
...: Values passed to the formatter function, where the provided values are to be in the form of named vectors. For example, when using the default formatter function, fmt_number(), options such as decimals, use_seps, and locale can be used.

Examples

Use sp500 to create a gt table with row groups. Create the summary rows labeled min, max, and avg by row group (where each each row group is a week number) with the summary_rows() function.

sp500 %>%
  dplyr::filter(date >= "2015-01-05" & date <="2015-01-16") %>%
  dplyr::arrange(date) %>%
  dplyr::mutate(week = paste0( "W", strftime(date, format = "%V"))) %>%
  dplyr::select(-adj_close, -volume) %>%
  gt(
    rowname_col = "date",
    groupname_col = "week"
  ) %>%
  summary_rows(
    groups = TRUE,
    columns = c(open, high, low, close),
    fns = list(
      min = ~min(.),
      max = ~max(.),
      avg = ~mean(.)),
    formatter = fmt_number,
    use_seps = FALSE
  )

This image of a table was generated from the first code example in the `summary_rows()` help file.

Function ID

5-1

Details

Should we need to obtain the summary data for external purposes, the extract_summary() function can be used with a gt_tbl object where summary rows were added via summary_rows().