Package {Nestimate}

Nestimate: Network Estimation, Bootstrap, and Higher-Order Analysis

Description

Estimate, compare, and analyze dynamic and psychological networks using a unified interface. Provides transition network analysis estimation (transition, frequency, co-occurrence, attention-weighted) Saqr et al. (2025) doi:10.1145/3706468.3706513, psychological network methods (correlation, partial correlation, 'graphical lasso', 'Ising') Saqr, Beck, and Lopez-Pernas (2024) doi:10.1007/978-3-031-54464-4_19, and higher-order network methods including higher-order networks, higher-order network embedding, hyper-path anomaly, and multi-order generative model. Supports bootstrap inference, permutation testing, split-half reliability, centrality stability analysis, mixed Markov models, multi-cluster multi-layer networks and clustering.

Author(s)

Maintainer: Mohammed Saqr saqr@saqr.me [copyright holder]

Authors:

• Sonsoles López-Pernas sonsoles.lopez@uef.fi

• Kamila Misiejuk kamila.misiejuk@fernuni-hagen.de

See Also

Useful links:

• https://github.com/mohsaqr/Nestimate

• https://saqr.me/Nestimate/

• Report bugs at https://github.com/mohsaqr/Nestimate/issues

Auto-detect clusters from netobject

Description

Auto-detect clusters from netobject

Usage

.auto_detect_clusters(x)

Build node-to-cluster lookup from cluster specification

Description

Build node-to-cluster lookup from cluster specification

Usage

.build_cluster_lookup(clusters, all_nodes)

Build cluster_summary from transition vectors

Description

Build cluster_summary from transition vectors

Usage

.build_from_transitions(
  from_nodes,
  to_nodes,
  weights,
  cluster_lookup,
  cluster_list,
  method,
  type,
  directed,
  compute_within,
  data = NULL
)

Build MCML from edge list data.frame

Description

Build MCML from edge list data.frame

Usage

.build_mcml_edgelist(df, clusters, method, type, directed, compute_within)

Build MCML from sequence data.frame

Description

Build MCML from sequence data.frame

Usage

.build_mcml_sequence(df, clusters, method, type, directed, compute_within)

Detect input type for build_mcml

Description

Detect input type for build_mcml

Usage

.detect_mcml_input(x)

Process weights based on type

Description

Process weights based on type

Usage

.process_weights(raw_weights, type, directed = TRUE)

Convert Action Column to One-Hot Encoding

Description

Convert a categorical Action column to one-hot (binary indicator) columns.

Usage

action_to_onehot(
  data,
  action_col = "Action",
  states = NULL,
  drop_action = TRUE,
  sort_states = FALSE,
  prefix = ""
)

Arguments

Value

Data frame with one-hot encoded columns (0/1 integers).

Examples

long_data <- data.frame(
  Actor = rep(1:3, each = 4),
  Time = rep(1:4, 3),
  Action = sample(c("A", "B", "C"), 12, replace = TRUE)
)
onehot_data <- action_to_onehot(long_data)
head(onehot_data)

Tidy per-actor endpoint summary of a wide-format sequence dataset.

Description

For each actor (row), reports the first and last observed states, the time indices at which they appear, the number of observed steps, and a dropped_out flag that is TRUE when the actor has a terminal-NA pattern (after the final observed step, every remaining cell is NA).

Usage

actor_endpoints(data, cols = NULL)

Arguments

Value

A tidy data.frame with one row per actor and columns:

actor

Row number (or row name if present).

first_state

First non-NA state.

last_state

Last non-NA state.

first_step

Column index of the first observed state.

last_step

Column index of the last observed state.

n_observed

Number of non-NA cells.

dropped_out

TRUE iff every cell after last_step is NA and last_step < ncol(data).

See Also

mark_terminal_state(), chain_structure()

Examples

actor_endpoints(trajectories) |> head()

Convert cluster_summary to tna Objects

Description

Converts a cluster_summary object to proper tna objects that can be used with all functions from the tna package. Creates both a between-cluster tna model (cluster-level transitions) and within-cluster tna models (internal transitions within each cluster).

Usage

as_tna(x)

## S3 method for class 'mcml'
as_tna(x)

## Default S3 method:
as_tna(x)

Arguments

Details

This is the final step in the MCML workflow, enabling full integration with the tna package for centrality analysis, bootstrap validation, permutation tests, and visualization.

Requirements

The tna package must be installed. If not available, the function throws an error with installation instructions.

Workflow

# Full MCML workflow
net <- build_network(data, method = "relative")
net$nodes$clusters <- group_assignments
cs <- cluster_summary(net)
tna_models <- as_tna(cs)

# Now use tna package functions
plot(tna_models$macro)
tna::centralities(tna_models$macro)
tna::bootstrap(tna_models$macro, iter = 1000)

# Analyze within-cluster patterns
plot(tna_models$clusters$ClusterA)
tna::centralities(tna_models$clusters$ClusterA)

Excluded Clusters

A within-cluster network is dropped only when row-normalisation would fail. Specifically, when the recorded net_method is "relative" (row-stochastic transitions) and any node in the cluster has zero outgoing weight, that cluster is excluded from $clusters and a warning() is emitted listing the dropped cluster names. For net_method = "frequency" (raw counts), a zero-row node is a legitimate sink and the cluster is retained. The macro / between-cluster network always includes every cluster regardless of the per-cluster drop decisions.

If a cluster you expect to see is missing from the returned $clusters, check the warning output and consider building with type = "raw" (which carries through to a frequency-method netobject and skips the drop) or inspect rowSums(x$clusters[[cl]]$weights).

Value

A cluster_tna object (S3 class) containing:

between

A tna object representing cluster-level transitions. Contains $weights (k x k transition matrix), $inits (initial distribution), and $labels (cluster names). Use this for analyzing how learners/entities move between high-level groups or phases.

within

Named list of tna objects, one per cluster. Each tna object represents internal transitions within that cluster. Contains $weights (n_i x n_i matrix), $inits (initial distribution), and $labels (node labels). Clusters with single nodes or zero-row nodes are excluded (tna requires positive row sums).

A netobject_group with data preserved from each sub-network.

A tna object constructed from the input.

See Also

cluster_summary to create the input object, plot() for visualization without conversion, tna::tna for the underlying tna constructor

Examples

mat <- matrix(runif(36), 6, 6)
rownames(mat) <- colnames(mat) <- LETTERS[1:6]
clusters <- list(G1 = c("A", "B"), G2 = c("C", "D"), G3 = c("E", "F"))
cs <- cluster_summary(mat, clusters)
tna_models <- as_tna(cs)
tna_models
tna_models$macro$weights

Discover Association Rules from Sequential or Transaction Data

Description

Discovers association rules using the Apriori algorithm with proper candidate pruning. Accepts netobject (extracts sequences as transactions), data frames, lists, or binary matrices.

Support counting is vectorized via crossprod() for 2-itemsets and logical matrix indexing for k-itemsets.

Usage

association_rules(
  x,
  min_support = 0.1,
  min_confidence = 0.5,
  min_lift = 1,
  max_length = 5L
)

Arguments

Details

Algorithm

Uses level-wise Apriori (Agrawal & Srikant, 1994) with the full pruning step: after the join step generates k-candidates, all (k-1)-subsets are verified as frequent before support counting. This is critical for efficiency at k >= 4.

Metrics

support

P(A and B). Fraction of transactions containing both antecedent and consequent.

confidence

P(B | A). Fraction of antecedent transactions that also contain the consequent.

lift

P(A and B) / (P(A) * P(B)). Values > 1 indicate positive association; < 1 indicate negative association.

conviction

(1 - P(B)) / (1 - confidence). Measures departure from independence. Higher = stronger implication.

Value

An object of class "net_association_rules" containing:

rules

Data frame with columns: antecedent (list), consequent (list), support, confidence, lift, conviction, count, n_transactions.

frequent_itemsets

List of frequent itemsets per level k.

items

Character vector of all items.

n_transactions

Integer.

n_rules

Integer.

params

List of min_support, min_confidence, min_lift, max_length.

References

Agrawal, R. & Srikant, R. (1994). Fast algorithms for mining association rules. In Proc. 20th VLDB Conference, 487–499.

See Also

build_network, predict_links

Examples

# From a list of transactions
trans <- list(
  c("plan", "discuss", "execute"),
  c("plan", "research", "analyze"),
  c("discuss", "execute", "reflect"),
  c("plan", "discuss", "execute", "reflect"),
  c("research", "analyze", "reflect")
)
rules <- association_rules(trans, min_support = 0.3, min_confidence = 0.5)
print(rules)

# From a netobject (sequences as transactions)
seqs <- data.frame(
  V1 = sample(LETTERS[1:5], 50, TRUE),
  V2 = sample(LETTERS[1:5], 50, TRUE),
  V3 = sample(LETTERS[1:5], 50, TRUE)
)
net <- build_network(seqs, method = "relative")
rules <- association_rules(net, min_support = 0.1)

Betti Numbers

Description

Computes Betti numbers: \beta_0 (components), \beta_1 (loops), \beta_2 (voids), etc.

Usage

betti_numbers(sc)

Arguments

Value

Named integer vector c(b0 = ..., b1 = ..., ...).

Examples

mat <- matrix(c(0,.6,.5,.6,0,.4,.5,.4,0), 3, 3)
colnames(mat) <- rownames(mat) <- c("A","B","C")
sc <- build_simplicial(mat, threshold = 0.3)
betti_numbers(sc)

Hypergraph from bipartite group / event data

Description

Constructs a net_hypergraph from long-format event data in which each row records a player participating in a group (a session, team, project, transaction, or any group context). Each unique group becomes one hyperedge spanning the players that appeared in it. Optional weight column produces a weighted incidence matrix.

Usage

bipartite_groups(data, player, group, weight = NULL)

Arguments

Details

The bipartite representation preserves the full group structure without projecting to a pairwise network. A group of three players A, B, C produces a single 3-hyperedge containing all three, not three pairwise edges AB, AC, BC. This avoids information loss when group interactions are the primary unit of analysis (Perc et al. 2013).

Unlike build_hypergraph() (which derives hyperedges from a network's clique structure), bipartite_groups() takes group memberships directly. The two functions are complementary:

• bipartite_groups() — when group membership is observed (sessions, transactions, co-authorships).

• build_hypergraph() — when only pairwise interactions are observed and triadic structure must be inferred from triangles.

Rows with NA in either the player or group column (or, when supplied, the weight column) are dropped silently.

Value

A net_hypergraph object with the same structure produced by build_hypergraph() (hyperedges, incidence, nodes, n_nodes, n_hyperedges, size_distribution, params). The params list records source = "bipartite_groups" and the original column names.

Note

(experimental) Validated against a hand-computed table() incidence reference only; no independent R package exposes the long-format-to-binary-incidence primitive, because the operation is definitionally table(). The code path is a direct one-to-one restatement of its definition.

References

Perc, M., Gomez-Gardenes, J., Szolnoki, A., Floria, L. M., & Moreno, Y. (2013). Evolutionary dynamics of group interactions on structured populations: a review. Journal of the Royal Society Interface 10(80), 20120997. doi:10.1098/rsif.2012.0997

See Also

build_hypergraph() for the clique-based constructor.

Examples

df <- data.frame(
  player = c("Alice", "Bob", "Carol", "Alice", "Bob",
             "Dave", "Carol", "Dave", "Eve"),
  session = c("S1", "S1", "S1", "S2", "S2",
              "S3", "S3", "S3", "S3")
)
hg <- bipartite_groups(df, player = "player", group = "session")
print(hg)
summary(hg)

Bootstrap for Regularized Partial Correlation Networks

Description

Fast, single-call bootstrap for EBICglasso partial correlation networks. Combines nonparametric edge/centrality bootstrap, case-dropping stability analysis, edge/centrality difference tests, predictability CIs, and thresholded network into one function. Designed as a faster alternative to bootnet with richer output.

Usage

boot_glasso(
  x,
  iter = 1000L,
  cs_iter = 500L,
  cs_drop = seq(0.1, 0.9, by = 0.1),
  alpha = 0.05,
  gamma = 0.5,
  nlambda = 100L,
  centrality = c("strength", "expected_influence", "betweenness", "closeness"),
  centrality_fn = NULL,
  cor_method = "pearson",
  ncores = 1L,
  seed = NULL
)

Arguments

Value

An object of class "boot_glasso" containing:

original_pcor

Original partial correlation matrix.

original_precision

Original precision matrix.

original_centrality

Named list of original centrality vectors.

original_predictability

Named numeric vector of node R-squared.

edge_ci

Data frame of edge CIs (edge, weight, ci_lower, ci_upper, inclusion).

edge_inclusion

Named numeric vector of edge inclusion probabilities.

thresholded_pcor

Partial correlation matrix with non-significant edges zeroed.

centrality_ci

Named list of data frames (node, value, ci_lower, ci_upper) per centrality measure.

cs_coefficient

Named numeric vector of CS-coefficients per centrality measure.

cs_data

Data frame of case-dropping correlations (drop_prop, measure, correlation).

edge_diff_p

Symmetric matrix of pairwise edge difference p-values.

centrality_diff_p

Named list of symmetric p-value matrices per centrality measure.

predictability_ci

Data frame of node predictability CIs (node, r2, ci_lower, ci_upper).

boot_edges

iter x n_edges matrix of bootstrap edge weights.

boot_centrality

Named list of iter x p bootstrap centrality matrices.

boot_predictability

iter x p matrix of bootstrap R-squared.

nodes

Character vector of node names.

n

Sample size.

p

Number of variables.

iter

Number of nonparametric iterations.

cs_iter

Number of case-dropping iterations.

cs_drop

Drop proportions used.

alpha

Significance level.

gamma

EBIC hyperparameter.

nlambda

Lambda path length.

centrality_measures

Character vector of centrality measures.

cor_method

Correlation method.

lambda_path

Lambda sequence used.

lambda_selected

Selected lambda for original data.

timing

Named numeric vector with timing in seconds.

See Also

build_network, bootstrap_network

Examples

set.seed(1)
dat <- as.data.frame(matrix(rnorm(60), ncol = 3))
net <- build_network(dat, method = "glasso")
bg <- boot_glasso(net, iter = 10, cs_iter = 5, centrality = "strength")

set.seed(42)
mat <- matrix(rnorm(60), ncol = 4)
colnames(mat) <- LETTERS[1:4]
net <- build_network(as.data.frame(mat), method = "glasso")
boot <- boot_glasso(net, iter = 100, cs_iter = 50, seed = 42,
  centrality = c("strength", "expected_influence"))
print(boot)
summary(boot, type = "edges")

Bootstrap a Network Estimate

Description

Non-parametric bootstrap for any network estimated by build_network. Works with all built-in methods (transition and association) as well as custom registered estimators.

For transition methods ("relative", "frequency", "co_occurrence"), uses a fast pre-computation strategy: per-sequence count matrices are computed once, and each bootstrap iteration only resamples sequences via colSums (C-level) plus lightweight post-processing. Data must be in wide format for transition bootstrap; use convert_sequence_format to convert long-format data first.

For association methods ("cor", "pcor", "glasso", and custom estimators), the full estimator is called on resampled rows each iteration.

If a transition network contains only one sequence, the function warns that such a network is not recommended for bootstrap or other confirmatory testing.

Usage

bootstrap_network(
  x,
  iter = 1000L,
  ci_level = 0.05,
  inference = "stability",
  consistency_range = c(0.75, 1.25),
  edge_threshold = NULL,
  seed = NULL,
  boundary = c("inclusive", "strict")
)

Arguments

Value

An object of class "net_bootstrap" containing:

original

The original netobject.

mean

Bootstrap mean weight matrix.

sd

Bootstrap SD matrix.

p_values

P-value matrix.

significant

Original weights where p < ci_level, else 0.

ci_lower

Lower CI bound matrix.

ci_upper

Upper CI bound matrix.

cr_lower

Consistency range lower bound (stability only).

cr_upper

Consistency range upper bound (stability only).

summary

Long-format data frame of edge-level statistics.

model

Pruned netobject (non-significant edges zeroed).

method, params, iter, ci_level, inference

Bootstrap config.

consistency_range, edge_threshold

Inference parameters.

See Also

build_network, print.net_bootstrap, summary.net_bootstrap

Examples

net <- build_network(data.frame(V1 = c("A","B","C"), V2 = c("B","C","A")),
  method = "relative")
boot <- bootstrap_network(net, iter = 10)

seqs <- data.frame(
  V1 = sample(LETTERS[1:4], 30, TRUE), V2 = sample(LETTERS[1:4], 30, TRUE),
  V3 = sample(LETTERS[1:4], 30, TRUE), V4 = sample(LETTERS[1:4], 30, TRUE)
)
net <- build_network(seqs, method = "relative")
boot <- bootstrap_network(net, iter = 100)
print(boot)
summary(boot)

Bottleneck Distance Between Persistence Diagrams

Description

Computes the bottleneck distance between two persistence diagrams. For finite pairs, the bottleneck distance is

W_\infty(D_1, D_2) = \inf_{\gamma} \sup_{p \in D_1} \|p - \gamma(p)\|_\infty,

where \gamma ranges over bijections D_1 \cup \Delta \to D_2 \cup \Delta and \Delta = \{(x,x)\} is the diagonal. Each point may match a point in the other diagram or its projection onto the diagonal at cost |d - b|/2. Computed via binary search on \varepsilon plus a Kuhn bipartite-matching feasibility check.

Essential classes (death = Inf in VR mode, or death = 0 in clique mode) are matched one-to-one within each dimension. If the diagrams have different numbers of essential classes in some dimension, the bottleneck distance for that dimension is Inf.

Usage

bottleneck_distance(d1, d2, dimension = NULL, tol = .Machine$double.eps^0.5)

Arguments

Value

Named numeric vector. Names are "dim_<k>". Inf indicates a structural mismatch (different essential counts in that dimension); a self-distance is always 0.

References

Edelsbrunner, H. & Harer, J. (2010). Computational Topology: An Introduction. AMS. Section VIII.

Examples

mat1 <- matrix(c(0, .6, .5, .6, 0, .4, .5, .4, 0), 3, 3)
rownames(mat1) <- colnames(mat1) <- c("A","B","C")
ph1 <- persistent_homology(mat1, n_steps = 5)
bottleneck_distance(ph1, ph1)  # self-distance is 0

Build an Attention-Weighted Transition Network (ATNA)

Description

Convenience wrapper for build_network(method = "attention"). Computes decay-weighted transitions from sequence data.

Usage

build_atna(data, ...)

Arguments

Value

A netobject (see build_network).

See Also

build_network

Examples

seqs <- data.frame(V1 = c("A","B","C"), V2 = c("B","C","A"))
net <- build_atna(seqs)

Cluster Sequences by Dissimilarity

Description

Clusters wide-format sequences using pairwise string dissimilarity and either PAM (Partitioning Around Medoids) or hierarchical clustering. Supports 9 distance metrics including temporal weighting for Hamming distance. When the stringdist package is available, uses C-level distance computation for 100-1000x speedup on edit distances.

Usage

build_clusters(
  data,
  k,
  dissimilarity = "hamming",
  method = "pam",
  na_syms = c("*", "%"),
  weighted = FALSE,
  lambda = 1,
  seed = NULL,
  q = 2L,
  p = 0.1,
  covariates = NULL,
  estimator = c("auto", "firth", "multinom", "chisq"),
  ...
)

Arguments

Value

An object of class "net_clustering" containing:

data

The original input data.

k

Number of clusters.

assignments

Named integer vector of cluster assignments.

silhouette

Overall average silhouette width.

sizes

Named integer vector of cluster sizes.

method

Clustering method used.

dissimilarity

Distance metric used.

distance

The computed dissimilarity matrix (dist object).

medoids

Integer vector of medoid row indices (PAM only; NULL for hierarchical methods).

seed

Seed used (or NULL).

weighted

Logical, whether weighted Hamming was used.

lambda

Lambda value used (0 if not weighted).

Examples

seqs <- data.frame(V1 = c("A","B","C","A","B"), V2 = c("B","C","A","B","A"),
                   V3 = c("C","A","B","C","B"))
cl <- build_clusters(seqs, k = 2)
cl

seqs <- data.frame(
  V1 = sample(LETTERS[1:3], 20, TRUE), V2 = sample(LETTERS[1:3], 20, TRUE),
  V3 = sample(LETTERS[1:3], 20, TRUE), V4 = sample(LETTERS[1:3], 20, TRUE)
)
cl <- build_clusters(seqs, k = 2)
print(cl)
summary(cl)

Build a Co-occurrence Network (CNA)

Description

Convenience wrapper for build_network(method = "co_occurrence"). Computes co-occurrence counts from binary or sequence data.

Usage

build_cna(data, ...)

Arguments

Value

A netobject (see build_network).

See Also

build_network, cooccurrence for delimited-field, bipartite, and other non-sequence co-occurrence formats.

Examples

seqs <- data.frame(V1 = c("A","B","C"), V2 = c("B","C","A"))
net <- build_cna(seqs)

Build a Correlation Network

Description

Convenience wrapper for build_network(method = "cor"). Computes Pearson correlations from numeric data.

Usage

build_cor(data, ...)

Arguments

Value

A netobject (see build_network).

See Also

build_network

Examples

data(srl_strategies)
net <- build_cor(srl_strategies)

Build a Frequency Transition Network (FTNA)

Description

Convenience wrapper for build_network(method = "frequency"). Computes raw transition counts from sequence data.

Usage

build_ftna(data, ...)

Arguments

Value

A netobject (see build_network).

See Also

build_network

Examples

seqs <- data.frame(V1 = c("A","B","C"), V2 = c("B","C","A"))
net <- build_ftna(seqs)

GIMME: Group Iterative Multiple Model Estimation

Description

Estimates person-specific directed networks from intensive longitudinal data using the unified Structural Equation Modeling (uSEM) framework. Implements a data-driven search that identifies:

1. Group-level paths: Directed edges present for a majority (default 75\

2. Individual-level paths: Additional edges specific to each person, found after group paths are established.

Uses lavaan for SEM estimation and modification indices. Accepts a single data frame with an ID column (not CSV directories).

Usage

build_gimme(
  data,
  vars,
  id,
  time = NULL,
  ar = TRUE,
  standardize = FALSE,
  groupcutoff = 0.75,
  subcutoff = 0.5,
  paths = NULL,
  exogenous = NULL,
  hybrid = FALSE,
  rmsea_cutoff = 0.05,
  srmr_cutoff = 0.05,
  nnfi_cutoff = 0.95,
  cfi_cutoff = 0.95,
  n_excellent = 2L,
  seed = NULL
)

Arguments

Value

An S3 object of class "net_gimme" containing:

temporal

p x p matrix of group-level temporal (lagged) path counts – entry [i,j] = number of individuals with path j(t-1)->i(t).

contemporaneous

p x p matrix of group-level contemporaneous path counts – entry [i,j] = number of individuals with path j(t)->i(t).

coefs

List of per-person p x 2p coefficient matrices (rows = endogenous, cols = [lagged, contemporaneous]).

psi

List of per-person residual covariance matrices.

fit

Data frame of per-person fit indices (chisq, df, pvalue, rmsea, srmr, nnfi, cfi, bic, aic, logl, status).

path_counts

p x 2p matrix: how many individuals have each path.

paths

List of per-person character vectors of lavaan path syntax.

group_paths

Character vector of group-level paths found.

individual_paths

List of per-person character vectors of individual-level paths (beyond group).

syntax

List of per-person full lavaan syntax strings.

labels

Character vector of variable names.

n_subjects

Integer. Number of individuals.

n_obs

Integer vector. Time points per individual.

config

List of configuration parameters.

See Also

build_network

Examples

# Create simple panel data (3 subjects, 4 variables, 50 time points).
set.seed(42)
n_sub <- 3; n_t <- 50; vars <- paste0("V", 1:4)
rows <- lapply(seq_len(n_sub), function(i) {
  d <- as.data.frame(matrix(rnorm(n_t * 4), ncol = 4))
  names(d) <- vars; d$id <- i; d
})
panel <- do.call(rbind, rows)
res <- build_gimme(panel, vars = vars, id = "id")
print(res)

Build a Graphical Lasso Network (EBICglasso)

Description

Convenience wrapper for build_network(method = "glasso"). Computes L1-regularized partial correlations with EBIC model selection.

Usage

build_glasso(data, ...)

Arguments

Value

A netobject (see build_network).

See Also

build_network

Examples

data(srl_strategies)
net <- build_glasso(srl_strategies)

Build a Higher-Order Network (HON)

Description

Constructs a Higher-Order Network from sequential data, faithfully implementing the BuildHON algorithm (Xu, Wickramarathne & Chawla, 2016).

The algorithm detects when a first-order Markov model is insufficient to capture sequential dependencies and automatically creates higher-order nodes. Uses KL-divergence to determine whether extending a node's history provides significantly different transition distributions.

Usage

build_hon(
  data,
  max_order = 5L,
  min_freq = 1L,
  collapse_repeats = FALSE,
  method = "hon+"
)

Arguments

Details

Node naming convention: Higher-order nodes use readable arrow notation. A first-order node is simply "A". A second-order node representing the context "came from A, now at B" is "A -> B". Third-order: "A -> B -> C", etc.

Algorithm overview:

1. Count all subsequence transitions up to max_order + 1.

2. Build probability distributions, filtering by min_freq.

3. For each first-order source, recursively test whether extending the history (adding more context) produces a significantly different distribution (via KL-divergence vs. an adaptive threshold).

4. Build the network from the accepted rules, rewiring edges so higher-order nodes are properly connected.

Value

An S3 object of class "net_hon" containing:

matrix

Weighted adjacency matrix (rows = from, cols = to). Rows and columns use readable arrow notation (e.g., "A -> B").

edges

Data frame with columns: path (full state sequence, e.g., "A -> B -> C"), from (context/conditioning states), to (predicted next state), count (raw frequency), probability (transition probability), from_order, to_order.

nodes

data.frame with columns id, label, name (one row per HON node; label/name are the arrow-notation node names). Stored as a data.frame for cograph_network compatibility.

n_nodes

Number of HON nodes.

n_edges

Number of edges.

first_order_states

Character vector of unique original states.

max_order_requested

The max_order parameter used.

max_order_observed

Highest order actually present.

min_freq

The min_freq parameter used.

n_trajectories

Number of trajectories after parsing.

directed

Logical. Always TRUE.

References

Xu, J., Wickramarathne, T. L., & Chawla, N. V. (2016). Representing higher-order dependencies in networks. Science Advances, 2(5), e1600028.

Saebi, M., Xu, J., Kaplan, L. M., Ribeiro, B., & Chawla, N. V. (2020). Efficient modeling of higher-order dependencies in networks: from algorithm to application for anomaly detection. EPJ Data Science, 9(1), 15.

Examples

seqs <- list(c("A","B","C","D"), c("A","B","C","A"), c("B","C","D","A"))
hon <- build_hon(seqs, max_order = 2)


# From list of trajectories
trajs <- list(
  c("A", "B", "C", "D", "A"),
  c("A", "B", "D", "C", "A"),
  c("A", "B", "C", "D", "A")
)
hon <- build_hon(trajs, max_order = 3, min_freq = 1)
print(hon)
summary(hon)

# From data.frame (rows = trajectories)
df <- data.frame(T1 = c("A", "A"), T2 = c("B", "B"),
                 T3 = c("C", "D"), T4 = c("D", "C"))
hon <- build_hon(df, max_order = 2)

Build HONEM Embeddings for Higher-Order Networks

Description

Constructs low-dimensional embeddings from a Higher-Order Network (HON) that preserve higher-order dependencies. Uses exponentially-decaying matrix powers of the HON transition matrix followed by truncated SVD.

Usage

build_honem(hon, dim = 32L, max_power = 10L)

Arguments

Details

HONEM is parameter-free and scalable — no random walks, skip-gram, or hyperparameter tuning required.

Value

An object of class net_honem with components:

embeddings

Numeric matrix (n_nodes x dim) of node embeddings.

nodes

Character vector of node names.

singular_values

Numeric vector of top singular values.

explained_variance

Proportion of variance explained.

dim

Embedding dimension used.

max_power

Maximum power used.

n_nodes

Number of nodes embedded.

References

Saebi, M., Ciampaglia, G. L., Kazemzadeh, S., & Meyur, R. (2020). HONEM: Learning Embedding for Higher Order Networks. Big Data, 8(4), 255–269.

Examples

seqs <- list(c("A","B","C","D"), c("A","B","C","A"), c("B","C","D","A"))
hem <- build_honem(build_hon(seqs, max_order = 2), dim = 2)


trajs <- list(c("A","B","C","D"), c("A","B","D","C"),
              c("B","C","D","A"), c("C","D","A","B"))
hon <- build_hon(trajs, max_order = 2)
emb <- build_honem(hon, dim = 4)
print(emb)
plot(emb)

Detect Path Anomalies via HYPA

Description

Constructs a k-th order De Bruijn graph from sequential trajectory data and uses a hypergeometric null model to detect paths with anomalous frequencies. Paths occurring more or less often than expected under the null model are flagged as over- or under-represented.

Usage

build_hypa(
  data,
  order = 2L,
  alpha = 0.05,
  min_count = 5L,
  p_adjust = "BH",
  k = NULL
)

Arguments

Value

An object of class c("net_hypa", "cograph_network") with components:

scores

Data frame with path, from, to, observed, expected, ratio, p_value, p_under, p_over, p_adjusted_under, p_adjusted_over, anomaly, order columns (one block of rows per requested order). The path column shows the full state sequence (e.g., "A -> B -> C"); from is the context (conditioning states); to is the next state; ratio is observed / expected; p_value is retained as an alias for p_under, the raw lower-tail hypergeometric CDF value; p_over is the inclusive upper-tail probability P(X >= observed); p_adjusted_under and p_adjusted_over are the corrected p-values for under- and over-representation tests respectively.

ho_edges

Alias for scores (all orders, arrow notation).

over

Subset of scores classified as over-represented.

under

Subset of scores classified as under-represented.

adjacency

Weighted adjacency matrix of the lowest-order De Bruijn graph.

weights

cograph weight matrix of the lowest-order graph.

xi

Fitted propensity matrix of the lowest-order graph.

edges

cograph edge data.frame of the lowest-order graph.

by_order

Named list of per-order result lists.

order

Integer vector of orders actually built (sorted ascending).

k

Back-compatibility alias for order.

alpha

Significance threshold used.

p_adjust

Multiple testing correction method used.

n_anomalous

Number of anomalous paths detected (all orders).

n_over

Number of over-represented paths (all orders).

n_under

Number of under-represented paths (all orders).

n_edges

Total number of edges (all orders).

nodes

data.frame (id, label, name) of the lowest-order De Bruijn graph nodes (arrow notation).

directed

Logical. Always TRUE.

meta

cograph meta list of the lowest-order graph.

node_groups

Always NULL.

References

LaRock, T., Nanumyan, V., Scholtes, I., Casiraghi, G., Eliassi-Rad, T., & Schweitzer, F. (2020). HYPA: Efficient Detection of Path Anomalies in Time Series Data on Networks. SDM 2020, 460-468.

Examples

seqs <- list(c("A","B","C"), c("B","C","A"), c("A","C","B"), c("A","B","C"))
hyp <- build_hypa(seqs, order = 2)


trajs <- list(c("A","B","C"), c("A","B","C"), c("A","B","C"),
              c("A","B","D"), c("C","B","D"), c("C","B","A"))
h <- build_hypa(trajs, order = 2)
print(h)

Higher-order hypergraph from a network's clique structure

Description

Takes a network and produces a hypergraph by promoting k-cliques (k >= 3) to k-hyperedges. Each k-clique is independently included as a k-hyperedge with probability p. Optionally retains the underlying pairwise edges as 2-hyperedges. Foundation for higher-order analyses.

Usage

build_hypergraph(
  net,
  p = 1,
  method = c("clique", "vr", "rips"),
  include_pairwise = TRUE,
  max_size = 3L,
  threshold = 0,
  seed = NULL
)

## S3 method for class 'net_hypergraph'
print(x, ...)

## S3 method for class 'net_hypergraph'
summary(object, ...)

Arguments

Details

The construction follows Burgio, Matamalas, Gomez & Arenas (2020) on simplicial / hypergraph contagion. For each k-clique with k >= 3 found in the underlying graph (via build_simplicial()), an independent Bernoulli(p) trial decides whether that clique becomes a k-hyperedge. Underlying pairwise edges are always retained when include_pairwise = TRUE, so the resulting hypergraph contains both the original 2-edge structure and the sampled higher-order interactions.

At the limits:

• p = 0 with include_pairwise = TRUE reproduces the input pairwise network as a hypergraph of size-2 edges.

• p = 1 with include_pairwise = FALSE returns a fully higher-order hypergraph containing only the k-hyperedges (k >= 3) found in the network's clique complex.

Value

A net_hypergraph object: a list with components

hyperedges

List of integer vectors. Each entry is a hyperedge given as the sorted node indices it spans.

incidence

Numeric matrix of size n_nodes x n_hyperedges. incidence[i, j] = 1 iff node i belongs to hyperedge j. Row names are node names; column names are h1, h2, ...

nodes

Character vector of node names.

n_nodes, n_hyperedges

Scalar counts.

size_distribution

Named integer vector: number of hyperedges of each size, named size_2, size_3, ...

params

Recorded call parameters: method, p, include_pairwise, max_size, threshold, seed.

The input x invisibly.

The input object invisibly.

References

Burgio, G., Matamalas, J. T., Gomez, S., & Arenas, A. (2020). Evolution of cooperation in the presence of higher-order interactions: from networks to hypergraphs. Entropy 22(7), 744. doi:10.3390/e22070744

See Also

build_simplicial() (underlying clique enumeration), build_network().

Examples

set.seed(1)
n <- 8
adj <- matrix(stats::rbinom(n * n, 1, 0.5), n, n)
diag(adj) <- 0
adj <- (adj + t(adj)) > 0
rownames(adj) <- colnames(adj) <- LETTERS[seq_len(n)]
hg <- build_hypergraph(adj, p = 1, max_size = 3L)
print(hg)
summary(hg)

Build an Ising Network

Description

Convenience wrapper for build_network(method = "ising"). Computes L1-regularized logistic regression network for binary data.

Usage

build_ising(data, ...)

Arguments

Value

A netobject (see build_network).

See Also

build_network

Examples

if (requireNamespace("glmnet", quietly = TRUE)) {
  bin_data <- data.frame(matrix(rbinom(200, 1, 0.5), ncol = 5))
  net <- build_ising(bin_data)
}

Build MCML from Raw Transition Data

Description

Builds a Multi-Cluster Multi-Level (MCML) model from raw transition data (edge lists or sequences) by recoding node labels to cluster labels and counting actual transitions. Unlike cluster_summary which aggregates a pre-computed weight matrix, this function works from the original transition data to produce the TRUE Markov chain over cluster states.

Usage

build_mcml(
  x,
  clusters = NULL,
  method = c("sum", "mean", "median", "max", "min", "density", "geomean"),
  type = c("tna", "frequency", "cooccurrence", "raw"),
  directed = TRUE,
  compute_within = TRUE,
  actor = NULL,
  action = NULL,
  time = NULL,
  order = NULL,
  session = NULL,
  time_threshold = 900,
  labels = NULL
)

Arguments

Value

A cluster_summary object with meta$source = "transitions", fully compatible with plot(), as_tna(), and plot().

See Also

cluster_summary for matrix-based aggregation, net_as_tna() to convert to tna objects, plot() for visualization

Examples

# Edge list with clusters
edges <- data.frame(
  from = c("A", "A", "B", "C", "C", "D"),
  to   = c("B", "C", "A", "D", "D", "A"),
  weight = c(1, 2, 1, 3, 1, 2)
)
clusters <- list(G1 = c("A", "B"), G2 = c("C", "D"))
cs <- build_mcml(edges, clusters)
cs$macro$weights

# Sequence data with clusters
seqs <- data.frame(
  T1 = c("A", "C", "B"),
  T2 = c("B", "D", "A"),
  T3 = c("C", "C", "D"),
  T4 = c("D", "A", "C")
)
cs <- build_mcml(seqs, clusters, type = "raw")
cs$macro$weights

Build a Multilevel Vector Autoregression (mlVAR) network

Description

Estimates three networks from ESM/EMA panel data, matching mlVAR::mlVAR() with estimator = "lmer", temporal = "fixed", contemporaneous = "fixed" at machine precision: (1) a directed temporal network of fixed-effect lagged regression coefficients, (2) an undirected contemporaneous network of partial correlations among residuals, and (3) an undirected between-subjects network of partial correlations derived from the person-mean fixed effects.

#' @details The algorithm follows mlVAR's lmer pipeline exactly:

1. Drop rows with NA in id/day/beep and optionally grand-mean standardize each variable.

2. Expand the per-(id, day) beep grid and right-join original values, producing the augmented panel (augData).

3. Add within-person lagged predictors (⁠L1_*⁠) and person-mean predictors (⁠PM_*⁠).

4. For each outcome variable fit lmer(y ~ within + between-except-own-PM + (1 | id)) with REML = FALSE. Collect the fixed-effect temporal matrix B, between-effect matrix Gamma, random-intercept SDs (mu_SD), and lmer residual SDs.

5. Contemporaneous network: cor2pcor(D %*% cov2cor(cor(resid)) %*% D).

6. Between-subjects network: cor2pcor(pseudoinverse(forcePositive(D (I - Gamma)))).

Validated to machine precision (max_diff < 1e-10) against mlVAR::mlVAR() on 25 real ESM datasets from openesm and 20 simulated configurations (seeds 201-220). See tmp/mlvar_equivalence_real20.R and tmp/mlvar_equivalence_20seeds.R.

Usage

build_mlvar(
  data,
  vars,
  id,
  day = NULL,
  beep = NULL,
  lag = 1L,
  standardize = FALSE
)

Arguments

Value

A dual-class c("net_mlvar", "netobject_group") object — a named list of three full netobjects, one per network, plus model-level metadata stored as attributes. Each element is a standard c("netobject", "cograph_network") weight-matrix wrapper (no raw ⁠$data⁠), so print(), summary(), coefs(), and cograph::splot(fit$temporal) work directly. The three constituents are matrix-wrapped and carry no underlying panel data, so data-resampling verbs such as bootstrap_network() (and reliability/stability) cannot iterate over them — extract a single constituent and rebuild via build_network() if you need those. Structure:

fit$temporal

Directed netobject for the ⁠d x d⁠ matrix of fixed-effect lagged coefficients. ⁠$weights[i, j]⁠ is the effect of variable j at t-lag on variable i at t. method = "mlvar_temporal", directed = TRUE.

fit$contemporaneous

Undirected netobject for the ⁠d x d⁠ partial-correlation network of within-person lmer residuals. method = "mlvar_contemporaneous", directed = FALSE.

fit$between

Undirected netobject for the ⁠d x d⁠ partial-correlation network of person means, derived from D (I - Gamma). method = "mlvar_between", directed = FALSE.

attr(fit, "coefs") / coefs()

Tidy data.frame with one row per ⁠(outcome, predictor)⁠ pair and columns outcome, predictor, beta, se, t, p, ci_lower, ci_upper, significant. Filter, sort, or plot with base R or the tidyverse. Retrieve with coefs(fit).

attr(fit, "n_obs")

Number of rows in the augmented panel after na.omit.

attr(fit, "n_subjects")

Number of unique subjects remaining.

attr(fit, "lag")

Lag order used.

attr(fit, "standardize")

Logical; whether pre-augmentation standardization was applied.

See Also

build_network()

Examples

## Not run: 
d <- simulate_data("mlvar", seed = 1)
fit <- build_mlvar(d, vars = attr(d, "vars"),
                   id = "id", day = "day", beep = "beep")
print(fit)
summary(fit)

## End(Not run)

Fit a Mixed Markov Model

Description

Discovers latent subgroups with different transition dynamics using Expectation-Maximization. Each mixture component has its own transition matrix. Sequences are probabilistically assigned to components.

Usage

build_mmm(
  data,
  k = 2L,
  n_starts = 50L,
  max_iter = 200L,
  tol = 1e-06,
  smooth = 0.01,
  seed = NULL,
  covariates = NULL,
  estimator = c("auto", "firth", "multinom", "chisq")
)

Arguments

Value

An object of class net_mmm with components:

data

The full N-row sequence frame used for estimation.

models

List of netobjects, one per component. Each component carries the rows assigned to that component in its $data slot, while its transition matrix is the EM-estimated component transition matrix.

k

Number of components.

mixing

Numeric vector of mixing proportions.

posterior

N x k matrix of posterior probabilities.

assignments

Integer vector of hard assignments (1..k).

quality

List: avepp (per-class), avepp_overall, entropy, relative_entropy, classification_error.

log_likelihood, BIC, AIC, ICL

Model fit statistics.

states

Character vector of state names.

Initial states

The first sequence column has special status: it is read directly as the per-sequence initial state (init_state[i] <- match(raw_data[i, state_cols[1L]], states)). The function does not scan forward to the first non-missing position, and it does not apply any na_syms-style symbol conversion (unlike build_clusters). The state vocabulary is built from the unique non-NA values across all columns, so if your data uses a sentinel character such as "*" or "%" for missing cells, that sentinel becomes a real state and the first column reads it as a valid initial state. If you want padded leading missings to be treated as missing, recode them to NA before calling build_mmm() (then match() returns NA, which the EM treats as an uninformative initial distribution), or left-trim the leading missings so each sequence's first column carries an observed state.

See Also

compare_mmm, build_network

Examples

seqs <- data.frame(V1 = sample(c("A","B","C"), 30, TRUE),
                   V2 = sample(c("A","B","C"), 30, TRUE))
mmm <- build_mmm(seqs, k = 2, n_starts = 1, max_iter = 10, seed = 1)
mmm

seqs <- data.frame(
  V1 = sample(LETTERS[1:3], 30, TRUE), V2 = sample(LETTERS[1:3], 30, TRUE),
  V3 = sample(LETTERS[1:3], 30, TRUE), V4 = sample(LETTERS[1:3], 30, TRUE)
)
mmm <- build_mmm(seqs, k = 2, seed = 42)
print(mmm)
summary(mmm)

Build Multi-Order Generative Model (MOGen)

Description

Constructs higher-order De Bruijn graphs from sequential trajectory data and selects the optimal Markov order using AIC, BIC, or likelihood ratio tests.

Usage

build_mogen(
  data,
  max_order = 5L,
  criterion = c("aic", "bic", "lrt"),
  lrt_alpha = 0.01
)

Arguments

Details

At order k, nodes are k-tuples of states and edges represent transitions between overlapping k-tuples. The model tests increasingly complex Markov orders and selects the one that best balances fit and parsimony.

Value

An object of class net_mogen with components:

optimal_order

Selected optimal Markov order.

criterion

Which criterion was used for selection.

orders

Integer vector of tested orders (0 to max_order).

aic

Named numeric vector of AIC values per order.

bic

Named numeric vector of BIC values per order.

log_likelihood

Named numeric vector of log-likelihoods.

dof

Named integer vector of cumulative DOF per model.

layer_dof

Named integer vector of per-layer DOF.

transition_matrices

List of transition matrices (index 1 = order 0).

states

Unique first-order states.

n_paths

Number of trajectories.

n_observations

Total number of state observations.

References

Scholtes, I. (2017). When is a Network a Network? Multi-Order Graphical Model Selection in Pathways and Temporal Networks. KDD 2017.

Gote, C. & Scholtes, I. (2023). Predicting variable-length paths in networked systems using multi-order generative models. Applied Network Science, 8, 62.

Examples

seqs <- list(c("A","B","C","D"), c("A","B","C","A"), c("B","C","D","A"))
mg <- build_mogen(seqs, max_order = 2)


trajs <- list(c("A","B","C","D"), c("A","B","D","C"),
              c("B","C","D","A"), c("C","D","A","B"))
m <- build_mogen(trajs, max_order = 3)
print(m)
plot(m)

Build a Network

Description

Universal network estimation function that supports both transition networks (relative, frequency, co-occurrence) and association networks (correlation, partial correlation, graphical lasso). Uses the global estimator registry, so custom estimators can also be used.

Usage

build_network(
  data,
  method,
  actor = NULL,
  action = NULL,
  time = NULL,
  session = NULL,
  order = NULL,
  codes = NULL,
  group = NULL,
  format = "auto",
  window_size = 3L,
  mode = c("non-overlapping", "overlapping"),
  scaling = NULL,
  threshold = 0,
  level = NULL,
  time_threshold = 900,
  predictability = TRUE,
  state_cols = NULL,
  metadata_cols = NULL,
  params = list(),
  labels = NULL,
  ...
)

Arguments

Details

The function works as follows:

1. Resolves method aliases to canonical names.

2. Validates explicit column arguments before any format guessing.

3. Retrieves the estimator function from the global registry.

4. For association methods with level specified, decomposes the data (between-person means or within-person centering).

5. Calls the estimator: do.call(fn, c(list(data = data), params)).

6. Applies scaling and thresholding to the result matrix.

7. Extracts edges and constructs the netobject.

For long-format transition data, supplying action without actor is allowed and treats all rows as one sequence in row/time order. The function warns because a one-sequence transition network is not recommended and cannot be validated by bootstrap or other confirmatory tests.

Value

An object of class c("netobject", "cograph_network") containing:

data

The input data used for estimation, as a data frame.

weights

The estimated network weight matrix.

nodes

Data frame with columns id, label, name, x, y. Node labels are in $nodes$label.

edges

Data frame of non-zero edges with integer from/to (node IDs) and numeric weight.

directed

Logical. Whether the network is directed.

method

The resolved method name.

params

The params list used (for reproducibility).

scaling

The scaling applied (or NULL).

threshold

The threshold applied.

n_nodes

Number of nodes.

n_edges

Number of non-zero edges.

level

Decomposition level used (or NULL).

meta

List with source, layout, and tna metadata (cograph-compatible).

node_groups

Node groupings data frame, or NULL.

predictability

Named numeric vector of R-squared predictability values per node (for undirected association methods when predictability = TRUE). NULL for directed methods.

Method-specific extras (e.g. precision_matrix, cor_matrix, frequency_matrix, lambda_selected, etc.) are preserved from the estimator output.

When level = "both", returns an object of class "netobject_ml" with $between and $within sub-networks and a $method field.

See Also

register_estimator, list_estimators, bootstrap_network

Examples

seqs <- data.frame(V1 = c("A","B","C","A"), V2 = c("B","C","A","B"))
net <- build_network(seqs, method = "relative")
net

# Transition network (relative probabilities)
seqs <- data.frame(
  V1 = sample(LETTERS[1:4], 30, TRUE), V2 = sample(LETTERS[1:4], 30, TRUE),
  V3 = sample(LETTERS[1:4], 30, TRUE), V4 = sample(LETTERS[1:4], 30, TRUE)
)
net <- build_network(seqs, method = "relative")
print(net)

# Association network (glasso)
freq_data <- convert_sequence_format(seqs, format = "frequency")
net_glasso <- build_network(freq_data, method = "glasso",
                             params = list(gamma = 0.5, nlambda = 50))

# With scaling
net_scaled <- build_network(seqs, method = "relative",
                             scaling = c("rank", "minmax"))

Build a Partial Correlation Network

Description

Convenience wrapper for build_network(method = "pcor"). Computes partial correlations from numeric data.

Usage

build_pcor(data, ...)

Arguments

Value

A netobject (see build_network).

See Also

build_network

Examples

data(srl_strategies)
net <- build_pcor(srl_strategies)

Build a Simplicial Complex

Description

Constructs a simplicial complex from a network or higher-order pathway object. Two construction methods are available:

• Clique complex ("clique"): every clique in the thresholded non-zero graph becomes a simplex. Edges with absolute weight \geq threshold are retained. The standard bridge from graph theory to algebraic topology.

• Pathway complex ("pathway"): each higher-order pathway from a net_hon or net_hypa becomes a simplex.

For type = "vr" (or alias "rips"), the input is treated as a non-negative distance / dissimilarity matrix and a Vietoris-Rips filtration is constructed: each k-simplex \sigma enters at \max_{(i,j) \in \sigma} d(i,j). Use max_scale to cap the filtration diameter; edges with d(i,j) > max_scale are excluded. Filtration values are attached as $filtration on the returned object so persistent_homology() can read them directly.

Usage

build_simplicial(
  x,
  type = "clique",
  threshold = 0,
  max_dim = 10L,
  max_pathways = NULL,
  anomaly = c("all", "over", "under"),
  max_scale = NULL,
  ...
)

Arguments

Value

A simplicial_complex object. For type = "vr" an additional $filtration numeric vector is attached (parallel to $simplices).

See Also

betti_numbers, persistent_homology, simplicial_degree, q_analysis

Examples

mat <- matrix(c(0,.6,.5,.6,0,.4,.5,.4,0), 3, 3)
colnames(mat) <- rownames(mat) <- c("A","B","C")
sc <- build_simplicial(mat, threshold = 0.3)
print(sc)
betti_numbers(sc)

# Vietoris-Rips on a distance matrix:
d <- 1 - mat
diag(d) <- 0
sc_vr <- build_simplicial(d, type = "vr", max_scale = 0.6)

Build a Transition Network (TNA)

Description

Convenience wrapper for build_network(method = "relative"). Computes row-normalized transition probabilities from sequence data.

Usage

build_tna(data, ...)

Arguments

Value

A netobject (see build_network).

See Also

build_network

Examples

seqs <- data.frame(V1 = c("A","B","C"), V2 = c("B","C","A"))
net <- build_tna(seqs)

Edge-weight Case-dropping Stability

Description

Computes a CS-coefficient for the edge-weight vector of a network: the maximum proportion of cases (rows of x$data) that can be dropped while the flattened edge-weight vector of the re-estimated network still correlates with the original above threshold in at least certainty of iterations.

Plots the four model-level reliability metrics across drop proportions: correlation, mean_abs_dev, median_abs_dev, max_abs_dev. Each panel shows the per-iteration mean with a ribbon at mean +/- sd. The correlation panel includes a dashed horizontal line at the user's threshold (default 0.7).

Overlay of per-cluster correlation curves across drop proportions. One colour per sub-network; ribbons show mean +/- sd across iterations. Dashed horizontal line marks the stability threshold (default 0.7).

Usage

casedrop_reliability(
  x,
  iter = 1000L,
  drop_prop = seq(0.1, 0.9, by = 0.1),
  threshold = 0.7,
  certainty = 0.95,
  method = c("spearman", "pearson", "kendall"),
  include_diag = FALSE,
  seed = NULL
)

## S3 method for class 'net_casedrop_reliability'
print(x, digits = 3, ...)

## S3 method for class 'net_casedrop_reliability'
summary(object, ...)

## S3 method for class 'net_casedrop_reliability_group'
print(x, ...)

## S3 method for class 'net_casedrop_reliability_group'
summary(object, drop_prop = NULL, ...)

## S3 method for class 'summary.net_casedrop_reliability_group'
print(x, ...)

## S3 method for class 'net_casedrop_reliability'
plot(x, combined = TRUE, ...)

## S3 method for class 'net_casedrop_reliability_group'
plot(
  x,
  metric = c("correlation", "mean_abs_dev", "median_abs_dev", "max_abs_dev"),
  ...
)

Arguments

Details

Complements centrality_stability(): that function asks whether centrality rankings are stable; this one asks whether the edge-weight structure itself is stable. For MCML-derived networks where each row of ⁠$data⁠ is one transition, this is case-dropping of edges.

For each drop_prop p and each iteration, a size n_cases * (1 - p) subset of ⁠$data⁠ rows is selected without replacement, the network is re-estimated using the same method/scaling/threshold as the input, and the upper/lower-triangle (directed: all off-diagonal entries) of the new weight matrix is flattened and correlated with the corresponding vector of the original matrix. The correlation method defaults to Spearman for robustness to the wide dynamic range of transition probabilities.

Unlike bootstrap CIs, case-dropping does not estimate sampling variance and so does not rely on the i.i.d. assumption. This makes it the appropriate robustness check for edgelist-derived networks (where rows of ⁠$data⁠ lack actor grouping), since dropping rows at random is a well-posed operation regardless of within-actor correlation.

Value

An object of class net_casedrop_reliability with:

cs

Scalar CS-coefficient — the maximum drop proportion for which the edge-vector correlation remains >= threshold in at least certainty of iterations. Zero if no proportion qualifies.

correlations

iter x length(drop_prop) matrix of per- iteration correlations.

drop_prop, threshold, certainty, iter, method

Inputs.

The input x invisibly.

A tidy data frame with columns metric, drop_prop, mean, sd summarising edge-weight stability across case-dropping iterations.

A data frame with one row per network containing cor, mean_abs_dev, median_abs_dev, max_abs_dev formatted as "mean +/- sd".

A ggplot object, or a named list of four ggplots when combined = FALSE.

A ggplot object.

References

Epskamp, S., Borsboom, D., & Fried, E. I. (2018). Estimating psychological networks and their accuracy: A tutorial paper. Behavior Research Methods 50(1), 195-212. doi:10.3758/s13428-017-0862-1

See Also

centrality_stability(), bootstrap_network().

Examples

seqs <- data.frame(
  V1 = sample(LETTERS[1:4], 30, TRUE),
  V2 = sample(LETTERS[1:4], 30, TRUE),
  V3 = sample(LETTERS[1:4], 30, TRUE)
)
net <- build_network(seqs, method = "relative")
es  <- casedrop_reliability(net, iter = 50, drop_prop = c(0.1, 0.3, 0.5),
                      seed = 1)
print(es)

Centrality Stability Coefficient (CS-coefficient)

Description

Estimates the stability of centrality indices under case-dropping. For each drop proportion, sequences are randomly removed and the network is re-estimated. The correlation between the original and subset centrality values is computed. The CS-coefficient is the maximum proportion of cases that can be dropped while maintaining a correlation above threshold in at least certainty of bootstrap samples.

For transition methods, uses pre-computed per-sequence count matrices for fast resampling. Strength centralities (InStrength, OutStrength) are computed directly from the matrix without igraph.

Usage

centrality_stability(
  x,
  measures = c("InStrength", "OutStrength", "Betweenness"),
  iter = 1000L,
  drop_prop = seq(0.1, 0.9, by = 0.1),
  threshold = 0.7,
  certainty = 0.95,
  method = "pearson",
  centrality_fn = NULL,
  loops = FALSE,
  seed = NULL
)

Arguments

Value

An object of class "net_stability" containing:

cs

Named numeric vector of CS-coefficients per measure.

correlations

Named list of matrices (iter x n_prop) of correlation values per measure.

measures

Character vector of measures assessed.

drop_prop

Drop proportions used.

threshold

Stability threshold.

certainty

Required certainty level.

iter

Number of iterations.

method

Correlation method.

See Also

build_network, network_reliability

Examples

net <- build_network(data.frame(V1 = c("A","B","C","A"),
  V2 = c("B","C","A","B")), method = "relative")
cs <- centrality_stability(net, iter = 10, drop_prop = 0.3)

seqs <- data.frame(
  V1 = sample(LETTERS[1:4], 30, TRUE), V2 = sample(LETTERS[1:4], 30, TRUE),
  V3 = sample(LETTERS[1:4], 30, TRUE), V4 = sample(LETTERS[1:4], 30, TRUE)
)
net <- build_network(seqs, method = "relative")
cs <- centrality_stability(net, iter = 100, seed = 42,
  measures = c("InStrength", "OutStrength"))
print(cs)

Qualitative structure of a discrete-time Markov chain.

Description

Computes properties that depend only on the transition matrix support, not on any starting distribution: state classification, communicating classes, periods, irreducibility / aperiodicity / regularity / reversibility, hitting probabilities, and absorption analysis when absorbing states exist.

Usage

chain_structure(x, normalize = TRUE, tol = 1e-10)

Arguments

Details

Built specifically as a diagnostic to run before trusting the output of passage_time() or markov_stability(). Both implicitly assume a regular chain (irreducible + aperiodic) so that the stationary distribution is unique and meaningful. Use is_regular to check.

The fundamental-matrix absorption math follows Kemeny & Snell (1976); the hitting-probability linear system follows Norris (1997).

Value

A chain_structure object: a list with elements

states

Character vector of state names.

classification

Named character vector. One of "absorbing", "recurrent", "transient" per state.

communicating_classes

List of state-name vectors. Each sublist is a strongly connected component of the support graph.

recurrent_classes

Subset of communicating_classes that are closed (no transitions leaving the class).

transient_classes

Subset that are not closed.

absorbing_states

Character vector of states with P[i, i] = 1 (tested exactly, to within .Machine$double.eps^0.5; the user-facing tol does not relax this).

period

Named integer vector. Period of each recurrent state; NA for transient states.

is_irreducible

Logical. TRUE iff there is exactly one communicating class.

is_aperiodic

Logical. TRUE iff every recurrent state has period 1.

is_regular

Logical. is_irreducible && is_aperiodic.

is_reversible

Logical or NA. TRUE iff the chain satisfies detailed balance against its stationary distribution. NA for non-irreducible chains (no unique stationary).

hitting_probabilities

⁠n x n⁠ matrix. ⁠[i, j] = P(ever reach j starting from i)⁠, computed over the same tol-thresholded support graph that drives classification so the two are mutually consistent (a state classified "absorbing"/closed never shows hitting probability to states outside its class).

absorption_probabilities

⁠n_transient x n_absorbing⁠ matrix or NULL if no transient -> absorbing pathway exists. ⁠[i, j] = P(eventual absorption in j | start in i)⁠.

mean_absorption_time

Named numeric vector or NULL. Expected number of steps until absorption from each transient state.

P

The (possibly normalized) transition matrix used.

References

Kemeny, J. G. and Snell, J. L. (1976). Finite Markov Chains. Springer-Verlag.

Norris, J. R. (1997). Markov Chains. Cambridge University Press.

See Also

passage_time(), markov_stability(), build_network()

Examples

net <- build_network(as.data.frame(trajectories), method = "relative")
cs  <- chain_structure(net)
print(cs)

summary(cs)

ChatGPT Self-Regulated Learning Scale Scores

Description

Scale scores on five self-regulated learning (SRL) constructs for 1,000 responses generated by ChatGPT to a validated SRL questionnaire. Part of a larger dataset comparing LLM-generated responses to human norms across seven large language models.

Usage

chatgpt_srl

Format

A data frame with 1,000 rows and 5 columns:

CSU

Numeric. Comprehension and Study Understanding scale mean.

IV

Numeric. Intrinsic Value scale mean.

SE

Numeric. Self-Efficacy scale mean.

SR

Numeric. Self-Regulation scale mean.

TA

Numeric. Task Avoidance scale mean.

Source

Vogelsmeier, L.V.D.E., Oliveira, E., Misiejuk, K., Lopez-Pernas, S., & Saqr, M. (2025). Delving into the psychology of Machines: Exploring the structure of self-regulated learning via LLM-generated survey responses. Computers in Human Behavior, 173, 108769. doi:10.1016/j.chb.2025.108769

Examples

net <- build_network(chatgpt_srl, method = "glasso",
                     params = list(gamma = 0.5))
net

Check Value in Range

Description

Check if a value falls within a specified range.

Usage

check_val_in_range(value, range_val)

Arguments

Value

Logical indicating whether value is in range.

Clique expansion of a hypergraph

Description

Projects a net_hypergraph to a standard pairwise netobject (the clique expansion — also called the "downgrade" of a hypergraph to a dyadic graph). Each hyperedge of size k contributes 1 (or its weight) to every pair of its members. The resulting edge weight W[i, j] equals the number of hyperedges containing both i and j (binary incidence) or the sum of incidence products (weighted incidence).

Usage

clique_expansion(hg, weighted = TRUE)

Arguments

Details

The clique expansion is the standard "loss-y but lossless-on-pairwise" projection: it preserves which pairs co-occurred and how often but discards the higher-order grouping. Comparing clique_expansion(hg) to a directly-estimated pairwise network (e.g. via cooccurrence() on the same data) quantifies how much information was carried by the hyperedge structure.

Computed in one BLAS call via tcrossprod(incidence); runs in O(n_nodes^2 * n_hyperedges) time, fast for typical sizes.

Closes the I/O cycle: event data -> bipartite_groups() -> clique_expansion() -> any function that accepts a netobject (centrality, bootstrap, clustering, plotting via cograph).

Value

A netobject (also cograph_network) with method = "clique_expansion", undirected, with weighted symmetric adjacency W = incidence %*% t(incidence) and zero diagonal.

Note

(experimental) Validated against tcrossprod(incidence) with zero diagonal. No external R package exposes clique expansion as a primitive; the implementation is a direct one-line restatement of the definition.

References

Tian, Y., & Zafarani, R. (2024). Higher-order network analysis methods. SIGKDD Explorations 26(1), Section 5.1.5.

See Also

build_hypergraph(), bipartite_groups(), build_network().

Examples

df <- data.frame(
  player  = c("A", "B", "C", "A", "B", "D", "C", "D", "E"),
  session = c("S1", "S1", "S1", "S2", "S2", "S3", "S3", "S3", "S3")
)
hg  <- bipartite_groups(df, player = "player", group = "session")
net <- clique_expansion(hg)
net$weights

Cluster Choice – sweep k, dissimilarity and method

Description

One-call sweep across any combination of k, dissimilarity metric, and clustering algorithm for distance-based sequence clustering. Mirrors compare_mmm for model-based clustering: returns a data frame with one row per swept configuration, a best marker on the silhouette-max row in the print method, and a plot() that adapts to the swept axes.

Usage

cluster_choice(
  data,
  k = 2:5,
  dissimilarity = "hamming",
  method = "ward.D2",
  ...
)

Arguments

Value

A cluster_choice object (a data.frame subclass) with one row per (k, dissimilarity, method) combination and columns:

k, dissimilarity, method

The configuration for that row.

silhouette

Overall average silhouette width (from cluster::silhouette, computed inside build_clusters).

mean_within_dist

Size-weighted mean of within-cluster distances, in the units of the row's dissimilarity.

min_size, max_size, size_ratio

Cluster-size balance bounds and their ratio (max / min).

See Also

build_clusters, compare_mmm for the model-based equivalent, cluster_diagnostics for the post-fit diagnostic surface on a single clustering.

Examples

seqs <- data.frame(V1 = sample(c("A","B","C"), 40, TRUE),
                   V2 = sample(c("A","B","C"), 40, TRUE))
cluster_choice(seqs, k = 2:4)

# Sweep dissimilarities at fixed k
cluster_choice(seqs, k = 3, dissimilarity = c("hamming", "lcs", "jaccard"))

# Full grid of k x dissimilarity
cluster_choice(seqs, k = 2:4, dissimilarity = c("hamming", "lcs"))

# "all" sentinel
cluster_choice(seqs, k = 3, dissimilarity = "all")

Cluster sequence data (deprecated alias)

Description

Renamed to build_clusters in Nestimate 0.4.3. This thin wrapper is preserved so the function name in older tutorials and the historical pkgdown reference continues to work; it issues a one-shot deprecation warning and forwards every argument unchanged.

Usage

cluster_data(...)

Arguments

Value

The net_clustering object returned by build_clusters.

See Also

build_clusters, cluster_network, cluster_mmm.

Cluster Diagnostics

Description

Unified entry point for clustering quality information. Returns a net_cluster_diagnostics object that normalises the diagnostic surface across distance-based and model-based clusterings – you no longer have to know which fields live on net_clustering vs. net_mmm vs. the slim net_mmm_clustering attribute of a netobject_group.

Usage

cluster_diagnostics(x, ...)

## S3 method for class 'net_cluster_diagnostics'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Details

The returned object carries:

family

Either "distance" or "mmm".

k, n, sizes

Number of clusters, number of sequences, sizes vector.

per_cluster

A data.frame – one row per cluster, columns differ by family. Distance: cluster, size, pct, mean_within_dist, sil_mean. MMM: cluster, size, pct, mix_pct, avepp, class_err_pct.

overall

A named list of family-specific summary metrics (silhouette for distance; avepp_overall, entropy, classification_error for MMM).

ics

For MMM: a list with BIC, AIC, ICL. NULL for distance.

metadata

Method / dissimilarity / weighted / lambda etc.

source

The original clustering object, kept by reference so plot() can delegate without recomputing anything.

Value

A net_cluster_diagnostics object.

See Also

print.net_cluster_diagnostics, plot.net_cluster_diagnostics, compare_mmm for k-sweep model selection (MMM only).

Examples

seqs <- data.frame(V1 = sample(c("A","B","C"), 30, TRUE),
                   V2 = sample(c("A","B","C"), 30, TRUE))
cl <- build_clusters(seqs, k = 2, method = "ward.D2")
cluster_diagnostics(cl)

grp <- cluster_mmm(seqs, k = 2, n_starts = 1, max_iter = 20, seed = 1)
cluster_diagnostics(grp)
as.data.frame(cluster_diagnostics(grp))

Cluster sequences using Mixed Markov Models

Description

Fits a mixture of Markov chains to sequence data and returns a netobject_group containing per-cluster transition networks. This is the MMM equivalent of cluster_network (which uses distance-based clustering); both functions share the cluster_by = ... surface argument so the call shape stays uniform across clustering families.

Usage

cluster_mmm(
  data,
  k = 2L,
  n_starts = 50L,
  max_iter = 200L,
  tol = 1e-06,
  smooth = 0.01,
  seed = NULL,
  covariates = NULL,
  estimator = c("auto", "firth", "multinom", "chisq"),
  cluster_by = "mmm",
  ...
)

Arguments

Details

For the full net_mmm object with posterior probabilities, model fit statistics, and S3 methods, use build_mmm instead.

Value

A netobject_group (list of netobjects, one per cluster). MMM-specific information is stored in attr(, "clustering") (class "net_mmm_clustering"):

assignments

Integer vector of cluster assignments.

k

Number of clusters.

posterior

N x k matrix of posterior probabilities.

mixing

Mixing proportions.

quality

List with AvePP, entropy, classification error.

BIC, AIC, ICL

Model fit statistics.

data

The full N-row sequence frame, matching $assignments – so sequence_plot and distribution_plot can recover both.

See Also

build_mmm for the full MMM object, cluster_network for distance-based clustering

Examples

seqs <- data.frame(V1 = sample(c("A","B","C"), 30, TRUE),
                   V2 = sample(c("A","B","C"), 30, TRUE))
grp <- cluster_mmm(seqs, k = 2, n_starts = 1, max_iter = 10, seed = 1)
grp[[1]]$weights
attr(grp, "clustering")$assignments

# Visualise with sequence_plot
seqs <- data.frame(
  V1 = sample(LETTERS[1:3], 40, TRUE),
  V2 = sample(LETTERS[1:3], 40, TRUE),
  V3 = sample(LETTERS[1:3], 40, TRUE)
)
grp <- cluster_mmm(seqs, k = 2)
sequence_plot(grp, type = "index")

Cluster data and build per-cluster networks in one step

Description

Combines sequence clustering and network estimation into a single call. Clusters the data using the specified algorithm, then calls build_network on each cluster subset.

Usage

cluster_network(data, k, cluster_by = "pam", dissimilarity = "hamming", ...)

Arguments

Details

If data is a netobject and method is not provided in ..., the original network method is inherited automatically so the per-cluster networks match the type of the input network.

Value

A netobject_group.

See Also

build_clusters, cluster_mmm, build_network

Examples

seqs <- data.frame(V1 = c("A","B","C","A","B"), V2 = c("B","C","A","B","A"),
                   V3 = c("C","A","B","C","B"))
grp <- cluster_network(seqs, k = 2)
grp

set.seed(1)
seqs <- data.frame(
  V1 = sample(LETTERS[1:4], 50, TRUE), V2 = sample(LETTERS[1:4], 50, TRUE),
  V3 = sample(LETTERS[1:4], 50, TRUE), V4 = sample(LETTERS[1:4], 50, TRUE)
)
# Default: PAM clustering, relative (transition) networks
grp <- cluster_network(seqs, k = 3)

# Specify network method (cor requires numeric panel data)
## Not run: 
panel <- as.data.frame(matrix(rnorm(1500), nrow = 300, ncol = 5))
grp <- cluster_network(panel, k = 2, method = "cor")

## End(Not run)

# MMM-based clustering
grp <- cluster_network(seqs, k = 2, cluster_by = "mmm")

Cluster Summary Statistics

Description

Aggregates node-level network weights to cluster-level summaries. Computes both between-cluster transitions (how clusters connect to each other) and within-cluster transitions (how nodes connect within each cluster).

Usage

cluster_summary(
  x,
  clusters = NULL,
  method = c("sum", "mean", "median", "max", "min", "density", "geomean"),
  directed = TRUE,
  compute_within = TRUE
)

Arguments

Details

This is the core function for Multi-Cluster Multi-Level (MCML) analysis. Use as_tna() to convert results to tna objects for further analysis with the tna package.

Workflow

Typical MCML analysis workflow:

# 1. Create network
net <- build_network(data, method = "relative")
net$nodes$clusters <- group_assignments

# 2. Compute cluster summary (arithmetic aggregation over edges)
cs <- cluster_summary(net, method = "sum")

# 3. Convert to tna models (normalization happens in as_tna)
tna_models <- as_tna(cs)

# 4. Analyze/visualize
plot(tna_models$macro)
tna::centralities(tna_models$macro)

Between-Cluster Matrix Structure

The macro$weights matrix has clusters as both rows and columns:

• Off-diagonal (row i, col j): Aggregated weight from cluster i to cluster j

• Diagonal (row i, col i): Within-cluster total (aggregation of internal edges)

Rows are NOT normalized. Entries are elementwise aggregates produced by method. If the caller wants probabilities, they should normalize downstream (e.g. via as_tna()). Mixing an arithmetic aggregation with row-normalization here (the old type = "tna" combined with method = "min" / "mean" etc.) produces numbers that sum to 1 per row but are not a probability distribution over any process; that silently-wrong combination is why type was removed from the matrix path. The sequence and edgelist paths of build_mcml() keep type, where the aggregation is always counts and the post-processing chooses between well-defined network constructions.

Choosing method

Value

A cluster_summary object (S3 class) containing:

between

List with two elements:

weights

k x k matrix of cluster-to-cluster weights, where k is the number of clusters. Row i, column j contains the elementwise aggregation (per method) of all edges from nodes in cluster i to nodes in cluster j. Diagonal contains within-cluster totals. Pure arithmetic – no row normalization.

inits

Numeric vector of length k. Initial state distribution across clusters, computed from column sums of the original matrix. Represents the proportion of incoming edges to each cluster.

within

Named list with one element per cluster. Each element contains:

weights

n_i x n_i matrix for nodes within that cluster. Shows internal transitions between nodes in the same cluster.

inits

Initial distribution within the cluster.

NULL if compute_within = FALSE.

clusters

Named list mapping cluster names to their member node labels. Example: list(A = c("n1", "n2"), B = c("n3", "n4", "n5"))

meta

List of metadata:

method

The method argument used ("sum", "mean", etc.)

directed

Logical, whether network was treated as directed

n_nodes

Total number of nodes in original network

n_clusters

Number of clusters

cluster_sizes

Named vector of cluster sizes

See Also

as_tna() to convert results to tna objects, plot() for two-layer visualization, plot() for flat cluster visualization

Examples

# -----------------------------------------------------
# Basic usage with matrix and cluster vector
# -----------------------------------------------------
mat <- matrix(runif(100), 10, 10)
rownames(mat) <- colnames(mat) <- LETTERS[1:10]

clusters <- c(1, 1, 1, 2, 2, 2, 3, 3, 3, 3)
cs <- cluster_summary(mat, clusters)

# Access results
cs$macro$weights    # 3x3 cluster transition matrix
cs$macro$inits      # Initial distribution
cs$clusters$`1`$weights # Within-cluster 1 transitions
cs$meta               # Metadata

# -----------------------------------------------------
# Named list clusters (more readable)
# -----------------------------------------------------
clusters <- list(
  Alpha = c("A", "B", "C"),
  Beta = c("D", "E", "F"),
  Gamma = c("G", "H", "I", "J")
)
cs <- cluster_summary(mat, clusters)
cs$macro$weights    # Rows/cols named Alpha, Beta, Gamma
cs$clusters$Alpha       # Within Alpha cluster

# -----------------------------------------------------
# Auto-detect clusters from netobject
# -----------------------------------------------------

seqs <- data.frame(
  V1 = sample(LETTERS[1:10], 30, TRUE), V2 = sample(LETTERS[1:10], 30, TRUE),
  V3 = sample(LETTERS[1:10], 30, TRUE)
)
net <- build_network(seqs, method = "relative")
cs2 <- cluster_summary(net, c(1, 1, 1, 2, 2, 2, 3, 3, 3, 3))


# -----------------------------------------------------
# Different aggregation methods
# -----------------------------------------------------
cs_sum <- cluster_summary(mat, clusters, method = "sum")   # Total flow
cs_mean <- cluster_summary(mat, clusters, method = "mean") # Average
cs_max <- cluster_summary(mat, clusters, method = "max")   # Strongest

# -----------------------------------------------------
# Skip within-cluster computation for speed
# -----------------------------------------------------
cs_fast <- cluster_summary(mat, clusters, compute_within = FALSE)
cs_fast$clusters  # NULL

# -----------------------------------------------------
# Convert to tna objects for tna package
# (as_tna() applies its own row normalisation)
# -----------------------------------------------------
cs <- cluster_summary(mat, clusters, method = "sum")
tna_models <- as_tna(cs)
# tna_models$macro      # tna object
# tna_models$clusters$Alpha # tna object

Tidy coefficients from a fitted mlvar model

Description

Generic accessor for the tidy coefficient table stored on a build_mlvar() result. Returns a data.frame with one row per ⁠(outcome, predictor)⁠ pair and columns outcome, predictor, beta, se, t, p, ci_lower, ci_upper, significant.

Usage

coefs(x, ...)

## S3 method for class 'net_mlvar'
coefs(x, ...)

## Default S3 method:
coefs(x, ...)

Arguments

Details

Only the within-person (temporal) coefficients are tabulated — these are the lagged fixed effects that populate fit$temporal. The between-subjects effects that go into fit$between are handled via the D (I - Gamma) transformation and are not exposed as a separate tidy table.

Value

A tidy data.frame of coefficient estimates.

Examples

## Not run: 
d <- simulate_data("mlvar", seed = 1)
fit <- build_mlvar(d, vars = attr(d, "vars"),
                   id = "id", day = "day", beep = "beep")
print(fit)
summary(fit)

## End(Not run)

Compare MMM fits across different k

Description

Compare MMM fits across different k

Usage

compare_mmm(data, k = 2:5, return_fits = FALSE, ...)

Arguments

Value

A mmm_compare data frame with BIC, AIC, ICL, AvePP, entropy per k. When return_fits = TRUE, the fitted models are attached as attr(result, "fits").

Examples

seqs <- data.frame(V1 = sample(c("A","B","C"), 30, TRUE),
                   V2 = sample(c("A","B","C"), 30, TRUE))
comp <- compare_mmm(seqs, k = 2:3, n_starts = 1, max_iter = 10, seed = 1)
comp

seqs <- data.frame(
  V1 = sample(LETTERS[1:3], 30, TRUE), V2 = sample(LETTERS[1:3], 30, TRUE),
  V3 = sample(LETTERS[1:3], 30, TRUE), V4 = sample(LETTERS[1:3], 30, TRUE)
)
comp <- compare_mmm(seqs, k = 2:3, seed = 42)
print(comp)

# Retain fits to avoid a re-fit after picking the BIC-min model.
comp_with_fits <- compare_mmm(seqs, k = 2:3, seed = 42, return_fits = TRUE)
best_k <- comp_with_fits$k[which.min(comp_with_fits$BIC)]
best_fit <- attr(comp_with_fits, "fits")[[as.character(best_k)]]

Compare two networks descriptively

Description

Computes a battery of descriptive comparison metrics between two networks or two weight matrices: weight deviations (mean / median / RMS / max absolute difference, relative mean absolute difference, coefficient-of- variation ratio), four correlation measures (Pearson, Spearman, Kendall, distance correlation), five dissimilarity measures (Euclidean, Manhattan, Canberra, Bray-Curtis, Frobenius), five similarity measures (Cosine, Jaccard, Dice, Overlap, RV), pattern agreements, and side-by-side network metrics. Optionally adds centrality differences and centrality correlations.

Usage

compare_model(x, ...)

## S3 method for class 'netobject'
compare_model(
  x,
  y,
  scaling = "none",
  measures = character(0),
  network = TRUE,
  ...
)

## S3 method for class 'cograph_network'
compare_model(
  x,
  y,
  scaling = "none",
  measures = character(0),
  network = TRUE,
  ...
)

## S3 method for class 'matrix'
compare_model(
  x,
  y,
  scaling = "none",
  measures = character(0),
  network = TRUE,
  ...
)

Arguments

Details

Mirrors tna::compare() numerically. Inputs are converted to weight matrices and scaled before comparison; the choice of scaling determines how weights from different estimators are placed on a common footing.

Value

A net_comparison object: a named list with matrices, difference_matrix, edge_metrics, summary_metrics, optionally network_metrics, centrality_differences, centrality_correlations.

Compare two networks within a netobject_group

Description

Selects two members of a netobject_group (by index or name) and dispatches to compare_model.netobject().

Usage

## S3 method for class 'netobject_group'
compare_model(
  x,
  i = 1L,
  j = 2L,
  scaling = "none",
  measures = character(0),
  network = TRUE,
  ...
)

Arguments

Value

A net_comparison object.

Convert Sequence Data to Different Formats

Description

Convert wide or long sequence data into frequency counts, one-hot encoding, edge lists, or follows format.

Usage

convert_sequence_format(
  data,
  seq_cols = NULL,
  id_col = NULL,
  action = NULL,
  time = NULL,
  format = c("frequency", "onehot", "edgelist", "follows")
)

Arguments

Value

A data frame in the requested format:

frequency

ID columns + one integer column per state with counts.

onehot

ID columns + one binary column per state (0/1).

edgelist

ID columns + from and to columns.

follows

ID columns + act and follows columns.

See Also

frequencies for building transition frequency matrices.

Examples

# Wide format input
seqs <- data.frame(V1 = c("A","B","A"), V2 = c("B","A","C"), V3 = c("A","C","B"))
convert_sequence_format(seqs, format = "frequency")
convert_sequence_format(seqs, format = "edgelist")

Build a Co-occurrence Network

Description

Constructs an undirected co-occurrence network from various input formats. Entities that appear together in the same transaction, document, or record are connected, with edge weights reflecting raw counts or a similarity measure. Argument names follow the citenets convention.

Usage

cooccurrence(
  data,
  field = NULL,
  by = NULL,
  sep = NULL,
  similarity = c("none", "jaccard", "cosine", "inclusion", "association", "dice",
    "equivalence", "relative"),
  threshold = 0,
  min_occur = 1L,
  diagonal = TRUE,
  top_n = NULL,
  ...
)

Arguments

Details

Six input formats are supported, auto-detected from the combination of field, by, and sep:

1. Delimited: field + sep (single column). Each cell is split by sep, trimmed, and de-duplicated per row.

2. Multi-column delimited: field (vector) + sep. Values from multiple columns are split, pooled, and de-duplicated per row.

3. Long bipartite: field + by. Groups by by; unique values of field within each group form a transaction.

4. Binary matrix: No field/by/sep, all values 0/1. Columns are items, rows are transactions.

5. Wide sequence: No field/by/sep, non-binary. Unique values across each row form a transaction.

6. List: A plain list of character vectors.

The pipeline converts all formats into a list of character vectors (transactions), optionally filters by min_occur, builds a binary transaction matrix, computes crossprod(B) for the raw co-occurrence counts, normalizes via the chosen similarity, then applies threshold and top_n filtering.

Value

A netobject (undirected) with method = "co_occurrence_fn". The $weights matrix contains similarity (or raw) co-occurrence values. The $params list stores the similarity method, threshold, and the number of transactions.

References

van Eck, N. J., & Waltman, L. (2009). How to normalize co-occurrence data? An analysis of some well-known similarity measures. Journal of the American Society for Information Science and Technology, 60(8), 1635–1651.

See Also

build_cna for sequence-positional co-occurrence via build_network().

Examples

# Delimited field (e.g., keyword co-occurrence)
df <- data.frame(
  id = 1:4,
  keywords = c("network; graph", "graph; matrix; network",
               "matrix; algebra", "network; algebra; graph")
)
net <- cooccurrence(df, field = "keywords", sep = ";")

# Long/bipartite
long_df <- data.frame(
  paper = c(1, 1, 1, 2, 2, 3, 3),
  keyword = c("network", "graph", "matrix", "graph", "algebra",
              "network", "algebra")
)
net <- cooccurrence(long_df, field = "keyword", by = "paper")

# List of transactions
transactions <- list(c("A", "B"), c("B", "C"), c("A", "B", "C"))
net <- cooccurrence(transactions, similarity = "jaccard")

# Binary matrix
bin <- matrix(c(1,0,1, 1,1,0, 0,1,1), nrow = 3, byrow = TRUE,
              dimnames = list(NULL, c("X", "Y", "Z")))
net <- cooccurrence(bin)

Data Format Conversion Functions

Description

Functions for converting between wide and long data formats commonly used in Temporal Network Analysis.

State Distribution Plot Over Time

Description

Draws how state proportions (or counts) evolve across time points. For each time column, tabulates how many sequences are in each state and renders the result as a stacked area (default) or stacked bar chart. Accepts the same inputs as sequence_plot.

Usage

distribution_plot(
  x,
  group = NULL,
  scale = c("proportion", "count"),
  geom = c("area", "bar"),
  na = TRUE,
  state_colors = NULL,
  na_color = "grey90",
  frame = FALSE,
  width = NULL,
  height = NULL,
  main = NULL,
  show_n = TRUE,
  time_label = "Time",
  xlab = NULL,
  y_label = NULL,
  ylab = NULL,
  tick = NULL,
  ncol = NULL,
  nrow = NULL,
  combined = TRUE,
  legend = c("right", "bottom", "none"),
  legend_size = NULL,
  legend_title = NULL,
  legend_ncol = NULL,
  legend_border = NA,
  legend_bty = "n"
)

Arguments

Value

Invisibly, a list with counts, proportions, levels, palette, and groups.

See Also

sequence_plot, build_clusters

Examples

distribution_plot(as.data.frame(trajectories))

Estimate a Network (Deprecated)

Description

This function is deprecated. Use build_network instead.

Usage

estimate_network(
  data,
  method = "relative",
  params = list(),
  scaling = NULL,
  threshold = 0,
  level = NULL,
  ...
)

Arguments

Value

A netobject (see build_network).

See Also

build_network

Examples

data <- data.frame(A = c("x","y","z","x"), B = c("y","x","z","y"))
net <- estimate_network(data, method = "relative")

Euler Characteristic

Description

Computes \chi = \sum_{k=0}^{d} (-1)^k f_k where f_k is the number of k-simplices. By the Euler-Poincare theorem, \chi = \sum_{k} (-1)^k \beta_k.

Usage

euler_characteristic(sc)

Arguments

Value

Integer.

Examples

mat <- matrix(c(0,.6,.5,.6,0,.4,.5,.4,0), 3, 3)
colnames(mat) <- rownames(mat) <- c("A","B","C")
sc <- build_simplicial(mat, threshold = 0.3)
euler_characteristic(sc)

Evaluate Link Predictions Against Known Edges

Description

Computes AUC-ROC, precision@k, and average precision for link predictions against a set of known true edges.

Usage

evaluate_links(pred, true_edges, k = c(5L, 10L, 20L))

Arguments

Value

A data frame with columns: method, auc, average_precision, and one precision_at_k column per k value.

Examples

set.seed(42)
seqs <- data.frame(
  V1 = sample(LETTERS[1:5], 50, TRUE),
  V2 = sample(LETTERS[1:5], 50, TRUE),
  V3 = sample(LETTERS[1:5], 50, TRUE)
)
net <- build_network(seqs, method = "relative")
pred <- predict_links(net, exclude_existing = FALSE)

# Evaluate: predict the network's own edges
true <- data.frame(from = pred$predictions$from[1:5],
                   to = pred$predictions$to[1:5])
evaluate_links(pred, true)

Extract Edge List with Weights

Description

Extract an edge list from a TNA model, representing the network as a data frame of from-to-weight tuples.

Usage

extract_edges(model, threshold = 0, include_self = FALSE, sort_by = "weight")

Arguments

Details

This function converts the transition matrix into an edge list format, which is useful for visualization, analysis with igraph, or export to other network tools.

Value

A data frame with columns:

from

Source state name.

to

Target state name.

weight

Edge weight (transition probability).

See Also

extract_transition_matrix for the full matrix, build_network for network estimation.

Examples

seqs <- data.frame(V1 = c("A","B","A"), V2 = c("B","A","C"), V3 = c("A","C","B"))
net <- build_network(seqs, method = "relative")
edges <- extract_edges(net, threshold = 0.05)
head(edges)

Extract Initial Probabilities from Model

Description

Extract the initial state probability vector from a TNA model object.

Usage

extract_initial_probs(model)

Arguments

Details

Initial probabilities represent the probability of starting a sequence in each state. If the model doesn't have explicit initial probabilities, this function attempts to estimate them from the data or use uniform probabilities.

Value

A named numeric vector of initial state probabilities.

See Also

extract_transition_matrix for extracting the transition matrix, extract_edges for extracting an edge list.

Examples

seqs <- data.frame(V1 = c("A","B","A"), V2 = c("B","A","C"), V3 = c("A","C","B"))
net <- build_network(seqs, method = "relative")
init_probs <- extract_initial_probs(net)
print(init_probs)

Extract Transition Matrix from Model

Description

Extract the transition probability matrix from a TNA model object.

Usage

extract_transition_matrix(model, type = c("raw", "scaled"))

Arguments

Details

TNA models store transition weights in different locations depending on the model type. This function handles the extraction automatically.

For "scaled" type, each row is divided by its sum to create valid transition probabilities. This is useful when the original weights don't sum to 1.

Value

A square numeric matrix with row and column names as state names.

See Also

extract_initial_probs for extracting initial probabilities, extract_edges for extracting an edge list.

Examples

seqs <- data.frame(V1 = c("A","B","A"), V2 = c("B","A","C"), V3 = c("A","C","B"))
net <- build_network(seqs, method = "relative")
trans_mat <- extract_transition_matrix(net)
print(trans_mat)

Model Extraction Functions

Description

Functions for extracting components from TNA model objects.

Sequence Data Conversion Functions

Description

Functions for converting sequence data (long or wide format) into transition frequency matrices and other useful representations.

Convert long or wide format sequence data into a transition frequency matrix. Counts how many times each transition from state_i to state_j occurs across all sequences.

Usage

frequencies(
  data,
  action = "Action",
  id = NULL,
  time = "Time",
  cols = NULL,
  format = c("auto", "long", "wide")
)

Arguments

Details

For long format data, each row is a single action/event. Sequences are defined by the id column(s), and actions are ordered by the time column within each sequence. Consecutive actions within a sequence form transition pairs.

For wide format data, each row is a sequence and columns represent consecutive time points. Transitions are counted across consecutive columns, skipping any NA values.

Value

A square integer matrix of transition frequencies where mat[i, j] is the number of times state i was followed by state j. Row and column names are the sorted unique states. Can be passed directly to tna::tna().

See Also

convert_sequence_format for converting to other representations (frequency counts, one-hot, edge lists).

Examples

# Wide format
seqs <- data.frame(V1 = c("A","B","A"), V2 = c("B","A","C"), V3 = c("A","C","B"))
freq <- frequencies(seqs, format = "wide")

# Long format
long <- data.frame(
  Actor = rep(1:2, each = 3), Time = rep(1:3, 2),
  Action = c("A","B","C","B","A","C")
)
freq <- frequencies(long, action = "Action", id = "Actor")

Retrieve a Registered Estimator

Description

Retrieve a registered network estimator by name.

Usage

get_estimator(name)

Arguments

Value

A list with elements fn, description, directed.

See Also

register_estimator, list_estimators

Examples

est <- get_estimator("relative")

Group Regulation in Collaborative Learning (Long Format)

Description

Students' regulation strategies during collaborative learning, in long format. Contains 27,533 timestamped action records from multiple students working in groups across two courses.

Usage

group_regulation_long

Format

A data frame with 27,533 rows and 6 columns:

Actor

Integer. Student identifier.

Achiever

Character. Achievement level: "High" or "Low".

Group

Numeric. Collaboration group identifier.

Course

Character. Course identifier ("A", "B", or "C").

Time

POSIXct. Timestamp of the action.

Action

Character. Regulation action (e.g., cohesion, consensus, discuss, synthesis).

Source

Synthetically generated from the group_regulation dataset in the tna package.

See Also

learning_activities, srl_strategies

Examples

net <- build_network(group_regulation_long,
                     method = "relative",
                     actor = "Actor", action = "Action", time = "Time")
net

Hypergraph eigenvector centralities

Description

Computes one or more eigenvector-style centralities on a net_hypergraph: clique-motif (CEC), Z-eigenvector (ZEC), and H-eigenvector (HEC). Each variant captures influence differently — CEC flattens group structure via clique expansion, while ZEC and HEC propagate through the higher-order groups directly.

Usage

hypergraph_centrality(
  hg,
  type = c("clique", "Z", "H"),
  max_iter = 1000L,
  tol = 1e-08,
  normalize = TRUE
)

Arguments

Details

Clique-motif eigenvector centrality (CEC): forms the clique-expanded pairwise graph W where W_{ij} = |\{e : i, j \in e\}| and returns the leading eigenvector of W. Equivalent to running igraph::eigen_centrality() on clique_expansion() output.

Z-eigenvector centrality (ZEC): solves the linear eigen-equation on the hyperedge tensor,

\lambda\, x_i \;=\; \sum_{e \ni i}\; \prod_{j \in e,\; j \neq i} x_j,

via power iteration. Works for hypergraphs with mixed edge sizes.

H-eigenvector centrality (HEC): solves the power-k-1 eigen-equation,

\lambda\, x_i^{k-1} \;=\; \sum_{e \ni i}\; \prod_{j \in e,\; j \neq i} x_j.

For uniform hypergraphs (all hyperedges of size k), this is equivalent to normalizing the ZEC update by the geometric-mean exponent 1/(k-1). For mixed sizes, the effective exponent is taken from the largest hyperedge; expect slightly different rankings from ZEC in the mixed case.

Value

A named list; one component per requested type. Each component is a named numeric vector of length hg$n_nodes.

Note

The "clique" (CEC) variant is validated against igraph::eigen_centrality (cosine ~ 1). The "Z" and "H" variants are (experimental) — validated only against a clean-room list-based tensor power iteration (same operator, different loop structure); no R package exposes tensor eigenvectors as a primitive for independent comparison.

References

Benson, A. R. (2019). Three hypergraph eigenvector centralities. SIAM Journal on Mathematics of Data Science 1(2), 293-312. arXiv:1807.09644.

See Also

build_hypergraph(), clique_expansion(), hypergraph_measures().

Examples

df <- data.frame(
  player  = c("A", "B", "C", "A", "B", "D", "C", "D", "E"),
  session = c("S1", "S1", "S1", "S2", "S2", "S3", "S3", "S3", "S3")
)
hg <- bipartite_groups(df, "player", "session")
cent <- hypergraph_centrality(hg)
# Compare rankings across the three variants
do.call(cbind, cent)

Structural measures for a hypergraph

Description

Computes a comprehensive structural-statistics suite for a net_hypergraph: node-level, hyperedge-level, and global measures. All measures are derived in a few BLAS calls on the incidence matrix.

Usage

hypergraph_measures(hg)

## S3 method for class 'hypergraph_measures'
print(x, ...)

Arguments

Details

All measures are computed via standard matrix operations on the binary incidence B = (b_{ij}) where b_{ij} = 1 iff node i is in hyperedge j:

• hyperdegree = rowSums(B), edge_sizes = colSums(B)

• co_degree = tcrossprod(B) (with zero diagonal)

• edge_pairwise_overlap = crossprod(B) (with zero diagonal)

• overlap_coefficient[i, j] = overlap[i, j] / min(edge_sizes[i], edge_sizes[j])

• jaccard[i, j] = overlap[i, j] / (edge_sizes[i] + edge_sizes[j] - overlap[i, j])

Empty hypergraph (n_hyperedges == 0) returns trivial zeros and empty matrices.

Value

An object of class hypergraph_measures (a named list) with components:

Node-level (length n_nodes)

hyperdegree

Number of hyperedges containing each node.

node_strength

Total participation: for node i, \sum_{e \ni i} |e|. A node in many large hyperedges has high strength.

max_edge_size

Size of the largest hyperedge containing each node.

co_degree

n_nodes x n_nodes matrix: ⁠co_degree[i, j] = |{e : i, j in e}|⁠ (number of hyperedges co-containing nodes i and j). Diagonal is zero.

Hyperedge-level (length n_hyperedges or m x m)

edge_sizes

Hyperedge sizes |e|.

edge_pairwise_overlap

m x m matrix: ⁠|e_i intersect e_j|⁠. Diagonal is zero.

overlap_coefficient

m x m: ⁠|e_i and e_j| / min(|e_i|, |e_j|)⁠. Measures how much the smaller hyperedge is contained in the larger.

jaccard

m x m: symmetric overlap index ⁠|e_i and e_j| / |e_i union e_j|⁠.

Global (scalars)

density

For k-uniform hypergraphs: m / choose(n, k). For mixed sizes: ⁠sum(|e|) / (n * m)⁠ (mean fraction of nodes per hyperedge).

avg_edge_size

Mean of edge_sizes.

size_distribution

Tabulation of hyperedge sizes (passed through from hg).

intersection_profile

Distribution of pairwise hyperedge intersection sizes — useful for spotting whether hyperedges overlap mostly trivially or share substantial cores (Do et al. 2020).

pairwise_participation

Fraction of node pairs co-appearing in at least one hyperedge.

n_nodes, n_hyperedges

Convenience scalars.

The input x invisibly.

References

Lee, G., Choe, M., & Shin, K. (2024). A survey on hypergraph representation, learning and mining. Data Mining & Knowledge Discovery 37, 1-39.

Do, M. T., Yoon, S., Hooi, B., & Shin, K. (2020). Structural patterns and generative models of real-world hypergraphs. arXiv:2006.07060.

See Also

build_hypergraph(), bipartite_groups(), clique_expansion().

Examples

df <- data.frame(
  player  = c("A", "B", "C", "A", "B", "D", "C", "D"),
  session = c("S1", "S1", "S1", "S2", "S2", "S3", "S3", "S3")
)
hg <- bipartite_groups(df, "player", "session")
m  <- hypergraph_measures(hg)
print(m)
m$hyperdegree         # how many sessions each player joined
m$co_degree           # pairwise co-membership counts
m$jaccard             # symmetric overlap between sessions

Online Learning Activity Indicators

Description

Simulated binary time-series data for 200 students across 30 time points. At each time point, one or more learning activities may be active (1) or inactive (0). Activities: Reading, Video, Forum, Quiz, Coding, Review. Includes temporal persistence (activities tend to continue across adjacent time points).

Usage

learning_activities

Format

A data frame with 6,000 rows and 7 columns:

student

Integer. Student identifier (1–200).

Reading

Integer (0/1). Reading activity indicator.

Video

Integer (0/1). Video watching indicator.

Forum

Integer (0/1). Discussion forum indicator.

Quiz

Integer (0/1). Quiz/assessment indicator.

Coding

Integer (0/1). Coding practice indicator.

Review

Integer (0/1). Review/revision indicator.

Examples

head(learning_activities)

List All Registered Estimators

Description

Return a data frame summarising all registered network estimators.

Usage

list_estimators()

Value

A data frame with columns name, description, directed.

See Also

register_estimator, get_estimator

Examples

list_estimators()

Human-AI Vibe Coding Interaction Data (Long Format)

Description

Coded interaction sequences from 429 human-AI pair programming sessions across 34 projects, in long format.

Usage

human_long

ai_long

Format

Data frames in long format with 9 columns:

message_id

Integer. Turn index.

project

Character. Project identifier (Project_1 .. Project_34).

session_id

Character. Unique session hash.

timestamp

Integer. Unix timestamp for ordering.

session_date

Character. Date of the session (YYYY-MM-DD).

code

Character. Interaction code (17 action labels).

cluster

Character. High-level cluster: Action, Communication, Directive, Evaluative, Metacognitive, or Repair.

code_order

Integer. Order of the code within the session.

order_in_session

Integer. Absolute turn order within the session.

An object of class data.frame with 10796 rows and 9 columns.

An object of class data.frame with 8551 rows and 9 columns.

Source

Saqr, M. (2026). Human-AI vibe coding interaction study. https://saqr.me/blog/2026/human-ai-interaction-cograph/

Examples

net <- build_network(human_long, method = "tna",
                     action = "code", actor = "session_id",
                     time = "timestamp")
net

Convert Long Format to Wide Sequences

Description

Convert sequence data from long format (one row per action) to wide format (one row per sequence, columns as time points).

Usage

long_to_wide(
  data,
  id_col = "Actor",
  time_col = "Time",
  action_col = "Action",
  time_prefix = "V",
  fill_na = TRUE
)

Arguments

Details

This function converts long format data (like that from simulate_long_data()) to the wide format expected by tna::tna() and related functions.

If time_col contains non-integer values (e.g., timestamps), the function will use the ordering within each sequence to create time indices.

Value

A data frame in wide format where each row is a sequence and columns V1, V2, ... contain the actions at each time point.

See Also

wide_to_long for the reverse conversion, prepare_for_tna for preparing data for TNA analysis.

Examples

long_data <- data.frame(
  Actor = rep(1:3, each = 4),
  Time = rep(1:4, 3),
  Action = sample(c("A", "B", "C"), 12, replace = TRUE)
)
wide_data <- long_to_wide(long_data, id_col = "Actor")
head(wide_data)

Magnitude difference between the frequency and probability views

Description

Quantifies, per edge, how much row-normalization moves a transition network between its two natural summaries: raw transition counts (frequency / FTNA, build_network(method = "frequency")) and row-conditional probabilities (TNA, build_network(method = "relative")). The two matrices rank edges differently — an edge that is large in counts can be modest in probability, and a rare-source edge can dominate its row in probability. The per-edge discrepancy on a common scale is the magnitude difference.

Usage

magnitude_difference(
  data,
  actor = "Actor",
  action = "Action",
  time = NULL,
  metric = c("abs_diff", "chord_dist", "atanh_diff", "geom_norm_diff", "cv_inflation"),
  scale = c("tna_range", "rank_minmax", "minmax", "none"),
  format = c("auto", "long", "wide")
)

## S3 method for class 'magnitude_difference'
print(x, ...)

## S3 method for class 'magnitude_difference'
plot(x, type = c("stacked", "circular"), min_show = 0.01, title = NULL, ...)

Arguments

Value

An object of class "magnitude_difference": a list with ⁠$edges⁠ (per-edge data.frame with columns from, to, ftna, tna, signed = tna - ftna, and value = the chosen metric), ⁠$metric⁠, ⁠$scale⁠, ⁠$weights_ftna⁠, ⁠$weights_tna⁠, and ⁠$states⁠.

print invisibly returns x.

plot returns a ggplot object.

Methods (by generic)

• print(magnitude_difference): Print a compact summary of the per-edge magnitude-difference distribution.

• plot(magnitude_difference): Plot the per-edge magnitude difference as a polar portrait. type = "stacked" (default) draws one sector per from-state with stacked wedges (grey base = shared value, colored tip = magnitude difference); type = "circular" draws a chord-style diagram with signed differences on a diverging blue-orange scale.

See Also

build_network(), compare_model()

Examples

data(group_regulation_long, package = "Nestimate")
fit <- magnitude_difference(group_regulation_long,
                            actor = "Actor", action = "Action",
                            time = "Time")
print(fit)
# Edges most promoted by row-normalization (rare-source transitions):
head(fit$edges[order(-fit$edges$signed), c("from", "to", "ftna", "tna")])

plot(fit)                       # stacked polar portrait
plot(fit, type = "circular")    # chord-style diagram

Mark leading-NA cells with an explicit state label.

Description

Mirror of mark_terminal_state() for left-censored sequence data. Replaces every cell before each row's first observed state with the label given by state. The resulting chain has a structurally recurrent "Start" state that everyone enters from — useful for cohort-entry analyses where students join at different time points and you want a uniform pre-observation marker.

Usage

mark_first_state(data, state = "Start", cols = NULL)

Arguments

Details

Unlike mark_terminal_state(), the marked state is not absorbing in the resulting transition matrix — every transition from "Start" goes to one of the original states (the actor's first observed state), and the "Start" row is row-stochastic exactly as the data dictates.

Value

A data.frame of the same shape as data with leading NAs filled by state.

See Also

mark_terminal_state(), actor_endpoints()

Examples

M <- mark_first_state(trajectories, state = "Start")
# In a chain built from M, "Start" is a transient entry point.

Mark terminal-NA cells with an explicit state label.

Description

Replaces every cell after each row's last observed state with the label given by state, leaving non-terminal NAs untouched. The result, passed to build_network(), yields a Markov chain in which the marked state is absorbing by construction (P[state, state] = 1).

Usage

mark_terminal_state(data, state = "End", cols = NULL)

Arguments

Details

This is the small piece of pre-processing required to turn right-censored sequence data into an absorbing-chain model. The chain on the resulting matrix has one extra state (state) which is structurally absorbing because every cell after the actor's last observed step has been set to state — the chain stays there forever once entered.

Use chain_structure() on the result to compute mean absorption time, absorption probabilities, and per-state classification. Note that markov_stability() is not the right summary for absorbing chains; its stationary distribution will collapse to the absorbing state.

Value

A data.frame of the same shape as data with terminal NAs filled by state.

See Also

actor_endpoints(), chain_structure(), build_network()

Examples

M <- mark_terminal_state(trajectories, state = "Dropout")
net <- build_network(M, method = "relative")
chain_structure(net)

Test the Markov order of a sequential process

Description

Principled test of whether a categorical sequence is best described as a k-th order Markov chain. At each order k = 1, \ldots, max_order, the function computes the classical likelihood-ratio statistic (G^2) for the conditional independence s \perp x \mid w, where w is the (k-1)-gram context, x is the extra (k-th-back) state added at order k, and s is the next state. Under H_0 (order-(k-1) is correct), s is independent of x given w.

The null distribution is obtained by an exact within-w permutation test: for each context w the successor labels are exchangeable under H_0, so shuffling s within each w-group yields an exact reference distribution for G^2. No plug-in MLE bias and no refitting per replicate. An asymptotic \chi^2 p-value is reported alongside for reference.

The optimal order is the smallest k that is not significantly better than k - 1 at level alpha: we keep raising the order while the test rejects, and stop at the first non-rejection.

Usage

markov_order_test(
  data,
  max_order = 3L,
  n_perm = 500L,
  alpha = 0.05,
  parallel = FALSE,
  n_cores = 2L,
  seed = NULL
)

Arguments

Value

An object of class net_markov_order with elements:

optimal_order

Integer. Selected order via sequential permutation test.

bic_order

Integer. Order minimising BIC (reported by print/plot; not used in the permutation selection).

aic_order

Integer. Order minimising AIC (reported by print/plot; not used in the permutation selection).

test_table

Tidy data.frame, one row per order tested with columns order, loglik, AIC, BIC, df, g2, p_permutation, p_asymptotic, significant. AIC/BIC are the information-criterion values used for the ic plot panel and to derive aic_order/bic_order; the order-0 row has NA for the test columns (df, g2, p_permutation, p_asymptotic, significant).

permutation_null

List of numeric vectors (length max_order), one empirical null G^2 distribution per order.

logliks

Named numeric vector of log-likelihoods per order (for AIC / BIC panel only, not used in the test).

layer_dofs

Named integer vector of model degrees of freedom per order (free parameters added at each layer), used to compute the AIC / BIC columns.

transition_matrices

List of fitted transition matrices.

states

Character vector of observed state labels.

n_sequences, n_observations

Data summary.

n_perm, alpha, max_order

Call settings.

Examples

# First-order Markov data: test should select order 1
set.seed(1)
states <- letters[1:4]
tm <- matrix(runif(16), 4, 4, dimnames = list(states, states))
tm <- tm / rowSums(tm)
seqs <- lapply(1:30, function(.) {
  s <- character(50); s[1] <- sample(states, 1)
  for (i in 2:50) s[i] <- sample(states, 1, prob = tm[s[i - 1], ])
  s
})
res <- markov_order_test(seqs, max_order = 3, n_perm = 300, seed = 1)
res$optimal_order
summary(res)
plot(res)

Markov Stability Analysis

Description

Computes per-state stability metrics from a transition network: persistence (self-loop probability), stationary distribution, mean recurrence time, sojourn time, and mean accessibility to/from other states.

Usage

markov_stability(x, normalize = TRUE)

## S3 method for class 'net_markov_stability'
plot(
  x,
  metrics = c("persistence", "stationary_prob", "return_time", "sojourn_time",
    "avg_time_to_others", "avg_time_from_others"),
  combined = TRUE,
  ...
)

Arguments

Details

Sojourn time is the expected consecutive time steps spent in a state before leaving: 1/(1-P_{ii}). States with persistence = 1 have sojourn_time = Inf.

avg_time_to_others: mean passage time from this state to all others; reflects how "sticky" or "isolated" the state is.

avg_time_from_others: mean passage time from all other states to this one; reflects accessibility (attractor strength).

Value

An object of class "net_markov_stability" with:

stability

Data frame with one row per state and columns: state, persistence (P_{ii}), stationary_prob (\pi_i), return_time (1/\pi_i), sojourn_time (1/(1-P_{ii})), avg_time_to_others (mean MFPT leaving state i), avg_time_from_others (mean MFPT arriving at state i).

mpt

The underlying net_mpt object.

See Also

passage_time

Examples

net <- build_network(as.data.frame(trajectories), method = "relative")
ms  <- markov_stability(net)
print(ms)

plot(ms)

Extract Transition Table from a MOGen Model

Description

Returns a data frame of all transitions at a given Markov order, sorted by count (descending). Each row shows the full path as a readable sequence of states, along with the observed count and transition probability.

Usage

mogen_transitions(x, order = NULL, min_count = 1L)

Arguments

Details

At order k, each edge in the De Bruijn graph represents a (k+1)-step path. For example, at order 2, the edge from node "AI -> FAIL" to node "FAIL -> SOLVE" represents the three-step path AI -> FAIL -> SOLVE. The path column reconstructs this full sequence for readability.

Value

A data frame with columns:

path

The full state sequence (e.g., "AI -> FAIL -> SOLVE").

count

Number of times this transition was observed.

probability

Transition probability P(to | from).

from

The context / conditioning states (k-gram source node).

to

The predicted next state.

Examples

seqs <- list(c("A","B","C","D"), c("A","B","C","A"), c("B","C","D","A"))
mg <- build_mogen(seqs, max_order = 2)
mogen_transitions(mg, order = 1)


trajs <- list(c("A","B","C","D"), c("A","B","D","C"),
              c("B","C","D","A"), c("C","D","A","B"))
m <- build_mogen(trajs, max_order = 3)
mogen_transitions(m, order = 1)

Mosaic Plot of a Network's Transition or Co-occurrence Counts

Description

Draws a Hartigan-Friendly mosaic (marimekko geometry, chi-square standardized-residual fill) for an integer-weighted network. Equivalent in algorithm and appearance to tna::plot_mosaic(); named differently to avoid an export clash when both packages are attached.

Usage

mosaic_plot(x, ...)

## Default S3 method:
mosaic_plot(x, ...)

## S3 method for class 'netobject'
mosaic_plot(
  x,
  xlab = NULL,
  ylab = NULL,
  range = NULL,
  top_angle = NULL,
  left_angle = NULL,
  residuals = c("permutation", "asymptotic"),
  n_perm = 500L,
  seed = NULL,
  values = FALSE,
  ...
)

## S3 method for class 'htna'
mosaic_plot(
  x,
  xlab = NULL,
  ylab = NULL,
  range = NULL,
  top_angle = NULL,
  left_angle = NULL,
  residuals = c("permutation", "asymptotic"),
  n_perm = 500L,
  seed = NULL,
  values = FALSE,
  ...
)

## S3 method for class 'mcml'
mosaic_plot(
  x,
  level = c("macro", "clusters"),
  xlab = NULL,
  ylab = NULL,
  range = NULL,
  top_angle = NULL,
  left_angle = NULL,
  residuals = c("permutation", "asymptotic"),
  n_perm = 500L,
  seed = NULL,
  ncol = 2L,
  values = FALSE,
  ...
)

## S3 method for class 'netobject_group'
mosaic_plot(
  x,
  xlab = NULL,
  ylab = NULL,
  range = NULL,
  top_angle = NULL,
  left_angle = NULL,
  residuals = c("permutation", "asymptotic"),
  n_perm = 500L,
  seed = NULL,
  ncol = 2L,
  values = FALSE,
  ...
)

## S3 method for class 'table'
mosaic_plot(
  x,
  xlab = "Row",
  ylab = "Column",
  range = NULL,
  top_angle = NULL,
  left_angle = NULL,
  residuals = c("permutation", "asymptotic"),
  n_perm = 500L,
  seed = NULL,
  values = FALSE,
  ...
)

## S3 method for class 'matrix'
mosaic_plot(x, ...)

Arguments

Details

Column widths are proportional to row marginals of the weight matrix (incoming totals when the matrix is transposed, as for transitions). Within each column, segment heights are proportional to that row's conditional distribution. Cell fill is the standardized residual from stats::chisq.test(), with a diverging palette clipped to \pm 4. Mosaics need integer counts: when $weights is already integer (method = "frequency" / "co_occurrence") it is used directly; for a single netobject / htna otherwise (relative, glasso, cor, ...) order-1 transition counts are recounted from the raw $data sequences. The function errors only when neither integer weights nor $data are available.

Value

A ggplot object (or a gtable from gridExtra::arrangeGrob for netobject_group when gridExtra is available).

See Also

plot_mosaic for the lower-level data.frame primitive.

Examples

## Not run: 
  net <- build_network(group_regulation, method = "frequency")
  mosaic_plot(net)

## End(Not run)

Network Comparison Test

Description

Tests whether two networks estimated from independent samples differ at three levels: global strength (M-statistic), network structure (S-statistic, max absolute edge difference), and individual edges (E-statistic per edge). Inference is via permutation of group labels.

Usage

nct(
  data1,
  data2,
  iter = 1000L,
  gamma = 0.5,
  paired = FALSE,
  abs = TRUE,
  weighted = TRUE,
  p_adjust = "none"
)

Arguments

Details

Implementation matches NetworkComparisonTest::NCT() with defaults abs = TRUE, weighted = TRUE, paired = FALSE at machine precision when the same seed is used. The network estimator is EBIC-selected glasso applied to a Pearson correlation matrix, with Matrix::nearPD symmetrization (matching NCT's NCT_estimator_GGM default).

Value

A list of class net_nct with elements:

nw1, nw2

Estimated weighted adjacency matrices.

M

List with observed, perm, p_value for the global strength test.

S

Same structure for the maximum absolute edge difference.

E

Same structure for per-edge tests.

n_iter

Number of permutations.

paired

Whether a paired test was used.

Examples

## Not run: 
set.seed(1)
x1 <- matrix(rnorm(200 * 5), 200, 5)
x2 <- matrix(rnorm(200 * 5), 200, 5)
colnames(x1) <- colnames(x2) <- paste0("V", 1:5)
res <- nct(x1, x2, iter = 100)
res$M$p_value
res$S$p_value

## End(Not run)

Aggregate Edge Weights

Description

Aggregates a vector of edge weights using various methods. Compatible with igraph's edge.attr.comb parameter.

Usage

net_aggregate_weights(w, method = "sum", n_possible = NULL)

Arguments

Value

Single aggregated value

Examples

w <- c(0.5, 0.8, 0.3, 0.9)
net_aggregate_weights(w, "sum")   # 2.5
net_aggregate_weights(w, "mean")  # 0.625
net_aggregate_weights(w, "max")   # 0.9
net_aggregate_weights(w, "density", n_possible = 9)  # 2.5 / 9

Compute Centrality Measures for a Network

Description

Computes centrality measures from a netobject, netobject_group, or cograph_network. For directed networks the default measures are InStrength, OutStrength, and Betweenness. For undirected networks the defaults are Closeness and Betweenness.

Usage

net_centrality(x, measures = NULL, loops = FALSE, centrality_fn = NULL, ...)

Arguments

Value

For a netobject: a data frame with node names as rows and centrality measures as columns. For a netobject_group: a named list of such data frames (one per group).

Examples

seqs <- data.frame(
  V1 = c("A","B","A","C"), V2 = c("B","C","B","A"),
  V3 = c("C","A","C","B"))
net <- build_network(seqs, method = "relative")
net_centrality(net)

Split-Half Reliability for Network Estimates

Description

Assesses the stability of network estimates by repeatedly splitting sequences into two halves, building networks from each half, and comparing them. Supports single-model reliability assessment and multi-model comparison with optional scaling for cross-method comparability.

For transition methods ("relative", "frequency", "co_occurrence"), uses pre-computed per-sequence count matrices for fast resampling (same infrastructure as bootstrap_network).

Usage

network_reliability(
  ...,
  iter = 1000L,
  split = 0.5,
  scale = "none",
  seed = NULL
)

Arguments

Value

An object of class "net_reliability" containing:

iterations

Data frame with columns model, mean_dev, median_dev, cor, max_dev (one row per iteration per model).

summary

Data frame with columns model, metric, mean, sd.

models

Named list of the original netobjects.

iter

Number of iterations.

split

Split fraction.

scale

Scaling method used.

See Also

build_network, bootstrap_network

Examples

net <- build_network(data.frame(V1 = c("A","B","C","A"),
  V2 = c("B","C","A","B")), method = "relative")
rel <- network_reliability(net, iter = 10)

seqs <- data.frame(
  V1 = sample(LETTERS[1:4], 30, TRUE), V2 = sample(LETTERS[1:4], 30, TRUE),
  V3 = sample(LETTERS[1:4], 30, TRUE), V4 = sample(LETTERS[1:4], 30, TRUE)
)
net <- build_network(seqs, method = "relative")
rel <- network_reliability(net, iter = 100, seed = 42)
print(rel)

Mean First Passage Times

Description

Computes the full matrix of mean first passage times (MFPT) for a Markov chain. Element M_{ij} is the expected number of steps to travel from state i to state j for the first time. The diagonal equals the mean recurrence time 1/\pi_i.

Usage

passage_time(x, states = NULL, normalize = TRUE)

## S3 method for class 'net_mpt'
summary(object, ...)

## S3 method for class 'net_mpt'
plot(
  x,
  log_scale = TRUE,
  digits = 1,
  title = "Mean First Passage Times",
  low = "#004d00",
  high = "#ccffcc",
  ...
)

Arguments

Details

Uses the Kemeny-Snell fundamental matrix formula:

M_{ij} = \frac{Z_{jj} - Z_{ij}}{\pi_j}, \quad Z = (I - P + \Pi)^{-1}

where \Pi_{ij} = \pi_j. Requires an ergodic (irreducible, aperiodic) chain.

Value

An object of class "net_mpt" with:

matrix

Full n \times n MFPT matrix. Row i, column j = expected steps from state i to state j. Diagonal = mean recurrence time 1/\pi_i.

stationary

Named numeric vector: stationary distribution \pi.

return_times

Named numeric vector: 1/\pi_i per state.

states

Character vector of state names.

summary.net_mpt returns a data frame with one row per state and columns state, return_time, stationary, mean_out (mean steps to other states), mean_in (mean steps from other states).

References

Kemeny, J.G. and Snell, J.L. (1976). Finite Markov Chains. Springer-Verlag.

See Also

markov_stability, build_network

Examples

net <- build_network(as.data.frame(trajectories), method = "relative")
pt  <- passage_time(net)
print(pt)

plot(pt)

Count Path Frequencies in Trajectory Data

Description

Counts the frequency of k-step paths (k-grams) across all trajectories. Useful for understanding which sequences dominate the data before applying formal models.

Usage

path_counts(data, k = 2L, top = NULL)

Arguments

Value

A data frame with columns: path, count, proportion.

Examples

trajs <- list(c("A","B","C","D"), c("A","B","D","C"))
path_counts(trajs, k = 2)


path_counts(trajs, k = 3, top = 10)

Per-Context Path Dependence at Order k

Description

Diagnoses where a chain's order-1 Markov assumption fails by comparing, for each order-k context (s_1, \ldots, s_{k-1}), the empirical next-state distribution P(s_k \mid s_1, \ldots, s_{k-1}) against the order-1 prediction P(s_k \mid s_{k-1}) that uses only the most recent state. Returns a tidy per-context table sorted by Kullback-Leibler divergence so the analyst can see exactly which histories carry extra predictive information.

Usage

path_dependence(x, order = 2L, min_count = 5L, base = 2)

Arguments

Details

For each context c = (s_1, \ldots, s_{k-1}) occurring at least min_count times, the function computes:

• the empirical conditional P_k(\cdot \mid c) from k-gram counts;

• the order-1 prediction P_1(\cdot \mid s_{k-1}) from the most recent state alone (the bigram-marginal estimator);

• the entropy drop H(P_1) - H(P_k) - bits of uncertainty removed by extending memory by one step in this specific context;

• the Kullback-Leibler divergence D_{KL}(P_k \,\|\, P_1) - bits of "surprise" if you used the order-1 model when the order-k model is true.

KL = 0 means longer history adds no information for that context. H_drop > 0 means longer history sharpens the prediction; H_drop < 0 indicates the order-k context happens to spread probability across more outcomes than order-1 alone (small-sample noise or genuine context-induced uncertainty - inspect n).

Contexts where flips = TRUE are the substantively interesting ones: the longer history changes the modal prediction, not just its confidence.

Pair this with markov_order_test (which decides whether order-k is needed globally) to see the chain-level decision broken down per context.

Value

An object of class "net_path_dependence" with

contexts

tidy data.frame, one row per order-k context, sorted by KL descending. Columns: context (e.g. "A -> B"), n (count), H_order1 (entropy of P(\cdot \mid s_{k-1})), H_orderk (entropy of P(\cdot \mid \mathrm{context})), H_drop (= H_order1 - H_orderk), KL (= D_{KL}(P_k \| P_1)), top_o1 (most likely next state under order-1), top_ok (most likely next state under order-k), flips (logical: did the most likely next state change?).

chain

list with chain-level summaries: KL_weighted (count-weighted mean KL across contexts), H_drop_weighted (count-weighted mean entropy drop), n_contexts, n_flips (contexts where the most-likely next state changed).

order

integer

base

numeric

min_count

integer

states

character vector

References

Cover, T.M. & Thomas, J.A. (2006). Elements of Information Theory, 2nd ed., chapters 2 and 4. Wiley. (KL divergence and conditional entropy.)

See Also

markov_order_test, transition_entropy, build_mogen

Examples

data(trajectories, package = "Nestimate")
pd <- path_dependence(as.data.frame(trajectories), order = 2)
print(pd)
summary(pd)
plot(pd)

Extract Pathways from Higher-Order Network Objects

Description

Extracts higher-order pathway strings suitable for cograph::plot_simplicial(). Each pathway represents a multi-step dependency: source states lead to a target state.

For net_hon: extracts edges where the source node is higher-order (order > 1), i.e., the transitions that differ from first-order Markov.

For net_hypa: extracts anomalous paths (over- or under-represented relative to the hypergeometric null model).

For net_mogen: extracts all transitions at the optimal order (or a specified order).

Usage

pathways(x, ...)

## S3 method for class 'net_hon'
pathways(x, min_count = 1L, min_prob = 0, top = NULL, order = NULL, ...)

## S3 method for class 'net_hypa'
pathways(x, type = "all", ...)

## S3 method for class 'netobject'
pathways(x, ho_method = c("hon", "hypa"), ...)

## S3 method for class 'net_association_rules'
pathways(x, top = NULL, min_lift = NULL, min_confidence = NULL, ...)

## S3 method for class 'net_link_prediction'
pathways(x, method = NULL, top = 10L, evidence = TRUE, max_evidence = 3L, ...)

## S3 method for class 'net_mogen'
pathways(x, order = NULL, min_count = 1L, min_prob = 0, top = NULL, ...)

Arguments

Value

A character vector of pathway strings in arrow notation (e.g. "A B -> C"), suitable for cograph::plot_simplicial().

A character vector of pathway strings.

A character vector of pathway strings.

A character vector of pathway strings.

A character vector of pathway strings.

A character vector of pathway strings.

A character vector of pathway strings.

Methods (by class)

• pathways(net_hon): Extract higher-order pathways from HON

• pathways(net_hypa): Extract anomalous pathways from HYPA

• pathways(netobject): Extract pathways from a netobject

  Builds a Higher-Order Network (HON) from the netobject's sequence data and returns the higher-order pathways. Requires that the netobject was built from sequence data (has $data).

• pathways(net_association_rules): Extract pathways from association rules

  Converts association rules {A, B} => {C} into pathway strings "A B -> C" suitable for cograph::plot_simplicial(). Antecedent items become source nodes; consequent items become the target.

• pathways(net_link_prediction): Extract pathways from link predictions

  Converts predicted links into pathway strings for cograph::plot_simplicial(). When evidence = TRUE (default), each predicted edge A -> B is enriched with common neighbors that structurally support the prediction, producing "A cn1 cn2 -> B".

• pathways(net_mogen): Extract transition pathways from MOGen

Examples

seqs <- list(c("A","B","C","D"), c("A","B","C","A"))
hon <- build_hon(seqs, max_order = 3)
pw <- pathways(hon)


trans <- list(c("A","B","C"), c("A","B"), c("B","C","D"), c("A","C","D"))
rules <- association_rules(trans, min_support = 0.3, min_confidence = 0.3,
                           min_lift = 0)
pathways(rules)

seqs <- data.frame(
  V1 = sample(LETTERS[1:5], 50, TRUE),
  V2 = sample(LETTERS[1:5], 50, TRUE),
  V3 = sample(LETTERS[1:5], 50, TRUE)
)
net <- build_network(seqs, method = "relative")
pred <- predict_links(net, methods = "common_neighbors")
pathways(pred)

Permutation Test for Network Comparison

Description

Compares two networks estimated by build_network using a permutation test. Works with all built-in methods (transition and association) as well as custom registered estimators. The test shuffles which observations belong to which group, re-estimates networks, and tests whether observed edge-wise differences exceed chance.

For transition methods ("relative", "frequency", "co_occurrence"), uses a fast pre-computation strategy: per-sequence count matrices are computed once, and each permutation iteration only shuffles group labels and computes group-wise colSums.

For association methods ("cor", "pcor", "glasso", and custom estimators), the full estimator is called on each permuted group split.

If either transition network contains only one sequence, the function warns that such a network is not recommended for permutation or other confirmatory testing.

Usage

permutation(
  x,
  y = NULL,
  iter = 1000L,
  alpha = 0.05,
  paired = FALSE,
  adjust = "none",
  nlambda = 50L,
  seed = NULL
)

Arguments

Value

An object of class "net_permutation" containing:

x

The first netobject.

y

The second netobject.

diff

Observed difference matrix (x - y).

diff_sig

Observed difference where p < alpha, else 0.

p_values

P-value matrix (adjusted if adjust != "none").

effect_size

Effect size matrix (observed diff / SD of permutation diffs).

summary

Long-format data frame of edge-level results.

method

The network estimation method.

iter

Number of permutation iterations.

alpha

Significance level used.

paired

Whether paired permutation was used.

adjust

p-value adjustment method used.

See Also

build_network, bootstrap_network, print.net_permutation, summary.net_permutation

Examples

s1 <- data.frame(V1 = c("A","B","C"), V2 = c("B","C","A"))
s2 <- data.frame(V1 = c("A","C","B"), V2 = c("C","B","A"))
n1 <- build_network(s1, method = "relative")
n2 <- build_network(s2, method = "relative")
perm <- permutation(n1, n2, iter = 10)

set.seed(1)
d1 <- data.frame(V1 = sample(LETTERS[1:4], 20, TRUE),
                 V2 = sample(LETTERS[1:4], 20, TRUE),
                 V3 = sample(LETTERS[1:4], 20, TRUE))
d2 <- data.frame(V1 = sample(LETTERS[1:4], 20, TRUE),
                 V2 = sample(LETTERS[1:4], 20, TRUE),
                 V3 = sample(LETTERS[1:4], 20, TRUE))
net1 <- build_network(d1, method = "relative")
net2 <- build_network(d2, method = "relative")
perm <- permutation(net1, net2, iter = 100, seed = 42)
print(perm)
summary(perm)

Persistence Landscape

Description

Computes the persistence landscape (Bubenik 2015) from a persistence diagram. Each (birth, death) pair contributes a tent function

\Lambda_{(b,d)}(t) = \max(0, \min(t - b, d - t)).

The k-th landscape function \lambda^{(k)}(t) is the k-th largest of \{\Lambda_{(b_i,d_i)}(t)\}_i at each t. Landscapes are stable under bottleneck distance and form a Banach-space embedding of persistence diagrams.

Usage

persistence_landscape(ph, k_max = 5L, dimension = 1L, t_grid = NULL)

Arguments

Value

A persistence_landscape object with:

landscape

Data frame: k, t, value.

dimension

Integer scalar.

k_max

Integer scalar.

t_grid

Numeric vector.

References

Bubenik, P. (2015). Statistical topological data analysis using persistence landscapes. Journal of Machine Learning Research 16, 77-102.

Examples

mat <- matrix(c(0, .6, .5, .6, 0, .4, .5, .4, 0), 3, 3)
rownames(mat) <- colnames(mat) <- c("A","B","C")
ph <- persistent_homology(mat, n_steps = 5)
pl <- persistence_landscape(ph, k_max = 3, dimension = 0)

Persistent Homology

Description

Computes persistent homology via full boundary-matrix reduction over \mathbb{Z}/2 (Edelsbrunner, Letscher & Zomorodian 2000). The returned persistence diagram pairs each k-dimensional homology class to the simplex whose addition creates it (birth) and the simplex whose addition destroys it (death). Essential classes — those never killed — are reported with death = 0 in clique mode (similarity scale, descending) and death = Inf in VR mode (distance scale, ascending).

Two filtration modes are supported:

type = "clique"

Weighted clique filtration. Input is treated as a similarity matrix; high-weight simplices appear early. For each k-simplex \sigma, the filtration value is \min_{(i,j) \in \sigma}\,|w(i,j)|. Thresholds run high to low.

type = "vr"

Vietoris-Rips filtration on a non-negative distance matrix. For each k-simplex \sigma, the filtration value is \max_{(i,j) \in \sigma}\,d(i,j). Thresholds run low to high. Use max_scale to cap the filtration diameter.

Usage

persistent_homology(
  x,
  n_steps = 20L,
  max_dim = 3L,
  type = "clique",
  max_scale = NULL
)

Arguments

Value

A persistent_homology object with:

betti_curve

Data frame: threshold, dimension, betti.

persistence

Data frame of birth-death pairs: dimension, birth, death, persistence. Sorted by descending persistence.

thresholds

Numeric vector of grid thresholds.

mode

Either "clique" or "vr".

References

Edelsbrunner, H., Letscher, D., & Zomorodian, A. (2000). Topological persistence and simplification. Discrete & Computational Geometry 28, 511-533.

Examples

mat <- matrix(c(0,.6,.5,.6,0,.4,.5,.4,0), 3, 3)
colnames(mat) <- rownames(mat) <- c("A","B","C")
ph <- persistent_homology(mat, n_steps = 10)
print(ph)

Plot Method for boot_glasso

Description

Plots bootstrap results for GLASSO networks.

Usage

## S3 method for class 'boot_glasso'
plot(x, type = "edges", measure = NULL, ...)

Arguments

Value

A ggplot object, invisibly.

Examples

set.seed(1)
dat <- as.data.frame(matrix(rnorm(60), ncol = 3))
bg <- boot_glasso(dat, iter = 10, cs_iter = 5, centrality = "strength")
plot(bg, type = "edges")

set.seed(42)
mat <- matrix(rnorm(60), ncol = 4)
colnames(mat) <- LETTERS[1:4]
boot <- boot_glasso(as.data.frame(mat), iter = 20, cs_iter = 10,
  centrality = "strength", seed = 42)
plot(boot, type = "edges")

Plot method for chain_structure.

Description

Renders the hitting-probability matrix as a heatmap, with rows and columns ordered by communicating class so the block structure is visible at a glance. State labels along both axes are coloured by classification (absorbing / recurrent / transient). The subtitle summarises the chain-level properties (regular, reversible).

Usage

## S3 method for class 'chain_structure'
plot(x, show_values = TRUE, digits = 2L, ...)

Arguments

Details

Cell colour encodes ⁠P(ever reach j | start at i)⁠. The diagonal uses the return-time convention (⁠P(return to j in >= 1 steps)⁠), matching markovchain::hittingProbabilities. A non-irreducible chain shows zero off-block entries – visual evidence of one-way doors between behavioural phases. An absorbing chain shows a column of 1's for the absorbing state.

Value

A ggplot object.

Plot Method for cluster_choice

Description

Six explicit chart types plus a smart "auto" default. The user picks the shape; the function does not editorialise (no "best" annotation, no interpretive subtitles, no inferred recommendation).

Usage

## S3 method for class 'cluster_choice'
plot(
  x,
  type = c("auto", "lines", "bars", "heatmap", "tradeoff", "facet"),
  abbrev = FALSE,
  combined = TRUE,
  ...
)

Arguments