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
DiseaseModelinstance. - 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
( |
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_projto 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
projectfor 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:
|
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:
|
Notes
- Internally calls
project_model_listto 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 |
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
|
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.,
|
required |
Returns:
| Name | Type | Description |
|---|---|---|
projection_summary |
dict :
|
Structured dictionary containing:
|
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.