GT.cols_merge_range()

Merge two columns to a value range column.

Usage

GT.cols_merge_range(
    col_begin, col_end, rows=None, sep=None, autohide=True, locale=None
)

cols_merge_range() is a specialized variant of cols_merge(). It operates by taking two columns that constitute a range of values (col_begin and col_end) and merges them into a single column. What results is a column containing both values separated by an en dash (or a custom separator). The column specified in col_end is dropped from the output table.

Parameters

col_begin: SelectExpr: The column that contains values for the start of the range. 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_end: SelectExpr: The column that contains values for the end of the range. 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.
rows: int | list[int] | None = None: In conjunction with col_begin, 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 | None = None: The separator text that indicates the values are ranged. If not provided, an en dash ("–") will be used. You can use "--" for an en dash or "---" for an em dash.
autohide: bool = True: An option to automatically hide the column specified as col_end. 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.
locale: str | None = None: An optional locale identifier that can be used for applying a separator pattern specific to a locale’s rules. Currently reserved for future use.

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_begin (but not col_end) result in a display of only the col_end value
Missing values in col_end (but not col_begin) result in a display of only the col_begin value
Missing values in both col_begin and col_end result in missing values for the merged column

Examples

Use a subset of the gtcars dataset to create a table. Merge the mpg_c and mpg_h columns together as a range.

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

gtcars_mini = (
    pl.from_pandas(gtcars)
    .select("model", "mpg_c", "mpg_h")
    .slice(0, 8)
)

(
    GT(gtcars_mini)
    .cols_merge_range(col_begin="mpg_c", col_end="mpg_h")
    .cols_label(mpg_c="MPG")
)

model	MPG
GT	11.0–18.0
458 Speciale	13.0–17.0
458 Spider	13.0–17.0
458 Italia	13.0–17.0
488 GTB	15.0–22.0
California	16.0–23.0
GTC4Lusso	12.0–17.0
FF	11.0–16.0

When there are missing values, the merged result gracefully degrades: if only one side is missing, the other value is shown alone (without a separator). A custom separator can be provided via the sep= argument.

df = pl.DataFrame({
    "city": ["NYC", "LA", "CHI", "HOU"],
    "temp_low": [28, 55, None, 45],
    "temp_high": [35, None, 50, 60],
})

(
    GT(df)
    .cols_merge_range(col_begin="temp_low", col_end="temp_high", sep=" to ")
    .cols_label(temp_low="Temp. Range (°F)")
)

city	Temp. Range (°F)
NYC	28 to 35
LA	55
CHI	50
HOU	45 to 60