sits_classify {sits}

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) deep residual networks: sits_resnet; (g) self-attention encoders: sits_lighttae.

Usage

sits_classify(
  data,
  ml_model,
  ...,
  filter_fn = NULL,
  multicores = 2L,
  progress = TRUE
)

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

## S3 method for class 'raster_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 = 16,
  output_dir,
  version = "v1",
  verbose = FALSE,
  progress = TRUE
)

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

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

## 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 = 16,
  output_dir,
  version = "v1",
  n_sam_pol = NULL,
  verbose = FALSE,
  progress = TRUE
)

## 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 (clousure containing object of class "function").

multicores

Number of cores to be used for classification (integer, min = 1, max = 2048).

progress

Logical: Show progress bar?

impute_fn

Imputation function to remove NA.

gpu_memory

Memory available in GPU in GB (default = 16)

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").

start_date

Start date for the classification (Date in YYYY-MM-DD format).

end_date

End date for the classification (Date im 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 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.

When using a GPU for deep learning, gpu_memory indicates the memory of available in the graphics card. 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 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",
        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)
}