select_timeseries.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/select_timeseries.R
\name{select_timeseries}
\alias{select_timeseries}
\title{Selects remote sensing records for a time series}
\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{
\item{records}{data.frame as returned by \link{calc_cloudcov}, either complete or subsetted but with all columns. 
Records will be selected from these records. If \code{prio_products} is provided only these products will be handled.}

\item{n_timestamps}{numeric the number of timestamps the timeseries shall cover.}

\item{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 \code{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.}

\item{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).}

\item{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.}

\item{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.}

\item{satisfaction_value}{numeric percentage value at which mosaic is considered as cloud-free. Default is 98.}

\item{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 \link{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 \code{records} will be selected in random order in case several are given in \code{records}.}

\item{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 \code{+proj=longlat +datum=WGS84 +no_defs}, 
it is reprojected to the latter. Use \link{set_aoi} instead to once define an AOI globally 
for all queries within the running session. If \code{aoi} is undefined, the AOI that has been 
set using \link{set_aoi} is used.}

\item{write_cmask_mosaic}{logical specifies if the timestamp-wise cloud mask mosaic rasters are written to file.}

\item{write_preview_mosaic}{logical specifies if the timestamp-wise preview mosaic rasters are written to file.}

\item{dir_out}{character. If \code{dir_out} is not NULL the given cloud mask rasters and 
a record file for each record will be saved in \code{dir_out}. If it is NULL, the session 
\code{dir_out} is used.
If no session \code{dir_out} is set through \link{set_archive} an error is thrown.}

\item{as_sf}{logical, whether records should be returned as \code{sf} \code{data.frame} or a simple \code{data.frame}. In both cases, spatial geometries are stored in column \code{footprint}.}

\item{verbose}{logical, if \code{TRUE}, details on the function's progress will be visibile 
on the console. Default is TRUE.}
}
\value{
\code{records} data.frame holding four additional columns:
\enumerate{
\item selected_for_timeseries logical column indicating for each record if it was selected (==TRUE).
\item selected_for_timestamp: numeric indicating for which timestamp the record was selected. If NA the record was selected for no timestamp.
\item rgb_mosaic_file: character path where the RGB preview mosaic is saved on disk. (not added if only SAR in \code{records})
\item cmask_mosaic_file: character path where the cloud mask mosaic is saved on disk. (not added if only SAR in \code{records})
}
}
\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.
}
\details{
For running the selection you have to process \link{calc_cloudcov} first.
Generally, the following products can be processed in \code{select_*} functionalities:
\itemize{
\item Sentinel-1
\item Sentinel-2 A/B
\item Sentinel-3 OLCI
\item Landsat 5-8
\item MODIS
}
For the precise supported product names call \link{get_select_supported}.
When aiming at mixing two or more optical products you may order them by priority
through \code{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 \code{dir_out} where
temporary files are saved. This folder will be deleted at the end of the function call.
}
\author{
Henrik Fisser
}