Introduction to the smapr package

Maxwell B. Joseph

2018-06-19

library(smapr)
library(raster)
#> Loading required package: sp

This vignette outlines a basic use scenario for smapr. We will acquire and process NASA (Soil Moisture Active-Passive) SMAP data, and generate some simple visualizations. We’ll use the global level 4 SPL4SMAU (Surface/Rootzone Soil Moisture Analysis Update) data product.

Finding data

To find out which SMAP data are availble, we’ll use the find_smap function, which takes a data set ID, date(s) to search, and a dataset version. The SPL4SMAU data product is on version 3 (see https://nsidc.org/data/SPL4SMAU), and we’ll search for data from June 01, 2018.

available_data <- find_smap(id = 'SPL4SMAU', dates = '2018-06-01', version = 3)

This returns a data frame, where every row is one data file that is available on NASA’s servers.

Downloading data

To download the data, we can use download_smap:

local_files <- download_smap(available_data)

Now we have 8 data files, which correspond to different times of day on our search date, as indicated by the file names:

local_files$name[1:2]
#> [1] "SMAP_L4_SM_aup_20180601T030000_Vv3030_001"
#> [2] "SMAP_L4_SM_aup_20180601T060000_Vv3030_001"

Exploring data

Each file that we downloaded is an HDF5 file with multiple datasets bundled together. To list all of the data in a file we can use list_smap. By default, if we give list_smap a data frame of local files, it will return a list of data frames. Because all of these data files are of the same data product, using list_smap on one file (e.g., the first) will tell us what’s available in all of the files:

list_smap(local_files[1, ])
#> $SMAP_L4_SM_aup_20180601T030000_Vv3030_001
#>   group              name       otype  dclass         dim
#> 0     /     Analysis_Data   H5I_GROUP                    
#> 1     /     Forecast_Data   H5I_GROUP                    
#> 2     /          Metadata   H5I_GROUP                    
#> 3     / Observations_Data   H5I_GROUP                    
#> 4     /       cell_column H5I_DATASET INTEGER 3856 x 1624
#> 5     /          cell_lat H5I_DATASET   FLOAT 3856 x 1624
#> 6     /          cell_lon H5I_DATASET   FLOAT 3856 x 1624
#> 7     /          cell_row H5I_DATASET INTEGER 3856 x 1624
#> 8     /              time H5I_DATASET   FLOAT           1

To dig deeper, we can use the all argument to list_smap:

list_smap(local_files[1, ], all = TRUE)
#> $SMAP_L4_SM_aup_20180601T030000_Vv3030_001
#>                                  group                             name
#> 0                                    /                    Analysis_Data
#> 1                       /Analysis_Data              sm_profile_analysis
#> 2                       /Analysis_Data       sm_profile_analysis_ensstd
#> 3                       /Analysis_Data             sm_rootzone_analysis
#> 4                       /Analysis_Data      sm_rootzone_analysis_ensstd
#> 5                       /Analysis_Data              sm_surface_analysis
#> 6                       /Analysis_Data       sm_surface_analysis_ensstd
#> 7                       /Analysis_Data        soil_temp_layer1_analysis
#> 8                       /Analysis_Data soil_temp_layer1_analysis_ensstd
#> 9                       /Analysis_Data            surface_temp_analysis
#> 10                      /Analysis_Data     surface_temp_analysis_ensstd
#> 11                                   /                    Forecast_Data
#> 12                      /Forecast_Data              sm_profile_forecast
#> 13                      /Forecast_Data             sm_rootzone_forecast
#> 14                      /Forecast_Data              sm_surface_forecast
#> 15                      /Forecast_Data        soil_temp_layer1_forecast
#> 16                      /Forecast_Data            surface_temp_forecast
#> 17                      /Forecast_Data                    tb_h_forecast
#> 18                      /Forecast_Data             tb_h_forecast_ensstd
#> 19                      /Forecast_Data                    tb_v_forecast
#> 20                      /Forecast_Data             tb_v_forecast_ensstd
#> 21                                   /                         Metadata
#> 22                           /Metadata           AcquisitionInformation
#> 23    /Metadata/AcquisitionInformation                         platform
#> 24    /Metadata/AcquisitionInformation                 platformDocument
#> 25    /Metadata/AcquisitionInformation                            radar
#> 26    /Metadata/AcquisitionInformation                    radarDocument
#> 27    /Metadata/AcquisitionInformation                       radiometer
#> 28    /Metadata/AcquisitionInformation               radiometerDocument
#> 29                           /Metadata                             CRID
#> 30                      /Metadata/CRID                              AUP
#> 31                      /Metadata/CRID                             Root
#> 32                           /Metadata                           Config
#> 33                           /Metadata                      DataQuality
#> 34               /Metadata/DataQuality                              TBH
#> 35           /Metadata/DataQuality/TBH             CompletenessOmission
#> 36           /Metadata/DataQuality/TBH                DomainConsistency
#> 37               /Metadata/DataQuality                              TBV
#> 38           /Metadata/DataQuality/TBV             CompletenessOmission
#> 39           /Metadata/DataQuality/TBV                DomainConsistency
#> 40                           /Metadata            DatasetIdentification
#> 41                           /Metadata                           Extent
#> 42                           /Metadata        GridSpatialRepresentation
#> 43 /Metadata/GridSpatialRepresentation                         Latitude
#> 44 /Metadata/GridSpatialRepresentation                        Longitude
#> 45                           /Metadata                      ProcessStep
#> 46                           /Metadata             SeriesIdentification
#> 47                           /Metadata                           Source
#> 48                    /Metadata/Source                           L1C_TB
#> 49                                   /                Observations_Data
#> 50                  /Observations_Data                         tb_h_obs
#> 51                  /Observations_Data                   tb_h_obs_assim
#> 52                  /Observations_Data                  tb_h_obs_errstd
#> 53                  /Observations_Data                tb_h_obs_time_sec
#> 54                  /Observations_Data                  tb_h_orbit_flag
#> 55                  /Observations_Data             tb_h_resolution_flag
#> 56                  /Observations_Data                         tb_v_obs
#> 57                  /Observations_Data                   tb_v_obs_assim
#> 58                  /Observations_Data                  tb_v_obs_errstd
#> 59                  /Observations_Data                tb_v_obs_time_sec
#> 60                  /Observations_Data                  tb_v_orbit_flag
#> 61                  /Observations_Data             tb_v_resolution_flag
#> 62                                   /                      cell_column
#> 63                                   /                         cell_lat
#> 64                                   /                         cell_lon
#> 65                                   /                         cell_row
#> 66                                   /                             time
#>          otype  dclass         dim
#> 0    H5I_GROUP                    
#> 1  H5I_DATASET   FLOAT 3856 x 1624
#> 2  H5I_DATASET   FLOAT 3856 x 1624
#> 3  H5I_DATASET   FLOAT 3856 x 1624
#> 4  H5I_DATASET   FLOAT 3856 x 1624
#> 5  H5I_DATASET   FLOAT 3856 x 1624
#> 6  H5I_DATASET   FLOAT 3856 x 1624
#> 7  H5I_DATASET   FLOAT 3856 x 1624
#> 8  H5I_DATASET   FLOAT 3856 x 1624
#> 9  H5I_DATASET   FLOAT 3856 x 1624
#> 10 H5I_DATASET   FLOAT 3856 x 1624
#> 11   H5I_GROUP                    
#> 12 H5I_DATASET   FLOAT 3856 x 1624
#> 13 H5I_DATASET   FLOAT 3856 x 1624
#> 14 H5I_DATASET   FLOAT 3856 x 1624
#> 15 H5I_DATASET   FLOAT 3856 x 1624
#> 16 H5I_DATASET   FLOAT 3856 x 1624
#> 17 H5I_DATASET   FLOAT 3856 x 1624
#> 18 H5I_DATASET   FLOAT 3856 x 1624
#> 19 H5I_DATASET   FLOAT 3856 x 1624
#> 20 H5I_DATASET   FLOAT 3856 x 1624
#> 21   H5I_GROUP                    
#> 22   H5I_GROUP                    
#> 23   H5I_GROUP                    
#> 24   H5I_GROUP                    
#> 25   H5I_GROUP                    
#> 26   H5I_GROUP                    
#> 27   H5I_GROUP                    
#> 28   H5I_GROUP                    
#> 29   H5I_GROUP                    
#> 30   H5I_GROUP                    
#> 31   H5I_GROUP                    
#> 32   H5I_GROUP                    
#> 33   H5I_GROUP                    
#> 34   H5I_GROUP                    
#> 35   H5I_GROUP                    
#> 36   H5I_GROUP                    
#> 37   H5I_GROUP                    
#> 38   H5I_GROUP                    
#> 39   H5I_GROUP                    
#> 40   H5I_GROUP                    
#> 41   H5I_GROUP                    
#> 42   H5I_GROUP                    
#> 43   H5I_GROUP                    
#> 44   H5I_GROUP                    
#> 45   H5I_GROUP                    
#> 46   H5I_GROUP                    
#> 47   H5I_GROUP                    
#> 48   H5I_GROUP                    
#> 49   H5I_GROUP                    
#> 50 H5I_DATASET   FLOAT 3856 x 1624
#> 51 H5I_DATASET   FLOAT 3856 x 1624
#> 52 H5I_DATASET   FLOAT 3856 x 1624
#> 53 H5I_DATASET   FLOAT 3856 x 1624
#> 54 H5I_DATASET INTEGER 3856 x 1624
#> 55 H5I_DATASET INTEGER 3856 x 1624
#> 56 H5I_DATASET   FLOAT 3856 x 1624
#> 57 H5I_DATASET   FLOAT 3856 x 1624
#> 58 H5I_DATASET   FLOAT 3856 x 1624
#> 59 H5I_DATASET   FLOAT 3856 x 1624
#> 60 H5I_DATASET INTEGER 3856 x 1624
#> 61 H5I_DATASET INTEGER 3856 x 1624
#> 62 H5I_DATASET INTEGER 3856 x 1624
#> 63 H5I_DATASET   FLOAT 3856 x 1624
#> 64 H5I_DATASET   FLOAT 3856 x 1624
#> 65 H5I_DATASET INTEGER 3856 x 1624
#> 66 H5I_DATASET   FLOAT           1

Looking at this output, we can conclude that the file contains multiple arrays (notice the dim column). These arrays correspond to things like estimated root zone soil moisture (/Analysis_Data/sm_rootzone_analysis), estimated surface soil moisture (/Analysis_Data/sm_surface_analysis), and estimated surface temperature (/Analysis_Data/surface_temp_analysis). See https://nsidc.org/data/smap/spl4sm/data-fields#sm_surface_analysis for more detailed information on what these datasets represent and how they were generated.

Extracting data

The datasets that we are interested in are spatial grids. The smapr package can extract these data into raster objects with the extract_smap function, which takes a dataset name as an argument. These names are paths that can be generated from the output of list_smap. For example, if we want to get rootzone soil moisture, we can see a dataset with name sm_rootzone_analysis in group /Analysis_Data, so that the path to the dataset is /Analysis_Data/sm_rootzone_analysis:

sm_raster <- extract_smap(local_files, '/Analysis_Data/sm_rootzone_analysis')

This will extract all of the data in the data frame local_files, generating a RasterBrick with one layer per file:

sm_raster
#> class       : RasterBrick 
#> dimensions  : 1624, 3856, 6262144, 8  (nrow, ncol, ncell, nlayers)
#> resolution  : 9008.055, 9008.055  (x, y)
#> extent      : -17367530, 17367530, -7314541, 7314541  (xmin, xmax, ymin, ymax)
#> coord. ref. : +proj=cea +lon_0=0 +lat_ts=30 +x_0=0 +y_0=0 +datum=WGS84 +units=m +no_defs +ellps=WGS84 +towgs84=0,0,0 
#> data source : /home/max/.cache/smap/tmp.tif 
#> names       : SMAP_L4_S//Vv3030_001, SMAP_L4_S//Vv3030_001, SMAP_L4_S//Vv3030_001, SMAP_L4_S//Vv3030_001, SMAP_L4_S//Vv3030_001, SMAP_L4_S//Vv3030_001, SMAP_L4_S//Vv3030_001, SMAP_L4_S//Vv3030_001 
#> min values  :           0.006924022,           0.006930893,           0.006900712,           0.006942416,           0.007022214,           0.006598844,           0.006681126,           0.006761795 
#> max values  :                   0.8,                   0.8,                   0.8,                   0.8,                   0.8,                   0.8,                   0.8,                   0.8

We can visualize root zone soil moisture at different times using the raster package:

plot(sm_raster)