Beginner `climr` workflow

Using the `downscale()` function

The basic use of climr is to pass a data.table of point coordinates, IDs and elevation to downscale() and select the type of climate projection or values wanted - e.g. below we ask for future projections in two periods, using two emissions scenarios and two General Circulation Models. We also specify we want 3 individual runs of each model/scenario combination, in addition to the ensemble mean (returned by default).

library(climr)

## provide a data.frame or data.table of point coordinates, IDs and elevation
my_points <- data.frame(
  lon = c(-123.4404, -123.5064, -124.2317),
  lat = c(48.52631, 48.46807, 49.21999),
  elev = c(52, 103, 357),
  id = LETTERS[1:3]
)

## climr query for the data.frame
ds_out <- downscale(
  xyz = my_points, which_refmap = "auto",
  gcms = c("GFDL-ESM4", "EC-Earth3"), # specify two global climate models
  ssps = c("ssp370", "ssp245"), # specify two greenhouse gas concentration scenarios
  gcm_periods = c("2001_2020", "2041_2060"), # specify two 20-year periods
  max_run = 3, # specify 3 individual runs for each model
  vars = c("PPT", "CMD", "CMI")
)
#> ...

The resulting output is a data.table, printed below:

‘ds_out’ table - Output from `downscale`. Outputs are shown for one location (‘id’)
id	GCM	SSP	RUN	PERIOD	PPT	CMD	CMI
A	NA	NA	NA	1961_1990	970.3429	343.4490	43.57850
A	EC-Earth3	ssp245	ensembleMean	2001_2020	972.1767	373.8551	39.70240
A	EC-Earth3	ssp245	ensembleMean	2041_2060	1006.1585	406.6225	36.52084
A	EC-Earth3	ssp245	r15i1p1f1	2001_2020	965.3922	371.3933	39.49866
A	EC-Earth3	ssp245	r15i1p1f1	2041_2060	997.9423	401.6324	37.44849
A	EC-Earth3	ssp245	r1i1p1f1	2001_2020	978.3516	340.3457	42.50610
A	EC-Earth3	ssp245	r1i1p1f1	2041_2060	1095.8585	415.1882	45.08819
A	EC-Earth3	ssp245	r4i1p1f1	2001_2020	951.6959	388.9020	36.72670
A	EC-Earth3	ssp245	r4i1p1f1	2041_2060	975.7146	416.2682	33.07894
A	EC-Earth3	ssp370	ensembleMean	2001_2020	958.5241	376.4395	37.49181
A	EC-Earth3	ssp370	ensembleMean	2041_2060	1018.8533	389.9082	38.46388
A	EC-Earth3	ssp370	r15i1p1f1	2001_2020	964.1214	382.3330	37.78381
A	EC-Earth3	ssp370	r15i1p1f1	2041_2060	1040.4095	382.6898	40.58923
A	EC-Earth3	ssp370	r1i1p1f1	2001_2020	913.8905	362.4083	34.85644
A	EC-Earth3	ssp370	r1i1p1f1	2041_2060	960.7842	400.2238	31.74355
A	EC-Earth3	ssp370	r4i1p1f1	2001_2020	981.5158	369.9150	39.62014
A	EC-Earth3	ssp370	r4i1p1f1	2041_2060	1082.2457	367.2968	45.98450
A	GFDL-ESM4	ssp245	ensembleMean	2001_2020	968.7068	361.9188	40.77159
A	GFDL-ESM4	ssp245	ensembleMean	2041_2060	1027.3375	404.7300	39.50524
A	GFDL-ESM4	ssp245	r1i1p1f1	2001_2020	969.7772	341.8364	42.13517
A	GFDL-ESM4	ssp245	r1i1p1f1	2041_2060	1012.5613	398.5545	37.81111
A	GFDL-ESM4	ssp245	r2i1p1f1	2001_2020	958.3115	373.1771	39.21174
A	GFDL-ESM4	ssp245	r2i1p1f1	2041_2060	1040.4092	407.5354	41.39380
A	GFDL-ESM4	ssp245	r3i1p1f1	2001_2020	978.0317	370.7409	40.93326
A	GFDL-ESM4	ssp245	r3i1p1f1	2041_2060	1029.0421	408.1012	39.30621
A	GFDL-ESM4	ssp370	ensembleMean	2001_2020	968.2722	355.0187	41.47202
A	GFDL-ESM4	ssp370	ensembleMean	2041_2060	1007.8247	381.8216	39.58630
A	GFDL-ESM4	ssp370	r1i1p1f1	2001_2020	968.2722	355.0187	41.47202
A	GFDL-ESM4	ssp370	r1i1p1f1	2041_2060	1007.8247	381.8216	39.58630

Listing available options

The list_* functions (see ?list_gcm) are useful to see available options, for example:

list_gcms()
#>  [1] "ACCESS-ESM1-5" "BCC-CSM2-MR"   "CanESM5"       "CNRM-ESM2-1"  
#>  [5] "EC-Earth3"     "GFDL-ESM4"     "GISS-E2-1-G"   "INM-CM5-0"    
#>  [9] "IPSL-CM6A-LR"  "MIROC6"        "MPI-ESM1-2-HR" "MRI-ESM2-0"   
#> [13] "UKESM1-0-LL"

list_gcm_periods()
#> [1] "2001_2020" "2021_2040" "2041_2060" "2061_2080" "2081_2100"

list_ssps()
#> [1] "ssp126" "ssp245" "ssp370" "ssp585"

These functions can be used as arguments in downscale(). For example, vars = list_variables() could be specified to obtain data for all available variables, or gcms = list_gcm()[c(1,4,5,6,7,10,11,12)] could be used to specify the eight-gcm ensemble recommended by Mahony et al. (2022).

Working with raster data

A common use of climr is to obtain climate data for a user-provided raster grid. Here is some sample code showing how to do so. We convert a digital elevation model (DEM) into a table of points (one per grid cell) which we use as the climr input table. Then we take the climr input and populate the raster grid with a climate variable.

library(terra)
library(data.table)

## get the sample digital elevation model (dem) provided with `climr`
dem_vancouver <- get(data("dem_vancouver")) |> 
  unwrap()

## convert the DEM to a data.frame
my_grid <- as.data.frame(dem_vancouver, cells = TRUE, xy = TRUE)
colnames(my_grid) <- c("id", "lon", "lat", "elev") # rename column names to what climr expects

## A simple climr query. This will return the observed 1961-1990 and 2001-2020 mean annual temperature (MAT) for the raster grid points. 
ds_out <- downscale(
  xyz = my_grid, 
  obs_periods = "2001_2020", 
  vars = c("MAT")
)
#> ..


## populate the raster grid with the downscaled climate values
my_clim <- rast(dem_vancouver) # use the DEM as a template raster
my_clim[ds_out[PERIOD == "2001_2020", id]] <- ds_out[PERIOD == "2001_2020", MAT] # populate the raster cells with the 2001-2020 mean annual temperature (MAT) values, using the `id` field as the link. 

plot(my_clim, main = "2001-2020 mean annual temperature (MAT)")

See vignette("vignettes/climr_with_rasters.Rmd") for more details on using climr with rasters and spatial data.

Looking under the hood

You can download and investigate the raw data that climr uses for downscaling, such as the reference climatological maps, the observational time series, and the GCM anomalies. See the section “Workflow with *_input functions and downscale” in vignette("vignettes/climr_workflow_int.Rmd") for an example.

Using the downscale() function

Listing available options

Working with raster data

Looking under the hood

Using the `downscale()` function