Using a custom extreme event definition
The default extreme event definition for this package is a specific heat wave definition:
A is two or more days at or above a city-specific threshold temperature, with the threshold determined as the \(98^{th}\) percentile of year-round temperature in the city during some reference period (by default, 1990–1999).
However, many other definitions of heat waves have been used in scientific literature (e.g., (Smith, Zaitchik, and Gohlke 2013)), so researchers will often want to use alternative event definitions when identifying heat waves. Researchers might want to use a specific definition, for example, because it matches the definition used by local health officials to declare heat wave warnings or, in the case of health impact assessments, to match with a definition used in an epidemiological study. Further, users will need to use a different definition when identifying other extreme events, like cold waves or periods of extremely high or low precipitation.
Several components of the extreme event definition can be easily customized in the gen_hw_set function call, without creating a new R function to use to identify extreme events. The customization of the extreme event definition is even more extensive as one has the option of writing a custom R function.
First, the percentile used to identify an extreme event can be changed using the probThreshold option in gen_hw_set. This option can take values between 0 and 1. The default value is 0.98, or a definition with a threshold of the \(98^{th}\) percentile of the location’s temperature. For example, to identify heat waves as two or more days at or above the city’s 99th percentile of year-round temperature, the user could run:
gen_hw_set(out = "example_results",
dataFolder = projection_dir_location ,
dataDirectories = list("historical" = c(1990, 1999),
"rcp85" = c(2060, 2079)),
citycsv = city_file_location,
coordinateFilenames = "latitude_longitude_NorthAmerica_12mo.csv",
tasFilenames = "tas_NorthAmerica_12mo.csv",
timeFilenames = "time_NorthAmerica_12mo.csv",
probThreshold = 0.99)
Second, the user can change the number of days used in the extreme event definition using the numDays argument in the gen_hw_set function.
Third, it is possible to specify the range of years that should be used when determining this threshold. For example, if you wanted to base the threshold for each location on its current climate, you could leave this option as its default, while if you wanted to use a different set of years (i.e. a threshold relative to future projected temperatures), you could set the start and end year bounds for this reference period using the thresholdBoundaries argument in the function gen_hw_set. For example, to use temperatures in each city from 2070 to 2079 to determine threshold temperatures, you would run:
gen_hw_set(out = "example_results",
dataFolder = projection_dir_location ,
dataDirectories = list("historical" = c(1990, 1999),
"rcp85" = c(2060, 2079)),
citycsv = city_file_location,
coordinateFilenames = "latitude_longitude_NorthAmerica_12mo.csv",
tasFilenames = "tas_NorthAmerica_12mo.csv",
timeFilenames = "time_NorthAmerica_12mo.csv",
thresholdBoundaries = c(2070, 2079))
Finally, if you’d like to identify extreme events below, rather than above, a certain threshold, you can do that with the above_threshold = FALSE argument in the gen_hw_set function. For example, to identify all cold spells in the example data, where a cold spell is defined as three or more days below the locations \(10^{th}\) percentile temperature, you can run:
gen_hw_set(out = "example_results",
dataFolder = projection_dir_location ,
dataDirectories = list("historical" = c(1990, 1999),
"rcp85" = c(2060, 2079)),
citycsv = city_file_location,
coordinateFilenames = "latitude_longitude_NorthAmerica_12mo.csv",
tasFilenames = "tas_NorthAmerica_12mo.csv",
timeFilenames = "time_NorthAmerica_12mo.csv",
above_threshold = FALSE,
probThreshold = 0.10,
numDays = 3)
It is also possible to use a completely customized extreme event definition. To do this, you will need to write and load a function that implements your chosen heat wave definition. You can then reference the custom function using the IDheatwavesFunction option in gen_hw_set. To work correctly, this custom function must allow only specific inputs and generate only specific outputs.
The function must allow the following inputs (even if it does not use them within the function code):
datafr: A data frame with columns for date and temperature for a community. The first column should be the date of each observation, in the Date class. The second column should be the temperature. If you are writing a custom function that uses an absolute threshold, it should be included in the function in the same units used for the input datasets (e.g., it should be based on Kelvin if using CMIP5 climate model output data).threshold: A single-value numerical vector; in the default definition, this is the threshold temperature for each community, as determined earlier in the function call, calculated as a percentile of the community’s year-round temperature. This should be an absolute temperature value, in the same units as the variable is expressed in the input data (Kelvin for CMIP5 climate model output data). Note: The code in the body of the function does not need to use this argument, and would not if you are setting the heat wave definition using an absolute temperature value, like \(90^oF\). However, even if the body of the code does not use this argument, you must include threshold as a possible argument in the header when defining your function, or you will get an error when you try to use the function with gen_hw_set.numDays: The number of days above the threshold required for an event.
The function must return only the input data frame (datafr), with the following columns added:
hw: A binary variable indicating whether a day was part of an extreme event (1: day was in an extreme event; 0: not in an extreme event) andhw.number: A non-negative integer that is 0 for all days that are not in an event and, for days in events, gives a unique number for each separate event. For example, all days in the first heat wave in the time series would get the value 1 for this column, all days in the second heat wave would get the value 2, etc., and all days not in heat waves would get the value 0.
To help in developing your own extreme event identification functions, the package includes an example of the required input data frame, datafr. You can load this data frame by calling:
If your extreme event identification function is properly set up to use in this package, it can take as input this example data frame and a threshold value and will return the original data frame with the columns hw and hw.number, as defined above, returned:
## date tmpd
## 20076 2061-01-01 30.452
## 20077 2061-01-02 30.668
## 20078 2061-01-03 35.294
id_of_hws <- IDHeatwavesR(datafr = datafr, threshold = 95, numDays = 2)
head(id_of_hws, 3)
## date tmpd hw hw.number
## 20076 2061-01-01 30.452 0 0
## 20077 2061-01-02 30.668 0 0
## 20078 2061-01-03 35.294 0 0
The custom function can then be passed to gen_hw_set using the IDheatwavesFunction argument. You should specify the function name in quotation marks for this argument. For example, we have included an alternative ID definition function in this package, called IDHeatwavesAlternative, which identifies heat waves as a certain number of days above the higher of either a community’s \(98^{th}\) percentile temperature or \(80^oF\). To use this as the heat wave definition, you would run:
gen_hw_set(out = "example_results",
dataFolder = projection_dir_location ,
dataDirectories = list("historical" = c(1990, 1999),
"rcp85" = c(2060, 2079)),
citycsv = city_file_location,
coordinateFilenames = "latitude_longitude_NorthAmerica_12mo.csv",
tasFilenames = "tas_NorthAmerica_12mo.csv",
timeFilenames = "time_NorthAmerica_12mo.csv",
IDheatwavesFunction = "IDHeatwavesAlternative")
As a note, if you are using a custom function to identify extreme events below a certain temperature, you will need to use a bit of hacking to get it to work correctly. This is because, when the above_threshold = FALSE argument is used for gen_hw_sets, the negative of all variable values are used at the point in processing when the event identification function is run. Please feel free to email the package maintainer if you are planning to use the package for this application to get more tips and help for this special case.
Customizing projection dates and dates for reference temperatures
By default, the function will generate extreme event datasets for climate model output from the years 2070 to 2079. This projection date range can be changed by specifying alternative starting and ending years in the projectionBoundaries argument of the gen_hw_set function (the years specified must be included in the climate model output data that you are using). For example, to create projections for 2060 to 2079, the user would call:
gen_hw_set(out = "example_results",
dataFolder = projection_dir_location ,
dataDirectories = list("historical" = c(1990, 1999),
"rcp85" = c(2060, 2079)),
citycsv = city_file_location,
coordinateFilenames = "latitude_longitude_NorthAmerica_12mo.csv",
tasFilenames = "tas_NorthAmerica_12mo.csv",
timeFilenames = "time_NorthAmerica_12mo.csv",
projectionBoundaries = c(2060, 2079))
The extreme events data sets characterize events in several ways that are based on relative values of the variable of interest. These characteristics are measured by taking the absolute variable measures of the event (e.g., average temperature during the heat wave is \(90^oF\)) and comparing them to the location’s typical distributions of the variable. This process generates relative measures of how intense the event is compared to what is normal in that location (e.g., \(90^oF\) is in the \(99^{th}\) percentile of year-round temperatures in the location).
The default in this characterization is to use variable distributions for the period 2070 to 2079 for these reference temperatures. However, the user can change this specification using the referenceBoundaries option of gen_hw_set. This functionality can be useful in exploring the role of adaptation in future heat waves. For example, to use temperature projections for 1990 to 1999 when calculating relative characteristics of heat waves, to explore the assumption that cities remain adapted to their present-day climate, rather than changing in adaptation as climate change increases temperatures, a user could run:
gen_hw_set(out = "example_results",
dataFolder = projection_dir_location ,
dataDirectories = list("historical" = c(1990, 1999),
"rcp85" = c(2060, 2079)),
citycsv = city_file_location,
coordinateFilenames = "latitude_longitude_NorthAmerica_12mo.csv",
tasFilenames = "tas_NorthAmerica_12mo.csv",
timeFilenames = "time_NorthAmerica_12mo.csv",
referenceBoundaries = c(1990, 1999))
If the date range used for these reference temperatures does not correspond to the dates used for the projection period, the reference temperatures will be pulled only from the ensemble member for each climate model specified using the threshold_ensemble argument in gen_hw_set.
For these date range specifications, there are some restrictions on which year ranges can be selected. The starting year cannot be earlier than the first year in the first subdirectory, the ending year cannot be later than the last year of the second subdirectory, and the custom date boundaries cannot span the two subdirectories.
Customizing settings for characterizing heatwaves
Two parameters in the gen_hw_set function can be set to customize the characteristics in the output dataframes. First, the extreme event files output by gen_hw_set include the column “mean.seasonal.var”, which by default gives the mean value of the variable in a study location for the months of May–September. If working with a variable or in a location for which different months comprise the “high” season for that type of extreme event, you can use the seasonal_months argument to customize the months included in this seasonal average, using a vector with numerical values for months (1 = January, 2 = February, etc.). For example, to set the season to the months of June through August in the earlier example of using gen_hw_set, you could call:
gen_hw_set(out = "example_results",
dataFolder = projection_dir_location ,
dataDirectories = list("historical" = c(1990, 1999),
"rcp85" = c(2060, 2079)),
citycsv = city_file_location,
coordinateFilenames = "latitude_longitude_NorthAmerica_12mo.csv",
tasFilenames = "tas_NorthAmerica_12mo.csv",
timeFilenames = "time_NorthAmerica_12mo.csv",
seasonal_months = c(6, 7, 8))
Note that this option does not restrict the period when heat waves are identified; rather, it specifies which subset of daily data should be used to calculate the “mean.seasonal.var” column in the output datasets.
Second, the heat wave characteristic datasets output by the package include four columns listing how many days in each extreme event were above specific absolute thresholds (“days.above.abs.threshold.1”, “days.above.abs.threshold.2”, “days.above.abs.threshold.3”, “days.above.abs.threshold.4”). By default, these thresholds are at the values of Kelvin that correspond to \(80^oF\), \(85^oF\), \(90^oF\), and \(95^oF\). You can customize these thresholds using the absolute_thresholds parameter in the gen_hw_set function. For example, to set thresholds at the Kelvin equivalents for \(26^oC\), \(28^oC\), \(30^oC\), and \(32^oC\), you can run:
library(weathermetrics)
gen_hw_set(out = "example_results",
dataFolder = projection_dir_location ,
dataDirectories = list("historical" = c(1990, 1999),
"rcp85" = c(2060, 2079)),
citycsv = city_file_location,
coordinateFilenames = "latitude_longitude_NorthAmerica_12mo.csv",
tasFilenames = "tas_NorthAmerica_12mo.csv",
timeFilenames = "time_NorthAmerica_12mo.csv",
absolute_thresholds = convert_temperature(c(26, 28, 30, 32),
old_metric = "c",
new_metric = "k"))
Note that the absolute_thresholds parameter only affects the thresholds used to calculate the four columns of the output that start with “days.above.abs.threshold”. Further, note that if you customize with absolute_thresholds, you must use a numerical vector with four values, and the values should be in the same units as the variable in the input data (e.g., Kelvin for CMIP5 climate model output data).
This functionality is likely to be especially useful when using this package to identify and characterize extended extreme events other than heat waves, like cold waves or air pollution events. A later section of this vignette gives more details of how to use the futureheatwaves package for these other types of events.
Mapping grid points
The package also has a function that allows you to plot the locations of grid points for each climate model that correspond with study locations, as well as show the links between climate grid points and associated locations, for US-based studies. The map_grid function allows you to specify a climate model (plot_model), as well as the location of your output directory (usually, this will be the directory specified using the out argument in gen_hw_set):
out <- system.file("extdata/example_results", package = "futureheatwaves")
map_grid(plot_model = "bcc1", out = out)
In this map, the points show the locations of grid points for that climate model that matched with study locations, and therefore were used in generating heat wave data sets. The lines on the map connect each climate model grid point to the study location(s) for which that grid point was used by gen_hw_set. This function requires that you use non-negative decimal degrees to express longitude values in both the climate projection files with grid point locations and in the community location file that are input to gen_hw_set.
Because the resulting plot is a “ggplot” object, you can use ggplot2 functions to change the formatting. For example, you could change the title and theme with the following code (results not shown):
a <- map_grid(plot_model = "bcc1", out = out)
a + ggtitle("BCC1 CMIP5 model") + theme_dark()
If you want to generate several of these maps for different climate models and then plot them together, you can use the grid.arrange function from the gridExtra package (results not shown):
library(gridExtra)
a <- map_grid(plot_model = "bcc1", out = out)
b <- map_grid(plot_model = "ccsm", out = out)
grid.arrange(a, b, ncol = 1)
As of version 1.0.3, the package has a new mapping function, map_grid_leaflet, which allows you to create interactive maps using the leaflet package and will also work for study cities anywhere. This function adds pop-ups labeling city locations (using the “city” column in the file designated with the citycsv parameter in gen_hw_set) and climate model grid point locations. The map, like any leaflet map, allows panning and zooming.
map_grid_leaflet(plot_model = "bcc1", out = out)
The development version, available on GitHub under the devel branch, also has the map_grid_ggmap function, which draws on ggmap functions to plot study cities and their matching climate model grid points on map background from Stamen Maps. The function is written to pull a background map just large enough to show all cities and climate model grid points. This mapping function works for study cities anywhere in the world. Here is the code to use to map study cities and matching climate model grid points for the example data included with the package:
map_grid_ggmap(plot_model = "bcc1", out = out)
