## GT.cols_merge_n_pct()
Merge two columns to combine counts and percentages.
Usage
``` python
GT.cols_merge_n_pct(
col_n,
col_pct,
rows=None,
autohide=True,
)
```
[cols_merge_n_pct()](GT.cols_merge_n_pct.md#great_tables.GT.cols_merge_n_pct) is a specialized variant of [cols_merge()](GT.cols_merge.md#great_tables.GT.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()](GT.fmt_percent.md#great_tables.GT.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()](GT.fmt_number.md#great_tables.GT.fmt_number) and [fmt_percent()](GT.fmt_percent.md#great_tables.GT.fmt_percent) calls.
## Examples
Create a simple table with counts and percentages, then merge them.
``` python
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.
``` python
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 | |