Skip to content

iamc-regional-fair-shares

The 401_custom_iamc_allocation.ipynb notebook calculates fair share allocations for IAMC model regions and prepares remaining budgets for IAM model input.

For allocation examples without model preparation, see:

  • 402_example_iamc_budget_allocations.ipynb - Budget allocation examples
  • 403_example_iamc_pathway_allocations.ipynb - Pathway allocation examples

Use this workflow with IAMC-format scenario data (model, scenario, region, variable, year columns). For country-level allocations, use country-fair-shares.

Entry Points Framework

Fair share quantification involves five structured decision stages [Pelz 2025b]: (1) foundational principles, (2) allocation quantity, (3) allocation approach, (4) indicators, (5) implications for all others. The allocation approach and indicator choices made in this workflow (e.g., allocation_year, capability_weight, GDP measure) correspond to Entry Points 3 and 4. See From Principle to Code for the full framework.

Regions come from your data

The library uses whatever regions are in your IAMC input file. Whether you're using IMAGE, MESSAGEix, REMIND, or any other model's native regionalization, fair-shares adapts automatically. There are no fixed regional mappings to configure.

Data Requirements

IAMC Format

Your data should have columns:

Column Description
model Model name (e.g., "SSP_SSP2_v6.3_ES")
scenario Scenario name (e.g., "ECPC-2015-800Gt")
region Region identifier
variable Variable name
Year columns 1990, 1995, 2000, 2015, 2020, 2025, ...

Required Variables

Variable Purpose
Population Per capita calculations
GDP\|PPP Capability adjustments (optional)

An emissions variable is needed only if you're subtracting historical emissions to compute remaining budgets (see Preparing Remaining Budgets). The variable name is configurable -- use whatever your IAMC data provides.

Key Functions

Loading Data

Python
from fair_shares.library.utils.data.iamc import load_iamc_data

data = load_iamc_data(
    data_file="data/scenarios/iamc_example/iamc_reporting_example.xlsx",
    population_variable="Population",
    gdp_variable="GDP|PPP",
    regions=["AFR", "CHN", "EEU", "FSU", "LAM", "MEA", "NAM", "PAO", "PAS", "RCPA", "SAS", "WEU"],
    allocation_start_year=2015,
    budget_end_year=2100,
    expand_to_annual=True,  # Interpolate non-annual data
)

Equal Per Capita Allocation

Python
from fair_shares.library.allocations.budgets.per_capita import equal_per_capita_budget

# Extract dataframes from loaded data
population_ts = data["population"].rename_axis(index={"region": "iso3c"})

result = equal_per_capita_budget(
    population_ts=population_ts,
    allocation_year=2015,
    emission_category="all-ghg-ex-co2-lulucf",
    preserve_allocation_year_shares=False,
    group_level="iso3c",
)

shares = result.relative_shares_cumulative_emission["2015"]

Capability-Adjusted Allocation

Python
from fair_shares.library.allocations.budgets.per_capita import per_capita_adjusted_budget

# Extract dataframes from loaded data
population_ts = data["population"].rename_axis(index={"region": "iso3c"})
gdp_ts = data["gdp"].rename_axis(index={"region": "iso3c"})

result = per_capita_adjusted_budget(
    population_ts=population_ts,
    gdp_ts=gdp_ts,
    allocation_year=2015,
    emission_category="all-ghg-ex-co2-lulucf",
    capability_weight=1.0,
    pre_allocation_responsibility_weight=0.0,
    pre_allocation_responsibility_year=1990,
    preserve_allocation_year_shares=False,
    group_level="iso3c",
)

Capability-only is a minimal example

Setting pre_allocation_responsibility_weight=0.0 produces a capability-only configuration for illustration. When one weight is 0, the other is the sole adjustment — its specific value does not matter (only the ratio between weights affects results), so 1.0 is used for clarity. The normatively recommended configuration typically includes both responsibility and capability components — see Principle to Code for guidance.

Preparing Remaining Budgets for IAM Model Input

Use notebook 401 for model input preparation. Notebooks 402/403 show allocation examples only.

Understanding Timesteps vs Periods

IAM models often use timestep labels that represent multi-year periods. For example, in MESSAGEix, timestep 2030 represents 2026-2030, 2040 represents 2031-2040, etc.

Critical: Your remaining budget must start from the first year of the first period, not the timestep label.

Calculation Method

If allocating from 2015 and your first model period is 2026-2030:

Text Only
Remaining Budget (from 2026) = Fair Share Allocation (2015→) - Actual Emissions (2015-2025)

Steps:

  1. Run allocation from your allocation year (e.g., 2015)
  2. Subtract cumulative actual emissions from allocation year to (first period start - 1)
  3. Export remaining budget in Mt CO2e
  4. Use as cumulative emission constraint in your model (e.g., bound_emission in MESSAGEix)

Example Workflow in Notebook 401

See "Step 7: Prepare for IAM Model Input" in notebook 401 for:

  • Configuration cells for model timestep/period
  • Automated calculation of remaining budgets
  • Export in model-ready format

Important:

  • Emissions must be annual (use expand_to_annual=True when loading data)
  • Units should match your model (typically Mt CO2e)
  • Negative remaining budgets indicate the region has exceeded its allocation — see Negative Allocations below

Handling Model Timesteps

The notebook automatically handles different timestep patterns from IAMC models:

  • Annual data (2020, 2021, 2022, ...) - No interpolation needed
  • 5-year intervals (2020, 2025, 2030, ...) - Interpolates to annual when expand_to_annual=True
  • 10-year intervals (2020, 2030, 2040, ...) - Interpolates to annual when expand_to_annual=True
  • Mixed patterns - Handles non-uniform timesteps automatically

Negative Allocations

Under principled approaches (e.g., ECPC from 1990), some developed regions will have exhausted their fair share and will show negative remaining allocations. For example, EU27 has a negative remaining allocation as of 2023 under 1.5°C budgets [Pelz 2025b].

Negative allocations are a feature, not a bug — they underscore the importance of minimizing overshoot duration and magnitude [Pelz 2025a]. They signal:

  • Highest possible domestic ambition — emissions reductions should be as deep and fast as possible
  • Carbon Dioxide Removal (CDR) — negative allocations may call for net-negative targets in model runs
  • International support and cooperation — regions that have exceeded their share have corresponding obligations to support others

Do not interpret negative allocations as prescriptive about timing or mechanism — they provide versatility for how regions respond. Transparently communicate negative allocations rather than clipping to zero, as the signal is normatively meaningful [Pelz 2025a; Pelz 2025b].

See Also