Sensitivity analysis across maps of habitat connectivity

This function performs a sensitivity analysis of habitat connectivity across dispersal, geographic, and habitat parameters. For each combination of selected parameters, an index of habitat connectivity is calculated. msean() is a wrapper function around sean() function. sean() is the base connectivity analysis function, while msean() (mapped sean) is a wrappers that produces visual maps. sean() returns a GeoRasters object, whereas msean() produces a GeoNetwork object containing maps for mean connectivity, variance, and rank differences. Users can use sean() for raw numerical connectivity analysis data, and msean() to generate the three standard output maps: mean, variance, difference. It has additional argument to specify maps which are calculated using connectivity() function.

Usage

sean(
  rast,
  global = TRUE,
  geoscale = NULL,
  agg_methods = c("sum", "mean"),
  dist_method = "geodesic",
  link_threshold = 0,
  hd_threshold = 0,
  res = reso(),
  inv_pl = inv_powerlaw(NULL, betas = c(0.5, 1, 1.5), mets = c("betweeness",
    "NODE_STRENGTH", "Sum_of_nearest_neighbors", "eigenVector_centrAlitY"), we = c(50,
    15, 15, 20), linkcutoff = -1),
  neg_exp = neg_expo(NULL, gammas = c(0.05, 1, 0.2, 0.3), mets = c("betweeness",
    "NODE_STRENGTH", "Sum_of_nearest_neighbors", "eigenVector_centrAlitY"), we = c(50,
    15, 15, 20), linkcutoff = -1)
)

msean(
  rast,
  global = TRUE,
  geoscale = NULL,
  res = reso(),
  maps = TRUE,
  ...,
  outdir = tempdir()
)

Arguments

rast: This is a SpatRaster object that indicates habitat suitability across locations in a landscape. Entry values in this object can include any positive real numbers, but they typically range from 0 to 1. Currently, this argument supports only raster layers in the standard global coordinate reference system -CRS-, that is, WGS 84 or World Geodetic System 1984, identified by the EPSG code 4326. Users need to project the raster layer before providing it as an input in msean() if it is in another CRS.
global: Logical. TRUE if global analysis, FALSE otherwise. Default is TRUE
geoscale: Numeric vector. This is a set of geographic coordinates in the form of c(Xmin, Xmax, Ymin, Ymax) which correspond to the positions in the standard geographic coordinate system or EPSG:4326. geoscape referst to the geographic extent, or bounding box, for the habitat connectivity analysis. Habitat locations outside the geographic extent will be excluded from the analysis. If geoscale is NuLL, the extent is extracted from rast(SpatRaster) using terra::ext().
agg_methods: Character. One or both methods of spatial aggregation - SUM, MEAN. This is an aggregation strategy for upscaling the input raster to the desired spatial resolution. If agg_methods = c("sum"), then the sum of the habitat suitability of a set of small grid cells is divided by the total number of small cells within the resulting larger grid. If agg_methods = c("mean"), then the sum of the habitat suitability of a set of small grid cells is divided by the number of small cells containing only land within the large grid. In this strategy, small cells with water are excluded from spatial aggregation.
dist_method: Character. The method to calculate the distance matrix. For each pair of habitat locations in the SpatRaster object, msean() will calculate the geographic distances and use them to calculate the probability of an organism's movement between locations based on dispersal kernels. There are two options to calculate the distance between locations: "vincentyEllipsoid", "geodesic". Vincenty ellipsoid distance is highly accurate, accounting for the curvature of Earth, but more computationally expensive. Geodesic distance is less computationally expensive but may be less accurate for large distances than the option above.
link_threshold: Numeric. A threshold value for link weight. Based on the information on the habitat layer and dispersal kernels, adjacency matrices are created, where entries represent the potential of an organism's movement between habitat locations. Then, the adjacency matrices are converted into graph objects to perform a network analysis, where the entries in the adjacency matrices are now the weights of the links of the network. This parameter supports any positive values, but make sure these values are smaller than the maximum link weight in the network. If link_threshold = 0, all link weights in the network will be considered in the connectivity analysis. Choosing link weight thresholds greater than zero helps to focus the analysis on the most likely dispersal connections in the landscape. All link weights that are below this threshold will be replaced with zeros for the connectivity analysis.
hd_threshold: Numeric. A threshold value for habitat suitability (e.g., habitat density or climate suitability). All locations with a habitat suitability below the selected threshold will be excluded from the connectivity analysis, which focuses the analysis on the most important locations. For example, the values for the habitat suitability range between 0 and 1; if the threshold is 1, all locations will be excluded from the analysis and 0 will include all locations in the analysis. Selecting a threshold for habitat suitability requires at least knowing the maximum value in the habitat suitability map to avoid excluding all locations from the analysis. Note that if the layer of habitat suitability has entry values above 1, hd_threshold can also be adjusted accordingly.
res: Numeric. The spatial aggregation factor that will be used to aggregate the raster layer of habitat availability, from fine to coars resolution. Default is reso().
inv_pl: List. A named list of parameters for inverse power law model. In geohabnet, two dispersal kernel models are used to calculate the probability of an organism's movement between habitat locations. In this model, the dispersal probability distribution is fat-tailed. Thus, very long-distance dispersal events are assigned a higher probability compared to the negative exponential model. Please use the inv_powerlaw() function as input for the inv_pl argument, customizing parameters as exemplified above. Refer to Xing et al 2020 for the specific mathematical formulation of this dispersal kernel. Users need to specify at least one value for each parameter in inv_powerlaw(). msean() works with either or both dispersal kernel models, inv_pl and/or neg_exp.
neg_exp: List. A named list of parameters for negative exponential model. See details. This is another dispersal kernel models commonly used in landscape and movement ecology to calculate the probability of an organism's movement between habitat locations. In this model, the dispersal probability distribution tail is exponentially bounded. Thus, long-distance dispersal events will be assigned a very low probability of occurrence. Please use the neg_expo() function as input for the neg_exp argument, customizing parameters as exemplified above. Refer to Xing et al 2020 for the specific mathematical formulation of this dispersal kernel. Users need to specify at least one value for each parameter in inv_powerlaw(). msean() works with either or both dispersal kernel models, inv_pl and/or neg_exp.
maps: Logical. True, if plots should be included in side effects. False, otherwise.
...: arguments passed to sean()
outdir: Character. Output directory for saving raster in TIFF format. Default is tempdir().

Value

GeoRasters.

GeoNetwork.

Details

When global = TRUE, geoscale is ignored and global_scales() is used by default.

The functions sean() and msean() perform the same sensitivity analysis, but they differ in their return value. The return value of msean() is GeoNetwork, which contains the result from applying the connectivity() function on the habitat connectivity indexes. Essentially, the risk maps.

If neither the inverse power law nor the negative exponential dispersal kernel is specified, the function will return an error.

In msean(), three spatRasters are produced with the following values. For each location in the area of interest, the mean in habitat connectivity across selected parameters is calculated. For each location in the area of interest, the variance in habitat connectivity across selected parameters is calculated. For each location in the area of interest, the difference between the rank of habitat connectivity and the rank of host density is calculated. By default, each of these spatRasters is plotted for visualization.

References

Yanru Xing, John F Hernandez Nopsa, Kelsey F Andersen, Jorge L Andrade-Piedra, Fenton D Beed, Guy Blomme, Mónica Carvajal-Yepes, Danny L Coyne, Wilmer J Cuellar, Gregory A Forbes, Jan F Kreuze, Jürgen Kroschel, P Lava Kumar, James P Legg, Monica Parker, Elmar Schulte-Geldermann, Kalpana Sharma, Karen A Garrett, Global Cropland connectivity: A Risk Factor for Invasion and Saturation by Emerging Pathogens and Pests, BioScience, Volume 70, Issue 9, September 2020, Pages 744–758, doi:10.1093/biosci/biaa067

Hijmans R (2023). terra: Spatial Data Analysis. R package version 1.7-46, https://CRAN.R-project.org/package=terra