CSIndicators (version 1.2.0)

CST_HeatIndex: Heat Index on s2dv_cube objects

Description

Heat Index computes the perceived temperature resulting from the combined effects of air temperature and relative humidity. It is used to indicate discomfort or potential health risks due to heat. The computation is based on an empirical formula developed by the U.S. National Weather Service (NWS), which estimates the apparent temperature under warm and humid conditions.

The index increases with higher humidity levels because the body's ability to cool itself through evaporation (sweating) becomes less effective.

Usage

CST_HeatIndex(
  temp,
  rh,
  start = NULL,
  end = NULL,
  temp_units_output = "C",
  time_dim = "time",
  fun = mean,
  ncores = NULL,
  na.rm = FALSE,
  ...
)

Value

An 's2dv_cube' object with the same shape as temp and rh, containing the Heat Index.

Arguments

temp

An 's2dv_cube' object with Temperatures. The structure of the s2dv cube should have the standard structure with data, dims, coords and attrs. The content should include variable name and units.

rh

An 's2dv_cube' object with Relative humidity. The structure of the s2dv cube should have the standard structure with data, dims, coords and attrs. The content should include variable name and units.

start

An optional parameter to defined the initial date of the period to select from the data by providing a list of two elements: the initial date of the period and the initial month of the period. By default it is set to NULL and the indicator is computed using all the data provided in data.

end

An optional parameter to define the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. By default it is set to NULL and the indicator is computed using all the data provided in data.

temp_units_output

A character string indicating the name of the units to compute the indicator. By default, it is set to 'C', Celsius.

time_dim

A character string indicating the name of the dimension to compute the indicator. By default, it is set to 'time'. More than one dimension name matching the dimensions provided in the object data$data can be specified.

fun

A function to be applied along the time dimension to aggregate the Heat Index. By default, the mean Heat Index is computed over time_dim. To keep the original temporal resolution (i.e., return values for each time step), set `fun = NULL`, in which case no aggregation is applied.

ncores

An integer indicating the number of cores to use in parallel computation.

na.rm

A logical value indicating whether to ignore NA values (TRUE) or not (FALSE).

...

Additional arguments passed to the aggregation function

Author

Alberto Bojaly,

References

National Weather Service (NWS): [Heat Index Equation](https://www.wpc.ncep.noaa.gov/html/heatindex_equation.shtml)

Examples

# --- s2dv cube creation for Temperature (K) ---
temp <- NULL
temp$data <- array(rnorm(100, mean = 300, sd = 5), 
                   c(member = 5, sdate = 3, time = 214, lon = 2, lat = 5))
temp$coords <- list(lat = 1:5, lon = 1:2)
variableT <- list(varName = 'tas', 
                  metadata = list(tas = list(units = 'K', long_name = '2m Temperature')))
temp$attrs <- list(Variable = variableT, 
                   Datasets = 'synthetic', 
                   when = Sys.time())

Dates <- c(seq(as.Date("2000-05-01"), as.Date("2000-11-30"), by = 'day'),
           seq(as.Date("2001-05-01"), as.Date("2001-11-30"), by = 'day'),
           seq(as.Date("2002-05-01"), as.Date("2002-11-30"), by = 'day'))
dim(Dates) <- c(sdate = 3, time = 214)
temp$attrs$Dates <- Dates
class(temp) <- "s2dv_cube"


# s2dv cube creation for Relative Humidity (%)
rh <- NULL
rh$data <- array(runif(100, min = 10, max = 100), 
                 c(member = 5, sdate = 3, time = 214, lon = 2, lat = 5))
rh$coords <- temp$coords
variableRH <- list(varName = 'hurs', 
                   metadata = list(hurs = list(units = '%', long_name = 'Relative Humidity')))
rh$attrs <- list(Variable = variableRH, 
                 Datasets = 'synthetic', 
                 when = Sys.time(), 
                 Dates = temp$attrs$Dates)
class(rh) <- "s2dv_cube"


# Example 1 : mean Heat Index (fun = mean by default)
HI_mean <- CST_HeatIndex(temp = temp, rh = rh)


#Example 2 : Input temporal resolution (no aggregation)
HI_full <- CST_HeatIndex(temp = temp, rh = rh, fun = NULL)


# Example 3 : 90% percentile calulation
HI_p90 <- CST_HeatIndex(
  temp = temp, rh = rh,
  fun = function(x, na.rm = TRUE) quantile(x, 0.90, na.rm = na.rm))


# Example 4 : Summer values (1 June to 31 August)
HI_summer <- CST_HeatIndex(
  temp = temp, rh = rh, fun = NULL,
  start = list(1, 6), end   = list(31, 8))