category: Calculate the categories of events.

Description

Calculates the categories of MHWs or MCSs produced by detect_event in accordance with the naming scheme proposed in Hobday et al. (2018).

Usage

category(
  data,
  y = temp,
  S = TRUE,
  name = "Event",
  climatology = FALSE,
  MCScorrect = F,
  season = "range",
  roundVal = 4
)

Arguments

data

The function receives the full (list) output from the detect_event function.

The column containing the measurement variable. If the column name differs from the default (i.e. temp), specify the name here.

This argument informs the function if the data were collected in the southern hemisphere (TRUE, default) or the northern hemisphere (FALSE) so that it may correctly output the season column (see below).

name

If a character string (e.g. "Bohai Sea") is provided here it will be used to name the events in the event_name column (see below) of the output. If no value is provided the default output is "Event".

climatology

The default setting of FALSE will tell this function to output only the summary (wide) results for the individual events as seen in Hobday et al. (2018). If set to TRUE, this function will return a list of two dataframes, same as detect_event. The first dataframe climatology, contains the same information as found in detect_event, but with the addition of the daily intensity (anomaly above seasonal doy threshold) and category values. The second dataframe, event, is the summary results that this function produces by default.

MCScorrect

When calculating marine cold-spells (MCSs) it may occur in some areas that the bottom thresholds for the more intense categories will be below -1.8C, this is physically impossible on Earth, so if one wants to correct the bottom thresholds to not be able to exceed -1.8C, set this argument to TRUE (default is FALSE).

season

This argument allows the user to decide how the season(s) of occurrence for the MHWs are labelled. The default setting of "range" will return the range of seasons over which the MHW occurred, as seen in Hobday et al. (2018). One may chose to rather have this function return only the season during the "start", "peak", or "end" of the MHW by giving the corresponding character vector.

roundVal

This argument allows the user to choose how many decimal places the outputs will be rounded to. Default is 4. To prevent rounding set roundClm = FALSE. This argument may only be given numeric values or FALSE.

Value

The function will return a tibble with results similar to those seen in Table 2 of Hobday et al. (2018). This provides the information necessary to appraise the extent of the events in the output of detect_event based on the category ranking scale. The category thresholds are calculated based on the difference between the given seasonal climatology and threshold climatology. The four category levels are then the difference multiplied by the category level.

The definitions for the default output columns are as follows:

event_no

The number of the event as determined by detect_event to allow for joining between the outputs.

event_name

The name of the event. Generated from the name value provided and the year of the peak_date (see following) of the event. If no name value is provided the default "Event" is used. As proposed in Hobday et al. (2018), Moderate events are not given a name so as to prevent multiple repeat names within the same year. If two or more events ranked greater than Moderate are reported within the same year, they will be differentiated with the addition of a trailing letter (e.g. Event 2001a, Event 2001b).

peak_date

The date (day) on which the maximum intensity of the event was recorded.

Details

An explanation for the categories is as follows:

I Moderate-Events that have been detected, but with a maximum intensity that does not double the distance between the seasonal climatology and the threshold value.
II Strong-Events with a maximum intensity that doubles the distance from the seasonal climatology and the threshold, but do not triple it.
III Severe-Events that triple the aforementioned distance, but do not quadruple it.
IV Extreme-Events with a maximum intensity that is four times or greater than the aforementioned distance. Scary stuff...

References

Hobday et al. (2018). Categorizing and Naming Marine Heatwaves. Oceanography 31(2).

Examples

Run this code

# NOT RUN {
res_WA <- detect_event(ts2clm(sst_WA,
                       climatologyPeriod = c("1983-01-01", "2012-12-31")))
# Note that the name argument expects a character vector
cat_WA <- category(res_WA, name = "WA")
tail(cat_WA)

# If the data were collected in the northern hemisphere
# we must let the function know this, as seen below
res_Med <- detect_event(ts2clm(sst_Med,
                        climatologyPeriod = c("1983-01-01", "2012-12-31")))
cat_Med <- category(res_Med, S = FALSE, name = "Med")
tail(cat_Med)

# One may also choose to have this function output the daily
# category classifications as well by setting: climatology = TRUE
cat_WA_daily <- category(res_WA, name = "WA", climatology = TRUE)
head(cat_WA_daily$climatology)

# Note that this will not return the complete time series, only the
# days during which events were detected.
# This was done to reduce the size of the output for those working
# with gridded data.
# Should one want a complete time series, the daily category results
# may simply be left_join() with the detect_event() results
cat_WA_ts <- dplyr::left_join(res_WA$climatology,
                              cat_WA_daily$climatology)
head(cat_WA_ts)

# }

Run the code above in your browser using DataLab