climateR simplifies the steps needed to get gridded geospatial data
into R. At its core, it provides three main things:
- A catalog of 112398 geospatial climate, land cover, and soils
resources from 3477 collections. See (
climateR::catalog)
This catalog is an evolving, federated collection of datasets that can be accessed by the data access utilities. This resource is rebuilt automatically on a monthly cycle to ensure the data provided is accurate, while continuously growing based on user requests.
-
A general toolkit for accessing remote and local gridded data files bounded by space, time, and variable constraints (
dap,dap_crop,read_dap_file) -
A set of shortcuts that implement these methods for a core set of selected catalog elements
⚠️ Python Users: Data catalog access is available through the USGSgdptoolspackage. Directly analogous climateR functionality can be found inclimatePy
remotes::install_github("mikejohnson51/AOI") # suggested!
remotes::install_github("mikejohnson51/climateR")library(climateR)The examples used here call upon the following shortcuts:
getGridMET(OPeNDAP server, historic data)getMODIS(Authenticated OPeNDAP server)getMACA(OPeNDAP server, projection data)getNLCD(COG)get3DEP(VRT)getCHIRPS(erddap)
With the aim of highlighting the convenience of a consistent access patterns for a variety of data stores.
climateR is designed with the same concepts as AOI. Namely, that all
spatial data aggregation questions must start with an extent/area of
interest.
Before extracting any data, you must provide an. For the examples here, we will use the state of Colorado (polygons), and all of its cities (points).
colorado = aoi_get(state = "CO", county = "all")
cities = readRDS(system.file("co/cities_colorado.rds", package = "climateR"))
The default behavior of climateR is to request data for the extent of
the AOI passed regardless of whether it is POINT or POLYGON data.
The exception to the default behavior is if the the AOI is a single point. To illustrate:
# Request Data for Colorado (POLYGON(s))
system.time({
gridmet_pr = getGridMET(AOI = colorado,
varname = "pr",
startDate = "1991-10-29",
endDate = "1991-11-06")
})
#> user system elapsed
#> 0.195 0.021 1.266
# Request data using cities (POINTs)
pr = getGridMET(
AOI = cities,
varname = "pr",
startDate = "2020-10-29")
However since the extent of a POINT means {xmax = xmin} and
{ymax = ymin}, climateR will return a time series of the intersecting
cell, opposed to a one cell SpatRaster.
# Request data for a single city
system.time({
future_city = getMACA(AOI = cities[1,],
varname = "tasmax",
startDate = "2050-10-29",
endDate = "2050-11-06")
})
#> user system elapsed
#> 0.203 0.005 0.547future_city
#> date tasmax_CCSM4_r6i1p1_rcp45
#> 1 2050-10-29 295.7503
#> 2 2050-10-30 292.0839
#> 3 2050-10-31 289.6805
#> 4 2050-11-01 287.1293
#> 5 2050-11-02 290.7788
#> 6 2050-11-03 287.1146
#> 7 2050-11-04 290.1259
#> 8 2050-11-05 291.0247
#> 9 2050-11-06 291.6172All climateR functions treat the extent of the AOI and the default
extraction area. This allows multiple climateR shortcuts to be chained
together using either the base R or dplyr piping syntax.
pipes = aoi_ext("Fort Collins", wh = c(10, 20), units = "km", bbox = TRUE)|>
getNLCD() |>
getTerraClimNormals(varname = c("tmax", "ppt"))
lapply(pipes, dim)
#> $`2019 Land Cover L48`
#> [1] 1402 786 1
#>
#> $tmax
#> [1] 10 8 12
#>
#> $ppt
#> [1] 10 8 12Using extract_sites, you can pass an existing data object. If no
identified column is provided to name the extracted timeseries, the
first, fully unique column in the data.frame is used:
gridmet_pts = extract_sites(gridmet_pr, pts = cities)
names(gridmet_pts)[1:5]
#> [1] "date" "177" "283" "527" "117"
gridmet_pts = extract_sites(gridmet_pr, pts = cities, ID = 'NAME')
names(gridmet_pts)[1:5]
#> [1] "date" "ADAMSCITY" "AGATE" "AGUILAR" "AKRON"While the default behavior is to extract data by extent, there are cases when the input AOI is a set of discrete units that you want to act as discrete units.
- A set of
POINTs from which to extract time series - A set of
POLYGONs that data should be summarized to (mean, max, min, etc.) (WIP)
In climateR, populating the ID parameter of any shortcut (or dap)
function, triggers data to be extracted by unit.
In the cities object, the individual POINTs are uniquely identified
by a NAME column. Tellings a climateR function, that ID = "NAME"
triggers it to return the summary:
chirps_pts = getCHIRPS(AOI = cities,
varname = "precip",
startDate = "1991-10-29",
endDate = "1991-11-06",
ID = "NAME")
dim(chirps_pts)
#> [1] 9 584
names(chirps_pts)[1:5]
#> [1] "date" "ADAMSCITY" "AGATE" "AGUILAR" "AKRON"
While climateR does not yet provide areal summaries, our intention is to
integrate the functionality from zonal. Until then, climateR outputs
can be piped directly into execute_zonal. The zonal package also
requires a uniquely identifying column name, and a function to summarize
data with.
library(zonal)
system.time({
chirps = getCHIRPS(AOI = colorado,
varname = "precip",
startDate = "1991-10-29",
endDate = "1991-11-06") %>%
execute_zonal(geom = colorado,
fun = "max",
ID = "fip_code")
})
#> user system elapsed
#> 0.174 0.012 1.245
animation(gridmet_pr$precipitation_amount, AOI = AOI, outfile = "man/figures/rast_gif.gif")
animation(max, feild_pattern = "precip_", outfile = "man/figures/vect_gif.gif")