Add summary columns using aggregation functions

The summary_columns() function adds one or more computed columns to a table by aggregating values across selected columns within each row. This is the horizontal counterpart to summary_rows(), which aggregates down columns to create summary rows. Common use cases include calculating row totals, row averages, or other row-wise statistics.

Summary columns are computed immediately when the function is called and are added to the table's data as regular columns. This means they can be referenced in subsequent gt operations like cols_move(), fmt_number(), tab_style(), or even in other computed columns via cols_add().

You can create a single summary column or multiple columns at once by providing a list of aggregation functions. The functions can be any R expression that takes a vector of values and returns a single value (like sum(), mean(), max(), min(), etc.). Column names and labels can be auto-generated from function names or explicitly specified.

Usage

summary_columns(
  data,
  columns = everything(),
  fns = NULL,
  new_col_names = NULL,
  new_col_labels = NULL,
  fmt = NULL,
  side = c("right", "left"),
  missing_text = "---"
)

Arguments

data

The gt table data object

obj:<gt_tbl> // required

This is the gt table object that is commonly created through use of the gt() function.

columns

Columns to aggregate

<column-targeting expression> // default: everything()

The columns to aggregate across for each row. Can either be a series of column names provided in c(), a vector of column indices, or a select helper function (e.g. starts_with(), ends_with(), contains(), matches(), num_range(), and everything()).

fns

Aggregation Expression(s)

<expression|list of expressions>

One or more functions used for aggregation. For a single summary column, provide a single function as a formula (e.g., ~ sum(.)), character string (e.g., "sum"), or bare function (e.g., sum). For multiple summary columns, provide a list of formulas (e.g., list(~ sum(.), ~ mean(.), ~ sd(.))). Base functions like mean, min, max, median, sd, and sum are supported, along with any user-defined aggregation functions.

new_col_names

Names for new summary columns

vector<character> // default: NULL

Optional names for the new summary columns. Can provide one name for a single summary column, or multiple names (must match the length of fns) when adding multiple columns. These names are used as column identifiers for targeting in other gt functions (e.g., fmt_number(), tab_style()). If NULL, names will be generated from the function expressions (e.g., "sum", "mean") or default to "summary_1", "summary_2", etc.

new_col_labels

Labels for new summary columns

list|vector<character> // default: NULL

Optional labels for the new summary column headers. Can provide one label for a single column, or multiple labels (must match the length of fns) when adding multiple columns. Can include plain text or use md() or html() helpers. If NULL, will use new_col_names as labels. Important: Use list() instead of c() when mixing plain text with md() or html() objects to preserve their classes (e.g., list("Total", md("**Average**"))).

fmt

Formatting expression

<expression>

An optional formatting expression in formula form. The RHS of ~ should contain a formatting call (e.g., ~ fmt_number(., decimals = 2)).

side

Side used for placement of summary column

singl-kw:[right|left] // default: "right"

Should the summary column be placed on the "right" (the default) or the "left" side of the table?

missing_text

Replacement text for NA values

scalar<character> // default: "---"

The text to be used in place of NA values in the summary column cells.

Value

An object of class gt_tbl.

Examples

Use a subset of the countrypops dataset to create a gt table. Add a summary column that computes the average annual change using summary_columns().

countrypops |>
  arrange(country_name, year) |>
  group_by(country_name, country_code_2) |>
  summarize(
    pop_1960 = first(population),
    pop_2024 = last(population),
    years = n(),
    .groups = "drop"
  ) |>
  filter(!is.na(pop_1960), !is.na(pop_2024)) |>
  mutate(total_change = pop_2024 - pop_1960) |>
  slice_max(total_change, n = 5) |>
  select(country_name, country_code_2, pop_1960, pop_2024, years) |>
  gt() |>
  summary_columns(
    columns = c(pop_1960, pop_2024, years),
    fns = ~ (.[2] - .[1]) / (.[3] - 1),
    new_col_names = "avg_annual_change",
    new_col_labels = md("**Avg. Annual Change**")  # No list() needed!
  ) |>
  cols_hide(columns = c(pop_1960, pop_2024, years)) |>
  fmt_integer() |>
  cols_label(
    country_name = "Country",
    country_code_2 = "Code"
  ) |>
  tab_header(
    title = "Top 5 Countries by Population Growth",
    subtitle = "Average annual population change (1960-2024)"
  )

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

Function ID

6-4

Function Introduced

In Development