get_events {hydropeak}

Flow Fluctuation Events and Metrics

Description

Given a data frame (time series) of stage measurements, all increase (IC) and decrease (DC) events are determined and all metrics implemented in the package hydropeak (see all_metrics()) are computed and combined to a data frame. Optionally, NA events and constant events can be included. NA events occur due to missing stage measurement values. The beginning of NA events refers to the last measurement with a non-missing Q value. Constant events are events where the Q values stay constant over time. An event is uniquely identifiable through the combination of the event starting time (Time) and the gauging station identifier (ID).

Usage

get_events(x, mc.cores = 2L, omit.constant = TRUE, omit.na = TRUE, ...)

Arguments

x

Data frame (time series) of stage measurements which contains at least a column with ID of the gauging station (default: column index 1) column with date-time values (default: columns index 2) in character representation and a column with flow rates (default: column index 3). If the column indices differ from c(1, 2, 3), they have to be specified as ... argument in the format c(i, j, k).

mc.cores

Number of cores to use with parallel::mclapply(). On Windows, this will be set to 1.

omit.constant

A logical. If FALSE (default) it does not return events with constant measurements. Otherwise these events are included.

omit.na

A logical. If FALSE (default) it does not return missing value events. Otherwise these events are included.

...

Arguments to be passed to flow() to specify the date-time format in the input data (default: dd.mm.YYYY HH:MM), the time zone used for the conversion (default: Etc/GMT-1) and the column indices in the input data, which contain date-time values and flow rate values. The default indices are 1 (ID), 2 (date-time) and 3 (flow rate, Q), i.e. cols = c(1, 2, 3).

Value

A data frame which contains for every event in a given time series all metrics (all_metrics()), gauging station ID, event type, and starting time of an event. Included metrics are amp(), mafr(), mefr(), dur(), ratio(). These metrics are only computed for increasing (IC) and decreasing (DC) events. For all other events the values are set to 0 except for flow ratio that is set to 1. Event types are defined as follows:

• 0: Constant event after NA event or constant event as first event in time series

• 1: Constant event after DC

• 2: Increasing event (IC)

• 3: Constant event after IC

• 4: Decreasing event (DC)

• 5: NA event

Examples

# Data with multiple events and different stations
data(Q)
get_events(Q)

# including constant events
get_events(Q, omit.constant = FALSE)