## GT.cols_merge_range()
Merge two columns to a value range column.
Usage
``` python
GT.cols_merge_range(
col_begin, col_end, rows=None, sep=None, autohide=True, locale=None
)
```
[cols_merge_range()](GT.cols_merge_range.md#great_tables.GT.cols_merge_range) is a specialized variant of [cols_merge()](GT.cols_merge.md#great_tables.GT.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()](GT.cols_merge.md#great_tables.GT.cols_merge):
1. Missing values in `col_begin` (but not `col_end`) result in a display of only the `col_end` value
2. Missing values in `col_end` (but not `col_begin`) result in a display of only the `col_begin` value
3. Missing values in both `col_begin` and `col_end` result in missing values for the merged column
## Examples
Use a subset of the [gtcars](data.gtcars.md#great_tables.data.gtcars) dataset to create a table. Merge the `mpg_c` and `mpg_h` columns together as a range.
``` python
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.
``` python
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 |