Skip to content

country-fair-shares

The 301_custom_fair_share_allocation.ipynb notebook calculates fair share allocations for individual countries.

Workflow

graph LR
    A[1. Data Sources] --> B[2. Approaches]
    B --> C[3. Pipeline]
    C --> D[4. Allocations]
    D --> E[5. Results]
Step Action
Data Sources Select emissions, population, GDP datasets
Approaches Configure allocation approach parameters
Pipeline Run data preprocessing (automated)
Allocations Calculate country shares
Results Export to Parquet/CSV

Step 1: Data Sources

Emission Category

Category Description Notes
co2-ffi (default) CO₂ from fossil fuels and industry
all-ghg-ex-co2-lulucf All GHGs excluding CO₂ from land use GWP100 AR6 values; avoids LULUCF measurement uncertainty
all-ghg All greenhouse gases including LULUCF GWP100 AR6 values

Target Source

Source Allocation Functions Description
rcbs Budget approaches Remaining Carbon Budgets -- single cumulative value per country
pathway Pathway approaches Scenario pathways (e.g. IPCC AR6) -- allocate existing scenario pathways
rcb-pathways Pathway approaches RCB to global pathway, then allocated annually using pathway approaches

Supporting Data

Data Type Purpose
emissions Historical emissions for pre-allocation responsibility calculations
population Per capita calculations
gdp Capability-based adjustments
gini Within-country inequality adjustments

Available sources are configured in conf/data_sources/.

Entry Points Framework

Before configuring approaches and parameters, it helps to work through the five entry points for fair share quantification [Pelz 2025b]: (1) foundational principles, (2) allocation quantity, (3) allocation approach, (4) indicators, (5) implications for all others. See From Principle to Code for details.

Step 2: Allocation Approaches

Budget Approaches (for target="rcbs")

Approach Description
equal-per-capita-budget Equal share per person
per-capita-adjusted-budget Adjusted for pre-allocation responsibility and capability
per-capita-adjusted-gini-budget Further adjusted for within-country inequality

Pathway Approaches (for target="pathway" or target="rcb-pathways")

Approach Description
equal-per-capita Equal share per person per year
per-capita-adjusted Adjusted for pre-allocation responsibility and capability
per-capita-adjusted-gini Further adjusted for within-country inequality
per-capita-convergence Transition from current emissions to equal per capita (comparison only — convergence from current levels embeds implicit grandfathering during the transition period [Kartha 2018])
cumulative-per-capita-convergence Budget-preserving transition from current emissions to cumulative targets
cumulative-per-capita-convergence-adjusted Cumulative convergence with pre-allocation responsibility and capability adjustments
cumulative-per-capita-convergence-gini-adjusted Cumulative convergence accounting for intra-national inequality

For detailed explanations, see Allocation Approaches.

Step 3: Data Pipeline

The pipeline runs automatically when you execute the Step 3 cell. It:

  1. Validates your configuration
  2. Loads raw data files
  3. Processes emissions, GDP, population data
  4. Prepares target scenarios or budgets
  5. Saves processed files for allocation

Processing typically takes 1-3 minutes depending on data sources.

Step 4: Run Allocations

The allocation step:

  1. Loads processed data from the pipeline
  2. Runs each approach with all parameter combinations
  3. Calculates relative shares (summing to 1)
  4. Computes absolute emissions (Mt CO2e)
  5. Saves results to parquet and CSV

Step 5: Explore Results

Output Files

Results are saved to output/{source_id}/allocations/{allocation_folder}/:

File Format Description
allocations_relative.parquet Parquet Relative shares (0-1)
allocations_absolute.parquet Parquet Absolute emissions (Mt CO2e)
allocations_wide.csv CSV Wide format for spreadsheets
param_manifest.csv CSV All parameter combinations

Output Types

  • Relative shares: Country fractions summing to 1.0 per year
  • Absolute emissions: Relative share × global target in physical units

Negative allocations under principled approaches

Under approaches like ECPC from 1990, some developed regions have already exhausted their fair share and will show negative remaining allocations. This is a feature, not a bug — it signals the need for maximum domestic ambition and active support for international cooperation to compensate for past overshoot.

Comparing Approaches

To compare multiple allocation approaches:

Python
allocations = {
    "equal-per-capita-budget": [
        {"allocation_year": [2020], "preserve_allocation_year_shares": [False]}
    ],
    "per-capita-adjusted-budget": [
        {
            "allocation_year": [2020],
            "preserve_allocation_year_shares": [False],
            "pre_allocation_responsibility_weight": [0.5],
            "capability_weight": [0.5],
        }
    ],
}

Illustrative parameters only

The per-capita-adjusted-budget entry above shows the config structure, not a complete parameter set. For full worked examples with all adjustment parameters, see From Principle to Code.

Both approaches run in a single pipeline execution. Results include an approach column for filtering.

Reference Notebooks

Notebook Purpose
302_example_templates_budget_allocations.py Budget allocation examples
303_example_templates_pathway_allocations.py Pathway allocation examples

See Also