sits_classify: Classify time series or data cubes

In e-sensing/sits: Satellite Image Time Series Analysis for Earth Observation Data Cubes

Classify time series or data cubes

Description

This function classifies a set of time series or data cube given a trained model prediction model created by sits_train.

SITS supports the following models: (a) support vector machines: sits_svm; (b) random forests: sits_rfor; (c) extreme gradient boosting: sits_xgboost; (d) multi-layer perceptrons: sits_mlp; (e) 1D CNN: sits_tempcnn; (f) self-attention encoders: sits_lighttae and sits_tae

Usage

sits_classify(data, ml_model, ...)

## S3 method for class 'sits'
sits_classify(
  data,
  ml_model,
  ...,
  filter_fn = NULL,
  impute_fn = impute_linear(),
  multicores = 2L,
  gpu_memory = 4,
  batch_size = 2^gpu_memory,
  progress = TRUE
)

## S3 method for class 'raster_cube'
sits_classify(
  data,
  ml_model,
  ...,
  roi = NULL,
  exclusion_mask = NULL,
  filter_fn = NULL,
  impute_fn = impute_linear(),
  start_date = NULL,
  end_date = NULL,
  memsize = 8L,
  multicores = 2L,
  gpu_memory = 4,
  batch_size = 2^gpu_memory,
  output_dir,
  version = "v1",
  verbose = FALSE,
  progress = TRUE
)

## S3 method for class 'segs_cube'
sits_classify(
  data,
  ml_model,
  ...,
  roi = NULL,
  filter_fn = NULL,
  impute_fn = impute_linear(),
  start_date = NULL,
  end_date = NULL,
  memsize = 8L,
  multicores = 2L,
  gpu_memory = 4,
  batch_size = 2^gpu_memory,
  output_dir,
  version = "v1",
  n_sam_pol = NULL,
  verbose = FALSE,
  progress = TRUE
)

## S3 method for class 'tbl_df'
sits_classify(data, ml_model, ...)

## S3 method for class 'derived_cube'
sits_classify(data, ml_model, ...)

## Default S3 method:
sits_classify(data, ml_model, ...)

Arguments

data	Data cube (tibble of class "raster_cube")
ml_model	R model trained by sits_train (closure of class "sits_model")
...	Other parameters for specific functions.
filter_fn	Smoothing filter to be applied - optional (closure containing object of class "function").
impute_fn	Imputation function to remove NA.
multicores	Number of cores to be used for classification (integer, min = 1, max = 2048).
gpu_memory	Memory available in GPU in GB (default = 4)
batch_size	Batch size for GPU classification.
progress	Logical: Show progress bar?
roi	Region of interest (either an sf object, shapefile, or a numeric vector with named XY values ("xmin", "xmax", "ymin", "ymax") or named lat/long values ("lon_min", "lat_min", "lon_max", "lat_max").
exclusion_mask	Areas to be excluded from the classification process. It can be defined as a sf object or a shapefile.
start_date	Start date for the classification (Date in YYYY-MM-DD format).
end_date	End date for the classification (Date in YYYY-MM-DD format).
memsize	Memory available for classification in GB (integer, min = 1, max = 16384).
output_dir	Valid directory for output file. (character vector of length 1).
version	Version of the output (character vector of length 1).
verbose	Logical: print information about processing time?
n_sam_pol	Number of time series per segment to be classified (integer, min = 10, max = 50).

Value

Time series with predicted labels for each point (tibble of class "sits") or a data cube with probabilities for each class (tibble of class "probs_cube").

Note

The roi parameter defines a region of interest. It can be an sf_object, a shapefile, or a bounding box vector with named XY values (xmin, xmax, ymin, ymax) or named lat/long values (lon_min, lon_max, lat_min, lat_max)

Parameter filter_fn parameter specifies a smoothing filter to be applied to each time series for reducing noise. Currently, options are Savitzky-Golay (see sits_sgolay) and Whittaker (see sits_whittaker) filters.

Parameter impute_fn defines a 1D function that will be used to interpolate NA values in each time series. Currently sits supports the impute_linear function, but users can define imputation functions which are defined externally.

Parameter memsize controls the amount of memory available for classification, while multicores defines the number of cores used for processing. We recommend using as much memory as possible.

Parameter exclusion_mask defines a region that will not be classify. The region can be defined by multiple polygons. Use an sf object or a shapefile to define it.

When using a GPU for deep learning, gpu_memory indicates the memory of the graphics card which is available for processing. The parameter batch_size defines the size of the matrix (measured in number of rows) which is sent to the GPU for classification. Users can test different values of batch_size to find out which one best fits their GPU architecture.

It is not possible to have an exact idea of the size of Deep Learning models in GPU memory, as the complexity of the model and factors such as CUDA Context increase the size of the model in memory. Therefore, we recommend that you leave at least 1GB free on the video card to store the Deep Learning model that will be used.

For users of Apple M3 chips or similar with a Neural Engine, be aware that these chips share memory between the GPU and the CPU. Tests indicate that the memsize should be set to half to the total memory and the batch_size parameter should be a small number (we suggest the value of 64). Be aware that increasing these parameters may lead to memory conflicts.

For classifying vector data cubes created by sits_segment, n_sam_pol controls is the number of time series to be classified per segment.

Please refer to the sits documentation available in <https://e-sensing.github.io/sitsbook/> for detailed examples.

Author(s)

Rolf Simoes, [e-mail]

Gilberto Camara, [e-mail]

Examples

if (sits_run_examples()) {
    # Example of classification of a time series
    # Retrieve the samples for Mato Grosso
    # train a random forest model
    rf_model <- sits_train(samples_modis_ndvi, ml_method = sits_rfor)

    # classify the point
    point_ndvi <- sits_select(point_mt_6bands, bands = c("NDVI"))
    point_class <- sits_classify(
        data = point_ndvi, ml_model = rf_model
    )
    plot(point_class)

    # Example of classification of a data cube
    # 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
    )
    # classify a data cube
    probs_cube <- sits_classify(
        data = cube,
        ml_model = rf_model,
        output_dir = tempdir(),
        version = "ex_classify"
    )
    # label the probability cube
    label_cube <- sits_label_classification(
        probs_cube,
        output_dir = tempdir(),
        version = "ex_classify"
    )
    # plot the classified image
    plot(label_cube)
    # segmentation
    # segment the image
    segments <- sits_segment(
        cube = cube,
        seg_fn = sits_slic(step = 5,
                       compactness = 1,
                       dist_fun = "euclidean",
                       avg_fun = "median",
                       iter = 50,
                       minarea = 10,
                       verbose = FALSE
                       ),
        output_dir = tempdir()
    )
    # Create a classified vector cube
    probs_segs <- sits_classify(
        data = segments,
        ml_model = rf_model,
        output_dir = tempdir(),
        multicores = 4,
        version = "segs"
    )
    # Create a labelled vector cube
    class_segs <- sits_label_classification(
        cube = probs_segs,
        output_dir = tempdir(),
        multicores = 2,
        memsize = 4,
        version = "segs_classify"
    )
    # plot class_segs
    plot(class_segs)
}

e-sensing/sits documentation built on Feb. 13, 2025, 2:22 a.m.