Self-contained change-factor downscaling of observed and simulated climate data

downscale() provides downscaled climate variables for user-specified locations. It adapts a simple change-factor (aka "delta') downscaling approach originally implemented in ClimateNA. This approach downscales climate data in three stages:

Change-factor downscaling of coarse-resolution (50-200km grid) monthly temperature and precipitation data from climate models or observational sources to high-resolution (800m grid);
Elevation adjustment of temperature variables to provide scales finer than the high-resolution reference grid; and
Calculating derived variables from the downscaled monthly temperature and precipitation variables.

See vignette("methods_downscaling") for a description of the downscaling methodology.

downscale() is a user-friendly wrapper for downscale_core()

Usage

downscale(
  xyz,
  which_refmap = "refmap_climr",
  obs_periods = NULL,
  obs_years = NULL,
  obs_ts_dataset = NULL,
  gcms = NULL,
  ssps = NULL,
  gcm_periods = NULL,
  gcm_ssp_years = NULL,
  gcm_hist_years = NULL,
  ensemble_mean = TRUE,
  max_run = 0L,
  run_nm = NULL,
  cache = TRUE,
  local = FALSE,
  indiv_tiles = FALSE,
  db_option = "auto",
  return_refperiod = TRUE,
  ...
)

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.
which_refmap: character. Which map of 1961-1990 climatological normals to use as the high-resolution reference climate map for downscaling. Default is "refmap_climr". Other options are one of list_refmaps().
obs_periods: character. Which historical period for observational climate data, averaged over this period. Options are list_obs_periods().
obs_years: integer. Vector of years to obtain individual years or time series of observational climate data. See list_obs_years() for available years.
obs_ts_dataset: character. The dataset to use for observational time series data. Options are "climatena" for the ClimateNA gridded time series or "cru.gpcc" for the combined Climatic Research Unit TS dataset (for temperature) and Global Precipitation Climatology Centre dataset (for precipitation).
gcms: character. Vector of global climate model names. Options are list_gcms().
ssps: character. Vector of SSP-RCP scenarios (representative concentration pathways paired with shared socioeconomic pathways). Options are list_ssps(). Defaults to all scenarios available.
gcm_periods: character. 20-year reference periods for GCM simulations. Options are list_gcm_periods().
gcm_ssp_years: character. Timeseries years for GCM simulations of future scenarios specified by ssps. See list_gcm_ssp_years() for available years.
gcm_hist_years: character. Timeseries years for GCM simulations of the historical scenario. See list_gcm_hist_years() for available years.
ensemble_mean: Logical. Return the mean of the individual GCM runs? If ensemble_mean = TRUE and max_run = 0, only the mean will be returned. To return an individual run and exclude the mean, set ensemble_mean = FALSE and max_run = 1.
max_run: integer. Maximum number of model runs to include, not including the ensemble mean. Runs are included in the order they are found in the models data until max_run is reached. Defaults to 0L.
run_nm: character. NULL or length >= 1. Name of specified run(s) to return, instead of using max_run. Use the list_runs_*() functions to list available runs.Defaults to NULL.
cache: logical. Cache data locally? Default TRUE
local: logical. Is the postgres database local? Default FALSE
indiv_tiles: logical. Only download necessary tiles instead of full bounding box? This will generally be faster, but doesn't cache.
db_option: character. One of auto, database, or local. Default auto.
return_refperiod: logical. Return 1961-1990 period? Default TRUE
...: other arguments passed to downscale_core(). Namely: vars, out_spatial and plot

Value

data.table or SpatRaster of downscaled climate variables for each location. All outputs are returned in one table. If output is SpatRaster, each layer corresponds to a variable.

Details

downscale_core() parameters can be applied in downscale(). For example, setting ppt_lr = TRUE in downscale() will apply elevation adjustment to precipitation values.

The standard climr method, when db_option = "local" downloads and optionally caches raster data, then does the processing locally. Option database submits points to the climr database, and processes them on the database server. This is generally faster for a) very few points, or b) timeseries with many layers. Option auto attempts to intelligently combine these methods depending on the input: if fewer than 5 points are submitted, all downscaling will be done on the database, otherwise period downscaling will be done locally, and timeseries will be done on the database.

Examples


## provide or create a dataframe of lon, lat, elev, and id - usually read from csv file
in_xyz <- data.frame(
  lon = c(-127.7052, -127.6227, -127.5623, -127.7162, -127.1858, -127.125, -126.9495, -126.9550),
  lat = c(55.3557, 55.38847, 55.28537, 55.25721, 54.88135, 54.65636, 54.6913, 54.61025),
  elev = c(291, 296, 626, 377, 424, 591, 723, 633),
  id = 1:8
)

## historic observational time series
vars <- c("PPT", "CMD", "Tave_07")
climate_norms_hist <- downscale(
  xyz = in_xyz,
  which_refmap = "refmap_climr",
  return_refperiod = TRUE,
  obs_periods = "2001_2020",
  vars = vars,
  out_spatial = TRUE, plot = "PPT"
) ## specify desired variables to plot
#> Welcome to climr!
#> Getting observed anomalies...
#> Downloading observed period anomalies
#> .
#> Caching data...
#> Downloading new data from refmap_climr...
#> .
#> Caching data...
#> Downscaling...
#> Plotting results for a single period/GCM/run/SSP


## as a data.table
climate_norms_hist <- downscale(
  xyz = in_xyz, which_refmap = "refmap_climr",
  return_refperiod = TRUE,
  vars = vars,
  out_spatial = FALSE, plot = "PPT"
) ## specify desired variables to plot
#> Welcome to climr!
#> Retrieving from cache...
#> Downscaling...

## future projections for annual variables from three models
climate_norms_fut <- downscale(
  xyz = in_xyz, which_refmap = "refmap_climr",
  gcms = list_gcms()[c(1, 5, 6)],
  ssps = list_ssps()[2],
  gcm_periods = list_gcm_periods()[1:2],
  # gcm_ssp_years = 2020:2060,
  max_run = 3, #' we want 3 individual runs for the model
  vars = list_vars("Annual")
)
#> Welcome to climr!
#> Getting GCMs...
#> Downloading GCM anomalies
#> .
#> Caching data...
#> Downloading GCM anomalies
#> .
#> Caching data...
#> Downloading GCM anomalies
#> .
#> Caching data...
#> Retrieving from cache...
#> Downscaling...