Adding Allocation Approaches

This guide explains how to add new allocation approaches to fair-shares.

---

Overview

Allocation approaches live in two directories:

Type	Location	Output
Budget	allocations/budgets/	Single cumulative allocation
Pathway	allocations/pathways/	Time-varying annual allocations

Each approach is registered in allocations/registry.py.

---

Before You Begin

Every allocation approach operationalizes specific equity principles. Before writing code, you should be able to explain:

1. What equity principle(s) it implements
2. What value judgments are embedded
3. How it relates to existing approaches

If unclear, read Principle-to-Code first.

Value neutrality

Do not present the approach as value-neutral — all allocation choices embed normative judgments [Dooley 2021; Kartha 2018].

Use the Entry Points Framework to structure your normative documentation: (1) foundational principles, (2) allocation quantity, (3) allocation approach, (4) indicators, (5) implications for all others [Pelz 2025b]. See From Principle to Code.

Grandfathering

Grandfathering-based allocation — assigning shares proportional to current emissions — has no support in the equity literature and contradicts the normative foundations of this project [Dooley 2021; Kartha 2018]. Contraction-and-convergence approaches that begin from current national emissions levels embed grandfathering during the convergence period and should be treated with the same caution [Kartha 2018]. New approaches should be grounded in defensible equity principles documented in From Principle to Code.

---

Contribution Workflow

flowchart LR
    A[Identify Principles] --> B[Implement Function]
    B --> C[Add Tests]
    C --> D[Register]
    D --> E[Update Docs if Needed]

Key principles:

1. Know your principles first - You should be able to explain what equity principle the approach implements before writing code
2. Docstrings include math - Document the mathematical foundation in the docstring (see existing approaches for examples)
3. Tests validate behavior - Tests should verify both correctness and that parameters have expected effects
4. Registration makes it discoverable - Until registered, the approach cannot be used via the high-level API

---

Step 1: Understand the Pattern

Function Signature

All allocation functions follow a consistent pattern:

Python

def my_new_budget(
    # Required data
    population_ts: TimeseriesDataFrame,
    allocation_year: int,
    emission_category: str,
    # Optional data (for adjustments)
    country_actual_emissions_ts: TimeseriesDataFrame | None = None,
    gdp_ts: TimeseriesDataFrame | None = None,
    # Parameters specific to this approach
    my_parameter: float = 0.5,
    # Common parameters
    group_level: str = "iso3c",
    unit_level: str = "unit",
) -> BudgetAllocationResult:
    """Docstring with academic context."""
    ...

Required Return Type

• Budget approaches: BudgetAllocationResult
• Pathway approaches: PathwayAllocationResult

Both are dataclasses in allocations/results/.

---

Step 2: Implement the Function

Budget Example

Create a new file or add to existing module in allocations/budgets/:

Python

"""My new allocation approach."""

from fair_shares.library.allocations.results import BudgetAllocationResult
from fair_shares.library.validation.models import AllocationInputs, AllocationOutputs


def my_new_budget(
    population_ts,
    allocation_year: int,
    emission_category: str,
    my_parameter: float = 0.5,
    group_level: str = "iso3c",
    unit_level: str = "unit",
) -> BudgetAllocationResult:
    """
    Allocate budget using my new approach.

    This approach does X based on principle Y from Author (Year).

    Parameters
    ----------
    population_ts : TimeseriesDataFrame
        Population data with MultiIndex (iso3c, unit)
    allocation_year : int
        Year when allocation begins
    emission_category : str
        Emission category being allocated
    my_parameter : float, default 0.5
        Controls strength of adjustment

    Returns
    -------
    BudgetAllocationResult
        Contains relative_shares_cumulative_emission

    See Also
    --------
    docs/science/allocations.md : Theoretical grounding
    """
    # Validate inputs
    AllocationInputs(
        population_ts=population_ts,
        first_allocation_year=allocation_year,
        last_allocation_year=allocation_year,
    )

    # Calculate shares (must sum to 1)
    # ... your implementation ...

    relative_shares = calculate_shares(population_ts, allocation_year, my_parameter)

    # Validate outputs
    AllocationOutputs(
        shares=relative_shares,
        dataset_name="my-new-budget allocation",
    )

    # Return result
    return BudgetAllocationResult(
        approach="my-new-budget",
        relative_shares_cumulative_emission=relative_shares,
        parameters={
            "allocation_year": allocation_year,
            "my_parameter": my_parameter,
        },
    )

Key Implementation Details

1. Validate inputs using AllocationInputs Pydantic model
2. Shares must sum to 1 for each group (e.g., climate-assessment, quantile)
3. Validate outputs using AllocationOutputs model
4. Document thoroughly with academic citations (see Docstring Template for required structure)

---

Step 3: Export the Function

Add to the module's __init__.py:

Python

# allocations/budgets/__init__.py
from fair_shares.library.allocations.budgets.my_module import my_new_budget

__all__ = [
    "equal_per_capita_budget",
    "per_capita_adjusted_budget",
    "per_capita_adjusted_gini_budget",
    "my_new_budget",  # Add here
]

---

Step 4: Register the Approach

Add to allocations/registry.py:

Python

from fair_shares.library.allocations.budgets import (
    # ... existing imports ...
    my_new_budget,
)

def get_allocation_functions() -> dict[str, Callable[..., Any]]:
    return {
        # ... existing approaches ...
        "my-new-budget": my_new_budget,
    }

---

Step 5: Add Tests

Create tests in tests/unit/allocations/:

Python

from fair_shares.library.utils import create_example_data


def test_my_new_budget_basic():
    """Test basic functionality."""
    data = create_example_data()
    result = my_new_budget(
        population_ts=data["population"],
        allocation_year=2020,
        emission_category="co2-ffi",
    )

    # Shares sum to 1
    shares = result.relative_shares_cumulative_emission["2020"]
    assert abs(shares.sum() - 1.0) < 1e-10

    # Result type
    assert result.approach == "my-new-budget"


def test_my_new_budget_parameter_effect():
    """Test that parameter has expected effect."""
    data = create_example_data()
    result_low = my_new_budget(
        population_ts=data["population"],
        allocation_year=2020,
        emission_category="co2-ffi",
        my_parameter=0.0,
    )
    result_high = my_new_budget(
        population_ts=data["population"],
        allocation_year=2020,
        emission_category="co2-ffi",
        my_parameter=1.0,
    )

    # Verify parameter affects results as expected
    assert result_low.approach == "my-new-budget"
    assert result_high.approach == "my-new-budget"

Key test assertions:

• Shares sum to 1.0: abs(shares.sum() - 1.0) < 1e-10
• Approach name matches registry key
• Parameters stored in result object

---

Step 6: Document

1. Docstring - See Docstring Template for required sections
2. Science docs - Add to docs/science/allocations.md if introducing new principle
3. API docs - Auto-generated from docstrings

Please consider the following:

• Explicit statement or link to documentation regarding normative foundations
• Indicator choices and justifications
• Implications for all parties, not just a focus country

---

Existing Implementations as Examples

Approach	File	Good Example Of
equal_per_capita_budget	budgets/per_capita.py	Simple budget allocation
per_capita_adjusted_budget	budgets/per_capita.py	Multiple adjustments
cumulative_per_capita_convergence	pathways/cumulative_per_capita_convergence.py	Complex pathway allocation

---

Common Utilities

Utility	Purpose
filter_time_columns()	Extract year columns from DataFrame
calculate_relative_adjustment()	Compute pre-allocation responsibility/capability adjustments
apply_deviation_constraint()	Limit extreme allocations
validate_weight_constraints()	Check weights sum correctly

See Utils API for full documentation.

---

Before Merging

Bash

uv run pytest tests/ -v                    # Run tests
uv run ruff check src/ tests/              # Lint
uv run ruff format src/ tests/             # Format
uv run mkdocs build --strict               # Check docs build

Common issues:

• Shares don't sum to 1.0 — Check for division by zero or NaN values
• Missing year columns — Use ensure_string_year_columns() on input DataFrames