sits_uncertainty: Estimate classification uncertainty based on probs cube

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

Estimate classification uncertainty based on probs cube

Description

Calculate the uncertainty cube based on the probabilities produced by the classifier. Takes a probability cube as input and produces a uncertainty cube.

Usage

sits_uncertainty(cube, ...)

## S3 method for class 'probs_cube'
sits_uncertainty(
  cube,
  ...,
  type = "entropy",
  multicores = 2L,
  memsize = 4L,
  output_dir,
  version = "v1",
  progress = TRUE
)

## S3 method for class 'probs_vector_cube'
sits_uncertainty(
  cube,
  ...,
  type = "entropy",
  multicores = 2L,
  memsize = 4L,
  output_dir,
  version = "v1"
)

## S3 method for class 'raster_cube'
sits_uncertainty(cube, ...)

## Default S3 method:
sits_uncertainty(cube, ...)

Arguments

cube	Probability data cube.
...	Other parameters for specific functions.
type	Method to measure uncertainty. See details.
multicores	Number of cores to run the function.
memsize	Maximum overall memory (in GB) to run the function.
output_dir	Output directory for image files.
version	Version of resulting image (in the case of multiple tests).
progress	Check progress bar?

Value

An uncertainty data cube

Note

The output of sits_classify and sits_smooth is a probability cube containing the class probability for all pixels, which are generated by the machine learning model. The sits_uncertainty function takes a probability cube and produces a uncertainty code which contains a measure of uncertainty for each pixel, based on the class probabilities.

The uncertainty measure is relevant in the context of active leaning, and helps to increase the quantity and quality of training samples by providing information about the confidence of the model.

The supported types of uncertainty are:

1. entropy: the difference between all predictions expressed a Shannon measure of entropy.

2. least: the difference between 1.0 and most confident prediction.

3. margin: the difference between the two most confident predictions.

Author(s)

Gilberto Camara, [e-mail]

Rolf Simoes, [e-mail]

Alber Sanchez, [e-mail]

References

Monarch, Robert Munro. Human-in-the-Loop Machine Learning: Active learning and annotation for human-centered AI. Simon and Schuster, 2021.

Examples

if (sits_run_examples()) {
    # create a random forest model
    rfor_model <- sits_train(samples_modis_ndvi, sits_rfor())
    # 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 = rfor_model, output_dir = tempdir()
    )
    # calculate uncertainty
    uncert_cube <- sits_uncertainty(probs_cube, output_dir = tempdir())
    # plot the resulting uncertainty cube
    plot(uncert_cube)
}

sits documentation built on Sept. 9, 2025, 5:54 p.m.