Type:	Package
Title:	Detect and Characterize Sub-Daily Flow Fluctuations
Version:	0.1.2
Description:	An important environmental impact on running water ecosystems is caused by hydropeaking - the discontinuous release of turbine water because of peaks of energy demand. An event-based algorithm is implemented to detect flow fluctuations referring to increase events (IC) and decrease events (DC). For each event, a set of parameters related to the fluctuation intensity is calculated. The framework is introduced in Greimel et al. (2016) "A method to detect and characterize sub-daily flow fluctuations" <doi:10.1002/hyp.10773> and can be used to identify different fluctuation types according to the potential source: e.g., sub-daily flow fluctuations caused by hydropeaking, rainfall, or snow and glacier melt. This is a companion to the package 'hydroroute', which is used to detect and follow hydropower plant-specific hydropeaking waves at the sub-catchment scale and to describe how hydropeaking flow parameters change along the longitudinal flow path as proposed and validated in Greimel et al. (2022).
License:	GPL-2
Encoding:	UTF-8
LazyData:	true
RoxygenNote:	7.1.2
Depends:	R (≥ 4.1.0)
Suggests:	rmarkdown, knitr, testthat (≥ 3.0.0), data.table
Config/testthat/edition:	3
Imports:	utils, parallel
VignetteBuilder:	knitr
NeedsCompilation:	no
Packaged:	2022-11-13 20:27:01 UTC; gruen
Author:	Bettina Grün [cre, ctb], Julia Haider [aut], Franz Greimel [ctb]
Maintainer:	Bettina Grün <Bettina.Gruen@R-project.org>
Repository:	CRAN
Date/Publication:	2022-11-16 03:50:15 UTC

Events

Description

A complementary dataset to the flow fluctuation dataset Q. It contains the events and metrics such as computed by get_events().

Usage

Events

Format

A data frame with 165 rows and 8 variables:

ID

Character string which refers to the identifier of the gauging station (in Austria: HZBCODE)

EVENT_TYPE

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

Time

Date-time of event starting point

AMP

Amplitude (amp())

MAFR

Maximum flow fluctuation rate (mafr())

MEFR

Mean flow fluctuation rate (mefr())

DUR

Duration (dur())

RATIO

Flow ratio (ratio())

Flow Fluctuations Q

Description

A dataset containing sub-daily flow fluctuations of five consecutive days from two different gauging stations. One time step is 15 minutes.

Usage

Q

Format

A data frame with 960 rows and 3 variables:

ID

Character string which refers to the identifier of the gauging station (in Austria: HZBCODE)

Time

Character string with date-time information of stage measurements which needs to be converted to a compatible format (see flow())

Q

Flow, stage measurements in m^3/s

Event Based Fluctuation Flow Parameters

Description

Given an event with equal flow trend, all metrics implemented in the package hydropeak are computed and combined to a data frame. It includes also an identifier of the gauging station provided by the user and the starting time of the event.

Usage

all_metrics(x, id, event_type)

Arguments

Value

A data frame including all computed metrics, IDs of gauging stations, event type (see event_type() for an overview of possible event types), and starting time of an event x. Included metrics are amp(), mafr(), mefr(), dur(), ratio().

Examples

data(Q)
# decreasing event:
Q4 <- flow(Q[3:4, ])
all_metrics(Q4, id = Q$ID[1], event_type = 4)
all_metrics(Q4, id = Q$ID[1], event_type = event_type(Q4))

# increasing event:
Q2 <- flow(Q[486:487, ])
all_metrics(Q2, id = Q$ID[1], event_type = 2)
all_metrics(Q2, id = Q$ID[1], event_type = event_type(Q2))

# constant event (at beginning or after NA event):
Q0 <- flow(Q[1:3, ])
all_metrics(Q0, id = Q$ID[1], event_type = 0)
all_metrics(Q0, id = Q$ID[1], event_type = event_type(Q0))

AMP - Amplitude (Metric 1)

Description

The amplitude (AMP, unit: m^3/s) of an event is defined as the difference between the flow maximum (Q_{max}) and the flow minimum (Q_{min}). Given an event with equal flow trend, the amplitude is computed and returned.

Usage

amp(x)

Arguments

Value

Returns a positive numeric value which is the difference of max(x$Q) and min(x$Q) of an event. If a data frame containing NA flow rates (Q) is given, NA is returned.

Examples

data(Q)
Q <- flow(Q[3:4, ])
amp(Q)

Change Points

Description

Calculates flow (Q) differences of consecutive time steps and discriminates between time steps with increasing (IC: Q_{ts1} < Q_{ts2}) and decreasing (DC: Q_{ts1} > Q_{ts2}) flow. The differences are transformed to 1 or -1 if the number is positive or negative, respectively. Then the lengths of runs of equal values are computed to determine the change point indices in the input data frame. NA in Q values is replaced with 0 and treated as an equal trend.

Usage

change_points(x, rownames = FALSE, omit.constant = TRUE, omit.na = TRUE)

Arguments

Value

A data frame which contains change point indices in the input data frame. These are the indices where an event starts and ends, and a column which indicates the event (-1 = decreasing (DC), 1 = increasing (IC)).

DUR - Duration (Metric 4)

Description

The duration of an event is specified as the number of consecutive time steps with equal flow trend.

Usage

dur(x)

Arguments

Value

Returns an integer value which is the number of consecutive time steps.

Examples

data(Q)
Q <- flow(Q[3:4, ])
dur(Q)

Event Type

Description

Given a data frame (time series) of equal flow (Q) trend, it is determined whether the flow is increasing or decreasing, constant or if missing values occur. It returns a numeric value which indicates the event type. As the event type is already determined when the change points are computed, this function is mainly used for demonstration purpose or if metrics should be computed individually.

Usage

event_type(x)

Arguments

Value

Returns an numeric value which indicates the event type. 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(Q)
# decreasing event
Q4 <- flow(Q[3:4, ])
event_type(Q4)

# increasing event
Q2 <- flow(Q[486:487, ])
event_type(Q2)

'flow' S3 Class for Flow Rate Time Series

Description

The function flow() creates a flow rate time series object which is formatted to be compatible with the functions in the hydropeak package.

Usage

flow(
  x,
  format = "%d.%m.%Y %H:%M",
  tz = "Etc/GMT-1",
  cols = c(1, 2, 3),
  steplength = 15,
  full = TRUE
)

validate_flow(x)

Arguments

Value

Returns a flow object which inherits from data frame (time series). It contains at least a gauging station ID column (ID) converted to character values, a date-time column (Time) converted to class "POSIXlt" (see base::strptime()) and a flow rate column (Q), which is converted to numeric values. The flow() object ensures that input flow fluctuation time series data can be processed with the functions in the hydropeak package. Therefore, it is mandatory to provide the correct indices (see argument cols) and the correct date-time format (see argument format) of the input data frame.

Examples

data(Q)
Q <- flow(Q)

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

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)

Flow Fluctuation Events and Metrics from Input Directory

Description

Given a directory path it calls get_events_file() for each file in the directory, recursively. The resulting events are split into separate files for each gauging station ID (ID) and Event_Type and are written to the given output directory.

Usage

get_events_dir(
  Q_dir,
  inputsep = ";",
  inputdec = ".",
  outdir = file.path(tempdir(), "Events"),
  mc.cores = 2L,
  ...
)

Arguments

Value

No return value, called for side effects.

Examples

Q_dir <- "./inst/extdata"
get_events_dir(Q_dir, inputsep = ",", inputdec = ".")

Flow Fluctuation Events and Metrics from Input File

Description

Given a file path it reads a data frame (time series) of stage measurements and calls get_events(). The resulting events can be optionally written to a single file or to separate files for each gauging station ID (ID) and Event_Type. Files which produce errors return NULL.

Usage

get_events_file(
  Q_file,
  inputsep = ";",
  inputdec = ".",
  save = FALSE,
  split = TRUE,
  outdir = file.path(tempdir(), "Events"),
  mc.cores = 2L,
  return = TRUE,
  ...
)

Arguments

Value

A data frame which contains for every increase or decrease 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(). The returned data frame is not split. Returns NULL, if argument return is set to FALSE.

Examples

Q_file <- system.file("extdata", "Q.csv", package = "hydropeak")
# save to tempdir()
events <- get_events_file(Q_file, inputsep = ",", inputdec = ".",
save = TRUE, split = TRUE, return = TRUE)

MAFR - Maximum Flow Fluctuation Rate (Metric 2)

Description

The maximum flow fluctuation rate (MAFR, unit: m^3/s) represents the highest absolute flow change of two consecutive time steps within an event. Given an event with equal flow trend, the maximum flow fluctuation rate is computed and returned.

Usage

mafr(x)

Arguments

Value

Returns a numeric value which is the maximum (absolute) flow fluctuation rate. If a data frame containing NA flow rates (Q) is given, NA is returned.

Examples

data(Q)
Q <- flow(Q[3:4, ])
mafr(Q)

MEFR - Mean Flow Fluctuation Rate (Metric 3)

Description

The mean flow fluctuation rate (MEFR, unit: m^3/s^2) is calculated by the event amplitude divided by the number of time steps (duration) within an event. Given an event with equal flow trend, amplitude and duration are computed. From these metrics the mean flow fluctuation rate is calculated and returned.

Usage

mefr(x)

Arguments

Value

Returns a numeric value which is the mean flow fluctuation rate computed by the event amplitude amp() divided by the number of time steps dur(). If a data frame containing NA flow rates (Q) is given, NA is returned.

Examples

data(Q)
Q <- flow(Q[3:4, ])
mefr(Q)

RATIO - Flow Ratio (Metric 5)

Description

The metric flow ratio (RATIO) is defined as the flow maximum divided by the flow minimum, \frac{Q_{max}}{Q_{min}}. Given an event with equal flow trend, the flow ratio is computed and returned.

Usage

ratio(x, event_type)

Arguments

Value

Returns a numeric value which is the flow ratio computed by max(x$Q) divided by min(x$Q). If a data frame containing NA flow rates (Q) is given, NA is returned.

Examples

data(Q)
Q <- flow(Q[3:4, ])
ratio(Q, event_type(Q))