API reference¶

__all__ = [
    "CATALOGUE",
    "COMPATIBILITY",
    "CONST_DISC_RATES",
    "DEFAULT_SAVE_FILES",
    "DISCOUNT_TYPES",
    "EXTRA_SAVE_FILES",
    "FAIR_AGGREGATIONS",
    "FORMULAS",
    "KNOWN_ECS_MASKS",
    "MODES",
    "PIPELINE",
    "RECIPES",
    "REDUCTIONS",
    "REQUIRED",
    "STATUSES",
    "Combination",
    "Option",
    "Stage",
    "Value",
    "option",
]

REQUIRED = _Required()

STATUSES = ('supported', 'unsupported', 'dead', 'removed')

MODES = ('ssp', 'rff')

FORMULAS = (
    "damages ~ -1 + np.power(anomaly, 2)",
    "damages ~ gmsl + np.power(gmsl, 2)",
    "damages ~ -1 + gmsl + np.power(gmsl, 2)",
    "damages ~ -1 + gmsl",
    "damages ~ anomaly + np.power(anomaly, 2)",
    "damages ~ -1 + anomaly + np.power(anomaly, 2)",
    "damages ~ -1 + gmsl + anomaly + np.power(anomaly, 2)",
    "damages ~ -1 + anomaly + np.power(anomaly, 2) + gmsl + np.power(gmsl, 2)",
    "damages ~ -1 + anomaly * gmsl + anomaly * np.power(gmsl, 2) + gmsl * np.power(anomaly, 2) + np.power(anomaly, 2) * np.power(gmsl, 2)",
    "damages ~ anomaly + np.power(anomaly, 2) + gmsl + np.power(gmsl, 2)",
    "damages ~ -1 + anomaly:gmsl + anomaly:np.power(gmsl, 2) + gmsl:np.power(anomaly, 2) + np.power(anomaly, 2):np.power(gmsl, 2)",
    "damages ~ -1 + gmsl:anomaly + gmsl:np.power(anomaly, 2)",
)

DISCOUNT_TYPES = (
    "constant",
    "constant_model_collapsed",
    "constant_gwr",
    "naive_ramsey",
    "euler_ramsey",
    "naive_gwr",
    "gwr_gwr",
    "euler_gwr",
)

CONST_DISC_RATES = (0.01, 0.015, 0.02, 0.025, 0.03, 0.05)

DEFAULT_SAVE_FILES = (
    "damage_function_points",
    "damage_function_coefficients",
    "damage_function_fit",
    "marginal_damages",
    "discount_factors",
    "uncollapsed_sccs",
    "scc",
    "uncollapsed_discount_factors",
    "uncollapsed_marginal_damages",
    "global_consumption",
    "global_consumption_no_pulse",
)

EXTRA_SAVE_FILES = (
    "ce_fair_pulse",
    "ce_fair_no_pulse",
    "global_consumption_pulse",
    "stat_uncertainty_iqr",
    "full_uncertainty_iqr",
)

FAIR_AGGREGATIONS = ('ce', 'mean', 'gwr_mean', 'median', 'median_params')

RECIPES = ('adding_up', 'risk_aversion', 'equity')

REDUCTIONS = ('cc', 'no_cc')

KNOWN_ECS_MASKS = (
    "truncate_at_ecs995symmetric_passing_mask",
    "truncate_at_ecs990symmetric_passing_mask",
    "truncate_at_ecs950symmetric_passing_mask",
    "truncate_at_ecs830symmetric_passing_mask",
    "truncate_at_ecs750symmetric_passing_mask",
)

PIPELINE: tuple[Stage, ...] = (
    Stage(
        name="sum-sectors",
        summary="Sum member sectors' delta and histclim into an aggregate sector zarr (e.g. AMEL from agriculture+mortality+energy+labor).",
        consumes=("member sector damages zarrs (sectors.<name>.sector_path)",),
        produces=("aggregate sector damages zarr (its sector_path)",),
        collapses=(
            "no collapse: sums variables across sectors at identical dimensions (preprocessing.py sum_AMEL)",
        ),
        modes=("ssp",),
        library_call="dscim.preprocessing.preprocessing.sum_AMEL",
    ),
    Stage(
        name="reduce",
        summary="Collapse the batch dimension of sector damages against socioeconomics, producing the reduced-damage zarrs runs consume.",
        consumes=("sector damages zarrs (batch chunked at 15)", "econ zarr (external)"),
        produces=(
            "reduced zarrs: adding_up_{cc,no_cc}.zarr and risk_aversion_{cc,no_cc}_eta{eta}.zarr per sector",
        ),
        collapses=(
            "batch: mean for adding_up, certainty equivalent at eta for risk_aversion (preprocessing.py ce_from_chunk)",
        ),
        modes=("ssp",),
        library_call="dscim.preprocessing.preprocessing.reduce_damages",
    ),
    Stage(
        name="run",
        summary="Execute menu runs: fit damage functions (or load precomputed coefficients), apply FaIR, discount, and write SCC artifacts.",
        consumes=(
            "reduced zarrs (sectors without damage_function_path; ssp only)",
            "damage-function coefficient nc4s (sectors with damage_function_path; all rff sectors)",
            "climate files: gmst/gmsl fitting inputs, FaIR control/pulse, pulse conversion (external)",
            "econ zarr or rff socioeconomics nc4 (external)",
        ),
        produces=(
            "per-run artifacts named {recipe}_{discounting}_eta{eta}_rho{rho}_{artifact} under the save path",
        ),
        collapses=(
            "ssp and model: collapsed when discounting contains gwr (pooled damage-function fit, pop.mean(['model','ssp']); main_recipe.py collapsed_pop and damage_function_calculation)",
            "fair_dims (default [simulation]): collapsed by the FaIR aggregations ce/mean/median (main_recipe.py marginal_damages)",
            "discrate: a new dimension added by constant discounting, one entry per CONST_DISC_RATES value (main_recipe.py discounted_damages)",
            "rff mode: runid (10,000 draws) replaces gcm/rcp/ssp/model as the uncertainty dimensions; the ssp/model collapse happened upstream in the emulator weights (utils/rff.py weight_df; utils/menu_runs.py run_rff)",
        ),
        library_call="dscim MENU_OPTIONS[recipe](**kwargs).order_plate(order)",
    ),
    Stage(
        name="combine",
        summary="Merge coastal and AMEL damage-function coefficients into the combined (CAMEL) sector's coefficient files.",
        consumes=("coastal and AMEL coefficient nc4s written by run (fit sectors)",),
        produces=("combined-sector coefficient (and optionally fit) nc4s",),
        collapses=(
            "no collapse: concatenates coefficient variables from the two sources (midprocessing.py combine_CAMEL_coefs)",
        ),
        modes=("ssp",),
        library_call="dscim.preprocessing.midprocessing.combine_CAMEL_coefs",
    ),
    Stage(
        name="scc",
        summary="Compose SCCs from the uncollapsed run outputs: sum marginal damages times discount factors over years, deflate, and collapse the uncertainty dimension.",
        consumes=(
            "uncollapsed_marginal_damages and uncollapsed_discount_factors nc4s written by run",
        ),
        produces=("SCC files under scc.output",),
        collapses=(
            "year: summed out by the present-value integration (dscim-facts-epa scghg_utils.py:335-337)",
            "runid (rff) or the fair dims (ssp): collapsed per scc.collapse: mean, certainty_equivalent (adjustment factor (gcnp/pop)^(-eta) normalized at the pulse year, scghg_utils.py:352-357), or none",
        ),
    ),
)

CATALOGUE: dict[str, Option] = {opt.name: opt for opt in _OPTIONS}

COMPATIBILITY: tuple[Combination, ...] = (
    Combination(
        key="median-params-fair-dims",
        options=("fair_aggregation", "fair_dims"),
        kind="requires",
        description="fair_aggregation containing median_params requires fair_dims to be exactly [simulation]; dscim documents this and does not enforce it.",
        citation="main_recipe.py:47 (docstring); no matching assert in __init__",
    ),
    Combination(
        key="clip-gmsl-formula",
        options=("clip_gmsl", "formula"),
        kind="requires",
        description="clip_gmsl requires the formula to be one of the two gmsl-quadratic formulas.",
        citation="main_recipe.py:264-270 (assert)",
    ),
    Combination(
        key="equity-not-reduced",
        options=("recipe",),
        kind="forbidden",
        description="reduce.recipes may not include equity: reduce_damages has no equity branch, and the equity recipe reads risk_aversion reduced damages. Add risk_aversion to reduce.recipes instead.",
        citation="preprocessing.py (ce_from_chunk has adding_up and risk_aversion branches only); equity.py reads risk_aversion CEs",
        modes=("ssp",),
    ),
    Combination(
        key="rff-emission-scenarios-null",
        options=("emission_scenarios",),
        kind="requires",
        description="rff mode requires climate.emission_scenarios to be null so the rcp selection is skipped on runid-shaped FaIR files.",
        citation="simple_storage.py:58 docstring",
        modes=("rff",),
    ),
    Combination(
        key="rff-coefficients-required",
        options=("damage_function_path",),
        kind="requires",
        description="rff mode requires damage_function_path on every swept sector: ce_path is None in rff runs, so fitting is impossible and coefficients must be precomputed.",
        citation="utils/menu_runs.py:163-167 (run_rff)",
        modes=("rff",),
    ),
    Combination(
        key="rff-no-masks-or-fair-dims",
        options=("ecs_mask_name", "fair_dims"),
        kind="forbidden",
        description="sweep.masks and sweep.fair_dims are not available in rff mode; run_rff has no such parameters and forces the mask off.",
        citation="utils/menu_runs.py:119-127,169-170",
        modes=("rff",),
    ),
    Combination(
        key="ssp-gmst-path-required",
        options=("gmst_path",),
        kind="requires",
        description="ssp mode requires a non-empty climate.gmst_path: damage points are merged with the GMST anomalies during fitting.",
        citation="main_recipe.py damage_function_points (gmst merge)",
        modes=("ssp",),
    ),
    Combination(
        key="gmsl-formula-needs-gmsl-paths",
        options=("formula", "gmsl_path", "gmsl_fair_path"),
        kind="requires",
        description="a swept sector whose formula contains gmsl requires climate.gmsl_path (ssp fitting) and climate.gmsl_fair_path.",
        citation="main_recipe.py (gmsl merge keyed on slr/gmsl columns); simple_storage.py:54 (anomaly_vars gate)",
    ),
    Combination(
        key="quantreg-lengths",
        options=("quantreg_quantiles", "quantreg_weights"),
        kind="requires",
        description="quantreg_quantiles and quantreg_weights must have equal length (dscim asserts this even though the weights are otherwise unused).",
        citation="main_recipe.py:241-243",
    ),
)

__all__ = [
    "COMBINATION_CHECKERS",
    "ConfigError",
    "Input",
    "PlanStep",
    "Run",
    "apply_overrides",
    "apply_selectors",
    "config_provenance",
    "effective_settings",
    "expand_sweep",
    "load_config",
    "plan_steps",
    "render_plan",
    "render_summary",
    "resolved_config",
    "run_inputs",
    "run_outputs",
    "save_path_for",
    "settings_summary",
    "summary_data",
    "validate_config",
]

TOP_LEVEL_KEYS = (
    "mode",
    "climate",
    "econ",
    "paths",
    "aggregates",
    "sectors",
    "menu",
    "sweep",
    "reduce",
    "combine",
    "scc",
)

MENU_KEYS = (
    "fit_type",
    "discrete_discounting",
    "fair_aggregation",
    "weitzman_parameter",
    "subset_dict",
    "ext_method",
    "ext_subset_start_year",
    "ext_subset_end_year",
    "ext_end_year",
    "clip_gmsl",
    "scenario_dimensions",
    "save_files",
    "filename_suffix",
    "full_uncertainty_quantiles",
    "quantreg_quantiles",
    "quantreg_weights",
)

CLIMATE_KEYS = (
    "gases",
    "gas_conversions",
    "gmst_path",
    "gmsl_path",
    "gmst_fair_path",
    "gmsl_fair_path",
    "damages_pulse_conversion_path",
    "ecs_mask_path",
    "emission_scenarios",
    "base_period",
)

SAVABLE = DEFAULT_SAVE_FILES + EXTRA_SAVE_FILES

SCC_COLLAPSES = ('certainty_equivalent', 'mean', 'none')

EXTERNAL = ''

COMBINATION_CHECKERS = {
    "median-params-fair-dims": _check_median_params_fair_dims,
    "clip-gmsl-formula": _check_clip_gmsl_formula,
    "equity-not-reduced": _check_equity_not_reduced,
    "rff-emission-scenarios-null": _check_rff_emission_scenarios,
    "rff-coefficients-required": _check_rff_coefficients,
    "rff-no-masks-or-fair-dims": _check_rff_no_masks,
    "ssp-gmst-path-required": _check_ssp_gmst_path,
    "gmsl-formula-needs-gmsl-paths": _check_gmsl_paths,
    "quantreg-lengths": _check_quantreg_lengths,
}

SCC_KEYS = ('deflator', 'collapse', 'output', 'damages_from', 'discounting_from')

OPTION_LOCATIONS = {
    **{key: ("menu", key) for key in MENU_KEYS},
    **{key: ("climate", key) for key in CLIMATE_KEYS},
    "path_econ": ("econ", "path"),
    "order": (None, "order"),
    "ce_path": ("paths", "reduced_damages_library"),
    "damage_function_path": ("sectors", None),
    "reduction": ("reduce", "reductions"),
}

SWEEP_OPTIONS = {
    "sector": "sectors",
    "pulse_year": "pulse_years",
    "recipe": "menu_pairs",
    "discounting_type": "menu_pairs",
    "eta": "eta_rho",
    "rho": "eta_rho",
    "ecs_mask_name": "masks",
    "fair_dims": "fair_dims",
}

SUMMARY_OPTIONS = (
    "eta",
    "rho",
    "recipe",
    "discounting_type",
    "sector",
    "pulse_year",
    "fit_type",
    "fair_aggregation",
    "weitzman_parameter",
    "discrete_discounting",
    "ext_method",
    "gases",
)

__all__ = [
    "TESTED_DSCIM_COMMIT",
    "PreflightError",
    "build_kwargs",
    "combine_all",
    "execute",
    "preflight",
    "reduce_all",
    "sum_sectors",
]

TESTED_DSCIM_COMMIT = '6a1f4d7e'

logger = logging.getLogger(__name__)

MENU = {
    "adding_up": dscim.menu.baseline.Baseline,
    "risk_aversion": dscim.menu.risk_aversion.RiskAversionRecipe,
    "equity": dscim.menu.equity.EquityRecipe,
}

__all__ = ['compose']

__all__ = ['main']

ACCENT = 'yellow'