Package {dynamicmultiplex}

Animate multiplex networks as a GIF by layer

Description

Creates one frame per layer and colors nodes by community using colorblind-friendly ColorBrewer palettes (Set2 or Dark2).

Usage

animate_multilayer_gif(
  layers,
  fit = NULL,
  community_memberships = NULL,
  output_file,
  directed = FALSE,
  fps = 2,
  width = 800,
  height = 600,
  layout = "layout_with_fr",
  palette = "Dark2"
)

Arguments

Value

The path to the created GIF.

Examples

if (requireNamespace("ggplot2", quietly = TRUE) &&
    requireNamespace("gganimate", quietly = TRUE) &&
    requireNamespace("gifski", quietly = TRUE)) {
  set.seed(123)
  layers <- lapply(1:3, function(i) {
    m <- matrix(rbinom(64, 1, 0.35), nrow = 8)
    m <- pmax(m, t(m))
    diag(m) <- 0
    m
  })
  fit <- fit_multilayer_jaccard(layers, algorithm = "louvain")
  gif_path <- animate_multilayer_gif(
    layers,
    fit = fit,
    output_file = tempfile(fileext = ".gif"),
    fps = 2,
    width = 200,
    height = 150
  )
}

Parametric network bootstrap for the stability score

Description

Quantifies the uncertainty of multilayer community detection by refitting communities on n_boot resampled networks, using a parametric network bootstrap: within- and between-community edge probabilities (and, for weighted networks, edge-weight pools) are estimated from the observed network using the point-estimate partition, and each replicate redraws the full edge set from those estimates. This reproduces the variability of fresh data, including which edges exist.

Since 1.4.0 the package uses the bootstrap only for the stability score s reported by partition_stability, which compares fits of the same network. The interval outputs of earlier versions (co_assignment_ci(), community_est(), the calibrated accuracy floor) were removed because their coverage was not reliable.

Agreement is measured on the cross-layer meta-communities (the tracked partition from the second-stage detection), not the independently-detected per-layer communities. Co-assignment therefore answers "do these two nodes belong to the same persistent community," and the community count is the number of meta-communities per layer.

Versions before 1.1.0 instead used a Bayesian bootstrap on edge weights (Exponential(1) multipliers on a fixed topology). That scheme was removed: because it never varies which edges exist, it understates the variability of fresh data, and in simulation studies confidence intervals built from it undercovered substantially (pairwise co-assignment intervals covered ~45-48 percent at a nominal 95 percent).

Usage

bootstrap_multilayer(
  layers,
  fit_type = c("jaccard", "overlap", "weighted_jaccard", "weighted_overlap", "identity"),
  algorithm = c("leiden", "louvain"),
  n_boot = 100,
  layer_links = NULL,
  min_similarity = 0,
  resolution_parameter = 1,
  directed = FALSE,
  seed = NULL,
  objective = NULL,
  tracking = "smoothed",
  repair_chains = FALSE,
  repair_min_similarity = 0.2,
  allow_unequal_nodes = FALSE
)

Arguments

Value

A list of class "multilayer_bootstrap" with components:

n_boot

Number of completed bootstrap replicates.

co_assignment

Per-layer co-assignment probability matrices on the meta-communities (probability two nodes share a persistent community).

node_stability

Per-layer vectors giving the fraction of replicates in which each node was assigned to its modal community.

modularity_samples

Per-layer vectors of bootstrap modularity values.

community_count_reproducibility

Per-layer numeric vector: the share of completed replicates whose meta-community count equals the observed-network count. A descriptive stability measure. The raw per-replicate community counts are intentionally not returned.

stability_samples

List with matrices nmi and ari (completed replicates x layers): agreement of each replicate's meta-partition with the point-estimate partition. Summarised by partition_stability.

node_jaccard_stability

Per-layer vectors: for each node, the mean Jaccard overlap between its replicate community and its point-estimate community.

point_estimate

The fit result from the original data.

Examples

set.seed(123)
layers <- lapply(1:3, function(i) {
  m <- matrix(rbinom(64, 1, 0.35), nrow = 8)
  m <- pmax(m, t(m))
  diag(m) <- 0
  m
})
boot <- bootstrap_multilayer(
  layers,
  fit_type = "jaccard",
  algorithm = "louvain",
  n_boot = 5,
  seed = 123
)
names(boot)

Extract cross-layer meta-community membership

Description

Returns the tracked (cross-layer) community assignment produced by the second-stage detection: for each layer, a vector giving every node's meta-community. Unlike the per-layer layer_communities (detected independently, ignoring the coupling), the meta-communities are the partition that reflects the interlayer ties and any custom layer_links. This is the membership that bootstrap_multilayer validates.

Usage

extract_meta_membership(fit)

Arguments

Value

A list with one integer vector per layer giving each node's meta-community assignment (node order).

Examples

set.seed(123)
layers <- lapply(1:3, function(i) {
  m <- matrix(rbinom(64, 1, 0.35), nrow = 8)
  m <- pmax(m, t(m)); diag(m) <- 0; m
})
fit <- fit_multilayer_jaccard(layers, algorithm = "leiden")
extract_meta_membership(fit)

Fit multilayer communities with Hungarian snapshot matching

Description

Detects communities independently in each layer and then tracks them across time by matching community labels between consecutive layers with the Hungarian (optimal linear-sum assignment) algorithm applied to the community overlap (contingency) matrix. This is a two-stage snapshot-and-match tracker: unlike the coupling-based fits (fit_multilayer_jaccard, fit_multilayer_overlap, fit_multilayer_identity_ties), communities are found per layer and aligned post hoc, not jointly optimised on a coupled supra-graph. It provides the common "independent detection + optimal label matching" baseline (e.g. per-layer Leiden matched with the Hungarian algorithm) as a first-class method with the same interface as the other fits.

Usage

fit_multilayer_hungarian(
  layers,
  algorithm = c("leiden", "louvain"),
  resolution_parameter = 1,
  directed = FALSE,
  objective = NULL,
  seed = 123,
  allow_unequal_nodes = FALSE
)

Arguments

Details

Matching is sequential: layer t is aligned to layer t-1. Nodes are matched across layers by vertex name when names are present (by position otherwise), so the order in which vertices are stored does not affect the result. For each adjacent pair the community overlap matrix is completed to a square cost matrix and solve_LSAP maximises total overlap; unmatched current communities receive fresh labels. The result is a consistently-labelled sequence suitable for extract_meta_membership, bootstrap_multilayer, and the plotting helpers.

Value

A list of class "multilayer_community_fit" with components:

layer_communities

Per-layer community detection (each with membership and communities), detected independently.

meta_communities

The tracked partition: one integer vector per layer where labels are aligned across consecutive layers by Hungarian matching on community overlap. A community with no positive-overlap match is given a new label (a birth); labels not carried forward are treated as deaths. See extract_meta_membership.

interlayer_ties

NULL - no coupled supra-graph is built.

method

"hungarian".

layer_links

Sequential adjacent-layer links (the chain the matcher walks).

See Also

fit_multilayer_jaccard, fit_multilayer_overlap, fit_multilayer_identity_ties for coupling-based tracking.

Examples

set.seed(123)
layers <- lapply(1:3, function(i) {
  m <- matrix(rbinom(64, 1, 0.35), nrow = 8)
  m <- pmax(m, t(m)); diag(m) <- 0; m
})
fit <- fit_multilayer_hungarian(layers, algorithm = "leiden")
extract_meta_membership(fit)

Fit multilayer communities with identity interlayer ties

Description

Runs Louvain or Leiden community detection for each layer and creates interlayer ties between the same node in selected adjacent layers. With allow_unequal_nodes = TRUE, layers may contain different node sets; only nodes present in both layers of a linked pair receive interlayer edges. Nodes are matched by V(g)$name when available, or by vertex index otherwise.

For this specification the cross-layer meta_communities are obtained by Mucha et al. (2010) multislice modularity: each layer keeps its own configuration null model (k_{is}k_{js}/2m_s), interlayer identity ties (each node to its copies in the coupled layers, weight = layer-link weight times omega) carry no null term, and the objective is optimised with a generalized Louvain (local moving + aggregation, random restarts). Versions before 1.2.1 ran plain single-graph modularity on the stacked supra-graph, which is a different objective and returns each layer as one community at omega <= 1.

Usage

fit_multilayer_identity_ties(
  layers,
  algorithm = c("leiden", "louvain"),
  layer_links = NULL,
  resolution_parameter = 1,
  omega = 1,
  directed = FALSE,
  objective = NULL,
  seed = 123,
  allow_unequal_nodes = FALSE
)

Arguments

Value

A list of class "multilayer_community_fit" with components:

layer_communities

Per-layer community detection (each with membership and communities). Detected independently per layer.

meta_communities

The cross-layer tracked partition from the second-stage detection: one integer vector per layer giving each node's meta-community. This is the membership that reflects the interlayer ties and any custom layer_links, and the one validated by bootstrap_multilayer. See extract_meta_membership.

interlayer_ties

Interlayer similarity edges between communities (plus self-loops).

layer_links

The layer connectivity used.

Directed networks

With directed = TRUE the multislice stage that produces meta_communities respects edge direction (Leicht and Newman's directed null model in each slice). A directed network in which every arc is reciprocated gives the same meta_communities as its undirected twin at the same omega; before version 1.3.2 such a network was fitted as if omega were halved. The first-stage layer_communities still collapse directed layers to weighted undirected graphs (igraph's detectors are undirected-only).

Examples

set.seed(123)
layers <- lapply(1:3, function(i) {
  m <- matrix(rbinom(64, 1, 0.35), nrow = 8)
  m <- pmax(m, t(m))
  diag(m) <- 0
  m
})
fit <- fit_multilayer_identity_ties(layers, algorithm = "louvain")
names(fit)

Fit multilayer communities and interlayer weighted Jaccard ties

Description

Runs Louvain or Leiden community detection for each layer and creates interlayer ties between communities in selected layer pairs using weighted Jaccard similarity.

Usage

fit_multilayer_jaccard(
  layers,
  algorithm = c("leiden", "louvain"),
  layer_links = NULL,
  min_similarity = 0,
  resolution_parameter = 1,
  directed = FALSE,
  add_self_loops = TRUE,
  self_loop_multiplier = 1,
  objective = NULL,
  seed = 123,
  allow_unequal_nodes = FALSE,
  tracking = "smoothed",
  repair_chains = FALSE,
  repair_min_similarity = 0.2
)

Arguments

Value

A list of class "multilayer_community_fit" with components:

layer_communities

Per-layer community detection (each with membership and communities). Detected independently per layer.

meta_communities

The cross-layer tracked partition from the second-stage detection: one integer vector per layer giving each node's meta-community. This is the membership that reflects the interlayer ties and any custom layer_links, and the one validated by bootstrap_multilayer. See extract_meta_membership.

interlayer_ties

Interlayer similarity edges between communities (plus self-loops).

layer_links

The layer connectivity used.

Directed networks

Directed layers are stored as directed graphs and the interlayer self-loop weighting is directed-aware, but community detection collapses directed layers to weighted undirected graphs on both Louvain and Leiden (igraph's detectors are undirected-only). For detection that respects edge direction, use the Python package with algorithm = "leiden".

Examples

set.seed(123)
layers <- lapply(1:3, function(i) {
  m <- matrix(rbinom(64, 1, 0.35), nrow = 8)
  m <- pmax(m, t(m))
  diag(m) <- 0
  m
})
fit <- fit_multilayer_jaccard(layers, algorithm = "louvain")
names(fit)
fit$layer_communities[[1]]$membership

Fit multilayer communities and interlayer weighted overlap ties

Description

Runs Louvain or Leiden community detection for each layer and creates interlayer ties between communities in selected layer pairs using a weighted overlap coefficient.

Usage

fit_multilayer_overlap(
  layers,
  algorithm = c("leiden", "louvain"),
  layer_links = NULL,
  min_similarity = 0,
  resolution_parameter = 1,
  directed = FALSE,
  add_self_loops = TRUE,
  self_loop_multiplier = 1,
  objective = NULL,
  seed = 123,
  allow_unequal_nodes = FALSE,
  tracking = "smoothed",
  repair_chains = FALSE,
  repair_min_similarity = 0.2
)

Arguments

Value

A list of class "multilayer_community_fit" with components:

layer_communities

Per-layer community detection (each with membership and communities). Detected independently per layer.

meta_communities

The cross-layer tracked partition from the second-stage detection: one integer vector per layer giving each node's meta-community. This is the membership that reflects the interlayer ties and any custom layer_links, and the one validated by bootstrap_multilayer. See extract_meta_membership.

interlayer_ties

Interlayer similarity edges between communities (plus self-loops).

layer_links

The layer connectivity used.

Directed networks

Directed layers are stored as directed graphs and the interlayer self-loop weighting is directed-aware, but community detection collapses directed layers to weighted undirected graphs on both Louvain and Leiden (igraph's detectors are undirected-only). For detection that respects edge direction, use the Python package with algorithm = "leiden".

Examples

set.seed(123)
layers <- lapply(1:3, function(i) {
  m <- matrix(rbinom(64, 1, 0.35), nrow = 8)
  m <- pmax(m, t(m))
  diag(m) <- 0
  m
})
fit <- fit_multilayer_overlap(layers, algorithm = "louvain")
names(fit)

Fit multilayer communities and interlayer node-strength weighted Jaccard ties

Description

Runs Louvain or Leiden community detection for each layer and creates interlayer ties between communities in selected layer pairs using node-strength weighted Jaccard similarity.

Usage

fit_multilayer_weighted_jaccard(
  layers,
  algorithm = c("leiden", "louvain"),
  layer_links = NULL,
  min_similarity = 0,
  resolution_parameter = 1,
  directed = FALSE,
  add_self_loops = TRUE,
  self_loop_multiplier = 1,
  objective = NULL,
  seed = 123,
  allow_unequal_nodes = FALSE,
  tracking = "smoothed",
  repair_chains = FALSE,
  repair_min_similarity = 0.2
)

Arguments

Value

A list of class "multilayer_community_fit" with components:

layer_communities

Per-layer community detection (each with membership and communities). Detected independently per layer.

meta_communities

The cross-layer tracked partition from the second-stage detection: one integer vector per layer giving each node's meta-community. This is the membership that reflects the interlayer ties and any custom layer_links, and the one validated by bootstrap_multilayer. See extract_meta_membership.

interlayer_ties

Interlayer similarity edges between communities (plus self-loops).

layer_links

The layer connectivity used.

Directed networks

Directed layers are stored as directed graphs and the interlayer self-loop weighting is directed-aware, but community detection collapses directed layers to weighted undirected graphs on both Louvain and Leiden (igraph's detectors are undirected-only). For detection that respects edge direction, use the Python package with algorithm = "leiden".

Examples

set.seed(123)
layers <- lapply(1:3, function(i) {
  w <- matrix(runif(64), 8, 8) * matrix(rbinom(64, 1, 0.35), 8, 8)
  w <- (w + t(w)) / 2
  diag(w) <- 0
  w
})
fit <- fit_multilayer_weighted_jaccard(layers, algorithm = "louvain")
names(fit)

Fit multilayer communities and interlayer node-strength weighted overlap ties

Description

Runs Louvain or Leiden community detection for each layer and creates interlayer ties between communities in selected layer pairs using node-strength weighted overlap coefficient.

Usage

fit_multilayer_weighted_overlap(
  layers,
  algorithm = c("leiden", "louvain"),
  layer_links = NULL,
  min_similarity = 0,
  resolution_parameter = 1,
  directed = FALSE,
  add_self_loops = TRUE,
  self_loop_multiplier = 1,
  objective = NULL,
  seed = 123,
  allow_unequal_nodes = FALSE,
  tracking = "smoothed",
  repair_chains = FALSE,
  repair_min_similarity = 0.2
)

Arguments

Value

A list of class "multilayer_community_fit" with components:

layer_communities

Per-layer community detection (each with membership and communities). Detected independently per layer.

meta_communities

The cross-layer tracked partition from the second-stage detection: one integer vector per layer giving each node's meta-community. This is the membership that reflects the interlayer ties and any custom layer_links, and the one validated by bootstrap_multilayer. See extract_meta_membership.

interlayer_ties

Interlayer similarity edges between communities (plus self-loops).

layer_links

The layer connectivity used.

Directed networks

Directed layers are stored as directed graphs and the interlayer self-loop weighting is directed-aware, but community detection collapses directed layers to weighted undirected graphs on both Louvain and Leiden (igraph's detectors are undirected-only). For detection that respects edge direction, use the Python package with algorithm = "leiden".

Examples

set.seed(123)
layers <- lapply(1:3, function(i) {
  w <- matrix(runif(64), 8, 8) * matrix(rbinom(64, 1, 0.35), 8, 8)
  w <- (w + t(w)) / 2
  diag(w) <- 0
  w
})
fit <- fit_multilayer_weighted_overlap(layers, algorithm = "louvain")
names(fit)

Build one weighted layer per time slice from group memberships

Description

Membership panels (states in IGOs, legislators in caucuses) are usually projected to a node-by-node network whose tie weight counts shared groups. layers_from_membership() builds that projection, or one of two size-aware alternatives, slice by slice, and returns layers that the fit_multilayer_* functions accept.

Let B be the N \times M 0/1 membership matrix of a slice and s_j the size of group j.

"count"

W = B B^\top (number of shared groups), diagonal 0.

"size"

W_{ik} = \sum_j B_{ij} B_{kj} / (s_j - 1), so each group adds total weight proportional to its size rather than its size squared.

"kumar"

Kumar et al.'s hypergraph reweighting (as in hypernetx 2.4.3). Group weights w_j start at 1; the slice is projected as in "size" with weights w_j and clustered with algorithm; each group gets the target r_j = [\sum_c 1/(1 + n_{jc})] (s_j + C) / M and w_j \leftarrow (w_j + r_j)/2, until \max_j |w_j - r_j|/2 \le tol. The projection with the final w_j is returned (the reference returns only the partition). The clustering calls the same per-layer routine as the fitters, so algorithm and resolution_parameter must be the ones you pass to the fitter.

Every slice is built on its own and reseeded with seed: the weights of slice t never depend on any other slice, so no later information enters an earlier layer.

No weighting is safe in general. In small Python simulations (hypotheses, not established results): the count projection failed badly when a few very large groups were present, where size-weighted and Kumar both recovered the planted blocs; Kumar beat size-weighting only under noise groups of the same size as real ones; under small groups bridging blocs, count was best and both size-aware weightings failed; and per-layer Louvain reproduced Kumar's own partition less reliably than Leiden.

Usage

layers_from_membership(
  memberships,
  weighting,
  algorithm = NULL,
  resolution_parameter = 1,
  seed = 123,
  max_iter = 50L,
  tol = 0.01,
  min_group_size = 2L,
  rescale = "none"
)

Arguments

Details

Projected ties are not independent across pairs (one group creates many ties), so the bootstrap stability score has not been checked for layers built this way.

Value

A list of weighted undirected igraph graphs, one per slice, with vertex names. Pass allow_unequal_nodes = TRUE to the fitter when node sets differ across slices. The graph attribute dm_membership holds weighting, group_weights (final w_j by group), iterations, final_diff, groups_dropped, rescale and partition (Kumar's final partition, a named integer vector; NULL otherwise).

Examples

m1 <- data.frame(node = c("a", "b", "c", "c", "d"), group = c("g1", "g1", "g1", "g2", "g2"))
m2 <- data.frame(node = c("a", "b", "b", "d"), group = c("g1", "g1", "g3", "g3"))
layers <- layers_from_membership(list(m1, m2), weighting = "size")
igraph::E(layers[[1]])$weight

Bootstrap stability score of a tracked partition

Description

Summarises a bootstrap_multilayer result into the stability score s: the mean agreement (NMI by default, or ARI) between each bootstrap replicate's meta-partition and the point-estimate meta-partition, averaged over layers and replicates. s is a point estimate with Monte Carlo standard error stability_mc_se. It has no validated mapping to accuracy: use it only to compare two fits of the same network (for example DynMux against multislice), never as an estimate of how accurate either fit is. Since 1.4.0 the package reports no interval or accuracy floor.

Usage

partition_stability(boot_result, metric = c("nmi", "ari"))

Arguments

Value

A list of class "partition_stability":

stability

Stability score s (mean over replicates and layers).

stability_by_layer

Per-layer mean agreement.

stability_mc_se

Monte Carlo standard error of s from the replicate spread.

metric

The agreement measure used.

report

One-sentence plain-language summary.

See Also

bootstrap_multilayer

Examples

set.seed(123)
layers <- lapply(1:3, function(i) {
  m <- matrix(rbinom(400, 1, 0.3), nrow = 20)
  m <- pmax(m, t(m)); diag(m) <- 0; m
})
boot <- bootstrap_multilayer(layers, fit_type = "jaccard",
                             algorithm = "leiden", n_boot = 10, seed = 123)
ps <- partition_stability(boot)
ps$stability; ps$report

Plot an alluvial view of community transitions over time

Description

Plot an alluvial view of community transitions over time

Usage

plot_multilayer_alluvial(fit, max_nodes = NULL, palette = "Dark2")

Arguments

Value

A ggplot object.

Examples

if (requireNamespace("ggplot2", quietly = TRUE) &&
    requireNamespace("ggalluvial", quietly = TRUE)) {
  set.seed(123)
  layers <- lapply(1:3, function(i) {
    m <- matrix(rbinom(64, 1, 0.35), nrow = 8)
    m <- pmax(m, t(m))
    diag(m) <- 0
    m
  })
  fit <- fit_multilayer_jaccard(layers, algorithm = "louvain")
  p <- plot_multilayer_alluvial(fit)
}

Plot multiplex networks as wrapped panels

Description

Draws one panel per layer with nodes colored by community assignment, using a faceted/wrapped layout.

Usage

plot_multilayer_series(
  layers,
  fit = NULL,
  community_memberships = NULL,
  directed = FALSE,
  layout = "layout_with_fr",
  ncol = 3,
  palette = "Dark2"
)

Arguments

Value

A ggplot object.

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  set.seed(123)
  layers <- lapply(1:3, function(i) {
    m <- matrix(rbinom(64, 1, 0.35), nrow = 8)
    m <- pmax(m, t(m))
    diag(m) <- 0
    m
  })
  fit <- fit_multilayer_jaccard(layers, algorithm = "louvain")
  p <- plot_multilayer_series(layers, fit = fit)
}

Simulate multiplex layers and fit interlayer models

Description

Generates synthetic multiplex network layers using a planted partition model, then fits one of the provided interlayer tie strategies.

Usage

simulate_and_fit_multilayer(
  n_nodes = 100,
  n_layers = 4,
  n_communities = 4,
  p_in = 0.2,
  p_out = 0.05,
  fit_type = c("jaccard", "overlap", "weighted_jaccard", "weighted_overlap", "identity"),
  algorithm = c("leiden", "louvain"),
  layer_links = NULL,
  min_similarity = 0,
  seed = NULL,
  directed = FALSE
)

Arguments

Value

A list containing simulated layers, true memberships, and fit results.

Examples

sim <- simulate_and_fit_multilayer(
  n_nodes = 30,
  n_layers = 3,
  n_communities = 3,
  fit_type = "jaccard",
  algorithm = "louvain",
  seed = 123
)
names(sim)