sits_apply {sits} | R Documentation |
Apply a function on a set of time series
Description
Apply a named expression to a sits cube or a sits tibble
to be evaluated and generate new bands (indices). In the case of sits
cubes, it creates a new band in output_dir
.
Usage
sits_apply(data, ...)
## S3 method for class 'sits'
sits_apply(data, ...)
## S3 method for class 'raster_cube'
sits_apply(
data,
...,
window_size = 3L,
memsize = 4L,
multicores = 2L,
normalized = TRUE,
output_dir,
progress = TRUE
)
## S3 method for class 'derived_cube'
sits_apply(data, ...)
## Default S3 method:
sits_apply(data, ...)
Arguments
data |
Valid sits tibble or cube |
... |
Named expressions to be evaluated (see details). |
window_size |
An odd number representing the size of the sliding window of sits kernel functions used in expressions (for a list of supported kernel functions, please see details). |
memsize |
Memory available for classification (in GB). |
multicores |
Number of cores to be used for classification. |
normalized |
Does the expression produces a normalized band? |
output_dir |
Directory where files will be saved. |
progress |
Show progress bar? |
Value
A sits tibble or a sits cube with new bands, produced according to the requested expression.
Kernel functions available
w_median()
: returns the median of the neighborhood's values.w_sum()
: returns the sum of the neighborhood's values.w_mean()
: returns the mean of the neighborhood's values.w_sd()
: returns the standard deviation of the neighborhood's values.w_min()
: returns the minimum of the neighborhood's values.w_max()
: returns the maximum of the neighborhood's values.w_var()
: returns the variance of the neighborhood's values.w_modal()
: returns the modal of the neighborhood's values.
Note
The main sits
classification workflow has the following steps:
sits_cube
: selects a ARD image collection from a cloud provider.sits_cube_copy
: copies an ARD image collection from a cloud provider to a local directory for faster processing.sits_regularize
: create a regular data cube from an ARD image collection.sits_apply
: create new indices by combining bands of a regular data cube (optional).sits_get_data
: extract time series from a regular data cube based on user-provided labelled samples.sits_train
: train a machine learning model based on image time series.sits_classify
: classify a data cube using a machine learning model and obtain a probability cube.sits_smooth
: post-process a probability cube using a spatial smoother to remove outliers and increase spatial consistency.sits_label_classification
: produce a classified map by selecting the label with the highest probability from a smoothed cube.
sits_apply()
allows any valid R expression to compute new bands.
Use R syntax to pass an expression to this function.
Besides arithmetic operators, you can use virtually any R function
that can be applied to elements of a matrix (functions that are
unaware of matrix sizes, e.g. sqrt()
, sin()
,
log()
).
Examples of valid expressions:
-
NDVI = (B08 - B04/(B08 + B04))
for Sentinel-2 images. -
EVI = 2.5 * (B05 – B04) / (B05 + 6 * B04 – 7.5 * B02 + 1)
for Landsat-8/9 images. -
VV_VH_RATIO = VH/VV
for Sentinel-1 images. In this case, set thenormalized
parameter to FALSE. -
VV_DB = 10 * log10(VV)
to convert Sentinel-1 RTC images available in Planetary Computer to decibels. Also, set thenormalized
parameter to FALSE.
sits_apply()
accepts a predefined set of kernel functions
(see below) that can be applied to pixels considering its
neighborhood. sits_apply()
considers a neighborhood of a
pixel as a set of pixels equidistant to it (including itself).
This neighborhood forms a square window (also known as kernel)
around the central pixel
(Moore neighborhood). Users can set the window_size
parameter to adjust the size of the kernel window.
The image is conceptually mirrored at the edges so that neighborhood
including a pixel outside the image is equivalent to take the
'mirrored' pixel inside the edge.
sits_apply()
applies a function to the kernel and its result
is assigned to a corresponding central pixel on a new matrix.
The kernel slides throughout the input image and this process
generates an entire new matrix, which is returned as a new band
to the cube. The kernel functions ignores any NA
values
inside the kernel window. If all pixels in the window are NA
the result will be NA
.
By default, the indexes generated by sits_apply()
function are
normalized between -1 and 1, scaled by a factor of 0.0001.
Normalized indexes are saved as INT2S (Integer with sign).
If the normalized
parameter is FALSE, no scaling factor will be
applied and the index will be saved as FLT4S (signed float) and
the values will vary between -3.4e+38 and 3.4e+38.
Author(s)
Rolf Simoes, rolfsimoes@gmail.com
Felipe Carvalho, felipe.carvalho@inpe.br
Gilberto Camara, gilberto.camara@inpe.br
Examples
if (sits_run_examples()) {
# get a time series
# Apply a normalization function
point2 <-
sits_select(point_mt_6bands, "NDVI") |>
sits_apply(NDVI_norm = (NDVI - min(NDVI)) / (max(NDVI) - min(NDVI)))
# Example of generation texture band with variance
# Create a data cube from local files
data_dir <- system.file("extdata/raster/mod13q1", package = "sits")
cube <- sits_cube(
source = "BDC",
collection = "MOD13Q1-6.1",
data_dir = data_dir
)
# Generate a texture images with variance in NDVI images
cube_texture <- sits_apply(
data = cube,
NDVITEXTURE = w_median(NDVI),
window_size = 5,
output_dir = tempdir()
)
}