Detect consecutive days in exceedance of a given threshold.

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

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 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.

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.

Value

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.

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 accommodate 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 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.

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_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).

Author

Robert W. Schlegel, Albertus J. Smit

Examples

res <- exceedance(sst_WA, threshold = 25)
# show first ten days of daily data:
res$threshold[1:10, ] #> # A tibble: 10 × 7 #> t temp thresh threshCriterion durationCriterion 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 × 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>