Package {Nestimate}

Nestimate: Dynamic, Probabilistic, and Higher-Order Network 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://pak.dynasite.org/Nestimate/

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

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

The input data frame with one 0/1 integer column appended per state (named paste0(prefix, state)). All other columns are kept; the original action column is removed unless drop_action = FALSE.

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

Build a grouped node-level network (htna) from data and a clustering

Description

Builds the full node-level network from the original data and attaches a cluster grouping, producing a single htna network in which every actor is a node and cluster membership labels the actors. This is the node-level counterpart of build_mcml: where build_mcml collapses the network to a cluster-level (macro) summary, as_htna keeps every node and every transition - including the between-cluster transitions an mcml only retains in aggregate.

Usage

as_htna(x, clusters = NULL, method = "relative", ...)

## S3 method for class 'mcml'
as_htna(x, clusters = NULL, method = "relative", data = NULL, ...)

## S3 method for class 'net_mmm'
as_htna(x, clusters = NULL, method = "relative", ...)

## Default S3 method:
as_htna(x, clusters = NULL, method = "relative", ...)

Arguments

Details

Why this rebuilds from data. An mcml stores cluster-level data (the macro sequences are recoded to cluster labels, and the per-cluster data is filtered to within-cluster nodes), so it does not retain a faithful node-level transition network. The only faithful source of node-level between-cluster transitions is the original data. as_htna() therefore rebuilds from data via build_network; an mcml supplies the cluster membership and either its retained source or explicitly supplied original data supplies the transitions.

The result is a genuine netobject, so it supports inference (bootstrap_network, centrality, permutation) and plots directly as a grouped network with cograph: cograph::plot_htna(as_htna(data, clusters)).

Value

For data and mcml inputs, a single htna (also a netobject and cograph_network) over all nodes. Cluster labels are stored as a factor in $nodes$groups and as character values in $node_groups$group; $actor_levels records their order and is also attached to $node_groups for lossless partition round trips. For compatibility, the result also retains $nodes$cluster and the membership in the "cluster_members" attribute. A fitted net_mmm returns an htna_group, one materialized HTNA network per sequence cluster, while preserving the MMM diagnostics.

See Also

build_mcml, build_network; plot with cograph::plot_htna().

Examples

seqs <- data.frame(
  t1 = c("A", "C", "E", "B"), t2 = c("B", "D", "F", "A"),
  t3 = c("C", "A", "E", "D"), stringsAsFactors = FALSE
)
clusters <- list(C1 = c("A", "B"), C2 = c("C", "D"), C3 = c("E", "F"))
net <- as_htna(seqs, clusters)
net
## Not run: 
cograph::plot_htna(net)

## End(Not run)

Coerce an inferential comparison to a network difference

Description

Coerce an inferential comparison to a network difference

Usage

as_netdifference(x, ...)

## S3 method for class 'net_bayes'
as_netdifference(x, significant_only = TRUE, ...)

## S3 method for class 'netdifference'
as_netdifference(x, ...)

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

Arguments

Value

A netdifference object suitable for cograph::splot().

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"))
b <- bayes_compare(build_network(s1, method = "relative"),
                   build_network(s2, method = "relative"),
                   draws = 500, seed = 1)
as_netdifference(b, significant_only = FALSE)

Coerce a network object to a Nestimate netobject

Description

Promotes a psychnets result (class c("psychnet", "cograph_network")) or any bare cograph_network to the dual-class c("netobject", "cograph_network") used throughout Nestimate, so it dispatches to the package's verbs (centrality(), plot(), bootstrap, reliability, ...). A netobject is returned unchanged.

Usage

as_netobject(x)

## S3 method for class 'netobject'
as_netobject(x)

## S3 method for class 'psychnet'
as_netobject(x)

## S3 method for class 'cograph_network'
as_netobject(x)

## Default S3 method:
as_netobject(x)

Arguments

Details

The psychnet method re-derives the integer-indexed edge table that Nestimate expects (psychnet stores character-labelled edges), preserves the estimator name in $method, and parks every psychnet-specific field - including the graphical-lasso $kkt optimality certificate - under $meta$psychnet so nothing is lost in translation.

Value

A c("netobject", "cograph_network") object.

See Also

validate_netobject

Examples

net <- build_cor(data.frame(a = rnorm(50), b = rnorm(50), c = rnorm(50)))
identical(as_netobject(net), net) # netobjects pass through unchanged

Promote a psychometric MCML result to a network group

Description

as_networks() is the psychometric-network counterpart of as_tna. It promotes the cluster-level (macro) and within-cluster networks produced by build_mcml_pc into a single netobject_group, so the result flows into the same downstream verbs as any other group of networks (print(), summary(), plot(), net_centrality).

Usage

as_networks(x)

## S3 method for class 'mcml_pc'
as_networks(x)

## Default S3 method:
as_networks(x)

Arguments

Details

Where as_tna() promotes transition networks (directed, row-normalised, with initial probabilities) and re-wraps raw matrices, as_networks() promotes psychometric networks (undirected; correlation / partial-correlation / glasso). The macro and within-cluster components of an mcml_pc object are already full netobjects carrying their estimator, directedness and data, so this function assembles them into a group rather than re-wrapping matrices.

Value

A netobject_group: a named list whose first element is macro (the cluster-level network), followed by one netobject per non-singleton cluster.

The mcml_pc method returns a netobject_group; singleton clusters (no within-network) are dropped with a warning().

The default method returns the input unchanged if it is already a netobject_group, otherwise it errors.

See Also

build_mcml_pc to create the input, as_tna for the transition-network counterpart.

Examples

set.seed(1)
f <- stats::rnorm(200)
g <- stats::rnorm(200)
df <- data.frame(a1 = f + stats::rnorm(200), a2 = f + stats::rnorm(200),
                 a3 = f + stats::rnorm(200), b1 = g + stats::rnorm(200),
                 b2 = g + stats::rnorm(200), b3 = g + stats::rnorm(200))
clusters <- list(A = c("a1", "a2", "a3"), B = c("b1", "b2", "b3"))
fit <- build_mcml_pc(df, clusters, aggregation = "composite", method = "cor")
nets <- as_networks(fit)
nets
summary(nets)

Promote the Layers of an mcml to Networks

Description

Converts an mcml object into a netobject_group: one netobject for the cluster-level (macro) layer, and one per cluster for the within-cluster layers. The stored weights are carried over as they are – nothing is re-normalised here, so the aggregation chosen when the mcml was built is what the networks hold.

Usage

as_tna(x, ...)

## S3 method for class 'mcml'
as_tna(x, expand = NULL, ...)

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

Arguments

Details

This is the step that lets an MCML result flow into the verbs that take a group of networks (printing, network-metric summaries, rendering with cograph).

Workflow

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

# Every layer is an ordinary netobject
print(nets)      # one line per layer
summary(nets)    # network metrics per layer

Zero-out-degree (sink) nodes

Every cluster is returned, regardless of its row sums. A node with zero outgoing weight is a legitimate sink (a terminal state); its row in the wrapped network is left all-zero. This holds for both net_method = "relative" and "frequency" – the stored weights are never re-normalised, so a sink row needs no special handling. Inspect rowSums(x$clusters[[cl]]$weights) to find sink nodes.

Value

A netobject_group: a named list whose first element is macro (the k x k cluster-level network) followed by one element per cluster, each a netobject/cograph_network carrying $weights, $inits, $nodes, $edges and the recorded $method ("relative" for an mcml whose weights are already row-normalised, "frequency" otherwise).

The mcml method returns that netobject_group, each layer keeping the data the corresponding mcml layer carried. With expand, its macro element is the mixed-resolution network of macro_network rather than the fully collapsed one.

The default method returns the input unchanged when it already inherits from tna, and otherwise raises an error.

See Also

cluster_summary and build_mcml to create the input object, macro_network for a macro layer with one cluster expanded, as_networks for the psychometric-network counterpart

Examples

set.seed(1)
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)
nets <- as_tna(cs)
nets
summary(nets)

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
)

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

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

## S3 method for class 'net_association_rules'
plot(x, ...)

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

Tidy data frame, one row per rule, ordered by descending lift then confidence, with columns antecedent and consequent (the itemsets as comma-separated character strings), support, confidence, lift, conviction, count and n_transactions.

frequent

Tidy data frame, one row per frequent itemset, with columns itemset, size, support and count.

frequent_itemsets

List of frequent itemsets per level k, each entry a list of items / count / support.

items

Character vector of the frequent 1-itemsets the mining ran on (all items when no item clears min_support).

n_transactions

Integer.

n_rules

Integer.

params

List of min_support, min_confidence, min_lift, max_length.

In print.net_association_rules(): The input object, invisibly.

In summary.net_association_rules(): The tidy rules data frame: one row per rule, with columns antecedent, consequent, support, confidence, lift, conviction, count and n_transactions.

In plot.net_association_rules(): The drawn ggplot object, invisibly (the plot is also printed). NULL, invisibly, when no rule was found.

Methods

• plot.net_association_rules(): Scatter plot of association rules: support vs confidence, with point size proportional to lift.

References

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

Brin, S., Motwani, R., Ullman, J. D. & Tsur, S. (1997). Dynamic itemset counting and implication rules for market basket data. In Proc. ACM SIGMOD, 255–264. (lift and conviction)

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)

Bayesian Dirichlet-Multinomial comparison of two transition networks

Description

Compares two transition networks estimated by build_network (method "relative" or "frequency") using a Bayesian Dirichlet-Multinomial model. The outgoing transitions from each source state are modelled as a Multinomial draw with a Dirichlet prior on the transition probabilities. With a Jeffreys prior the posterior for the transitions out of state i is \mathrm{Dirichlet}(c_i + \alpha), where c_i are the observed outgoing counts. Each edge probability is then marginally Beta-distributed, so the posterior mean difference between the two networks is available in closed form and a credible interval is obtained by Monte Carlo.

This is a complement to permutation: the permutation test answers "is this difference more extreme than chance?"; the Bayesian comparison answers "what is the plausible range of the true difference, and how precisely is it estimated given the counts?". An edge with few outgoing transitions from its source state yields a wide credible interval even when its row-normalised probability looks decisive.

bayes_compare() also accepts two net_edge_betweenness objects (source method "relative" only). Edge betweenness is a nonlinear function of the whole transition matrix, so instead of Beta marginals the full transition matrix is drawn from each group's row-wise Dirichlet posterior and edge betweenness is recomputed on every draw - the Bayesian analogue of permutation()'s edge-betweenness dispatch. The result summarises the posterior of EB(x) - EB(y): diff is the posterior mean difference, prob_x/prob_y hold the posterior mean betweenness matrices, and observed_diff the plug-in difference of the two input networks. Both inputs must use the same invert setting.

Usage

bayes_compare(
  x,
  y = NULL,
  prior = 0.5,
  draws = 10000L,
  ci = 0.95,
  mean_threshold = 0.01,
  bound_threshold = 0.001,
  seed = NULL
)

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

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

## S3 method for class 'net_bayes'
plot(x, significant_only = TRUE, title = NULL, ...)

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

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

Arguments

Value

An object of class c("net_bayes", "netdifference", "net_permutation"). It carries the same fields as a permutation result, so it is a drop-in wherever a net_permutation is consumed, and also carries a netdifference difference matrix for cograph difference plotting, plus Bayesian extras:

x, y

The two input netobjects.

diff

Posterior mean difference matrix (prob_x - prob_y); the analogue of the permutation observed difference.

difference_matrix

Alias of diff for cograph netdifference helpers.

diff_sig

Difference where sig, else 0.

p_values

The two-sided Bayesian p-equivalent, in the field a net_permutation consumer reads as p-values (see p_bayes).

effect_size

Posterior mean difference over its posterior SD.

ci_lower, ci_upper

Credible-interval bound matrices.

p_difference

Probability of the difference: the share of posterior mass on the dominant side of zero, in [0.5, 1] (P(\mathrm{High} > \mathrm{Low}) for a positive difference).

p_bayes

Alias of p_values: the two-sided Bayesian p-equivalent 2(1-\mathrm{p\_difference}). It summarises posterior mass, not a frequentist tail probability, so it is not a p-value and should not be reported as one.

prob_x, prob_y

Posterior mean transition-probability matrices.

sig

Logical significance matrix (CI excludes zero, mean and nearest bound exceed their thresholds).

summary

Long-format data frame whose columns are a superset of summary.net_permutation (from, to, weight_x, weight_y, diff, effect_size, p_value, sig) plus count_x, count_y, ci_lower, ci_upper, ci_width, p_difference.

method, iter, alpha, paired, adjust

Permutation-compatible settings (iter = draws, alpha = 1 - ci, paired = FALSE, adjust = "none").

prior, draws, ci, mean_threshold, bound_threshold

Bayesian settings.

In print.net_bayes() and print.net_bayes_group(): The input object, invisibly.

In summary.net_bayes(): A data frame with edge-level posterior differences and intervals.

In plot.net_bayes(): Invisibly, the cograph network returned by cograph::splot() when cograph is available; otherwise a fallback ggplot object.

In summary.net_bayes_group(): A combined data frame with a comparison column.

Methods

• plot.net_bayes(): Draws a differential transition network as a directed chord diagram. Edge colour encodes the signed posterior mean difference (x stronger vs y stronger) and edge width its magnitude.

References

Johnston, L. & Jendoubi, T. (2026). How Delivery Mode Reshapes Resource Engagement: A Bayesian Differential Network Analysis. TNA Workshop 2026.

Gelman, A., Carlin, J. B., Stern, H. S., Dunson, D. B., Vehtari, A., & Rubin, D. B. (2013). Bayesian Data Analysis (3rd ed.). CRC Press.

Jeffreys, H. (1946). An invariant form for the prior probability in estimation problems. Proceedings of the Royal Society of London A, 186(1007), 453-461.

See Also

permutation for the frequentist complement; certainty for single-network posterior edge intervals; subtract_networks and as_netdifference for the difference verbs; build_network

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")
bayes_compare(n1, n2, draws = 500, seed = 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
)

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

## S3 method for class 'boot_glasso'
summary(object, type = "edges", ...)

## S3 method for class 'boot_glasso'
plot(x, type = "edges", measure = 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 results, one row per drop proportion by measure, with columns drop_prop, measure, mean_cor, prop_above (fraction of that proportion's iterations correlating above 0.7) and n_samples (iterations that landed on that proportion).

edge_diff_p

Symmetric matrix of pairwise edge difference p-values; NULL when the network has more than 500 edges.

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.

In print.boot_glasso(): The input object, invisibly.

In summary.boot_glasso(): For type = "edges", the edge_ci data frame (edge, weight, ci_lower, ci_upper, inclusion) ordered by decreasing absolute weight; for "cs" the cs_data data frame; for "predictability" the predictability_ci data frame; for "centrality" a named list of one data frame per measure (node, value, ci_lower, ci_upper); for "all" a named list holding all four.

In plot.boot_glasso(): A ggplot object (returned, and so printed when the call is made at the top level).

Methods

• plot.boot_glasso(): Plots bootstrap results for GLASSO networks.

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 (source of the CS-coefficient and of the case-dropping, edge-difference and centrality-difference procedures reproduced here.)

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")
# iter = 20 keeps the example fast; a real analysis uses 1000 or more.
boot <- boot_glasso(net, iter = 20, cs_iter = 10, 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"),
  ci_method = c("percentile", "basic"),
  actor = NULL
)

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

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

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

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

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

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

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, one row per non-zero original edge (undirected networks keep one row per unordered pair), with columns from, to, weight, mean, sd, p_value, sig, ci_lower, ci_upper, plus cr_lower and cr_upper when inference = "stability".

model

Pruned netobject (non-significant edges zeroed).

method, params, iter, ci_level, inference, ci_method

Bootstrap config.

consistency_range, edge_threshold

Inference parameters.

actor, n_actors

The actor column and its number of actors; NULL without actor.

clustering

Only with actor. One-row data frame: n_sequences, n_actors, icc, icc_ci_lower, icc_ci_upper, deff_edges.

clustering_edges

Only with actor. One row per edge of summary: from, to, icc, sd_actor, sd_sequence, deff.

A netobject_group or mcml input returns a "net_bootstrap_group" (named list of net_bootstrap results); a wtna_mixed input returns a "wtna_boot_mixed" with $transition and $cooccurrence results.

In print.net_bootstrap() and print.wtna_boot_mixed(): The input object, invisibly.

In summary.net_bootstrap(): The $summary data frame: one row per non-zero original edge, with columns from, to, weight, mean, sd, p_value, sig, ci_lower, ci_upper, plus cr_lower and cr_upper when the bootstrap used inference = "stability".

In print.net_bootstrap_group(): x invisibly.

In summary.net_bootstrap_group(): The per-group summaries stacked into one data frame: the columns of summary.net_bootstrap prefixed by a group column naming the network each row came from.

In summary.wtna_boot_mixed(): A list with $transition and $cooccurrence summary data frames.

Nested data and actor

The bootstrap resamples sequences as independent units. When sequences are nested in actors (sessions in students, students in teams), actor names the column identifying the actor, and whole actors are resampled with replacement, keeping all their sequences together: the cluster bootstrap that resamples at the top level only (Davison & Hinkley, 1997, section 3.8; Field & Welsh, 2007). The number of sequences per replicate then varies with the actors drawn.

With actor, the result also reports the nesting effect. The ICC is the proportion of the total variance that lies between actors (Shrout & Fleiss, 1979); an ICC close to 0 indicates little evidence of a nesting effect. It is computed as in permutation. The design effect is the ratio of the variance under the nested design to the variance had the sequences been sampled independently (Kish, 1965): here, the variance of the edge weights over actor-level replicates divided by their variance over sequence-level replicates drawn in the same run, reported as the median over edges. actor is available for transition networks ("relative", "frequency", "co_occurrence").

References

Davison, A. C., & Hinkley, D. V. (1997). Bootstrap Methods and Their Application. Cambridge University Press.

Field, C. A., & Welsh, A. H. (2007). Bootstrapping clustered data. Journal of the Royal Statistical Society: Series B, 69(3), 369-390.

Kish, L. (1965). Survey Sampling. Wiley.

Shrout, P. E., & Fleiss, J. L. (1979). Intraclass correlations: Uses in assessing rater reliability. Psychological Bulletin, 86(2), 420-428.

See Also

certainty for the closed-form Bayesian counterpart (same result layout, no resampling); 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)

set.seed(1)
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)

# Students nested in teams: resample whole teams
teams <- build_network(group_regulation_long, method = "relative",
                       actor = "Actor", action = "Action", time = "Time",
                       group = "Achiever")
bootstrap_network(teams, iter = 100, actor = "Group", seed = 1)

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, start = FALSE, end = FALSE, ...)

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"),
  ...
)

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

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

## S3 method for class 'net_clustering'
plot(
  x,
  type = c("silhouette", "mds", "heatmap", "predictors"),
  combined = TRUE,
  ...
)

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

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

covariates

The post-hoc covariate analysis (a list; see the estimator argument), or NULL when covariates = NULL.

network_method, build_args

For netobject input, the source network's method and stored build arguments, so per-cluster networks can be rebuilt the same way. NULL otherwise.

metadata

For netobject input, its per-sequence metadata, one row per clustered sequence, so session_ids can name each sequence. NULL otherwise.

htna_partition

For HTNA input, the preserved node-to-actor partition used to restore HTNA children when networks are built.

In print.net_clustering(): The input object, invisibly.

In summary.net_clustering(): A data frame of per-cluster statistics, one row per cluster, with columns cluster, size and mean_within_dist, returned visibly. When the clustering was fitted with covariates, a tidy_covariates/data.frame (the tidied covariate table, with cluster sizes, fit statistics and profiles attached as attributes) is returned invisibly instead. In both cases the printed summary is a side effect.

In plot.net_clustering(): A ggplot object (invisibly); for type = "predictors" with combined = FALSE, a list of ggplot objects named by cluster (invisibly).

In print.tidy_covariates(): The input invisibly.

Methods

• print.net_clustering(): Compact, fixed-width summary of a sequence-clustering result. The header carries the clustering method and dissimilarity; the per-cluster table carries cluster size (count and percentage) and mean within-cluster distance when available. Optional medoid and covariate lines surface only when those fields are populated.

• print.tidy_covariates(): Prints a one-line header naming the estimator, then the data.frame. The full human-readable view (per-cluster stats, profiles, OR/test tables) was already printed by summary() when this object was produced, so this method intentionally stays minimal to avoid duplication. Auto-prints when the user types the variable at the REPL.

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, start = FALSE, end = FALSE, ...)

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, start = FALSE, end = FALSE, ...)

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%) of individuals.

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

Estimation is delegated to idiographic::fit_gimme(), the clean-room home of the temporal idiographic estimators, whose search reproduces the upstream gimme package (>= 10.0) exactly (verified at tolerance 0 on path counts and per-person coefficient matrices in idiographic's own parity suite). 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

The object returned by idiographic::fit_gimme(): an S3 object of class c("net_gimme", "cograph_network", "list"). It is a superset of the pre-0.9.0 in-package field contract – every element below is present, alongside idiographic's own additions (contemp_cov, contemp_cov_avg, contemp_is_cov). Elements:

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

temporal_avg, contemporaneous_avg

p x p group-average coefficient matrices.

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.

The object additionally carries idiographic's netobject fields (weights, nodes, edges, directed, data, meta, node_groups) so it renders directly with cograph. print(), summary() and plot() dispatch to idiographic's methods, not to Nestimate's: in particular summary() returns a tidy data.frame rather than printing.

Results changed in 0.9.0

Before 0.9.0 the search ran in an in-package implementation that was not upstream-gimme-exact. Delegating to idiographic::fit_gimme() changed which paths the search selects on the same data – individual-level paths in particular – so numeric results are not comparable with Nestimate <= 0.8.5. The returned object also gained fields (see Value); nothing was removed.

See Also

build_network

Examples

# Create simple panel data (3 subjects, 4 variables, 30 time points).
set.seed(42)
n_sub <- 3; n_t <- 30; 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+"
)

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

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

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 c("net_hon", "cograph_network") containing:

weights, matrix

The same weighted adjacency matrix (rows = from, cols = to) under both names; weights is the cograph_network slot, matrix the higher-order name kept for back-compatibility. Rows and columns use readable arrow notation (e.g., "A -> B").

ho_edges

The higher-order edge table: one row per HON edge, 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.

edges

The cograph_network edge table: one row per non-zero cell of weights, with integer from/to node indices into nodes and a numeric weight. This is not the arrow-notation table - use ho_edges for that.

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 rows in ho_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.

meta

cograph_network metadata list (source, layout, tna$method = "hon").

node_groups

Always NULL.

In print.net_hon(): The input object, invisibly.

In summary.net_hon(): The cograph_network edge data.frame object$edges: one row per non-zero cell of the adjacency matrix, with integer from/to node indices and a numeric weight. Returned visibly; the summary text (counts, first-order states, order distribution) is printed as a side effect. The arrow-notation table with path/count/probability is object$ho_edges.

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)

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

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

## S3 method for class 'net_honem'
plot(x, dims = c(1L, 2L), ...)

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, row names = node names, column names dim_1, dim_2, ...

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.

In print.net_honem() and plot.net_honem(): The input object, invisibly.

In summary.net_honem(): A data.frame with one row per node: column node (node label) followed by dim1, dim2, ..., dimd embedding coordinates, returned visibly; the summary text is printed as a side effect.

References

Saebi, M., Ciampaglia, G. L., Kaplan, L. M., & Chawla, N. V. (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
)

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

## S3 method for class 'net_hypa'
summary(
  object,
  n = 10L,
  type = c("all", "over", "under"),
  order_by = c("sig", "freq", "frequency", "ratio", "path"),
  ...
)

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.

In print.net_hypa(): The input object, invisibly.

In summary.net_hypa(): A data frame of the reported anomalies, at most n rows per direction, with columns order (the De Bruijn order the path was found at), path, observed, expected, ratio, p_tail (the raw tail probability in the reported direction: p_over for over-represented paths, p_under for under-represented ones) and direction ("over"/"under"). Returned visibly; the summary text and the top-n tables are printed as a side effect. When no anomalies were detected, a zero-row data frame with the same columns except order is returned.

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.

In print.net_hypergraph(): For print(), the input x invisibly.

In summary.net_hypergraph(): For summary(), a data.frame with one row per node and columns node (node name) and degree (number of hyperedges containing the node), returned visibly; the summary block (node / hyperedge counts, mean and maximum hyperedge size) is printed as a side effect.

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,
  exclude = NULL,
  trim = NULL,
  end = FALSE,
  end_by = NULL,
  labels = NULL,
  combine = NULL,
  expand = NULL
)

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

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

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

Arguments

Value

An mcml object with the same layout as the return value of cluster_summary (macro, clusters, cluster_members, edges, meta). On the sequence and edge-list paths meta$source is "transitions", meta$type records the type post-processing, and edges is a tidy data frame with one row per observed node-level transition and columns from, to, weight, cluster_from, cluster_to, type ("within"/"between"). Matrix input falls through to cluster_summary, so meta$source is "matrix" and edges is NULL. Works with print(), summary(), as_tna, as_htna and macro_network.

In print.mcml_layer(): The input mcml_layer, invisibly.

In print.mcml(): The input object, invisibly.

In summary.mcml(): A tidy data frame with one row per cluster and columns cluster, size, within_total, between_out, between_in. For undirected macro networks the in/out split is not meaningful, so between_out reports total incident weight and between_in is NA. The data frame is returned silently without printing the full object – call print(object) explicitly if you want the verbose dump.

Methods

• print.mcml_layer(): Compact view of one mcml layer (the macro layer or a single within-cluster network): a header line with the node and non-zero edge counts and the weight range, the rounded weight matrix, the initial probabilities as a bar chart, and the dimensions of any attached data – rather than the raw list contents.

See Also

cluster_summary for matrix-based aggregation, as_tna to promote the layers to netobjects, macro_network for the cluster-level network with one cluster expanded

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"))
build_mcml(edges, clusters)

# 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
summary(cs)

# Change the partition while building ...
three <- build_mcml(seqs, list(G1 = "A", G2 = "B", G3 = c("C", "D")))
build_mcml(seqs, list(G1 = "A", G2 = "B", G3 = c("C", "D")),
           combine = c("G1", "G2"))

# ... or re-partition an existing mcml: the model is re-estimated
build_mcml(three, combine = c("G1", "G2"))           # G1 + G2 as one cluster
build_mcml(three, combine = list(AB = c("G1", "G2"))) # named merge
build_mcml(three, expand = "G3")                      # C and D as clusters

Multi-Cluster Multi-Level Aggregation for Psychometric Networks

Description

Experimental. Aggregates a node-level psychometric network (correlation, partial correlation, or EBICglasso) into a cluster-level macro network plus per-cluster within networks - the MCML view that build_mcml provides for transition networks, adapted to the statistics of undirected association networks. The API and the exact aggregation formulas may change between releases.

Unlike transition counts, partial correlations do not aggregate by arithmetic: the submatrix of a pcor matrix is not the pcor network of the subsystem (the conditioning set changes), and averaging pcor entries across blocks is descriptive only. The aggregation methods therefore have explicitly different statuses (the full list of accepted values is under aggregation below):

"average" (descriptive)

Macro edge A–B = mean of the signed node-level weights between members of A and members of B; macro diagonal = mean within-block off-diagonal weight. Needs only the weight matrix (works on data-less netobjects). Caveat: signed averaging can cancel opposite-sign edges; interpret as net average association, not connectivity strength.

"composite" (re-estimated)

Per-observation cluster scores = (optionally standardized) mean of member variables; the chosen method is then re-fit on the k composite columns, so the macro network is a genuine correlation / pcor / EBICglasso network among clusters. Requires raw data.

"loadings" (re-estimated, connectivity-weighted)

As "composite", but member variables are weighted by their within-cluster connection strength in the node-level network (the absolute summed weight to the other members of their own cluster, normalized to sum to 1 per cluster). Nodes that anchor their cluster contribute more to its composite. This is Nestimate's own weighting - related in spirit to network loadings (Christensen & Golino 2021) but not a reimplementation of any EGA-family estimator. Requires raw data.

"escoufier" (descriptive, multivariate)

Macro edge A–B = Escoufier's RV coefficient between the member blocks - a matrix correlation in ⁠[0, 1]⁠ computed from the block covariance structure. No composites are formed and no estimator is re-fit, so nothing is lost to averaging; signs are not represented. Requires raw data.

"cancor" (descriptive, multivariate)

Macro edge A–B = the first canonical correlation between the member blocks: the strongest linear relationship any weighting of A's items can have with any weighting of B's items - an upper bound on what composite methods can recover. Requires raw data.

Usage

build_mcml_pc(
  x,
  clusters,
  aggregation = c("scaled", "composite", "mean", "median", "loadings", "average",
    "escoufier", "cancor"),
  method = c("pcor", "glasso", "cor"),
  within = c("reestimate", "subnetwork"),
  weighting = c("equal", "strength", "eigen", "closeness", "betweenness",
    "expected_influence", "specificity", "pca", "factor", "item_total"),
  cor_method = c("pearson", "spearman", "polychoric"),
  signed = TRUE,
  id_col = NULL,
  fa_method = c("ml", "paf", "minres", "cfa"),
  ...
)

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

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

## S3 method for class 'mcml_pc'
plot(x, digits = 2, ...)

Arguments

Details

Item diagnostics. Whenever raw data or a node-level network is available, every item's connection strength to every cluster is computed. The item_loadings() table reports, per item: its signed own-cluster loading, its composite weight, its strongest cross-cluster loading, and a misfit flag set when the cross-cluster loading exceeds the own-cluster loading - evidence the item is assigned to the wrong cluster. Misfit items trigger a warning; every aggregation silently inherits a bad membership, so fix the assignment rather than ignoring the flag.

Reverse-keyed items. With signed = TRUE (default), items whose summed within-cluster association is negative are flipped (their standardized values enter composites with weight sign -1), so a reverse-keyed item reinforces its cluster composite instead of cancelling it. Flips are reported in the sign column and via a warning.

Missing data. Composites are per-row weighted means over the observed members (weights renormalized per row); rows with no observed member yield NA and are dropped by the estimator with a message. Node-level estimation applies the estimators' own complete-case handling.

Ordinal items. cor_method = "polychoric" (requires the lavaan package) estimates the node-level and within-cluster networks from polychoric correlations - appropriate for Likert items. Composites are continuous sums, so the macro re-estimation uses Pearson correlations of the composites regardless.

Within-cluster networks follow within: "reestimate" (default) re-fits the estimator on the member columns alone - the honest conditional structure of the subsystem; "subnetwork" slices the node-level weight matrix and is descriptive (for pcor/glasso it retains conditioning on out-of-cluster nodes). Modes without raw data force "subnetwork". Singleton clusters get no within network (NULL).

Uncertainty. The composite/loadings macro network is a full netobject carrying its composite data, so bootstrap_network(macro_network(fit)) (edge-weight CIs) and vertex_bootstrap(macro_network(fit)) (network-level CIs) work directly; vertex_compare(macro_network(fit1), macro_network(fit2)) compares two groups. loading_stability quantifies how stable the composite weights themselves are under case resampling.

All constituent networks are undirected (meta$directed = FALSE), so renderers that auto-detect directedness (e.g. cograph::plot_mcml()) draw the result without arrowheads.

Value

An object of class "mcml_pc" containing:

macro

Cluster-level netobject (k x k, undirected).

clusters

Named list of within-cluster netobjects (NULL for singleton clusters).

cluster_members

Named list of member node labels.

loadings

Tidy item-diagnostic data frame (one row per node): node, cluster, loading (signed own-cluster), weight, sign, max_cross, cross_cluster, misfit. NULL only when no node-level network is available.

node_network

The node-level netobject the aggregation was based on (kept for diagnostics and loading_stability).

data

The raw data (data.frame) when available, else NULL.

meta

List: aggregation (the name as the caller spelled it), method, within, weighting, fa_method, fa_args, scale, cor_method, signed, n_nodes, n_clusters, cluster_sizes, n_misfit, n_flipped, directed = FALSE, source = "pc", experimental = TRUE. method and weighting are NA on the descriptive paths that re-estimate nothing, and fa_method/fa_args are set only for weighting = "factor".

In print.mcml_pc(): x, invisibly.

In summary.mcml_pc(): Tidy data frame with one row per macro edge (upper triangle), columns from, to, weight.

In plot.mcml_pc(): A ggplot object.

Methods

• plot.mcml_pc(): Heatmap of the macro (cluster-level) weights with the package's diverging palette. For the two-layer network rendering use cograph::plot_mcml(), which accepts mcml_pc objects and draws them undirected.

References

Escoufier, Y. (1973). Le traitement des variables vectorielles. Biometrics, 29(4), 751-760.

Hotelling, H. (1936). Relations between two sets of variates. Biometrika, 28(3/4), 321-377.

Robinaugh, D. J., Millner, A. J., & McNally, R. J. (2016). Identifying highly influential nodes in the complicated grief network. Journal of Abnormal Psychology, 125(6), 747-757.

Christensen, A. P., & Golino, H. (2021). On the equivalency of factor and network loadings. Behavior Research Methods, 53, 1563-1580.

Epskamp, S., & Fried, E. I. (2018). A tutorial on regularized partial correlation networks. Psychological Methods, 23(4), 617-634.

See Also

build_mcml for transition networks, loading_stability for composite-weight stability, bootstrap_network and vertex_bootstrap for uncertainty on the macro network.

Examples

set.seed(1)
n <- 200
sigma <- matrix(0.15, 6, 6)
sigma[1:3, 1:3] <- 0.5
sigma[4:6, 4:6] <- 0.5
diag(sigma) <- 1
z <- matrix(rnorm(n * 6), n, 6) %*% chol(sigma)
df <- as.data.frame(z)
names(df) <- c("a1", "a2", "a3", "b1", "b2", "b3")
clusters <- list(A = c("a1", "a2", "a3"), B = c("b1", "b2", "b3"))

fit <- build_mcml_pc(df, clusters, aggregation = "composite",
                     method = "cor")
fit            # macro (cluster-level) weights
summary(fit)   # one row per macro edge
plot(fit)      # heatmap of the same 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.

Usage

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

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

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

Arguments

Details

Estimation is delegated to idiographic::fit_mlvar() (the clean-room home of the temporal idiographic estimators), called with estimator = "lmer", temporal = "fixed", contemporaneous = "fixed". The pipeline follows mlVAR's lmer path 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, and to exact equality (max_diff == 0) against the pre-delegation Nestimate implementation on all layers, coefficients, and observation counts across lag/standardize/day/beep configurations.

When the data carry no between-person variance (a random-intercept SD of zero), the between-subjects network is not estimable. Since 0.9.0 this raises a warning from idiographic and still returns the zero matrix by convention; before 0.9.0 the zero matrix was returned silently.

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. See Dispatch limitation for the verbs that do not work on this object (plot(), bootstrap_network(), centrality(), reliability/stability). 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.

In print.net_mlvar(): Invisibly returns x.

In summary.net_mlvar(): The tidy coefficient data.frame - the same table coefs() returns, with one row per ⁠(outcome, predictor)⁠ pair and columns outcome, predictor, beta, se, t, p, ci_lower, ci_upper, significant. Returned visibly, so calling summary(fit) at the console prints the matrices and then the table.

Dispatch limitation

There is no plot() method for net_mlvar - plot a single constituent (cograph::splot(fit$temporal)) instead. The three constituents are matrix-wrapped and carry no ⁠$data⁠, so the data-resampling and data-reading verbs do not work on the fitted object or its parts: bootstrap_network(), certainty(), network_reliability(), centrality_stability() and centrality() all need the source panel. Extract a constituent and rebuild it through build_network() if you need those. Use coefs() for the tidy model output.

Methods

• summary.net_mlvar(): Prints the three weight matrices and the significant temporal edges, then returns the tidy coefficient table.

See Also

build_network()

Examples

# A three-variable ESM panel: 20 people x 20 beeps. `tired` is driven by
# `happy` one beep earlier, so the temporal network should recover it.
if (requireNamespace("lme4", quietly = TRUE)) {
  set.seed(1)
  n_beep <- 20
  ar1 <- function(n, phi) as.numeric(stats::filter(stats::rnorm(n), phi,
                                                   method = "recursive"))
  panel <- do.call(rbind, lapply(seq_len(20), function(i) {
    happy <- ar1(n_beep, 0.4)
    data.frame(
      id    = i,
      beep  = seq_len(n_beep),
      happy = happy + stats::rnorm(1),
      calm  = ar1(n_beep, 0.3) + stats::rnorm(1),
      tired = 0.5 * c(0, happy[-n_beep]) + stats::rnorm(n_beep) +
              stats::rnorm(1)
    )
  }))
  fit <- build_mlvar(panel, vars = c("happy", "calm", "tired"),
                     id = "id", beep = "beep")
  fit
  coefs(fit)
  summary(fit)
}

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,
  covariate_effect = c("em", "posthoc"),
  estimator = c("auto", "firth", "multinom", "chisq")
)

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

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

## S3 method for class 'net_mmm'
plot(x, type = c("posterior", "covariates"), combined = TRUE, ...)

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

## S3 method for class 'net_mmm_clustering'
plot(
  x,
  type = c("posterior", "covariates", "predictors"),
  combined = TRUE,
  ...
)

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, class_entropy.

log_likelihood, BIC, AIC, ICL

Model fit statistics.

n_params

Number of free parameters behind BIC/AIC/ICL. With covariate_effect = "em" it grows by (k - 1) * p for p covariate columns.

iterations, converged

EM iterations used by the retained fit and whether it met tol.

states

Character vector of state names.

n_sequences

Number of sequences actually fitted (rows with missing covariates are dropped under covariate_effect = "em").

covariates

The post-hoc covariate analysis (list), or NULL when covariates = NULL.

network_method, build_args, htna_partition

Provenance kept from netobject / HTNA input so per-cluster networks can be rebuilt the same way; NULL otherwise.

metadata

The netobject's per-sequence metadata, one row per fitted sequence in the row order of posterior, so session_ids can name each sequence; NULL for other input.

In print.net_mmm() and print.net_mmm_clustering(): The input object, invisibly.

In summary.net_mmm(): A per-component summary data.frame. The class and visibility depend on whether the model was fitted with covariates:

No covariates

A plain data.frame with one row per component and columns component, prior, n_assigned, mean_posterior, avepp, returned visibly (so it auto-prints after the printed summary block).

With covariates

A tidy_covariates/data.frame (the tidied covariate table, with the per-component stats attached), returned invisibly.

In both cases the printed summary (model fit, per-cluster transition matrices, optional covariate profiles) is emitted as a side effect.

In plot.net_mmm(): A ggplot object, invisibly; for type = "covariates" with combined = FALSE, a list of ggplot objects named by cluster (invisibly).

In plot.net_mmm_clustering(): A ggplot object, invisibly; for type = "covariates" / "predictors" with combined = FALSE, a list of ggplot objects named by cluster (invisibly).

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.

Methods

• plot.net_mmm_clustering(): Plot routines for the MMM clustering metadata attached to the netobject_group that build_network materializes from a cluster_mmm fit (or that cluster_network returns directly with cluster_by = "mmm"). Mirrors the type-driven surface of plot.net_clustering but covers only the metrics the EM fit produces – there is no distance matrix on an MMM clustering, so "silhouette" / "mds" / "heatmap" aren't defined here and the dispatcher raises a clear error if you ask for one of those on an MMM result.

• print.net_mmm(): Compact summary of a Mixed Markov Model fit. Header carries dimensions and information criteria; cluster table carries N, mixing share, and per-cluster average posterior probability (AvePP). Layout matches print.net_clustering so distance- and model-based clusterings can be compared at a glance.

• print.net_mmm_clustering(): Prints the clustering metadata attached to the netobject_group that build_network materializes from a cluster_mmm fit (attr(grp, "clustering")). Layout mirrors print.net_clustering: a one-line dimension header, a quality line with AvePP / entropy / classification error, information criteria, and a per-cluster table.

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
)

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

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

## S3 method for class 'net_mogen'
plot(x, type = c("ic", "likelihood"), ...)

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 c("net_mogen", "cograph_network") 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, after any capping).

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 row-stochastic transition matrices (index 1 = order 0, held as the marginal named numeric vector).

count_matrices

List of the matching raw count matrices, same indexing; read by mogen_transitions().

states

Unique first-order states.

n_paths

Number of trajectories.

n_observations

Total number of state observations.

weights

cograph_network weight matrix: the transition matrix of the selected optimal order (a 1 x n matrix named "marginal" when the optimal order is 0). Its dimnames are the internal k-gram keys (states joined by a non-printing separator), not arrow notation.

nodes

data.frame (id, label, name) of the optimal-order De Bruijn nodes.

edges

cograph_network edge data.frame with integer from/to node indices and a numeric weight. The readable arrow-notation table is mogen_transitions().

directed

Logical. Always TRUE.

n_nodes, n_edges

Counts for the optimal-order graph.

meta

cograph_network metadata list.

node_groups

Always NULL.

In print.net_mogen() and plot.net_mogen(): The input object, invisibly.

In summary.net_mogen(): A per-order model-selection data.frame with columns order, layer_dof, cum_dof, loglik, aic, bic, best ("AIC"/"BIC"/"AIC+BIC" marker) and selected ("<--" on the chosen order), returned visibly; the summary text is printed as a side effect.

References

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

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

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,
  timezone = "UTC",
  predictability = TRUE,
  state_cols = NULL,
  metadata_cols = NULL,
  start = FALSE,
  end = FALSE,
  params = list(),
  labels = NULL,
  ...
)

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

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

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

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

## S3 method for class 'netobject_group'
summary(object, combined = TRUE, ...)

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

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

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 state columns of the cleaned input data, as a data frame.

metadata

Data frame of the non-state columns of the cleaned input (and, for long input, the per-sequence metadata), or NULL.

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

build_args

The resolved column/format arguments (actor, action, time, session, order, codes, format, window_size, mode) used for this build.

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, initial, 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. level = "between" or "within" returns a single netobject estimated on the decomposed data.

When group is supplied (or data is a net_clustering / net_mmm object), returns an object of class "netobject_group": a named list of netobjects, one per group, carrying the grouping column in attr(x, "group_col").

In print.netobject(), print.netobject_group() and print.netobject_ml(): The input object, invisibly.

In summary.netobject(): A data.frame with columns metric and value, of class c("summary.netobject", "data.frame").

In summary.netobject_group(): Either a data.frame (one column per group) or a named list of summary.netobject objects, of class c("summary.netobject_group", ...).

In print.summary.netobject(): x, invisibly.

In print.summary.netobject_group(): x, invisibly.

Methods

• print.netobject_group(): Compact summary of a netobject_group. Header surfaces the source (a clustering attached by cluster_network or cluster_mmm, or a plain split by group_col). The per-group table carries node and edge counts, weight range, and – when a clustering attribute is present – N and percentage of sequences per cluster (matching the layout used by print.net_clustering and print.net_mmm).

• summary.netobject(): Computes node count, edge count, density, mean shortest-path distance, mean and SD of in/out strength, mean and SD of in/out degree, in/out degree centralization (Freeman), and reciprocity. Mirrors the metric set returned by tna::summary.tna() so a Nestimate netobject and the equivalent tna model report numerically identical descriptive metrics.

• summary.netobject_group(): Returns one summary per constituent network. With combined = TRUE (default) the per-group tables are joined into a single wide data.frame with one column per group; with combined = FALSE returns a named list.

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,
  ...
)

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

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

Arguments

Value

A simplicial_complex object - a list with:

simplices

List of integer vectors, one per simplex, each holding the (sorted) node indices it spans. Every face of every simplex is present, including all 0-simplices (isolated vertices included).

nodes

Character vector of node labels; simplices index into it.

n_nodes, n_simplices

Integer counts.

dimension

Integer. Highest simplex dimension present (a k-simplex has k+1 nodes).

f_vector

Named integer vector dim_0, dim_1, ... - the number of simplices of each dimension.

density

Numeric. n_simplices divided by the number of simplices a complete complex on n_nodes would have up to dimension.

mean_dim

Numeric. Mean simplex dimension.

type

"clique", "pathway", or "vr".

For type = "vr" two further elements are attached: $filtration (numeric, parallel to $simplices: the value at which each simplex enters) and $max_scale (the cap actually used). persistent_homology() consumes them directly.

In print.simplicial_complex(): The input object, invisibly.

In plot.simplicial_complex(): A grid grob (invisibly) when combined = TRUE; a named list of four ggplots when combined = FALSE.

Methods

• plot.simplicial_complex(): Produces a four-panel summary: f-vector, Betti numbers, simplicial degree ranking, and degree-by-dimension heatmap.

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, start = FALSE, end = FALSE, ...)

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.

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.

summary

Tidy data frame, one row per metric by drop proportion, with columns metric ("mean_abs_dev", "median_abs_dev", "correlation", "max_abs_dev"), drop_prop, mean, sd, median, mad, q025, q975.

metrics

Named list of four iter x length(drop_prop) matrices, one per metric, holding the raw per-iteration values.

correlations

iter x length(drop_prop) matrix of per- iteration correlations (the correlation entry of metrics).

drop_prop, threshold, certainty, iter, method, include_diag

Inputs.

n_cases

Number of cases resampled from (sequences for transition methods, rows of ⁠$data⁠ otherwise).

n_edges

Length of the edge vector assessed.

A netobject_group or mcml input instead returns a net_casedrop_reliability_group: a named list of one result per constituent network.

When the original edge vector has zero variance a warning is issued and the object is returned with cs = 0, an empty summary, and all-NA metric matrices.

In print.net_casedrop_reliability(): The input x invisibly.

In summary.net_casedrop_reliability(): A tidy data frame with columns metric, drop_prop, mean, sd summarising edge-weight stability across case-dropping iterations.

In summary.net_casedrop_reliability_group(): A data frame with one row per network containing cor, mean_abs_dev, median_abs_dev, max_abs_dev formatted as "mean +/- sd".

In plot.net_casedrop_reliability(): A ggplot object, or a named list of four ggplots when combined = FALSE.

In plot.net_casedrop_reliability_group(): A ggplot object.

Methods

• plot.net_casedrop_reliability(): 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).

• plot.net_casedrop_reliability_group(): 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).

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

set.seed(1)
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,
  normalize = FALSE,
  invert = TRUE,
  normalize_diffusion = TRUE,
  seed = NULL
)

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

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

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

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

## S3 method for class 'net_stability'
plot(x, ...)

Arguments

Value

An object of class "net_stability": a list with

cs

Named numeric vector of CS-coefficients, one per retained measure.

correlations

Named list of iter x length(drop_prop) matrices of correlation values, one per retained measure.

measures

Character vector of the measures actually assessed (see the zero-variance rule below).

drop_prop

Drop proportions used.

threshold

Stability threshold.

certainty

Required certainty level.

iter

Number of iterations.

method

Correlation method.

A netobject_group or mcml input instead returns a "net_stability_group": a named list of one net_stability per constituent network.

Zero-variance measures are handled by two different rules, both long-standing behaviour. When some requested measures have zero variance on the original network (for example "OutStrength" on a row-normalised transition network), those measures are dropped: $cs, $correlations and $measures cover only the retained ones. When every requested measure has zero variance a warning is issued and all requested names are returned with cs = 0 and all-NA correlation matrices.

In print.net_stability(): The input object, invisibly.

In print.net_stability_group(): The input x invisibly.

In summary.net_stability_group(): A data frame with columns group, measure, drop_prop, mean_cor, sd_cor, prop_above.

In summary.net_stability(): A data frame with columns measure, drop_prop, mean_cor, sd_cor, prop_above.

In plot.net_stability(): A ggplot object (invisibly).

Methods

• plot.net_stability(): Plots mean correlation vs drop proportion for each centrality measure. The CS-coefficient is marked where the curve crosses the threshold.

• summary.net_stability(): Returns the mean correlation at each drop proportion for each measure.

• summary.net_stability_group(): Per-network stability as a tidy data frame. Stacks summary() results for each network with a group column.

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

build_network, network_reliability

Examples

seqs <- data.frame(
  T1 = c("plan", "code", "debug", "plan", "test", "code"),
  T2 = c("code", "debug", "code", "plan", "code", "test"),
  T3 = c("debug", "code", "plan", "code", "debug", "plan"),
  T4 = c("test", "plan", "test", "debug", "plan", "code")
)
net <- build_network(seqs, method = "relative")
cs <- centrality_stability(net, iter = 10, drop_prop = 0.3, seed = 1)

set.seed(1)
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)

Analytic certainty of network edges (Bayesian Dirichlet-Multinomial)

Description

Closed-form alternative to bootstrap_network for transition networks. Models the outgoing transitions from each state as a Dirichlet-Multinomial process: with a Jeffreys prior the posterior for state i is \mathrm{Dirichlet}(c_i + \mathrm{prior}), so each edge is marginally Beta and its posterior mean, standard deviation, credible interval and stability decision are available analytically. No resampling, so it runs in microseconds.

The return value has the same structure as bootstrap_network (same slots and summary columns) and carries class c("net_certainty", "net_bootstrap"), so summary() and any code that consumes a net_bootstrap object work unchanged.

Usage

certainty(
  x,
  prior = 0.5,
  ci_level = 0.05,
  inference = c("stability", "threshold"),
  consistency_range = c(0.75, 1.25),
  edge_threshold = NULL
)

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

Arguments

Details

Certainty (this function), stability (bootstrap_network) and reliability (reliability) answer different questions about an edge: how precisely it is pinned down by the observed counts, whether it survives resampling the sequences, and whether it is consistent across split-halves. Certainty and stability agree on homogeneous data; certainty is over-confident when the data are a mixture of latent classes, because it treats transitions clustered within a sequence as independent.

Value

For a netobject: an object of class c("net_certainty", "net_bootstrap") with the same fields as bootstrap_network: original, mean, sd, p_values, significant, ci_lower, ci_upper, cr_lower, cr_upper, summary, model, method, params, ci_level, inference, consistency_range, edge_threshold, plus prior, ci_method = "analytic" and iter = NA (no iterations).

For a netobject_group: a named list of those objects, one per constituent network, of class c("net_certainty_group", "net_bootstrap_group", "list").

In print.net_certainty(): The input object, invisibly.

References

Johnston, L. & Jendoubi, T. (2026). How Delivery Mode Reshapes Resource Engagement: A Bayesian Differential Network Analysis. TNA Workshop 2026.

See Also

bootstrap_network, bayes_compare, network_reliability

Examples

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

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)

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

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

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

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

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

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

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

For a netobject_group, a c("chain_structure_group", "list"): a named list holding one chain_structure per constituent network, with its own print() and summary() methods.

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

In print.chain_structure(), print.chain_structure_group() and print.summary_chain_structure(): x invisibly.

In plot.chain_structure(): A ggplot object.

In summary.chain_structure(): A data.frame with one row per state, of class c("summary_chain_structure", "data.frame"), carrying the chain-level flags (is_regular, is_irreducible, is_aperiodic, is_reversible, n_classes, absorbing_states) as attributes, which its print() method shows as a header. Columns as described above.

In summary.chain_structure_group(): A data.frame with columns group, state, classification, period, persistence, return_probability, sojourn_steps, plus stationary_probability if all groups are irreducible and mean_absorption_time if any group has absorbing states.

Methods

• plot.chain_structure(): 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).

• print.chain_structure(): Prints a compact chain-level header. For the full per-state table, call summary() on the same object.

• print.chain_structure_group(): One header line per group, followed by each group's per-state table (via summary.chain_structure).

• print.summary_chain_structure(): Prints a one-line chain header followed by the tidy per-state table.

• summary.chain_structure(): Returns a single data.frame with one row per state, combining every per-state metric chain_structure() computes. Always includes state, classification, period, persistence (the diagonal of the transition matrix), return_probability (the diagonal of the hitting matrix) and sojourn_steps (1 / (1 - persistence), which is Inf for an absorbing state). Adds the chain's stationary_probability when the chain is irreducible, and absorption columns when it has any absorbing states: absorption_probability for a single absorbing state or one ⁠absorbed_in_<state>⁠ column per state when there are several, plus mean_absorption_time.

• summary.chain_structure_group(): Produces a single tidy data.frame with one row per (group, state) combination, combining classification, persistence, sojourn, and – when applicable – stationary or mean-absorption-time columns. Useful for side-by-side reporting of chain_structure() across the members of a netobject_group.

Plot colours

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.

Summary columns

Columns are ordered for readability: identifiers first, classification second, dynamic per-state metrics last.

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

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. The standard netobject fields are present (⁠$weights⁠, ⁠$nodes⁠, ⁠$edges⁠ - one row per non-zero upper-triangle cell with integer from/to node indices and weight - ⁠$n_nodes⁠, ⁠$n_edges⁠, ⁠$meta⁠); ⁠$params⁠ records source, weighted, n_hyperedges and hypergraph_size_distribution.

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, H., & Zafarani, R. (2024). Higher-order networks representation and learning: A survey. ACM SIGKDD Explorations Newsletter 26(1), 1-18.

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)
extract_edges(net, threshold = 1)

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",
  ...
)

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

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

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

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

In print.cluster_choice(): The input object, invisibly.

In summary.cluster_choice(): A data frame with the swept configurations, all metrics, and a best character column flagging the silhouette-max row.

In plot.cluster_choice(): A ggplot object, invisibly; for type = "facet" with combined = FALSE, a named list of ggplots.

Methods

• plot.cluster_choice(): 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).

Plot types

Type cheat-sheet:

"auto"

Default. Picks one of the others based on which axes were swept. k-only -> "lines"; one categorical axis swept -> "bars"; k plus one categorical -> "lines"; k plus two categoricals -> "facet"; both categoricals without k -> "heatmap".

"lines"

Silhouette across k (and mean_within_dist when k is the only swept axis), one line per non-k axis when present.

"bars"

Horizontal bar chart of silhouette per axis level. Bars sorted by silhouette.

"heatmap"

Tiled silhouette across two categorical axes. Requires both dissimilarity and method swept.

"tradeoff"

Scatter: silhouette (y) vs size_ratio (x). Works for any sweep; labels each point.

"facet"

Lines vs k, colour by one categorical axis, facet by another. Requires k plus two categoricals.

Asking for a type the data can't support raises an error pointing at the alternatives.

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'
print(x, digits = 3L, ...)

## S3 method for class 'net_cluster_diagnostics'
plot(x, type = NULL, ...)

## 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

cluster_diagnostics() returns a net_cluster_diagnostics object: a list carrying family, k, n, sizes, the per_cluster data frame (one row per cluster), overall, ics, metadata and source, as detailed above. as.data.frame() on that object returns the per_cluster data frame itself – one row per cluster, with family-specific columns.

In print.net_cluster_diagnostics(): The input object, invisibly.

In plot.net_cluster_diagnostics(): Whatever the underlying plot method returns: a ggplot object, invisibly; or, for the covariate forest views called with combined = FALSE, a list of ggplot objects named by cluster (invisibly).

Methods

• plot.net_cluster_diagnostics(): Delegates to the original clustering object's plot method (plot.net_clustering for distance-based diagnostics, plot.net_mmm_clustering or plot.net_mmm for model-based). The diagnostics object itself stores no plot geometry – it just keeps a reference to the source so the existing visual layer is reused.

• print.net_cluster_diagnostics(): Prints a uniform header, family-specific quality / IC line, and a per-cluster table. Layout matches print.net_clustering and print.net_mmm.

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)

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

Cluster sequences using Mixed Markov Models

Description

Fits a mixture of Markov chains to sequence data and returns the fitted net_mmm clustering object. The fit retains assignments, posterior probabilities, mixing proportions, information criteria, and the fitted component models.

Usage

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

Arguments

Details

To materialize one network per fitted cluster, pass the result to build_network or use cluster_network(..., cluster_by = "mmm") for fitting and network construction in one call.

Value

A fitted net_mmm clustering object. This is the same object contract returned by build_mmm. For HTNA input, its preserved actor partition is restored when the fit is materialized with build_network or Nestimate::as_htna().

See Also

build_mmm, build_network, and cluster_network for fitting and immediately materializing per-cluster networks

Examples

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

# 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)
)
fit <- cluster_mmm(seqs, k = 2)
sequence_plot(fit, 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 the node-level network
net <- build_network(data, method = "relative")

# 2. Aggregate its edges to cluster level (arithmetic aggregation)
cs <- cluster_summary(net, clusters = group_assignments, method = "sum")

# 3. Read the result
print(cs)      # macro weights
summary(cs)    # one row per cluster

# 4. Promote the layers to netobjects for downstream verbs
nets <- as_tna(cs)

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

An mcml object (S3 class): a list with

macro

An mcml_layer holding the cluster-level network: $weights, the k x k matrix whose entry (i, j) is the aggregation (per method) of all edges from nodes in cluster i to nodes in cluster j, with the diagonal holding the within-cluster edges – pure arithmetic, no row normalization; $inits, the length-k column sums of that matrix normalized to sum to 1; $labels, the cluster names; and $data, NULL on this path.

clusters

Named list with one mcml_layer per cluster. Its $weights is the n_i x n_i submatrix of the nodes in that cluster and its $inits the normalized column sums of that submatrix. NULL when compute_within = FALSE.

cluster_members

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

edges

NULL on this path – a matrix carries no node-level transitions. The sequence and edge-list paths of build_mcml fill in a tidy edge table here.

meta

List with type (always "aggregate" here), method, directed, n_nodes, n_clusters, cluster_sizes (named integer vector) and source ("matrix").

See Also

build_mcml to build an mcml from raw transitions instead of a weight matrix, as_tna to promote the layers to netobjects, macro_network for the cluster-level network with one cluster expanded back into its member states

Examples

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

cs <- cluster_summary(mat, c(1, 1, 1, 2, 2, 2, 3, 3, 3, 3))
cs            # cluster-level (macro) weights
summary(cs)   # one row per cluster

# -----------------------------------------------------
# Named list clusters (more readable)
# -----------------------------------------------------
clusters <- list(
  Alpha = c("A", "B", "C"),
  Beta = c("D", "E", "F"),
  Gamma = c("G", "H", "I", "J")
)
cluster_summary(mat, clusters)

# -----------------------------------------------------
# A netobject as input: its weight matrix is aggregated
# -----------------------------------------------------
seqs <- data.frame(
  T1 = c("A", "C", "B", "D"), T2 = c("B", "D", "A", "C"),
  T3 = c("C", "A", "D", "B")
)
net <- build_network(seqs, method = "relative")
cluster_summary(net, list(G1 = c("A", "B"), G2 = c("C", "D")))

# -----------------------------------------------------
# Different aggregation methods
# -----------------------------------------------------
summary(cluster_summary(mat, clusters, method = "sum"))   # total flow
summary(cluster_summary(mat, clusters, method = "mean"))  # average
summary(cluster_summary(mat, clusters, method = "max"))   # strongest

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

# -----------------------------------------------------
# Promote the layers to netobjects
# (as_tna() stores the aggregated weights as they are)
# -----------------------------------------------------
as_tna(cluster_summary(mat, clusters, method = "sum"))

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

# A three-variable ESM panel: 20 people x 20 beeps. `tired` is driven by
# `happy` one beep earlier, so the temporal network should recover it.
if (requireNamespace("lme4", quietly = TRUE)) {
  set.seed(1)
  n_beep <- 20
  ar1 <- function(n, phi) as.numeric(stats::filter(stats::rnorm(n), phi,
                                                   method = "recursive"))
  panel <- do.call(rbind, lapply(seq_len(20), function(i) {
    happy <- ar1(n_beep, 0.4)
    data.frame(
      id    = i,
      beep  = seq_len(n_beep),
      happy = happy + stats::rnorm(1),
      calm  = ar1(n_beep, 0.3) + stats::rnorm(1),
      tired = 0.5 * c(0, happy[-n_beep]) + stats::rnorm(n_beep) +
              stats::rnorm(1)
    )
  }))
  fit <- build_mlvar(panel, vars = c("happy", "calm", "tired"),
                     id = "id", beep = "beep")
  fit
  coefs(fit)
  summary(fit)
}

Compare MMM fits across different k

Description

Compare MMM fits across different k

Usage

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

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

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

## S3 method for class 'mmm_compare'
plot(x, ...)

Arguments

Value

A mmm_compare data frame, one row per requested k, with columns k, log_likelihood, AIC, BIC, ICL, AvePP, Entropy and converged. When return_fits = TRUE, the fitted net_mmm models are attached as attr(result, "fits").

In print.mmm_compare(): The comparison table, invisibly, with the printed best marker column ("<-- BIC" / "<-- ICL") added.

In summary.mmm_compare(): A tidy data frame with one row per k, plus a best character column flagging the minimum-BIC and minimum-ICL solutions.

In plot.mmm_compare(): A ggplot object, invisibly.

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 the fits so the chosen model needs no re-run; summary() marks
# the minimum-BIC and minimum-ICL rows in its `best` column.
comp_with_fits <- compare_mmm(seqs, k = 2:3, seed = 42, return_fits = TRUE)
summary(comp_with_fits)

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,
  ...
)

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

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

## S3 method for class 'net_comparison'
plot(
  x,
  type = c("scatter", "heatmap", "diff_hist", "weight_dist", "all"),
  combined = 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.

In print.net_comparison(): x, invisibly.

In plot.net_comparison(): A ggplot object; for type = "all" with combined = TRUE a gtable arranged 2 by 2; for type = "all" with combined = FALSE a named list of four ggplots.

Methods

• compare_model.netobject_group(): Selects two members of a netobject_group (by index or name) and dispatches to compare_model.netobject(). See also compare_networks, the N-way successor with tidy tables and a plot() that draws one view per call.

• plot.net_comparison(): Visualises a net_comparison object. Currently supports the edge-weight scatterplot (default), with the diagonal reference (perfect agreement) and the OLS regression line annotated by Pearson, Spearman, and Kendall correlations.

Examples

nets <- build_network(group_regulation_long, method = "relative",
                      actor = "Actor", action = "Action", time = "Time",
                      group = "Achiever")
compare_model(nets)

Compare two or more networks

Description

Compares any number of networks pairwise (all pairs, or every network against one reference) and returns one tidy object: an edge table, a node (centrality) table, a global-metric table and per-network structural metrics, each returned by a named verb and carrying a pair column so nothing ever needs list indexing. Descriptive by default; ⁠test =⁠ adds permutation, Bayesian and bootstrap evidence to the same tables. plot() draws one view per call.

Usage

compare_networks(
  ...,
  reference = NULL,
  scaling = c("none", "minmax", "max", "rank", "zscore", "robust", "log", "log1p",
    "softmax", "quantile", "frobenius", "row"),
  measures = c("InStrength", "OutStrength", "Betweenness"),
  labels = NULL,
  test = "none",
  iter = 1000L,
  alpha = 0.05,
  adjust = "none",
  paired = FALSE,
  rope = NULL,
  seed = NULL,
  actor = NULL
)

## S3 method for class 'net_network_comparison'
print(x, digits = 2L, ...)

## S3 method for class 'net_network_comparison'
plot(
  x,
  type = c("networks", "difference", "edges", "nodes", "global", "heatmap", "scatter",
    "inference"),
  pair = NULL,
  combined = TRUE,
  top_n = 20L,
  measure = NULL,
  labels = TRUE,
  digits = 2L,
  what = NULL,
  ...
)

Arguments