Package: hydrotools.events
OWPHydroTools :: EventsThis subpackage implements methods to partition hydrometric times series into discrete "events." See theEvents Documentationfor a complete list and description of the currently available methods. To report bugs or request new methods, submit an issue through theOWPHydroTools Issue Trackeron GitHub.InstallationIn accordance with the python community, we support and advise the usage of virtual
environments in any workflow using python. In the following installation guide, we
use python's built-invenvmodule to create a virtual environment in which the
tool will be installed. Note this is just personal preference, any python virtual
environment manager should work just fine (conda,pipenv, etc. ).# Create and activate python environment, requires python >= 3.8$python3-mvenvvenv
$sourcevenv/bin/activate
$python3-mpipinstall--upgradepip# Install events$python3-mpipinstallhydrotools.eventsUsageThe following example demonstrates how one might usehydrotools.events.event_detectionto extract hydrological events from a time series of real streamflow measurements. This example requires thehydrotools.nwis_clientpackage.Code# Import tools to retrieve data and detect eventsfromhydrotools.nwis_client.ivimportIVDataServicefromhydrotools.events.event_detectionimportdecompositionasev# Use pandas to resample the datafrompandasimportGrouper# Use a helper function to detect events at multiple sitesdeflist_events_helper(mi_series,level,halflife,window):"""Reduce multi-index series before applying event detection."""returnev.list_events(mi_series.droplevel(level),halflife,window)# Retrieve streamflow observations for two sitesservice=IVDataService()observations=service.get(sites='02146750,0214676115,09489000',startDT='2019-10-01',endDT='2020-09-30')# Drop extra columns to be more efficientobservations=observations[['usgs_site_code','value_date','value']]# Check for duplicate time series, keep first by defaultobservations=observations.drop_duplicates(subset=['usgs_site_code','value_date'])# Resample to hourly, keep first measurement in each 1-hour binobservations=observations.groupby(['usgs_site_code',Grouper(key='value_date',freq='H')]).first().ffill()# Detect eventsevents=observations['value'].groupby(level='usgs_site_code').apply(list_events_helper,level='usgs_site_code',halflife='6H',window='7D')# Print event listprint(events)Outputstart                 endusgs_site_code02146750       0  2019-10-13 22:00:00 2019-10-15 04:00:001  2019-10-16 09:00:00 2019-10-18 02:00:002  2019-10-19 03:00:00 2019-10-23 19:00:003  2019-10-27 05:00:00 2019-10-28 18:00:004  2019-10-30 01:00:00 2019-11-02 18:00:00...                               ...                 ...09489000       34 2020-09-16 00:00:00 2020-09-16 19:00:0035 2020-09-17 00:00:00 2020-09-17 15:00:0036 2020-09-18 04:00:00 2020-09-18 10:00:0037 2020-09-27 01:00:00 2020-09-27 03:00:0038 2020-09-28 05:00:00 2020-09-28 11:00:00Event Detection TipsTheevaluation_tools.events.event_detection.decompositionmethod has two main parameters:halflifeandwindow. These parameters are passed directly to underlying filters used to remove noise and model the trend in a streamflow time series (also calledbaseflow). Significant contiguous deviations from this trend are flagged as "events". This method was originally conceived to detect rainfall-driven runoff events in small watersheds from records of volumetric discharge or total runoff. Before using decomposition you will want to have some idea of the event timescales you hope to detect.In general you'll want to consider the following:Ensure your time series is monotonically increasing with a frequency significantly less than the frequency of events and fill missing dataUse apandas.Timedeltacompatiblestrto specifyhalflifeandwindow. See thepandas docsSpecify ahalflifelarger than the expected frequency of noise, but smaller than the event timescaleSpecify awindowlarger than the event timescale, but at least 4 to 5 times smaller than the entire length of the time seriesFilter the final list of events to remove false positive events, particularly in noisy signals. You could filter on peak event flow, event duration, or other event characteristics