exceedance {RmarineHeatWaves}

Detect consecutive days in exceedance of a given threshold.

Description

Detect consecutive days in exceedance of a given threshold.

Usage

exceedance(data, x = t, y = temp, threshold = 20, below = FALSE,
  min_duration = 5, join_across_gaps = TRUE, max_gap = 2,
  max_pad_length = 3)

Arguments

data

A data frame with at least the two following columns: a t column which is a vector of dates of class Date, and a temp column, which is the temperature on those given dates. If columns are named differently, their names can be supplied as x and y (see below). The function will not accurately detect consecutive days of temperatures in exceedance of the threshold if missing days of data are not filled in with NA. Data of the appropriate format are created by the function make_whole, but your own data may be used directly if they meet the given criteria.

x

This column is expected to contain a vector of dates as per the specification of make_whole. If a column headed t is present in the dataframe, this argument may be ommitted; otherwise, specify the name of the column with dates here.

y

This is a column containing the measurement variable. If the column name differs from the default (i.e. temp), specify the name here.

threshold

The static threshold used to determine how many consecutive days are in exceedance of the temperature of interest. Default is 20 degrees.

below

Default is FALSE. When set to TRUE, consecutive days of temperature below the threshold variable are calculated. When set to FALSE, consecutive days above the threshold variable are calculated.

min_duration

Minimum duration that temperatures must be in exceedance of the threshold variable. Default is 5 days.

join_across_gaps

A TRUE/FALSE statement that indicates whether or not to join consecutive days of temperatures in exceedance of the threshold across a small gap between groups before/after a short gap as specified by max_gap. Default is TRUE.

max_gap

The maximum length of the gap across which to connect consecutive days in exceedance of the threshold when join_across_gaps is TRUE.

max_pad_length

Specifies the maximum length of days over which to interpolate (pad) missing data (specified as NA) in the input temperature time series; i.e., any consecutive blocks of NAs with length greater than max_pad_length will be left as NA. Set as an integer. Default is 3 days.

Details

1. This function assumes that the input time series consists of continuous daily temperatures, with few missing values. The accompanying function make_whole aids in the preparation of a time series that is suitable for use with exceedance, although this may also be accomplished 'by hand' as long as the criteria are met as discussed in the documentation to make_whole.

2. Future versions seek to accomodate monthly and annual time series, too.

3. The calculation of onset and decline rates assumes that exceedance of the threshold started a half-day before the start day and ended a half-day after the end-day. This is consistent with the duration definition as implemented, which assumes duration = end day - start day + 1.

4. For the purposes of exceedance detection, any missing temperature values not interpolated over (through optional max_pad_length) will remain as NA. This means they will trigger the end of an exceedance if the adjacent temperature values are in exceedance of the threshold.

5. If the function is used to detect consecutive days of temperature under the given theshold, these temperatures are then taken as being in exceedance below the threshold as there is no antonym in the English language for 'exceedance'.

This function is based largely on the detect function found in this package, which was ported from the Python algorithm that was written by Eric Oliver, Institute for Marine and Antarctic Studies, University of Tasmania, Feb 2015, and is documented by Hobday et al. (2016).

Value

The function will return a list of two components. The first being threshold, which shows the daily temperatures and on which specific days the given threshold was exceeded. The second component of the list is exceedance, which shows a medley of statistics for each discrete group of days in exceedance of the given threshold. Note that any additional columns left in the data frame given to this function will be output in the threshold component of the output. For example, if one uses make_whole to prepare a time series for analysis and leaves in the doy column, this column will appear in the output.

The information shown in the threshold component is:

t

The date of the temperature measurement. This variable may named differently if an alternative name is supplied to the function's x argument.

temp

Temperature on the specified date [deg. C]. This variable may named differently if an alternative name is supplied to the function's y argument.

thresh

The static threshold chosen by the user [deg. C].

thresh_criterion

Boolean indicating if temp exceeds threshold.

duration_criterion

Boolean indicating whether periods of consecutive thresh_criterion are >= min_duration.

exceedance

Boolean indicting if all criteria that define a discrete group in exceedance of the threshold are met.

exceedance_no

A sequential number indicating the ID and order of occurence of exceedances.

The individual exceedances are summarised using the following metrics:

index_start

Row number on which exceedance starts.

index_stop

Row number on which exceedance stops.

exceedance_no

The same sequential number indicating the ID and order of the exceedance as found in the threshold component of the output list.

duration

Duration of exceedance [days].

date_start

Start date of exceedance [date].

date_stop

Stop date of exceedance [date].

date_peak

Date of exceedance peak [date].

int_mean

Mean intensity [deg. C].

int_max

Maximum (peak) intensity [deg. C].

int_var

Intensity variability (standard deviation) [deg. C].

int_cum

Cumulative intensity [deg. C x days].

rate_onset

Onset rate of exceedance [deg. C / day].

rate_decline

Decline rate of exceedance [deg. C / day].

int_max_abs, int_mean_abs, int_var_abs, and int_cum_abs are as above except as absolute magnitudes rather than relative to the threshold.

Author(s)

Robert W. Schlegel, Albertus J. Smit

Examples

ts_dat <- make_whole(sst_WA)
res <- exceedance(ts_dat, threshold = 25)
# show first ten days of daily data:
res$threshold[1:10, ]
# show first five exceedances:
res$exceedance[1:5, ]