Title: Acquire and Explore BEC-SMOS L4 Soil Moisture Data in R
Version: 1.0.1
Date: 2023-07-13
Author: Tatiana A. Shestakova ORCID iD [aut, cre, cph]
Maintainer: Tatiana A. Shestakova <tasha.work24@gmail.com>
Description: Provides functions that automate accessing, downloading and exploring Soil Moisture and Ocean Salinity (SMOS) Level 4 (L4) data developed by Barcelona Expert Center (BEC). Particularly, it includes functions to search for, acquire, extract, and plot BEC-SMOS L4 soil moisture data downscaled to ~1 km spatial resolution. Note that SMOS is one of Earth Explorer Opportunity missions by the European Space Agency (ESA). More information about SMOS products can be found at https://earth.esa.int/eogateway/missions/smos/data.
License: GPL-3
URL: https://github.com/tshestakova/smosr
BugReports: https://github.com/tshestakova/smosr/issues
Depends: R (≥ 4.0.0)
Imports: fields, graphics, grDevices, lubridate, methods, ncdf4, RCurl, terra, tidyr, utils
Suggests: knitr, rmarkdown, testthat (≥ 3.0.0)
Encoding: UTF-8
RoxygenNote: 7.2.3
NeedsCompilation: no
Packaged: 2023-07-20 16:53:36 UTC; tshestakova
Repository: CRAN
Date/Publication: 2023-07-20 18:50:02 UTC

Download BEC-SMOS soil moisture data

Description

This function automates downloading of BEC-SMOS soil moisture data to a local computer via a secure FTP (SFTP) server.

Usage

download_smos(data, dir = NULL)

Arguments

data

a character vector as produced by find_smos() containing external links to the data files on the BEC server.

dir

a character string specifying a path to a local directory in which to save the data. Default value is NULL meaning that the dataset is stored in a temporary directory of the current R session.

Details

This function downloads the original BEC-SMOS soil moisture data in NetCDF format ("as is") via a secure FTP (SFTP) server. The data files are stored on the local computer in a temporary directory of the current R session (default option) if no otherwise specified by the user.

Note that the registration as a user on the Barcelona Expert Center (BEC) webpage is required to access the server. See set_credentials() for details.

Value

downloaded files in the specified directory

References

Pablos M, Gonzalez-Haro C, Portal G, Piles M, Vall-llossera M, Portabella M (2022). SMOS L4 Surface Soil Moisture downscaled maps at 1 km EASE-2 (reprocessed mode) (V.6.0) [Dataset].

Examples

## Not run: 
# to download files found with find_smos() into a temporary directory of the current R session
start_date <- as.Date("2022-01-01")
end_date <- as.Date("2022-12-31")
date_range <- seq(start_date, end_date, by = 30)
smos_data <- find_smos(freq = 3, orbit = "des", dates = date_range)
download_smos(smos_data)

## End(Not run)

Extract BEC-SMOS soil moisture estimates for specific geographical locations

Description

This function facilitates reading of the original BEC-SMOS soil moisture data files and extracting relevant information for specific geographical locations by using Lat/Lon coordinates in decimal degrees.

Usage

extract_smos(
  data,
  lat,
  lon,
  save = FALSE,
  dir = NULL,
  filename = "smosr_output.csv"
)

Arguments

data

a character vector as produced by list_smos() containing links to the data files on the local computer.

lat

a numeric vector containing latitudes of geographical locations to extract the data from (in ‘latlon’ projection).

lon

a numeric vector containing longitudes of geographical locations to extract the data from (in ‘latlon’ projection).

save

a logical vector indicating whether the output should be saved as a CSV file. Default is FALSE.

dir

a character string specifying a path to a local directory in which to save the CSV file with the output. Default value is NULL meaning that the file is stored in a temporary directory of the current R session.

filename

a character string naming the CSV file for saving the output. If save = TRUE and no filename is specified by the user, the data is saved in a file with a generic name ‘smosr_output.csv’.

Details

This function reads the original BEC-SMOS soil moisture data files in NetCDF format, converts data from EASE-2 grid cells to geographic coordinates, and extracts relevant information for Lat/Lon locations specified by the user.

The data retrieved from each data file includes:

- the coordinates of spatial points (Lon and Lat) from which the data were extracted;

- frequency and SMOS orbit of each file over which the function iterated;

- date and time when the data was obtained;

- soil moisture estimate (SM);

- quality assurance (QA) flag corresponding to each SM estimate.

The output of this function could be saved as a CSV file.

Value

a data.matrix with the relevant information as described in Details.

References

Pablos M, Gonzalez-Haro C, Portal G, Piles M, Vall-llossera M, Portabella M (2022). SMOS L4 Surface Soil Moisture downscaled maps at 1 km EASE-2 (reprocessed mode) (V.6.0) [Dataset].

Examples

## Not run: 
# to iterate over a list of BEC-SMOS data files produced by list_smos() and
# extract soil moisture estimates for the specified geographical locations
smos_files <- list_smos()
lat <- c(40.42, 41.90, 48.86, 52.50, 59.91)
lon <- c(-3.70, 12.50, 2.35, 13.40, 10.75)
sm_estimates <- extract_smos(data = smos_files, lat = lat, lon = lon)

## End(Not run)

Find BEC-SMOS soil moisture data on the server

Description

This function searches for BEC-SMOS soil moisture data available on Barcelona Expert Center (BEC) server for the frequency, orbit, and dates specified by the user.

Usage

find_smos(freq, orbit, dates)

Arguments

freq

an integer specifying temporal frequency of the data. Possible values are: 1 - for daily data, or 3 - for 3-day moving averages. No default value is provided.

orbit

a character (or character string) specifying SMOS orbit corresponding to the data. Possible values are: ‘a’, ‘asc’, and ‘ascending’ - for an ascending pass, or ‘d’, ‘des’, or ‘descending’ - for a descending pass. No default value is provided.

dates

an object of class Date or a character string formatted as ‘yyyy-mm-dd’ (e.g. ‘2010-06-01’) which specifies the date(s) to search through. To look for a specific date, it can be a Date object or a character vector of length 1. To iterate over various dates or a time interval, a multiple-element object of class Date or a vector should be passed (e.g. as produced by seq.Date).

Details

BEC-SMOS soil moisture (SM) data is a regional root zone SM product that covers Europe and Mediterranean countries. Particularly, smosr package works with the reprocessed SMOS Level 4 (L4) SM estimates downscaled to ~1 km spatial resolution (EASE-grid v.2). The data is computed for two time periods (argument frequency): daily and 3-day moving averages produced by a temporal aggregation of the daily products. Note that SMOS ascending and descending passes (argument orbit) are processed separately. The data is available starting from June 1st, 2010 throughout the end of 2022. The currently supported version is 6.0. For more details about the BEC-SMOS SM products, see the technical note available at https://digital.csic.es/handle/10261/303808.

Note that the registration as a user on the Barcelona Expert Center (BEC) webpage is required to access the server. See set_credentials() for details.

Value

a character vector containing full links to the data files on the server.

References

Pablos M, Gonzalez-Haro C, Portal G, Piles M, Vall-llossera M, Portabella M (2022). SMOS L4 Surface Soil Moisture downscaled maps at 1 km EASE-2 (reprocessed mode) (V.6.0) [Dataset].

Examples

## Not run: 
# to look for BEC-SMOS data on a specific date
smos_data <- find_smos(freq = 1, orbit = "a", dates = "2022-12-31")
# to search data over a date range
start_date <- as.Date("2022-01-01")
end_date <- as.Date("2022-12-31")
date_range <- seq(start_date, end_date, by = 10)
smos_data <- find_smos(freq = 3, orbit = "descending", dates = date_range)

## End(Not run)

List BEC-SMOS data files stored on a local computer

Description

This function returns a list of the BEC-SMOS data files previously stored on a local computer.

Usage

list_smos(
  freq = NULL,
  orbit = NULL,
  dates = NULL,
  dir = NULL,
  recursive = FALSE
)

Arguments

freq

an integer specifying temporal frequency of the data. Possible values are: 1 - for daily data, or 3 - for 3-day moving averages, and NULL - for cases when data frequency is irrelevant. Default value is NULL.

orbit

a character (or character string) specifying SMOS orbit corresponding to the data. Possible values are: ‘a’, ‘asc’, and ‘ascending’ - for an ascending pass, or ‘d’, ‘des’, or ‘descending’ - for a descending pass, and NULL - for cases when orbit is irrelevant. Default value is NULL.

dates

an object of class Date or a character string formatted as ‘yyyy-mm-dd’ (e.g. ‘2010-06-01’) which specifies the date(s) to search through. To look for a specific date, it can be a Date object or a character vector of length 1. To iterate over various dates or a time interval, a multiple-element object of class Date or a vector should be passed (e.g. as produced by seq.Date).

dir

a character string specifying a path to a local directory in which to search the data for. Default value is NULL meaning that the dataset is looked up in a temporary directory of the current R session.

recursive

a logical vector indicating whether the listing should recurse into directories. Default is FALSE.

Details

This function iterates over all files in a temporary directory of the current R session (default option) or another local folder as indicated by dir argument and returns a list of the BEC-SMOS data files with the frequency, orbit, and dates specified by the user. If no arguments are provided, all BEC-SMOS soil moisture data files found in the selected folder will be listed. A recursive option is also available.

Value

a character vector containing full links to the data files on the local computer.

References

Pablos M, Gonzalez-Haro C, Portal G, Piles M, Vall-llossera M, Portabella M (2022). SMOS L4 Surface Soil Moisture downscaled maps at 1 km EASE-2 (reprocessed mode) (V.6.0) [Dataset].

Examples

## Not run: 
# to list BEC-SMOS data files with the specified frequency and SMOS orbit
# stored in a temporary directory of the current R session
smos_files <- list_smos(freq = 3, orbit = "des")

## End(Not run)

Print the dates for which BEC-SMOS soil moisture data were not found

Description

This function prints out the dates for which BEC-SMOS soil moisture data with specified frequency and orbit arguments were not found on the BEC server. This information is automatically generated while running find_smos(), but displayed only if requested by the user.

Usage

missing_smos()

Value

a character string containing dates for which the data files were not found on the server.

References

Pablos M, Gonzalez-Haro C, Portal G, Piles M, Vall-llossera M, Portabella M (2022). SMOS L4 Surface Soil Moisture downscaled maps at 1 km EASE-2 (reprocessed mode) (V.6.0) [Dataset].

Examples

## Not run: 
missing_smos()

## End(Not run)

Draw a raster image of BEC-SMOS soil moisture data

Description

This function draws a raster image of BEC-SMOS soil moisture data corresponding to a single data file and specific geographical extent.

Usage

plot_raster_smos(data, lat = NULL, lon = NULL, QA = NULL)

Arguments

data

a character string containing a link to a single BEC-SMOS data file stored on the local computer.

lat

a numeric vector of length 2 containing latitudinal bounds of the plotting region (in ‘latlon’ projection). Default value is NULL meaning that all data between min and max latitudes are drawn.

lon

a numeric vector of length 2 containing longitudinal bounds of the plotting region (in ‘latlon’ projection). Default value is NULL meaning that all data between min and max longitudes are drawn.

QA

a numeric vector specifying the desired data quality to be plotted. Possible values range from 0 (good quality data) to 15. To know the meanings of QA flags, see Details.

Details

This function reads an original BEC-SMOS soil moisture data file in NetCDF format, converts data from EASE-2 grid cells to geographic coordinates, and draws a raster image of soil moisture estimates in ‘latlon’ projection. The image can be drawn for a specific geographical extent if requested by the user. Otherwise, the entire dataset across Europe (between 28 and 72 degrees north and -11 and 40 degrees east) will be plotted. Note that due to high resolution of the data (~1 km), the execution of this function may take a long time to be completed depending on the amount of data to be drawn.

**** Quality assurance (QA) ****

QA flags are coded by four significant bits as described below:

-------------- --------------------------------------------------------------------------------
Bit position Bit value
-------------- --------------------------------------------------------------------------------
[0] 0 - Brightness temperature not affected by sea-land contamination
1 - Brightness temperature corrected by sea-land contamination
------------- --------------------------------------------------------------------------------
[1] 0 - Radio Frequency Interference (RFI) not flagged in ESA L1C
brightness temperature
1 - RFI flagged in ESA L1C brightness temperature
------------- --------------------------------------------------------------------------------
[2] 0 - L3 soil moisture with data obtained from L2 retrievals
1 - L3 soil moisture with data obtained from a linear model
------------- --------------------------------------------------------------------------------
[3] 0 - L4 soil moisture values within the interval [0,1] m^3/m^3
1 - L4 soil moisture values outside the interval [0,1] m^3/m^3
------------- --------------------------------------------------------------------------------

In case of the 3-day averaged data, each bit of the quality flag is activated if at least one soil moisture estimate during the corresponding time interval is affected.

Value

a raster image

References

Pablos M, Gonzalez-Haro C, Portal G, Piles M, Vall-llossera M, Portabella M (2022). SMOS L4 Surface Soil Moisture downscaled maps at 1 km EASE-2 (reprocessed mode) (V.6.0) [Dataset].

Examples

## Not run: 
# to draw a raster image of soil moisture data corresponding to the first BEC-SMOS file
# from a list produced by list_smos() and within the specified geographical bounds#'
smos_files <- list_smos()
lat <- c(35.00, 45.00)
lon <- c(-10.50, 4.50)
plot_raster_smos(data = smos_files[1], lat = lat, lon = lon)

## End(Not run)

Plot temporal series of BEC-SMOS soil moisture data

Description

This function plots temporal series of BEC-SMOS soil moisture data extracted for specific geographical locations.

Usage

plot_temporal_smos(data, freq = NULL, orbit = NULL, dates = NULL, QA = NULL)

Arguments

data

a data.matrix containing soil moisture data as produced by extract_smos().

freq

an integer specifying temporal frequency of the data. Possible values are: 1 - for daily data, 3 - for 3-day moving averages, and NULL - for cases when data frequency is irrelevant. Default value is NULL.

orbit

a character (or character string) specifying SMOS orbit corresponding to the data. Possible values are: ‘a’, ‘asc’, and ‘ascending’ - for an ascending pass, or ‘d’, ‘des’, or ‘descending’ - for a descending pass, and NULL - for cases when orbit is irrelevant. Default value is NULL.

dates

a object of class Date or a character string formatted as ‘yyyy-mm-dd’ (e.g. ‘2010-06-01’) which specifies the dates to plot the data for. A multiple-element object of class Date or a vector should be passed (e.g. as produced by seq.Date).

QA

a numeric vector specifying the desired data quality to be plotted. Possible values range from 0 (good quality data) to 15. To know the meanings of QA flags, see Details.

Details

This function takes as input temporal series of BEC-SMOS soil moisture estimates extracted for specific geographical locations and plots these data as a line chart. Note that the data characterized by the same frequency and SMOS orbit can be drawn at a time. If the dataset to plot contains a mixture of temporal resolutions and/or SMOS passes, arguments frequency and orbit must be specified. In addition, the dataset can be filtered by desired data quality and specific dates to be plotted.

**** Quality assurance (QA) ****

QA flags are coded by four significant bits as described below:

-------------- --------------------------------------------------------------------------------
Bit position Bit value
-------------- --------------------------------------------------------------------------------
[0] 0 - Brightness temperature not affected by sea-land contamination
1 - Brightness temperature corrected by sea-land contamination
------------- --------------------------------------------------------------------------------
[1] 0 - Radio Frequency Interference (RFI) not flagged in ESA L1C
brightness temperature
1 - RFI flagged in ESA L1C brightness temperature
------------- --------------------------------------------------------------------------------
[2] 0 - L3 soil moisture with data obtained from L2 retrievals
1 - L3 soil moisture with data obtained from a linear model
------------- --------------------------------------------------------------------------------
[3] 0 - L4 soil moisture values within the interval [0,1] m^3/m^3
1 - L4 soil moisture values outside the interval [0,1] m^3/m^3
------------- --------------------------------------------------------------------------------

In case of the 3-day averaged data, each bit of the quality flag is activated if at least one soil moisture estimate during the corresponding time interval is affected.

Value

a line chart

References

Pablos M, Gonzalez-Haro C, Portal G, Piles M, Vall-llossera M, Portabella M (2022). SMOS L4 Surface Soil Moisture downscaled maps at 1 km EASE-2 (reprocessed mode) (V.6.0) [Dataset].

Examples

## Not run: 
# to plot extracted temporal series of BEC-SMOS soil moisture data produced by extract_smos()
# with the specified frequency, SMOS orbit and QA
smos_files <- list_smos()
lat <- c(40.42, 41.90, 48.86, 52.50, 59.91)
lon <- c(-3.70, 12.50, 2.35, 13.40, 10.75)
sm_estimates <- extract_smos(data = smos_files, lat = lat, lon = lon)
plot_temporal_smos(data = sm_estimates, freq = 3, orbit = "des", QA = 0)

## End(Not run)

Set credentials to access Barcelona Expert Center (BEC) server

Description

To use some functionalities of smosr package (e.g. access the server or download data to a local computer), the user should first register at Barcelona Expert Center (BEC) webpage. This function allows the authenticated users to set their BEC credentials (username and password) for the current R session which are used internally in find_smos() and download_smos().

Usage

set_credentials(username, password)

Arguments

username

a character string containing BEC server username.

password

a character string containing BEC server password.

Details

If you do not have your BEC login details yet, please register on https://bec.icm.csic.es/bec-ftp-service-registration/.

Value

a character string with the inputs pasted together in the format required by find_smos() and download_smos().

Examples

## Not run: 
set_credentials("username", "password")

## End(Not run)