R/MK_dPCIIC_samc.R
MK_dPC_SAMC.RdComputes overall landscape connectivity and the importance (contribution) of each node (habitat patch) to that connectivity using the Probability of Connectivity (PC) index for a specified dispersal distance. Movement and settlement are modeled under a Spatial Absorbing Markov Chain (SAMC) framework.
MK_dPC_SAMC(
nodes,
keep = NULL,
attribute = NULL,
weighted = FALSE,
LA = NULL,
area_unit = "m2",
restoration = NULL,
onlyrestor = FALSE,
disp_kernel = list(resistance = NULL, CostFun = NULL, absorption = NULL, dir = 8,
SettlFunc = sum, pvertices = NULL, nvertices = 10, systematic = TRUE),
probability = NULL,
dispersal_dist = NULL,
overall = FALSE,
onlyoverall = FALSE,
parallel = NULL,
parallel_mode = 1,
write = NULL,
id_sel = NULL,
intern = TRUE
)Object containing nodes (e.g., habitat patches or fragments) information. It can be of the following classes:
- Data.frame with at least two columns: the first for node IDs and the second for attributes. If the `restoration` argument is used, the data frame must include a third column for restoration values.
- Spatial data of type vector (class sf, SpatVector, SpatialPolygonsDataFrame). It must be in a projected coordinate system.
- Raster (class RasterLayer, SpatRaster). It must be in a projected coordinate system. The values must be integers representing the ID of each habitat patch or node, with non-habitat areas represented by NA values (see clump or patches).
numeric. Use this option to simplify the nodes geometry and reduce the number of vertices. The value can range from 0 to 1 and is the proportion of points to retain (default equal to NULL). The higher the value, the higher the speed but less precision.
Character or vector. If NULL (only applicable when nodes is of spatial data of vector or raster type) the area of the nodes will be used as the node attribute. The unit of area can be selected using the area_unit parameter. To use an alternative attribute, consider the class type of the object in the nodes parameter:
- If nodes is a spatial vector or data.frame, specify the name of the column containing the attribute for the nodes.
- If nodes is a raster layer then it must be a numeric vector with the node's attribute. The length of the vector must be equal to the number of nodes. If the parameter weighted is TRUE then the numeric vector is multiplied by the area of each node to obtain a weighted habitat index.
logical. If the nodes are of raster type, you can weight the estimated area of each node by the attribute. When using this parameter the attribute parameter, which must be a vector of length equal to the number of nodes, usually has values between 0 and 1.
numeric. (optional, default = NULL). The maximum landscape attribute, which is the attribute value that would correspond to a hypothetical habitat patch covering all the landscape with the best possible habitat, in which PC would be equal to 1. For example, if nodes attribute corresponds to the node area, then LA equals total landscape area. If nodes attribute correspond to a quality-weighted area and the quality factor ranges from 0 to 100, LA will be equal to 100 multiplied by total landscape area. The value of LA does not affect at all the importance of the nodes and is only used to calculate the overall landscape connectivity. If no LA value is entered (default) and overall = TRUE or onlyoverall = TRUE, the function will only calculate the numerator of the global connectivity indices and the equivalent connected ECA or EC index.
character. (optional, default = "m2")
. A character indicating the area units when attribute is NULL. Some options are "m2" (the default), "km2", "cm2", or "ha"; See unit_convert for details.
Character or vector, (optional). This parameter specifies the binary restoration value indicating whether each node is existing or hypothetically added for restoration: 1 for existing nodes in the landscape and 0 for nodes to be added to the initial landscape. If NULL (default), all nodes are considered existing (as if all restoration values were 1). Otherwise:
- If nodes is a shapefile (spatial vector) or a data.frame, specify the name of the column containing the restoration values. If `nodes` is a data.frame, it must have three columns: the first for node IDs, the second for attributes, and the third for restoration values.
- If nodes is a raster layer, provide a numeric vector with restoration values for each node in the raster.
logical. If TRUE, then only restoration metric will be calculated.
A list with the parameters used to estimate settlement probability.
Expected components:
resistanceResistance raster (e.g., terra::SpatRaster)
where higher values indicate greater movement cost. The resistance raster must be a closed matrix with no isolated pixels.
CostFunFunction to compute the cost of moving between cells
from local resistance. Default: function(x) 1/mean(x).
absorptionraster with absorption rate for absorbing states. By default, it is estimated from the species’ mean dispersal distance and the cell size of the resistance raster (Fletcher et al., 2023). If raster, then it must be a closed matrix with no isolated pixels.
dirNeighborhood (directions) for the probability graph.
Options: 4, 8 (Moore, default), or 16.
SettlFuncFunction that aggregates (combines) settlement
probabilities among polygon vertices (edges) for each patch. Default:
mean.
pverticesProportion of boundary vertices per patch to include
in the analysis (range (0, 1]). Default: 0.1.
nverticesNumber of boundary vertices per patch to include
in the analysis. Default: 0.1.
systematicIf TRUE, vertices are selected systematically, with each selected vertex separated by approximately the same number of intermediate vertices. When FALSE, the function selects vertices at random. Default: TRUE.
A numeric value indicating the probability that corresponds to the distance specified in the dispersal_dist. For example, if the dispersal_dist is a median dispersal distance, use a probability of 0.5 (50%). If the dispersal_dist is a maximum dispersal distance, set a probability of 0.05 (5%) or 0.01 (1%). Use in case of selecting the "PC" metric. If probability = NULL, then a probability of 0.5 will be used.
A numeric indicating the dispersal distance (meters) of the considered species. If NULL then distance is estimated as the median dispersal distance between nodes. Alternatively, the dispersal_distance function can be used to estimate the dispersal distance using the species home range.
logical. If TRUE, then the overall metrics will be added to the result which is transformed into a list. Default equal to FALSE
logical. If TRUE, then only overall metrics will be calculated.
(optional, default = NULL).
A numeric specifying the number of cores to parallelize the index estimation of the PC index and its deltas.Particularly useful when you have more than 1000 nodes. By default the analyses are not parallelized.
(optional, default = 1).
A numeric indicating the mode of parallelization: Mode 1 (the default option, and recommended for less than 1000 nodes) parallelizes on the connectivity delta estimate, while Mode 2 (recommended for more than 1000 nodes)
parallelizes on the shortest paths between vertices estimate.
Character indicating the path and initial prefix of the objects to save, for example, "C:/example/test_PC_". By default, nothing is saved. The saved objects are:
- The importance of each node or habitat patch. The format of the output file depends on the class of nodes (shapefile, raster, or table).
- Overall landscape connectivity table (if the overall argument is TRUE).
Internal use only, not for users.
logical. Show the progress of the process, default = TRUE. Sometimes the advance process does not reach 100 percent when operations are carried out very quickly.
- If you add overall = TRUE, then a list containing the sf class object with the importance values of the nodes and a data.frame with the overall connectivity values (num, EC, PC) will be returned.
- If you use the restoration parameter then an extra column will be returned to the sf object with the node importance values, unless you use the onlyrestor argument (i.e., equal to TRUE) only the restoration metric is estimated.
The SAMC framework treats raster cells as states with three roles: departure, transient (movement) and absorbing (settlement at patch boundaries). Transition probabilities are derived from a resistance surface (and a chosen neighborhood structure), while absorption rates reflect species’ dispersal and patch properties. Multi-step transitions yield probabilities of reaching (and settling in) patches across the landscape. These probabilities are then used to compute the overall connectivity (PC) and the node importance (each patch’s contribution to PC, e.g., via ΔPC). The SAMC computations are implemented via the samc R package (Marx et al., 2020).
Sometimes the advance process does not reach 100 percent when operations are carried out very quickly.
- Saura, S. & Torné, J. 2012. Conefor 2.6 user manual (May 2012). Universidad Politécnica de Madrid. Available at www.conefor.org.
- Saura, S. & Pascual-Hortal, L. 2007. A new habitat availability index to integrate connectivity in landscape conservation planning: comparison with existing indices and application to a case study. Landscape and Urban Planning 83 (2-3): 91-103.
- Saura, S., Bodin, Ö., & Fortin, M.-J. (2014). EDITOR’S CHOICE: Stepping stones are crucial for species’ long-distance dispersal and range expansion through habitat networks. Journal of Applied Ecology, 51(1), 171-182.
- Hanski, I. and Ovaskainen, O. 2000. The metapopulation capacity of a fragmented landscape. Nature 404: 755–758.
- Marx, A. J., Wang, C., Sefair, J. A., Acevedo, M. A., & Fletcher Jr., R. J. (2020). samc: An R package for connectivity modeling with spatial absorbing Markov chains. Ecography, 43(4), 518-527.
- Fletcher, R. J., Iezzi, M. E., Guralnick, R., Marx, A. J., Ryan, S. J., & Valle, D. (2023). A framework for linking dispersal biology to connectivity across landscapes. Landscape Ecology, 38(10), 2487-2500. https://doi.org/10.1007/s10980-023-01741-8
if (FALSE) { # \dontrun{
library(Makurhini)
library(sf)
library(raster)
data("habitat_nodes", package = "Makurhini")
nrow(habitat_nodes) # Number of patches
data("resistance_matrix", package = "Makurhini")
#Example
hn <- habitat_nodes[350:404,]
hn$Id <- 1:nrow(hn)
plot(hn)
mask_hn <- st_as_sfc(st_bbox(hn)) |> st_as_sf() |> st_buffer(5000)
#Aggregate for this example
resist <- aggregate(resistance_matrix, 4)
resist <- crop(resistance_matrix, mask_hn)
plot(resist)
#Two distance threshold,
PCsamc <- MK_dPC_SAMC(nodes = hn,
keep = 0.5,
attribute = NULL,
area_unit = "m2",
disp_kernel = list(resistance = resist,
CostFun = function(x) 1/mean(x),
absorption = NULL, dir = 4,
SettlFunc = sum, nvertices = 10),
LA = NULL,
overall = TRUE,
dispersal_dist = 10000) #10 km
PCsamc$overall_d10000
plot(PCsamc$node_importances_d10000["dPC"], breaks = "jenks")
plot(PCsamc$node_importances_d10000["dPCintra"], breaks = "jenks")
plot(PCsamc$node_importances_d10000["dPCflux"], breaks = "jenks")
plot(PCsamc$node_importances_d10000["dPCconnector"], breaks = "jenks")
} # }