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
  )
}

Bootstrap confidence intervals for multilayer community detection

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.

Uncertainty is quantified 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("louvain", "leiden"),
  n_boot = 100,
  layer_links = NULL,
  min_similarity = 0,
  resolution_parameter = 1,
  directed = FALSE,
  seed = NULL,
  objective = NULL
)

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)

Descriptive Monte Carlo interval for node-pair co-assignment

Description

For every pair of nodes in every layer, returns the bootstrap co-assignment share (the fraction of replicates in which the pair landed in the same meta-community) with a Wilson score interval treating the replicates as binomial draws.

Read this interval as a diagnostic, not as a calibrated confidence interval. In the package's simulation study its width shrinks with the number of replicates while its coverage of the fresh-data co-assignment propensity was near nominal only for pairs whose share is close to 0 or 1 and fell to 0.03-0.15 for ambiguous pairs (share between 0.3 and 0.8). No conditioning or alternative bootstrap repaired this, so versions from 1.3.0 no longer offer a "calibrated" pair interval. The validated reliability product is partition_stability: a stability score for the tracked partition with a calibrated lower bound on its accuracy, plus a decided / undetermined flag for each pair.

Usage

co_assignment_ci(
  boot_result,
  alpha = 0.05,
  method = c("wilson", "calibrated"),
  calibration_table = NULL
)

Arguments

Value

A list with one element per layer. Each element is a list with components:

estimate

n x n matrix of co-assignment shares.

lower

n x n matrix of interval lower bounds.

upper

n x n matrix of interval upper bounds.

Diagonals are 1 by construction. The list carries the attribute "method".

See Also

partition_stability for the calibrated reliability score; community_est for community-count summaries.

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
)
pci <- co_assignment_ci(boot)
pci[[1]]$estimate[1:4, 1:4]

Summarize bootstrap community-count reproducibility (meta-communities)

Description

Reports, for each layer, the community count from the observed network together with its bootstrap reproducibility: the proportion of bootstrap replicates in which the fitted number of communities equals the observed-network count. It also returns mean node stability, per-node stability, and the co-assignment matrices.

Usage

community_est(boot_result)

Arguments

Value

A list with components:

community_count

Data frame with columns layer, estimate (the observed-network meta-community count), and reproducibility (share of bootstrap replicates whose community count equals estimate, in [0, 1]).

report

Character vector, one plain-language sentence per layer.

mean_node_stability

Data frame with columns layer, mean_stability.

node_stability

Per-layer stability vectors.

co_assignment

Per-layer co-assignment matrices.

Why this is not a confidence interval

Earlier versions returned a percentile community_count_ci. It was replaced in version 1.1.0 with a reproducibility summary because the interval's coverage is not robust to model misspecification. In a large simulation study the nominal 95 percent community-count interval covered the truth at or above the nominal level on well-specified planted-partition networks (about 0.99 for n >= 100 nodes), but coverage collapsed to about 0.62 when community sizes were strongly skewed, and no observable diagnostic reliably separated the trustworthy cases from the rest. Rather than ship an interval that silently undercovers, the function now reports how often the community count reproduces under resampling. This is a descriptive stability measure, not a calibrated interval: it makes no claim about the probability that any range contains the true community count. For a calibrated reliability measure use partition_stability, which bounds the accuracy of the tracked partition from below. The raw per-replicate community counts are intentionally not exposed anywhere in the package output; only this reproducibility summary is returned.

See Also

partition_stability for the calibrated reliability score of the tracked partition.

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
)
est <- community_est(boot)
est$community_count
est$report

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("louvain", "leiden"),
  resolution_parameter = 1,
  directed = FALSE,
  objective = NULL,
  seed = NULL
)

Arguments

Details

Matching is sequential: layer t is aligned to layer t-1. 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("louvain", "leiden"),
  layer_links = NULL,
  resolution_parameter = 1,
  omega = 1,
  directed = FALSE,
  objective = NULL,
  seed = NULL,
  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

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_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("louvain", "leiden"),
  layer_links = NULL,
  min_similarity = 0,
  resolution_parameter = 1,
  directed = FALSE,
  add_self_loops = TRUE,
  self_loop_multiplier = 1,
  objective = NULL,
  seed = NULL,
  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

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("louvain", "leiden"),
  layer_links = NULL,
  min_similarity = 0,
  resolution_parameter = 1,
  directed = FALSE,
  add_self_loops = TRUE,
  self_loop_multiplier = 1,
  objective = NULL,
  seed = NULL,
  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

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("louvain", "leiden"),
  layer_links = NULL,
  min_similarity = 0,
  resolution_parameter = 1,
  directed = FALSE,
  add_self_loops = TRUE,
  self_loop_multiplier = 1,
  objective = NULL,
  seed = NULL,
  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

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("louvain", "leiden"),
  layer_links = NULL,
  min_similarity = 0,
  resolution_parameter = 1,
  directed = FALSE,
  add_self_loops = TRUE,
  self_loop_multiplier = 1,
  objective = NULL,
  seed = NULL,
  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

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)

Stability score and calibrated accuracy floor for a tracked partition

Description

Summarises a bootstrap_multilayer result into one reliability report for the recovered (tracked) partition:

1. 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.

2. Accuracy floor: a calibrated lower bound on the accuracy of the point-estimate partition against the (unknown) truth. In the package's simulation study, fits were binned by s and the 5th percentile of accuracy (NMI or ARI to the planted partition) recorded in each bin on a calibration half of the configurations. On the held-out half, accuracy exceeded the floor in 95 percent of fits, in every bin. The floor is therefore read as "with this stability, partition accuracy was at least this value 95 percent of the time in calibration".

3. Node-level stability: per node, the mean Jaccard overlap between its replicate community and its point-estimate community, with a calibrated floor on node-level accuracy that is reported only above stability 0.9 (below that the floor is uninformative).

4. Decided pairs: per layer, node pairs whose bootstrap co-assignment share is below decided[1] (decidedly apart) or above decided[2] (decidedly together); everything in between is undetermined. No interval is attached to pairs: pair-level intervals were found not to be calibratable for ambiguous pairs.

The calibration is within the simulated family (planted-partition networks with node switching, sizes 50-400, 3-10 communities, 5-15 layers). On networks whose structure the planted-partition model does not describe, a stable but wrong partition could receive a floor it does not deserve; the accompanying paper reports the degree-corrected and weighted robustness arms.

Usage

partition_stability(
  boot_result,
  metric = c("nmi", "ari"),
  decided = c(0.1, 0.9),
  calibration_table = NULL
)

Arguments

Value

A list of class "partition_stability":

stability

Partition 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 (about 0.02 at 100 replicates).

floor

Calibrated 5th-percentile accuracy for the bin containing s; floor_median is the median accuracy in that bin.

bin

The stability bin used, as "[lo, hi)".

node

Per-layer data frames with node, stability (Jaccard) and floor (NA below 0.9).

pairs

Per-layer integer matrices: 1 = decidedly together, -1 = decidedly apart, 0 = undetermined; pair_summary gives the shares.

report

One-sentence plain-language summary.

See Also

bootstrap_multilayer, community_est

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$floor; 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("louvain", "leiden"),
  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)