The TNA-simulation family generates synthetic Temporal Network Analysis data with known ground-truth parameters. The simulate_tna_* functions build fitted tna/group_tna model objects (ready for the tna package), simulate_*_matrix/simulate_htna return transition matrices with node groupings for hierarchical/multilevel plots, and generate_probabilities produces the underlying Markov probabilities. The generate_* names are silent backward-compatibility aliases of their simulate_* counterparts and produce identical output. All examples below are seeded and kept small for fast rendering.

simulate_tna_network()

Generate a single fitted TNA network model with learning-state names — the simplest way to obtain a ready-to-use tna object ($weights, $inits, $labels, $data).

Signature

args(simulate_tna_network)
#> function (n_states = 9, n_sequences = NULL, seq_length = 25, 
#>     categories = c("metacognitive", "cognitive"), seed = NULL) 
#> NULL

Example

model <- simulate_tna_network(n_states = 4, seed = 1)
class(model)
#> [1] "tna"
names(model)
#> [1] "weights" "inits"   "labels"  "data"
head(round(model$weights, 3))     # transition weights; rows sum to 1
#>               Analyze Differentiate Elaborate Track
#> Analyze         0.345         0.270     0.020 0.365
#> Differentiate   0.129         0.268     0.255 0.348
#> Elaborate       0.165         0.292     0.098 0.446
#> Track           0.195         0.304     0.114 0.387
round(rowSums(model$weights), 3)
#>       Analyze Differentiate     Elaborate         Track 
#>             1             1             1             1
# tna ships a plot method; guard it in case the suggested deps are absent
invisible(try(plot(model), silent = TRUE))

simulate_tna_networks()

Simulate multiple independent TNA network objects for simulation studies, returning a named list of fitted tna models (no underlying data/probabilities). Alias: generate_tna_networks().

Signature

args(simulate_tna_networks)
#> function (n_networks = 1, n_states = 8, n_sequences = 100, seq_length = 30, 
#>     model_type = "tna", use_learning_states = TRUE, categories = NULL, 
#>     seed = NULL, verbose = TRUE, num_sequences = NULL, max_seq_length = NULL, 
#>     learning_categories = NULL, ...) 
#> NULL

Example

nets <- simulate_tna_networks(
  n_networks = 2, n_states = 4, n_sequences = 30, seq_length = 10,
  seed = 1, verbose = FALSE
)
length(nets)
#> [1] 2
names(nets)
#> [1] "network_1" "network_2"
class(nets[[1]])
#> [1] "tna"
head(round(nets[[1]]$weights, 3))
#>         Adapt Monitor  Plan Reflect
#> Adapt   0.260   0.589 0.041   0.110
#> Monitor 0.526   0.018 0.053   0.404
#> Plan    0.476   0.143 0.143   0.238
#> Reflect 0.109   0.084 0.059   0.748

simulate_tna_datasets()

Simulate complete TNA datasets: each element bundles the fitted model, the generating transition_probs/initial_probs, the simulated sequences, and a params list. Aliases: generate_tna_datasets(), generate_sequence_data().

Signature

args(simulate_tna_datasets)
#> function (n_datasets = 1, n_states = 8, n_sequences = 100, seq_length = 30, 
#>     states = NULL, use_learning_states = TRUE, categories = NULL, 
#>     smart_select = TRUE, na_range = c(0, 0), model_type = "tna", 
#>     use_advanced = FALSE, stable_transitions = NULL, stability_prob = 0.95, 
#>     unstable_mode = "random_jump", unstable_random_transition_prob = 0.5, 
#>     include_data = TRUE, include_probs = TRUE, seed = NULL, verbose = TRUE, 
#>     state_names = NULL, learning_categories = NULL, num_rows = NULL, 
#>     max_seq_length = NULL, min_na = NULL, max_na = NULL, include_probabilities = NULL) 
#> NULL

Example

data <- simulate_tna_datasets(
  n_datasets = 2, n_states = 4, n_sequences = 30, seq_length = 10,
  seed = 1, verbose = FALSE
)
length(data)
#> [1] 2
names(data)
#> [1] "dataset_1" "dataset_2"
names(data[[1]])                       # model, params, probs, sequences
#> [1] "model"            "params"           "transition_probs" "initial_probs"   
#> [5] "sequences"
data[[1]]$params$state_names
#> [1] "Reflect" "Adapt"   "Plan"    "Monitor"
head(data[[1]]$sequences, 3)
round(rowSums(data[[1]]$transition_probs), 3)
#> Reflect   Adapt    Plan Monitor 
#>       1       1       1       1

simulate_group_tna_networks()

Simulate a grouped/clustered TNA model (class group_tna) — one TNA network per group (e.g. classrooms or teams), built from long-format sequence data. Alias: generate_group_tna_networks().

Signature

args(simulate_group_tna_networks)
#> function (n_groups = 5, n_actors = 10, n_states = 8, seq_length_range = c(10, 
#>     30), use_learning_states = TRUE, categories = NULL, seed = NULL, 
#>     verbose = TRUE, actors_per_group = NULL, min_seq_length = NULL, 
#>     max_seq_length = NULL, learning_categories = NULL, ...) 
#> NULL

Example

group_net <- simulate_group_tna_networks(
  n_groups = 2, n_actors = 5, n_states = 3, seq_length_range = c(5, 8),
  seed = 1, verbose = FALSE
)
class(group_net)
#> [1] "group_tna"
length(group_net)                      # one tna model per group
#> [1] 2
names(group_net)
#> [1] "1" "2"
head(round(group_net[[1]]$weights, 3))
#>         Adapt  Plan Reflect
#> Adapt   0.750 0.000   0.250
#> Plan    0.333 0.444   0.222
#> Reflect 0.400 0.600   0.000

simulate_tna_matrix()

Simulate a transition matrix with node groupings, compatible with tna::plot_htna() (hierarchical) and tna::plot_mlna() (multilevel). Returns list(matrix, node_types). A convenience wrapper around simulate_htna(). Alias: generate_tna_matrix().

Signature

args(simulate_tna_matrix)
#> function (nodes_per_group = 5, group_names = c("Metacognitive", 
#>     "Cognitive", "Behavioral", "Social", "Motivational"), n_groups = 5, 
#>     edge_prob_range = c(0, 1), self_loops = FALSE, use_learning_states = TRUE, 
#>     categories = c("metacognitive", "cognitive", "behavioral", 
#>         "social", "motivational"), within_prob = 0.4, between_prob = 0.15, 
#>     node_prefix = "N", seed = NULL, verbose = TRUE, learning_categories = NULL) 
#> NULL

Example

net <- simulate_tna_matrix(
  nodes_per_group = 2, n_groups = 2,
  group_names = c("Macro", "Micro"),
  seed = 1, verbose = FALSE
)
names(net)
#> [1] "matrix"     "node_types"
dim(net$matrix)
#> [1] 4 4
round(net$matrix, 3)
#>         Reflect Adapt Read Study
#> Reflect       0     0    0     0
#> Adapt         0     0    1     0
#> Read          0     0    0     0
#> Study         0     0    0     0
round(rowSums(net$matrix), 3)          # transition matrix: rows sum to 1
#> Reflect   Adapt    Read   Study 
#>       0       1       0       0
net$node_types                         # group -> node-name mapping
#> $Macro
#> [1] "Reflect" "Adapt"  
#> 
#> $Micro
#> [1] "Read"  "Study"

simulate_htna()

Simulate a transition matrix with multiple node types for hierarchical (HTNA), multilevel (MLNA), or multi-type (MTNA) analysis. Returns list(matrix, node_types, type_names, n_nodes_per_type). simulate_mlna() and simulate_mtna() are aliases that produce identical output — choose the name matching your analysis context.

Signature

args(simulate_htna)
#> function (n_nodes = 5, n_types = 5, type_names = c("Metacognitive", 
#>     "Cognitive", "Behavioral", "Social", "Motivational"), within_prob = 0.4, 
#>     between_prob = 0.15, weight_range = c(0, 1), allow_self_loops = FALSE, 
#>     categories = c("metacognitive", "cognitive", "behavioral", 
#>         "social", "motivational"), seed = NULL) 
#> NULL

Example

htna <- simulate_htna(n_nodes = 2, n_types = 2, seed = 1)
names(htna)
#> [1] "matrix"           "node_types"       "type_names"       "n_nodes_per_type"
htna$type_names
#> [1] "Metacognitive" "Cognitive"
dim(htna$matrix)
#> [1] 4 4
round(htna$matrix, 3)
#>         Reflect Adapt Read Study
#> Reflect       0     0    0     0
#> Adapt         0     0    1     0
#> Read          0     0    0     0
#> Study         0     0    0     0
round(rowSums(htna$matrix), 3)
#> Reflect   Adapt    Read   Study 
#>       0       1       0       0
# a quick heatmap of the transition structure
image(htna$matrix, axes = FALSE, main = "simulate_htna() transition matrix")

simulate_mlna()

Multilevel-network alias of simulate_htna() — identical behaviour and return value; the name simply documents intent in multilevel (MLNA) workflows.

Signature

args(simulate_mlna)
#> function (n_nodes = 5, n_types = 5, type_names = c("Metacognitive", 
#>     "Cognitive", "Behavioral", "Social", "Motivational"), within_prob = 0.4, 
#>     between_prob = 0.15, weight_range = c(0, 1), allow_self_loops = FALSE, 
#>     categories = c("metacognitive", "cognitive", "behavioral", 
#>         "social", "motivational"), seed = NULL) 
#> NULL

Example

mlna <- simulate_mlna(
  n_nodes = 2,
  type_names = c("Macro", "Meso", "Micro"),
  seed = 1
)
mlna$type_names
#> [1] "Macro" "Meso"  "Micro"
dim(mlna$matrix)
#> [1] 6 6
round(rowSums(mlna$matrix), 3)
#>  Reflect    Adapt     Read    Study Organize Exercise 
#>        1        1        1        1        1        0

simulate_mtna()

Multi-type-network alias of simulate_htna() — identical behaviour and return value, named for multi-type (MTNA) workflows.

Signature

args(simulate_mtna)
#> function (n_nodes = 5, n_types = 5, type_names = c("Metacognitive", 
#>     "Cognitive", "Behavioral", "Social", "Motivational"), within_prob = 0.4, 
#>     between_prob = 0.15, weight_range = c(0, 1), allow_self_loops = FALSE, 
#>     categories = c("metacognitive", "cognitive", "behavioral", 
#>         "social", "motivational"), seed = NULL) 
#> NULL

Example

mtna <- simulate_mtna(n_nodes = 2, n_types = 3, seed = 1)
mtna$type_names
#> [1] "Metacognitive" "Cognitive"     "Behavioral"
dim(mtna$matrix)
#> [1] 6 6
round(rowSums(mtna$matrix), 3)
#>  Reflect    Adapt     Read    Study Organize Exercise 
#>        1        1        1        1        1        0

simulate_matrix()

Generate a single simple network matrix (transition, frequency, co-occurrence, or adjacency) with learning-state node names. A transition matrix is row-normalised (rows sum to 1).

Signature

args(simulate_matrix)
#> function (n_nodes = 9, matrix_type = c("transition", "frequency", 
#>     "co-occurrence", "adjacency"), edge_prob = 0.3, weighted = TRUE, 
#>     weight_range = c(0, 1), directed = TRUE, allow_self_loops = FALSE, 
#>     names = NULL, seed = NULL) 
#> NULL

Example

mat <- simulate_matrix(n_nodes = 4, matrix_type = "transition", seed = 1)
dim(mat)
#> [1] 4 4
round(mat, 3)
#>         Reflect Adapt  Plan Monitor
#> Reflect    0.00     0 0.000   0.000
#> Adapt      0.00     0 0.231   0.769
#> Plan       0.00     1 0.000   0.000
#> Monitor    0.63     0 0.370   0.000
round(rowSums(mat), 3)                  # rows sum to 1 (empty rows -> 0)
#> Reflect   Adapt    Plan Monitor 
#>       0       1       1       1

# co-occurrence is symmetric
co <- simulate_matrix(n_nodes = 4, matrix_type = "co-occurrence", seed = 1)
isSymmetric(co)
#> [1] TRUE

generate_tna_matrix()

Backward-compatibility alias of simulate_tna_matrix() — see that section for full documentation. It forwards all arguments unchanged.

Signature

args(generate_tna_matrix)
#> function (...) 
#> NULL

Example

net <- generate_tna_matrix(nodes_per_group = 2, n_groups = 2, seed = 1, verbose = FALSE)
identical(names(net), c("matrix", "node_types"))
#> [1] TRUE
dim(net$matrix)
#> [1] 4 4

generate_tna_networks()

Backward-compatibility alias of simulate_tna_networks() — see that section for full documentation. It forwards all arguments unchanged.

Signature

args(generate_tna_networks)
#> function (...) 
#> NULL

Example

nets <- generate_tna_networks(
  n_networks = 2, n_states = 4, n_sequences = 30, seq_length = 10,
  seed = 1, verbose = FALSE
)
length(nets)
#> [1] 2
class(nets[[1]])
#> [1] "tna"

generate_tna_datasets()

Backward-compatibility alias of simulate_tna_datasets() — see that section for full documentation. It forwards all arguments unchanged.

Signature

args(generate_tna_datasets)
#> function (...) 
#> NULL

Example

data <- generate_tna_datasets(
  n_datasets = 2, n_states = 4, n_sequences = 30, seq_length = 10,
  seed = 1, verbose = FALSE
)
length(data)
#> [1] 2
names(data[[1]])
#> [1] "model"            "params"           "transition_probs" "initial_probs"   
#> [5] "sequences"

generate_group_tna_networks()

Backward-compatibility alias of simulate_group_tna_networks() — see that section for full documentation. It forwards all arguments unchanged.

Signature

args(generate_group_tna_networks)
#> function (...) 
#> NULL

Example

g <- generate_group_tna_networks(
  n_groups = 2, n_actors = 5, n_states = 3, seq_length_range = c(5, 8),
  seed = 1, verbose = FALSE
)
class(g)
#> [1] "group_tna"
length(g)
#> [1] 2

generate_probabilities()

Generate random transition probabilities and initial-state probabilities for a Markov chain (via seqHMM). Returns list(initial_probs, transition_probs, state_names); transition-matrix rows sum to 1.

Signature

args(generate_probabilities)
#> function (n_states = 8, states = NULL, alpha = 1, diag_c = 0, 
#>     seed = NULL, possible_state_names = NULL) 
#> NULL

Example

probs <- generate_probabilities(n_states = 4, seed = 1)
names(probs)
#> [1] "initial_probs"    "transition_probs" "state_names"
probs$state_names
#> [1] "A" "B" "C" "D"
round(probs$initial_probs, 3)
#>     A     B     C     D 
#> 0.033 0.402 0.386 0.179
sum(probs$initial_probs)                # initial probs sum to 1
#> [1] 1
round(probs$transition_probs, 3)
#>       A     B     C     D
#> A 0.332 0.315 0.269 0.084
#> B 0.092 0.152 0.301 0.454
#> C 0.018 0.339 0.273 0.369
#> D 0.266 0.122 0.266 0.345
round(rowSums(probs$transition_probs), 3)
#> A B C D 
#> 1 1 1 1

generate_sequence_data()

Backward-compatibility alias of simulate_tna_datasets() — see that section for full documentation. It forwards all arguments unchanged, returning the full datasets bundle (model + probabilities + sequences).

Signature

args(generate_sequence_data)
#> function (...) 
#> NULL

Example

seqs <- generate_sequence_data(
  n_datasets = 1, n_states = 4, n_sequences = 30, seq_length = 10,
  seed = 1, verbose = FALSE
)
length(seqs)
#> [1] 1
names(seqs[[1]])
#> [1] "model"            "params"           "transition_probs" "initial_probs"   
#> [5] "sequences"
head(seqs[[1]]$sequences, 3)

sample_tna()

Take a fitted tna model (or a sequence data.frame), randomly sample a proportion of its rows, and re-estimate a new tna model with the same parameters. sampling_percent must be in (0, 1]. Useful for sampling-stability and bootstrap-style studies.

Signature

args(sample_tna)
#> function (model, sampling_percent = 0.3, model_type = NULL, scaling = NULL) 
#> NULL

Example

model   <- simulate_tna_network(n_states = 4, seed = 1)
sampled <- sample_tna(model, sampling_percent = 0.5)
class(sampled)
#> [1] "tna"
nrow(model$data)                        # rows in the original model
#> [1] 728
nrow(sampled$data)                      # ~50% of the rows, re-estimated
#> [1] 364
head(round(sampled$weights, 3))
#>               Analyze Differentiate Elaborate Track
#> Analyze         0.350         0.259     0.023 0.369
#> Differentiate   0.130         0.278     0.249 0.343
#> Elaborate       0.167         0.305     0.096 0.432
#> Track           0.199         0.297     0.118 0.386