Convergence Validation

Validation functions specific to convergence pathway allocations.

Weight Validation

validate_weights

fair_shares.library.validation.convergence.validate_weights

Python

validate_weights(
    pre_allocation_responsibility_weight: float,
    capability_weight: float,
) -> None

Validate that adjustment weights are non-negative and sum to <= 1.0.

Parameters:

Name	Type	Description	Default
pre_allocation_responsibility_weight	float	Weight for pre-allocation responsibility adjustment (historical emissions).	required
capability_weight	float	Weight for capability adjustment (GDP-based).	required

Raises:

Type	Description
AllocationError	If weights are negative or sum exceeds 1.0.

validate_adjustment_data_requirements

fair_shares.library.validation.convergence.validate_adjustment_data_requirements

Python

validate_adjustment_data_requirements(
    capability_weight: float,
    gdp_ts: TimeseriesDataFrame | None,
    gini_s: DataFrame | None,
) -> None

Validate that required data is provided when adjustment weights are used.

Parameters:

Name	Type	Description	Default
capability_weight	float	Weight for capability adjustment.	required
gdp_ts	TimeseriesDataFrame | None	GDP data (required if capability_weight > 0 or gini_s provided).	required
gini_s	DataFrame | None	Gini coefficient data (requires gdp_ts if provided).	required

Raises:

Type	Description
AllocationError	If required data is missing for requested adjustments.

Data Validation

validate_emissions_data

fair_shares.library.validation.convergence.validate_emissions_data

Python

validate_emissions_data(
    emissions_numeric: DataFrame,
    emission_category: str,
    group_level: str,
) -> None

Validate emissions data structure and content.

Parameters:

Name	Type	Description	Default
emissions_numeric	DataFrame	Emissions data after unit processing.	required
emission_category	str	The emission category being analyzed.	required
group_level	str	Index level for country grouping (e.g., 'iso3c').	required

Raises:

Type	Description
AllocationError	If emissions data is empty, missing required index, or contains no countries.

validate_country_data_present

fair_shares.library.validation.convergence.validate_country_data_present

Python

validate_country_data_present(
    emissions_countries: DataFrame, group_level: str
) -> None

Validate that emissions data contains country-level data, not just World totals.

Parameters:

Name	Type	Description	Default
emissions_countries	DataFrame	Emissions data after filtering out World rows.	required
group_level	str	Index level for country grouping (e.g., 'iso3c').	required

Raises:

Type	Description
AllocationError	If no country data is found (only World totals present).

validate_year_in_data

fair_shares.library.validation.convergence.validate_year_in_data

Python

validate_year_in_data(
    year: int,
    year_to_label: dict[int, str | int | float],
    dataset_name: str,
    available_columns: list[str],
) -> None

Validate that a required year is present in the dataset.

Parameters:

Name	Type	Description	Default
year	int	Required year.	required
year_to_label	dict[int, str | int | float]	Mapping from integer years to column labels.	required
dataset_name	str	Name of dataset for error message (e.g., "country emissions").	required
available_columns	list[str]	Available column labels in dataset.	required

Raises:

Type	Description
AllocationError	If the required year is not found in the dataset.

validate_world_emissions_present

fair_shares.library.validation.convergence.validate_world_emissions_present

Python

validate_world_emissions_present(
    world_numeric: DataFrame,
) -> None

Validate that world scenario emissions data is not empty.

Parameters:

Name	Type	Description	Default
world_numeric	DataFrame	World scenario emissions after processing.	required

Raises:

Type	Description
AllocationError	If world emissions data is empty.

validate_country_world_consistency

fair_shares.library.validation.convergence.validate_country_world_consistency

Python

validate_country_world_consistency(
    country_sum: float,
    world_total: float,
    first_allocation_year: int,
    tolerance: float = 1e-06,
) -> None

Validate that country emissions sum to world total at allocation start year.

Parameters:

Name	Type	Description	Default
country_sum	float	Sum of all country emissions at start year.	required
world_total	float	World total emissions at start year.	required
first_allocation_year	int	Year when allocation begins.	required
tolerance	float	Absolute tolerance for comparison (default: 1e-6).	1e-06

Raises:

Type	Description
AllocationError	If country and world totals don't match within tolerance.

Convergence Calculation Validation

validate_sufficient_time_horizon

fair_shares.library.validation.convergence.validate_sufficient_time_horizon

Python

validate_sufficient_time_horizon(
    sorted_columns: list[str],
    start_column: str,
    first_allocation_year: int,
) -> None

Validate that there are enough years after start for convergence.

Parameters:

Name	Type	Description	Default
sorted_columns	list[str]	Sorted list of year column labels.	required
start_column	str	Column label for first allocation year.	required
first_allocation_year	int	Year when allocation begins.	required

Raises:

Type	Description
AllocationError	If no years exist after the first allocation year.

validate_share_calculation

fair_shares.library.validation.convergence.validate_share_calculation

Python

validate_share_calculation(
    shares: Series | DataFrame, step_description: str
) -> None

Validate that calculated shares are valid (not NaN, positive sum).

Parameters:

Name	Type	Description	Default
shares	Series | DataFrame	Calculated shares to validate.	required
step_description	str	Description of calculation step for error message.	required

Raises:

Type	Description
AllocationError	If shares contain NaN or sum to invalid total.

validate_world_weights_aligned

fair_shares.library.validation.convergence.validate_world_weights_aligned

Python

validate_world_weights_aligned(
    year_fractions: Series, required_columns: Index
) -> None

Validate that world weight fractions are available for all required years.

Parameters:

Name	Type	Description	Default
year_fractions	Series	Year-based weight fractions (reindexed to required_columns).	required
required_columns	Index	Required year columns.	required

Raises:

Type	Description
AllocationError	If any required years are missing from world weights.

See Also

• Math Utilities: Convergence solver
• Data Utilities: Data processing