forked from ropensci/prism
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.Rmd
252 lines (187 loc) · 11 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
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, echo = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-"
)
# knitr hook to truncate long output. See:
# https://stackoverflow.com/q/23114654/3362993
hook_output <- knitr::knit_hooks$get("output")
knitr::knit_hooks$set(output = function(x, options) {
if (!is.null(n <- options$out.lines)) {
x <- unlist(strsplit(x, "\n"))
if (length(x) > n) {
# truncate the output
x <- c(head(x, n), "....\n")
}
x <- paste(x, collapse = "\n")
}
hook_output(x, options)
})
```
# `prism`
[](https://cran.r-project.org/package=prism)
[](https://github.com/ropensci/prism/actions)
[](https://app.codecov.io/github/ropensci/prism?branch=master)
This package allows users to access and visualize data from the [Oregon State PRISM project](https://prism.nacse.org). Data are all in the form of gridded rasters for the continental US at 4 different temporal scales: daily, monthly, annual, and 30 year normals. Please see their webpage for a full description of the data products, or [see their overview](https://www.prism.oregonstate.edu/documents/PRISM_datasets.pdf).
## Installation
prism is available on CRAN:
```{r eval=FALSE}
install.packages("prism")
```
Or the development version can be installed from GitHub with devtools:
```{r start, eval=FALSE}
# install.packages("devtools")
library(devtools)
install_github("ropensci/prism")
```
## Quickstart
The overall work flow in the prism package is (links go to details on this page):
1. [Set the download directory](#downloading-data), i.e., the folder on your computer that prism data will be saved to: `prism_set_dl_dir()`. This is now referred to as the "prism archive".
2. [Download prism data to the archive:](#download-30-year-normal-data) `get_prism_*()`. Each folder, or variable, timestep, day/month/year is stored in a single folder in the archive and referred to as prism data (`pd`).
3. [Interact with the prism archive:](#interact-with-the-archive-and-prism-data) `prism_archive_*()`. Or interact with the prism data: `pd_*()`.
The remainder of this README provides examples following this work flow.
## prism data and parameters
Data are available in 4 different temporal scales as mentioned above. At each temporal scale, there are 7 different parameters/variables available. Keep in mind these are modeled parameters, not measured. Please see the [full description](https://www.prism.oregonstate.edu/documents/PRISM_datasets.pdf) for how they are calculated.
| Parameter name| Description |
|:---------------|:-------------|
| *tmean* | Mean temperature |
| *tmax* | Maximum temperature |
| *tmin* | Minimum temperature |
| *tdmean* | Mean dew point temperature |
| *ppt* | Total precipitation (rain and snow)|
| *vpdmin* | Daily minimum vapor pressure deficit |
| *vpdmax* |Daily maximum vapor pressure deficit |
## Downloading data
Before downloading any data, set the directory that the prism data will be saved to:
```{r prism setup}
library(prism)
prism_set_dl_dir("~/prismtmp")
```
This is now referred to as the "prism archive". The `prism_archive_*()` functions allow the user to search through the archive. The prism archive contains "prism data". The prism data are referred to by their folder names, even though the "real" data are the .bil, .txt, and other files that exist in the folder. The prism data (`pd`) can be accessed using the `pd_*()` functions.
### Download 30-year normal data
Normals are based on the latest 30-year period; currently 1981 - 2010. Normals can be downloaded in two resolutions, 4km and 800m, and a resolution must be specified. They can be downloaded for a given month, vector of months, or annual averages for all 30 years.
```{r get normals,results=FALSE, eval=FALSE}
# Download the January - June 30-year averages at 4km resolution
get_prism_normals(type="tmean", resolution = "4km", mon = 1:6, keepZip = FALSE)
# Download the 30-year annual average precip and annual average temperature
get_prism_normals("ppt", "4km", annual = TRUE, keepZip = FALSE)
get_prism_normals("tmean", "4km", annual = TRUE, keepZip = FALSE)
```
If the archive has not already been set, calling any of the `get_prism_*()` functions will prompt the user to specify the directory. prism data are downloaded as zip files and then unzipped. If the `keepZip` argument is `TRUE` the zip file will remain on your machine, otherwise it will be automatically deleted.
### Download daily, monthly, and annual data
Let us download daily average temperatures from June 1 to June 14, 2013. We can also download January average temperature data from 1982 to 2014. Finally, we will download annual average precipitation for 2000 to 2015.
```{r get daily monthly, message=FALSE, results=FALSE, eval=FALSE}
get_prism_dailys(
type = "tmean",
minDate = "2013-06-01",
maxDate = "2013-06-14",
keepZip = FALSE
)
get_prism_monthlys(type = "tmean", year = 1982:2014, mon = 1, keepZip = FALSE)
get_prism_annual("ppt", years = 2000:2015, keepZip = FALSE)
```
Note that for daily data you need to give a well formed date string in the form of "YYYY-MM-DD".
## Interact with the archive and prism data
You can view all the prism data you have downloaded with a simple command: `prism_archive_ls()`. This function gives a list of folder names, i.e., prism data (`pd`). All the functions in the prism package work off of one or more of these folder names (`pd`).
```{r listingFiles, out.lines=10}
## Truncated to keep file list short
prism_archive_ls()
```
While prism functions use this folder format, other files may need an absolute path (e.g. the `raster` package). The `pd_to_file()` function conveniently returns the absolute path. Alternatively, you may want to see what the normal name for the product is (not the file name), and we can get that with the `pd_get_name()` function.
```{r moreListing, out.lines=5}
## Truncated to keep file list short
pd_to_file(prism_archive_ls())
pd_get_name(prism_archive_ls())
```
Finally, `prism_archive_subset()` is a convenient way to search for specific parameters, time steps, days, months, years, or ranges of days, months, years.
```{r}
# we know we have downloaded June 2013 daily data, so lets search for those
prism_archive_subset("tmean", "daily", mon = 6)
# or we can look for days between June 7 and June 10
prism_archive_subset(
"tmean", "daily", minDate = "2013-06-07", maxDate = "2013-06-10"
)
```
### Raster plots
You can easily make a quick plot of your data using the output of `prism_archive_ls()` or `prism_archive_subset()` with `pd_image()`.
```{r quick_plot,fig.height=5,fig.width=7}
# Plot the January 30-year average temperatures
jmean <- prism_archive_subset(
"tmean", "monthly normals", mon = 1, resolution = "4km"
)
pd_image(jmean)
```
It is easy to load the prism data with the raster package. This time we will look at January temperature anomalies. To do this we will examine the difference between January 2013 and the January 30-year normals. Conveniently, we already downloaded these data. We just need to grab them out of our archive.
```{r raster_math,fig.height=5,fig.width=7}
library(raster)
# knowing the name of the files you are after allows you to find them in the
# list of all files that exist
# jnorm_name <- "PRISM_tmean_30yr_normal_4kmM2_01_bil"
# j2013_name <- "PRISM_tmean_stable_4kmM3_201301_bil"
# but we will use prism_archive_subset() to find the files we need
jnorm <- prism_archive_subset(
"tmean", "monthly normals", mon = 1, resolution = "4km"
)
j2013 <- prism_archive_subset("tmean", "monthly", years = 2013, mon = 1)
# raster needs a full path, not the "short" prism data name
jnorm <- pd_to_file(jnorm)
j2013 <- pd_to_file(j2013)
## Now we'll load the rasters.
jnorm_rast <- raster(jnorm)
j2013_rast <- raster(j2013)
# Now we can do simple subtraction to get the anomaly by subtracting 2014
# from the 30 year normal map
anomCalc <- function(x, y) {
return(x - y)
}
anom_rast <- raster::overlay(j2013_rast,jnorm_rast,fun = anomCalc)
plot(anom_rast)
```
The plot shows that January 2013 was warmer than the average over the last 30 years. It also shows how easy it is to use the raster library to work with prism data. The package provides a simple framework to work with a large number of rasters that you can easily download and visualize or use with other data sets.
### Single grid cell plot
You can also visualize a single point across multiple prism data files (slice) using `pd_plot_slice()`. This procedure will take a set of rasters, create a "`raster::stack`", extract data at a point, and then create a ggplot2 object.
Let's now make a plot of January temperatures in Boulder between 1982 and 2014. First we'll grab all the data from the US (downloaded in the previous step), and then give our function a point to get data from. The point must be a vector in the form of longitude, latitude. Because `pd_plot_slice()` returns a gg object, it can be combined with other ggplot functions.
```{r plot_Boulder,fig.height=5,fig.width=7, results=FALSE}
library(ggplot2)
# data already exist in the prism dl dir
boulder <- c(-105.2797, 40.0176)
# prism_archive_subset() will return prism data that matches the specified
# variable, time step, years, months, days, etc.
to_slice <- prism_archive_subset("tmean", "monthly", mon = 1)
p <- pd_plot_slice(to_slice, boulder)
# add a linear average and title
p +
stat_smooth(method="lm", se = FALSE) +
theme_bw() +
ggtitle("Average January temperature in Boulder, CO 1982-2014")
```
### leaflet map
Finally, the prism data are in a form that can be used with leaflet maps (with the help of the raster package). The [leaflet package](https://CRAN.R-project.org/package=leaflet) allows you to easily make JavaScript maps using the [leaflet](https://leafletjs.com/) mapping framework using prism data. These can easily be hosted on websites like [Rpubs](https://rpubs.com/) or your own site. Here is a simple example of plotting the [30-year normal for annual temperature](https://rpubs.com/DistribEcology/122453). If you run this code you will have an interactive map, instead of just the screen shot shown here.
```{r leaflet,eval=F}
library(leaflet)
library(raster)
library(prism)
# 30-year normal average temperature have already been downloaded for
norm <- prism_archive_subset(
"tmean", "annual normals", resolution = "4km"
)
rast <- raster(pd_to_file(norm))
# Create color palette and plot
pal <- colorNumeric(
c("#0000FF", "#FFFF00", "#FF0000"),
values(rast),
na.color = "transparent"
)
leaflet() %>%
addTiles(
urlTemplate = 'http://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}'
) %>%
addRasterImage(rast, colors = pal, opacity=.65) %>%
addLegend(pal = pal, values = values(rast), title = "Deg C")
```
[