sits_classify: Classify time series or data cubes

In 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) 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,
  multicores = 2L,
  gpu_memory = 16,
  progress = TRUE
)

## S3 method for class 'raster_cube'
sits_classify(
  data,
  ml_model,
  ...,
  roi = NULL,
  filter_fn = NULL,
  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,
  ...,
  filter_fn = NULL,
  start_date = NULL,
  end_date = NULL,
  memsize = 8L,
  multicores = 2L,
  gpu_memory = 16,
  output_dir,
  version = "v1",
  n_sam_pol = 40,
  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?
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.

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(),
        n_sam_pol = 20,
        multicores = 4,
        version = "segs_classify"
    )
    # 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)
}

sits documentation built on Nov. 2, 2023, 5:59 p.m.