Data-Driven Priors

suggest_priors() combines BrutsaertNieber recession analysis with HydrographSeparation to produce a coherent set of parameter starting points before any model run or calibration.

See the Tutorial: From Data to Calibrated Model for a full worked example.

hydroravens.suggest_priors(Q, P=None, n_reservoirs=3, dt=1.0, min_recession_days=3)

Estimate HydroRaVENS parameter priors from an observed discharge record.

Combines BrutsaertNieber recession analysis with HydrographSeparation to produce timescale estimates, recession exponents, and initial storage depths without running any model.

Parameters:

• Q (array-like) – Observed specific discharge time series [mm/day]. Must be non-negative and at daily resolution.

• P (array-like, optional) – Observed precipitation time series [mm/day], same length as Q. Improves the HydrographSeparation spectral decomposition when provided. Default None.

• n_reservoirs (int, optional) – Number of reservoirs in the intended model structure (2 or 3). Default 3.

• dt (float, optional) – Timestep [days]. Default 1.0.

• min_recession_days (int, optional) – Minimum recession length passed to BrutsaertNieber. Default 3.

Returns:

Object containing timescales, recession exponents, initial depths, calibration bounds, and the underlying analysis objects.

Return type:

Priors

Notes

Recession exponents are assigned as follows:

• Fastest reservoir (soil): the catchment-integrated B–N estimate b = 1 / (2 − n), where n is the slope of the log(−dQ/dt) vs log(Q) cloud. Treat as a calibration starting point.

• Slow reservoir (karst): the theoretical Brutsaert & Nieber (1977) long-time value, b ≈ 2.203. Consider fixing rather than calibrating.

• Deep reservoir (if present): b = 1.0 (linear).

Timescales come from the spectral + recession decomposition in HydrographSeparation. None entries in Priors.t_efold mean the timescale could not be resolved from the data; fall back to calibration defaults in that case.

The B–N slope and the overall b estimate reflect the catchment- integrated recession, not individual reservoir responses. They anchor the soil exponent but cannot distinguish the karst component directly — that is why the karst exponent defaults to the theoretical value.

Examples

>>> import pandas as pd
>>> from hydroravens import suggest_priors
>>> df = pd.read_csv('input.csv', parse_dates=['Date'])
>>> Q  = df['Specific Discharge [mm/day]'].values
>>> P  = df['Precipitation [mm/day]'].values
>>> pr = suggest_priors(Q, P=P, n_reservoirs=3)
>>> pr.summary()
>>> print(pr.to_yaml_snippet())

class hydroravens.Priors(t_efold, recession_exponents, initial_depths, log_t_efold_bounds, bn, hs, n_reservoirs)

Data-driven parameter priors for HydroRaVENS.

Produced by suggest_priors(); not intended to be instantiated directly.

t_efold

Suggested e-folding residence times [days], fastest reservoir first. None entries indicate that the timescale could not be estimated from the data (fall back to calibration defaults).

Type:

list of float

recession_exponents

Suggested power-law recession exponents, fastest reservoir first. The fastest reservoir uses the catchment-integrated B–N estimate; the slow (karst) reservoir uses the theoretical value (Brutsaert & Nieber 1977, b ≈ 2.203); deeper reservoirs default to 1.0 (linear).

Type:

list of float

initial_depths

Estimated initial storage depths [mm], fastest reservoir first.

Type:

list of float

log_t_efold_bounds

Calibration bounds in log10(days) for each log__t_efold_* parameter, as returned by get_parameter_priors().

Type:

dict

bn

Fitted Brutsaert & Nieber object; inspect bn.n_, bn.a_, or call bn.plot() for the recession cloud.

Type:

BrutsaertNieber

hs

Fitted HydrographSeparation object; call hs.summary() for full spectral decomposition detail.

Type:

HydrographSeparation

n_reservoirs

Number of reservoirs these priors are intended for.

Type:

int

summary()

Print a human-readable summary of all suggested priors.

Includes timescales, recession exponents, initial depths, and calibration bounds, alongside guidance on which values to fix versus calibrate.

to_yaml_snippet()

Return a YAML string snippet for the reservoirs: and initial_conditions: sections, populated with these priors.

The snippet is a starting point only; review and adjust before running calibration.

Return type:

str