Disease Model¶
Note
This page documents the v1 (legacy) methods. The v2 methods forecast_v2() and project_v2() are
documented in the ClimAID v2 API and the v2 forecasting guide.
Climate-informed disease prediction and projection model.
This class implements an end-to-end pipeline for modeling climate-sensitive diseases (e.g., dengue, malaria) using historical climate data, lagged features, and hybrid machine learning approaches.
The pipeline includes: 1. Data ingestion (disease + climate) 2. Climate–disease data merging 3. Lagged feature optimisation (Bayesian search) 4. Model training (stacked learning framework) 5. Prediction and evaluation 6. Climate-based future projections (via DiseaseProjection)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
district
|
str
|
District identifier (must match supported naming convention, e.g., 'IND_Pune_MAHARASHTRA'). |
required |
disease_file
|
str or Path :
|
Path to the disease dataset file. Supported formats include: CSV (.csv), Excel (.xlsx), and Parquet (.parquet). |
required |
target_col
|
str
|
Column name representing disease case counts. |
"Count" :
|
random_state
|
int
|
Random seed for reproducibility across the pipeline. |
42 :
|
disease_name
|
str, optional :
|
Name of the disease (e.g., "Dengue", "Malaria"). Used for reporting and visualization. |
None
|
Attributes:
| Name | Type | Description |
|---|---|---|
df_disease |
pandas.DataFrame :
|
Raw disease dataset. |
df_climate_hist |
pandas.DataFrame :
|
Historical climate data. |
df_climate_proj |
pandas.DataFrame :
|
Climate projection data (CMIP6). |
df_merged |
pandas.DataFrame :
|
Combined dataset with aligned disease and climate variables. |
train_df |
pandas.DataFrame :
|
Training subset after domain-aware split. |
test_df |
pandas.DataFrame :
|
Testing subset. |
lag_search_results |
dict
|
Results from lag optimisation process. |
best_config |
dict
|
Best-performing lag configuration. |
final_models |
dict
|
Trained models (base, residual, calibration). |
runtime |
dict
|
Execution time tracking for each pipeline stage. |
Notes
- The modeling framework uses
- Base model: captures main signal (e.g., XGBoost)
- Residual model: models unexplained variation (e.g., Random Forest)
- Calibration model: adjusts predictions (e.g., isotonic regression)
detect_historical_outbreaks(method='zscore', window=12, threshold=2.0, date_col='time')
¶
Detect historical outbreak periods using anomaly-based thresholds.
This method identifies unusually high disease incidence relative to a historical baseline using statistical anomaly detection techniques.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
method
|
str
|
Method used for anomaly detection. Supported options:
|
"zscore" :
|
window
|
int
|
Rolling window size (in time steps, typically months) used to compute baseline statistics such as mean and standard deviation. |
12 :
|
threshold
|
float
|
Threshold for outbreak detection:
|
2.0 :
|
date_col
|
str
|
Column name representing temporal ordering of the data. |
"time" :
|
Returns:
| Name | Type | Description |
|---|---|---|
df |
DataFrame
|
DataFrame with additional columns :
|
Notes
- The method assumes time-series structure in the dataset.
- Rolling statistics are computed using past observations only (no future leakage).
- Suitable for identifying epidemic spikes in climate-sensitive diseases.
optimize_lags(base_models=('xgb', 'rf'), residual_models=('rf', 'extratrees'), correction_models=('ridge', 'gbr', 'isotonic'), n_trials=30, debug=False, n_jobs=-1, pruning_strategy='percentile', top_k=50, sh_range=range(0, 4), temp_range=range(0, 4), rain_range=range(0, 4), elnino_range=range(0, 13), percentile=90, scalar=None)
¶
Optimize climate lag structures and model configurations using Bayesian search.
This method identifies the optimal combination of lagged climate variables (e.g., temperature, rainfall, humidity, ENSO indices) along with the best model architecture using a hybrid AutoML framework.
The optimization jointly searches over: - Climate lag configurations - Base models (signal learning) - Residual models (error correction) - Calibration models (prediction adjustment)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
base_models
|
tuple of str
|
Models used to capture the primary disease–climate relationship.
|
("xgb", "rf") :
|
residual_models
|
tuple of str
|
Models used to capture residual patterns not explained by base models. |
("rf", "extratrees")
|
correction_models
|
tuple of str
|
Models used for calibration or bias correction of predictions. |
("ridge", "gbr", "isotonic")
|
n_trials
|
int
|
Number of optimization iterations (Bayesian search trials). |
30
|
debug
|
bool
|
If True, enables verbose logging and debugging output. |
False
|
n_jobs
|
int
|
Number of parallel jobs: - -1 uses all available CPU cores |
-1
|
pruning_strategy
|
str
|
Strategy for pruning poor-performing configurations during search.
|
"percentile"
|
top_k
|
int
|
Maximum number of configurations retained after pruning (applies to both strategies). |
50
|
sh_range
|
iterable
|
Lag range for specific humidity (months). |
range(0, 4)
|
temp_range
|
iterable
|
Lag range for temperature. |
range(0, 4)
|
rain_range
|
iterable
|
Lag range for rainfall. |
range(0, 4)
|
elnino_range
|
iterable
|
Lag range for ENSO (El Niño) index. |
range(0, 13)
|
percentile
|
int
|
Percentile threshold used for pruning or model selection. |
90
|
scalar
|
object
|
Optional feature scaling object (e.g., StandardScaler). |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
tuple |
(feature_metadata, lag_search_results, best_config)
|
Notes
- Uses Bayesian optimization for efficient hyperparameter search.
- Supports parallel evaluation of configurations.
- Designed for climate-sensitive disease systems with delayed effects.
- Lag ranges should reflect domain knowledge (e.g., incubation periods).
train_final_model()
¶
Train the final disease prediction model using the optimized feature set.
This method fits the final model after preprocessing, feature engineering, and lag optimization steps have been completed. It typically uses the best-performing configuration identified during model selection (e.g., stacked learning framework or tuned estimator).
The trained model is stored internally and used for subsequent prediction and projection tasks. It takes no arguments.
Returns:
| Name | Type | Description |
|---|---|---|
self |
DiseaseModel
|
Returns the instance with the trained model stored internally. |
Notes
- Assumes that data ingestion and preprocessing have already been performed.
- Requires optimized lagged features to be available.
- May internally split data into training and validation sets.
- Supports integration with ensemble or stacked models if configured.
_train_test_split(train_year=None, test_year=None, drop_2020=True)
¶
Perform a time-aware train/test split for disease modeling.
This method splits the merged dataset into training and testing subsets based on temporal ordering, ensuring no data leakage from future observations.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
train_year
|
int or None
|
Last year to include in the training dataset. If None, the split is determined automatically. |
None
|
test_year
|
int or None
|
First year to include in the test dataset. If None, the split is determined automatically. |
None
|
drop_2020
|
bool
|
Whether to exclude data from the year 2020. This is useful to remove anomalies due to COVID-19 disruptions in disease reporting and transmission patterns. |
True
|
Returns:
| Name | Type | Description |
|---|---|---|
None |
Updates internal attributes:
|
Notes
- The split preserves temporal ordering (no random shuffling).
- Designed for time-series epidemiological data.
- Avoids leakage by ensuring test data strictly follows training data.
- If both
train_yearandtest_yearare provided, they must be consistent.
Warning
This is an internal method and is not intended for direct use.
build_report_artifacts(projection_summary, tidy_df)
¶
Construct standardized reporting artifacts from model outputs.
This method generates a structured collection of artifacts required for downstream reporting and visualization. It transforms model outputs, including projections and evaluation summaries, into a consistent format that can be used by the reporting layer (e.g., dashboards, plots, or exports).
Users are not expected to manually assemble these artifacts. This function ensures that all required components are created automatically and in a reproducible format.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
projection_summary
|
dict or DataFrame
|
Summary of model projections, typically produced by the projection
pipeline (e.g., |
required |
Returns:
| Name | Type | Description |
|---|---|---|
artifacts |
ReportArtifacts
|
|
Notes
- This method is part of the reporting pipeline and is typically called after model training and projection steps.
- Ensures consistency between modeling outputs and reporting interfaces.
- Designed to support reproducible research workflows.
predict(X)
¶
Generate disease case predictions using the trained stacked model.
This method applies the full prediction pipeline consisting of:
- Base model – Generates initial predictions from input features.
- Residual model – Learns and predicts residual errors from the base model.
- Correction step – Combines base predictions and residual corrections to produce final refined predictions.
The method assumes that the model has already been trained using
train_final_model.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
X
|
pandas.DataFrame :
|
Input feature matrix containing the same variables used during training, including climate variables and any engineered lagged features. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
predictions |
ndarray
|
Array of predicted disease case counts (or risk scores), aligned with
the input samples in |
Notes
- Input features must match the training schema (column names and preprocessing).
- If lagged features were used during training, they must be present in
X. - This method uses the internally stored trained models and does not retrain.
generate_report(projection_summary=None, llm_client=None, tidy_df=None, style='detailed', open_browser=False, save_copy=False, output_dir=None)
¶
Generate a comprehensive disease projection report.
This method provides a fully automated reporting pipeline that transforms model outputs into a structured, human-readable report. It integrates projections, optional language model summarization, and formatted outputs for visualization or sharing.
Users are not required to manually construct intermediate artifacts—this method handles all necessary steps internally, including artifact creation, formatting, and optional rendering.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
projection_summary
|
dict or DataFrame
|
Precomputed projection results. If not provided, the method may internally generate projections using the trained model. |
None
|
llm_client
|
object
|
Language model client used to generate narrative summaries or insights. If provided, the report may include AI-generated interpretations of trends. |
None
|
tidy_df
|
DataFrame
|
DataFrame for exporting to an excel file. |
None
|
style
|
(detailed, summary, policy)
|
|
"detailed"
|
open_browser
|
bool
|
If True, automatically opens the generated report in a web browser. |
False
|
save_copy
|
bool
|
If True, saves a copy of the report to disk. |
False
|
output_dir
|
str
|
Directory where the report will be saved if |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
report |
str or Path
|
Path to the generated report file or rendered output, depending on configuration. |
Notes
- This method combines multiple pipeline stages:
- Projection (if not provided)
- Artifact construction
- Report formatting and rendering
- Designed for end-to-end usability with minimal user intervention.
- Supports integration with LLMs for enhanced interpretability.
plot_historical_predictions(actual_color='#006d77', prediction_color='#e29578', hatch_color='#ffddd2', figsize=(12, 5), hatch='.', save=False, alpha=0.4, path='path', theme='ticks', dpi=500)
¶
Plot observed vs predicted disease cases over time.
This method visualizes the model's performance by comparing historical observed values with predicted values. It helps assess model fit, identify temporal patterns, and detect systematic deviations.
The plot may optionally include shaded or hatched regions to highlight differences between observed and predicted values.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
actual_color
|
str
|
Color used for plotting observed (true) disease cases. |
'#006d77'
|
prediction_color
|
str
|
Color used for plotting model predictions. |
'#e29578'
|
hatch_color
|
str
|
Color used for shaded or hatched regions representing prediction error or uncertainty. |
'#ffddd2'
|
figsize
|
tuple of int
|
Size of the figure in inches (width, height). |
(12, 5)
|
hatch
|
str
|
Matplotlib hatch pattern used to highlight differences between observed and predicted values. |
'.'
|
save
|
bool
|
If True, saves the plot to disk. |
False
|
alpha
|
float
|
Transparency level for shaded or hatched regions. |
0.4
|
path
|
str
|
File path where the plot will be saved if |
'path'
|
theme
|
str
|
Seaborn or matplotlib style theme applied to the plot. |
'ticks'
|
dpi
|
int
|
Resolution of the saved figure in dots per inch. |
500
|
Returns:
| Type | Description |
|---|---|
-None
|
|
- Displays the plot and optionally saves it to disk.
|
|
Notes
- Requires the model to be trained and predictions to be available.
- Assumes temporal alignment between observed and predicted values.
- Useful for diagnostic evaluation of model performance.
print_runtime_summary()
¶
Prints a clean runtime summary for the full pipeline.