sits_apply: Apply a function on a set of time series

In sits: Satellite Image Time Series Analysis for Earth Observation Data Cubes

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 materializes a new band in output_dir using gdalcubes.

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 = FALSE
)

## 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	Produce normalized band?
output_dir	Directory where files will be saved.
progress	Show progress bar?

Details

sits_apply() allow 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()).

Also, 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) according the Chebyshev distance. This neighborhood form 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. Central pixel is NA just only all pixels in the window are NA.

By default, the indexes generated by the 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 (Float with sign).

Value

A sits tibble or a sits cube with new bands, produced according to the requested expression.

Summarizing kernel functions

• 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(s)

Rolf Simoes, [e-mail]

Felipe Carvalho, [e-mail]

Gilberto Camara, [e-mail]

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

sits documentation built on May 29, 2024, 5:55 a.m.