Analysis Module

Analytical helpers for SWMM subcatchment hydrograph data.

Functions in this module operate on pd.DataFrame objects returned by FeaturesSimulation.calculate_timeseries() and are intentionally decoupled from the simulation class itself.

catchment_simulation.analysis.runoff_volume(timeseries: DataFrame, column: str = 'runoff', start: Timestamp | datetime | None = None, end: Timestamp | datetime | None = None) → float

Compute total volume by integrating a flow-rate column over time.

Uses the trapezoidal rule. The result is in flow-unit x seconds (e.g. if the model uses CMS the volume is in cubic metres).

Note

Slicing with start / end uses pd.Series.loc which is inclusive on both endpoints for DatetimeIndex.

Parameters

timeseriespd.DataFrame

DataFrame with a DatetimeIndex as returned by FeaturesSimulation.calculate_timeseries().

columnstr, optional

Column to integrate, defaults to "runoff".

startpd.Timestamp | datetime | None, optional

Start of the integration window (inclusive). Defaults to the first timestamp.

endpd.Timestamp | datetime | None, optional

End of the integration window (inclusive). Defaults to the last timestamp.

Returns

float

Total volume over the selected interval.

Raises

ValueError

If column is not present or the (sliced) timeseries has fewer than 2 data points.

catchment_simulation.analysis.time_to_peak(timeseries: DataFrame, column: str = 'runoff') → Timedelta

Calculate the elapsed time from simulation start to the peak value.

Parameters

timeseriespd.DataFrame

DataFrame with a DatetimeIndex as returned by FeaturesSimulation.calculate_timeseries().

columnstr, optional

Column to analyse, defaults to "runoff".

Returns

pd.Timedelta

Time elapsed from the first timestamp to the peak.

Raises

ValueError

If timeseries is empty, column is not present, or all values in the column are zero (no meaningful peak).