SSI Calculation, LSTM, and SHAP Analysis

Overview

This directory contains the data products, trained models, and Jupyter notebooks used for the surrogate modeling and explainable AI components of the study:

Harnessing Backcasting to Identify Drivers of Critical Warming at Hoover Dam Using Hydrodynamic and Machine Learning Models

The materials in this folder support workflows for:

• calculation of the Schmidt Stability Index (SSI)
• training and applying Long Short-Term Memory (LSTM) surrogate models,
• storing optimized trained models for lower- and upper-intake analyses,
• computing and storing Shapley Additive ExPlanation (SHAP) values for model interpretation, and
• generating SHAP-based visualizations used in the study.

These files are provided to support transparency, reproducibility, and reuse of the machine learning analysis associated with the publication.

Folder Contents

Notebooks

• LSTM_lower.ipynb
  Jupyter notebook for the lower-intake LSTM workflow, including SSI calculation, model development, evaluation, prediction analysis, and visualization.

• LSTM_upper.ipynb
  Jupyter notebook for the upper-intake LSTM workflow.

• shapplots_lower_v3_CRtemp.ipynb
  Notebook for SHAP-based interpretation and visualization of the lower-intake optimized model.

• shapplots_upper_v3_CRtemp.ipynb
  Notebook for SHAP-based interpretation and visualization of the upper-intake optimized model.

Trained Model Files

• optimal_model_lower.keras
  Saved optimized Keras model for the lower-intake analysis.

• optimal_model_upper.keras
  Saved optimized Keras model for the upper-intake analysis.

Precomputed SHAP Outputs

• shap_values_lower_CRtemp_optim.npy
  Precomputed SHAP values for the lower-intake optimized model.

• shap_values_upper_CRtemp_optim.npy
  Precomputed SHAP values for the upper-intake optimized model.

Data Directories

• mergedfilled_daily_CRinflowtemp/
  Daily merged and gap-filled input datasets used in the lower-intake workflow across multiple elevation and scenario combinations.

• mergedfilled_upper_daily_CRinflowtemp/
  Daily merged and gap-filled input datasets used in the upper-intake workflow.

• merged_with_schmidt/
  Merged datasets that include Schmidt stability-related variables.

• wtrtempdepth/
  Water temperature-by-depth datasets derived from hydrodynamic model outputs.

• wtrtempdepth_mergedfilled_daily/
  Daily-averaged water temperature datasets derived from the depth-resolved water temperature files.

Data Organization

This folder includes multiple datasets corresponding to combinations of:

• analysis elevation:
• 900ft
• 950ft
• 1000ft
• 1050ft

• 1100ft

• scenario or time period labels such as:

• 20162025
• 20262030
• 20262030_20912097
• 2099
• 8075pct

Many filenames also indicate processing steps such as:

• daily_avg
• filled
• merged
• wtrtemp
• schmidt

Users should preserve the original filenames and folder structure where possible, as notebooks may reference these paths directly.

Typical Workflow

A typical use of this directory is:

1. Access prepared input datasets
   Use files in:
2. mergedfilled_daily_CRinflowtemp/

3. mergedfilled_upper_daily_CRinflowtemp/

4. Run or inspect the LSTM notebooks

5. LSTM_lower.ipynb

6. LSTM_upper.ipynb

7. Reuse optimized trained models

8. optimal_model_lower.keras

9. optimal_model_upper.keras

10. Interpret model behavior using SHAP

11. shap_values_lower_CRtemp_optim.npy
12. shap_values_upper_CRtemp_optim.npy
13. shapplots_lower_v3_CRtemp.ipynb

14. shapplots_upper_v3_CRtemp.ipynb

15. Reproduce figures and interpretation results
    Run the SHAP notebooks to regenerate visual summaries of driver influence.

Notes on Reproducibility

• Saved model files and SHAP arrays are included as precomputed artifacts to reduce runtime and facilitate reproduction of published results.
• Notebooks may depend on specific Python package versions for TensorFlow/Keras, SHAP, NumPy, pandas, and plotting libraries.
• Relative file paths may be hard-coded in some notebooks, so preserving the directory structure is recommended.
• Large CSV and NumPy files are included because they serve as intermediate or analysis-ready products used in the study.

Recommended Citation

If you use these materials, please cite the associated journal article and the HydroShare resource accompanying the publication.