Retrieves the simple statistics for the area of interest calculated based on satellite imagery without having to download images.
Usage
GetStatistics(
aoi,
bbox,
time_range,
collection,
script,
mosaicking_order = c("mostRecent", "leastRecent", "leastCC")[1],
pixels,
resolution,
buffer = 0,
percentiles = NULL,
aggregation_period = 1L,
aggregation_unit = c("day", "week", "month", "year")[1],
lastIntervalBehavior = c("SKIP", "SHORTEN", "EXTEND")[1],
as_data_frame = TRUE,
client,
token,
url = getOption("CDSE.statistical_url")
)Arguments
- aoi
sf or sfc object, typically a (multi)polygon, describing the Area of Interest.
- bbox
numeric vector of four elements describing the bounding box of interest. Specify with a coordinate pair on two (opposite) vertices of the bounding box rectangle. Coordinates need to be in longitude, latitude.
Only one of either
aoiorbboxmay be specified.- time_range
scalar or vector (Date or character that can be converted to date) defining the time interval.
- collection
character indicating which collection to search. Must be one of the collections returned by
GetCollections.- script
a length one character string containing the evaluation script or the name of the file containing the script.
- mosaicking_order
character indicating the order in which tiles are overlapped from which the output result is mosaicked. Must be one of "mostRecent", "leastRecent", or "leastCC". Partial matching is used, that is, only enough initial letters of each string element are needed to guarantee unique recognition. Default: "mostRecent"
- pixels
integer scalar or length-two vector indicating the request image width and height. Values must be integers between 1 and 2500.
- resolution
numeric scalar or length-two vector indicating the spatial resolution of the request image in horizontal and vertical direction (in meters).
Only one of the arguments
pixelsorresolutionmust be set at the same time. If the argumentpixelsorresolutionis scalar, the same value is used for horizontal and vertical direction (width and height).- buffer
numeric, width of the buffer to retrieve the image of enlarged area. Default: 0
- percentiles
numeric vector indicating which percentile values should be computed. Default: NULL, don't compute any percentiles.
- aggregation_period
the length of the aggregation period in
aggregation_unit(days by default). Default: 1- aggregation_unit
character indicating the the unit of the aggregation period, must be one of "day", "week", "month", or "year". Partial matching is used, that is, only enough initial letters of each string element are needed to guarantee unique recognition (here just the first letter is enough). Default: "day"
- lastIntervalBehavior
character indicating the behavior of the last interval if the given
time_rangeisn't divisible by the providedaggregation_period.Must be one of:SKIP- skip the last interval (default behavior)
SHORTEN- shortens the last interval so that it ends at the end of provided
time_rangeEXTEND- extends the last interval over the end of the provided time range so that all intervals are of equal duration
Partial matching is used, that is, only enough initial letters of each string element are needed to guarantee unique recognition. Default: "SKIP"
- as_data_frame
logical indicating if the result should be returned as data frame. Default: TRUE
- client
OAuth client object to use for authentication.
- token
OAuth token character string to use for authentication.
Exactly one of either
clientortokenmust be specified. It is recommended to useclient.- url
character indicating the process endpoint. Default: Copernicus Data Space Ecosystem process endpoint
Details
The values are aggregated over the period (number of aggregation_units)
given by the aggregation_period argument.
The default values provide daily statistics. The statistics are returned only for the
aggregation_units (days, weeks, months, years) when the data is
available. This can be determined by the days of the satellite overpasses, but also
by the calculations done in the evaluation script.
The scripts used for the Statistical API have some additional requirements: the evaluatePixel()
function must, in addition to other output, always also return dataMask output.
This output defines which pixels are excluded from calculations.
For more information please visit the online documentation
https://documentation.dataspace.copernicus.eu/APIs/SentinelHub/Statistical.html.
If a time_range is not divisible by an aggregation_period, the last ("not full") time
interval will be dismissed by default (SKIP option). The user can instead set the
lastIntervalBehavior to SHORTEN (shortens the last interval so that it ends at the end
of the provided time range) or EXTEND (extends the last interval over the end of the
provided time range so that all the intervals are of equal duration).
If percentiles requested are 25, 50, and 75, the columns are renamed 'q1', 'median', and 'q3'.
Examples
if (FALSE) { # \dontrun{
dsn <- system.file("extdata", "centralpark.geojson", package = "CDSE")
aoi <- sf::read_sf(dsn, as_tibble = FALSE)
script_file <- system.file("scripts", "NDVI_CLOUDS_STAT.js", package = "CDSE")
daily_stats <- GetStatistics(aoi = aoi, time_range = c("2023-07-01", "2023-07-31"),
collection = "sentinel-2-l2a", script = script_file, mosaicking_order = "leastCC",
resolution = 100, aggregation_period = 1, client = OAuthClient)
# specify week as 7 days
weekly_stats <- GetStatistics(aoi = aoi, time_range = c("2023-07-01", "2023-07-31"),
collection = "sentinel-2-l2a", script = script_file,mosaicking_order = "leastCC",
resolution = 100, aggregation_period = 7, client = OAuthClient)
# specify week as 1 week
weekly_stats_extended <- GetStatistics(aoi = aoi, time_range = c("2023-07-01", "2023-07-31"),
collection = "sentinel-2-l2a", script = script_file, mosaicking_order = "leastCC",
resolution = 100, aggregation_period = 1, aggregation_unit = "w",
lastIntervalBehavior = "EXTEND", client = OAuthClient)
} # }