Skip to content

Fair shares for IAM model regions

Use this workflow when your data is an IAMC-format scenario file (columns for model, scenario, region, variable, and one column per year) and you want to divide a budget or a pathway between that model's regions. For allocations to individual countries, use country-fair-shares instead.

Run the notebooks in this order

Step 1 — always run 400_data_preprocess_scenario_for_allocation.ipynb first. It reads a raw IAMC scenario file, prepends the historical emissions, population and GDP that an allocation needs, and writes output/iamc/iamc_covered.xlsx. Everything below reads that file.

To run it on your own scenario, edit the SCENARIO_FILE line near the top of notebook 400 to point at your file. Out of the box it points at the bundled MESSAGEix-GLOBIOM example. If you leave it, notebook 400 processes that example instead of your scenario and raises no error. Change the path before you run it.

Step 2 — pick the notebook that matches what you want:

Notebook What it does
402_example_iamc_budget_allocations.ipynb Worked budget examples — one cumulative number per region. Runs unchanged.
403_example_iamc_pathway_allocations.ipynb Worked pathway examples — a value per region per year. Runs unchanged.
401_custom_iamc_allocation.ipynb Blank workspace you configure yourself, plus export of a model-ready budget.

401, 402 and 403 will not run on their own

All three open output/iamc/iamc_covered.xlsx. That file does not exist in a fresh clone — notebook 400 creates it. If you see a missing-file error naming iamc_covered.xlsx, you have skipped step 1.

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 from allocation year onwards (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

The notebooks load the file notebook 400 produced. Read the region names out of the file rather than typing them — they are whatever your model calls them, and often carry a model prefix such as MESSAGEix-GLOBIOM 2.1-R12|Western Europe:

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

scenario = pyam.IamDataFrame("output/iamc/iamc_covered.xlsx")
regions = [r for r in scenario.region if r.lower() not in ("world", "global")]

data = load_iamc_data(
    data_file=scenario,
    population_variable="Population",
    gdp_variable="GDP|PPP",
    emissions_variable="Emissions|Covered",
    regions=regions,
    allocation_start_year=1990,
    budget_end_year=2100,
    expand_to_annual=True,  # Interpolate non-annual data
)

Emissions|Covered is the combined emissions variable notebook 400 builds.

Why not load the raw scenario file directly

You can point data_file at a raw IAMC file instead — the bundled example is data/scenarios/iamc_example/iamc_reporting_example.xlsx. But a raw file only holds the scenario's own years. That example starts in 2015, while the notebooks allocate from 1990 by default, so there would be no data for the first 25 years and the result would be wrong without any error being raised. Notebook 400 exists to prepend that history. Use its output unless you are certain your allocation never reaches back before your scenario starts.

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