Skip to contents

Convenience wrapper for marine heatwave event categories

Source: R/category3.R
category3.Rd

category3() is a convenience wrapper for adding or reading Hobday et al. (2018) categories (I Moderate, II Strong, III Severe, IV Extreme) for an event NetCDF file. New analyses should usually set category = TRUE in detect_event3 or detect3, which computes the same categories during event detection and avoids a second pass over the files.

Usage

category3(
  event_file,
  clim_file = NULL,
  hemisphere = "south",
  roundVal = 4L,
  S = NULL
)

Arguments

event_file

Path to the event NetCDF file from detect_event3.

clim_file

Path to the climatology NetCDF from ts2clm3. Only required when the event file does not contain pre-computed categories.

hemisphere

Character. Either "south" (default, austral: DJF = Summer) or "north" (boreal: DJF = Winter).

roundVal

Decimal places for rounding. Default 4.

S

Deprecated. Use hemisphere instead.

Value

A data.frame with columns: event_no, lon, lat, peak_date, category, intensity_max, duration, p_moderate, p_strong, p_severe, p_extreme, season.

Details

If the event file already contains categories, category3() reads those values directly and clim_file may be omitted. If the event file does not contain categories, clim_file is required so the category width can be computed from the seasonal and threshold climatologies.

Works for both marine heatwaves and cold-spells: the category width is |seas - thresh|, which is always positive regardless of whether the threshold is above (heatwave) or below (cold-spell) the seasonal mean.

Examples

# \donttest{
sst_file <- system.file("extdata/sst_test.nc", package = "heatwave3")
clim_file <- tempfile(fileext = ".nc")
event_file <- tempfile(fileext = ".nc")

detect3(sst_file, clim_file, event_file,
        climatologyPeriod = c("1982-01-01", "2011-12-31"))
#> Reading SST data from /tmp/RtmptnP3kw/temp_libpath10f40785ac7f0/heatwave3/extdata/sst_test.nc...
#> Error: NetCDF error in inq varid /tmp/RtmpbqjzHu/file16260738183a7.nc: NetCDF: Variable not found

cats <- category3(event_file, clim_file)
#> Error: Event file does not exist: /tmp/RtmpbqjzHu/file16260738183a7.nc
table(cats$category)
#> Error: object 'cats' not found
# }