Calculates the categories of a series of events as produced by detect_event in accordance with the naming scheme proposed in Hobday et al. (2018).

category(data, y = temp, S = TRUE, name = "Event",
  climatology = FALSE)

Arguments

data

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

y

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

S

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 provide 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 rather return a list of two data frames, 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 and category values. The second dataframe, event, is the summary results that this function produces by default.

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 for reference 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 withiin the same year, they will be differentiated with the addition of a trailing letter (e.g. Event 2001 a, Event 2001 b). (still in development)

peak_date

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

category

The maximum category threshold reached/exceeded by the event.

i_max

The maximum intensity of the event above the threshold value.

duration

The total duration (days) of the event. Note that this includes any possible days when the measurement value y) may have dropped below the threshold value. Therefore, the proportion of the event duration (days) spent above certain thresholds may not add up to 100% (see following four items).

p_moderate

The proportion of the total duration (days) spent at or above the first threshold, but below any further thresholds.

p_strong

The proportion of the total duration (days) spent at or above the second threshold, but below any further thresholds.

p_severe

The proportion of the total duration (days) spent at or above the third threshold, but below the fourth threshold.

p_extreme

The proportion of the total duration (days) spent at or above the fourth and final threshold. There is currently no recorded event that has exceeded a hypothetical fifth threshold so none is calculated... yet..

season

The season(S) during which the event occurred. If the event occurred across two seasons this will be displayed as "Winter/Spring". Across three seasons as "Winter-Summer". Events lasting across four or more seasons are listed as "Year-round". December (June) is used here as the start of Austral (Boreal) summer.

If climatology = TRUE, this function will output a list of two dataframes. The first dataframe, climatology, will contain only the following columns:
t

The column containing the daily date values.

event_no

The numeric event number label.

intensity

The total exceedance (default is degrees C) above the 90th percentile threshold.

category

The category classification per day.

The second dataframe, event, contains the default output of this function, as detailed above.

Details

An explanation for the categories is as follows:

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

  2. II Strong-Events with a maximum intensity that doubles the distance from the seasonal climatology and the threshold, but do not triple it.

  3. III Severe-Events that triple the aforementioned distance, but do not quadruple it.

  4. IV Extreme-Events with a maximum intensity that is four times or greater the aforementioned distance. Scary stuff...

References

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

Examples

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)
#> # A tibble: 6 x 11 #> event_no event_name peak_date category i_max duration p_moderate p_strong #> <dbl> <fct> <date> <chr> <dbl> <dbl> <dbl> <dbl> #> 1 40 WA 2010 2010-12-02 II Stro… 2.66 15 73 27 #> 2 31 WA 2008 2008-04-14 III Sev… 3.77 34 62 29 #> 3 22 WA 1999 1999-05-22 II Stro… 3.6 95 59 41 #> 4 58 WA 2014 2014-08-31 II Stro… 2.2 12 58 42 #> 5 61 WA 2015 2015-10-02 II Stro… 2.43 7 57 43 #> 6 42 WA 2011 2011-02-28 IV Extr… 6.51 60 47 32 #> # … with 3 more variables: p_severe <dbl>, p_extreme <dbl>, season <chr>
# If the data were collected in the northern hemisphere # we must let the funciton 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)
#> # A tibble: 6 x 11 #> event_no event_name peak_date category i_max duration p_moderate p_strong #> <dbl> <fct> <date> <chr> <dbl> <dbl> <dbl> <dbl> #> 1 84 Med 2017 2017-04-12 II Stro… 2.6 24 58 42 #> 2 28 Med 2003 2003-06-20 II Stro… 5.02 30 57 43 #> 3 62 Med 2012 2012-08-20 II Stro… 4.22 18 56 44 #> 4 70 Med 2014 2014-10-18 II Stro… 3.31 144 49 50 #> 5 87 Med 2018 2018-04-21 II Stro… 3.32 14 43 57 #> 6 44 Med 2007 2007-04-25 III Sev… 4.02 19 42 53 #> # … with 3 more variables: p_severe <dbl>, p_extreme <dbl>, season <chr>
# 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)
#> # A tibble: 6 x 4 #> t event_no intensity category #> <date> <dbl> <dbl> <chr> #> 1 1984-06-03 1 1.35 I Moderate #> 2 1984-06-04 1 1.34 I Moderate #> 3 1984-06-05 1 1.34 I Moderate #> 4 1984-06-06 1 1.35 I Moderate #> 5 1984-06-07 1 1.36 I Moderate #> 6 1984-06-17 2 1.46 I Moderate
# 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)
#> Joining, by = c("t", "event_no")
head(cat_WA_ts)
#> # A tibble: 6 x 11 #> doy t temp seas thresh threshCriterion durationCriteri… event #> <dbl> <date> <dbl> <dbl> <dbl> <lgl> <lgl> <lgl> #> 1 1 1982-01-01 20.9 21.6 23.0 FALSE FALSE FALSE #> 2 2 1982-01-02 21.2 21.6 23.0 FALSE FALSE FALSE #> 3 3 1982-01-03 21.4 21.7 23.0 FALSE FALSE FALSE #> 4 4 1982-01-04 21.2 21.7 23.1 FALSE FALSE FALSE #> 5 5 1982-01-05 21.3 21.7 23.1 FALSE FALSE FALSE #> 6 6 1982-01-06 21.6 21.7 23.1 FALSE FALSE FALSE #> # … with 3 more variables: event_no <dbl>, intensity <dbl>, category <chr>