extract_s2ts: Extract time series from sen2r archives

In ranghetti/sen2rts: Build and Analyse Sentinel-2 Time Series

Extract time series from sen2r archives

Description

Extract time series from a Sentinel-2 data archive (created with the package sen2r) over spatial features (points or polygons). Quality flags can be added exploiting an additional extracted archive (see arguments scl_paths and cld_paths).

Usage

extract_s2ts(
  in_paths,
  in_sf,
  fun = "mean",
  in_sf_id,
  scl_paths,
  cld_paths,
  scl_w,
  fun_w = "mean"
)

Arguments

in_paths	Paths of the sen2r files (eventually obtained using read_in_cube(..., out_format = "path")).
in_sf	Object with polygonal or point geometries
fun	(optional) aggregation function (or function name) to be used in case of polygonal in_sf features. Default is mean. If scl_paths and/or cld_paths are defined: the default mean is intended as weighted.mean() (where the computed quality flags are used as weights); only the alternative value "best" is accepted (in this case, the pixel with the higher quality flag - or the average of pixels with the same higher quality flags - is considered).
in_sf_id	(optional) character vector corresponding to the name/names of the in_sf column with the features IDs. If missing, the row number is used.
scl_paths	(optional) Paths of the SCL files (they must correspond to in_paths); if provided, it is used to weight pixels during the aggregation and to provide an output quality flag. See details for the conversion between SCL and weights.
cld_paths	(optional) Paths of the CLD files (they must correspond to in_paths); see scl_paths. See details for the conversion between SCL and weights.
scl_w	(optional) weights to be used for each SCL class, which can be created using function scl_weights(). If missing, the default outputs of scl_weights() are used. See details for the conversion between SCL and weights.
fun_w	(optional) function to be used to aggregate quality flags in case of polygonal in_sf features. Default is mean.

Details

To generate pixel weights, SCL and/or CLD layers can be used.

SCL are categorical layers (12 levels), so each level must be converted in a 0-1 numeric value. This is done by function scl_weights(). If the user provides only scl_paths, the layer of weights will be a 0-1 numeric layer in which each pixel value corresponds to the 0-1 value associated with the corresponding SCL class.

CLD are integer layers with the percentage (0-100) of cloud probability. Assumed that a CLD of 0% is associated to a weight of 1 and a CLD of 100% to a weight of 0, intermediate values are computed taking into account the output of scl_weights() for classes "cloud_high_probability", "cloud_medium_probability" and "unclassified" (this because CLD values are in the range 80-100 when associated to the SCL class "cloud_high_probability", in the range 20-80 when associated to "cloud_medium_probability" and in the range 20-80 when associated to "unclassified" or "thin_cirrus"). The two values "cloud_medium_probability" - "cloud_high_probability" and "unclassified" - "cloud_medium_probability" are taken as breaks to reclassify CLD. I.e., consider the default case: scl_weights()[c("cloud_high_probability", "cloud_medium_probability", "unclassified")] returns ⁠0.0 0.1 0.5⁠; so, breaks 0.05 and 0.35 are used, meaning that CLD values in the range 80-100% are rescaled to 0-0.05, CLD values in the range 20-80% are rescaled to 0.05-0.35 and CLD values in the range 80-100% are rescaled to 0.35-1. If the user provides only cld_paths, the layer of weights will be a 0-1 numeric layer with the above described values.

Finally, if the user provides both scl_paths and cld_paths, the two layers of weights are combined and the lowest quality flag is considered.

Value

The output time series in s2ts format.

Author(s)

Luigi Ranghetti, PhD (2020) [e-mail]

Examples

# Load input data
data("sampleroi")
sen2r_ndvi_paths <- sample_paths("NDVI")
sen2r_scl_paths <- sample_paths("SCL")


# Simple TS extraction from polygons (without quality flags)
ts_raw_0 <- extract_s2ts(sen2r_ndvi_paths, sampleroi)
print(ts_raw_0, topn = 5)


# TS extraction from polygons using a SCL archive for quality flags
# (example used to produce the sample dataset "ts_raw")
ts_raw <- extract_s2ts(
  sen2r_ndvi_paths, 
  sampleroi,
  scl_paths = sen2r_scl_paths
)
ts_raw$value <- ts_raw$value / 1E4 # reshape to standard NDVI range -1 to 1
print(ts_raw, topn = 5) # standard print
head(as.data.frame(ts_raw)) # see content
plot(ts_raw)


# TS extraction from polygons using a different aggregation function
ts_raw_2 <- extract_s2ts(sen2r_ndvi_paths, sampleroi, fun = "max")

# TS extraction from points
samplepts <- suppressWarnings(sf::st_centroid(sampleroi))
ts_raw_3 <- extract_s2ts(sen2r_ndvi_paths, samplepts)

ranghetti/sen2rts documentation built on March 31, 2024, 1:18 a.m.