GT.cols_merge_uncert()

Merge columns to a value-with-uncertainty column.

Usage

GT.cols_merge_uncert(
    col_val, col_uncert, rows=None, sep=" +/- ", autohide=True
)

cols_merge_uncert() is a specialized variant of cols_merge(). It takes as input a base value column (col_val) and either: (1) a single uncertainty column, or (2) two columns representing lower and upper uncertainty bounds. These columns will be essentially merged into a single column (that of col_val). What results is a column with values and associated uncertainties, and any columns specified in col_uncert are hidden from appearing in the output table.

Parameters

col_val: SelectExpr: The column that contains values for the base measurement. 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_uncert: SelectExpr: The column or columns that contain uncertainty values. The most common case involves supplying a single column with uncertainties; these values will be combined with those in col_val. Less commonly, the lower and upper uncertainty bounds may be different. For that case, two columns representing the lower and upper uncertainty values away from col_val, respectively, should be provided as a list.
rows: int | list[int] | None = None: In conjunction with col_val, 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.
sep: str = " +/- ": The separator text that contains the uncertainty mark for a single uncertainty value. The default value of " +/- " indicates that an appropriate plus/minus mark will be used depending on the output context. The plus/minus symbol (±) is used in HTML output.
autohide: bool = True: An option to automatically hide any columns specified in col_uncert. 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 handling

This function employs specialized semantics for missing value handling that differ from the generic cols_merge():

Missing values in col_val result in missing values for the merged column (e.g., NA + 0.1 = NA)
Missing values in col_uncert (but not col_val) result in base values only for the merged column (e.g., 12.0 + NA = 12.0)
Missing values in both col_val and col_uncert result in missing values for the merged column (e.g., NA + NA = NA)

Examples

Use the exibble dataset to create a simple, two-column table. Merge the currency and num columns together as a value with uncertainty.

from great_tables import GT
from great_tables.data import exibble
import polars as pl

exibble_mini = (
    pl.from_pandas(exibble)
    .select("num", "currency")
    .slice(0, 7)
)

(
    GT(exibble_mini)
    .fmt_number(columns="num", decimals=3, use_seps=False)
    .cols_merge_uncert(col_val="currency", col_uncert="num")
    .cols_label(currency="value + uncert.")
)

value + uncert.
49.95 ± 0.111
17.95 ± 2.222
1.39 ± 33.330
65100.0 ± 444.400
1325.81 ± 5550.000
13.255

When there are missing values in the uncertainty column, the merged result shows only the base value. When the base value itself is missing, the entire merged cell is empty.

df = pl.DataFrame({
    "measurement": [12.5, 8.3, 15.0, 9.7],
    "error": [0.2, None, 0.5, None],
})

(
    GT(df)
    .fmt_number(columns="error", decimals=2)
    .cols_merge_uncert(col_val="measurement", col_uncert="error")
    .cols_label(measurement="Measurement")
)

Measurement
12.5 ± 0.20
8.3
15.0 ± 0.50
9.7