calc_zoi: Calculates the zone of influence from the nearest feature and...

In NINAnor/oneimpact: Tools for the assessment of the cumulative impacts of anthropogenic features in ecological studies

Calculates the zone of influence from the nearest feature and the cumulative zone of influence of multiple features

Description

This function takes in a raster with locations of infrastructure and calculates either (1) a raster representing the Zone of Influence (ZOI) of the neareast feature or (2) a raster representing the cumulative Zone of Influence of multiple features, or both. This function takes in a raster with locations or counts of infrastructure and calculates a raster (or set of rasters, in case there is more the one value for radius) representing either of two zone of influence (ZOI) metrics for type of infrastructure: (1) the ZOI of the neareast feature, (2) the cumulative ZOI of multiple features, or (3) both ZOI metrics. Zones of influence are defined by functions that decay with the distance from each infrastructure and their rate of decay is controlled by the ZOI radius (radius), which defines how far the influence of an infrastructure feature goes. To see more information on each ZOI metric, see calc_zoi_nearest() and calc_zoi_cumulative().

Usage

calc_zoi(
  x,
  radius = 100,
  type = c("circle", "Gauss", "rectangle", "exp_decay", "bartlett", "threshold",
    "mfilter")[1],
  zoi_metric = c("all", "nearest", "cumulative")[1],
  where = c("R", "GRASS")[1],
  zeroAsNA = TRUE,
  output_type = c("cumulative_zoi", "density")[1],
  ...
)

Arguments

x	⁠[RasterLayer,SpatRaster]⁠ Raster representing locations of features, preferentially with positive value where the features are located and either 0 or NA elsewhere. Alternatively, x might be a binary (dummy) spatial variable representing the presence of linear or area features, with 0 or NA/no-data as background. x can be a RasterLayer from raster package or a SpatRaster from terra package. If where = "GRASS", x must be a string corresponding to the name of the input map within a GRASS GIS location and mapset. The default parameters assume that the input x presents zeros as the background value, where infrastructure or disturbance are absent. Therefore, to deal correctly with the computation of both ZOI metrics, by default we set the parameter zeroAsNA = TRUE. If, in contrast, the input map x has NA as background values, the parameter zeroAsNA should be set to FALSE.
radius	⁠[numeric(1)]⁠ Radius of the zone of influence (ZOI), the distance at which the ZOI vanishes or goes below a given minimum limit value zoi_limit. See zoi_functions() for details. It can be a single value or a vector of values, in which case several ZOI layers (one for each radius) are created.
type	⁠[character(1)="circle"]{"circle", "Gauss", "rectangle", "exp_decay", "bartlett", "threshold", "step"}⁠ Shape of the zone of influence. See calc_zoi_nearest() for details.
zoi_metric	⁠[character(1)="all"]{"all", "nearest", "cumulative"}⁠ Which metric of zone of influence should be computed. Either "all", "nearest", or "cumulative".
output_type	⁠[character(1)="cumulative_zoi"]{"cumulative_zoi", "density"}⁠ For the cumulative ZOI, if output_type = "cumulative_zoi" (default), the ZOI weight matrix not not normalized, i.e. the maximum value of the weight matrix at the central pixel value is always 1. This means the values of the input map are summed (considering a decay with distance within the neighborhood) and the output map presents values higher than 1. If output_type = "density", the weight matrix is normalized before the filtering process, leading to values in the outmap map generally lower than 1. This parameter is ignored for the ZOI of the nearest feature.

Value

If the calculations are performed in R (where = "R"), a RasterLayer/RasterStack or SpatRaster object (according to the input x map) with the either the zone of influence of the nearest feature (if zoi_metric = "nearest"), the cumulative zone of influence of multiple features (if zoi_metric = "cumulative"), or both metrics (if zoi_metric = "all", the default).
If the computation is done in GRASS GIS, the output is the name of the output raster map(s) within the GRASS GIS location and mapset of the current session. The user can retrieve these maps to R using rgrass::read_RAST() or export them outside GRASS using the r.out.gdal module, for instance.

See Also

Fore more details on each of the ZOI metrics, other function parameters, and their specific details, see calc_zoi_nearest() and calc_zoi_cumulative().

Examples

library(terra)

# Load raster data
f <- system.file("raster/sample_area_cabins.tif", package = "oneimpact")
cabins <- terra::rast(f)

#---
# check background values
terra::freq(cabins) ## No zeros, background is NA

# compute both Zoi metrics with Gaussian decay, radius = 1000 m
# since the background is NA, we use zeroAsNA = FALSE
zoi_metrics <- calc_zoi(cabins,
                        radius = 1000,
                        type = "Gauss",
                        zeroAsNA = FALSE)
# check
zoi_metrics
# plot
plot(zoi_metrics)

#-------

# Load raster data
f <- system.file("raster/sample_area_cabins_count.tif", package = "oneimpact")
cabins_count <- terra::rast(f)

# check background values
terra::freq(cabins_count) ## Places with no infrastructure have value zero

# compute both Zoi metrics with linear decay, varying radius from 1000 m to 3000 m
# since the background is zero, we use zeroAsNA = TRUE
zoi_metrics2 <- calc_zoi(cabins_count,
                         radius = c(1000, 2000, 3000),
                         type = "bartlett",
                         zeroAsNA = TRUE,
                         output_type = "density")

# check
zoi_metrics2
# plot
plot(zoi_metrics2)

NINAnor/oneimpact documentation built on June 14, 2025, 12:27 a.m.