graphab_metric: Compute connectivity metrics from a graph in the Graphab...

In graph4lg: Build Graphs for Landscape Genetics Analysis

Compute connectivity metrics from a graph in the Graphab project

Description

The function computes connectivity metrics on a graph from a link set in a Graphab project

Usage

graphab_metric(
  proj_name,
  graph,
  metric,
  multihab = NULL,
  resfile = NULL,
  dist = NULL,
  prob = 0.05,
  beta = 1,
  cost_conv = FALSE,
  return_val = TRUE,
  proj_path = NULL,
  parallel.java = NULL,
  alloc_ram = NULL
)

Arguments

proj_name	A character string indicating the Graphab project name. The project name is also the name of the project directory in which the file proj_name.xml is.
graph	A character string indicating the name of the graph on which the metric is computed. This graph has been created with Graphab or using graphab_graph function and is associated with a link set. Only the links present in the graph and their corresponding weights will be used in the computation, together with patch areas.
metric	A character string indicating the metric which will be computed on the graph. This metric can be: A global metric: Probability of Connectivity (metric = 'PC'): Sum of products of area of all pairs of patches weighted by their interaction probability, divided by the square of the area of the study zone. This ratio is the equivalent to the probability that two points randomly placed in the study area are connected. Equivalent Connectivity (metric = 'EC'): Square root of the sum of products of capacity of all pairs of patches weighted by their interaction probability. This is the size of a single patch (maximally connected) that would provide the same probability of connectivity as the actual habitat pattern in the landscape (Saura et al., 2011). Integral Index of Connectivity (metric = 'IIC'): For the entire graph: product of patch areas divided by the number of links between them, the sum is divided by the square of the area of the study zone. IIC is built like the PC index but using the inverse of a topological distance rather than a negative exponential function of the distance based on the link weight. A local metric: Flux (metric = 'F'): For the focal patch i : sum of area of patches other than i and weighted according to their minimum distance to the focal patch through the graph. This sum is an indicator of the potential dispersion from the patch i or, conversely to the patch i Betweenness Centrality index (metric = 'BC'): Sum of the shortest paths through the focal patch i, each path is weighted by the product of the areas of the patches connected and of their interaction probability. All possible paths between every pair of patches is considered in this computation. Interaction Flux (metric = 'IF'): Sum of products of the focal patch area with all the other patches, weighted by their interaction probability. Degree (metric = 'Dg'): Number of edges connected to the node i i.e. number of patches connected directly to the patch i. Closeness Centrality index (metric = 'CCe'): Mean distance from the patch i to all other patches of its component k. Current Flux (metric = 'CF'): Sum of currents passing through the patch i. c_{i}^{j} represents the current through the patch i when currents are sent from all patches (except j) to the patch j. The patch j is connected to the ground. A delta metric: delta Probability of Connectivity (metric = 'dPC'): Rate of variation between the value of PC index and the value of PC' corresponding to the removal of the patch i. The value of dPC is decomposed into three parts: dPC_{area} is the variation induced by the area lost after removal; dPC_{flux} is the variation induced by the loss of interaction between the patch i and other patches; dPC_{connector} is the variation induced by the modification of paths connecting other patches and initially routed through i. For most metrics, the interaction probability is computed for each pair of patches from the path that minimizes the distance d (or the cost) between them. It then maximizes {e}^{-\alpha d_{ij}} for patches i and j. To use patch capacity values different from the patch area, please use directly Graphab software.
multihab	(optional, default = NULL) A character string indicating whether the metric value should be decomposed across the different habitat types and their pairwise combinations. If ‘multihab=’all'', all the pairwise combinations are considered, including the within-habitat case. If ‘multihab=’inter'', only the inter-habitat types combinations are considered. Note that this argument is only required if the graph on which you compute the metrics is based on several habitat types.
resfile	(optional, default = NULL) A character string giving the name of the text file storing the results of the computation. Must be of the form 'file.txt'.
dist	A numeric or integer value specifying the distance at which dispersal probability is equal to prob. This argument is mandatory for weighted metrics (PC, F, IF, BC, dPC, CCe, CF) but not used for others. It is used to set \alpha for computing dispersal probabilities associated with all inter-patch distances such that dispersal probability between patches i and j is p_{ij}= e^{-\alpha d_{ij}}.
prob	A numeric or integer value specifying the dispersal probability at distance dist. By default, code=0.05. It is used to set \alpha (see param dist above).
beta	A numeric or integer value between 0 and 1 specifying the exponent associated with patch areas in the computation of metrics weighted by patch area. By default, beta=1. When beta=0, patch areas do not have any influence in the computation.
cost_conv	FALSE (default) or TRUE. Logical indicating whether numeric dist values are converted from cost-distance into Euclidean distance using a log-log linear regression. See also convert_cd function.
return_val	Logical (default = TRUE) indicating whether metric values are returned in R (TRUE) or only stored in the patch attribute layers (FALSE)
proj_path	(optional) A character string indicating the path to the directory that contains the project directory. It should be used when the project directory is not in the current working directory. Default is NULL. When 'proj_path = NULL', the project directory is equal to getwd().
parallel.java	An integer indicating how many computer cores are used to run the .jar file. By default, parallel.java = NULL, and java sets it according to local settings.
alloc_ram	(optional, default = NULL) Integer or numeric value indicating RAM gigabytes allocated to the java process. Increasing this value can speed up the computations. Too large values may not be compatible with your machine settings.

Details

The metrics are described in Graphab 3.0 manual: https://thema.umlp.fr/productions/software/graphab/download/manual-3.0-en.pdf Graphab software makes possible the computation of other metrics. Be careful, when the same metric is computed several times, the option return=TRUE is not returning the right columns. In these cases, use get_graphab_metric.

Value

If return_val=TRUE, the function returns a data.frame with the computed metric values and the corresponding patch ID when the metric is local or delta metric, or the numeric value of the global metric. If the metric is computed on a graph whose nodes belong to different habitat categories, the returned table includes several habitat categories.

Author(s)

P. Savary

References

\insertRef

foltete2012softwaregraph4lg \insertReffoltete2021graphabgraph4lg \insertRefsavary2024multiplegraph4lg

Examples

## Not run: 
graphab_metric(proj_name = "graphab_example",
               graph = "graph_forest",
               metric = "F",
               multihab = "all",
               dist = 1000,
               prob = 0.05,
               beta = 1,
               cost_conv = TRUE)

## End(Not run)

graph4lg documentation built on Sept. 24, 2026, 5:12 p.m.