Skip to content

DiseaseProjection

Generate climate-driven disease projections using CMIP6 data.

This class provides a high-level interface for producing future disease projections under different climate scenarios. It integrates trained disease models with CMIP6 climate projections to simulate potential disease dynamics across time, regions, and emission pathways.

The projection pipeline supports flexible configurations, including multiple climate models (GCMs), Shared Socioeconomic Pathways (SSPs), and ensemble-based approaches.

Features
  • Single scenario projection (one GCM + SSP)
  • Multi-GCM projections for model comparison
  • Multi-SSP projections for scenario analysis
  • Ensemble mean projections across multiple simulations
  • Visualization of projected disease trends
  • Export of results to CSV with prediction intervals
Notes
  • Requires a trained DiseaseModel instance.
  • Assumes CMIP6 climate inputs are preprocessed and aligned with the model's feature requirements.
  • Designed for scenario-based forecasting and climate impact assessment.

__init__(disease_model)

Initialize the DiseaseProjection interface using a trained DiseaseModel.

This constructor extracts the necessary components from a trained DiseaseModel instance to enable future climate-based projections. It validates the availability of projected climate data and prepares all required attributes for downstream projection tasks.

Parameters:

Name Type Description Default
disease_model DiseaseModel

A trained DiseaseModel instance containing fitted models, optimized features, preprocessing objects, and projected climate data (df_climate_proj).

required

Raises:

Type Description
ValueError :

If the provided DiseaseModel does not contain projected climate data.

Notes
  • The DiseaseModel must be fully trained prior to initialization.
  • Requires df_climate_proj to be available for generating projections.
  • Internally extracts:
    • Target variable name
    • Selected feature set (from best configuration)
    • Preprocessing objects (e.g., scaler)
    • Model performance metrics (e.g., RMSE)
    • Feature metadata for consistent transformation

prepare_features(df)

Prepare and transform input features for projection or prediction.

This method ensures that input data is aligned with the feature configuration used during model training. It applies necessary preprocessing steps such as feature selection, ordering, and scaling to maintain consistency with the trained model.

Parameters:

Name Type Description Default
df pandas.DataFrame :

Input data containing climate variables and any required predictors. Must include all features expected by the trained model.

required

Returns:

Name Type Description
df_out pandas.DataFrame :

Transformed feature matrix ready for model inference, with the correct feature set, ordering, and preprocessing applied.

Notes
  • Ensures consistency between training and projection pipelines.
  • Applies the same feature selection defined in best_config.
  • Uses the stored scaler or preprocessing objects from the trained model.
  • Missing or misaligned features may result in errors.

project(model_name, ssp, data=None)

Generate disease projections for a single CMIP6 model and SSP scenario.

This method produces future disease predictions using climate projections from a specified General Circulation Model (GCM) under a given Shared Socioeconomic Pathway (SSP). It forms the core projection step by combining climate inputs with the trained disease model.

The method internally prepares features, applies the trained model, and returns time-resolved projections.

Parameters:

Name Type Description Default
model_name str

Name of the CMIP6 climate model (GCM) to use (e.g., "MPI-ESM1-2-HR").

required
ssp str

Shared Socioeconomic Pathway scenario (e.g., "ssp245", "ssp585").

required
data pandas.DataFrame, optional :

Optional pre-filtered climate dataset. If not provided, the method uses internally stored CMIP6 projection data.

None

Returns:

Name Type Description
proj_features pandas.DataFrame or None :

DataFrame containing projected disease values over time for the specified model and scenario. Returns None if the requested data is not available.

project_model_list(model_list, ssp)

Generate disease projections for multiple CMIP6 models under a single SSP.

This method iterates over a list of General Circulation Models (GCMs) and computes disease projections for each model using the specified Shared Socioeconomic Pathway (SSP). It acts as a wrapper around the core project method, enabling multi-model comparison.

Models with missing or unavailable data are skipped automatically.

Parameters:

Name Type Description Default
model_list list of str

List of CMIP6 model names (GCMs) to evaluate.

required
ssp str

Shared Socioeconomic Pathway scenario (e.g., "ssp245", "ssp585").

required

Returns:

Name Type Description
outputs dict[str, DataFrame]

Dictionary mapping each valid GCM name to its corresponding projection DataFrame.

Notes
  • Internally calls project for each model.
  • Skips models with missing or empty projection data.
  • Prints informational messages when models are skipped.
  • Returns an empty dictionary if no valid projections are generated.

project_multi_model_ssp(model_list, ssp_list)

Generate disease projections across multiple CMIP6 models and SSP scenarios.

This method performs a full projection sweep over all combinations of General Circulation Models (GCMs) and Shared Socioeconomic Pathways (SSPs). It aggregates results into a single unified DataFrame for comparative analysis and downstream processing.

Each projection is computed using the core project method, with results annotated by model and scenario identifiers.

Parameters:

Name Type Description Default
model_list list of str

List of CMIP6 model names (GCMs) to evaluate.

required
ssp_list list of str

List of SSP scenarios (e.g., ["ssp245", "ssp585"]).

required

Returns:

Name Type Description
master_df pandas.DataFrame :

Combined DataFrame containing projections for all valid model–scenario combinations. Includes:

  • Predicted disease values (disease_projection)
  • Prediction intervals (e.g., lower_bound)
  • Model identifier (GCM)
  • Scenario identifier (SSP)
  • Temporal columns (e.g., Year, Month)

Raises:

Type Description
ValueError :

If no valid projections are generated across all combinations.

Notes
  • Iterates over all combinations of model_list × ssp_list.
  • Skips combinations with missing or invalid data.
  • Catches and logs errors for individual model–scenario pairs without interrupting the full pipeline.
  • Clips negative projection values to zero for physical consistency.
  • Sorts output by GCM, SSP, and time (if columns are available).

project_ensemble_mean(model_list, ssp)

Compute ensemble-mean disease projections across multiple CMIP6 models.

This method aggregates projections from multiple General Circulation Models (GCMs) under a single Shared Socioeconomic Pathway (SSP) to produce a consolidated ensemble estimate. It summarizes central tendency and uncertainty across models.

The ensemble provides a more robust estimate of future disease dynamics by reducing reliance on any single climate model.

Parameters:

Name Type Description Default
model_list list of str

List of CMIP6 model names (GCMs) to include in the ensemble.

required
ssp str

Shared Socioeconomic Pathway scenario (e.g., "ssp245", "ssp585").

required

Returns:

Name Type Description
ensemble DataFrame

DataFrame containing aggregated projections with the following columns:

  • Year, Month : Time indices
  • mean : Ensemble mean projection
  • min, max : Range across models
  • p05, p95 : 5th and 95th percentile bounds
  • GCM : Set to "ENSEMBLE_MEAN"
  • SSP : Scenario identifier
Notes
  • Internally calls project_model_list to generate individual projections.
  • Assumes consistent temporal alignment across models.
  • Percentile bounds (p05, p95) provide a measure of inter-model uncertainty.
  • Useful for summarizing projections in reports and decision-making contexts.

flag_outbreak_risk(df_proj, method='both', percentile=0.9, projection_col='disease_projection', year_col='Year')

Flag outbreak risk based on projected disease levels.

This method classifies projected disease values into outbreak risk categories using percentile-based thresholds. It supports both fixed (historical) and adaptive (scenario-specific) baselines.

Two approaches are available:

A) Historical baseline: Uses a fixed percentile threshold derived from historical data (e.g., 90th percentile of observed cases).

B) Dynamic baseline: Computes thresholds separately for each GCM–SSP combination, allowing risk levels to adapt to scenario-specific distributions.

Parameters:

Name Type Description Default
df_proj pandas.DataFrame :

DataFrame containing projection results. Must include the column specified by projection_col, and optionally GCM and SSP for dynamic thresholding.

required
method ('historical', 'dynamic', 'both')

Method used to define outbreak thresholds: - "historical": fixed threshold from historical data - "dynamic": scenario-specific thresholds - 'gam' : Generalised-Additive Model using Q_{0.9}​(t)≈ μ(t)+ zσ - "both": compute and return both risk indicators

"historical"
percentile float

Percentile used to define the outbreak threshold (e.g., 0.9 = 90th percentile).

0.9 :
projection_col str

Column name containing projected disease values.

"disease_projection" :
year_col str

Column name for the year which comes from the model itself.

'Year'

Returns:

Name Type Description
df pandas.DataFrame :

Input DataFrame with additional columns indicating outbreak risk. Depending on method, includes:

  • risk_historical : binary or categorical flag based on historical threshold
  • risk_dynamic : binary or categorical flag based on adaptive thresholds
Notes
  • Historical thresholds are typically computed from training or observed data.
  • Dynamic thresholds are computed within each (GCM, SSP) group.
  • Useful for identifying high-risk periods under future climate scenarios.
  • The method does not modify original projection values.

build_projection_summary(df)

Construct a structured summary of CMIP6-based disease projections.

This method transforms a multi-model, multi-scenario projection DataFrame into a standardized summary dictionary suitable for reporting, visualization, and downstream analysis. It aggregates projections across GCMs and SSPs, computes ensemble statistics, and organizes outputs into interpretable blocks.

Parameters:

Name Type Description Default
df pandas.DataFrame :

Projection DataFrame generated from multi-model and multi-SSP workflows (e.g., project_multi_model_ssp). Expected to include:

  • time or (Year, Month)
  • GCM (climate model identifier)
  • SSP (scenario identifier)
  • disease_projection
  • lower_bound
  • upper_bound
required

Returns:

Name Type Description
projection_summary dict :

Structured dictionary containing:

  • mode : Type of analysis (e.g., future climate projection)
  • method : Description of projection methodology
  • projection_period : Time span of projections
  • climate_models : List of GCMs used
  • ssp_scenarios : List of SSPs evaluated

  • ensemble_mean : Aggregated statistics across all models

    • mean_projection
    • max_projection
    • min_projection
    • trend
    • peak_transmission_months
  • ssp_ensemble : Scenario-specific aggregated summaries

  • ensemble_timeseries : Time series of ensemble mean projections
  • ssp_timeseries : Time series per SSP
  • gcm_summary : Model-wise summary statistics
  • risk_matrix : Risk classification across models and scenarios

  • uncertainty :

    • mean_uncertainty_range
    • definition of uncertainty metric
Notes
  • Designed as the primary interface between projection outputs and reporting/visualization layers.
  • Aggregates both central tendency and uncertainty metrics.
  • Assumes input data is preprocessed and validated.
  • Supports downstream use in generate_report.