Detect consecutive days in exceedance of a given threshold.
exceedance(data, x = t, y = temp, threshold = 20, below = FALSE,
min_duration = 5, join_across_gaps = TRUE, max_gap = 2,
max_pad_length = 3)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.
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.
This is a column containing the measurement variable. If the column
name differs from the default (i.e. temp), specify the name here.
The static threshold used to determine how many consecutive
days are in exceedance of the temperature of interest. Default is
20 degrees.
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.
Minimum duration that temperatures must be in exceedance
of the threshold variable. Default is 5 days.
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.
The maximum length of the gap across which to connect
consecutive days in exceedance of the threshold when
join_across_gaps is TRUE.
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.
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:
The date of the temperature measurement. This variable may named
differently if an alternative name is supplied to the function's x
argument.
Temperature on the specified date [deg. C]. This variable may
named differently if an alternative name is supplied to the function's y
argument.
The static threshold chosen by the user [deg. C].
Boolean indicating if temp exceeds
threshold.
Boolean indicating whether periods of consecutive
thresh_criterion are >= min_duration.
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 individual exceedances are summarised using the following metrics:
Row number on which exceedance starts.
Row number on which exceedance stops.
The same sequential number indicating the ID and
order of the exceedance as found in the threshold component of the
output list.
Duration of exceedance [days].
Start date of exceedance [date].
Stop date of exceedance [date].
Date of exceedance peak [date].
Mean intensity [deg. C].
Maximum (peak) intensity [deg. C].
Intensity variability (standard deviation) [deg. C].
Cumulative intensity [deg. C x days].
Onset rate of exceedance [deg. C / day].
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.
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 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 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.
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).
# NOT RUN {
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, ]
# }
Run the code above in your browser using DataLab