hydrotools.events.event_detection.decomposition module#

Event Detection :: Decomposition#

Use time series decomposition to detect hydrological events in streamflow time series as described in Regina & Ogden, 2020.

Regina, J.A., F.L. Ogden, 2020. Automated Correction of Systematic: Errors in High-Frequency Stage Data from V-Notch Weirs using Time Series Decomposition., Under review., Hydrol. Proc.

Functions#

rolling_minimum detrend_streamflow mark_event_flows find_local_minimum event_boundaries list_events

hydrotools.events.event_detection.decomposition.detrend_streamflow(series: Series, halflife: float | str | Timedelta, window: int | DateOffset | Index) → Series#

Model the trend in a streamflow time series using a rolling minimum filter. Remove the trend and residual components. The method aims to produce a detrended time series with a median of 0.0. It assumes any residual components less than twice the detrended median are random noise. Return the detrended streamflow time series.

Parameters:

series (pandas.Series with a DateTimeIndex, required) – The original streamflow time series.
halflife (float, str, timedelta, required) – Specifies the decay term for pandas.Series.ewm.mean. This filter is used to smooth over interevent noise and reduce detection of normal instrument fluctuations as events.
window (int, offset, or BaseIndexer subclass, required) – Size of the moving window for pandas.Series.rolling.min. This filter is used to model the trend in series.

Returns:

detrended – New streamflow time series with trend removed.

Return type:

pandas.Series

hydrotools.events.event_detection.decomposition.event_boundaries(event_points: Series)#

Return a two column pandas.DataFrame with ‘start’ and ‘end’ event times generated from a time series of boolean event points.

Parameters:: event_points (pandas.Series) – Boolean time series where True indicates the associated value in the series is part of an event.
Returns:: events – A two column DataFrame with a row for each event detected. start and end columns indicate the boundaries of each event.
Return type:: pandas.DataFrame

hydrotools.events.event_detection.decomposition.find_local_minimum(origin: Timestamp, radius: float | str | Timedelta, timeseries: Series)#

Return Datetime of the local minimum value within radius of origin.

Parameters:

origin (pandas.Timestamp, required) – The central datetime around which to search.
radius (float, str, pd.Timedelta, required) – The search radius around origin to look for a minimum value.
timseries (pandas.Series with a DateTimeIndex, required) – The original time series to inspect.

Returns:

Datetime of the local minimum value.

Return type:

Index

Apply time series decomposition to mark event values in a streamflow time series. Discretize continuous event values into indiviual events. Return a DataFrame with one row for each event detected with start and end columns indicating the boundaries of each event.

Parameters:

series (pandas.Series with a DateTimeIndex, required) – The original streamflow time series.
halflife (float, str, timedelta, required) – Specifies the decay term for pandas.Series.ewm.mean. This filter is used to smooth over interevent noise and reduce detection of normal instrument fluctuations as events.
window (int, offset, or BaseIndexer subclass, required) – Size of the moving window for pandas.Series.rolling.min. This filter is used to model the trend in series.
minimum_event_duration (pandas.Timedelta, datetime.timedelta, numpy.timedelta64, str, int, optional, default '0h') – Enforce a minimum event duration. This should generally be set equal to halflife to reduce the number of false positives flagged as events.
start_radius (pandas.Timedelta, datetime.timedelta, numpy.timedelta64, str, int, optional, default '0h') – Shift event starts to a local minimum. Phase shifts imparted on the original signal may advance or delay event start times depending upon how much smoothing is required to eliminate noise.

Returns:

events – A two column DataFrame with a row for each event detected. start and end columns indicate the boundaries of each event.

Return type:

pandas.DataFrame

Model the trend in a streamflow time series by taking the max of two rolling minimum filters applied in a forward and backward fashion. Remove the trend and residual components. The method aims to produce a detrended time series with a median of 0.0. It assumes any residual components less than twice the detrended median are random noise. Return the boolean time series that indicates whether an individual value in the original streamflow time series is part of an event (True) or not part of an event (False).

Parameters:

series (pandas.Series with a DateTimeIndex, required) – The original streamflow time series.
halflife (float, str, timedelta, required) – Specifies the decay term for pandas.Series.ewm.mean. This filter is used to smooth over interevent noise and reduce detection of normal instrument fluctuations as events.
window (int, offset, or BaseIndexer subclass, required) – Size of the moving window for pandas.Series.rolling.min. This filter is used to model the trend in series.
minimum_event_duration (pandas.Timedelta, datetime.timedelta, numpy.timedelta64, str, int, optional, default '0h') – Enforce a minimum event duration. This should generally be set equal to halflife to reduce the number of false positives flagged as events.
start_radius (pandas.Timedelta, datetime.timedelta, numpy.timedelta64, str, int, optional, default '0h') – Shift event starts to a local minimum. Phase shifts imparted on the original signal may advance or delay event start times depending upon how much smoothing is required to eliminate noise.

Returns:

event_points – Boolean time series where True indicates the associated value in the series is part of an event.

Return type:

pandas.Series

hydrotools.events.event_detection.decomposition.rolling_minimum(series: Series, window: int | DateOffset | Index) → Series#

Model the trend in a streamflow time series using a rolling minimum filter. Return the trend of a streamflow time series.

Parameters:

series (pandas.Series with a DateTimeIndex, required) – The original streamflow time series.
window (int, offset, or BaseIndexer subclass, required) – Size of the moving window for pandas.Series.rolling.min. This filter is used to model the trend in series.

Returns:

trend – Approximate baseflow trend of original series.

Return type:

pandas.Series