For each stratification unit present in a single-layer SpatRaster, a raster
layer of landscape similarity is created by aggregating the stratification
unit's corresponding set of spatial signatures (see signature).
For a stratification unit x, the corresponding set of spatial
signatures consists of one spatial signature for each of the n
classification units that are present in the numeric code of x (one
classification unit per landscape factor/factor scale). The aggregation
process is performed cell-wise, and by using a mathematical function which
takes multiple values but return a single value (e.g., mean, sum, min, max).
The resulting raster layer represents the correspondence between an XY
location in geographic space and the landscape configuration represented by a
given stratification unit.
Usage
similarity(
su.rast,
su.code,
sig.rast,
fun = mean,
to.disk = FALSE,
outdir = ".",
prefix = "su_",
extension = ".tif",
overwrite = FALSE,
...
)Arguments
- su.rast
SpatRaster, as in
rast. Single-layer SpatRaster representing the stratification units occurring across geographic space. Integer values are expected as cell values (i.e., numeric codes) of stratification units.- su.code
List. The structure of the stratification units' numeric code. This (nested) list should indicate the names of the landscape factors/factor scales used to create the stratification units, and the position (start, end) of their corresponding classification units' ID in the numeric code. See Examples.
- sig.rast
SpatRaster. Multi-layer SpatRaster with the spatial signatures of all the classification units that were used to create the stratification units. The spatial signatures should follow this name convention: x_n; where x is the landscape factor/factor scale, and n is the numeric ID of the classification unit to which the spatial signature belongs.
- fun
Function. The mathematical function must accept 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 layers of landscape similarity to disk? See note about parallel processing. Default: FALSE
- outdir
Character. If to.disk = TRUE, string specifying the path for the output raster layers of landscape similarity. Default: "."
- prefix
Character. If to.disk = TRUE, prefix for the file name of the output raster layers of landscape similarity. Default: "su_"
- extension
Character. If to.disk = TRUE, string specifying the extension for the output raster layers of landscape signature. Default: ".tif"
- overwrite
Boolean. When to.disk = TRUE, should raster layers in disk and with same name as the output landscape similarities be overwritten? Default: FALSE
- ...
Additional arguments as for
writeRaster(if to.disk = TRUE).
Value
A list with the following components:
landsim: Multi-layer SpatRaster with the landscape similarity to each stratification unit present in su.rast.
codes: A data frame with the numeric code for each stratification unit and the corresponding classification units' numeric ID for each landscape factor/factor scale.
Details
The landscape similarity is a landscape correspondence metric. The aggregation of multiple spatial signatures into a single landscape similarity layer is somewhat similar to the application of fuzzy logic and aggregation operators in GIS-based multi-criteria decision analysis. Furthermore, the aggregation of raster layers indicating relative optimality for spatially-varying phenomena, like spatial signatures, can be guided by physical/ecological principles like Sprengel-Liebig's law of the minimum. In such case, one could select the min function when aggregating the spatial signatures into landscape similarities.
When writing the output raster layers of landscape similarity to disk, a
parallel backend can be registered before running this function with
registerDoParallel to speed-up computation.
See also
Other Landscape Correspondence Metrics:
predict_functions(),
select_functions(),
signature
Examples
require(terra)
p <- system.file("exdat", package = "rassta")
# Single-layer SpatRaster of stratification units
fsu <- list.files(path = p, pattern = "strata2.tif", full.names = TRUE)
su <- terra::rast(fsu)
# Define the structure of the stratification units' numeric code
code <- list(geology = c(1,1), climate = c(2,2), topography = c(3,3))
# Multi-layer SpatRaster of spatial signatures of classification units
fsig <- list.files(path = p, pattern = "geology_|climate_|topography_",
full.names = TRUE
)
sig <- terra::rast(fsig)
# Calculate landscape similarity to stratification units
landsim <- similarity(su.rast = su, su.code = code, sig.rast = sig)
# Plot some landscape similarities
# if(interactive()){plot(landsim$landsim[[c(1,10,12,14)]],
# col = hcl.colors(100, "Oslo", rev = TRUE)
# )}
#-------
# A note on the numeric code of stratification units
# For a given stratification unit, the structure of its corresponding numeric
# code indicates: (1) the landscape factors and/or factor scales that were
# accounted for when creating the stratification unit, and (2) the numeric id
# of the classification unit from each landscape factor/factor scale.
# Consider the following numeric code structure:
su.code <- list(geology = c(1,1), climate = c(2,2), topography = c(3,4))
# The stratification units are composed of classification units from...
# ...three landscape factors: geology, climate, and topography
names(su.code)
#> [1] "geology" "climate" "topography"
# For geology, the classification units are represented by the first...
# ...digit in the numeric code
su.code$geology
#> [1] 1 1
# For climate, the classification units are represented by the second...
# ...digit in the numeric code
su.code$climate
#> [1] 2 2
# For topography, the classification units are represented by the third...
# ...and fourth digit in the numeric code
su.code$topography
#> [1] 3 4
# Thus, the numeric code of the stratification units 1101 and 2410 means:
su <- c(1101, 2410)
su[1] # 'geology' = 1, 'climate' = 1, and 'topography' = 1
#> [1] 1101
su[2] # 'geology' = 2, 'climate' = 4, and 'topography' = 10
#> [1] 2410