Change-factor downscaling of user-supplied climate data

downscale_core() is the engine for downscale(). It takes user-supplied high- and low-resolution rasters as input and downscales to user-specified point locations. While less user-friendly than downscale(), downscale_core() is more flexible in that users can supply their own raster inputs. For example, a user could supply their own high-resolution climate map, instead of what is available in climr, as the input to refmap. Another example is in downscaling a uniform warming level, as shown in the example for this function.

Usage

downscale_core(
  xyz,
  refmap,
  gcms = NULL,
  obs = NULL,
  gcm_ssp_ts = NULL,
  gcm_hist_ts = NULL,
  obs_ts = NULL,
  return_refperiod = TRUE,
  vars = sort(sprintf(c("PPT_%02d", "Tmax_%02d", "Tmin_%02d"), sort(rep(1:12, 3)))),
  ppt_lr = FALSE,
  nthread = 1L,
  out_spatial = FALSE,
  plot = NULL
)

Arguments

xyz

a data.frame with the following columns "long", "lat", "elev", and a unique "id". Any extra columns will be ignored and not output.

refmap

SpatRaster. Outputs from input_refmap(). The high-resolution climate maps for use as the downscaling baseline.

gcms

list of SpatRasters. Outputs from input_gcms(). Global climate model data for 20-year reference periods to be downscaled. Default to NULL.

obs

list of SpatRasters. Outputs from input_obs(). Observed climate data for 20-year reference periods to be downscaled. Default to NULL.

gcm_ssp_ts

list of SpatRasters. Outputs from input_gcm_ssp(). Global climate model time series for ssps-rcp scenarios to be downscaled. Default to NULL.

gcm_hist_ts

list of SpatRasters. Outputs from input_gcm_hist(). Global climate model time series for historical scenario to be downscaled. Default to NULL.

obs_ts

list of SpatRasters. Outputs from input_obs_ts(). Observed climate time series to be downscaled. Default to NULL.

return_refperiod

logical. Return downscaled reference period (1961-1990)? Default TRUE.

vars

character. A vector of climate variables to compute. Supported variables can be obtained with list_vars(). Definitions can be found in this package variables dataset. Default to monthly PPT, Tmax, Tmin.

ppt_lr

logical. Apply elevation adjustment to precipitation. Default to FALSE.

nthread

integer. Number of parallel threads to use to do computations. Default to 1L.

out_spatial

logical. Should a SpatVector be returned instead of a data.frame.

plot

character. If out_spatial is TRUE, the name of a variable to plot. If the variable exists in reference, then its reference values will also be plotted. Otherwise, reference January total precipitation (PPT01) values will be plotted. Defaults to no plotting (NULL).

Value

A data.table or SpatVector with downscaled climate variables. If gcms is NULL, this is just the downscaled reference at point locations. If gcms is provided, this returns a downscaled dataset for each point location, general circulation model (GCM), shared socioeconomic pathway (SSP), run and period.

Details

We recommend downscale() for most purposes.

See also

input_gcms(), input_obs(), list_vars()

Examples

## 
library(terra)
#> terra 1.7.78
xyz <- data.frame(lon = runif(10, -130, -106), lat = runif(10, 37, 50), elev = runif(10), id = 1:10)

## get bounding box based on input points
thebb <- get_bb(xyz)

## get database connection
dbCon <- data_connect()

# obtain the climatena 1961-1990 normals for the study area. 
refmap <- input_refmap(dbCon, thebb, reference = "refmap_climatena")
#> Downloading new data...
#> ............
#> Caching data...

# obtain the low-resolution climate data for a single gcm, 20-year period, and ssp scenario. 
gcm_raw <- input_gcms(dbCon, thebb, list_gcms()[3], list_ssps()[1], period = list_gcm_periods()[2])
#> Downloading GCM anomalies
#> .
#> Caching data...

# downscale the GCM data
gcm_downscaled <- downscale_core(xyz = xyz, refmap = refmap, gcms = gcm_raw, vars = c("MAT", "PAS"))

# create an input of uniform warming of 2 degrees Celsius and no precipitation change, for use as a null comparison to the GCM warming
null <- gcm_raw #' use the gcm input object as a template
names(null) <- "null_2C"
names(null[[1]]) <-  sapply(strsplit(names(null[[1]]), "_"), function(x) paste("null2C", x[2], x[3], "NA", "NA", "NA", "NA", sep="_"))
for(var in names(null[[1]])){ values(null[[1]][[var]]) <- if(length(grep("PPT", var)==1)) 1 else 2 } #' repopulate with the null values

# downscale the null values for variables of interest
null_downscaled <- downscale_core(xyz = xyz, refmap = refmap, gcms = null, vars = c("MAT", "PAS"))
pool::poolClose(dbCon)