Skip to content

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" : Computes standardized anomalies relative to rolling mean and standard deviation.

  • "percentile" : Flags observations exceeding a specified percentile threshold.

"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:

  • For "zscore": Number of standard deviations above the rolling mean.

  • For "percentile": Percentile cutoff (e.g., 0.9 for 90th percentile).

2.0 :
date_col str

Column name representing temporal ordering of the data.

"time" :

Returns:

Name Type Description
df DataFrame

DataFrame with additional columns :

  • anomaly_score : float
    • Computed anomaly metric (z-score or percentile-based)
  • outbreak_flag : int
    • Binary indicator (1 = outbreak, 0 = normal)
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.

  • Supported options include
    • "xgb" : XGBoost
    • "rf" : Random Forest
("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.

  • Options:
    • "percentile" : keeps the best (100 - percentile)% of configurations by Stage 1 RMSE, capped at top_k
    • "top_k" : keeps the top_k configurations by Stage 1 RMSE
"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)

  • feature_metadata : dict Information about generated lagged features

  • lag_search_results : pandas.DataFrame Performance of all evaluated configurations

  • best_config : dict Best-performing configuration (lags + model combination)

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:

  • self.train_df : pandas.DataFrame Training dataset

  • self.test_df : pandas.DataFrame Testing dataset

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_year and test_year are 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., DiseaseProjection). This may include predicted values, confidence intervals, and temporal aggregation.

required

Returns:

Name Type Description
artifacts ReportArtifacts
  • A structured object containing all elements required for reporting, such as:
    • Processed projection data
    • Evaluation metrics (if available)
    • Metadata (e.g., model configuration, time range)
    • Visualization-ready datasets
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:

  1. Base model – Generates initial predictions from input features.
  2. Residual model – Learns and predicts residual errors from the base model.
  3. 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 X.

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)
  • Level of detail in the generated report:
    • "detailed": Includes full analysis, metrics, and explanations.
    • "summary": Provides a concise overview of key findings.
    • "policy": Provides a comprehensive policy report.
"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 save_copy=True. If not specified, a default output location is used.

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:
    1. Projection (if not provided)
    2. Artifact construction
    3. 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 save=True.

'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.