getSpatialData (version 0.0.4)

getSentinel_query: Query Sentinel-1, Sentinel-2, Sentinel-3, Sentinel-5P or Sentinel GNSS records

Description

getSentinel_query queries the Copernicus Open Access Hubs for Sentinel records by some basic input search parameters. The function returns a data frame of records that can be further filtered.

Usage

getSentinel_query(time_range, platform, aoi = NULL,
  check_avail = FALSE, gnss = FALSE, username = NULL,
  password = NULL, hub = "auto", verbose = TRUE)

Arguments

time_range

character, containing two elements: the query's starting date and stopping date, formatted "YYYY-MM-DD", e.g. "2017-05-15"

platform

character, identifies the platform. Either "Sentinel-1", "Sentinel-2", "Sentinel-3" or "Sentinel-5P".

aoi

sfc_POLYGON or SpatialPolygons or matrix, representing a single multi-point (at least three points) polygon of your area-of-interest (AOI). If it is a matrix, it has to have two columns (longitude and latitude) and at least three rows (each row representing one corner coordinate). If its projection is not +proj=longlat +datum=WGS84 +no_defs, it is reprojected to the latter. Use set_aoi instead to once define an AOI globally for all queries within the running session. If aoi is undefined, the AOI that has been set using set_aoi is used.

check_avail

logical, check if datasets are available on-demand or have been archived to the Copernicus Long-Term Archive (LTA). Adds an additional column available to the returned data frame of records. Default is FALSE, since check increases query request time.

gnss

logical, whether to query for GNSS RINEX records instead of remote sensing instrument records. If TRUE, only records of the dual-frequency GPS recievers mounted on Sentinel-1, -2, and -3 are returned and aoi settings are ignored. If FALSE (default), remote sensing instrument records, queried including aoi settings, are returned (see details).

username

character, a valid user name to the ESA Copernicus Open Access Hub. If NULL (default), the session-wide login credentials are used (see login_CopHub for details on registration).

password

character, the password to the specified user account. If NULL (default) and no seesion-wide password is defined, it is asked interactively ((see login_CopHub for details on registration).

hub

character, either

• "auto" (default) to automatically select a suitable Copernicus hub depending on the selected platform,

• "dhus" to look for operational Open Hub records only,

• "s3" to look for Sentinel-3 pre-operational records only,

• "s5p" to look for Sentinel-5P precursor pre-operational records only,

• "GNSS" to look for GNSS RINEX records only,

• or a valid API URL.

verbose

logical, whether to display details on the function's progress or output on the console.

Value

A data frame of records. Each row represents one record. The data frame can be further filtered by its columnwise attributes. Records can be handed to the other getSentinel functions for previewing and downloading.

Details

To query for records of remote sensing instruments by time_range, platform and aoi, argument gnss should be FALSE (default). If you are instead interested in (AOI-independent) GNSS records of the dual-frequency GPS recievers mounted on Sentinel-1, -2, and -3, set argument gnss to TRUE. GNSS data originally have been only used to precisely calculate the satellites' orbits, but then have been released to the scientific public due to their potential scientifc uses (for details, see https://earth.esa.int/web/sentinel/missions/sentinel-3/news/-/article/new-gnss-l1b-rinex-data-release-for-sentinel-1-2-and-3 and https://earth.esa.int/documents/247904/351187/GMES_Sentinels_POD_Service_File_Format_Specification).

See Also

getSentinel_data

Examples

# NOT RUN {
## Load packages
library(getSpatialData)
library(raster)
library(sf)
library(sp)

## Define an AOI (either matrix, sf or sp object)
data("aoi_data") # example aoi

aoi <- aoi_data[[3]] # AOI as matrix object, or better:
aoi <- aoi_data[[2]] # AOI as sp object, or:
aoi <- aoi_data[[1]] # AOI as sf object

## set AOI for this session
set_aoi(aoi)
view_aoi() #view AOI in viewer
# or, simply call set_aoi() without argument to interactively draw an AOI

## Define time range and platform
time_range <-  c("2017-08-01", "2017-08-30")
platform <- "Sentinel-2"

## set login credentials and an archive directory
# }
# NOT RUN {
login_CopHub(username = "username") #asks for password or define 'password'
set_archive("/path/to/archive/")

## Use getSentinel_query to search for data (using the session AOI)
records <- getSentinel_query(time_range = time_range, platform = platform)

## Get an overview of the records
View(records) #get an overview about the search records
colnames(records) #see all available filter attributes
unique(records$processinglevel) #use one of the, e.g. to see available processing levels

## Filter the records
records_filtered <- records[which(records$processinglevel == "Level-1C"),] #filter by Level

## Preview a single record
getSentinel_preview(record = records_filtered[5,])

## Download some datasets
datasets <- getSentinel_data(records = records_filtered[c(4,5,6),])

## Make them ready to use
datasets_prep <- prepSentinel(datasets, format = "tiff")

## Load them to R
r <- stack(datasets_prep[[1]][[1]][1]) #first dataset, first tile, 10m resoultion
# }
# NOT RUN {
# }