HydroPredict Hyderabad

HydroPredict Hyderabad is an interactive Streamlit dashboard for exploring and forecasting hydrology-related daily time series from six monitoring stations around Hyderabad.

It combines an included Excel workbook of station observations with hydrological feature engineering, Plotly visual analytics, Google TimesFM 2.5 zero-shot forecasting, and a live 10-day ECMWF IFS weather forecast from Open-Meteo.

Repository: github.com/WhatsThisClint/HydroPredict-Hyderabad

What This Project Does

• Loads daily station data from DATA_ Daily_CGWB_Stations_2022-2025.xlsx.
• Computes net water balance as rainfall minus evaporation.
• Computes cumulative net water balance as a simple groundwater recharge/deficit proxy.
• Shows an interactive station map with rainfall, evaporation, and water-balance summaries.
• Plots historical rainfall, evaporation, and cumulative water-balance trends.
• Runs TimesFM 2.5 zero-shot forecasts and compares them with seasonal and persistence baselines.
• Offers a validation-weighted ensemble strategy to reduce blind trust in any single method.
• Fetches a live 10-day ECMWF IFS forecast for precipitation and daily min/max temperature at the selected station.

What This Project Is Not

This is a visualization and decision-support tool, not a full groundwater simulation model. It does not model pumping, aquifer geometry, runoff, soil permeability, land-use change, measured water-table depth, or groundwater extraction. Treat the output as an analytical signal that should be validated with domain knowledge and field measurements before operational use.

Dashboard Tabs

1. Overview & Geospatial Map: station map, station-level metrics, and network summary table.
2. Historical Hydrology & Storage: rolling rainfall/evaporation trends and cumulative net water-balance proxy.
3. TimesFM 2.5 Zero-Shot Forecasting: on-demand forecast plus a recent validation comparison against baseline methods.
4. ECMWF Weather Forecast: live 10-day precipitation and temperature forecast via Open-Meteo.
5. Hydrological Insights: plain-language notes about monsoon recharge patterns and station-level behavior.

Quick Start

1. Clone The Repository

git clone https://github.com/WhatsThisClint/HydroPredict-Hyderabad.git
cd HydroPredict-Hyderabad

2. Create A Virtual Environment

Windows PowerShell:

py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip

macOS or Linux:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

3. Install Dependencies

python -m pip install -r requirements.txt

4. Run The Dashboard

python -m streamlit run app.py

Streamlit will print a local URL, usually:

http://localhost:8501

Open that URL in your browser.

Using The App

1. Select a monitoring station from the sidebar.
2. Choose the variable to forecast.
3. Adjust the forecast horizon and historical context window.
4. Explore the map and historical tabs first.
5. Open the TimesFM tab and click Run Forecast & Backtest when you want to load the model, compare strategies, and generate predictions.
6. Open the ECMWF tab to view the live 10-day weather forecast for the selected station.

The TimesFM model is loaded only when you click the forecast button. This keeps the dashboard usable even on machines where the model download has not happened yet.

The default strategy is Validation-weighted ensemble. It compares TimesFM, seasonal climatology, and persistence on a recent holdout window, then blends the methods using recent validation accuracy. You can still choose TimesFM-only or either baseline in the sidebar.

First TimesFM Run

On first TimesFM use, transformers downloads:

google/timesfm-2.5-200m-transformers

This can take a while depending on network speed. Hugging Face allows unauthenticated downloads, but you may see rate-limit warnings. If needed, set a Hugging Face token before running the app.

Windows PowerShell:

$env:HF_TOKEN="your_hugging_face_token"
python -m streamlit run app.py

macOS or Linux:

export HF_TOKEN="your_hugging_face_token"
python -m streamlit run app.py

Data

The included workbook contains these station sheets:

• CGWHYD0005
• CGWHYD0032
• CGWHYD0114
• CGWHYD0158
• CGWHYD0230
• CGWHYD0239

Each sheet currently has 1,461 daily rows from 2022-01-01 through 2025-12-31 with no missing values in the checked copy.

See Data And Model Notes for the field dictionary, engineered features, and interpretation limits. See Prediction Audit for what the forecast is doing and how the validation strategy behaves.

Project Structure

.
+-- app.py                                   # Streamlit dashboard
+-- data_loader.py                           # Excel loading and hydrological feature engineering
+-- forecast_engine.py                       # TimesFM 2.5 wrapper
+-- DATA_ Daily_CGWB_Stations_2022-2025.xlsx # Included station dataset
+-- requirements.txt                         # Python dependencies
+-- run_dashboard.ps1                        # Convenience launcher for Windows
+-- .streamlit/config.toml                   # Streamlit theme and server settings
+-- docs/
|   +-- DATA_AND_MODEL_NOTES.md
|   +-- PREDICTION_AUDIT.md
|   +-- TROUBLESHOOTING.md
+-- scripts/
|   +-- backtest_forecasts.py
+-- LICENSE
+-- README.md

Development Checks

Run these after making changes:

python -m py_compile app.py data_loader.py forecast_engine.py
python data_loader.py
python forecast_engine.py
python -m streamlit run app.py

forecast_engine.py loads TimesFM and runs a small dummy forecast, so it may download model weights on first use.

To run the historical forecast audit:

python scripts\backtest_forecasts.py

Troubleshooting

Common setup and runtime fixes are documented in Troubleshooting.

License

This project is released under the MIT License.

Commercial use is allowed under MIT. Users may use, modify, distribute, sublicense, and sell copies of the software as long as they retain the copyright and license notice.