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.

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

Estimate MNiShed 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, time-domain, and recession decomposition in HydrographSeparation. None entries in Priors.recession_coeff mean the coefficient 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 mnished 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 mnished.Priors(recession_coeff, recession_exponents, initial_depths, log_recession_coeff_bounds, bn, hs, n_reservoirs)

Data-driven parameter priors for MNiShed.

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

recession_coeff

Suggested recession coefficients [days], fastest reservoir first. These are e-folding timescales from hydrograph separation (b=1 linear fit); for b>1 they are not residence times but still serve as initial values for calibration. None entries indicate that the coefficient 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_recession_coeff_bounds

Calibration bounds in log10(days) for each log__recession_coeff_* 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