graph4lg (version 1.8.0)

graphab_modul: Create modules from a graph in the Graphab project

Description

The function creates modules from a graph by maximising modularity

Usage

graphab_modul(
  proj_name,
  graph,
  dist,
  prob = 0.05,
  beta = 1,
  nb = NULL,
  return = TRUE,
  proj_path = NULL,
  alloc_ram = NULL
)

Value

If return=TRUE, the function returns a message indicating whether the partition has been done. New options are being developed.

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 modularity index 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.

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.

nb

(optional, default=NULL) An integer or numeric value indicating the number of modules to be created. By default, it is the number that maximises the modularity index.

return

Logical (default=TRUE) indicating whether results are returned to user.

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().

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.

Author

P. Savary

Details

This function maximises a modularity index by searching for the node partition involves a large number of links within modules and a small number of inter-module links. Each link is given a weight in the computation, such as the weight \(w_{ij}\) of the link between patches i and j is: $$w_{ij} = (a_{i} a_{j})^\beta e^{-\alpha d_{ij}}$$. This function does not allow users to convert automatically Euclidean distances into cost-distances. See more information in Graphab 2.8 manual: https://sourcesup.renater.fr/www/graphab/download/manual-2.8-en.pdf

Examples

if (FALSE) {
graphab_modul(proj_name = "grphb_ex",
               graph = "graph",
               dist = 1000,
               prob = 0.05,
               beta = 1)
}