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.

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.

Value

records data.frame holding four additional columns:

  1. selected_for_timeseries logical column indicating for each record if it was selected (==TRUE).

  2. selected_for_timestamp: numeric indicating for which timestamp the record was selected. If NA the record was selected for no timestamp.

  3. rgb_mosaic_file: character path where the RGB preview mosaic is saved on disk. (not added if only SAR in records)

  4. cmask_mosaic_file: character path where the cloud mask mosaic is saved on disk. (not added if only SAR in records)

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.

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.

Author

Henrik Fisser