Package 'sits'

Description

Satellite Image Time Series Analysis for Earth Observation Data Cubes

Purpose

The SITS package provides a set of tools for analysis, visualization and classification of satellite image time series. It includes methods for filtering, clustering, classification, and post-processing.

Author(s)

Maintainer: Gilberto Camara [email protected] [thesis advisor]

Authors:

• Rolf Simoes [email protected]

• Felipe Souza [email protected]

• Felipe Carlos [email protected]

Other contributors:

• Lorena Santos [email protected] [contributor]

• Karine Ferreira [email protected] [contributor, thesis advisor]

• Charlotte Pelletier [email protected] [contributor]

• Pedro Andrade [email protected] [contributor]

• Alber Sanchez [email protected] [contributor]

• Gilberto Queiroz [email protected] [contributor]

See Also

Useful links:

• https://github.com/e-sensing/sits/

• https://e-sensing.github.io/sitsbook/

• Report bugs at https://github.com/e-sensing/sits/issues

Description

Given a sits tibble with a set of labels, renames the labels to the specified in value.

Usage

sits_labels(data) <- value

## S3 replacement method for class 'sits'
sits_labels(data) <- value

## S3 replacement method for class 'probs_cube'
sits_labels(data) <- value

## S3 replacement method for class 'class_cube'
sits_labels(data) <- value

## Default S3 replacement method:
sits_labels(data) <- value

Arguments

Value

A sits tibble or data cube with modified labels.

A probs or class_cube cube with modified labels.

Author(s)

Rolf Simoes, [email protected]

Examples

# show original samples ("Cerrado" and "Pasture")
sits_labels(cerrado_2classes)
# rename label samples to "Savanna" and "Grasslands"
sits_labels(cerrado_2classes) <- c("Savanna", "Grasslands")
# see the change
sits_labels(cerrado_2classes)

Description

A dataset containing a tibble with time series samples for the Cerrado and Pasture areas of the Mato Grosso state. The time series come from MOD13Q1 collection 5 images.

Usage

data(cerrado_2classes)

Format

A tibble with 736 rows and 7 variables: longitude: East-west coordinate of the time series sample (WGS 84), latitude (North-south coordinate of the time series sample in WGS 84), start_date (initial date of the time series), end_date (final date of the time series), label (the class label associated to the sample), cube (the name of the cube associated with the data), time_series (list containing a tibble with the values of the time series).

Description

This is a generic function. Parameters depend on the specific type of input.

Usage

## S3 method for class 'probs_cube'
hist(x, ..., tile = x[["tile"]][[1]], label = NULL, size = 1e+05)

Arguments

Value

A histogram of one label of a probability cube.

Author(s)

Gilberto Camara, [email protected]

Examples

if (sits_run_examples()) {
    # create a data cube from local files
    data_dir <- system.file("extdata/raster/mod13q1", package = "sits")
    modis_cube <- sits_cube(
        source = "BDC",
        collection = "MOD13Q1-6.1",
        data_dir = data_dir
    )
    rfor_model <- sits_train(samples_modis_ndvi, sits_rfor())
    probs_cube <- sits_classify(
        data = modis_cube,
        ml_model = rfor_model,
        output_dir = tempdir()
    )
    hist(probs_cube, label = "Forest")
}

Description

This is a generic function. Parameters depend on the specific type of input.

Usage

## S3 method for class 'raster_cube'
hist(x, ..., tile = x[["tile"]][[1]], date = NULL, band = NULL, size = 10000)

Arguments

Value

A histogram of one band of data cube.

Author(s)

Gilberto Camara, [email protected]

Examples

if (sits_run_examples()) {
    # 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
    )
    hist(cube)
}

Description

This is a generic function. Parameters depend on the specific type of input.

Usage

## S3 method for class 'sits'
hist(x, ...)

Arguments

Value

A summary of the sits tibble.

Author(s)

Gilberto Camara, [email protected]

Examples

if (sits_run_examples()) {
    hist(samples_modis_ndvi)
}

Description

This is a generic function. Parameters depend on the specific type of input.

Usage

## S3 method for class 'uncertainty_cube'
hist(x, ..., tile = x[["tile"]][[1]], size = 1e+05)

Arguments

Value

A histogram of a uncertainty cube

Author(s)

Gilberto Camara, [email protected]

Examples

if (sits_run_examples()) {
    # 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
    )
    # create a random forest model
    rfor_model <- sits_train(samples_modis_ndvi, sits_rfor())
    # classify a data cube
    probs_cube <- sits_classify(
        data = cube, ml_model = rfor_model, output_dir = tempdir()
    )
    uncert_cube <- sits_uncertainty(
        cube = probs_cube,
        output_dir = tempdir()
    )
    hist(uncert_cube)
}

Description

Remove NA by linear interpolation

Remove NA by linear interpolation

Usage

impute_linear(data = NULL)

impute_linear(data = NULL)

Arguments

Value

A set of filtered time series using the imputation function.

A set of filtered time series using the imputation function.

Author(s)

Gilberto Camara, [email protected]

Description

This is a generic function. Parameters depend on the specific type of input. See each function description for the required parameters.

• sits tibble: see plot.sits

• patterns: see plot.patterns

• classified time series: see plot.predicted

• raster cube: see plot.raster_cube

• SAR cube: see plot.sar_cube

• DEM cube: see plot.dem_cube

• vector cube: see plot.vector_cube

• classification probabilities: see plot.probs_cube

• classification uncertainty: see plot.uncertainty_cube

• uncertainty of vector cubes: see plot.uncertainty_vector_cube

• classified cube: see plot.class_cube

• classified vector cube: see plot.class_vector_cube

• dendrogram cluster: see plot.sits_cluster

• SOM map: see plot.som_map

• SOM evaluate cluster: see plot.som_evaluate_cluster

• geo-distances: see plot.geo_distances

• random forest model: see plot.rfor_model

• xgboost model: see plot.xgb_model

• torch ML model: see plot.torch_model

Usage

## S3 method for class 'sits'
plot(x, y, ..., together = FALSE)

Arguments

Value

A series of plot objects produced by ggplot2 showing all time series associated to each combination of band and label, and including the median, and first and third quartile ranges.

Author(s)

Gilberto Camara, [email protected]

Examples

if (sits_run_examples()) {
    # plot sets of time series
    plot(cerrado_2classes)
}

Description

plots a classified raster using ggplot.

Usage

## S3 method for class 'class_cube'
plot(
  x,
  y,
  ...,
  tile = x[["tile"]][[1]],
  title = "Classified Image",
  legend = NULL,
  palette = "Spectral",
  scale = 1,
  max_cog_size = 1024
)

Arguments

Value

A color map, where each pixel has the color associated to a label, as defined by the legend parameter.

Note

The following optional parameters are available to allow for detailed control over the plot output:

• first_quantile: 1st quantile for stretching images (default = 0.05)

• last_quantile: last quantile for stretching images (default = 0.95)

• graticules_labels_size: size of coordinates labels (default = 0.8)

• legend_title_size: relative size of legend title (default = 1.0)

• legend_text_size: relative size of legend text (default = 1.0)

• legend_bg_color: color of legend background (default = "white")

• legend_bg_alpha: legend opacity (default = 0.5)

Author(s)

Gilberto Camara, [email protected]

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()
    )
    # label cube with the most likely class
    label_cube <- sits_label_classification(
        probs_cube,
        output_dir = tempdir()
    )
    # plot the resulting classified image
    plot(label_cube)
}

Description

Plot vector classified cube

Usage

## S3 method for class 'class_vector_cube'
plot(
  x,
  ...,
  tile = x[["tile"]][[1]],
  legend = NULL,
  seg_color = "black",
  line_width = 0.5,
  palette = "Spectral",
  scale = 1
)

Arguments

Value

A plot object with an RGB image or a B/W image on a color scale using the chosen palette

Note

To see which color palettes are supported, please run

Author(s)

Gilberto Camara, [email protected]

Examples

if (sits_run_examples()) {
    data_dir <- system.file("extdata/raster/mod13q1", package = "sits")
    cube <- sits_cube(
        source = "BDC",
        collection = "MOD13Q1-6.1",
        data_dir = data_dir
    )
    # segment the image
    segments <- sits_segment(
        cube = cube,
        output_dir = tempdir()
    )
    # create a classification model
    rfor_model <- sits_train(samples_modis_ndvi, sits_rfor())
    # classify the segments
    probs_segs <- sits_classify(
        data = segments,
        ml_model = rfor_model,
        output_dir = tempdir()
    )
    #
    # Create a classified vector cube
    class_segs <- sits_label_classification(
        cube = probs_segs,
        output_dir = tempdir(),
        multicores = 2,
        memsize = 4
    )
    # plot the segments
    plot(class_segs)
}

Description

Plot RGB raster cube

Usage

## S3 method for class 'dem_cube'
plot(
  x,
  ...,
  band = "ELEVATION",
  tile = x[["tile"]][[1]],
  palette = "Spectral",
  rev = TRUE,
  scale = 1,
  max_cog_size = 1024
)

Arguments

Value

A plot object with a DEM cube or a B/W image on a color scale

Note

Use scale parameter for general output control.

The following optional parameters are available to allow for detailed control over the plot output:

• graticules_labels_size: size of coordinates labels (default = 0.7)

• legend_title_size: relative size of legend title (default = 0.7)

• legend_text_size: relative size of legend text (default = 0.7)

• legend_bg_color: color of legend background (default = "white")

• legend_bg_alpha: legend opacity (default = 0.3)

Author(s)

Gilberto Camara, [email protected]

Examples

if (sits_run_examples()) {
# obtain the DEM cube
    dem_cube_19HBA <- sits_cube(
        source = "MPC",
        collection = "COP-DEM-GLO-30",
        bands = "ELEVATION",
        tiles = "19HBA"
        )
# plot the DEM reversing the palette
    plot(dem_cube_19HBA, band = "ELEVATION")
}

Description

Make a kernel density plot of samples distances.

Usage

## S3 method for class 'geo_distances'
plot(x, y, ...)

Arguments

Value

A plot showing the sample-to-sample distances and sample-to-prediction distances.

Note

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

Author(s)

Felipe Souza, [email protected]

Rolf Simoes, [email protected]

Alber Sanchez, [email protected]

References

Hanna Meyer and Edzer Pebesma, "Machine learning-based global maps of ecological variables and the challenge of assessing them" Nature Communications, 13,2022. DOI: 10.1038/s41467-022-29838-9.

Examples

if (sits_run_examples()) {
    # read a shapefile for the state of Mato Grosso, Brazil
    mt_shp <- system.file("extdata/shapefiles/mato_grosso/mt.shp",
        package = "sits"
    )
    # convert to an sf object
    mt_sf <- sf::read_sf(mt_shp)
    # calculate sample-to-sample and sample-to-prediction distances
    distances <- sits_geo_dist(samples_modis_ndvi, mt_sf)
    # plot sample-to-sample and sample-to-prediction distances
    plot(distances)
}

Description

Plots the patterns to be used for classification

Given a sits tibble with a set of patterns, plot them.

Usage

## S3 method for class 'patterns'
plot(x, y, ..., bands = NULL, year_grid = FALSE)

Arguments

Value

A plot object produced by ggplot2 with one average pattern per label.

Note

This code is reused from the dtwSat package by Victor Maus.

Author(s)

Gilberto Camara, [email protected]

Victor Maus, [email protected]

Examples

if (sits_run_examples()) {
    # plot patterns
    plot(sits_patterns(cerrado_2classes))
}

Description

Given a sits tibble with a set of predictions, plot them

Usage

## S3 method for class 'predicted'
plot(x, y, ..., bands = "NDVI", palette = "Harmonic")

Arguments

Value

A plot object produced by ggplot2 showing the time series and its label.

Note

This code is reused from the dtwSat package by Victor Maus.

Author(s)

Victor Maus, [email protected]

Gilberto Camara, [email protected]

Examples

if (sits_run_examples()) {
    # Retrieve the samples for Mato Grosso
    # train an svm model
    ml_model <- sits_train(samples_modis_ndvi, ml_method = sits_svm)
    # classify the point
    point_ndvi <- sits_select(point_mt_6bands, bands = "NDVI")
    point_class <- sits_classify(
        data = point_ndvi, ml_model = ml_model
    )
    plot(point_class)
}

Description

plots a probability cube using stars

Usage

## S3 method for class 'probs_cube'
plot(
  x,
  ...,
  tile = x[["tile"]][[1]],
  labels = NULL,
  palette = "YlGn",
  rev = FALSE,
  scale = 1,
  max_cog_size = 512
)

Arguments

Value

A plot containing probabilities associated to each class for each pixel.

Author(s)

Gilberto Camara, [email protected]

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()
    )
    # plot the resulting probability cube
    plot(probs_cube)
}

Description

plots a probability cube using stars

Usage

## S3 method for class 'probs_vector_cube'
plot(
  x,
  ...,
  tile = x[["tile"]][[1]],
  labels = NULL,
  palette = "YlGn",
  rev = FALSE,
  scale = 1
)

Arguments

Value

A plot containing probabilities associated to each class for each pixel.

Author(s)

Gilberto Camara, [email protected]

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
    )
    # segment the image
    segments <- sits_segment(
        cube = cube,
        seg_fn = sits_slic(step = 5,
                           compactness = 1,
                           dist_fun = "euclidean",
                           avg_fun = "median",
                           iter = 20,
                           minarea = 10,
                           verbose = FALSE),
        output_dir = tempdir()
    )
    # classify a data cube
    probs_vector_cube <- sits_classify(
        data = segments,
        ml_model = rfor_model,
        output_dir = tempdir()
    )
    # plot the resulting probability cube
    plot(probs_vector_cube, labels = "Forest")
}

Description

Plot RGB raster cube

Usage

## S3 method for class 'raster_cube'
plot(
  x,
  ...,
  band = NULL,
  red = NULL,
  green = NULL,
  blue = NULL,
  tile = x[["tile"]][[1]],
  dates = NULL,
  palette = "RdYlGn",
  rev = FALSE,
  scale = 1,
  first_quantile = 0.02,
  last_quantile = 0.98,
  max_cog_size = 1024
)

Arguments

Value

A plot object with an RGB image or a B/W image on a color scale

Note

Use scale parameter for general output control. The dates parameter indicates the date allows plotting of different dates when a single band and three dates are provided, 'sits' will plot a multi-temporal RGB image for a single band (useful in the case of SAR data). For RGB bands with multi-dates, multiple plots will be produced.

The following optional parameters are available to allow for detailed control over the plot output:

• graticules_labels_size: size of coordinates labels (default = 0.7)

• legend_title_size: relative size of legend title (default = 0.7)

• legend_text_size: relative size of legend text (default = 0.7)

• legend_bg_color: color of legend background (default = "white")

• legend_bg_alpha: legend opacity (default = 0.3)

Author(s)

Gilberto Camara, [email protected]

Examples

if (sits_run_examples()) {
    # 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
    )
    # plot NDVI band of the second date date of the data cube
    plot(cube, band = "NDVI", dates = sits_timeline(cube)[1])
}

Description

Plots the important variables in a random forest model.

Usage

## S3 method for class 'rfor_model'
plot(x, y, ...)

Arguments

Value

A random forest object.

Note

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

Author(s)

Gilberto Camara, [email protected]

Examples

if (sits_run_examples()) {
    # Retrieve the samples for Mato Grosso
    # train a random forest model
    rf_model <- sits_train(samples_modis_ndvi, ml_method = sits_rfor())
    # plot the model
    plot(rf_model)
}

Description

Plot RGB raster cube

Usage

## S3 method for class 'sar_cube'
plot(
  x,
  ...,
  band = NULL,
  red = NULL,
  green = NULL,
  blue = NULL,
  tile = x[["tile"]][[1]],
  dates = NULL,
  palette = "Greys",
  rev = FALSE,
  scale = 1,
  first_quantile = 0.05,
  last_quantile = 0.95,
  max_cog_size = 1024
)

Arguments

Value

A plot object with an RGB image or a B/W image on a color scale for SAR cubes

Note

Use scale parameter for general output control. The dates parameter indicates the date allows plotting of different dates when a single band and three dates are provided, 'sits' will plot a multi-temporal RGB image for a single band (useful in the case of SAR data). For RGB bands with multi-dates, multiple plots will be produced.

The following optional parameters are available to allow for detailed control over the plot output:

• graticules_labels_size: size of coordinates labels (default = 0.7)

• legend_title_size: relative size of legend title (default = 0.7)

• legend_text_size: relative size of legend text (default = 0.7)

• legend_bg_color: color of legend background (default = "white")

• legend_bg_alpha: legend opacity (default = 0.3)

Author(s)

Gilberto Camara, [email protected]

Examples

if (sits_run_examples()) {
    # create a SAR data cube from cloud services
    cube_s1_grd <-  sits_cube(
        source = "MPC",
        collection = "SENTINEL-1-GRD",
        bands = c("VV", "VH"),
        orbit = "descending",
        tiles = c("21LUJ"),
        start_date = "2021-08-01",
        end_date = "2021-09-30"
    )
    # plot VH band of the first date of the data cube
    plot(cube_s1_grd, band = "VH")
}

Description

Plot a bar graph with informations about the confusion matrix

Usage

## S3 method for class 'sits_accuracy'
plot(x, y, ..., title = "Confusion matrix")

Arguments

Value

A plot object produced by the ggplot2 package containing color bars showing the confusion between classes.

Note

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

Author(s)

Gilberto Camara [email protected]

Examples

if (sits_run_examples()) {
    # show accuracy for a set of samples
    train_data <- sits_sample(samples_modis_ndvi, frac = 0.5)
    test_data  <- sits_sample(samples_modis_ndvi, frac = 0.5)
    # compute a random forest model
    rfor_model <- sits_train(train_data, sits_rfor())
    # classify training points
    points_class <- sits_classify(
        data = test_data, ml_model = rfor_model
    )
    # calculate accuracy
    acc <- sits_accuracy(points_class)
    # plot accuracy
    plot(acc)
}

Description

Plot a dendrogram

Usage

## S3 method for class 'sits_cluster'
plot(x, ..., cluster, cutree_height, palette)

Arguments

Value

The dendrogram object.

Author(s)

Rolf Simoes, [email protected]

Examples

if (sits_run_examples()) {
     samples <- sits_cluster_dendro(cerrado_2classes,
                bands = c("NDVI", "EVI"))
}

Description

Plot a bar graph with informations about each cluster. The percentage of mixture between the clusters.

Usage

## S3 method for class 'som_evaluate_cluster'
plot(x, y, ..., name_cluster = NULL, title = "Confusion by cluster")

Arguments

Value

A plot object produced by the ggplot2 package containing color bars showing the confusion between classes.

Note

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

Author(s)

Lorena Santos [email protected]

Examples

if (sits_run_examples()) {
    # create a SOM map
    som_map <- sits_som_map(samples_modis_ndvi)
    # evaluate the SOM cluster
    som_clusters <- sits_som_evaluate_cluster(som_map)
    # plot the SOM cluster evaluation
    plot(som_clusters)
}

Description

plots a SOM map generated by "sits_som_map". The plot function produces different plots based on the input data. If type is "codes", plots the vector weight for in each neuron. If type is "mapping", shows where samples are mapped.

Usage

## S3 method for class 'som_map'
plot(x, y, ..., type = "codes", band = 1)

Arguments

Value

Called for side effects.

Note

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

Author(s)

Gilberto Camara, [email protected]

Examples

if (sits_run_examples()) {
    # create a SOM map
    som_map <- sits_som_map(samples_modis_ndvi)
    # plot the SOM map
    plot(som_map)
}

Description

Plots a deep learning model developed using torch.

Usage

## S3 method for class 'torch_model'
plot(x, y, ...)

Arguments

Value

A plot object produced by the ggplot2 package showing the evolution of the loss and accuracy of the model.

Note

This code has been lifted from the "keras" package.

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

Author(s)

Felipe Souza, [email protected]

Rolf Simoes, [email protected]

Alber Sanchez, [email protected]

Examples

if (sits_run_examples()) {
    # Retrieve the samples for Mato Grosso
    # train a tempCNN model
    ml_model <- sits_train(samples_modis_ndvi, ml_method = sits_tempcnn)
    # plot the model
    plot(ml_model)
}

Description

plots a probability cube using stars

Usage

## S3 method for class 'uncertainty_cube'
plot(
  x,
  ...,
  tile = x[["tile"]][[1]],
  palette = "RdYlGn",
  rev = TRUE,
  scale = 1,
  first_quantile = 0.02,
  last_quantile = 0.98,
  max_cog_size = 1024
)

Arguments

Value

A plot object produced by the stars package with a map showing the uncertainty associated to each classified pixel.

Note

The following optional parameters are available to allow for detailed control over the plot output:

• graticules_labels_size: size of coordinates labels (default = 0.7)

• legend_title_size: relative size of legend title (default = 1.0)

• legend_text_size: relative size of legend text (default = 1.0)

• legend_bg_color: color of legend background (default = "white")

• legend_bg_alpha: legend opacity (default = 0.5)

Author(s)

Gilberto Camara, [email protected]

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)
}

Description

plots a probability cube using stars

Usage

## S3 method for class 'uncertainty_vector_cube'
plot(
  x,
  ...,
  tile = x[["tile"]][[1]],
  palette = "RdYlGn",
  rev = TRUE,
  scale = 1
)

Arguments

Value

A plot containing probabilities associated to each class for each pixel.

Author(s)

Gilberto Camara, [email protected]

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
    )
    # segment the image
    segments <- sits_segment(
        cube = cube,
        seg_fn = sits_slic(step = 5,
                           compactness = 1,
                           dist_fun = "euclidean",
                           avg_fun = "median",
                           iter = 20,
                           minarea = 10,
                           verbose = FALSE),
        output_dir = tempdir()
    )
    # classify a data cube
    probs_vector_cube <- sits_classify(
        data = segments,
        ml_model = rfor_model,
        output_dir = tempdir()
    )
    # measure uncertainty
    uncert_vector_cube <- sits_uncertainty(
        cube = probs_vector_cube,
        type = "margin",
        output_dir = tempdir()
    )
    # plot the resulting uncertainty cube
    plot(uncert_vector_cube)
}

Description

plots a probability cube using stars

Usage

## S3 method for class 'variance_cube'
plot(
  x,
  ...,
  tile = x[["tile"]][[1]],
  labels = NULL,
  palette = "YlGnBu",
  rev = FALSE,
  type = "map",
  scale = 1,
  max_cog_size = 1024
)

Arguments

Value

A plot containing probabilities associated to each class for each pixel.

Author(s)

Gilberto Camara, [email protected]

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()
    )
    # obtain a variance cube
    var_cube <- sits_variance(probs_cube, output_dir = tempdir())
    # plot the variance cube
    plot(var_cube)
}

Description

Plot RGB raster cube

Usage

## S3 method for class 'vector_cube'
plot(
  x,
  ...,
  band = NULL,
  red = NULL,
  green = NULL,
  blue = NULL,
  tile = x[["tile"]][[1]],
  dates = NULL,
  seg_color = "yellow",
  line_width = 0.3,
  palette = "RdYlGn",
  rev = FALSE,
  scale = 1,
  first_quantile = 0.02,
  last_quantile = 0.98,
  max_cog_size = 1024
)

Arguments

Value

A plot object with an RGB image or a B/W image on a color scale using the palette

Note

The following optional parameters are available to allow for detailed control over the plot output:

• graticules_labels_size: size of coordinates labels (default = 0.7)

• legend_title_size: relative size of legend title (default = 0.7)

• legend_text_size: relative size of legend text (default = 0.7)

• legend_bg_color: color of legend background (default = "white")

• legend_bg_alpha: legend opacity (default = 0.3)

Author(s)

Gilberto Camara, [email protected]

Examples

if (sits_run_examples()) {
    # 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
    )
    # Segment the cube
    segments <- sits_segment(
        cube = cube,
        output_dir = tempdir(),
        multicores = 2,
        memsize = 4
    )
    # plot NDVI band of the second date date of the data cube
    plot(segments, band = "NDVI", date = sits_timeline(cube)[1])
}

Description

Plots trees in an extreme gradient boosting model.

Usage

## S3 method for class 'xgb_model'
plot(x, ..., trees = 0:4, width = 1500, height = 1900)

Arguments

Value

A plot

Note

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

Author(s)

Gilberto Camara, [email protected]

Examples

if (sits_run_examples()) {
    # Retrieve the samples for Mato Grosso
    # train an extreme gradient boosting
    xgb_model <- sits_train(samples_modis_ndvi,
        ml_method = sits_xgboost()
    )
    plot(xgb_model)
}

Description

A dataset containing a tibble with one time series samples in the Mato Grosso state of Brazil. The time series comes from MOD13Q1 collection 6 images.

Usage

data(point_mt_6bands)

Format

A tibble with 1 rows and 7 variables: longitude: East-west coordinate of the time series sample (WGS 84), latitude (North-south coordinate of the time series sample in WGS 84), start_date (initial date of the time series), end_date (final date of the time series), label (the class label associated to the sample), cube (the name of the cube associated with the data), time_series (list containing a tibble with the values of the time series).

Description

A sits tibble with time series samples from Brazilian Amazonia rain forest.

The labels are: "Deforestation", "Forest", "NatNonForest" and "Pasture".

The time series were extracted from the Landsat-8 BDC data cube (collection = "LC8_30_16D_STK-1", tiles = "038047"). These time series comprehends a period of 12 months (25 observations) from "2018-07-12" to "2019-07-28". The extracted bands are NDVI and EVI. Cloudy values were removed and interpolated.

Usage

data("samples_l8_rondonia_2bands")

Format

A sits tibble with 160 samples.

Description

A dataset containing a tibble with time series samples for the Mato Grosso state in Brasil. The time series come from MOD13Q1 collection 6 images. The data set has the following classes: Cerrado(379 samples), Forest (131 samples), Pasture (344 samples), and Soy_Corn (364 samples).

Usage

data(samples_modis_ndvi)

Format

A tibble with 1308 rows and 7 variables: longitude: East-west coordinate of the time series sample (WGS 84), latitude (North-south coordinate of the time series sample in WGS 84), start_date (initial date of the time series), end_date (final date of the time series), label (the class label associated to the sample), cube (the name of the cube associated with the data), time_series (list containing a tibble with the values of the time series).

Description

This function calculates the accuracy of the classification result. For a set of time series, it creates a confusion matrix and then calculates the resulting statistics using package caret. The time series needs to be classified using sits_classify.

Classified images are generated using sits_classify followed by sits_label_classification. For a classified image, the function uses an area-weighted technique proposed by Olofsson et al. according to [1-3] to produce more reliable accuracy estimates at 95

In both cases, it provides an accuracy assessment of the classified, including Overall Accuracy, Kappa, User's Accuracy, Producer's Accuracy and error matrix (confusion matrix)

Usage

sits_accuracy(data, ...)

## S3 method for class 'sits'
sits_accuracy(data, ...)

## S3 method for class 'class_cube'
sits_accuracy(data, ..., validation)

## S3 method for class 'raster_cube'
sits_accuracy(data, ...)

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

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

## Default S3 method:
sits_accuracy(data, ...)

Arguments

Value

A list of lists: The error_matrix, the class_areas, the unbiased estimated areas, the standard error areas, confidence interval 95 and the accuracy (user, producer, and overall), or NULL if the data is empty. A confusion matrix assessment produced by the caret package.

Note

The 'validation' data needs to contain the following columns: "latitude", "longitude", "start_date", "end_date", and "label". It can be either a path to a CSV file, a sits tibble, a data frame, or an sf object.

When 'validation' is an sf object, the columns "latitude" and "longitude" are not required as the locations are extracted from the geometry column. The 'centroid' is calculated before extracting the location values for any geometry type.

Author(s)

Rolf Simoes, [email protected]

Alber Sanchez, [email protected]

References

[1] Olofsson, P., Foody, G.M., Stehman, S.V., Woodcock, C.E. (2013). Making better use of accuracy data in land change studies: Estimating accuracy and area and quantifying uncertainty using stratified estimation. Remote Sensing of Environment, 129, pp.122-131.

[2] Olofsson, P., Foody G.M., Herold M., Stehman, S.V., Woodcock, C.E., Wulder, M.A. (2014) Good practices for estimating area and assessing accuracy of land change. Remote Sensing of Environment, 148, pp. 42-57.

[3] FAO, Map Accuracy Assessment and Area Estimation: A Practical Guide. National forest monitoring assessment working paper No.46/E, 2016.

Examples

if (sits_run_examples()) {
    # show accuracy for a set of samples
    train_data <- sits_sample(samples_modis_ndvi, frac = 0.5)
    test_data  <- sits_sample(samples_modis_ndvi, frac = 0.5)
    rfor_model <- sits_train(train_data, sits_rfor())
    points_class <- sits_classify(
        data = test_data, ml_model = rfor_model
    )
    acc <- sits_accuracy(points_class)

    # show accuracy for a data cube classification
    # 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()
    )
    # label the probability cube
    label_cube <- sits_label_classification(
        probs_cube,
        output_dir = tempdir()
    )
    # obtain the ground truth for accuracy assessment
    ground_truth <- system.file("extdata/samples/samples_sinop_crop.csv",
        package = "sits"
    )
    # make accuracy assessment
    as <- sits_accuracy(label_cube, validation = ground_truth)
}

Description

This function add base maps to time series data cube. Base maps have information that is stable in time (e.g, DEM) which provide relevant information for modelling and classification.

To add a base cube to an existing data cube, they should share the same sensor, resolution, bounding box, timeline, and have different bands.

Usage

sits_add_base_cube(cube1, cube2)

Arguments

Value

a merged data cube with the inclusion of a base_info tibble

Author(s)

Gilberto Camara, [email protected]

Examples

if (sits_run_examples()) {
     s2_cube <- sits_cube(
           source = "MPC",
           collection = "SENTINEL-2-L2A",
           tiles = "18HYE",
           bands = c("B8A", "CLOUD"),
           start_date = "2022-01-01",
           end_date = "2022-03-31"
           )
     output_dir <- paste0(tempdir(), "/reg")
     if (!dir.exists(output_dir)) {
               dir.create(output_dir)
     }
     dem_cube <- sits_cube(
           source = "MPC",
           collection = "COP-DEM-GLO-30",
           tiles = "18HYE",
           bands = "ELEVATION"
           )
     s2_reg  <- sits_regularize(
           cube = s2_cube,
           period = "P1M",
           res = 240,
           output_dir = output_dir,
           multicores = 2,
           memsize = 4
     )
     dem_reg  <- sits_regularize(
           cube = dem_cube,
           res = 240,
           tiles = "18HYE",
           output_dir = output_dir,
           multicores = 2,
           memsize = 4
     )
     s2_reg <- sits_add_base_cube(s2_reg, dem_reg)
}

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

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, [email protected]

Felipe Carvalho, [email protected]

Gilberto Camara, [email protected]

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

Description

Return a sits_tibble or raster_cube as an sf object.

Usage

sits_as_sf(data, ..., as_crs = NULL)

## S3 method for class 'sits'
sits_as_sf(data, ..., crs = "EPSG:4326", as_crs = NULL)

## S3 method for class 'raster_cube'
sits_as_sf(data, ..., as_crs = NULL)

Arguments

Value

An sf object of point or polygon geometry.

Author(s)

Felipe Carvalho, [email protected]

Alber Sanchez, [email protected]

Examples

if (sits_run_examples()) {
    # convert sits tibble to an sf object (point)
    sf_object <- sits_as_sf(cerrado_2classes)

    # convert sits cube to an sf object (polygon)
    data_dir <- system.file("extdata/raster/mod13q1", package = "sits")
    cube <- sits_cube(
        source = "BDC",
        collection = "MOD13Q1-6.1",
        data_dir = data_dir
    )
    sf_object <- sits_as_sf(cube)
}

Description

Finds the names of the bands of a set of time series or of a data cube

Usage

sits_bands(x)

## S3 method for class 'sits'
sits_bands(x)

## S3 method for class 'raster_cube'
sits_bands(x)

## S3 method for class 'patterns'
sits_bands(x)

## S3 method for class 'sits_model'
sits_bands(x)

## Default S3 method:
sits_bands(x)

sits_bands(x) <- value

## S3 replacement method for class 'sits'
sits_bands(x) <- value

## S3 replacement method for class 'raster_cube'
sits_bands(x) <- value

## Default S3 replacement method:
sits_bands(x) <- value

Arguments

Value

A vector with the names of the bands.

Author(s)

Gilberto Camara, [email protected]

Rolf Simoes, [email protected]

Examples

if (sits_run_examples()) {
    # 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
    )
    # Get the bands from a daya cube
    bands <- sits_bands(cube)
    # Get the bands from a sits tibble
    bands <- sits_bands(samples_modis_ndvi)
    # Get the bands from patterns
    bands <- sits_bands(sits_patterns(samples_modis_ndvi))
    # Get the bands from ML model
    rf_model <- sits_train(samples_modis_ndvi, sits_rfor())
    bands <- sits_bands(rf_model)
    # Set the bands for a SITS time series
    sits_bands(samples_modis_ndvi) <- "NDVI2"
    # Set the bands for a SITS cube
    sits_bands(cube) <- "NDVI2"
}

Description

Obtain a vector of limits (either on lat/long for time series or in projection coordinates in the case of cubes)

Usage

sits_bbox(data, crs = "EPSG:4326", as_crs = NULL)

## S3 method for class 'sits'
sits_bbox(data, crs = "EPSG:4326", as_crs = NULL)

## S3 method for class 'raster_cube'
sits_bbox(data, crs = "EPSG:4326", as_crs = NULL)

## S3 method for class 'tbl_df'
sits_bbox(data, crs = "EPSG:4326", as_crs = NULL)

## Default S3 method:
sits_bbox(data, crs = "EPSG:4326", as_crs = NULL)

Arguments

Value

A bbox.

Author(s)

Gilberto Camara, [email protected]

Rolf Simoes, [email protected]

Examples

if (sits_run_examples()) {
    # get the bbox of a set of samples
    sits_bbox(samples_modis_ndvi)
    # get the bbox of a cube in WGS84
    data_dir <- system.file("extdata/raster/mod13q1", package = "sits")
    cube <- sits_cube(
        source = "BDC",
        collection = "MOD13Q1-6.1",
        data_dir = data_dir
    )
    sits_bbox(cube, as_crs = "EPSG:4326")
}

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.

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

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

Arguments

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, [email protected]

Gilberto Camara, [email protected]

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)
}

Description

Applies a modal function to clean up possible noisy pixels keeping the most frequently values within the neighborhood. In a tie, the first value of the vector is considered.

Usage

sits_clean(
  cube,
  window_size = 5L,
  memsize = 4L,
  multicores = 2L,
  output_dir,
  version = "v1-clean",
  progress = TRUE
)

## S3 method for class 'class_cube'
sits_clean(
  cube,
  window_size = 5L,
  memsize = 4L,
  multicores = 2L,
  output_dir,
  version = "v1-clean",
  progress = TRUE
)

## S3 method for class 'raster_cube'
sits_clean(
  cube,
  window_size = 5L,
  memsize = 4L,
  multicores = 2L,
  output_dir,
  version = "v1-clean",
  progress = TRUE
)

## S3 method for class 'derived_cube'
sits_clean(
  cube,
  window_size = 5L,
  memsize = 4L,
  multicores = 2L,
  output_dir,
  version = "v1-clean",
  progress = TRUE
)

## Default S3 method:
sits_clean(
  cube,
  window_size = 5L,
  memsize = 4L,
  multicores = 2L,
  output_dir,
  version = "v1-clean",
  progress = TRUE
)

Arguments

Value

A tibble with an classified map (class = "class_cube").

Author(s)

Felipe Carvalho, [email protected]

Examples

if (sits_run_examples()) {
rf_model <- sits_train(samples_modis_ndvi, ml_method = 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 = rf_model,
    output_dir = tempdir()
)
# label the probability cube
label_cube <- sits_label_classification(
    probs_cube,
    output_dir = tempdir()
)
# apply a mode function in the labelled cube
clean_cube <- sits_clean(
    cube = label_cube,
    window_size = 5,
    output_dir = tempdir(),
    multicores = 1
)
}

Description

Takes a tibble with time series that has an additional 'cluster' produced by link[sits]{sits_cluster_dendro()} and removes labels that are minority in each cluster.

Usage

sits_cluster_clean(samples)

Arguments

Value

Tibble with time series (class "sits")

Author(s)

Rolf Simoes, [email protected]

Examples

if (sits_run_examples()) {
    clusters <- sits_cluster_dendro(cerrado_2classes)
    freq1 <- sits_cluster_frequency(clusters)
    freq1
    clean_clusters <- sits_cluster_clean(clusters)
    freq2 <- sits_cluster_frequency(clean_clusters)
    freq2
}

Description

These functions support hierarchical agglomerative clustering in sits. They provide support from creating a dendrogram and using it for cleaning samples.

link[sits]{sits_cluster_dendro()} takes a tibble with time series and produces a sits tibble with an added "cluster" column. The function first calculates a dendrogram and obtains a validity index for best clustering using the adjusted Rand Index. After cutting the dendrogram using the chosen validity index, it assigns a cluster to each sample.

link[sits]{sits_cluster_frequency()} computes the contingency table between labels and clusters and produces a matrix. Its input is a tibble produced by link[sits]{sits_cluster_dendro()}.

link[sits]{sits_cluster_clean()} takes a tibble with time series that has an additional 'cluster' produced by link[sits]{sits_cluster_dendro()} and removes labels that are minority in each cluster.

Usage

sits_cluster_dendro(
  samples,
  bands = NULL,
  dist_method = "dtw_basic",
  linkage = "ward.D2",
  k = NULL,
  palette = "RdYlGn"
)

## S3 method for class 'sits'
sits_cluster_dendro(
  samples,
  bands = NULL,
  dist_method = "dtw_basic",
  linkage = "ward.D2",
  k = NULL,
  palette = "RdYlGn",
  ...
)

## Default S3 method:
sits_cluster_dendro(samples, ...)

Arguments

Value

Tibble with "cluster" column (class "sits_cluster").

Note

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

Author(s)

Rolf Simoes, [email protected]

References

"dtwclust" package (https://CRAN.R-project.org/package=dtwclust)

Examples

if (sits_run_examples()) {
    # default
    clusters <- sits_cluster_dendro(cerrado_2classes)
    # with parameters
    clusters <- sits_cluster_dendro(cerrado_2classes,
                bands = "NDVI", k = 5)
}

Description

Show label frequency in each cluster produced by dendrogram analysis

Usage

sits_cluster_frequency(samples)

Arguments

Value

A matrix containing frequencies of labels in clusters.

Author(s)

Rolf Simoes, [email protected]

Examples

if (sits_run_examples()) {
    clusters <- sits_cluster_dendro(cerrado_2classes)
    freq <- sits_cluster_frequency(clusters)
    freq
}

Description

Returns a color table

Usage

sits_colors(legend = NULL)

Arguments

Value

A tibble with color names and values

Author(s)

Gilberto Camara, [email protected]

Examples

if (sits_run_examples()) {
    # return the names of all colors supported by SITS
    sits_colors()
}

Description

Saves a color table associated to a classified data cube as a QGIS style file

Usage

sits_colors_qgis(cube, file)

Arguments

Value

No return, called for side effects

Author(s)

Gilberto Camara, [email protected]

Examples

if (sits_run_examples()) {
   data_dir <- system.file("extdata/raster/classif", package = "sits")
   ro_class <- sits_cube(
      source = "MPC",
      collection = "SENTINEL-2-L2A",
      data_dir = data_dir,
      parse_info = c( "X1", "X2", "tile", "start_date", "end_date",
                      "band", "version"),
      bands = "class",
      labels = c(
           "1" = "Clear_Cut_Burned_Area",
           "2" = "Clear_Cut_Bare_Soil",
           "3" = "Clear_Cut_Vegetation",
           "4" = "Forest")
  )
  qml_file <- paste0(tempdir(), "/qgis.qml")
  sits_colors_qgis(ro_class, qml_file)
}

Description

Resets the color table

Usage

sits_colors_reset()

Value

No return, called for side effects

Author(s)

Gilberto Camara, [email protected]

Examples

if (sits_run_examples()) {
    # reset the default colors supported by SITS
    sits_colors_reset()
}

Description

Includes new colors in the SITS color sets. If the colors exist, replace them with the new HEX value. Optionally, the new colors can be associated to a legend. In this case, the new legend name should be informed. The colors parameter should be a data.frame or a tibble with name and HEX code. Colour names should be one character string only. Composite names need to be combined with underscores (e.g., use "Snow_and_Ice" and not "Snow and Ice").

This function changes the global sits color table and the global set of sits color legends. To undo these effects, please use "sits_colors_reset()".

Usage

sits_colors_set(colors, legend = NULL)

Arguments

Value

A modified sits color table (invisible)

Author(s)

Gilberto Camara, [email protected]

Examples

if (sits_run_examples()) {
    # Define a color table based on the Anderson Land Classification System
    us_nlcd <- tibble::tibble(name = character(), color = character())
    us_nlcd <- us_nlcd |>
        tibble::add_row(name = "Urban_Built_Up", color = "#85929E") |>
        tibble::add_row(name = "Agricultural_Land", color = "#F0B27A") |>
        tibble::add_row(name = "Rangeland", color = "#F1C40F") |>
        tibble::add_row(name = "Forest_Land", color = "#27AE60") |>
        tibble::add_row(name = "Water", color = "#2980B9") |>
        tibble::add_row(name = "Wetland", color = "#D4E6F1") |>
        tibble::add_row(name = "Barren_Land", color = "#FDEBD0") |>
        tibble::add_row(name = "Tundra", color = "#EBDEF0") |>
        tibble::add_row(name = "Snow_and_Ice", color = "#F7F9F9")

    # Load the color table into `sits`
    sits_colors_set(colors = us_nlcd, legend = "US_NLCD")

    # Show the new color table used by sits
    sits_colors_show("US_NLCD")

    # Change colors in the sits global color table
    # First show the default colors for the UMD legend
    sits_colors_show("UMD")
    # Then change some colors associated to the UMD legend
    mycolors <- tibble::tibble(name = character(), color = character())
    mycolors <- mycolors |>
        tibble::add_row(name = "Savannas", color = "#F8C471") |>
        tibble::add_row(name = "Grasslands", color = "#ABEBC6")
    sits_colors_set(colors = mycolors)
    # Notice that the UMD colors change
    sits_colors_show("UMD")
    # Reset the color table
    sits_colors_reset()
    # Show the default colors for the UMD legend
    sits_colors_show("UMD")
}

Description

Shows the default SITS colors

Usage

sits_colors_show(legend = NULL, font_family = "sans")

Arguments

Value

no return, called for side effects

Author(s)

Gilberto Camara, [email protected]

Examples

if (sits_run_examples()) {
    # show the colors supported by SITS
    sits_colors_show()
}

Description

Calculate an ensemble predictor based a list of probability cubes. The function combines the output of two or more classifier to derive a value which is based on weights assigned to each model. The supported types of ensemble predictors are 'average' and 'uncertainty'.

Usage

sits_combine_predictions(
  cubes,
  type = "average",
  ...,
  memsize = 8L,
  multicores = 2L,
  output_dir,
  version = "v1"
)

## S3 method for class 'average'
sits_combine_predictions(
  cubes,
  type = "average",
  ...,
  weights = NULL,
  memsize = 8L,
  multicores = 2L,
  output_dir,
  version = "v1"
)

## S3 method for class 'uncertainty'
sits_combine_predictions(
  cubes,
  type = "uncertainty",
  ...,
  uncert_cubes,
  memsize = 8L,
  multicores = 2L,
  output_dir,
  version = "v1"
)

## Default S3 method:
sits_combine_predictions(cubes, type, ...)

Arguments

Value

A combined probability cube (tibble of class "probs_cube").

Author(s)

Gilberto Camara, [email protected]

Rolf Simoes, [email protected]

Examples

if (sits_run_examples()) {
    # 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
    )
    # create a random forest model
    rfor_model <- sits_train(samples_modis_ndvi, sits_rfor())
    # classify a data cube using rfor model
    probs_rfor_cube <- sits_classify(
        data = cube, ml_model = rfor_model, output_dir = tempdir(),
        version = "rfor"
    )
    # create an SVM model
    svm_model <- sits_train(samples_modis_ndvi, sits_svm())
    # classify a data cube using SVM model
    probs_svm_cube <- sits_classify(
        data = cube, ml_model = svm_model, output_dir = tempdir(),
        version = "svm"
    )
    # create a list of predictions to be combined
    pred_cubes <- list(probs_rfor_cube, probs_svm_cube)
    # combine predictions
    comb_probs_cube <- sits_combine_predictions(
        pred_cubes,
        output_dir = tempdir()
    )
    # plot the resulting combined prediction cube
    plot(comb_probs_cube)
}

Description

Suggest points for increasing the training set. These points are labelled with high confidence so they can be added to the training set. They need to have a satisfactory margin of confidence to be selected. The input is a probability cube. For each label, the algorithm finds out location where the machine learning model has high confidence in choosing this label compared to all others. The algorithm also considers a minimum distance between new labels, to minimize spatial autocorrelation effects. This function is best used in the following context: 1. Select an initial set of samples. 2. Train a machine learning model. 3. Build a data cube and classify it using the model. 4. Run a Bayesian smoothing in the resulting probability cube. 5. Perform confidence sampling.

The Bayesian smoothing procedure will reduce the classification outliers and thus increase the likelihood that the resulting pixels with provide good quality samples for each class.

Usage

sits_confidence_sampling(
  probs_cube,
  n = 20L,
  min_margin = 0.9,
  sampling_window = 10L,
  multicores = 1L,
  memsize = 1L
)

Arguments

Value

A tibble with longitude and latitude in WGS84 with locations which have high uncertainty and meet the minimum distance criteria.

Author(s)

Alber Sanchez, [email protected]

Rolf Simoes, [email protected]

Felipe Carvalho, [email protected]

Gilberto Camara, [email protected]

Examples

if (sits_run_examples()) {
    # create a data cube
    data_dir <- system.file("extdata/raster/mod13q1", package = "sits")
    cube <- sits_cube(
        source = "BDC",
        collection = "MOD13Q1-6.1",
        data_dir = data_dir
    )
    # build a random forest model
    rfor_model <- sits_train(samples_modis_ndvi, ml_method = sits_rfor())
    # classify the cube
    probs_cube <- sits_classify(
        data = cube, ml_model = rfor_model, output_dir = tempdir()
    )
    # obtain a new set of samples for active learning
    # the samples are located in uncertain places
    new_samples <- sits_confidence_sampling(probs_cube)
}

Description

These functions load and show sits configurations.

The 'sits' package uses a configuration file that contains information on parameters required by different functions. This includes information about the image collections handled by 'sits'.

sits_config() loads the default configuration file and the user provided configuration file. The final configuration is obtained by overriding the options by the values provided by the user.

Usage

sits_config(config_user_file = NULL)

Arguments

Details

Users can provide additional configuration files, by specifying the location of their file in the environmental variable SITS_CONFIG_USER_FILE or as parameter to this function.

To see the key entries and contents of the current configuration values, use link[sits]{sits_config_show()}.

Value

Called for side effects

Author(s)

Rolf Simoes, [email protected]

Examples

yaml_user_file <- system.file("extdata/config_user_example.yml",
                  package = "sits")
sits_config(config_user_file = yaml_user_file)

Description

Prints the current sits configuration options. To show specific configuration options for a source, a collection, or a palette, users can inform the corresponding keys to source and collection.

Usage

sits_config_show()

Value

No return value, called for side effects.

Examples

sits_config_show()

Description

Creates a user configuration file.

Usage

sits_config_user_file(file_path, overwrite = FALSE)

Arguments

Value

Called for side effects

Examples

user_file <- paste0(tempdir(), "/my_config_file.yml")
sits_config_user_file(user_file)

Description

Creates a data cube based on spatial and temporal restrictions in collections available in cloud services or local repositories. The following cloud providers are supported, based on the STAC protocol: Amazon Web Services (AWS), Brazil Data Cube (BDC), Digital Earth Africa (DEAFRICA), Microsoft Planetary Computer (MPC), Nasa Harmonized Landsat/Sentinel (HLS), USGS Landsat (USGS), and Swiss Data Cube (SDC). Data cubes can also be created using local files.

Usage

sits_cube(source, collection, ...)

## S3 method for class 'sar_cube'
sits_cube(
  source,
  collection,
  ...,
  orbit = "ascending",
  bands = NULL,
  tiles = NULL,
  roi = NULL,
  start_date = NULL,
  end_date = NULL,
  platform = NULL,
  multicores = 2,
  progress = TRUE
)

## S3 method for class 'stac_cube'
sits_cube(
  source,
  collection,
  ...,
  bands = NULL,
  tiles = NULL,
  roi = NULL,
  start_date = NULL,
  end_date = NULL,
  platform = NULL,
  multicores = 2,
  progress = TRUE
)

## S3 method for class 'local_cube'
sits_cube(
  source,
  collection,
  ...,
  data_dir,
  vector_dir = NULL,
  tiles = NULL,
  bands = NULL,
  vector_band = NULL,
  start_date = NULL,
  end_date = NULL,
  labels = NULL,
  parse_info = NULL,
  version = "v1",
  delim = "_",
  multicores = 2L,
  progress = TRUE
)

Arguments

Value

A tibble describing the contents of a data cube.

Note

To create cubes from cloud providers, users need to inform:

1. source: One of "AWS", "BDC", "DEAFRICA", "HLS", "MPC", "SDC" or "USGS";

2. collection: Collection available in the cloud provider. Use sits_list_collections() to see which collections are supported;

3. tiles: A set of tiles defined according to the collection tiling grid;

4. roi: Region of interest. Either a named vector ("lon_min", "lat_min", "lon_max", "lat_max") in WGS84, a sfc or sf object from sf package in WGS84 projection.

Either tiles or roi must be informed. The parameters bands, start_date, and end_date are optional for cubes created from cloud providers.

GeoJSON geometries (RFC 7946) and shapefiles should be converted to sf objects before being used to define a region of interest. This parameter does not crop a region; it only selects images that intersect the roi.

To create a cube from local files, users need to inform:

1. source: Provider from where the data has been downloaded (e.g, "BDC");

2. collection: Collection where the data has been extracted from. (e.g., "SENTINEL-2-L2A" for the Sentinel-2 MPC collection level 2A);

3. data_dir: Local directory where images are stored.

4. parse_info: Parsing information for files. Default is c("X1", "X2", "tile", "band", "date").

5. delim: Delimiter character for parsing files. Default is "_".

To create a cube from local files, all images should have the same spatial resolution and projection and each file should contain a single image band for a single date. Files can belong to different tiles of a spatial reference system and file names need to include tile, date, and band information. For example: "CBERS-4_WFI_022024_B13_2018-02-02.tif" and "SENTINEL-2_MSI_20LKP_B02_2018-07-18.jp2" are accepted names. The user has to provide parsing information to allow sits to extract values of tile, band, and date. In the examples above, the parsing info is c("X1", "X2", "tile", "band", "date") and the delimiter is "_", which are the default values.

It is also possible to create result cubes for these are local files produced by classification or post-classification algorithms. In this case, more parameters that are required (see below). The parameter parse_info is specified differently, as follows:

1. band: Band name associated to the type of result. Use "probs", for probability cubes produced by sits_classify(); "bayes", for smoothed cubes produced by sits_smooth(); "segments", for vector cubes produced by sits_segment(); "entropy" when using sits_uncertainty(), and "class" for cubes produced by sits_label_classification();

2. labels: Labels associated to the classification results;

3. parse_info: File name parsing information to deduce the values of "tile", "start_date", "end_date" from the file name. Default is c("X1", "X2", "tile", "start_date", "end_date", "band"). Unlike non-classified image files, cubes with results have both "start_date" and "end_date".

In MPC, sits can access are two open data collections: "SENTINEL-2-L2A" for Sentinel-2/2A images, and "LANDSAT-C2-L2" for the Landsat-4/5/7/8/9 collection. (requester-pays) and "SENTINEL-S2-L2A-COGS" (open data).

Sentinel-2/2A level 2A files in MPC are organized by sensor resolution. The bands in 10m resolution are "B02", "B03", "B04", and "B08". The 20m bands are "B05", "B06", "B07", "B8A", "B11", and "B12". Bands "B01" and "B09" are available at 60m resolution. The "CLOUD" band is also available.

All Landsat-4/5/7/8/9 images in MPC have bands with 30 meter resolution. To account for differences between the different sensors, Landsat bands in this collection have been renamed "BLUE", "GREEN", "RED", "NIR08", "SWIR16" and "SWIR22". The "CLOUD" band is also available.

In AWS, there are two types of collections: open data and requester-pays. Currently, sits supports collection "SENTINEL-2-L2A" (open data) and LANDSAT-C2-L2 (requester-pays). There is no need to provide AWS credentials to access open data collections. For requester-pays data, users need to provide their access codes as environment variables, as follows: Sys.setenv( AWS_ACCESS_KEY_ID = <your_access_key>, AWS_SECRET_ACCESS_KEY = <your_secret_access_key> )

Sentinel-2/2A level 2A files in AWS are organized by sensor resolution. The AWS bands in 10m resolution are "B02", "B03", "B04", and "B08". The 20m bands are "B05", "B06", "B07", "B8A", "B11", and "B12". Bands "B01" and "B09" are available at 60m resolution.

For DEAFRICA, sits currently works with collections "S2_L2A" for Sentinel-2 level 2A and "LS8_SR" for Landsat-8 ARD collection. (open data). These collections are located in Africa (Capetown) for faster access to African users. No payment for access is required.

For USGS, sits currently works with collection "LANDSAT-C2L2-SR", which corresponds to Landsat Collection 2 Level-2 surface reflectance data, covering Landsat-8 dataset. This collection is requester-pays and requires payment for accessing.

All BDC collections are regularized. BDC users need to provide their credentials using environment variables. To create your credentials, please see <brazil-data-cube.github.io/applications/dc_explorer/token-module.html>. Accessing data in the BDC is free. After obtaining the BDC access key, please include it as an environment variable, as follows: Sys.setenv( BDC_ACCESS_KEY = <your_bdc_access_key> )

Examples

if (sits_run_examples()) {
    # --- Access to the Brazil Data Cube
    # create a raster cube file based on the information in the BDC
    cbers_tile <- sits_cube(
        source = "BDC",
        collection = "CBERS-WFI-16D",
        bands = c("NDVI", "EVI"),
        tiles = "007004",
        start_date = "2018-09-01",
        end_date = "2019-08-28"
    )
    # --- Access to Digital Earth Africa
    # create a raster cube file based on the information about the files
    # DEAFRICA does not support definition of tiles
    cube_deafrica <- sits_cube(
        source = "DEAFRICA",
        collection = "SENTINEL-2-L2A",
        bands = c("B04", "B08"),
        roi = c(
            "lat_min" = 17.379,
            "lon_min" = 1.1573,
            "lat_max" = 17.410,
            "lon_max" = 1.1910
        ),
        start_date = "2019-01-01",
        end_date = "2019-10-28"
    )
    # --- Access to Digital Earth Australia
    cube_deaustralia <- sits_cube(
        source = "DEAUSTRALIA",
        collection = "GA_LS8CLS9C_GM_CYEAR_3",
        bands = c("RED", "GREEN", "BLUE"),
        roi = c(
            lon_min = 137.15991,
            lon_max = 138.18467,
            lat_min = -33.85777,
            lat_max = -32.56690
        ),
        start_date = "2018-01-01",
        end_date = "2018-12-31"
    )
    # --- Access to CDSE open data Sentinel 2/2A level 2 collection
    # --- remember to set the appropriate environmental variables
    # It is recommended that `multicores` be used to accelerate the process.
    s2_cube <- sits_cube(
        source = "CDSE",
        collection = "SENTINEL-2-L2A",
        tiles = c("20LKP"),
        bands = c("B04", "B08", "B11"),
        start_date = "2018-07-18",
        end_date = "2019-01-23"
    )

    ## --- Sentinel-1 SAR from CDSE
    # --- remember to set the appropriate environmental variables
    roi_sar <- c("lon_min" = 33.546, "lon_max" = 34.999,
                 "lat_min" = 1.427, "lat_max" = 3.726)
    s1_cube_open <- sits_cube(
       source = "CDSE",
       collection = "SENTINEL-1-RTC",
       bands = c("VV", "VH"),
       orbit = "descending",
       roi = roi_sar,
       start_date = "2020-01-01",
       end_date = "2020-06-10"
    )

    # --- Access to AWS open data Sentinel 2/2A level 2 collection
    s2_cube <- sits_cube(
        source = "AWS",
        collection = "SENTINEL-S2-L2A-COGS",
        tiles = c("20LKP", "20LLP"),
        bands = c("B04", "B08", "B11"),
        start_date = "2018-07-18",
        end_date = "2019-07-23"
    )

    # --- Creating Sentinel cube from MPC
    s2_cube <- sits_cube(
        source = "MPC",
        collection = "SENTINEL-2-L2A",
        tiles = "20LKP",
        bands = c("B05", "CLOUD"),
        start_date = "2018-07-18",
        end_date = "2018-08-23"
    )

    # --- Creating Landsat cube from MPC
    roi <- c("lon_min" = -50.410, "lon_max" = -50.379,
             "lat_min" = -10.1910 , "lat_max" = -10.1573)
    mpc_cube <- sits_cube(
        source = "MPC",
        collection = "LANDSAT-C2-L2",
        bands = c("BLUE", "RED", "CLOUD"),
        roi = roi,
        start_date = "2005-01-01",
        end_date = "2006-10-28"
    )

    ## Sentinel-1 SAR from MPC
    roi_sar <- c("lon_min" = -50.410, "lon_max" = -50.379,
                 "lat_min" = -10.1910, "lat_max" = -10.1573)

    s1_cube_open <- sits_cube(
       source = "MPC",
       collection = "SENTINEL-1-GRD",
       bands = c("VV", "VH"),
       orbit = "descending",
       roi = roi_sar,
       start_date = "2020-06-01",
       end_date = "2020-09-28"
    )
    # --- Access to World Cover data (2021) via Terrascope
    cube_terrascope <- sits_cube(
        source = "TERRASCOPE",
        collection = "WORLD-COVER-2021",
        roi = c(
            lon_min = -62.7,
            lon_max = -62.5,
            lat_min = -8.83,
            lat_max = -8.70
        )
    )
    # --- Create a cube based on a local MODIS data
    data_dir <- system.file("extdata/raster/mod13q1", package = "sits")
    modis_cube <- sits_cube(
        source = "BDC",
        collection = "MOD13Q1-6.1",
        data_dir = data_dir
    )
}

Description

This function downloads the images of a cube in parallel. A region of interest (roi) can be provided to crop the images and a resolution (res) to resample the bands.

Usage

sits_cube_copy(
  cube,
  ...,
  roi = NULL,
  res = NULL,
  n_tries = 3,
  multicores = 2L,
  output_dir,
  progress = TRUE
)

Arguments

Value

Copy of input data cube (class "raster cube").

Examples

if (sits_run_examples()) {
    # Creating a sits cube from BDC
    bdc_cube <- sits_cube(
        source = "BDC",
        collection = "CBERS-WFI-16D",
        tiles = c("007004", "007005"),
        bands = c("B15", "CLOUD"),
        start_date = "2018-01-01",
        end_date = "2018-01-12"
    )
    # Downloading images to a temporary directory
    cube_local <- sits_cube_copy(
        cube = bdc_cube,
        output_dir = tempdir(),
        roi = c(
            lon_min = -46.5,
            lat_min = -45.5,
            lon_max = -15.5,
            lat_max = -14.6
        ),
        multicores = 2L,
        res = 250,
    )
}

Description

This function implements the factory method pattern. Its creates a generic interface to closures in R so that the functions in the sits package can be called in two different ways: 1. Called directly, passing input data and parameters. 2. Called as second-order values (parameters of another function). In the second case, the call will pass no data values and only pass the parameters for execution

The factory pattern is used in many situations in the sits package, to allow different alternatives for filtering, pattern creation, training, and cross-validation

Please see the chapter "Technical Annex" in the sits book for details.

Usage

sits_factory_function(data, fun)

Arguments

Value

A closure that encapsulates the function applied to data.

Author(s)

Rolf Simoes, [email protected]

Gilberto Camara, [email protected]

Examples

# example code
if (sits_run_examples()) {
    # Include a new machine learning function (multiple linear regression)
    # function that returns mlr model based on a sits sample tibble

    sits_mlr <- function(samples = NULL, formula = sits_formula_linear(),
                         n_weights = 20000, maxit = 2000) {
        train_fun <- function(samples) {
            # Data normalization
            ml_stats <- sits_stats(samples)
            train_samples <- sits_predictors(samples)
            train_samples <- sits_pred_normalize(
                pred = train_samples,
                stats = ml_stats
            )
            formula <- formula(train_samples[, -1])
            # call method and return the trained model
            result_mlr <- nnet::multinom(
                formula = formula,
                data = train_samples,
                maxit = maxit,
                MaxNWts = n_weights,
                trace = FALSE,
                na.action = stats::na.fail
            )

            # construct model predict closure function and returns
            predict_fun <- function(values) {
                # retrieve the prediction (values and probs)
                prediction <- tibble::as_tibble(
                    stats::predict(result_mlr,
                        newdata = values,
                        type = "probs"
                    )
                )
                return(prediction)
            }
            class(predict_fun) <- c("sits_model", class(predict_fun))
            return(predict_fun)
        }
        result <- sits_factory_function(samples, train_fun)
        return(result)
    }
    # create an mlr model using a set of samples
    mlr_model <- sits_train(samples_modis_ndvi, sits_mlr)
    # classify a point
    point_ndvi <- sits_select(point_mt_6bands, bands = "NDVI")
    point_class <- sits_classify(point_ndvi, mlr_model, multicores = 1)
    plot(point_class)
}

Description

Applies a filter to all bands, using a filter function such as sits_whittaker() or sits_sgolay().

Usage

sits_filter(data, filter = sits_whittaker())

Arguments

Value

Filtered time series

Examples

if (sits_run_examples()) {
    # Retrieve a time series with values of NDVI
    point_ndvi <- sits_select(point_mt_6bands, bands = "NDVI")
    # Filter the point using the Whittaker smoother
    point_whit <- sits_filter(point_ndvi, sits_whittaker(lambda = 3.0))
    # Merge time series
    point_ndvi <- sits_merge(point_ndvi, point_whit,
                             suffix = c("", ".WHIT"))
    # Plot the two points to see the smoothing effect
    plot(point_ndvi)
}

Description

Provides a symbolic description of a fitting model. Tells the model to do a linear transformation of the input values. The 'predictors_index' parameter informs the positions of fields corresponding to formula independent variables. If no value is given, that all fields will be used as predictors.

Usage

sits_formula_linear(predictors_index = -2:0)

Arguments

Value

A function that computes a valid formula using a linear function.

Author(s)

Gilberto Camara, [email protected]

Alexandre Ywata de Carvalho, [email protected]

Rolf Simoes, [email protected]

Examples

if (sits_run_examples()) {
    # Example of training a model for time series classification
    # Retrieve the samples for Mato Grosso
    # train an SVM model
    ml_model <- sits_train(samples_modis_ndvi,
        ml_method = sits_svm(formula = sits_formula_logref())
    )
    # classify the point
    point_ndvi <- sits_select(point_mt_6bands, bands = "NDVI")
    # classify the point
    point_class <- sits_classify(
        data = point_ndvi, ml_model = ml_model
    )
    plot(point_class)
}

Description

A function to be used as a symbolic description of some fitting models such as svm and random forest. This function tells the models to do a log transformation of the inputs. The 'predictors_index' parameter informs the positions of 'tb' fields corresponding to formula independent variables. If no value is given, the default is NULL, a value indicating that all fields will be used as predictors.

Usage

sits_formula_logref(predictors_index = -2:0)

Arguments

Value

A function that computes a valid formula using a log function.

Author(s)

Alexandre Ywata de Carvalho, [email protected]

Rolf Simoes, [email protected]

Examples

if (sits_run_examples()) {
    # Example of training a model for time series classification
    # Retrieve the samples for Mato Grosso
    # train an SVM model
    ml_model <- sits_train(samples_modis_ndvi,
        ml_method = sits_svm(formula = sits_formula_logref())
    )
    # classify the point
    point_ndvi <- sits_select(point_mt_6bands, bands = "NDVI")
    # classify the point
    point_class <- sits_classify(
        data = point_ndvi, ml_model = ml_model
    )
    plot(point_class)
}

Description

Compute the minimum distances among samples and samples to prediction points, following the approach proposed by Meyer and Pebesma(2022).

Usage

sits_geo_dist(samples, roi, n = 1000L, crs = "EPSG:4326")

Arguments

Value

A tibble with sample-to-sample and sample-to-prediction distances (object of class "distances").

Author(s)

Alber Sanchez, [email protected]

Rolf Simoes, [email protected]

Felipe Carvalho, [email protected]

Gilberto Camara, [email protected]

References

Meyer, H., Pebesma, E. "Machine learning-based global maps of ecological variables and the challenge of assessing them", Nature Communications 13, 2208 (2022). https://doi.org/10.1038/s41467-022-29838-9

Examples

if (sits_run_examples()) {
    # read a shapefile for the state of Mato Grosso, Brazil
    mt_shp <- system.file("extdata/shapefiles/mato_grosso/mt.shp",
        package = "sits"
    )
    # convert to an sf object
    mt_sf <- sf::read_sf(mt_shp)
    # calculate sample-to-sample and sample-to-prediction distances
    distances <- sits_geo_dist(
        samples = samples_modis_ndvi,
        roi = mt_sf
    )
    # plot sample-to-sample and sample-to-prediction distances
    plot(distances)
}

Description

Retrieve a set of time series from a data cube or from a time series service. Data cubes and puts it in a "sits tibble". Sits tibbles are the main structures of sits package. They contain both the satellite image time series and their metadata.

Usage

sits_get_data(
  cube,
  samples,
  ...,
  start_date = NULL,
  end_date = NULL,
  label = "NoClass",
  bands = NULL,
  crs = "EPSG:4326",
  impute_fn = impute_linear(),
  label_attr = NULL,
  n_sam_pol = 30L,
  pol_avg = FALSE,
  pol_id = NULL,
  sampling_type = "random",
  multicores = 2L,
  progress = TRUE
)

## Default S3 method:
sits_get_data(cube, samples, ...)

## S3 method for class 'csv'
sits_get_data(
  cube,
  samples,
  ...,
  bands = NULL,
  crs = "EPSG:4326",
  impute_fn = impute_linear(),
  multicores = 2,
  progress = FALSE
)

## S3 method for class 'shp'
sits_get_data(
  cube,
  samples,
  ...,
  label = "NoClass",
  start_date = NULL,
  end_date = NULL,
  bands = NULL,
  impute_fn = impute_linear(),
  label_attr = NULL,
  n_sam_pol = 30,
  pol_avg = FALSE,
  pol_id = NULL,
  sampling_type = "random",
  multicores = 2,
  progress = FALSE
)

## S3 method for class 'sf'
sits_get_data(
  cube,
  samples,
  ...,
  start_date = NULL,
  end_date = NULL,
  bands = NULL,
  impute_fn = impute_linear(),
  label = "NoClass",
  label_attr = NULL,
  n_sam_pol = 30,
  pol_avg = FALSE,
  pol_id = NULL,
  sampling_type = "random",
  multicores = 2,
  progress = FALSE
)

## S3 method for class 'sits'
sits_get_data(
  cube,
  samples,
  ...,
  bands = NULL,
  crs = "EPSG:4326",
  impute_fn = impute_linear(),
  multicores = 2,
  progress = FALSE
)

## S3 method for class 'data.frame'
sits_get_data(
  cube,
  samples,
  ...,
  start_date = NULL,
  end_date = NULL,
  bands = NULL,
  label = "NoClass",
  crs = "EPSG:4326",
  impute_fn = impute_linear(),
  multicores = 2,
  progress = FALSE
)