Skip to content

Core Utilities

Core utility functions for data manipulation, unit conversion, and common operations.

Data Filtering

filter_time_columns

fair_shares.library.utils.filter_time_columns

Python
filter_time_columns(
    df: TimeseriesDataFrame, allocation_time: int
) -> TimeseriesDataFrame

Filter DataFrame to include only numeric columns >= allocation_time.

ensure_string_year_columns

fair_shares.library.utils.ensure_string_year_columns

Python
ensure_string_year_columns(
    df: TimeseriesDataFrame, *, inplace: bool = False
) -> TimeseriesDataFrame

Coerce numeric-looking year column labels to strings.

This is used to deal with TimeseriesDataFrames that have year columns often stored as ints or other types. We want to coerce these to strings so that merges are not problematic.

Parameters:

Name Type Description Default
df TimeseriesDataFrame

TimeseriesDataFrame that may contain year columns stored as ints or other types.

 required
inplace bool

If True, rename the columns on df and return it. If False (default), return a TimeseriesDataFrame with renamed columns and leave df untouched.

 False

Returns:

Type Description
TimeseriesDataFrame

TimeseriesDataFrame whose year columns are strings. The returned object is df when inplace is True; otherwise it is a renamed copy.

Unit Handling

set_single_unit

fair_shares.library.utils.set_single_unit

Python
set_single_unit(
    df: TimeseriesDataFrame,
    unit_level: str,
    ur: PlainRegistry = None,
) -> TimeseriesDataFrame

Convert DataFrame to have a single unit by converting all units to the first unit.

Parameters:

Name Type Description Default
df TimeseriesDataFrame

DataFrame to convert to single unit

 required
unit_level str

Name of the index level containing units

 required
ur PlainRegistry

Unit registry to use for conversions (defaults to openscm-units registry)

 None

Returns:

Type Description
TimeseriesDataFrame

DataFrame with all data converted to the first unit found

Raises:

Type Description
DataProcessingError

If the DataFrame has no units

get_default_unit_registry

fair_shares.library.utils.get_default_unit_registry cached

Python
get_default_unit_registry() -> PlainRegistry

Get the default unit registry to use throughout the codebase.

This registry is configured with climate-specific units and contexts needed for fair share allocation calculations. It includes: - Magnitude units (thousand, million, billion) - Emission units (kt, Mt, CO2e, gigagram) - Annual conversion contexts - AR6GWP100 context for greenhouse gas equivalencies

This is the standard unit registry used by default in all allocation functions and unit conversion utilities. Custom registries can be supplied directly to individual functions if needed.

Returns:

Type Description
PlainRegistry

Configured unit registry with climate-specific units and contexts

Raises:

Type Description
MissingOptionalDependencyError

openscm_units is not installed

Index Operations

groupby_except_robust

fair_shares.library.utils.groupby_except_robust

Python
groupby_except_robust(
    data: TimeseriesDataFrame | Series, group_level: str
) -> TimeseriesDataFrame | Series

Robust groupby that handles both MultiIndex and single-level index cases.

For MultiIndex: uses groupby_except to group by all levels except group_level For single-level index: uses simple sum() across rows

Parameters:

Name Type Description Default
data TimeseriesDataFrame | Series

DataFrame or Series to group

 required
group_level str

Level name to exclude from grouping (typically "iso3c")

 required

Returns:

Type Description
Grouped data with totals calculated appropriately for the index structure

See Also