Title: | Acquire and Explore BEC-SMOS L4 Soil Moisture Data in R |
---|---|
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>. |
Authors: | Tatiana A. Shestakova [aut, cre, cph]
|
Maintainer: | Tatiana A. Shestakova <[email protected]> |
License: | GPL-3 |
Version: | 1.0.1 |
Built: | 2025-02-14 05:27:16 UTC |
Source: | https://github.com/tshestakova/smosr |
This function automates downloading of BEC-SMOS soil moisture data to a local computer via a secure FTP (SFTP) server.
download_smos(data, dir = NULL)
download_smos(data, dir = NULL)
data |
a character vector as produced by |
dir |
a character string specifying a path to a local directory in which
to save the data. Default value is |
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.
downloaded files in the specified directory
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].
## 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)
## 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)
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.
extract_smos( data, lat, lon, save = FALSE, dir = NULL, filename = "smosr_output.csv" )
extract_smos( data, lat, lon, save = FALSE, dir = NULL, filename = "smosr_output.csv" )
data |
a character vector as produced by |
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 |
dir |
a character string specifying a path to a local directory in which
to save the CSV file with the output. Default value is |
filename |
a character string naming the CSV file for saving the output.
If |
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.
a data.matrix with the relevant information as described in Details.
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].
## 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)
## 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)
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.
find_smos(freq, orbit, dates)
find_smos(freq, orbit, dates)
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 |
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.
a character vector containing full links to the data files on the server.
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].
## 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)
## 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)
This function returns a list of the BEC-SMOS data files previously stored on a local computer.
list_smos( freq = NULL, orbit = NULL, dates = NULL, dir = NULL, recursive = FALSE )
list_smos( freq = NULL, orbit = NULL, dates = NULL, dir = NULL, recursive = FALSE )
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 |
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
|
dates |
an object of class |
dir |
a character string specifying a path to a local directory in which
to search the data for. Default value is |
recursive |
a logical vector indicating whether the listing should
recurse into directories. Default is |
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.
a character vector containing full links to the data files on the local computer.
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].
## 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)
## 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)
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.
missing_smos()
missing_smos()
a character string containing dates for which the data files were not found on the server.
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].
## Not run: missing_smos() ## End(Not run)
## Not run: missing_smos() ## End(Not run)
This function draws a raster image of BEC-SMOS soil moisture data corresponding to a single data file and specific geographical extent.
plot_raster_smos(data, lat = NULL, lon = NULL, QA = NULL)
plot_raster_smos(data, lat = NULL, lon = NULL, QA = NULL)
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 |
lon |
a numeric vector of length 2 containing longitudinal bounds of
the plotting region (in ‘latlon’ projection). Default value is |
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. |
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.
a raster image
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].
## 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)
## 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)
This function plots temporal series of BEC-SMOS soil moisture data extracted for specific geographical locations.
plot_temporal_smos(data, freq = NULL, orbit = NULL, dates = NULL, QA = NULL)
plot_temporal_smos(data, freq = NULL, orbit = NULL, dates = NULL, QA = NULL)
data |
a data.matrix containing soil moisture data as produced by
|
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 |
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
|
dates |
a object of class |
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. |
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.
a line chart
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].
## 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)
## 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)
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()
.
set_credentials(username, password)
set_credentials(username, password)
username |
a character string containing BEC server username. |
password |
a character string containing BEC server password. |
If you do not have your BEC login details yet, please register on https://bec.icm.csic.es/bec-ftp-service-registration/.
a character string with the inputs pasted together in the format
required by find_smos()
and
download_smos()
.
## Not run: set_credentials("username", "password") ## End(Not run)
## Not run: set_credentials("username", "password") ## End(Not run)