Apply a function on a set of time series

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.

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 the normalized parameter to FALSE.
VV_DB = 10 * log10(VV) to convert Sentinel-1 RTC images available in Planetary Computer to decibels. Also, set the normalized parameter to FALSE.

sits_apply() also accepts a predefined set of kernel functions (see below) that can be applied to pixels considering its neighborhood. The function 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.

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.

Author

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()
    )
}