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 ( |
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 |
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 |
"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 |
True
|
Forecasting engine¶
Climate-mandatory probabilistic disease forecaster.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
models
|
iterable[str]
|
Any combination of |
('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
|
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".