Package 'mlr3spatial'

Description

Extends the 'mlr3' ML framework with methods for spatial objects. Data storage and prediction are supported for packages 'terra', 'raster' and 'stars'.

Learn mlr3

• Book on mlr3: https://mlr3book.mlr-org.com

• Use cases and examples gallery: https://mlr3gallery.mlr-org.com

• Cheat Sheets: https://github.com/mlr-org/mlr3cheatsheets

mlr3 extensions

• Preprocessing and machine learning pipelines: mlr3pipelines

• Analysis of benchmark experiments: mlr3benchmark

• More classification and regression tasks: mlr3data

• Connector to OpenML: mlr3oml

• Solid selection of good classification and regression learners: mlr3learners

• Even more learners: https://github.com/mlr-org/mlr3extralearners

• Tuning of hyperparameters: mlr3tuning

• Hyperband tuner: mlr3hyperband

• Visualizations for many mlr3 objects: mlr3viz

• Survival analysis and probabilistic regression: mlr3proba

• Cluster analysis: mlr3cluster

• Feature selection filters: mlr3filters

• Feature selection wrappers: mlr3fselect

• Interface to real (out-of-memory) data bases: mlr3db

• Performance measures as plain functions: mlr3measures

Suggested packages

• Parallelization framework: future

• Progress bars: progressr

• Encapsulated evaluation: evaluate, callr (external process)

Package Options

• "mlr3.debug": If set to TRUE, parallelization via future is disabled to simplify debugging and provide more concise tracebacks. Note that results computed with debug mode enabled use a different seeding mechanism and are not reproducible.

• "mlr3.allow_utf8_names": If set to TRUE, checks on the feature names are relaxed, allowing non-ascii characters in column names. This is an experimental and temporal option to pave the way for text analysis, and will likely be removed in a future version of the package. analysis.

Author(s)

Maintainer: Marc Becker [email protected] (ORCID)

Authors:

• Patrick Schratz [email protected] (ORCID)

References

Becker M, Schratz P (2024). mlr3spatial: Support for Spatial Objects Within the 'mlr3' Ecosystem. https://mlr3spatial.mlr-org.com, https://github.com/mlr-org/mlr3spatial.

See Also

Useful links:

• https://mlr3spatial.mlr-org.com

• https://github.com/mlr-org/mlr3spatial

• Report bugs at https://github.com/mlr-org/mlr3spatial/issues

Description

Wraps a DataBackend around spatial objects. Currently these S3 methods are only alternative ways for writing DataBackendRaster$new(). They do not support coercing from other backends yet.

Usage

## S3 method for class 'stars'
as_data_backend(data, primary_key = NULL, ...)

## S3 method for class 'SpatRaster'
as_data_backend(data, primary_key = NULL, ...)

## S3 method for class 'RasterBrick'
as_data_backend(data, primary_key = NULL, ...)

## S3 method for class 'RasterStack'
as_data_backend(data, primary_key = NULL, ...)

## S3 method for class 'sf'
as_data_backend(data, primary_key = NULL, keep_rownames = FALSE, ...)

Arguments

Value

DataBackend.

Description

Convert object to a TaskClassifST. This is a S3 generic, specialized for at least the following objects:

1. TaskClassifST: Ensure the identity.

2. data.frame() and DataBackend: Provides an alternative to the constructor of TaskClassifST.

3. sf::sf: Extracts spatial meta data before construction.

4. TaskRegr: Calls convert_task().

Usage

as_task_classif_st(x, ...)

## S3 method for class 'TaskClassifST'
as_task_classif_st(x, clone = FALSE, ...)

## S3 method for class 'data.frame'
as_task_classif_st(
  x,
  target,
  id = deparse(substitute(x)),
  positive = NULL,
  coordinate_names,
  crs = NA_character_,
  coords_as_features = FALSE,
  label = NA_character_,
  ...
)

## S3 method for class 'DataBackend'
as_task_classif_st(
  x,
  target,
  id = deparse(substitute(x)),
  positive = NULL,
  coordinate_names,
  crs,
  coords_as_features = FALSE,
  label = NA_character_,
  ...
)

## S3 method for class 'sf'
as_task_classif_st(
  x,
  target = NULL,
  id = deparse(substitute(x)),
  positive = NULL,
  coords_as_features = FALSE,
  label = NA_character_,
  ...
)

## S3 method for class 'TaskRegrST'
as_task_classif_st(
  x,
  target = NULL,
  drop_original_target = FALSE,
  drop_levels = TRUE,
  ...
)

Arguments

Value

TaskClassifST

Description

Convert object to a TaskRegrST. This is a S3 generic, specialized for at least the following objects:

1. TaskRegrST: Ensure the identity.

2. data.frame() and DataBackend: Provides an alternative to the constructor of TaskRegrST.

3. sf::sf: Extracts spatial meta data before construction.

4. TaskClassif: Calls convert_task().

Usage

as_task_regr_st(x, ...)

## S3 method for class 'TaskRegrST'
as_task_regr_st(x, clone = FALSE, ...)

## S3 method for class 'data.frame'
as_task_regr_st(
  x,
  target,
  id = deparse(substitute(x)),
  coordinate_names,
  crs = NA_character_,
  coords_as_features = FALSE,
  label = NA_character_,
  ...
)

## S3 method for class 'DataBackend'
as_task_regr_st(
  x,
  target,
  id = deparse(substitute(x)),
  coordinate_names,
  crs,
  coords_as_features = FALSE,
  label = NA_character_,
  ...
)

## S3 method for class 'sf'
as_task_regr_st(
  x,
  target = NULL,
  id = deparse(substitute(x)),
  coords_as_features = FALSE,
  label = NA_character_,
  ...
)

## S3 method for class 'TaskClassifST'
as_task_regr_st(
  x,
  target = NULL,
  drop_original_target = FALSE,
  drop_levels = TRUE,
  ...
)

Arguments

Value

TaskRegrST

Description

mlr3::DataBackend for terra::SpatRaster raster objects.

Read mode

There are two different ways the reading of values is performed internally:

• "Block mode" reads complete rows of the raster file and subsets the requested cells. This mode is faster than "cell mode" if the complete raster file is iterated over.

• "Cell mode" reads individual cells. This is faster than "block mode" if only a few cells are sampled.

"Block mode" is activated if ⁠$data(rows)⁠ is used with a increasing integer sequence e.g. 200:300. If only a single cell is requested, "cell mode" is used.

Super class

mlr3::DataBackend -> DataBackendRaster

Active bindings

Methods

Public methods

• DataBackendRaster$new()

• DataBackendRaster$data()

• DataBackendRaster$head()

• DataBackendRaster$distinct()

• DataBackendRaster$missings()

• DataBackendRaster$coordinates()

Method new()

Creates a new instance of this R6 class.

Usage

DataBackendRaster$new(data)

Arguments

Method data()

Returns a slice of the raster in the specified format. Currently, the only supported formats is "data.table".

The rows must be addressed as vector of cells indices, columns must be referred to via layer names. Queries for rows with no matching row id and queries for columns with no matching column name are silently ignored.

Rows are guaranteed to be returned in the same order as rows, columns may be returned in an arbitrary order. Duplicated row ids result in duplicated rows, duplicated column names lead to an exception.

Usage

DataBackendRaster$data(rows, cols, data_format = "data.table")

Arguments

Method head()

Retrieve the first n rows.

Usage

DataBackendRaster$head(n = 6L)

Arguments

Returns

data.table::data.table() of the first n rows.

Method distinct()

Returns a named list of vectors of distinct values for each column specified. If na_rm is TRUE, missing values are removed from the returned vectors of distinct values. Non-existing rows and columns are silently ignored.

Usage

DataBackendRaster$distinct(rows, cols, na_rm = TRUE)

Arguments

Returns

Named list() of distinct values.

Method missings()

Returns the number of missing values per column in the specified slice of data. Non-existing rows and columns are silently ignored.

Usage

DataBackendRaster$missings(rows, cols)

Arguments

Returns

Total of missing values per column (named numeric()).

Method coordinates()

Returns the coordinates of rows. If rows is missing, all coordinates are returned.

Usage

DataBackendRaster$coordinates(rows)

Arguments

Returns

data.table::data.table() of coordinates of rows.

Description

mlr3::DataBackend for sf::sf vector objects.

Super classes

mlr3::DataBackend -> mlr3::DataBackendDataTable -> DataBackendVector

Active bindings

Methods

Public methods

• DataBackendVector$new()

Method new()

Creates a new instance of this R6 class.

Usage

DataBackendVector$new(data, primary_key)

Arguments

Description

Point survey of land cover in Leipzig. Includes Sentinel-2 spectral bands and NDVI.

Source

Copernicus Sentinel Data (2021). Retrieved from Copernicus Open Access Hub and processed by European Space Agency.

Examples

if (requireNamespace("sf")) {
  library(sf)
  data("leipzig", package = "mlr3spatial")
  print(leipzig)
}

Description

This function allows to directly predict mlr3 learners on various spatial objects.

Usage

predict_spatial(
  newdata,
  learner,
  chunksize = 200L,
  format = "terra",
  filename = NULL
)

Arguments

Value

Spatial object of class given in argument format.

Examples

library(terra, exclude = "resample")

# fit rpart on training points
task_train = tsk("leipzig")
learner = lrn("classif.rpart")
learner$train(task_train)

# load raster
stack = rast(system.file("extdata", "leipzig_raster.tif", package = "mlr3spatial"))

# predict land cover classes
pred = predict_spatial(stack, learner, chunksize = 1L)

Description

This task specializes TaskClassif for spatiotemporal classification problems.

A spatial example task is available via tsk("ecuador").

The coordinate reference system passed during initialization must match the one which was used during data creation, otherwise offsets of multiple meters may occur. By default, coordinates are not used as features. This can be changed by setting coords_as_features = TRUE.

Super classes

mlr3::Task -> mlr3::TaskSupervised -> mlr3::TaskClassif -> TaskClassifST

Active bindings

Methods

Public methods

• TaskClassifST$new()

• TaskClassifST$coordinates()

• TaskClassifST$print()

• TaskClassifST$clone()

Method new()

Creates a new instance of this R6 class. The function as_task_classif_st() provides an alternative way to construct classification tasks.

Usage

TaskClassifST$new(
  id,
  backend,
  target,
  positive = NULL,
  label = NA_character_,
  coordinate_names,
  crs = NA_character_,
  coords_as_features = FALSE,
  extra_args = list()
)

Arguments

Method coordinates()

Returns coordinates of observations.

Usage

TaskClassifST$coordinates(row_ids = NULL)

Arguments

Returns

data.table::data.table()

Method print()

Print the task.

Usage

TaskClassifST$print(...)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

TaskClassifST$clone(deep = FALSE)

Arguments

Description

This task specializes TaskRegr for spatiotemporal regression problems.

A spatial example task is available via tsk("cookfarm_mlr3").

The coordinate reference system passed during initialization must match the one which was used during data creation, otherwise offsets of multiple meters may occur. By default, coordinates are not used as features. This can be changed by setting coords_as_features = TRUE.

Super classes

mlr3::Task -> mlr3::TaskSupervised -> mlr3::TaskRegr -> TaskRegrST

Active bindings

Methods

Public methods

• TaskRegrST$new()

• TaskRegrST$coordinates()

• TaskRegrST$print()

• TaskRegrST$clone()

Method new()

Creates a new instance of this R6 class. The function as_task_regr_st() provides an alternative way to construct classification tasks.

Usage

TaskRegrST$new(
  id,
  backend,
  target,
  label = NA_character_,
  coordinate_names,
  crs = NA_character_,
  coords_as_features = FALSE,
  extra_args = list()
)

Arguments

Method coordinates()

Returns coordinates of observations.

Usage

TaskRegrST$coordinates(row_ids = NULL)

Arguments

Returns

data.table::data.table()

Method print()

Print the task.

Usage

TaskRegrST$print(...)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

TaskRegrST$clone(deep = FALSE)

Arguments