-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathREADME.Rmd
230 lines (154 loc) · 8.97 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
---
title: caladaptR
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
<a href='http://ucanr-igis.github.io/caladaptr'><img src='man/figures/logo.gif' align="right" height="150" style="padding:15px;"/></a>
<!-- badges: start -->
[](https://lifecycle.r-lib.org/articles/stages.html#stable)
[](https://ajlyons.r-universe.dev)
<!-- badges: end -->
## Features
`caladaptr` is an API client that makes it easier to work with data from [Cal-Adapt.org](https://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:
<p align="center"><img src="man/figures/caladaptr_role_480x432x256.png" width="480" height="432"/></p>
`caladaptr` allows you to:
- query any of Cal-Adapt's ~950 raster data layers
- retrieve values by point, a preset area-of-interest (e.g., census tract), or a user-provided polygon
- cache large queries in a local SQLite database
- download cropped rasters as TIFs and import them into R as stars objects
`caladaptr` functions have been designed to:
- be pipe friendly
- return tibbles for compatibility with tidyverse packages
- return values with encoded units (managed by the [units](https://cran.r-project.org/package=units) package)
- accept and return `sf` data frames where spatial objects are needed
- return rasters as spatiotemporal arrays ([`stars`](https://r-spatial.github.io/stars/) objects)
`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](https://cal-adapt.org/data/).
\
## Installation
`caladaptr` is available on [r-universe](https://ajlyons.r-universe.dev/){target="_blank" rel="noopener"}. To install it, you can run:
```
options(repos = c(ajlyons = 'https://ajlyons.r-universe.dev',
CRAN = 'https://cloud.r-project.org'))
install.packages('caladaptr')
```
Alternately, you can install it directly from [GitHub](https://github.com/ucanr-igis/caladaptr){target="_blank" rel="noopener"}. (This requires the `remotes` package plus [RTools](https://cran.r-project.org/bin/windows/Rtools/){target="_blank" rel="noopener"} for Windows users.)
```
remotes::install_github("ucanr-igis/caladaptr")
```
If you are trying (and failing) to install `caladaptr` on [RStudio Cloud](https://rstudio.cloud/){target="_blank" rel="noopener"} (or another Linux machine), try to install `sf` by itself, and then `caladaptr`.
```
if (!require(sf)) install.packages("sf")
options(repos = c(ajlyons = 'https://ajlyons.r-universe.dev',
CRAN = 'https://cloud.r-project.org'))
install.packages('caladaptr')
```
## General Workflow
In general, there are three steps to retrieving Cal-Adapt data with `caladaptr`:
1) Create an 'API request object'
2) Feed the API request into a function that fetches data (either values or rasters)
3) Wrangle the data that comes back into the format required for your analysis
## Example: Projected Annual Temperature at a Point Location
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](https://berkeley-gif.github.io/caladapt-docs/data-catalog.html) from Scripps, for a single point location.
```{r cap1_create, cache = FALSE}
library(caladaptr)
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
```
\
**2\. Fetch data**
Functions that **fetch data** from Cal-Adapt include `ca_getvals_tbl()`, `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 `ca_getvals_tbl()`:
```{r cap1_getvals, cache = FALSE}
sac_tasmax_tbl <- sac_tasmax_cap %>% ca_getvals_tbl(quiet = TRUE)
head(sac_tasmax_tbl)
dim(sac_tasmax_tbl)
```
\
**3\. Wrangle Data**
Depending what your goal it, you may need to add or delete columns, reshape the data, group rows, etc. Below we'll add a column for Fahrenheit using `set_units()` from the [`units`](https://cran.r-project.org/package=units) package.
```{r message = FALSE}
## 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)
```
Now we can plot it:
```{r sac_tasmax_tbl2_plot, out.width = 600}
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)")
```
\
## Constructing API Requests
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):
|Function |Location Type|
|---------------------|-------------|
|`ca_loc_pt()` | points in matrices|
|`ca_loc_aoipreset()` | preset areas-of-interest|
|`ca_loc_sf( )` | user-supplied sf object (point or polygon)|
**Date functions** (pick one):
|Function |Date Type|
|---------------------|-------------|
|`ca_dates()`|specific dates|
|`ca_years()`|years|
**Dataset functions** (pick one group):
|Functions |Dataset|
|---------------------|-------------|
|`ca_gcm()` + `ca_scenario()` + `ca_cvar()` + `ca_period()`|LOCA downscaled modeled climate data (including all Scripps and VIC)|
|`ca_livneh()` + `ca_cvar()` + `ca_period()`|Livneh data (observed historical)|
|`ca_slug()`|Everything else|
`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:
```{r plot_samp_cap, out.width=360}
samp_cap <- ca_example_apireq(3)
samp_cap %>% ca_preflight()
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](https://ucanr-igis.github.io/caladaptr/).
## Constants
To help you pass arguments for the various constructor functions, `caladaptr` provides the following constants:
```{r constants, cache = FALSE}
## Climate Variables
cvars
## Global Climate Models
## Note: the first 4 are the 'priority' models recommended under California's 4th Climate Change Assessment.
gcms
## Emission scenarios
scenarios
## Temporal resolution periods
periods
```
## Data Catalog
`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.
```
View(ca_catalog_rs())
```
You can also search for datasets using `ca_catalog_search()`, and download a fresh copy of the catalog from Cal-Adapt using `ca_catalog_fetch()`.
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 `ca_locagrid_geom()`.
```{r, include=FALSE}
# end_vignette()
```