detect {RmarineHeatWaves}

Detect heatwaves and cold-spells.

Description

Applies the Hobday et al. (2016) marine heat wave definition to an input time series of temperature along with a daily date vector.

Usage

detect(data, doy = doy, x = t, y = temp, climatology_start,
  climatology_end, pctile = 90, window_half_width = 5,
  smooth_percentile = TRUE, smooth_percentile_width = 31,
  clim_only = FALSE, min_duration = 5, join_across_gaps = TRUE,
  max_gap = 2, max_pad_length = 3, cold_spells = FALSE)

Arguments

data

A data frame with three columns. In the default setting (i.e. ommitting the arguments doy, x and y; see immediately below), the data set is expected to have the headers doy, t and temp. doy is the Julian day running from 1 to 366, but modified so that the day-of-year (doy) vector for non-leap-years runs 1...59 and then 61...366. For leap years the 60th day is February 29. The t column is a vector of dates of class Date, while temp is the measured variable (by default it is assumed to be temperature). Data of the appropriate format are created by the function make_whole, but your own data can be supplied if they meet the criteria specified by make_whole.

doy

If a column headed doy is not available, another column with Julian dates can be supplied. This argument accepts the name of that column. The default name is, of course, doy.

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.

climatology_start

Required. The start date for the period across which the (varying by day-of-year) seasonal cycle and extremes threshold are calculated.

climatology_end

Required. The end date for the period across which the (varying by day-of-year) seasonal cycle and extremes threshold are calculated.

pctile

Threshold percentile (%) for detection of extreme values. Default is 90th percentile. Please see cold_spells for more information about the calculation of marine cold spells.

window_half_width

Width of sliding window about day-of-year (to one side of the center day-of-year) used for the pooling of values and calculation of climatology and threshold percentile. Default is 5 days, which gives a window width of 11 days centered on the 6th day of the series of 11 days.

smooth_percentile

Boolean switch selecting whether to smooth the climatology and threshold percentile timeseries with a moving average of width smooth_percentile. Default is TRUE.

smooth_percentile_width

Full width of moving average window for smoothing climatology and threshold. Default is 31 days.

clim_only

Choose to calculate only the climatologies and not the events. Default is FALSE.

min_duration

Minimum duration for acceptance of detected MHWs. Default is 5 days.

join_across_gaps

Boolean switch indicating whether to join MHWs which occur before/after a short gap as specified by max_gap. Default is TRUE.

max_gap

Maximum length of gap allowed for the joining of MHWs. Default is 2 days.

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.

cold_spells

Boolean specifying if the code should detect cold events instead of heat events. Default is FALSE. Please note that the climatological thresholds for cold-spells are calculated the same as for heatwaves, meaning that pctile should be set the same regardless if one is calculating heatwaves or cold-spells. For example, if one wants to calculate heatwaves above the 90th percentile threshold (the default) one sets pctile = 90. Likewise, if one would like identify the most intense cold-spells one must also set pctile = 90, even though cold spells are in fact simply the coldest extreme events in a time series, which statistically equate to values below the 10th percentile.

Details

1. This function assumes that the input time series consists of continuous daily values with few missing values. Time ranges which start and end part-way through the calendar year are supported. The accompanying function make_whole aids in the preparation of a time series that is suitable for use with detect, although this may also be accomplished 'by hand' as long as the criteria are met as discussed in the documentation to make_whole.

2. It is recommended that a climatology period of at least 30 years is specified in order to capture decadal thermal periodicities. It is further advised that full the start and end dates for the climatology period result in full years, e.g. "1982-01-01" to "2011-12-31" or "1982-07-01" to "2012-06-30"; if not, this may result in an unequal weighting of data belonging with certain months within a time series.

3. This function supports leap years. This is done by ignoring Feb 29s for the initial calculation of the climatology and threshold. The values for Feb 29 are then linearly interpolated from the values for Feb 28 and Mar 1.

4. The calculation of onset and decline rates assumes that the events 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. As of version 0.15.7, an event that is already present at the beginning of a time series, or an event that is still present at the end of a time series, will report the rate of onset or the rate of decline as NA, as it is impossible to know what the temperature half a day before or after the start or end of the event is. This may be a departure from the python marineHeatWaves function.

5. For the purposes of event detection, any missing temperature values not interpolated over (through optional max_pad_length) will be set equal to the seasonal climatology. This means they will trigger the end/start of any adjacent temperature values which satisfy the event definition criteria.

6. If the code is used to detect cold events (coldSpells = TRUE), then it works just as for heat waves except that events are detected as deviations below the (100 - pctile)th percentile (e.g., the 10th instead of 90th) for at least 5 days. Intensities are reported as negative values and represent the temperature anomaly below climatology.

7. If only the climatology for the time series is required, and not the events themselves, this may be done by setting clim_only = TRUE.

The original Python algorithm 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 marine cold spell option was implemented in version 0.13 (21 Nov 2015) of the Python module as a result of our preparation of Schlegel et al. (submitted), wherein the cold events receive a brief overview.

Value

The function will return a list of two tibbles (see the tidyverse), clim and event, which are the climatology and events, respectively. The climatology contains the full time series of daily temperatures, as well as the the seasonal climatology, the threshold and various aspects of the events that were detected. The software was designed for detecting extreme thermal events, and the units specified below reflect that intended purpose. However, the various other kinds of extreme events may be detected according to the 'marine heat wave' specifications, and if that is the case, the appropriate units need to be determined by the user.

doy

Julian day (day-of-year). For non-leap years it runs 1...59 and 61...366, while leap years run 1...366. This column will be named differently if another name was specified to the doy argument.

t

The date of the temperature measurement. This column will be named differently if another name was specified to the x argument.

temp

If the software was used for the purpose for which it was designed, seawater temperature [deg. C] on the specified date will be returned. This column will of course be named differently if another kind of measurement was specified to the y argument.

seas_clim_year

Climatological seasonal cycle [deg. C].

thresh_clim_year

Seasonally varying threshold (e.g., 90th percentile) [deg. C].

var_clim_year

Seasonally varying variance (standard deviation) [deg. C].

thresh_criterion

Boolean indicating if temp exceeds thresh_clim_year.

duration_criterion

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

event

Boolean indicating if all criteria that define a MHW or MCS are met.

event_no

A sequential number indicating the ID and order of occurence of the MHWs or MCSs.

The events are summarised using a range of event metrics:

index_start

Start index of event.

index_stop

Stop index of event.

event_no

A sequential number indicating the ID and order of the events.

duration

Duration of event [days].

date_start

Start date of event [date].

date_stop

Stop date of event [date].

date_peak

Date of event 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 event [deg. C / day].

rate_decline

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

int_max_rel_thresh, int_mean_rel_thresh, int_var_rel_thresh, and int_cum_rel_thresh are as above except relative to the threshold (e.g., 90th percentile) rather than the seasonal climatology.

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 seasonal climatology or threshold.

int_max_norm and int_mean_norm are as above except units are in multiples of threshold exceedances, i.e., a value of 1.5 indicates the event intensity (relative to the climatology) was 1.5 times the value of the threshold (relative to climatology, i.e., threshold - climatology.)

Note that rate_onset and rate_decline will return NA when the event begins/ends on the first/last day of the time series. This may be particularly evident when the function is applied to large gridded data sets. Although the other metrics do not contain any errors and provide sensible values, please take this into account in its interpretation.

Author(s)

Albertus J. Smit, Robert W. Schlegel, Eric C. J. Oliver

References

Hobday, A.J. et al. (2016). A hierarchical approach to defining marine heatwaves, Progress in Oceanography, 141, pp. 227-238, doi:10.1016/j.pocean.2015.12.014

Schlegel, R. W., Oliver, C. J., Wernberg, T. W., Smit, A. J. (2017). Coastal and offshore co-occurrences of marine heatwaves and cold-spells. Progress in Oceanography, 151, pp. 189-205, doi:10.1016/j.pocean.2017.01.004

Examples

ts_dat <- make_whole(sst_WA)
res <- detect(ts_dat, climatology_start = "1983-01-01",
              climatology_end = "2012-12-31")
# show a portion of the climatology:
res$clim[1:10, ]
# show some of the heat waves:
res$event[1:5, 1:10]