select_timeseries: Selects remote sensing records for a time series
In 16EAGLE/getSpatialData: Get different kinds of freely available spatial datasets

select_timeseries

R Documentation

Selects remote sensing records for a time series

Description

Selection is done according to aoi cloud cover (in case of optical data) and temporal characteristics. Both optical and SAR records are supported as well as combined selection for different products across systems and data providers.

Usage

select_timeseries(
  records,
  n_timestamps,
  min_distance,
  max_sub_period,
  min_improvement = 5,
  max_cloudcov_tile = 80,
  satisfaction_value = 98,
  prio_products = c(),
  aoi = NULL,
  write_cmask_mosaic = TRUE,
  write_preview_mosaic = TRUE,
  dir_out = NULL,
  as_sf = TRUE,
  verbose = TRUE
)

Arguments

`records`	data.frame as returned by calc_cloudcov, either complete or subsetted but with all columns. Records will be selected from these records. If `prio_products` is provided only these products will be handled.
`n_timestamps`	numeric the number of timestamps the timeseries shall cover.
`min_distance`	numeric the minimum number of days between two used acquisitions for distinguished timestamps. For example, if a scene from 20th May 2019 is selected for a timestamp and `min_distance == 10` then the next timestamp will not include scenes in <= 10 days after 20th May 2019. The first scene that the next timestamp could include would be the 31st May 2019, thus.
`max_sub_period`	numeric maximum number of days to be used for creating a mosaic per timestamp if mosaicking is needed. This determines how temporally close together the selected records for one timestamp are (if mosaicking is needed).
`min_improvement`	numeric the minimum increase of valid pixels percentage in a tile when adding a record. This protects from adding large amounts of records that improve coverage by only a few pixels. Default is 100.
`max_cloudcov_tile`	numeric maximum aoi cloud cover (%) a selected tile is allowed to have. The assumption is that a high cloud cover in a scene makes it unlikely that theoretically non-cloudy pixels are free from haze or shadows. Default is 80.
`satisfaction_value`	numeric percentage value at which mosaic is considered as cloud-free. Default is 98.
`prio_products`	character vector optional. Product names ordered by priority. Selection is done in the order of prio_products starting with the first product. Following products are included consecutively in case selection was not fullfilled by previous product. Product names must be provided as returned by get_select_supported. Landsat and MODIS can be summarized by 'landsat' respectively 'modis' if no further differentiation demanded. If prio_products is empty, given products in `records` will be selected in random order in case several are given in `records`.
`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.
`write_cmask_mosaic`	logical specifies if the timestamp-wise cloud mask mosaic rasters are written to file.
`write_preview_mosaic`	logical specifies if the timestamp-wise preview mosaic rasters are written to file.
`dir_out`	character. If `dir_out` is not NULL the given cloud mask rasters and a record file for each record will be saved in `dir_out`. If it is NULL, the session `dir_out` is used. If no session `dir_out` is set through set_archive an error is thrown.
`as_sf`	logical, whether records should be returned as `sf` `data.frame` or a simple `data.frame`. In both cases, spatial geometries are stored in column `footprint`.
`verbose`	logical, if `TRUE`, details on the function's progress will be visibile on the console. Default is TRUE.

Details

For running the selection you have to process calc_cloudcov first. Generally, the following products can be processed in select_* functionalities:

Sentinel-1
Sentinel-2 A/B
Sentinel-3 OLCI
Landsat 5-8
MODIS

For the precise supported product names call get_select_supported. When aiming at mixing two or more optical products you may order them by priority through prio_products. Coupled selection of optical and SAR sensors is possible. Optical records will always be selected first, SAR records second, in temporal accordance with the selected optical records.

Value

records data.frame holding four additional columns:

selected_for_timeseries logical column indicating for each record if it was selected (==TRUE).
selected_for_timestamp: numeric indicating for which timestamp the record was selected. If NA the record was selected for no timestamp.
rgb_mosaic_file: character path where the RGB preview mosaic is saved on disk. (not added if only SAR in records)
cmask_mosaic_file: character path where the cloud mask mosaic is saved on disk. (not added if only SAR in records)

Note

This functionality creates a 'tmp' folder below dir_out where temporary files are saved. This folder will be deleted at the end of the function call.