futureheatwaves (version 1.0.3)

gen_hw_set: Create and write extreme event projections

Description

This function creates datasets of identified and characterized extreme events for all ensemble members in all climate models in a directory of climate projections for a user-specified set of locations.The resulting extreme event projections are written out to a specified directory on the user's local computer. For more details on downloading CMIP5 climate model output data and setting it up to use with this function, see this package's "starting_from_netcdf" vignette.

Usage

gen_hw_set(out, dataFolder, dataDirectories = list(historical = c(1980, 2004), rcp85 = c(2006, 2099)), citycsv, coordinateFilenames, tasFilenames, timeFilenames, IDheatwavesFunction = "IDHeatwavesCPPwrapper", thresholdBoundaries = c(1990, 1999), projectionBoundaries = c(2070, 2079), referenceBoundaries = c(2070, 2079), models_to_run = "all", probThreshold = 0.98, numDays = 2, printWarning = TRUE, threshold_ensemble = "r1i1p1", lat_lon_colnames = c("lat", "lon"), above_threshold = TRUE, absolute_thresholds = c(299.82, 302.6, 305.37, 308.15), seasonal_months = c(5:9))

Arguments

out

Character string with pathway to directory to which extreme event files will be written. This should be a pathname to a directory on the user's local computer. If the directory already exists, it will be overwritten by this function, so the user should either specify a pathname for a directory that does not yet exist or be willing to overwrite the existing directory. The parent directory of the specified directory must exist.

dataFolder

Character string with pathway to a directory with climate projection data. This directory must have a specific structure-- see the futureheatwaves vignette for guidance on setting up this directory.

dataDirectories

A list object, with two elements, one for each of the two subdirectories included in the main directory. Typically, these will be separate directories of historical and projection experiments from climate models. Each element of the list should be named with the name of the subdirectory and should provide a numeric vector with the starting and ending years of the data within each of the two subdirectories (e.g., list("historical" = c(1990, 1999), "rcp85" = c(2060, 2079)) for a dataFolder with historical experiment data for 1990 to 1999 and RCP8.5 projections for 2060 to 2079).

citycsv

Character string giving the filepath to a comma-separated (.csv) file with, for each study city, a unique city identifier, latitude, and longitude. These values must be specified with the column names city, lat, and lon. See the futureheatwaves vignette for guidance on setting up this file.

coordinateFilenames

Character string the with filename of each grid point location file. This filename should be identical for all ensemble member subdirectories included in the dataFolder directory. See the package vignette for an example of the required structure for this file.

tasFilenames

Character string the with filename of each climate projection file. This filename should be identical for all ensemble member subdirectories included in the dataFolder directory. See the package vignette for an example of the required structure for this file.

timeFilenames

Character string the with filename of each projection dates file. This filename should be identical for all ensemble member subdirectories included in the dataFolder directory. See the package vignette for an example of the required structure for this file.

IDheatwavesFunction

A character string with the name of the R function to use to identify extreme events. This function may be a user-specified custom function, but it must be loaded into the current R session. The function name must be put in quotation marks. For more guidance on how to write and use a custom function to identify extreme events, see the package vignette for futureheatwaves.

thresholdBoundaries

A numeric vector with the custom time boundaries to be used to determine the threshold variable values for the extreme event definition. The required format for this vector is c(start year, end year), with the restriction that bounds must be contained within the time boundaries of one of the two experiment subdirectories specified by the dataDirectories argument in gen_hw_set. The default value is 1990 to 1999.

projectionBoundaries

A numeric vector with the custom time boundaries for which the user wants to create extreme event projections. The required format for this vector is c(start year, end year), with the restriction that bounds must be contained within the time boundaries of one of the two experiment subdirectories specified by the dataDirectories argument in gen_hw_set. The default value is 2070 to 2079.

referenceBoundaries

A numeric vector with the custom time boundaries to use in calculating relative characteristics for extreme events (i.e., to use when exploring the role of adaptation in projections). For more information on how reference temperatures are used, see the package vignette for futureheatwaves. The required format for this vector is c(start year, end year), with the restriction that bounds must be contained within the time boundaries of one of the two experiment subdirectories specified by the dataDirectories argument in gen_hw_set. The default value is 2070 to 2079. If the time bounds used differ from those used for projections, these reference variables will be pulled from the ensemble member for each climate model specified by threshold_ensemble.

models_to_run

A character vector with either "all" (the default), in which case the function runs through all models in the dataFolder directory, or the names of the models to run, using the names of each model's subdirectory within the data directory (e.g., c("bcc1", "ccsm")).

probThreshold

Numerical value between 0 and 1 specifying the percentile to be used for the threshold variable used to define extreme events. The default value is 0.98 (i.e., a heat wave is a certain number of days above the city's 98th percentile temperature).

numDays

Integer greater than 0 giving the number of days to use in the extreme event definition (e.g., numDays = 2 would define a heat wave as two or more days above the threshold temperature).

printWarning

TRUE / FALSE, specifies whether to print out a warning informing the user that the function will write out results to the local directory specified by the user with out. This warning prints out by default; the user must opt out of this warning by specifying FALSE for this argument, for example if running this function within a loop.

threshold_ensemble

A character vector giving the name of the ensemble member that should be used when determining the city-specific threshold temperatures for each climate model (e.g., "r1i1p1"). This threshold is used for relative extreme event definitions. See the futureheatwaves vignette for more on extreme event definitions. If any climate model lacks that ensemble member for the specified dates for calculating the threshold, it will be excluded from the processing.

lat_lon_colnames

A character vector of length two with the column names in the citycsv dataframe for latitude (first vector element) and longitude (second vector element)

above_threshold

A logical value specifying whether events should be identified by finding days above a threshold (TRUE, the default, e.g., for finding heat waves or extreme air pollution events) or below a threshold (FALSE, e.g., for finding cold waves or droughts).

absolute_thresholds

A numeric vector with four values giving the absolute thresholds to use when calculating the "days.above.abs.thershold" columns in the heatwave characteristic output files. These values must be given in the units in which temperature is expressed in the input data (typically Kelvin for climate model output data). The default values are the values in Kelvin corresponding to 80, 85, 90, and 95 degrees Fahrenheit. If this parameter is customized, it must include four values.

seasonal_months

A numeric vector giving the months to use to calculate the "mean.seasonal.var" column in the extreme event characteristics output file. For example, if seasonal_months is set to 6:8, daily temperatures from June through August each day during the reference years would be used to calculate this mean seasonal value. The default is 5:9 (May--September).

Value

This function creates, and writes to the user's computer, files with the extreme events and their characteristics for the specified climate projections and dates. For more information on customizing this function, see the futureheatwaves vignette. This function also returns a dataframe listing the name of each climate model processed, as well as the number of historical and future projection ensemble members for each model. This output can be used as a check that the function processed through the directory of input files specified using the dataFolder argument.

Examples

## Not run: 
# projection_dir_location <- system.file("extdata/cmip5",
#                                       package = "futureheatwaves")
# city_file_location <- system.file("extdata/cities.csv",
#                                  package = "futureheatwaves")
# 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")
# ## End(Not run)