exceedance: Detect consecutive days in exceedance of a given threshold.
In heatwaveR: Detect Heatwaves and Cold-Spells

Description Usage Arguments Details Value Author(s) Examples

Detect consecutive days in exceedance of a given threshold.

exceedance(
  data,
  x = t,
  y = temp,
  threshold,
  below = FALSE,
  minDuration = 5,
  joinAcrossGaps = TRUE,
  maxGap = 2,
  maxPadLength = FALSE
)

`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 omitted; 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.
`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.
`minDuration`	Minimum duration that temperatures must be in exceedance of the `threshold` variable. The default is `5` days.
`joinAcrossGaps`	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 `maxGap`. The default is `TRUE`.
`maxGap`	The maximum length of the gap across which to connect consecutive days in exceedance of the `threshold` when `joinAcrossGaps = TRUE`.
`maxPadLength`	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 `maxPadLength` will be left as `NA`. Set as an integer. The default is `3` days.

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.
Future versions seek to accommodate monthly and annual time series, too.
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.
For the purposes of exceedance detection, any missing temperature values not interpolated over (through optional maxPadLength) 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.
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_event 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).

The function will return a list of two tibbles (see the tidyverse). 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 ts2clm 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 >= `minDuration`.
`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 occurrence of exceedances.

The individual exceedances are summarised using the following metrics:

`exceedance_no`	The same sequential number indicating the ID and order of the exceedance as found in the `threshold` component of the output list.
`index_start`	Row number on which exceedance starts.
`index_peak`	Row number on which exceedance peaks.
`index_end`	Row number on which exceedance ends.
`duration`	Duration of exceedance [days].
`date_start`	Start date of exceedance [date].
`date_peak`	Date of exceedance peak [date].
`date_end`	End date of exceedance [date].
`intensity_mean`	Mean intensity [deg. C].
`intensity_max`	Maximum (peak) intensity [deg. C].
`intensity_var`	Intensity standard deviation [deg. C].
`intensity_cumulative`	Cumulative intensity [deg. C x days].
`rate_onset`	Onset rate of exceedance [deg. C / day].
`rate_decline`	Decline rate of exceedance [deg. C / day].

intensity_max_abs, intensity_mean_abs, intensity_var_abs, and intensity_cum_abs are as above except as absolute magnitudes rather than relative to the threshold.

Robert W. Schlegel, Albertus J. Smit

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