A professional Python package for hydrological data analysis featuring a Streamlit web dashboard, 23+ visualization types, and integrations with USGS, NOAA, and climate data services.
Live Demo: hydroplot.streamlit.app
-
Interactive Site Map - Explore 736+ USGS monitoring sites across the Pacific Northwest
- Dark theme Folium map with marker clustering
- HUC watershed boundary overlays (Regions, Subregions, Basins, Subbasins)
- Color-coded markers by record age
- Watershed quick-jump dropdown for WA, OR, and ID regions
- Click-to-zoom site tables
-
5 Analysis Modes
- Site Map - Interactive exploration of all monitoring sites
- Single Analysis - Deep dive into one site with 23 plot types
- Compare Time Periods - Same site across two date ranges
- Compare Sites - 2-4 sites for the same period
- 2x2 Comparison - Two sites x two time periods
-
Real-time Data - Live fetching from USGS NWIS with accurate data availability dates
-
Flexible Date Selection - Year sliders with fine-tune inputs
-
Metric Cards - Record length, data points, mean/peak flow statistics
| Category | Plots |
|---|---|
| Time Series | Discharge timeseries, Precip-discharge overlay, Anomaly detection |
| Flow Analysis | Flow duration curve, Monthly boxplots, Annual trend, Low-flow trend |
| Frequency Analysis | Flood frequency (Log-Pearson III), 7Q10 low flow analysis |
| Hydrograph Analysis | Baseflow separation (Lyne-Hollick), Recession curves, Stage-discharge rating curve |
| Climate Correlation | Hexbin temperature, Lagged precipitation, Seasonal scatter, Correlation matrix, Lag analysis (0-30 days) |
| Heatmaps | Discharge density by day-of-year, Temporal panels (5/10/20 year) |
| Advanced | Double mass curve, Cumulative departure, Spectral analysis (FFT), Climate anomaly (Q/T/P) |
# Clone the repository
git clone https://github.com/abstractionisms/Hydroanalysispy
cd Hydroanalysispy
# Install in development mode
pip install -e .
# Or install with optional dependencies
pip install -e .[dev] # Development tools (pytest, black, flake8)
pip install -e .[dashboard] # Streamlit dashboard# Run locally
python run_dashboard.py
# With network access (for remote connections)
python run_dashboard.py --network
# Custom port
python run_dashboard.py --port 8502Then open http://localhost:8501 in your browser.
# Run analysis with config file
python -m hydrology.scripts.analyze_sites --config configs/my_analysis.yamlfrom hydrology.data.usgs import fetch_daily_values
from hydrology.data.climate import fetch_climate_data
from hydrology.analysis.trends import analyze_trend
from hydrology.visualization.plots import plot_flow_duration
# Fetch discharge data
site_id = "12354500" # Clark Fork at St. Regis, MT
discharge = fetch_daily_values(site_id, "2020-01-01", "2024-01-01")
# Fetch climate data
climate = fetch_climate_data(lat=47.3, lon=-115.1, start="2020-01-01", end="2024-01-01")
# Analyze trends
trend_result = analyze_trend(discharge)
print(f"Mann-Kendall p-value: {trend_result['p_value']}")
# Generate plots
fig = plot_flow_duration(discharge, site_id)
fig.savefig("flow_duration.png")hydrology/
├── core/ # Configuration and utilities
│ ├── config.py # JSON/YAML config management
│ ├── parameters.py # USGS parameter codes (discharge, stage, temp, etc.)
│ ├── paths.py # Portable path handling
│ ├── logging_setup.py # Centralized logging
│ ├── timezone.py # Timezone normalization (UTC)
│ └── huc_regions.py # HUC watershed region definitions
│
├── data/ # Data fetching modules
│ ├── usgs.py # USGS NWIS daily/instantaneous values
│ ├── climate.py # Meteostat temperature/precipitation
│ ├── inventory.py # Local site inventory parsing
│ ├── national_inventory.py # National USGS inventory by HUC-2
│ ├── nwm.py # NOAA National Water Model forecasts
│ └── nldi.py # USGS NLDI river network navigation
│
├── analysis/ # Statistical analysis
│ ├── trends.py # Mann-Kendall, linear regression trends
│ ├── stage_discharge.py # Power-law rating curve fitting
│ ├── alerts.py # Threshold-based alert monitoring
│ ├── multisite.py # Cross-site correlation analysis
│ └── flood_events.py # Flood event detection and animation
│
├── visualization/ # Plotting
│ ├── plots.py # 23+ plot functions
│ └── composer.py # Multi-panel layout system
│
├── app/ # Streamlit dashboard
│ ├── streamlit_app.py # Main application
│ ├── plot_config.py # Plot categorization
│ └── styles.py # Custom CSS and UI components
│
└── scripts/ # CLI tools
├── analyze_sites.py # Config-driven batch analysis
└── example_analysis.py # Example workflow
| Source | Data | API |
|---|---|---|
| USGS NWIS | Discharge, stage, water quality | https://waterservices.usgs.gov/nwis/ |
| Meteostat | Temperature, precipitation | Python library |
| USGS NLDI | River network topology | https://api.water.usgs.gov/nldi/ |
| NOAA NWM | Water model forecasts | https://api.water.noaa.gov/nwps/v1 |
| USGS WBD | HUC watershed boundaries | WMS layers |
Analysis can be configured via YAML or JSON files:
# configs/example.yaml
sites:
- site_id: "12354500"
name: "Clark Fork at St. Regis"
lat: 47.298
lon: -115.087
analysis:
start_date: "2020-01-01"
end_date: "2024-01-01"
plots:
- flow_duration
- annual_trend
- flood_frequency
alerts:
flood_threshold: 15000 # cfs
low_flow_threshold: 100 # cfs- Python 3.8+
- pandas >= 2.0.0
- numpy >= 1.24.0
- scipy >= 1.10.0
- matplotlib >= 3.7.0
- streamlit >= 1.28.0
- folium >= 0.14.0
- meteostat == 1.6.8
- scikit-learn >= 1.2.0
- pymannkendall >= 1.4.3
See requirements.txt for complete list.
MIT License - see LICENSE file.
- USGS - Streamflow data via NWIS API and HUC watershed boundary WMS layers
- NOAA - National Water Model forecasts via Water Prediction Service
- Meteostat - Climate data integration
- Streamlit - Web application framework
- Folium - Interactive mapping