Index

subsurfaceio.polars_utils

Shared Polars helpers.

from subsurfaceio.polars_utils import aggregate
import polars as pl

aggregate(pl.DataFrame({'x': [1.0, 2.0]}))

Functions:

Name	Description
`aggregate`	Aggregate every column of a DataFrame into a single row.
`aggregate_by_bins`	Bin a DataFrame by `key` and aggregate the remaining columns per bin.
`cast_to_registered_dtypes`	Coerce columns to their canonical registry dtype, where registered.
`rename_to_registered_labels`	Rename columns to their registry display label, where registered.
`rename_to_registered_names`	Rename columns to their canonical registry name, where registered.

aggregate

aggregate(
    df: DataFrame,
    aggregation: Aggregation = "mean",
    quantile: float | None = None,
) -> pl.DataFrame

Aggregate every column of a DataFrame into a single row.

NaNs are treated as nulls before aggregating, since Polars otherwise propagates NaN through most reductions.

Parameters:

Name	Type	Description	Default
`df`	`DataFrame`	DataFrame to aggregate.	required
`aggregation`	`Aggregation`	Aggregation strategy: `"quantile"` — requires `quantile` to be set; uses linear interpolation. `"characteristic"` — `mean - 0.5 * std` (null std treated as 0), a common geotechnical "characteristic value". `"gmean"` — geometric mean over strictly positive values only.	`'mean'`
`quantile`	`float \| None`	Quantile in `[0, 1]`, required when `aggregation="quantile"`.	`None`

Returns:

Type	Description
`DataFrame`	A single-row DataFrame with the aggregated value per column.

Raises:

Type	Description
`ValueError`	If `aggregation == "quantile"` and `quantile` is None.

aggregate_by_bins

aggregate_by_bins(
    df: DataFrame,
    key: str,
    breaks: Sequence[float],
    aggregation: Aggregation = "mean",
    quantile: float | None = None,
    left_closed: bool = False,
    include_string_types_as_mode: bool = True,
    drop_infinite: bool = True,
) -> pl.DataFrame

Bin a DataFrame by key and aggregate the remaining columns per bin.

Numeric columns are reduced using aggregation; string/categorical and boolean columns are optionally reduced using their mode. The key column is replaced by each bin's upper breakpoint, and the result is sorted by key — grouping does not preserve numeric bin order (it's the default, unordered group by; within-group row order is unaffected), so the trailing sort is what actually determines bin order in the output.

Parameters:

Name	Type	Description	Default
`df`	`DataFrame`	DataFrame to bin and aggregate.	required
`key`	`str`	Name of the column to bin (e.g. depth).	required
`breaks`	`Sequence[float]`	Bin edges, as passed to `polars.Expr.cut`. When derived from `numpy.arange`, callers should account for floating-point imprecision in the edge values.	required
`aggregation`	`Aggregation`	Aggregation strategy for numeric columns; see `aggregate`.	`'mean'`
`quantile`	`float \| None`	Quantile in `[0, 1]`, required when `aggregation="quantile"`.	`None`
`left_closed`	`bool`	Whether bins are left-closed, as passed to `polars.Expr.cut`.	`False`
`include_string_types_as_mode`	`bool`	If True, also aggregate string, categorical, and boolean columns using their first mode.	`True`
`drop_infinite`	`bool`	If True, drop the bin whose breakpoint is infinite — i.e. values of `key` beyond the last explicit break. Rows where `key` itself is null are kept.	`True`

Returns:

Type	Description
`DataFrame`	A DataFrame with one row per bin, sorted by `key`.

cast_to_registered_dtypes

cast_to_registered_dtypes(df: DataFrame) -> pl.DataFrame

Coerce columns to their canonical registry dtype, where registered.

For every column whose key is present in parameter_registry, the values are passed through the parameter's data_ensure_data_type conversion and cast to its declared data_type. Columns not present in the registry are left untouched.

Parameters:

Name	Type	Description	Default
`df`	`DataFrame`	DataFrame to coerce.	required

Returns:

Type	Description
`DataFrame`	A new DataFrame with registered columns cast to their declared dtypes.

rename_to_registered_labels

rename_to_registered_labels(df: DataFrame) -> pl.DataFrame

Rename columns to their registry display label, where registered.

Parameters:

Name	Type	Description	Default
`df`	`DataFrame`	DataFrame whose columns are parameter names.	required

Returns:

Type	Description
`DataFrame`	A new DataFrame with registered columns renamed to their display label via `parameter_registry.name_to_display_label_map`.

rename_to_registered_names

rename_to_registered_names(df: DataFrame) -> pl.DataFrame

Rename columns to their canonical registry name, where registered.

Parameters:

Name	Type	Description	Default
`df`	`DataFrame`	DataFrame whose columns are parameter labels.	required

Returns:

Type	Description
`DataFrame`	A new DataFrame with registered columns renamed to their canonical registry name via `parameter_registry.display_label_to_name_map`.