Repository files navigation

An R package for acquisition and processing ofNASA (Soil MoistureActive-Passive) SMAP data

To install smapr from CRAN:

install.packages("smapr")

To install the development version from GitHub:

# install.packages("devtools")devtools::install_github("ropensci/smapr")

If a local installation is not possible for some reason, we have made aDocker 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.

Access to the NASA SMAP data requires authentication through NASA’sEarthdata portal. If you do not already have a username and passwordthrough Earthdata, you can register for an account here:https://urs.earthdata.nasa.gov/ You cannot use this package without anEarthdata account.

Once you have an account, you need to pass your Earthdata username(ed_un) and password (ed_pw) as environmental variables that can beread from within your R session. There are a couple of ways to do this:

Useset_smap_credentials('yourusername', 'yourpasswd'). This will saveyour credentials by default, overwriting existing credentials ifoverwrite = TRUE.

• UseSys.setenv() interactively in your R session to set yourusername and password (not including the< and>):

Sys.setenv(ed_un="<your username>",ed_pw="<your password>")

• Create a text file.Renviron in your home directory, which containsyour username and password. If you don’t know what your home directoryis, executenormalizePath("~/") in the R console and it will beprinted. Be sure to include a new line at the end of the file or Rwill fail silently when loading it.

Example.Renviron file (note the new line at the end!):

ed_un=slkdjfsldkjfsed_pw=dlfkjDD124^

Once this file is created, restart your R session and you should now beable to access these environment variables (e.g., viaSys.getenv("ed_un")).

Multiple SMAP data products are provided by the NSIDC, and theseproducts vary in the amount of processing. Currently, smapr primarilysupports level 3 and level 4 data products, which represent global dailycomposite 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/thawstatus, surface temperature, vegetation water content, vegetationopacity, net ecosystem carbon exchange, soil temperature, andevapotranspiration. NSIDC provides documentation for all SMAP dataproducts on theirwebsite,and we provide a summary of data products supported by smapr below.

At a high level, most workflows follow these steps:

1. Find SMAP data withfind_smap()
2. Download data withdownload_smap()
3. List data contents withlist_smap()
4. Extract data withextract_smap()

Each of these steps are outlined below:

Data are hosted on a server by the National Snow and Ice Data Center.Thefind_smap() function searches for specific data products andreturns a data frame of available data. As data mature and pass checks,versions advance. At any specific time, not all versions of all datasetsfor all dates may exist. For the most up to date overview of datasetversions, see the NSIDC SMAP data versionwebpage.

library(smapr)library(terra)#> terra 1.7.18available_data<- find_smap(id="SPL3SMAP",date="2015-05-25",version=3)str(available_data)#> 'data.frame':    1 obs. of  3 variables:#>  $ name: chr "SMAP_L3_SM_AP_20150525_R13080_001"#>  $ date: Date, format: "2015-05-25"#>  $ dir : chr "SPL3SMAP.003/2015.05.25/"

Given a data frame produced byfind_smap,download_smap downloadsthe data onto the local file system. Unless a directory is specified asan argument, the data are stored in the user’s cache.

downloads<- download_smap(available_data)#> Downloading https://n5eil01u.ecs.nsidc.org/SMAP/SPL3SMAP.003/2015.05.25/SMAP_L3_SM_AP_20150525_R13080_001.h5#> Downloading https://n5eil01u.ecs.nsidc.org/SMAP/SPL3SMAP.003/2015.05.25/SMAP_L3_SM_AP_20150525_R13080_001.qa#> Downloading https://n5eil01u.ecs.nsidc.org/SMAP/SPL3SMAP.003/2015.05.25/SMAP_L3_SM_AP_20150525_R13080_001.h5.iso.xmlstr(downloads)#> 'data.frame':    1 obs. of  4 variables:#>  $ name     : chr "SMAP_L3_SM_AP_20150525_R13080_001"#>  $ date     : Date, format: "2015-05-25"#>  $ dir      : chr "SPL3SMAP.003/2015.05.25/"#>  $ local_dir: chr "~/.cache/smap"

The SMAP data are provided in HDF5 format, and in any one file there areactually multiple data sets, including metadata. Thelist_smapfunction allows users to inspect the contents of downloaded data at ahigh level (all = FALSE) or in depth (all = TRUE).

list_smap(downloads,all=FALSE)#> $SMAP_L3_SM_AP_20150525_R13080_001#>                           name group     otype dclass  dim#> 1                     Metadata     . H5I_GROUP   <NA> <NA>#> 2 Soil_Moisture_Retrieval_Data     . H5I_GROUP   <NA> <NA>

To see all of the data fields, setall = TRUE.

Theextract_smap function extracts gridded data products (e.g., globalsoil moisture). If more than one file has been downloaded and passedinto the first argument,extract_smap extracts data for each file

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 determinedfrom the output oflist_smap(downloads, all = TRUE), which lists allof the data contained in SMAP data files.

The data can be saved as a GeoTIFF using thewriteRaster function fromthe terra pacakge.

writeRaster(sm_raster,"sm_raster.tif")

• Pleasereport any issues orbugs, after reading ourcontributionguidelines, and theContributor Codeof Conduct.
• License: GPL-3
• Seecitation("smapr") in R to cite this package in publications.