er_model_core/metrics.py

"""
Carbon sequestration metrics calculations.
"""
from typing import Dict, List, Optional, Tuple

import numpy as np
import pandas as pd


def calculate_carbon(biomass: float, carbon_fraction: float, co2_conversion: float) -> float:
    """
    Convert biomass to carbon dioxide equivalent.
    
    Args:
        biomass: Total biomass in kg
        carbon_fraction: Fraction of biomass that is carbon
        co2_conversion: Conversion factor from C to CO2
        
    Returns:
        Carbon dioxide equivalent in tonnes
    """
    # Convert kg biomass to tonnes CO2
    carbon = biomass * carbon_fraction  # kg C
    co2 = carbon * co2_conversion  # kg CO2
    tonnes_co2 = co2 / 1000.0  # tonnes CO2
    
    return tonnes_co2


def calculate_milestone_metrics(
    carbon_series: pd.Series,
    milestones: List[int] = [5, 10, 15, 20, 25, 30]
) -> Dict[str, float]:
    """
    Calculate carbon metrics at milestone years.
    
    Args:
        carbon_series: Series of carbon values indexed by year
        milestones: List of milestone years to report
        
    Returns:
        Dictionary of milestone metrics
    """
    metrics = {}
    for year in milestones:
        if year in carbon_series.index:
            metrics[f"Year_{year}"] = carbon_series[year]
    return metrics


def calculate_per_hectare_metrics(
    carbon: float,
    area: float,
    buffer_pct: float = 0.0,
    leakage_pct: float = 0.0,
    baseline: float = 0.0
) -> Tuple[float, float]:
    """
    Calculate per-hectare carbon metrics with deductions.
    
    Args:
        carbon: Gross carbon in tCO2
        area: Area in hectares
        buffer_pct: Buffer pool percentage
        leakage_pct: Leakage percentage
        baseline: Baseline emissions in tCO2/ha/yr
        
    Returns:
        Tuple of (gross_per_ha, net_per_ha)
    """
    if area <= 0:
        return 0.0, 0.0
        
    gross_per_ha = carbon / area
    
    # Apply deductions
    net_carbon = carbon * (1 - buffer_pct/100) * (1 - leakage_pct/100)
    net_carbon -= baseline * area
    net_per_ha = max(0, net_carbon / area)
    
    return gross_per_ha, net_per_ha


def calculate_scenario_metrics(
    base_carbon: float,
    scenario_carbon: float,
    area: float
) -> Dict[str, float]:
    """
    Calculate comparison metrics between base and scenario.
    
    Args:
        base_carbon: Base scenario carbon in tCO2
        scenario_carbon: Alternative scenario carbon in tCO2
        area: Area in hectares
        
    Returns:
        Dictionary of comparison metrics
    """
    metrics = {
        "Absolute_Difference": scenario_carbon - base_carbon,
        "Percent_Difference": ((scenario_carbon - base_carbon) / base_carbon * 100 
                             if base_carbon > 0 else 0),
        "Per_Hectare_Difference": (scenario_carbon - base_carbon) / area if area > 0 else 0
    }
    return metrics