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 )
A data frame with at least the two following columns:
This column is expected to contain a vector of dates as per the
This is a column containing the measurement variable. If the column
name differs from the default (i.e.
The static threshold used to determine how many consecutive days are in exceedance of the temperature of interest.
Minimum duration that temperatures must be in exceedance
A TRUE/FALSE statement that indicates whether
or not to join consecutive days of temperatures in exceedance of the
The maximum length of the gap across which to connect
consecutive days in exceedance of the
Specifies the maximum length of days over which to
interpolate (pad) missing data (specified as
The function will return a list of two components. The first being
threshold, which shows the daily temperatures and on which specific days
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
doy column, this column will appear in the output.
The information shown in the
threshold component is:
The date of the temperature measurement. This variable may named
differently if an alternative name is supplied to the function's
Temperature on the specified date [deg. C]. This variable may
named differently if an alternative name is supplied to the function's
threshold chosen by the user [deg. C].
Boolean indicating if
Boolean indicating whether periods of consecutive
thresh_criterion are >=
Boolean indicting if all criteria that define a discrete
group in exceedance of the
threshold are met.
A sequential number indicating the ID and order of occurence of exceedances.
The same sequential number indicating the ID and
order of the exceedance as found in the
threshold component of the
Row number on which exceedance starts.
Row number on which exceedance peaks.
Row number on which exceedance ends.
Duration of exceedance [days].
Start date of exceedance [date].
Date of exceedance peak [date].
End date of exceedance [date].
Mean intensity [deg. C].
Maximum (peak) intensity [deg. C].
Intensity standard deviation [deg. C].
Cumulative intensity [deg. C x days].
Onset rate of exceedance [deg. C / day].
Decline rate of exceedance [deg. C / day].
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
Future versions seek to accomodate 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
If the function is used to detect consecutive days of temperature under
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).
res <- exceedance(sst_WA, threshold = 25) # show first ten days of daily data: res$threshold[1:10, ]#> # A tibble: 10 x 7 #> t temp thresh threshCriterion durationCriteri… exceedance #> <date> <dbl> <dbl> <lgl> <lgl> <lgl> #> 1 1982-01-01 20.9 25 FALSE FALSE FALSE #> 2 1982-01-02 21.2 25 FALSE FALSE FALSE #> 3 1982-01-03 21.4 25 FALSE FALSE FALSE #> 4 1982-01-04 21.2 25 FALSE FALSE FALSE #> 5 1982-01-05 21.3 25 FALSE FALSE FALSE #> 6 1982-01-06 21.6 25 FALSE FALSE FALSE #> 7 1982-01-07 21.7 25 FALSE FALSE FALSE #> 8 1982-01-08 21.5 25 FALSE FALSE FALSE #> 9 1982-01-09 21.4 25 FALSE FALSE FALSE #> 10 1982-01-10 21.4 25 FALSE FALSE FALSE #> # … with 1 more variable: exceedance_no <int># show first five exceedances: res$exceedance[1:5, ]#> # A tibble: 5 x 18 #> exceedance_no index_start index_peak index_end duration date_start date_peak #> <dbl> <dbl> <dbl> <dbl> <dbl> <date> <date> #> 1 1 2682 2683 2686 5 1989-05-05 1989-05-06 #> 2 2 6342 6351 6358 17 1999-05-13 1999-05-22 #> 3 3 6362 6363 6368 7 1999-06-02 1999-06-03 #> 4 4 6686 6688 6691 6 2000-04-21 2000-04-23 #> 5 5 6698 6699 6707 10 2000-05-03 2000-05-04 #> # … with 11 more variables: date_end <date>, intensity_mean <dbl>, #> # intensity_max <dbl>, intensity_var <dbl>, intensity_cumulative <dbl>, #> # intensity_mean_abs <dbl>, intensity_max_abs <dbl>, intensity_var_abs <dbl>, #> # intensity_cum_abs <dbl>, rate_onset <dbl>, rate_decline <dbl>