Description Usage Arguments Details Value Author(s) References Examples
View source: R/RmarineHeatWaves.R
Applies the Hobday et al. (2016) marine heat wave definition to an input time series of temperature along with a daily date vector.
1 2 3 4 5 |
data |
A data frame with three columns. In the default setting (i.e. ommitting
the arguments |
doy |
If a column headed |
x |
This column is expected to contain a vector of dates as per the
specification of |
y |
This is a column containing the measurement variable. If the column
name differs from the default (i.e. |
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 |
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 |
smooth_percentile |
Boolean switch selecting whether to smooth the
climatology and threshold percentile timeseries with a moving average of
width |
smooth_percentile_width |
Full width of moving average window for smoothing
climatology and threshold. Default is |
clim_only |
Choose to calculate only the climatologies and not the
events. Default is |
min_duration |
Minimum duration for acceptance of detected MHWs.
Default is |
join_across_gaps |
Boolean switch indicating whether to join MHWs which
occur before/after a short gap as specified by |
max_gap |
Maximum length of gap allowed for the joining of MHWs. Default
is |
max_pad_length |
Specifies the maximum length of days over which to
interpolate (pad) missing data (specified as |
cold_spells |
Boolean specifying if the code should detect cold events
instead of heat events. Default is |
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
.
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.
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.
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.
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.
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.
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.
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 |
t |
The date of the temperature measurement. This column will be
named differently if another name was specified to the |
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 |
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 |
duration_criterion |
Boolean indicating whether periods of consecutive
|
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.
Albertus J. Smit, Robert W. Schlegel, Eric C. J. Oliver
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
1 2 3 4 5 6 7 | 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]
|
# A tibble: 10 x 10
doy date temp seas_clim_year thresh_clim_year var_clim_year
<dbl> <date> <dbl> <dbl> <dbl> <dbl>
1 1 1982-01-01 20.9 21.6 23.0 0.959
2 2 1982-01-02 21.2 21.6 23.0 0.964
3 3 1982-01-03 21.4 21.7 23.0 0.968
4 4 1982-01-04 21.2 21.7 23.1 0.973
5 5 1982-01-05 21.3 21.7 23.1 0.976
6 6 1982-01-06 21.6 21.7 23.1 0.980
7 7 1982-01-07 21.7 21.8 23.2 0.983
8 8 1982-01-08 21.5 21.8 23.2 0.986
9 9 1982-01-09 21.4 21.8 23.2 0.988
10 10 1982-01-10 21.4 21.8 23.3 0.991
# ... with 4 more variables: thresh_criterion <lgl>, duration_criterion <lgl>,
# event <lgl>, event_no <int>
# A tibble: 5 x 10
index_start index_stop event_no duration date_start date_stop date_peak
<int> <int> <int> <dbl> <date> <date> <date>
1 885 889 1 5 1984-06-03 1984-06-07 1984-06-05
2 899 904 2 6 1984-06-17 1984-06-22 1984-06-19
3 908 926 3 19 1984-06-26 1984-07-14 1984-07-10
4 1023 1029 4 7 1984-10-19 1984-10-25 1984-10-23
5 1033 1037 5 5 1984-10-29 1984-11-02 1984-10-30
# ... with 3 more variables: int_mean <dbl>, int_max <dbl>, int_var <dbl>
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.