Calculate Network Roles Based on Within-Module Z-Score and Participation Coefficient

Implements the node role classification system of Guimerà & Amaral (2005) by calculating the within-module degree z-score and the participation coefficient for each node in a network. Nodes are assigned to one of seven role categories (R1–R7) based on their local modular connectivity.

Usage

calculate_roles(
  graph,
  communities = NULL,
  cluster.method = "spinglass",
  plot = TRUE,
  highlight_roles = TRUE,
  hub_z = 2.5,
  label_region = NULL,
  label.size = 12
)

Arguments

graph: An igraph object representing the network.
communities: Optional. A community clustering object (as returned by an igraph clustering function), or a named membership vector. If NULL, community detection is performed using cluster.method.
cluster.method: Character. Clustering algorithm to use if communities is NULL. Default is "spinglass". Passed to find_modules().
plot: Logical. Whether to generate a 2D plot of participation coefficient (P) vs. within-module z-score (z). Default is TRUE.
highlight_roles: Logical. If TRUE, the role regions in the z–P plane are shaded for visual clarity. Default is TRUE.
hub_z: Numeric. Threshold for defining hubs in terms of within-module z-score. Default is 2.5.
label_region: Optional character vector of role labels (e.g., c("R4", "R7")) indicating which role regions should have their nodes labeled in the plot. Default is NULL.
label.size: Numeric. Base font size for plot text. Default is 12.

Value

A list with three elements:

plot: The ggplot2 object (only if plot = TRUE).
roles_definitions: A data frame describing the seven role types and their conditions.
result: A data frame with node-level information: node name, module, z-score, participation coefficient, and assigned role.

Details

If no community structure is provided, modules are automatically detected using the specified clustering method. The function can optionally produce a 2D role plot (z vs. P) highlighting the canonical role regions.

The node roles are defined as:

R1	Ultra-peripheral (non-hub): \(z < 2.5, P <= 0.05\)
R2	Peripheral (non-hub): \(z < 2.5, 0.05 < P <= 0.6\)
R3	Non-hub connector: \(z < 2.5, 0.6 < P <= 0.8\)
R4	Non-hub kinless: \(z < 2.5, P > 0.8\)
R5	Provincial hub: \(z >= 2.5, P <= 0.3\)
R6	Connector hub: \(z >= 2.5, 0.3 < P <= 0.75\)
R7	Kinless hub: \(z >= 2.5, P > 0.75\)

References

Guimerà, R., & Amaral, L. A. N. (2005). Functional cartography of complex metabolic networks. Nature, 433(7028), 895–900. doi:10.1038/nature03288

Examples

if (FALSE) { # \dontrun{
g <- igraph::sample_gnp(200, 0.05, directed = F)
igraph::V(g)$name <- as.character(1:200)
result <- calculate_roles(g, plot = TRUE)
head(result$result)
} # }