Allocation Manager¶

The fair_shares.library.allocations.manager module provides the high-level interface for running allocations with data loading and output management.

Running Allocations¶

run_allocation¶

Run a single allocation.

This is the main function for running allocations. It handles:

Parameter validation
Data requirement checking
Function execution
Result validation

Parameters:

Name	Type	Description	Default
`approach`	`str`	The allocation approach to use	required
`population_ts`	`TimeseriesDataFrame`	Population time series data	required
`first_allocation_year`	`int`	First allocation year (for pathway allocations)	`None`
`allocation_year`	`int`	Allocation year (for budget allocations)	`None`
`gdp_ts`	`TimeseriesDataFrame`	GDP time series data (if required by approach)	`None`
`gini_s`	`TimeseriesDataFrame`	Gini coefficient data (if required by approach)	`None`
`country_actual_emissions_ts`	`TimeseriesDataFrame`	Country-level actual emissions time series data (if required by approach)	`None`
`world_scenario_emissions_ts`	`TimeseriesDataFrame`	World scenario emissions pathway (used by approaches that require it)	`None`
`emission_category`	`str`	Emission category to allocate	`None`
`**kwargs`		Additional parameters specific to the allocation approach	`{}`

Returns:

Type	Description
`Union[BudgetAllocationResult, PathwayAllocationResult]`	The allocation result with relative shares

Raises:

Type	Description
`AllocationError`	If validation fails or required data is missing
`DataProcessingError`	If other errors occur during allocation

Examples:

Run a simple budget allocation:

Python Console Session

>>> from fair_shares.library.allocations import run_allocation
>>> from fair_shares.library.utils import create_example_data
>>>
>>> # Create example data
>>> data = create_example_data()
>>>
>>> # Run equal per capita budget allocation
>>> result = run_allocation(
...     approach="equal-per-capita-budget",
...     population_ts=data["population"],
...     allocation_year=2020,
...     emission_category="co2-ffi",
... )
Converting units...
>>>
>>> # Check result
>>> result.approach
'equal-per-capita-budget'
>>> # Shares sum to 1.0
>>> shares_sum = result.relative_shares_cumulative_emission.sum().iloc[0]
>>> bool(abs(shares_sum - 1.0) < 0.01)
True

Run a pathway allocation with adjustments:

Python Console Session

>>> # Run per capita adjusted pathway allocation
>>> result = run_allocation(
...     approach="per-capita-adjusted",
...     population_ts=data["population"],
...     gdp_ts=data["gdp"],
...     country_actual_emissions_ts=data["emissions"],
...     world_scenario_emissions_ts=data["world_emissions"],
...     first_allocation_year=2020,
...     emission_category="co2-ffi",
...     pre_allocation_responsibility_weight=0.5,
...     capability_weight=0.5,
... )
Converting units...
>>>
>>> # Check result
>>> result.approach
'per-capita-adjusted'
>>> # Check that shares are calculated for all years
>>> len(result.relative_shares_pathway_emissions.columns) == 3
True

Notes

This is the main entry point for running allocations. It automatically:

Determines whether the approach is budget or pathway based
Validates all input data structures
Checks that required data is provided for the chosen approach
Filters parameters to only pass what the allocation function needs

When to use: Use this function for single allocation runs. For running multiple parameter combinations, use :func:run_parameter_grid instead.

Budget vs Pathway: Budget approaches (ending in "-budget") allocate a single year's cumulative budget. Pathway approaches allocate emissions over multiple years. Budget approaches use allocation_year, pathway approaches use first_allocation_year.

Equity considerations: Each approach implements different equity principles. The equal per capita approaches treat population as the sole basis for claims. Adjusted approaches incorporate capability (ability to pay based on GDP) and/or historical responsibility, implementing aspects of CBDR-RC. Parameters like pre_allocation_responsibility_weight and capability_weight represent explicit normative choices about how to balance these considerations.

Transparency: All parameter choices are recorded in the result metadata to enable replication and critical assessment.

run_parameter_grid¶

Run allocations for all parameter combinations in a grid.

This function expands the configuration into all possible parameter combinations and runs each allocation.

Parameters:

Name	Type	Description	Default
`allocations_config`	`dict[str, list[dict[str, Any]]]`	Configuration dict with approach names as keys and lists of parameter dicts as values. Each parameter dict defines one configuration to run. Parameters within each dict can be single values or lists for grid expansion.	required
`population_ts`	`TimeseriesDataFrame`	Population time series data	required
`gdp_ts`	`TimeseriesDataFrame`	GDP time series data	`None`
`gini_s`	`TimeseriesDataFrame`	Gini coefficient data	`None`
`country_actual_emissions_ts`	`TimeseriesDataFrame`	Country-level actual emissions time series data	`None`
`world_scenario_emissions_ts`	`TimeseriesDataFrame`	World scenario emissions pathway data	`None`
`emission_category`	`str`	Emission category to allocate	`None`
`target_source`	`str`	Target source (e.g., "rcbs", "pathway")	`None`
`harmonisation_year`	`int`	Year at which scenarios are harmonized to historical data. Required for scenario-based targets (not RCBs).	`None`

Returns:

Type	Description
`list[Union[BudgetAllocationResult, PathwayAllocationResult]]`	list of allocation results

Examples:

Run multiple budget allocations across different years:

Python Console Session

>>> from fair_shares.library.allocations import run_parameter_grid
>>> from fair_shares.library.utils import create_example_data
>>>
>>> # Create example data
>>> data = create_example_data()
>>>
>>> # Define configuration with multiple years for equal per capita
>>> config = {"equal-per-capita-budget": [{"allocation-year": [2020, 2030]}]}
>>>
>>> # Run parameter grid
>>> results = run_parameter_grid(
...     allocations_config=config,
...     population_ts=data["population"],
...     emission_category="co2-ffi",
... )

Processing approach: equal-per-capita-budget
...
>>> # Check we got 2 results (one per year)
>>> len(results)
2
>>> # Both are budget results
>>> all(r.approach == "equal-per-capita-budget" for r in results)
True

Run parameter grid with weight combinations for adjusted allocation:

Python Console Session

>>> # Define configuration with parameter grid expansion
>>> config = {
...     "per-capita-adjusted-budget": [
...         {
...             "allocation-year": 2020,
...             "pre-allocation-responsibility-weight": 0.0,
...             "capability-weight": [0.25, 0.5, 0.75],
...         }
...     ]
... }
>>>
>>> # Run parameter grid (will expand to 3 combinations)
>>> results = run_parameter_grid(
...     allocations_config=config,
...     population_ts=data["population"],
...     gdp_ts=data["gdp"],
...     emission_category="co2-ffi",
... )

Processing approach: per-capita-adjusted-budget
...
>>> # Check we got 3 results (3 capability weights)
>>> len(results)
3
>>> # All are per-capita-adjusted-budget results
>>> all(r.approach == "per-capita-adjusted-budget" for r in results)
True

Notes

This function is designed for systematic parameter exploration. It:

Automatically expands parameter lists into all combinations
Validates that approaches are compatible with the target source
Ensures allocation years are consistent with harmonisation_year
Returns a list of all results for comparison

When to use: Use this function when you want to run the same allocation approach with multiple parameter combinations to compare results. For single allocations, use :func:run_allocation instead.

Parameter expansion: Any parameter value can be a list, and the function will create all combinations. For example, if allocation-year: [2020, 2030] and capability-weight: [0.25, 0.5], this will run 4 allocations (2 years x 2 weights).

Configuration format: The allocations_config parameter expects a nested structure where each approach maps to a list of parameter dictionaries. Each dictionary in the list can use either single values or lists for grid expansion.

Exploring normative choices: The parameter grid is useful for exploring how different normative choices affect allocations. For example, varying pre-allocation-responsibility-weight and capability-weight reveals the sensitivity of results to how CBDR-RC principles are operationalized. Similarly, varying pre-allocation-responsibility-year shows how the choice of start date for counting historical emissions affects current allocations - a choice that remains debated. See docs/science/allocations.md for details.

Results Processing¶

calculate_absolute_emissions¶

Calculate absolute emissions from allocation result and emissions data.

Converts relative shares (fractions summing to 1.0) into absolute emission quantities by applying the shares to a global emissions total. This separation of relative and absolute allows the same equity-based allocation to be applied to different emissions scenarios or budget estimates.

Parameters:

Name	Type	Description	Default
`result`	`Union[BudgetAllocationResult, PathwayAllocationResult]`	The allocation result containing relative shares. These shares represent each country's claim to a portion of the global emissions space.	required
`emissions_data`	`TimeseriesDataFrame`	Emissions data providing the global totals to which shares are applied. For budget allocations, this is the total budget to distribute. For pathway allocations, this is the year-by-year global trajectory.	required

Returns:

Type	Description
`TimeseriesDataFrame`	Absolute emissions/budgets calculated from relative shares. Units match the input emissions_data (typically MtCO2eq or GtCO2eq).

save_allocation_result¶

Save allocation results to parquet files.

Persists allocation results with comprehensive metadata to enable transparent, replicable analysis. Following the transparency principles recommended for transparency, all parameter choices and data sources are recorded to allow critical assessment of the normative choices embedded in each allocation.

Parameters:

Name	Type	Description	Default
`result`	`Union[BudgetAllocationResult, PathwayAllocationResult]`	The allocation result to save	required
`output_dir`	`Path`	Directory to save results	required
`absolute_emissions`	`TimeseriesDataFrame`	Absolute emissions data (if None, only relative shares are saved)	`None`
`climate_assessment`	`str`	Climate assessment name (e.g., "AR6")	`None`
`quantile`	`float`	Quantile value for scenario (e.g., 0.5 for median)	`None`
`data_context`	`dict`	Context about data sources and processing. Should include sources for population, GDP, emissions, and other input data to enable verification.	`None`
`**metadata`		Additional metadata to include	`{}`

Returns:

Type	Description
`dict[str, Path]`	Paths to saved parquet files

Raises:

Type	Description
`DataProcessingError`	If data preparation fails
`IOError`	If file writing fails

Notes

The output includes a warnings column that flags allocations requiring attention, such as:

not-fair-share: Approaches like per-capita-convergence that privilege current emission patterns during transition
missing-net-negative: Scenarios where negative emissions were excluded

Output Management¶

generate_readme¶

Generate README files for relative and absolute parquet files.

Creates human-readable documentation of the allocation outputs, including column descriptions and data sources. This supports the transparency goal of enabling users to understand and critically assess the choices embedded in each allocation.

Parameters:

Name	Type	Description	Default
`output_dir`	`Path`	Directory containing parquet files	required
`data_context`	`dict`	Context about data sources and processing	`None`

create_param_manifest¶

Create param_manifest.csv with proper kebab-case column names.

The parameter manifest provides a summary of all allocation configurations run in a batch, enabling quick comparison of different normative choices. This supports transparent reporting of how different parameter combinations affect allocation results.

Parameters:

Name	Type	Description	Default
`param_manifest_rows`	`list[dict[str, Any]]`	List of parameter manifest rows, where each row contains parameters in snake_case format	required
`output_dir`	`Path`	Directory where param_manifest.csv will be saved	required

Allocation Manager¶

Running Allocations¶

run_allocation¶

run_parameter_grid¶

Results Processing¶

calculate_absolute_emissions¶

save_allocation_result¶

Output Management¶

generate_readme¶

create_param_manifest¶

See Also¶