Metadata-Version: 2.4
Name: GaugePredict
Version: 1.0.0
Summary: An open-source package that forecasts downstream gauge conditions using a hybrid neural network model
Author-email: "Caitlin R. R. Turner" <cturn65@lsu.edu>
Project-URL: Homepage, https://github.com/yourusername/GaugePredict
Project-URL: Bug Tracker, https://github.com/yourusername/GaugePredict/issues
Project-URL: Documentation, https://github.com/yourusername/GaugePredict#readme
Keywords: hydrology,forecasting,neural-network,USGS,gauge,water-level
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Hydrology
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: geopandas>=0.10.0
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: shap>=0.40.0
Requires-Dist: psutil>=5.8.0
Requires-Dist: matplotlib>=3.4.0
Requires-Dist: requests>=2.26.0
Requires-Dist: torch>=1.10.0
Provides-Extra: gpu
Requires-Dist: torch>=1.10.0; (platform_system != "Linux" or sys_platform != "darwin") and extra == "gpu"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Requires-Dist: mypy>=0.950; extra == "dev"
Requires-Dist: build>=0.8.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=4.5.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "docs"
Dynamic: license-file

## GaugePredict (Beta Version - V 1.0.0 Release coming soon!)
---

An open-source package that forecasts downstream gauge conditions using a hybrid neural network model.

- Creates extended-range forecasts of downstream gauge conditions (e.g., water level, discharge) from daily to multi-week horizons (1–30 days).
- Ingests and preprocesses basin-wide USGS gauge data by automatically downloading, aligning, and cleaning multi-site time series defined by user-selected HUC regions.
  - Synchronizes all sites to a continuous daily index and fills missing days so datasets are sequence-model ready.
- Trains horizon-specific CNN–LSTM models and uses SHAP-selected gauges to reduce inputs, enabling rapid forecasts on a standard machine.
- Supports continuity during data interruptions by using trained models to fill estimates when target-gauge observations are missing due to down gauges.
- Can be applied to forecast diversion-related flows for water management decisions.
- Comes with walkthrough notebooks that make dataset building, training, and figure generation easy to follow.


We welcome contributions! Please email cturn65@lsu.edu or open an issue/pull request to get involved!

---

## Installation
```bash
#git clone https://github.com/<your-username>/GaugePredict.git
#cd GaugePredict
#pip install -e .
```
('python -m pip install GaugePredict' installation through PyPI coming soon)

---

*Conda and container instructions removed.*

## Workflow Assisted by Notebooks (located in examples)
- **1) GaugePredict Data Downloader notebook (`downloader_notebook.ipynb`)**
  - Builds basin-scale **predictor datasets** from USGS gauge records for GaugePredict.
  - Main steps:
    - Define a target gauge (what you want to predict) and analysis window.
    - Select upstream predictor gauges (e.g., by HUC regions) and download daily records.
    - Standardize to a continuous daily time index and handle missing values consistently.
    - Save outputs for modeling:
      - Cached time series files per gauge.
      - A site dictionary JSON with metadata.
    **This file must be created to run the other two notebooks as is. They can also be used as a guide for your own area**

- **2) GaugePredict Training notebook (`training_notebook.ipynb`)**
  - Trains the **CNN–LSTM** GaugePredict model for a selected target site and variable using the cached predictor dataset.
  - Main steps:
    - Configure run metadata (run name, target, date window, horizons).
    - Choose predictor-site selection mode:
      - Use all sites, or a SHAP-ranked subset if available (can be created in notebook).
    - Run training and evaluation per horizon.
    - Save outputs to a run-specific results folder:
      - Per-horizon predictions, metrics, and artifacts.
      - A compute summary JSON with hardware info, hyperparameters, runtimes, and skill scores for reporting.

- **3) GaugePredict Figure Creating notebook (`figure_creating_notebook.ipynb`)**
  - Generates figures from saved run outputs.
  - Main figure workflows:
    - **Training + test performance figure**
      - Loads saved runs for selected horizons.
      - Aligns test series and plots observed vs predicted plus training diagnostics.
    - **SHAP geoplot grid**
      - Reads SHAP artifacts from the SHAP results folder.
      - Plots a map grid of predictor sites and SHAP-selected subsets by horizon, with a target-site marker.


---

## License
This project is licensed under the MIT License

---

## Citing GaugePredict (NOT PEER REVIEWED YET)
If you use **GaugePredict** in your research, please cite the software and associated paper upon release.  

**Citation:**
coming soon

