rassta (version 1.0.6)

signature: Calculate the Spatial Signature of Classification Units

Description

Using a mathematical function, a raster layer is created from the cell-wise aggregation of a set of predicted distribution functions for a classification unit (see predict_functions). Each element in this set can be thought of as a correspondence measurement between an XY location in the geographic space and the landscape configuration represented by a given classification unit in terms of a specific variable. Therefore, aggregating the set of predicted distribution functions into a single layer produces an overall (multivariate) measurement of correspondence. This multivariate landscape correspondence metric is considered to be the spatial signature of the classification unit.

Usage

signature(
  pdif.rast,
  inprex,
  outname,
  fun = mean,
  to.disk = FALSE,
  outdir = ".",
  extension = ".tif",
  overwrite = FALSE,
  ...
)

Value

Single-layer or multi-layer SpatRaster with the spatial signature(s) calculated from the set(s) of predicted distribution functions.

Arguments

pdif.rast

SpatRaster, as in rast. Multi-layer SpatRaster whose raster layers represent predicted distribution functions for continuous variables and for one or more classification units. All predicted distribution functions for a particular classification unit are considered as part of the same set. There must be a matching pattern in the names of predicted distribution functions from the same set (see inprex).

inprex

Character. Prefix in the name of raster layers representing predicted distribution functions belonging to the same set (i.e.,same classification unit). If spatial signatures for multiple sets are to be calculated, a vector of strings must be provided. See Details and Examples.

outname

Character. Output layer/file name for the raster layer(s) of spatial signature. If the spatial signatures for multiple classification units are to be calculated, then a vector of strings must be provided.

fun

Function. The mathematical function must take a vector of values and return a single value (e.g., mean, max, sum, etc.). See app. Default: mean

to.disk

Boolean. Write the output raster layer(s) of spatial signature to disk? See details about parallel processing. Default: FALSE

outdir

Character. If to.disk = TRUE, string specifying the path for the output raster layer(s) of spatial signature. Default: "."

extension

Character. If to.disk = TRUE, String specifying the extension for the output raster layer(s) of spatial signature. Default: ".tif"

overwrite

Boolean. If to.disk = TRUE, should raster layers in disk and with same name as the output raster layer(s) of spatial signature be overwritten? Default: FALSE

...

If to.disk = TRUE, additional arguments as for writeRaster.

Details

Raster layers of predicted distribution functions belonging to the same classification unit must be identified by a unique prefix in their layer names (argument inprex). This prefix is used as a string pattern to find all the predicted distribution functions belonging to one classification unit. Consequently, a unique prefix must be defined for each additional classification unit to distinguish between predicted distribution functions for different classification units. Similarly, an additional string (or vector of strings) of file/layer name(s) must be provided to distinguish between the resulting spatial signatures for different classification units (argument outname). The length of outname must match that from inprex.

When writing the output raster layers of spatial signature to disk, a parallel backend can be registered before running this function with registerDoParallel to speed-up computation. Note that this is only helpful when calculating spatial signatures for many classification units.

From a spatial analysis standpoint, the aggregation of predicted distribution functions into spatial signature is similar to the application of fuzzy aggregation operators commonly used in GIS-based multi-criteria decision analysis. Moreover, The use of descriptive statistics to calculate signatures for landscape-related classification units can be traced back to the works of Pike and Rozema (1975), and Pike (1988).

References

R. Pike. The geometric signature: quantifying landslide-terrain types from digital elevation models. Mathematical geology, 20(5):491–511, 1988. tools:::Rd_expr_doi("https://doi.org/10.1007/BF00890333")

R. Pike and W. Rozema. Spectral analysis of landforms. Annals of the Association of American Geographers,65(4):499–516, 1975. tools:::Rd_expr_doi("https://doi.org/10.1111/j.1467-8306.1975.tb01058.x")

See Also

Other Landscape Correspondence Metrics: predict_functions(), select_functions(), similarity()

Examples

require(terra)
p <- system.file("exdat", package = "rassta")
# Multi-layer SpatRast with predicted distribution functions
## 3 continuous variables and 5 classification units, = 15 functions
ft <- list.files(path = p, pattern = "topo_", full.names = TRUE)
t <- terra::rast(ft)
# Vector with the prefix for each set of predicted distribution functions
## 5 classification units = 5 sets
it <- paste("topo_", seq(1, 5), "_", sep = "")
# Vector of names for output raster layers of spatial signature
## 5 spatial signatures, one per classification unit
ot <- paste("topography_", seq(1, 5), sep = "")
# Calculate spatial signatures
tsig <- signature(pdif.rast = t, inprex = it, outname = ot)
# Plot spatial signatures
if(interactive()){plot(tsig, col = hcl.colors(100, "Oslo", rev = TRUE))}