Skip to content

ClimAID v2 API

Under testing

The v2 API is under active testing and may still change before a stable release.

DiseaseModel.forecast_v2

Run the new leakage-safe probabilistic ClimAID v2 engine.

calibrate_intervals : bool, default True Widen (or narrow) each model's forecast intervals, per lead-time band, so they would have reached their stated coverage in the rolling hindcasts (split-conformal; see forecasting_v2/calibration.py). Requires run_hindcasts=True. tuning : {"fast", "balanced", "deep"} or int, default None (= "balanced") Hyperparameter tuning for every ML model is compulsory; this sets how much effort to spend (10 / 30 / 80 Optuna trials per model, or a custom number). Tuning uses time-ordered cross-validation inside the training period only, and hindcasts re-tune at each origin.

drop_2020 : bool, default True Treat 2020 disease counts in the training history as unreliable (COVID-19 disruption to reporting and care-seeking) and replace each 2020 month with the median of that calendar month across the other training years. Rows are replaced rather than deleted because the seasonal-naive, renewal and lagged ML models all need an unbroken monthly series. Only history at or before the forecast origin is changed; observed 2020 values after the origin are left intact for evaluation. The substitution is recorded in the report warnings. exclude_period : "2020", "none", "YYYY-MM:YYYY-MM" or (start, end), optional Disrupted period to exclude (e.g. COVID-19). Default: 2020 (via drop_2020). A custom period covers whole months, inclusive. Takes precedence over drop_2020.

This method is intentionally additive: none of the original ClimAID v1 methods, supported model registry entries, CMIP6 projection methods, DiseaseProjection API, or deterministic C-DSI reporting are removed.

DiseaseModel.project_v2

Hybrid ClimAID v2 climate-scenario outlook.

Near-term v2 probabilistic forecast (recent cases + each climate model's bias-corrected climate), handed over to CMIP6-driven scenario projections for every climate model x SSP, with ranges pooled across climate models.

Parameters:

Name Type Description Default
forecast_origin date
last disease observation
end_year int
2050
ssps optional lists to restrict scenarios / climate models
None
gcms optional lists to restrict scenarios / climate models
None
projection DataFrame

CMIP6-style table (time, model, ssp, climate variables). Defaults to the projections DiseaseModel loaded for this district (df_climate_proj).

None
near_term_months int

Months taken from the near-term forecast, then months of linear hand-over.

12
blend_months int

Months taken from the near-term forecast, then months of linear hand-over.

12
response (seasonal, anomaly)

How the long-term model identifies climate effects. "seasonal" learns them from the seasonal cycle (assumes seasonality is largely climate driven); "anomaly" only from year-to-year deviations (conservative).

"seasonal"
sensitivity bool

Also run the other response mode (long-term only) and report the difference, so readers can see how much conclusions depend on it.

True
drop_2020 bool

Replace 2020 in the near-term history with monthly medians and exclude it from the long-term model fit (COVID-19 reporting disruption).

True
exclude_period (2020, none, 'YYYY-MM:YYYY-MM' or (start, end))

Disrupted period to exclude (e.g. COVID-19). Default: 2020 (via drop_2020). A custom period covers whole months, inclusive. Takes precedence over drop_2020.

None
lag_selection (ensemble, auto, v1, all)

Climate lags for the long-term model. "ensemble" (default) averages all lag structures that cross-validate within 2% of the best, because climate variables sharing a seasonal cycle usually cannot be told apart and imply different warming responses. "v1" reuses the lags selected by optimize_lags() in the chosen v1_mode (Fast/Balanced/Deep, default from tuning), run on data up to the forecast origin; "auto" keeps only the single best structure; "all" uses lags 0-3 for every variable.

"ensemble"
extra_districts list of DiseaseModel or (disease, climate) pairs

Learn the climate response jointly with other districts (shared climate coefficients, own intercepts). Separates climate variables whose seasonal cycles coincide in this district but not elsewhere.

None
temperature_curve str or (T_min, T_opt, T_max)

Constrain the temperature response to a thermal-suitability curve (e.g. "aedes_aegypti_mordecai2017", values from Mordecai et al. 2017).

None
population_projection DataFrame(year, population[, ssp])

Also report results scaled by projected population (constant incidence per person). Climate-only results are always reported.

None
run_backtest bool

Refit on data up to backtest_years before the end of the record and check the long-term model against the held-out years' observed cases.

True

Forecasting engine

Climate-mandatory probabilistic disease forecaster.

Parameters:

Name Type Description Default
models iterable[str]

Any combination of seasonal_naive, renewal, sarimax, v1_stack and all model names available in the original ClimAID registry.

('seasonal_naive', 'renewal', 'random_forest')
population_at_risk float

Used by the renewal component only when the disease data do not contain a population column. If omitted, renewal falls back to relative-incidence mode and records that susceptible depletion was unavailable.

None

fit(disease, climate, cutoff=None)

predict(future_climate, horizon, n_simulations=2000)

evaluate(observed, bundle)

available_models() staticmethod

evaluate(disease, climate, models=('seasonal_naive', 'renewal', 'random_forest'), population_at_risk=None, renewal_kwargs=None, n_simulations=1000, score_exclude_times=(), tuning=None)

Run rolling-origin hindcasts and score them.

ROBUSTNESS FIX: this used to wrap each fold in a bare except Exception: continue and silently skip folds whose post-origin climate was shorter than the horizon. If every fold failed (bad climate columns, a model error, too-short climate), the caller got an empty table and the report said "no hindcast scores were available", hiding the actual cause. Now every skipped fold is recorded in self.skipped_origins_ (origin + reason), partial failures raise a RuntimeWarning, and if no fold succeeds a RuntimeError listing the reasons is raised, so callers (e.g. DiseaseModel.forecast_v2) can surface it.

Scenario outlook

project(disease, climate_hist, projection, origin, end_year=2050, ssps=None, gcms=None, exclude_times=(), peak_months=None, extra_districts=None, population_projection=None, baseline_population=None)

extra_districts : optional list/dict of (disease, climate) for other districts. When given, the long-term climate response is learned jointly across districts (shared coefficients, own intercepts), which separates climate variables whose seasonal cycles coincide in one place but not in others.

backtest(disease, climate_hist, test_years=5, exclude_times=(), extra_districts=None)

Check the long-term climate response on years it has not seen.

Refits everything (lag selection, bootstrap) on data up to test_years before the end of the record, then "projects" the held-out years using their observed climate, exactly as future scenarios are projected. Returns a per-year table (observed vs projected annual cases with 80% range) and a summary including a comparison with simply repeating the training-period mean.

Unimodal suitability in [0, 1]: 0 at/below T_min and at/above T_max, 1 at T_opt, asymmetric parabola on each side.

This constrains the shape of the temperature response (an optimum and a decline beyond it); the model still estimates how strongly suitability affects cases. It is not a re-implementation of any published R0(T) model, and monthly mean temperatures smooth out daily extremes.

Interval calibration

Recalibrate forecast intervals from rolling hindcasts.

Problem

v2 intervals were too narrow: in a Pune dengue run the ensemble's 95% intervals contained only 58% of hindcast months. Intervals built from in-sample residuals or simulation noise miss model error and grow too slowly with lead time.

Method (split-conformal, per lead-time band)

For each model and each central interval (50/80/90/95%), every hindcast month gets a normalised miss score

r = (y - median) / (q_upper - median)    if y >= median
r = (median - y) / (median - q_lower)    otherwise

so r <= 1 means the observation fell inside the original interval. The calibration factor k is the conformal quantile of r at the nominal level, i.e. the smallest multiple of each half-width that would have contained that share of hindcast outcomes. Quantiles are then rescaled about the median: q' = median + k (q - median). k > 1 widens, k < 1 narrows.

Factors are estimated separately for lead-time bands because errors grow with lead time. A band with fewer than min_points hindcast months uses the factor pooled across all bands; lead times beyond any hindcast use the longest available band, which is reported as a warning because uncertainty there is extrapolated.

fit_interval_calibration(hindcast_forecasts, observed, exclude_times=(), min_points=8, shrink=20)

Return {model: {"bands": {band: {level: k}}, "pooled": {level: k}, "n": {band: n}, "max_lead": int}} estimated from hindcast forecasts (columns time, origin, model, q025..q975) and observed cases.

apply_interval_calibration(frame, cal, origin)

Rescale a forecast frame's quantiles about the median using cal (one model's entry from fit_interval_calibration).

Tuning and model catalogue

Model catalogue and compulsory, leakage-safe hyperparameter tuning for ClimAID v2 machine-learning forecasters.

Tuning

Every v2 ML model is tuned with Optuna before it is fitted; users choose how much effort to spend (TUNING_PRESETS) but cannot switch tuning off.

Leakage safety: candidate settings are scored by expanding-window, time-ordered cross-validation inside the training period only (the last n_folds blocks of training months are predicted from the months before them). Hindcasts re-tune at every origin, so settings are never chosen with data from after the point being forecast.

Guard: the default settings are always scored on the same folds, and if no tuned candidate beats them the defaults are kept, so tuning cannot make a model worse on this criterion.

Score: mean absolute error of one-month-ahead predictions (actual recent cases as inputs). It is robust to outbreak spikes and valid for every model.

TUNING_PRESETS = {'fast': {'n_trials': 10, 'n_folds': 2, 'label': 'Fast (10 trials per model)'}, 'balanced': {'n_trials': 30, 'n_folds': 3, 'label': 'Balanced (30 trials per model)'}, 'deep': {'n_trials': 80, 'n_folds': 4, 'label': 'Deep (80 trials per model)'}} module-attribute

resolve_tuning(tuning)

Map a preset name or an integer trial count to (n_trials, n_folds, label). Tuning is compulsory: None means the default preset, never 'off'.

tune(name, X, y, tuning=None, random_state=42)

Tune name on (X, y) (time-ordered training data). Returns (params, info).

build_estimator(name, params=None, random_state=42)

Construct a v2 model: ClimAID defaults (v1 table) overridden by params.

v1 inside v2

Reports

Generate a self-contained HTML report for a v2 forecast.

The report opens with a plain-language layer for non-specialists (short version, month-by-month table, trust rating, caveats, glossary; see reporting_plain.py). All technical content follows in a collapsible "Technical details" section. history (cases up to the forecast start) enables "compared with a typical year"; observed (cases after the start, if known) enables "what actually happened".