floodgb 0.3.0

Quick start

from floodgb import FloodGB
from sklearn.ensemble import HistGradientBoostingRegressor
from sklearn.pipeline import make_pipeline

lags = {
    rain_id:  (1, 48, 'sum'),    # DRIVER: one column per lag in [start, end]
    river_id: (72, 24, 'mean'),  # TARGET: (fore_len, target_period, agg)
}                                # fore_len is the number of models trained

m = FloodGB()
m.set_params([rain_id, river_id], river_id, 'h', lags)
m.set_model(make_pipeline(HistGradientBoostingRegressor(
    loss='squared_error', max_iter=100, learning_rate=0.05, early_stopping=False)))
m.train_models([precip, flow], break_time='2015-07-31',
               variables=['precipitation', 'streamflow'])
all_results, hf_results, max_results, predictions = m.test_models()
m.export('model.blt')

# later, operationally
forecast = FloodGB('model.blt').predict([precip, flow],
                                        variables=['precipitation', 'streamflow'])

Input is a list of xarray.Dataset with time and station_id; name the measurement with variables=. Datasets are flattened to one wide frame and merged by station id, so rainfall and flow arrive separately.

Choosing which gauges to use

floodgb.selection answers the operational question: how few rain gauges can the model depend on? Every extra gauge is another telemetry feed that can fail during the storm the model exists to forecast.

from floodgb import evaluate_subsets

res = evaluate_subsets(model, [precip, flow], river_id, candidate_ids, lags, 'h',
                       time_steps=[6, 24, 72], break_times=['2011-07-01', '2014-07-01'],
                       variables=['precipitation', 'streamflow'])
res.frontier()     # best subset at each size, per lead, with ties shown

It fits a model for every subset of the candidates and scores them all on one shared evaluation set. That is deliberately more expensive than ranking gauges by importance — and necessary, because no per-gauge score can express “these three are watching the same storm”. Rank and truncate, and you reliably select near-duplicates of one signal while discarding the independent gauges carrying the rest of it.

Three things it handles that a hand-rolled sweep usually does not:

• Fabricated zeros. Resampling rainfall with sum turns every gap — including a gauge’s entire pre-record span — into measured zero rainfall, not missing data. Those rows are removed.

• Comparability. Every subset is scored on the same rows, asserted at runtime.

• The evaluation window is computed, never hardcoded. A recorded window is only correct for the station set it was computed over, and station sets change.

Read the frontier per lead, and pass several break_times: on real records the winning subset moves with the forecast horizon, and with the train/test split.

Requirements

Python ≥ 3.11, pandas ≥ 2.2 (tested to 3.0), scikit-learn ≥ 1.3.1. Exported artifacts embed the training frame and hold pickled estimators, so pin scikit-learn in any environment that loads them.

License

Apache-2.0.