forked from ropensci/smapr
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.Rmd
215 lines (158 loc) · 7.96 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
---
title: "smapr"
output: github_document
---
[](https://travis-ci.org/ropensci/smapr)
[](https://ci.appveyor.com/project/mbjoseph/smapr)
[](https://codecov.io/gh/ropensci/smapr)
[](https://cran.r-project.org/package=smapr)
[](https://www.tidyverse.org/lifecycle/#maturing)
[](http://cran.rstudio.com/web/packages/smapr/index.html)
[](https://github.com/ropensci/onboarding/issues/231)
[](http://www.repostatus.org/#active)
```{r, echo = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/"
)
```
An R package for acquisition and processing of [NASA (Soil Moisture Active-Passive) SMAP data](http://smap.jpl.nasa.gov/)
## Installation
To install smapr from CRAN:
```{r cran-installation, eval = FALSE}
install.packages("smapr")
```
To install the development version from GitHub:
```{r gh-installation, eval = FALSE}
# install.packages("devtools")
devtools::install_github("ropensci/smapr")
```
#### Docker instructions (alternative to a local installation)
If a local installation is not possible for some reason, we have made a Docker
image available with smapr and all its dependencies.
```
docker run -d -p 8787:8787 earthlab/smapr
```
In a web browser, navigate to localhost:8787 and log in with
username: rstudio, password: rstudio.
## Authentication
Access to the NASA SMAP data requires authentication through NASA's Earthdata
portal.
If you do not already have a username and password through Earthdata, you can
register for an account here: https://urs.earthdata.nasa.gov/
You cannot use this package without an Earthdata account.
Once you have an account, you need to pass your Earthdata username (`ed_un`)
and password (`ed_pw`) as environmental variables that can be read from within
your R session.
There are a couple of ways to do this:
### Recommended approach
Use `set_smap_credentials('yourusername', 'yourpasswd')`.
This will save your credentials by default, overwriting existing credentials if
`overwrite = TRUE`.
#### Alternative approaches
- Use `Sys.setenv()` interactively in your R session to set your username and
password (not including the `<` and `>`):
```{r, eval = FALSE}
Sys.setenv(ed_un = "<your username>", ed_pw = "<your password>")
```
- Create a text file `.Renviron` in your home directory, which contains your
username and password.
If you don't know what your home directory is, execute `normalizePath("~/")` in
the R console and it will be printed.
Be sure to include a new line at the end of the file or R will fail silently
when loading it.
Example `.Renviron file` (note the new line at the end!):
```
ed_un=slkdjfsldkjfs
ed_pw=dlfkjDD124^
```
Once this file is created, restart your R session and you should now be able to
access these environment variables (e.g., via `Sys.getenv("ed_un")`).
# SMAP data products
Multiple SMAP data products are provided by the NSIDC, and these products vary
in the amount of processing.
Currently, smapr primarily supports level 3 and level 4 data products,
which represent global daily composite and global three hourly modeled data
products, respectively.
There are a wide variety of data layers available in SMAP products, including surface soil moisture, root zone soil moisture, freeze/thaw status, surface temperature, vegetation water content, vegetation opacity, net ecosystem carbon exchange, soil temperature, and evapotranspiration.
NSIDC provides documentation for all SMAP data products on their
[website](https://nsidc.org/data/smap/smap-data.html), and we provide a summary
of data products supported by smapr below.
| Dataset id | Description | Resolution |
|------------|-----------------------------------------------------|------------|
| SPL2SMAP_S | SMAP/Sentinel-1 Radiometer/Radar Soil Moisture | 3 km |
| SPL3FTA | Radar Northern Hemisphere Daily Freeze/Thaw State | 3 km |
| SPL3SMA | Radar Global Daily Soil Moisture | 3 km |
| SPL3SMP | Radiometer Global Soil Moisture | 36 km |
| SPL3SMAP | Radar/Radiometer Global Soil Moisture | 9 km |
| SPL4SMAU | Surface/Rootzone Soil Moisture Analysis Update | 9 km |
| SPL4SMGP | Surface/Rootzone Soil Moisture Geophysical Data | 9 km |
| SPL4SMLM | Surface/Rootzone Soil Moisture Land Model Constants | 9 km |
| SPL4CMDL | Carbon Net Ecosystem Exchange | 9 km |
## Typical workflow
At a high level, most workflows follow these steps:
1. Find SMAP data with `find_smap()`
2. Download data with `download_smap()`
3. List data contents with `list_smap()`
4. Extract data with `extract_smap()`
Each of these steps are outlined below:
### Finding SMAP data
Data are hosted on a server by the National Snow and Ice Data Center.
The `find_smap()` function searches for specific data products and returns a
data frame of available data.
As data mature and pass checks, versions advance.
At any specific time, not all versions of all datasets for all dates may exist.
For the most up to date overview of dataset versions, see the NSIDC SMAP data
version [webpage](https://nsidc.org/data/smap/smap-data.html).
```{r find-data}
library(smapr)
library(raster)
available_data <- find_smap(id = "SPL3SMAP", date = "2015-05-25", version = 3)
str(available_data)
```
### Downloading and inspecting SMAP data
Given a data frame produced by `find_smap`, `download_smap` downloads the data
onto the local file system.
Unless a directory is specified as an argument, the data are stored in the
user's cache.
```{r download-data}
downloads <- download_smap(available_data)
str(downloads)
```
The SMAP data are provided in HDF5 format, and in any one file there are
actually multiple data sets, including metadata.
The `list_smap` function allows users to inspect the contents of downloaded
data at a high level (`all = FALSE`) or in depth (`all = TRUE`).
```{r list-data}
list_smap(downloads, all = FALSE)
```
To see all of the data fields, set `all = TRUE`.
### Extracting gridded data products
The `extract_smap` function extracts gridded data products
(e.g., global soil moisture) and returns Raster* objects.
If more than one file has been downloaded and passed into the first argument, `extract_smap` extracts all of the rasters and returns a RasterStack.
```{r extract-data, fig.align='center', fig.width=8, fig.height=7}
sm_raster <- extract_smap(downloads, "Soil_Moisture_Retrieval_Data/soil_moisture")
plot(sm_raster, main = "Level 3 soil moisture: May 25, 2015")
```
The path "Soil_Moisture_Retrieval_Data/soil_moisture" was determined from the
output of `list_smap(downloads, all = TRUE)`, which lists all of the data
contained in SMAP data files.
### Saving GeoTIFF output
The raster stack can be saved as a GeoTIFF using the `writeRaster` function
from the raster pacakge.
```{r}
writeRaster(sm_raster, "sm_raster.tif")
```
```{r, echo = FALSE, results='hide'}
# cleanup
file.remove("sm_raster.tif")
```
## Meta
* Please [report any issues or bugs](https://github.com/ropensci/smapr/issues),
after reading our contribution [guidelines](CONTRIBUTING.md), and the
[Contributor Code of Conduct](CONDUCT.md).
* License: GPL-3
* See `citation("smapr")` in R to cite this package in publications.
[](https://ropensci.org)