gcubed.projections.equivalent_variation

Adapt native projection levels and household parameters for lifetime EV.

FACTORS: tuple[str, ...] = ('k', 'l', 'e', 'm')

QUANTITIES: tuple[str, ...] = ('CNPK', 'CNPL', 'CNPE', 'CNPO')

INPUT_UNITS: dict[str, str] = {'CNPK': 'gdp', 'CNPL': 'gdp', 'CNPE': 'gdp', 'CNPO': 'gdp', 'SHYZ': 'pct', 'SHLZ': 'pct', 'SHEFC': 'pct', 'RISW': 'del', 'LGDPR': 'realusdbillion'}

FACTOR_VARIABLES: dict[str, str] = {'k': 'CNPK', 'l': 'CNPL', 'e': 'CNPE', 'm': 'CNPO'}

MONETARY_INPUT_UNITS: dict[str, str] = {'PRCT': 'idx', 'PRID': 'idx', 'INTR': 'pct'}

def equivalent_variation( reference_projections: Any, scenario_projections: Any, *, start_year: int, terminal_year: int | None = None, include_monetary: bool = False) -> pandas.DataFrame:

Return remaining-lifetime percentage EV for each native model region.

start_year is the valuation origin: its discount weight is one. The default terminal year is the last shared numerical observation, requiring matching ending years rather than silently truncating a longer path. Both arguments must supply database-level projections and matching calibrated household preferences. The returned DataFrame includes intermediate utility/discount diagnostics; it writes no files. With include_monetary=True, reference prices/rates reconstruct regional real-dollar compensation, detrended from the selected valuation year.

Raises EVInputError for incompatible models, unsupported units, missing observations, changed preferences, or invalid economic/numerical inputs.