caladaptr is an API client that makes it easier to work with data from Cal-Adapt.org in R. The niche of
caladaptr is to bring data into R after which you can use other packages for analysis and visualization:
caladaptr allows you to:
caladaptr functions have been designed to:
sfdata frames where spatial objects are needed
caladaptr does not support downloading the original NetCDF rasters nor station data (e.g., sea level rise, stream gauges). For these data, see the Data Download tool or FTP server on Cal-Adapt.org.
caladaptr is available on r-universe. To install it, you can run:
options(repos = c(ajlyons = 'https://ajlyons.r-universe.dev', CRAN = 'https://cloud.r-project.org')) install.packages('caladaptr')
If you are trying (and failing) to install
caladaptr on RStudio Cloud (or another Linux machine), try to install
sf by itself, and then
if (!require(sf)) install.packages("sf") options(repos = c(ajlyons = 'https://ajlyons.r-universe.dev', CRAN = 'https://cloud.r-project.org')) install.packages('caladaptr')
In general, there are three steps to retrieving Cal-Adapt data with
Create an ‘API request object’
Feed the API request into a function that fetches data (either values or rasters)
Wrangle the data that comes back into the format required for your analysis
In this example, we’ll get the projected maximum daily temperature for a point location near Sacramento, averaged by calendar year from 2040-2070, for 10 GCMs and 2 emissions scenarios. Then we’ll plot them.
1. Create an API request object
Creating an API request object is a bit like filling in an order form. The request is essentially a description of the data you want.
There are a number of constructor functions you can mix and match to create an API request object. Below we create a request for 30 years of projected annual average maximum daily temperature from the LOCA downscaled CMIP5 climate projections from Scripps, for a single point location.
library(caladaptr) #> caladaptr (version 0.6.4) #> URL: https://ucanr-igis.github.io/caladaptr #> Bug reports: https://github.com/ucanr-igis/caladaptr/issues sac_tasmax_cap <- ca_loc_pt(coords = c(-121.4687, 38.5938)) %>% ## specify a location ca_gcm(c("HadGEM2-ES", "CNRM-CM5", "CanESM2","MIROC5", ## select GCM(s) "ACCESS1-0", "CCSM4", "CESM1-BGC", "CMCC-CMS", "GFDL-CM3", "HadGEM2-CC")) %>% ca_scenario(c("rcp45","rcp85")) %>% ## select emission scenarios(s) ca_cvar(c("tasmax")) %>% ## select climate variables ca_period("year") %>% ## select a temporal aggregation period ca_years(start = 2040, end = 2070) ## select start and end dates sac_tasmax_cap #> Cal-Adapt API Request #> Location(s): #> x: -121.469 #> y: 38.594 #> Variable(s): tasmax #> Temporal aggregration period(s): year #> GCM(s): HadGEM2-ES, CNRM-CM5, CanESM2, MIROC5, ACCESS1-0, CCSM4, CESM1-BGC, CMCC-CMS, GFDL-CM3, HadGEM2-CC #> Scenario(s): rcp45, rcp85 #> Dates: 2040-01-01 to 2070-12-31 #>
2. Fetch data
Functions that fetch data from Cal-Adapt include
ca_getvals_db() (see Large Queries vignette), and
ca_getrst_stars() (see Rasters Part I vignette). Below we’ll fetch data into a tibble by passing the API request to
sac_tasmax_tbl <- sac_tasmax_cap %>% ca_getvals_tbl(quiet = TRUE) head(sac_tasmax_tbl) #> # A tibble: 6 x 8 #> id cvar period gcm scenario spag dt val #> <int> <fct> <fct> <fct> <fct> <fct> <chr> [K] #> 1 1 tasmax year HadGEM2-ES rcp45 none 2040-12-31 299. #> 2 1 tasmax year HadGEM2-ES rcp45 none 2041-12-31 299. #> 3 1 tasmax year HadGEM2-ES rcp45 none 2042-12-31 299. #> 4 1 tasmax year HadGEM2-ES rcp45 none 2043-12-31 300. #> 5 1 tasmax year HadGEM2-ES rcp45 none 2044-12-31 300. #> 6 1 tasmax year HadGEM2-ES rcp45 none 2045-12-31 298. dim(sac_tasmax_tbl) #>  620 8
3. Wrangle Data
## Add a column with Fahrenheit units library(dplyr) library(units) sac_tasmax_tbl2 <- sac_tasmax_tbl %>% mutate(temp_f = set_units(val, degF)) head(sac_tasmax_tbl2) #> # A tibble: 6 x 9 #> id cvar period gcm scenario spag dt val temp_f #> <int> <fct> <fct> <fct> <fct> <fct> <chr> [K] [degF] #> 1 1 tasmax year HadGEM2-ES rcp45 none 2040-12-31 299. 78.1 #> 2 1 tasmax year HadGEM2-ES rcp45 none 2041-12-31 299. 78.0 #> 3 1 tasmax year HadGEM2-ES rcp45 none 2042-12-31 299. 77.8 #> 4 1 tasmax year HadGEM2-ES rcp45 none 2043-12-31 300. 79.7 #> 5 1 tasmax year HadGEM2-ES rcp45 none 2044-12-31 300. 79.5 #> 6 1 tasmax year HadGEM2-ES rcp45 none 2045-12-31 298. 77.2
Now we can plot it:
library(ggplot2) ggplot(data = sac_tasmax_tbl2, aes(x = as.Date(dt), y = as.numeric(temp_f))) + geom_line(aes(color=gcm)) + facet_grid(scenario ~ .) + labs(title = "Annual Average Maximum Daily Temperature for Sacramento", x = "year", y = "temp (F)")
API request objects are constructed by stringing together functions that provide the key elements of the request, including the location(s), dataset(s), and time frame.
Location functions (pick one):
||points in matrices|
||user-supplied sf object (point or polygon)|
Date functions (pick one):
Dataset functions (pick one group):
||LOCA downscaled modeled climate data (including all Scripps and VIC)|
||Livneh data (observed historical)|
ca_example_apireq() is a convenience function that returns sample API requests for testing. You can use
ca_preflight() to check an API request for errors. Plotting an API request will show the location(s), with an option to overlay the loca grid cells:
samp_cap <- ca_example_apireq(3) samp_cap %>% ca_preflight() #> General issues #> - none found #> Issues for querying values #> - none found #> Issues for downloading rasters #> - none found plot(samp_cap, locagrid = TRUE, static = TRUE)
For more examples, including retrieving data for a preset area-of-interest (i.e., census tracts), see the API Requests vignette and ‘R Notebooks’ on the website.
To help you pass arguments for the various constructor functions,
caladaptr provides the following constants:
## Climate Variables cvars #>  "tasmax" "tasmin" "pr" "swe" "baseflow" #>  "et" "rainfall" "runoff" "snowfall" "soilMoist1" #>  "Tair" ## Global Climate Models ## Note: the first 4 are the 'priority' models recommended under California's 4th Climate Change Assessment. gcms #>  "HadGEM2-ES" "CNRM-CM5" "CanESM2" "MIROC5" "ACCESS1-0" #>  "CCSM4" "CESM1-BGC" "CMCC-CMS" "GFDL-CM3" "HadGEM2-CC" #>  "ens32avg" "ens32max" "ens32min" ## Emission scenarios scenarios #>  "rcp45" "rcp85" "historical" ## Temporal resolution periods periods #>  "day" "month" "year" "30yavg"
caladaptr can not tell you which climate data you need for your project. Nor will it teach you how to use climate data appropriately or wisely. However it does have a copy of the Cal-Adapt raster series data catalog, so you can see what’s available and specify the datasets you need.
To view the entire data catalog in a RStudio Viewer pane, run the following. You can then use the filter button to find datasets that match a key word.
Most / all of the Cal-Adapt rasters series have been downscaled to approximately 6km (3.7 mi) using the LOCA downscaling method, and are available for the coverage area shown below. For a finer scale analysis, you can download the LOCA grid cells as a polygon layer using