Budget Allocation Functions¶

Budget allocation functions distribute a fixed cumulative emission budget among countries in a given allocation year.

Overview¶

All budget allocation approaches return a BudgetAllocationResult containing:

approach: Name of the allocation approach used
parameters: Dictionary of parameters used in the calculation
relative_shares_cumulative_emission: DataFrame of budget shares (sum to 1.0)

Per Capita Budgets¶

equal_per_capita_budget¶

fair_shares.library.allocations.budgets.per_capita.equal_per_capita_budget ¶

Python

equal_per_capita_budget(
    population_ts: TimeseriesDataFrame,
    allocation_year: int,
    emission_category: str,
    preserve_allocation_year_shares: bool = False,
    cumulative_end_year: int | None = None,
    group_level: str = "iso3c",
    unit_level: str = "unit",
    ur: PlainRegistry = get_default_unit_registry(),
) -> BudgetAllocationResult

Equal per capita budget allocation for cumulative emissions.

This function generates cumulative shares for the allocation year based on equal per capita principles.

Mathematical Foundation

Two allocation modes are supported:

Mode 1: Dynamic shares (preserve_allocation_year_shares=False, default)

Population shares are calculated using cumulative population from allocation_year onwards. This accounts for changes in relative population shares over time:

\[ A(g) = \frac{\sum_{t \geq t_a} P(g, t)}{\sum_{g} \sum_{t \geq t_a} P(g, t)} \]

Where:

\(A(g)\): Budget share allocated to country \(g\)
\(P(g, t)\): Population of country \(g\) in year \(t\)
\(t_a\): Allocation year
\(\sum_{t \geq t_a} P(g, t)\): Cumulative population of country \(g\) from allocation year onwards
\(\sum_{g} \sum_{t \geq t_a} P(g, t)\): Total cumulative population across all countries from allocation year onwards

Mode 2: Preserved shares (preserve_allocation_year_shares=True)

Population shares calculated at the allocation year are preserved. This means the relative allocation between groups remains constant:

\[ A(g) = \frac{P(g, t_a)}{\sum_{g} P(g, t_a)} \]

Where:

\(A(g)\): Budget share allocated to country \(g\)
\(P(g, t_a)\): Population of country \(g\) at allocation year \(t_a\)
\(\sum_{g} P(g, t_a)\): Total world population at allocation year

Parameters:

Name	Type	Description	Default
`population_ts`	`TimeseriesDataFrame`	Population time series for each group of interest.	required
`allocation_year`	`int`	Year from which to calculate budget shares. See `docs/science/parameter-effects.md` §allocation_year for how the choice of year affects country shares.	required
`emission_category`	`str`	Emission category (e.g., `'co2-ffi'`, `'all-ghg'`).	required
`preserve_allocation_year_shares`	`bool`	Mode. If `False` (default), shares are calculated using cumulative population from `allocation_year` onwards. If `True`, shares from `allocation_year` only are used.	`False`
`cumulative_end_year`	`int \| None`	Upper bound of the cumulative population window. `None` (default) uses the last year in the population data.	`None`
`group_level`	`str`	Index level name for grouping. Default: `'iso3c'`.	`'iso3c'`
`unit_level`	`str`	Index level name for units. Default: `'unit'`.	`'unit'`
`ur`	`PlainRegistry`	Pint unit registry for unit conversions.	`get_default_unit_registry()`

Returns:

Type	Description
`BudgetAllocationResult`	Relative shares for cumulative emissions budget allocation, summing to 1 across groups.

Notes

See docs/science/allocations.md for mathematical formulation. See docs/science/principle-to-code.md for implementation examples.

per_capita_adjusted_budget¶

fair_shares.library.allocations.budgets.per_capita.per_capita_adjusted_budget ¶

Python

per_capita_adjusted_budget(
    population_ts: TimeseriesDataFrame,
    allocation_year: int,
    emission_category: str,
    country_actual_emissions_ts: (
        TimeseriesDataFrame | None
    ) = None,
    responsibility_emissions_ts: (
        TimeseriesDataFrame | None
    ) = None,
    gdp_ts: TimeseriesDataFrame | None = None,
    pre_allocation_responsibility_weight: float = 0.0,
    capability_weight: float = 0.0,
    pre_allocation_responsibility_year: int = 1990,
    pre_allocation_responsibility_per_capita: bool = False,
    pre_allocation_responsibility_exponent: float = 1.0,
    pre_allocation_responsibility_functional_form: str = "asinh",
    capability_per_capita: bool = True,
    capability_exponent: float = 1.0,
    capability_functional_form: str = "asinh",
    capability_reference_year: int | None = None,
    max_deviation_sigma: float | None = None,
    preserve_allocation_year_shares: bool = False,
    historical_discount_rate: float = 0.0,
    cumulative_end_year: int | None = None,
    group_level: str = "iso3c",
    unit_level: str = "unit",
    ur: PlainRegistry = get_default_unit_registry(),
) -> BudgetAllocationResult

Per capita budget allocation with pre-allocation responsibility and capability adjustments.

This function generates cumulative shares for the allocation year based on adjusted per capita principles, incorporating pre-allocation responsibility and economic capability adjustments (but without Gini correction).

Mathematical Foundation

The per capita adjusted budget allocation adjusts for pre-allocation responsibility and economic capability using the following approach.

Core Allocation Formula

For budget allocation with dynamic shares (default mode):

\[ A(g) = \frac{\sum_{t \geq t_a} R(g) \times C(g, t) \times P(g, t)}{\sum_g \sum_{t \geq t_a} R(g) \times C(g, t) \times P(g, t)} \]

Where:

\(A(g)\): Budget share allocated to country \(g\)
\(R(g)\): Pre-allocation responsibility adjustment factor for country \(g\) (constant over time, equals 1.0 if not used)
\(C(g, t)\): Capability adjustment factor for country \(g\) in year \(t\) (equals 1.0 if not used)
\(P(g, t)\): Population of country \(g\) in year \(t\)
\(t_a\): Allocation year

Pre-Allocation Responsibility Adjustment

Historical emissions reduce future allocation rights.

For per capita pre-allocation responsibility (:code:pre_allocation_responsibility_per_capita=True):

\[ R(g) = \left(\frac{\sum_{t=t_h}^{t_a-1} E(g, t)}{\sum_{t=t_h}^{t_a-1} P(g, t)}\right)^{-w_r \times e_r} \]

Where:

\(R(g)\): Pre-allocation responsibility adjustment factor (inverse - higher emissions = lower allocation)
\(E(g, t)\): Emissions of country \(g\) in year \(t\)
\(t_h\): Pre-allocation responsibility start year
\(t_a\): Allocation year
\(w_r\): Normalized pre-allocation responsibility weight
\(e_r\): Pre-allocation responsibility exponent

For absolute pre-allocation responsibility (:code:pre_allocation_responsibility_per_capita=False, default):

\[ R(g) = \left(\sum_{t=t_h}^{t_a-1} E(g, t)\right)^{-w_r \times e_r} \]

Capability Adjustment

Economic capacity reduces allocation rights for wealthier countries.

By default (capability_reference_year=None), the capability term \(C(g, t)\) is computed year-by-year from gdp_ts, integrating lifetime capability over the full allocation window. When capability_reference_year is set to an integer \(t_{\text{ref}}\), the capability is frozen at that year: \(C(g, t) \equiv C(g, t_{\text{ref}})\) for all \(t\) in the cumulative window. When capability_reference_year is before allocation_year, the snapshot is sourced from the full unfiltered gdp_ts. When capability_reference_year exceeds the last observed GDP year, the last observed column is used as the snapshot (forward-fill fallback, consistent with year-by-year default mode), and a UserWarning is emitted.

For per capita capability (:code:capability_per_capita=True, default):

\[ C(g, t) = \left(\frac{\text{GDP}(g, t)}{P(g, t)}\right)^{-w_c \times e_c} \]

Where:

\(C(g, t)\): Capability adjustment factor (inverse - higher GDP per capita = lower allocation)
\(\text{GDP}(g, t)\): Gross domestic product of country \(g\) in year \(t\)
\(w_c\): Normalized capability weight
\(e_c\): Capability exponent

For absolute capability (:code:capability_per_capita=False):

\[ C(g, t) = \text{GDP}(g, t)^{-w_c \times e_c} \]

Two allocation modes are supported based on :code:preserve_allocation_year_shares:

False (default): Uses cumulative adjusted population from allocation_year onwards
True: Uses adjusted population at allocation_year only

Parameters:

Name	Type	Description	Default
`population_ts`	`TimeseriesDataFrame`	Population time series for each group of interest.	required
`allocation_year`	`int`	Year from which to calculate budget shares. See `docs/science/parameter-effects.md` §allocation_year for how the choice of year affects country shares.	required
`emission_category`	`str`	Emission category (e.g., `'co2-ffi'`, `'all-ghg'`).	required
`country_actual_emissions_ts`	`TimeseriesDataFrame \| None`	Pre-allocation responsibility. Historical emissions data. Required when `pre_allocation_responsibility_weight > 0`.	`None`
`gdp_ts`	`TimeseriesDataFrame \| None`	Capability. GDP data used from `allocation_year` onwards, or at `capability_reference_year` only when that is set. Required when `capability_weight > 0`.	`None`
`pre_allocation_responsibility_weight`	`float`	Pre-allocation responsibility. Relative weight (0–1). Only the ratio to `capability_weight` matters. When 0, pre-allocation responsibility is disabled. See `docs/science/parameter-effects.md` §weights.	`0.0`
`capability_weight`	`float`	Capability. Relative weight (0–1). Applies from `allocation_year` onwards (contrast with pre-allocation responsibility, which covers the window before it). When 0, capability is disabled. See `docs/science/parameter-effects.md` §weights.	`0.0`
`pre_allocation_responsibility_year`	`int`	Pre-allocation responsibility. Start year of the historical window `[pre_allocation_responsibility_year, allocation_year)`. Default: 1990.	`1990`
`pre_allocation_responsibility_per_capita`	`bool`	Pre-allocation responsibility. If `True`, uses per-capita cumulative emissions. If `False` (default), uses absolute cumulative emissions.	`False`
`pre_allocation_responsibility_exponent`	`float`	Pre-allocation responsibility. Exponent applied to the emissions metric. Default: 1.0.	`1.0`
`pre_allocation_responsibility_functional_form`	`str`	Pre-allocation responsibility. Transformation: `'asinh'` (default) or `'power'`.	`'asinh'`
`capability_per_capita`	`bool`	Capability. If `True` (default), GDP is divided by population. If `False`, absolute GDP is used.	`True`
`capability_exponent`	`float`	Capability. Exponent applied to the GDP metric. Default: 1.0.	`1.0`
`capability_functional_form`	`str`	Capability. Transformation: `'asinh'` (default) or `'power'`.	`'asinh'`
`capability_reference_year`	`int \| None`	Capability. When `None` (default), capability is computed year-by-year. When set to an integer, GDP from that single year is broadcast across the allocation window. May be before or after `allocation_year`. GDP is then required at that year only, so `allocation_year` may precede the first GDP year. Ignored when `capability_weight == 0`.	`None`
`max_deviation_sigma`	`float \| None`	Constraint. Maximum allowed deviation from equal per capita, in standard deviations. `None` (default) means no constraint.	`None`
`preserve_allocation_year_shares`	`bool`	Mode. If `False` (default), uses cumulative adjusted population from `allocation_year` onwards. If `True`, uses population at `allocation_year` only.	`False`
`historical_discount_rate`	`float`	Pre-allocation responsibility. Discount rate for historical emissions (0.0 to <1.0), via `(1 - rate)^(reference_year - t)` Default: 0.0. Only affects the pre-allocation responsibility calculation.	`0.0`
`cumulative_end_year`	`int \| None`	Upper bound of the cumulative window. `None` (default) uses the last year in the population data.	`None`
`group_level`	`str`	Index level name for grouping. Default: `'iso3c'`.	`'iso3c'`
`unit_level`	`str`	Index level name for units. Default: `'unit'`.	`'unit'`
`ur`	`PlainRegistry`	Pint unit registry for unit conversions.	`get_default_unit_registry()`

Returns:

Type	Description
`BudgetAllocationResult`	Container with relative shares for cumulative emissions budget allocation. The TimeseriesDataFrame contains only the allocation_year column with adjusted population shares that sum to 1 across groups for the specified emission category.

Notes

Theoretical grounding:

See docs/science/allocations.md#historical-responsibility for CBDR-RC alignment and parameter considerations. For implementation examples combining pre-allocation responsibility and capability adjustments, see docs/science/principle-to-code.md.

GDP window: When the allocation cumulative window extends past the last year of the input gdp_ts, the GDP per capita values from the last observed year are forward-filled to cover the full window. This preserves the cross-country capability ratios of the last observed year, but those ratios then get weighted against the full post-observation population trajectory. Users who want different post-observation capability dynamics (SSP2 projections, custom growth assumptions, or a future-extended WDI release) should extend the input gdp_ts time series before calling this function. The forward-fill is the minimum-disruption default when no projected GDP data is supplied.

per_capita_adjusted_gini_budget¶

fair_shares.library.allocations.budgets.per_capita.per_capita_adjusted_gini_budget ¶

Python

per_capita_adjusted_gini_budget(
    population_ts: TimeseriesDataFrame,
    gdp_ts: TimeseriesDataFrame,
    gini_s: DataFrame,
    allocation_year: int,
    emission_category: str,
    country_actual_emissions_ts: (
        TimeseriesDataFrame | None
    ) = None,
    responsibility_emissions_ts: (
        TimeseriesDataFrame | None
    ) = None,
    pre_allocation_responsibility_weight: float = 0.0,
    capability_weight: float = 1.0,
    pre_allocation_responsibility_year: int = 1990,
    pre_allocation_responsibility_per_capita: bool = False,
    pre_allocation_responsibility_exponent: float = 1.0,
    pre_allocation_responsibility_functional_form: str = "asinh",
    capability_per_capita: bool = True,
    capability_exponent: float = 1.0,
    capability_functional_form: str = "asinh",
    capability_reference_year: int | None = None,
    income_floor: float = 0.0,
    max_gini_adjustment: float = 0.8,
    max_deviation_sigma: float | None = None,
    preserve_allocation_year_shares: bool = False,
    historical_discount_rate: float = 0.0,
    cumulative_end_year: int | None = None,
    group_level: str = "iso3c",
    unit_level: str = "unit",
    ur: PlainRegistry = get_default_unit_registry(),
) -> BudgetAllocationResult

Per capita budget allocation with pre-allocation responsibility, capability, and Gini adjustments.

This function generates cumulative shares for the allocation year based on adjusted per capita principles, incorporating pre-allocation responsibility, Gini-corrected GDP capability adjustments, and inequality considerations.

Mathematical Foundation

The Gini-adjusted budget allocation extends the per capita adjusted approach by incorporating income inequality within countries.

Core Allocation Formula

For budget allocation with dynamic shares (default mode):

\[ A(g) = \frac{\sum_{t \geq t_a} R(g) \times C_{\text{Gini}}(g, t) \times P(g, t)}{\sum_g \sum_{t \geq t_a} R(g) \times C_{\text{Gini}}(g, t) \times P(g, t)} \]

Where:

\(A(g)\): Budget share allocated to country \(g\)
\(R(g)\): Pre-allocation responsibility adjustment factor (equals 1.0 if not used)
\(C_{\text{Gini}}(g, t)\): Gini-adjusted capability factor (equals 1.0 if not used)
\(P(g, t)\): Population of country \(g\) in year \(t\)
\(t_a\): Allocation year

Gini Adjustment Process

GDP is adjusted using an interpretation of the Greenhouse Development Rights (GDR) framework's capability metric (note: GDR was designed for burden-sharing; fair-shares adapts its capability calculation for entitlement allocation). Only income above a development threshold counts as capability. When combined with the income floor, higher inequality means more national income sits above the threshold — increasing measured capability. See :func:~fair_shares.library.utils.math.allocation.calculate_gini_adjusted_gdp for the full mathematical derivation.

Pre-Allocation Responsibility Adjustment

Identical to per capita adjusted budget (see that function for details).

For per capita pre-allocation responsibility (:code:pre_allocation_responsibility_per_capita=True):

\[ R(g) = \left(\frac{\sum_{t=t_h}^{t_a-1} E(g, t)}{\sum_{t=t_h}^{t_a-1} P(g, t)}\right)^{-w_r \times e_r} \]

Where:

\(E(g, t)\): Emissions of country \(g\) in year \(t\)
\(t_h\): Pre-allocation responsibility start year
\(t_a\): Allocation year
\(w_r\): Normalized pre-allocation responsibility weight
\(e_r\): Pre-allocation responsibility exponent

Capability Adjustment with Gini-Adjusted GDP

For per capita capability (:code:capability_per_capita=True, default):

\[ C_{\text{Gini}}(g, t) = \left(\frac{\text{GDP}^{\text{adj}}(g, t)}{P(g, t)}\right)^{-w_c \times e_c} \]

Where:

\(C_{\text{Gini}}(g, t)\): Gini-adjusted capability factor (inverse - higher adjusted GDP = lower allocation)
\(\text{GDP}^{\text{adj}}(g, t)\): Gini-adjusted GDP (see :func:~fair_shares.library.utils.math.allocation.calculate_gini_adjusted_gdp)
\(w_c\): Normalized capability weight
\(e_c\): Capability exponent

When combined with the income floor, higher inequality means more income above the development threshold, giving high-inequality countries smaller emission allocations than unadjusted GDP would suggest.

By default (capability_reference_year=None), \(C_{\text{Gini}}(g, t)\) is computed year-by-year. Setting capability_reference_year to an integer freezes capability at that year: \(C_{\text{Gini}}(g, t) \equiv C_{\text{Gini}}(g, t_{\text{ref}})\) for all \(t\) in the window. The Gini adjustment applies to the snapshot wherever the reference year lies, including when capability_reference_year < allocation_year.

Two allocation modes are supported based on :code:preserve_allocation_year_shares:

False (default): Uses cumulative adjusted population from allocation_year onwards
True: Uses adjusted population at allocation_year only

Parameters:

Name	Type	Description	Default
`population_ts`	`TimeseriesDataFrame`	Population time series for each group of interest.	required
`gdp_ts`	`TimeseriesDataFrame`	Capability. GDP time series (required). Used from `allocation_year` onwards for capability calculations, or at `capability_reference_year` only when that is set.	required
`gini_s`	`DataFrame`	Gini. Gini coefficients for within-country income inequality (required). Used to adjust GDP before computing the capability factor.	required
`allocation_year`	`int`	Year from which to calculate budget shares. See `docs/science/parameter-effects.md` §allocation_year.	required
`emission_category`	`str`	Emission category (e.g., `'co2-ffi'`, `'all-ghg'`).	required
`country_actual_emissions_ts`	`TimeseriesDataFrame \| None`	Pre-allocation responsibility. Historical emissions data. Required when `pre_allocation_responsibility_weight > 0`.	`None`
`pre_allocation_responsibility_weight`	`float`	Pre-allocation responsibility. Relative weight (0–1). Only the ratio to `capability_weight` matters. When 0, pre-allocation responsibility is disabled. See `docs/science/parameter-effects.md` §weights.	`0.0`
`capability_weight`	`float`	Capability. Relative weight (0–1, default 1.0). Applies from `allocation_year` onwards. When 0, capability is disabled.	`1.0`
`pre_allocation_responsibility_year`	`int`	Pre-allocation responsibility. Start year of the historical window. Default: 1990.	`1990`
`pre_allocation_responsibility_per_capita`	`bool`	Pre-allocation responsibility. If `True`, uses per-capita cumulative emissions. If `False` (default), uses absolute cumulative emissions.	`False`
`pre_allocation_responsibility_exponent`	`float`	Pre-allocation responsibility. Exponent applied to the emissions metric. Default: 1.0.	`1.0`
`pre_allocation_responsibility_functional_form`	`str`	Pre-allocation responsibility. Transformation: `'asinh'` (default) or `'power'`.	`'asinh'`
`capability_per_capita`	`bool`	Capability. If `True` (default), Gini-adjusted GDP is divided by population. If `False`, absolute Gini-adjusted GDP is used.	`True`
`capability_exponent`	`float`	Capability. Exponent applied to the Gini-adjusted GDP metric. Default: 1.0.	`1.0`
`capability_functional_form`	`str`	Capability. Transformation: `'asinh'` (default) or `'power'`.	`'asinh'`
`capability_reference_year`	`int \| None`	Capability. When `None` (default), capability is computed year-by-year. When set to an integer, GDP from that single year is broadcast across the allocation window. May be before or after `allocation_year`; the Gini adjustment applies to the snapshot in both cases. GDP is then required at that year only, so `allocation_year` may precede the first GDP year. Ignored when `capability_weight == 0`.	`None`
`income_floor`	`float`	Gini. Development threshold in USD PPP per capita. Income below this is excluded from capability calculations, adapted from GDR. Default: 0.0. See `docs/science/parameter-effects.md` §income_floor.	`0.0`
`max_gini_adjustment`	`float`	Gini. Maximum reduction factor from threshold deduction (0–1). Default: 0.8.	`0.8`
`max_deviation_sigma`	`float \| None`	Constraint. Maximum allowed deviation from equal per capita, in standard deviations. `None` (default) means no constraint.	`None`
`preserve_allocation_year_shares`	`bool`	Mode. If `False` (default), uses cumulative adjusted population from `allocation_year` onwards. If `True`, uses population at `allocation_year` only.	`False`
`historical_discount_rate`	`float`	Pre-allocation responsibility. Discount rate for historical emissions (0.0 to <1.0), via `(1 - rate)^(reference_year - t)` Default: 0.0. Only affects the pre-allocation responsibility calculation.	`0.0`
`cumulative_end_year`	`int \| None`	Upper bound of the cumulative window. `None` (default) uses the last year in the population data.	`None`
`group_level`	`str`	Index level name for grouping. Default: `'iso3c'`.	`'iso3c'`
`unit_level`	`str`	Index level name for units. Default: `'unit'`.	`'unit'`
`ur`	`PlainRegistry`	Pint unit registry for unit conversions.	`get_default_unit_registry()`

Returns:

Type	Description
`BudgetAllocationResult`	Container with relative shares for cumulative emissions budget allocation. The TimeseriesDataFrame contains only the allocation_year column with Gini-adjusted capability-weighted population shares that sum to 1 across groups for the specified emission category.

Notes

Theoretical grounding:

See docs/science/allocations.md#gini-adjustment for intra-national equity considerations. For implementation examples combining capability with subsistence protection, see docs/science/principle-to-code.md.

GDP window: When the allocation cumulative window extends past the last year of the input gdp_ts, the (Gini-adjusted) GDP per capita values from the last observed year are forward-filled to cover the full window. This preserves the cross-country capability ratios of the last observed year, but those ratios then get weighted against the full post-observation population trajectory. Users who want different post-observation capability dynamics (SSP2 projections, custom growth assumptions, or a future-extended WDI release) should extend the input gdp_ts time series before calling this function. Gini coefficients are looked up per-country and are not part of this forward-fill — only the GDP series is extended in time.

Budget Allocation Functions¶

Overview¶

Per Capita Budgets¶

equal_per_capita_budget¶

fair_shares.library.allocations.budgets.per_capita.equal_per_capita_budget ¶

per_capita_adjusted_budget¶

fair_shares.library.allocations.budgets.per_capita.per_capita_adjusted_budget ¶

per_capita_adjusted_gini_budget¶

fair_shares.library.allocations.budgets.per_capita.per_capita_adjusted_gini_budget ¶

See Also¶