GT.cols_merge_n_pct()

Merge two columns to combine counts and percentages.

Usage

Source

GT.cols_merge_n_pct(
    col_n,
    col_pct,
    rows=None,
    autohide=True,
)

cols_merge_n_pct() is a specialized variant of cols_merge(). 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.

Parameters

col_n: SelectExpr

The column that contains values for the count component. While column selection expressions can be used, it’s recommended that a single column name be used to ensure that exactly one column is provided here.

col_pct: SelectExpr

The column that contains values for the percentage component. While column selection expressions can be used, it’s recommended that a single column name be used to ensure that exactly one column is provided here. This column should be formatted such that percentages are displayed (e.g., with fmt_percent()).

rows: int | list[int] | None = None

In conjunction with col_n, we can specify which rows should participate in the merging process. The default is all rows. Alternatively, we can supply a list of row indices.

autohide: bool = True
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. Defaults to True.

Returns

GT
The GT object is returned. This is the same object that the method is called on so that we can facilitate method chaining.

Details

Specialized NA and zero-value handling

This function employs specialized semantics for missing value and zero-value handling:

  1. Missing values in col_n result in missing values for the merged column (e.g., NA + 10.2% = NA)
  2. Missing values in col_pct (but not col_n) result in base values only for the merged column (e.g., 13 + NA = 13)
  3. Missing values in 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)

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.

Examples

Create a simple table with counts and percentages, then merge them.

from great_tables import GT
import polars as pl

df = pl.DataFrame({
    "category": ["A", "B", "C"],
    "n": [10, 20, 30],
    "pct": [0.167, 0.333, 0.500],
})

(
    GT(df)
    .fmt_percent(columns="pct")
    .cols_merge_n_pct(col_n="n", col_pct="pct")
    .cols_label(n="Count (%)")
)
category Count (%)
A 10 (16.70%)
B 20 (33.30%)
C 30 (50.00%)

Zero values in the count column suppress the percentage display. Missing values in the percentage column result in just the count being shown, and missing counts produce empty cells.

df = pl.DataFrame({
    "item": ["Alpha", "Beta", "Gamma", "Delta"],
    "count": [15, 0, 8, None],
    "frac": [0.375, 0.0, None, 0.125],
})

(
    GT(df)
    .fmt_percent(columns="frac", decimals=1)
    .cols_merge_n_pct(col_n="count", col_pct="frac")
    .cols_label(count="N (%)")
)
item N (%)
Alpha 15 (37.5%)
Beta 0
Gamma 8
Delta