USGS Streamflow Volatility Spike Risk (Next 7–14 Days)

Portfolio-ready, Kaggle-style prediction task built from USGS NWIS Daily Values discharge time series.

What you’re predicting

• Task: binary classification
• Predict: pred_vol_spike_next (probability in ([0,1]))
• Target: target_vol_spike_next — future log-flow volatility spikes within the next horizon
• Panelization: each (station, day) becomes two examples via horizon_d ∈ {7,14}

Data & evaluation highlights

• Rows: train 66,495, test 30,808
• Positive rate (train): ~0.097
• Split: time-based regime shift + deterministic bridge years (details in dataset_card.md)
• Metric: composite scorer (LogLoss overall + slice LogLoss + (1 − AUPRC)); see instruction.md
• Slice: slice_summer_lowflow stresses performance in dry-season low-flow regimes

Repository contents

• train.csv, test.csv, solution.csv
• sample_submission.csv, perfect_submission.csv
• build_dataset.py, build_meta.json
• score_submission.py
• instruction.md, golden_workflow.md, dataset_card.md

Quickstart

python build_dataset.py
python score_submission.py --submission-path sample_submission.csv --solution-path solution.csv

Baseline tips:

• Treat station_token and horizon_d as categorical
• Calibrate probabilities (LogLoss-heavy metric)

Why this is interesting (and non-trivial)

• Volatility is second-order: you’re forecasting future variability, not level.
• Horizon tradeoffs: 7-day volatility is noisier than 14-day; per-horizon calibration can help.
• Seasonal confounding: snowmelt/rain seasons create recurring patterns; the time split tests whether you learned robust signals.
• Slice pressure: slice_summer_lowflow stresses dry-season behavior where volatility spikes can be brief and hard to catch.

Target intuition

The label answers:

“Will the next window’s log-flow volatility jump into an unusually high regime?”

Source

USGS NWIS Water Services:

• https://waterservices.usgs.gov/
• Daily Values endpoint: https://waterservices.usgs.gov/nwis/dv/