Visualization of communities and hyper order networks • cograph

1 Introduction

cograph provides two functions for visualizing community structure and higher-order relationships in networks:

overlay_communities() — renders a network with splot() and overlays smooth blob shapes highlighting communities
plot_simplicial() — visualizes higher-order pathways (simplicial complexes) as blobs on a ggplot2 canvas

Both accept any network type: tna, matrix, igraph, or cograph_network.

We use a TNA model of collaborative group regulation throughout:

model <- tna(group_regulation)

2 overlay_communities()

2.1 Method Name

The simplest way: pass an igraph community detection method name. Partial matching and flexible naming are supported.

overlay_communities(model, "fast_greedy")

Any igraph cluster_* method works: "walktrap", "louvain", "fast_greedy", "leading_eigen", "infomap", "leiden", "label_prop", "edge_betweenness", "spinglass", "optimal", "fluid_communities". You can use the full igraph name ("cluster_walktrap"), the short name ("walktrap"), or a partial match ("leading_eige"). Directed graphs are automatically converted to undirected for detection.

overlay_communities(model, "louvain")

2.2 Named List

Define communities manually with a named list:

overlay_communities(model, list(
  Regulatory = c("plan", "monitor", "adapt"),
  Social     = c("cohesion", "emotion", "consensus"),
  Task       = c("discuss", "synthesis", "coregulate")
))

2.3 Membership Vector

A numeric vector or factor where each position maps to a node:

overlay_communities(model, c(1, 1, 1, 2, 2, 2, 3, 3, 3))

2.4 Custom Colors

overlay_communities(model, "louvain", blob_colors = c("#E5B000", "#B4D7E0", "#C5E8A4"))

2.5 Overlapping Communities

Communities can share nodes:

overlay_communities(model, list(
  "Self-Regulation" = c("plan", "monitor", "adapt", "emotion"),
  Collaboration     = c("cohesion", "consensus", "discuss",
                         "coregulate", "synthesis")
), blob_colors = c("#4FC3F7", "#fbb550"), blob_alpha = 0.30)

3 plot_simplicial()

plot_simplicial() visualizes higher-order pathways as smooth blob shapes over a network layout. Source nodes appear in blue, target nodes in red.

3.1 Manual Pathways

You can specify pathways directly as strings:

plot_simplicial(model, c(
  "plan monitor -> adapt",
  "cohesion emotion -> consensus",
  "discuss synthesis -> coregulate"
), title = "Manual Pathways")

3.2 Auto-Built from HON

When given a netobject (from Nestimate), plot_simplicial() automatically builds a Higher-Order Network and extracts the most frequent pathways where sequential context changes the transition distribution:

library(Nestimate)
net <- build_network(group_regulation, method = "relative")

plot_simplicial(net, max_pathways = 6,
  title = "Top 6 HON Pathways")

3.3 Dismantled View

One panel per pathway — easier to read individual pathways:

plot_simplicial(net, max_pathways = 6,
  dismantled = TRUE, ncol = 3)

3.4 HYPA Anomalous Pathways

Switch to method = "hypa" to show paths that occur significantly more or less often than expected under a null model:

plot_simplicial(net, method = "hypa", max_pathways = 6,
  dismantled = TRUE, ncol = 3)

3.5 Custom Styling

plot_simplicial(model,
  c("plan monitor -> adapt",
    "adapt monitor -> plan",
    "plan adapt -> monitor"),
  blob_colors = c("#B0D4F1", "#8BBDE0", "#6AA6CF"),
  blob_alpha = 0.30,
  title = "Regulatory Cycle"
)