This page covers Saqrlab’s orchestration layer: tools that run a simulation many times across a parameter grid, bootstrap edge-significance recovery, fit batches of TNA models, and summarize the resulting collections. Every example here is kept deliberately tiny (small grids, num_runs <= 3, num_cores = 1) so it runs in seconds; in practice you would use larger grids and parallel cores. A shared two-state Markov model is reused throughout.

trans <- matrix(c(.7, .3, .4, .6), 2, 2, byrow = TRUE,
                dimnames = list(c("A", "B"), c("A", "B")))
Model <- list(weights = trans, inits = c(A = 0.5, B = 0.5))
Model
#> $weights
#>     A   B
#> A 0.7 0.3
#> B 0.4 0.6
#> 
#> $inits
#>   A   B 
#> 0.5 0.5

run_grid_simulation()

Runs a TNA bootstrap recovery experiment across a grid of sample sizes, sequence lengths and missingness levels, returning one result element per parameter combination.

Signature

args(run_grid_simulation)
#> function (Model, stable_transitions, num_runs, n_sequences_vec = NULL, 
#>     seq_length_vec = NULL, na_range_list = list(list(min = 0, 
#>         max = 0)), stability_prob = 0.95, unstable_mode = "random_jump", 
#>     unstable_random_transition_prob = 0.5, unstable_perturb_noise = 0.5, 
#>     unlikely_prob_threshold = 0.1, include_na = TRUE, consistency_range = c(0.75, 
#>         1.25), level = 0.05, num_cores = parallel::detectCores() - 
#>         1, num_rows_vec = NULL, max_seq_length_vec = NULL) 
#> NULL

Example

grid <- run_grid_simulation(
  Model = Model,
  stable_transitions = list(c("A", "B")),
  num_runs = 2,
  n_sequences_vec = 20,
  seq_length_vec = 10,
  num_cores = 1
)
length(grid)
#> [1] 1
names(grid[[1]])
#> [1] "aggregated_summary" "individual_runs"    "successful_runs"   
#> [4] "parameters"

summarize_grid_results()

Aggregates a run_grid_simulation() result into overall-performance, edge-level and per-setting summaries; set print_output = FALSE to get the data back silently.

Signature

args(summarize_grid_results)
#> function (grid_results_list, n_sequences_range = NULL, seq_length_range = NULL, 
#>     min_na_range = NULL, max_na_range = NULL, level_context = 0.05, 
#>     print_output = TRUE, print_aggregated_overall = TRUE, print_aggregated_edges = TRUE, 
#>     print_settings_summary = TRUE, num_rows_range = NULL, max_seq_length_range = NULL) 
#> NULL

Example

grid_summary <- summarize_grid_results(grid, print_output = FALSE)
names(grid_summary)
#> [1] "n_selected"                   "aggregated_summary"          
#> [3] "selected_settings_summary_df" "compiled_individual_runs"
grid_summary$n_selected
#> [1] 1

analyze_grid_results()

Backward-compatible alias of summarize_grid_results() — identical behaviour and arguments.

Signature

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

Example

identical(
  analyze_grid_results(grid, print_output = FALSE)$n_selected,
  summarize_grid_results(grid, print_output = FALSE)$n_selected
)
#> [1] TRUE

run_bootstrap_simulation()

Repeats a single bootstrap edge-recovery experiment num_runs times for one fixed parameter setting and aggregates how reliably the known stable edges are recovered.

Signature

args(run_bootstrap_simulation)
#> function (Model, stable_transitions, num_runs, seq_length = 20, 
#>     n_sequences = 100, stability_prob = 0.95, unstable_mode = "random_jump", 
#>     unstable_random_transition_prob = 0.5, unstable_perturb_noise = 0.5, 
#>     unlikely_prob_threshold = 0.1, na_range = c(0, 0), include_na = TRUE, 
#>     consistency_range = c(0.75, 1.25), level = 0.05, num_cores = parallel::detectCores() - 
#>         1, max_seq_length = NULL, num_rows = NULL, min_na = NULL, 
#>     max_na = NULL) 
#> NULL

Example

boot <- run_bootstrap_simulation(
  Model = Model,
  stable_transitions = list(c("A", "B")),
  num_runs = 2,
  seq_length = 10,
  n_sequences = 20,
  num_cores = 1
)
names(boot)
#> [1] "aggregated_summary" "individual_runs"    "successful_runs"
boot$successful_runs
#> [1] 2

run_bootstrap_iteration()

The single-iteration engine underneath run_bootstrap_simulation(): simulates one dataset from a transition matrix + initial probabilities, fits a model, bootstraps it, and scores edge recovery (TP/TN/FP/FN) against the known stable edges.

Signature

args(run_bootstrap_iteration)
#> function (trans_matrix = NULL, init_probs = NULL, stable_transitions, 
#>     seq_length = 20, n_sequences = 100, stability_prob = 0.95, 
#>     unstable_mode = "random_jump", unstable_random_transition_prob = 0.5, 
#>     unstable_perturb_noise = 0.5, unlikely_prob_threshold = 0.1, 
#>     na_range = c(0, 0), include_na = TRUE, consistency_range = c(0.75, 
#>         1.25), level = 0.05, transition_matrix = NULL, initial_probabilities = NULL, 
#>     max_seq_length = NULL, num_rows = NULL, min_na = NULL, max_na = NULL) 
#> NULL

Example

iter <- run_bootstrap_iteration(
  trans_matrix = trans,
  init_probs = c(A = 0.5, B = 0.5),
  stable_transitions = list(c("A", "B")),
  seq_length = 10,
  n_sequences = 20
)
names(iter)
#> [1] "per_edge"              "bootstrap_summary_raw" "TP_matrix"            
#> [4] "TN_matrix"             "FP_matrix"             "FN_matrix"
iter$per_edge

evaluate_bootstrap()

Backward-compatible alias of run_bootstrap_iteration().

Signature

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

Example

ev <- evaluate_bootstrap(
  trans_matrix = trans,
  init_probs = c(A = 0.5, B = 0.5),
  stable_transitions = list(c("A", "B")),
  seq_length = 10,
  n_sequences = 20
)
names(ev)
#> [1] "per_edge"              "bootstrap_summary_raw" "TP_matrix"            
#> [4] "TN_matrix"             "FP_matrix"             "FN_matrix"

run_network_simulation()

Simulates many replicate datasets from observed sequence data, fits one or more TNA model types to each, and returns tidy per-replicate metrics plus aggregated summary_stats.

Signature

args(run_network_simulation)
#> function (original_data_list, sim_params = NULL, models = c("tna"), 
#>     comparisons = c("original"), num_runs = 3, parallel = FALSE, 
#>     scaling = "minmax") 
#> NULL

Example

original_data <- simulate_sequences(
  trans_matrix = trans, init_probs = c(A = 0.5, B = 0.5),
  seq_length = 12, n_sequences = 30
)
net_sim <- run_network_simulation(
  original_data_list = original_data,
  sim_params = list(seq_length = 12, n_sequences = 30),
  models = c("tna"),
  comparisons = c("original"),
  num_runs = 3
)
#> Running simulation 1/1 with parameters: seq_length=12, n_sequences=30, min_na=0, max_na=5, max_seq_length=12, num_rows=30
names(net_sim)
#> [1] "metrics"       "summary_stats" "parameters"
head(net_sim$metrics)

summarize_simulation()

Summarizes a tidy simulation-metrics data.frame (such as run_network_simulation()$metrics), optionally grouped by one or more columns, reporting mean/sd/CI per numeric column.

Signature

args(summarize_simulation)
#> function (results, by = NULL, metrics = c("mean", "sd", "ci"), 
#>     value_cols = NULL, na.rm = TRUE) 
#> NULL

Example

summarize_simulation(net_sim$metrics, by = "model_type")

summarize_networks()

Summarizes a list of fitted TNA models, reporting density, centrality and edge-count statistics per network plus an aggregate row.

Signature

args(summarize_networks)
#> function (model_list, include = c("density", "centrality", "edges"), 
#>     threshold = 0.01, centrality_measures = c("OutStrength", 
#>         "InStrength")) 
#> NULL

Example

datasets <- lapply(1:2, function(i) {
  simulate_sequences(trans_matrix = trans, init_probs = c(A = 0.5, B = 0.5),
                     seq_length = 12, n_sequences = 30)
})
models <- batch_fit_models(datasets, model_type = "tna", progress = FALSE)
net_summary <- summarize_networks(models)
names(net_summary)
#> [1] "summary_table" "aggregate"     "n_networks"
net_summary$n_networks
#> [1] 2

batch_fit_models()

Fits a TNA model type to each dataset in a list, returning a list of fitted models (with NULL entries where fitting failed). Supports optional parallel execution.

Signature

args(batch_fit_models)
#> function (data_list, model_type = c("tna", "ftna", "ctna", "atna"), 
#>     parallel = FALSE, cores = NULL, progress = TRUE, ...) 
#> NULL

Example

models <- batch_fit_models(datasets, model_type = "tna", progress = FALSE)
length(models)
#> [1] 2
vapply(models, function(m) if (!is.null(m)) "OK" else "Failed", character(1))
#> [1] "OK" "OK"

batch_apply()

Applies a function over a list of objects (e.g. fitted models), with optional parallelism, progress reporting and simplification — a thin, list-friendly wrapper for batch extraction tasks.

Signature

args(batch_apply)
#> function (object_list, fun, parallel = FALSE, cores = NULL, progress = TRUE, 
#>     simplify = FALSE, ...) 
#> NULL

Example

edge_counts <- batch_apply(
  models,
  function(m) sum(m$weights > 0, na.rm = TRUE),
  progress = FALSE
)
unlist(edge_counts)
#> [1] 4 4

generate_param_grid()

Builds a parameter grid (one row per parameter combination) via random, Latin Hypercube, or regular-grid sampling. With no arguments it returns a small demo grid of default TNA parameters.

Signature

args(generate_param_grid)
#> function (param_ranges = NULL, n = 10, method = "random") 
#> NULL

Example

head(generate_param_grid())

ranges <- list(num_rows = c(50, 100), max_seq_length = c(10, 20),
               stability_prob = c(0.7, 1.0))
generate_param_grid(ranges, n = 4, method = "lhs")

create_param_grid()

Backward-compatible alias of generate_param_grid().

Signature

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

Example

create_param_grid(list(num_rows = c(50, 100)), n = 3, method = "random")

run_sampling_analysis()

Repeatedly subsamples the sequence data underlying a fitted TNA model, refits on each subsample, and reports the stability of edge weights and centralities across iterations.

Signature

args(run_sampling_analysis)
#> function (model, sampling_percent = 0.3, iterations = 100, seed = NULL, 
#>     model_scaling = NULL, verbose = TRUE) 
#> NULL

Example

suppressMessages(library(tna))
fit <- tna(group_regulation)
samp <- run_sampling_analysis(fit, iterations = 5, sampling_percent = 0.3,
                              seed = 1, verbose = FALSE)
names(samp)
#> [1] "aggregated" "individual" "params"
head(samp$aggregated)