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,
  skip_check = FALSE
)

downscale_db_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 terra::SpatRaster with a single layer containing elevation values in metres, or 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 models to be downscaled.
obs: list of SpatRasters. Outputs from input_obs(). Observed climate data for 20-year reference periods to be downscaled.
gcm_ssp_ts: list of SpatRasters. Outputs from input_gcm_ssp(). Global climate model time series for ssps-rcp scenarios to be downscaled.
gcm_hist_ts: list of SpatRasters. Outputs from input_gcm_hist(). Global climate model time series for historical scenario to be downscaled.
obs_ts: list of SpatRasters. Outputs from input_obs_ts(). Observed climate time series to be downscaled.
return_refperiod: logical. Return downscaled reference period (1961-1990)?
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.
nthread: integer. Number of parallel threads to use to do computations. Only supported for table of points.
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.
skip_check: A boolean. Skip checks if coming from downscale.

Value

A SpatRaster, 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, global climate model (GCM), shared socioeconomic pathway scenario (SSP), model run, and period.

Details

We recommend downscale() for most purposes.

Examples

##
library(terra)
#> terra 1.8.50
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)


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

#> Caching data...

# obtain the low-resolution climate data for a single gcm, 20-year period, and ssp scenario.
gcm_raw <- input_gcms(
  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"))