cols_merge_n_pct: Merge two columns to combine counts and percentages

View source: R/modify_columns.R

cols_merge_n_pctR Documentation

Merge two columns to combine counts and percentages

Description

The cols_merge_n_pct() function is a specialized variant of the cols_merge() function. It operates by taking two columns that constitute both a count (col_n) and a fraction of the total population (col_pct) and merges them into a single column. What results is a column containing both counts and their associated percentages (e.g., 12 (23.2%)). The column specified in col_pct is dropped from the output table.

Usage

cols_merge_n_pct(data, col_n, col_pct, autohide = TRUE)

Arguments

data

A table object that is created using the gt() function.

col_n

A column that contains values for the count component.

col_pct

A column that contains values for the percentage component. This column should be formatted such that percentages are displayed (e.g., with fmt_percent()).

autohide

An option to automatically hide the column specified as col_pct. Any columns with their state changed to hidden will behave the same as before, they just won't be displayed in the finalized table.

Details

This function could be somewhat replicated using cols_merge(), however, cols_merge_n_pct() employs the following specialized semantics for NA and zero-value handling:

  1. NAs in col_n result in missing values for the merged column (e.g., NA + 10.2% = NA)

  2. NAs in col_pct (but not col_n) result in base values only for the merged column (e.g., 13 + NA = 13)

  3. NAs both col_n and col_pct result in missing values for the merged column (e.g., NA + NA = NA)

  4. If a zero (0) value is in col_n then the formatted output will be "0" (i.e., no percentage will be shown)

Any resulting NA values in the col_n column following the merge operation can be easily formatted using the fmt_missing() function. Separate calls of fmt_missing() can be used for the col_n and col_pct columns for finer control of the replacement values. It is the responsibility of the user to ensure that values are correct in both the col_n and col_pct columns (this function neither generates nor recalculates values in either). Formatting of each column can be done independently in separate fmt_number() and fmt_percent() calls.

This function is part of a set of four column-merging functions. The other two are the general cols_merge() function and the specialized cols_merge_uncert() and cols_merge_range() functions. These functions operate similarly, where the non-target columns can be optionally hidden from the output table through the hide_columns or autohide options.

Value

An object of class gt_tbl.

Figures

Function ID

4-11

See Also

Other Modify Columns: cols_align(), cols_hide(), cols_label(), cols_merge_range(), cols_merge_uncert(), cols_merge(), cols_move_to_end(), cols_move_to_start(), cols_move(), cols_unhide(), cols_width()

Examples

# Use `pizzaplace` to create a gt table
# that displays the counts and percentages
# of the top 3 pizzas sold by pizza
# category in 2015; the `cols_merge_n_pct()`
# function is used to merge the `n` and
# `frac` columns (and the `frac` column is
# formatted using `fmt_percent()`)
tab_1 <-
  pizzaplace %>%
  dplyr::group_by(name, type, price) %>%
  dplyr::summarize(
    n = dplyr::n(),
    frac = n/nrow(.),
    .groups = "drop"
  ) %>%
  dplyr::arrange(type, dplyr::desc(n)) %>%
  dplyr::group_by(type) %>%
  dplyr::slice_head(n = 3) %>%
  gt(
    rowname_col = "name",
    groupname_col = "type"
  ) %>%
  fmt_currency(price) %>%
  fmt_percent(frac) %>%
  cols_merge_n_pct(
    col_n = n,
    col_pct = frac
  ) %>%
  cols_label(
    n = md("*N* (%)"),
    price = "Price"
  ) %>%
  tab_style(
    style = cell_text(font = "monospace"),
    locations = cells_stub()
  ) %>%
  tab_stubhead(md("Cat. and  \nPizza Code")) %>%
  tab_header(title = "Top 3 Pizzas Sold by Category in 2015") %>%
  tab_options(table.width = px(512))


gt documentation built on April 22, 2022, 1:05 a.m.