Package 'Saqrlab'

Description

Apply a function to a list of TNA models or datasets, with optional parallel processing.

Usage

batch_apply(
  object_list,
  fun,
  parallel = FALSE,
  cores = NULL,
  progress = TRUE,
  simplify = FALSE,
  ...
)

Arguments

Details

This is a general-purpose function for batch operations on model lists. It handles errors gracefully, returning NULL for failed operations.

Value

A list of results from applying fun to each element. If simplify = TRUE and results are atomic, returns a simplified vector.

See Also

batch_fit_models for fitting multiple models.

Examples

## Not run: 
# Extract transition matrices from multiple models
trans_mats <- batch_apply(models, extract_transition_matrix)

# Compare each model to a reference
ref_model <- models[[1]]
comparisons <- batch_apply(
  models[-1],
  function(m) compare_networks(ref_model, m)$metrics$correlation
)

# Extract centralities with simplification
centralities <- batch_apply(
  models,
  function(m) tna::centralities(m),
  simplify = FALSE
)

## End(Not run)

Description

Fit TNA models to multiple datasets at once, with optional parallel processing.

Usage

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

Arguments

Details

This function provides a convenient way to fit TNA models to many datasets, such as when running simulations or analyzing multiple groups.

For parallel processing on Windows, set up a parallel backend first using the future package.

Value

A list of fitted model objects, with the same names/indices as data_list. Failed fits are returned as NULL with a warning.

See Also

fit_network_model for fitting a single model, batch_apply for applying functions to model lists.

Examples

## Not run: 
# Generate multiple datasets
datasets <- lapply(1:10, function(i) {
  simulate_sequences(trans_mat, init_probs, max_seq_length = 20, num_rows = 100)
})

# Fit models in sequence
models <- batch_fit_models(datasets, model_type = "tna")

# Fit models in parallel
models <- batch_fit_models(datasets, model_type = "tna",
                           parallel = TRUE, cores = 4)

# Check results
sapply(models, function(m) if (!is.null(m)) "OK" else "Failed")

## End(Not run)

Description

Compare centrality measures between two TNA networks using correlation or rank-based methods.

Usage

compare_centralities(
  model1,
  model2,
  measures = c("OutStrength", "InStrength", "Betweenness"),
  method = c("both", "correlation", "rank")
)

Arguments

Details

Centrality measures are extracted from the TNA model objects using tna::centralities(). The function compares how well the centrality profiles are preserved between the original and simulated/comparison model.

Value

A list containing:

• correlations: Named list of correlation values by measure.

• centrality_comparison: Data frame with centrality values for each state.

• summary: Character summary of the comparison.

See Also

compare_networks() for full network comparison.

Examples

## Not run: 
# Compare centrality profiles between models
comparison <- compare_centralities(model_original, model_simulated)
print(comparison$correlations)

## End(Not run)

Description

Calculate metrics for how well edges from an original network are recovered in a simulated/comparison network.

Usage

compare_edge_recovery(
  original,
  simulated,
  threshold = 0.01,
  return_edges = FALSE
)

calculate_edge_recovery(...)

Arguments

Details

This function treats edge recovery as a binary classification problem:

• True Positive: Edge present in both original and simulated.

• False Positive: Edge present in simulated but not original.

• False Negative: Edge present in original but not simulated.

• True Negative: Edge absent in both.

An edge is considered "present" if its weight exceeds the threshold.

Value

A list containing:

• true_positives: Number of edges correctly present in both.

• false_positives: Number of edges present in simulated but not original.

• false_negatives: Number of edges present in original but not simulated.

• true_negatives: Number of edges correctly absent in both.

• precision: TP / (TP + FP).

• recall: TP / (TP + FN), also known as sensitivity.

• f1_score: Harmonic mean of precision and recall.

• accuracy: (TP + TN) / total edges.

• jaccard: TP / (TP + FP + FN), Jaccard similarity.

• edges: (Optional) Data frame with edge-level results.

See Also

compare_networks() for full network comparison, run_bootstrap_iteration() for bootstrap evaluation.

Examples

## Not run: 
# Calculate edge recovery
recovery <- compare_edge_recovery(model_original, model_simulated)
print(sprintf("Precision: %.2f, Recall: %.2f", recovery$precision, recovery$recall))

## End(Not run)

Description

Run multiple simulations comparing how well different TNA model types recover the true transition structure, using tna::compare() for each comparison. Supports any model type available in the tna package.

Usage

compare_estimation(
  models = c("tna", "ftna"),
  n_simulations = 1000,
  n_sequences = 200,
  seq_length = 25,
  n_states = 6,
  na_range = c(0, 5),
  scaling = "minmax",
  seed = NULL,
  verbose = TRUE,
  parallel = FALSE,
  cores = parallel::detectCores() - 1
)

Arguments

Details

For each simulation:

1. Generate random transition probabilities (ground truth)

2. Simulate sequences with optional NAs (varying lengths)

3. Fit all specified model types

4. Compare each to ground truth using tna::compare()

5. Collect metrics (Pearson, Spearman, Kendall, Euclidean, etc.)

Available model types (any tna package model):

• tna: Standard transition network analysis (probabilities)

• ftna: Frequency-based TNA (raw counts)

• ctna: Concurrent TNA

• atna: Absorbing TNA

• sna: Sequential network analysis

• tsn: Time-series network

• Any other model function exported by tna package

Value

A list containing:

comparison

Side-by-side comparison of key metrics across models.

summary

Data frame with mean/sd of all metrics by model type.

raw_results

Data frame with all simulation results.

ranking

Models ranked by Pearson correlation (best to worst).

winner

Model with highest Pearson correlation.

params

Parameters used for the simulation.

Examples

## Not run: 
# Compare 2 models (default: tna vs ftna)
results <- compare_estimation(n_simulations = 100, seed = 42)

# Compare 3 models
results <- compare_estimation(
  models = c("tna", "ftna", "ctna"),
  n_simulations = 100,
  seed = 42
)

# Compare all 4 models
results <- compare_estimation(
  models = c("tna", "ftna", "ctna", "atna"),
  n_simulations = 500,
  parallel = TRUE,
  seed = 42
)

# View results
results$comparison  # Side-by-side metrics
results$ranking     # Best to worst
results$winner      # Top performer

## End(Not run)

Description

Perform side-by-side comparison of multiple TNA model types (tna, atna, ctna, ftna) using comprehensive sampling analysis. Uses a statistically correct approach: comparing models built on independent data subsets (sample vs remaining).

Usage

compare_network_estimation(
  data,
  model_types = c("tna", "ftna"),
  model_scaling = NULL,
  sampling_percent = 0.3,
  iterations = 100,
  seed = NULL,
  verbose = TRUE
)

compare_tna_models(
  data,
  model_types = c("tna", "ftna"),
  model_scaling = NULL,
  sampling_percent = 0.3,
  iterations = 100,
  seed = NULL,
  verbose = TRUE
)

Arguments

Details

The function workflow:

1. For each model type, builds a model from the data.

2. Runs sampling analysis comparing sample vs remaining subsets.

3. Combines all results for comparison.

This approach is statistically correct because it compares models built on independent data subsets, providing a true measure of estimation stability.

Value

A list containing:

individual

Data frame with all iteration results including model_type column.

aggregated

Data frame with aggregated metrics by model type.

ranking

Models ranked by mean Pearson correlation.

winner

Model with highest Pearson correlation.

params

Parameters used for the comparison.

Examples

## Not run: 
library(tna)
data(group_regulation)

# Compare tna and ftna models
results <- compare_network_estimation(group_regulation)
results$ranking
results$winner

# Compare all model types
results <- compare_network_estimation(
  group_regulation,
  model_types = c("tna", "atna", "ctna", "ftna"),
  iterations = 100
)

# Plot results
plot(results)  # Default histogram
plot(results, metric_name = "Pearson")

## End(Not run)

Description

Compare two TNA network models using multiple metrics including correlation, RMSE, and edge-level differences.

Usage

compare_networks(
  model1,
  model2,
  metrics = c("correlation", "rmse", "edge_diff"),
  scaling = c("none", "minmax", "zscore"),
  include_self = TRUE,
  threshold = 0.05
)

Arguments

Details

This function extracts edge weights from both models and computes various comparison metrics. Edge weights are extracted from the transition matrices stored in the TNA model objects.

Value

A list with class "tna_comparison" containing:

• metrics: Named list of computed metrics.

• edge_comparison: Data frame comparing edges from both models.

• summary: Character summary of the comparison.

See Also

compare_centralities() for comparing centrality profiles, compare_edge_recovery() for edge recovery metrics.

Examples

## Not run: 
# Generate original data and fit model
original_data <- simulate_sequences(trans_mat, init_probs, 20, 200)
model_original <- tna::tna(original_data)

# Simulate from fitted model and fit new model
sim_data <- simulate_sequences(
  transition_matrix = model_original$weights,
  initial_probabilities = model_original$initial,
  max_seq_length = 20, num_rows = 200
)
model_sim <- tna::tna(sim_data)

# Compare the models
comparison <- compare_networks(model_original, model_sim)
print(comparison$metrics)

## End(Not run)

Description

Run multiple simulations assessing split-half reliability under varying data conditions (number of sequences, sequence length, number of states). Uses tna::reliability() for each simulation with randomly sampled parameters from user-specified ranges.

Usage

compare_reliability(
  n_simulations = 1000,
  n_sequences = c(50, 500),
  seq_length = c(10, 50),
  n_states = 6,
  alpha = 1,
  diag_c = 0,
  na_range = c(0, 5),
  model_type = "tna",
  reliability_iter = 100,
  reliability_split = 0.5,
  scaling = "none",
  seed = NULL,
  verbose = TRUE,
  parallel = FALSE,
  cores = parallel::detectCores() - 1
)

Arguments

Details

For each simulation:

1. Randomly sample n_sequences, seq_length, n_states from user-specified ranges.

2. Generate ground truth via generate_probabilities().

3. Simulate sequences via simulate_sequences() with those parameters and NAs.

4. Fit a TNA model (e.g., tna::tna(sequences)).

5. Run tna::reliability() on the fitted model.

6. Extract the ⁠$summary⁠ table (22 metrics with mean/sd/median/min/max/q25/q75).

7. Append simulation parameters as columns.

Value

A list of class "tna_reliability_comparison" containing:

raw_results

Data frame with all simulation results (one row per metric per simulation, with parameter columns).

summary

Data frame with mean/sd aggregated across simulations grouped by metric.

params

List of input parameters for reference.

Examples

## Not run: 
# Quick test
res <- compare_reliability(
  n_simulations = 10,
  reliability_iter = 20,
  seed = 42
)
print(res)

# Vary number of states too
res <- compare_reliability(
  n_simulations = 100,
  n_states = c(3, 8),
  reliability_iter = 50,
  seed = 42
)
plot(res)

# Parallel execution
res <- compare_reliability(
  n_simulations = 500,
  parallel = TRUE,
  seed = 42
)

## End(Not run)

Description

Perform cross-validation by testing different TNA model types on the same data, allowing comparison of model performance.

Usage

cross_validate_tna(
  data,
  model_types = c("relative", "frequency", "co-occurrence"),
  sampling_percent = 0.3,
  iterations = 50,
  seed = NULL,
  verbose = TRUE
)

Arguments

Value

A list containing cross-validation results for each model type.

Examples

## Not run: 
data(group_regulation, package = "tna")
cv_results <- cross_validate_tna(
  group_regulation,
  model_types = c("relative", "frequency"),
  iterations = 30
)

## End(Not run)

Description

Write a tidy simulation data.frame to CSV. A list of saqr_sim objects (or a single one) is first flattened with tidy_simulation_results; a data.frame is written as-is.

Usage

export_simulation(x, file)

Arguments

Value

The file path, invisibly.

Examples

s <- run_scenario("power_ttest", seed = 1)
path <- tempfile(fileext = ".csv")
export_simulation(s, path)

Description

Fit a TNA (Temporal Network Analysis) model to sequence data using one of several available model types.

Usage

fit_network_model(sequences, model_type, group = NULL)

Arguments

Details

This function is a wrapper around the tna package's model fitting functions. It provides a unified interface for fitting different types of TNA models.

For group_tna models, the sequences data frame must contain a column identifying the group membership of each sequence, specified by the group parameter.

Value

A fitted TNA model object of the appropriate class.

Examples

## Not run: 
# Generate some sequence data
trans_mat <- matrix(c(
  0.7, 0.2, 0.1,
  0.3, 0.5, 0.2,
  0.2, 0.3, 0.5
), nrow = 3, byrow = TRUE)
rownames(trans_mat) <- colnames(trans_mat) <- c("A", "B", "C")
init_probs <- c(A = 0.5, B = 0.3, C = 0.2)

sequences <- simulate_sequences(
  transition_matrix = trans_mat,
  initial_probabilities = init_probs,
  max_seq_length = 20,
  num_rows = 100
)

# Fit different model types
model_tna <- fit_network_model(sequences, "tna")
model_ftna <- fit_network_model(sequences, "ftna")

# Fit group model
long_data <- simulate_long_data(n_groups = 5, actors_per_group = 10)
wide_data <- long_to_wide(long_data, id_col = "Actor")
# Add group column back
actor_groups <- unique(long_data[, c("Actor", "Group")])
wide_data <- merge(wide_data, actor_groups, by = "Actor")
model_group <- fit_network_model(wide_data, "group_tna", group = "Group")

## End(Not run)

Description

Generate a grid of parameter combinations for simulation studies using various sampling methods. Can be called with no arguments for a demo grid.

Usage

generate_param_grid(param_ranges = NULL, n = 10, method = "random")

create_param_grid(...)

Arguments

Details

Method Details:

• "random": Draws uniform random values within each range. Integer parameters (detected when min and max are both integers) are rounded.

• "grid": Creates a regular grid with approximately n^(1/d) points per dimension (where d is the number of parameters). If the resulting grid exceeds n points, it is randomly subsampled.

• "lhs": Uses Latin Hypercube Sampling for space-filling designs that provide better coverage of the parameter space than random sampling.

Categorical parameters are sampled uniformly with replacement for all methods.

Value

A data frame with n rows and columns for each parameter.

Examples

# Simplest usage: demo grid with default TNA parameters
grid <- generate_param_grid()
head(grid)

# Define custom parameter ranges
ranges <- list(
  num_rows = c(50, 500),       # Integer parameter
  max_seq_length = c(10, 100), # Integer parameter
  stability_prob = c(0.7, 1.0) # Continuous parameter
)

# Random sampling
grid_random <- generate_param_grid(ranges, n = 20, method = "random")

# Latin Hypercube Sampling
grid_lhs <- generate_param_grid(ranges, n = 20, method = "lhs")

# Grid sampling
grid_regular <- generate_param_grid(ranges, n = 20, method = "grid")

Description

Generate random transition probabilities and initial state probabilities for a Markov chain using the seqHMM package.

Usage

generate_probabilities(
  n_states = 8,
  states = NULL,
  alpha = 1,
  diag_c = 0,
  seed = NULL,
  possible_state_names = NULL
)

Arguments

Details

The transition probabilities are generated using seqHMM::simulate_transition_probs() and initial probabilities using seqHMM::simulate_initial_probs().

Value

A list containing:

initial_probs

Named numeric vector of initial state probabilities.

transition_probs

Square matrix of transition probabilities with row and column names set to state names.

state_names

Character vector of state names used.

Examples

## Not run: 
# Generate probabilities for 4 states with default names
probs <- generate_probabilities(n_states = 4, seed = 42)

# Generate probabilities with custom state names
probs <- generate_probabilities(
  n_states = 4,
  states = c("A", "B", "C", "D", "E"),
  seed = 123
)

# View initial probabilities
probs$initial_probs

# View transition matrix
probs$transition_probs

# Old parameter name still works
probs <- generate_probabilities(
  n_states = 3,
  possible_state_names = c("X", "Y", "Z")
)

## End(Not run)

Description

Retrieve names from the global names dataset, with optional filtering by region.

Usage

get_global_names(n = NULL, regions = "all", seed = NULL)

Arguments

Value

Character vector of names.

See Also

list_name_regions for available regions, GLOBAL_NAMES for the full dataset.

Examples

# Get 20 random names from all regions
get_global_names(20, seed = 42)

# Get 10 names from Arab region
get_global_names(10, regions = "arab")

# Get 15 names from any African region
get_global_names(15, regions = "africa")

# Get names from multiple regions
get_global_names(20, regions = c("east_asia", "south_asia"))

# Get all Nordic names
get_global_names(regions = "nordic")

Description

Retrieve learning action verbs by category, with options for random selection and combining multiple categories.

Usage

get_learning_states(categories = "all", n = NULL, seed = NULL)

Arguments

Value

Character vector of learning state verbs.

Examples

# All metacognitive verbs
get_learning_states("metacognitive")

# 10 random verbs from all categories
get_learning_states(n = 10, seed = 42)

# 5 verbs from cognitive and behavioral
get_learning_states(c("cognitive", "behavioral"), n = 5)

# Self-regulated learning focus (metacognitive + motivational)
get_learning_states(c("metacognitive", "motivational"))

Description

Retrieve the argument-lists for a named scenario. With case = NULL the full list of argument-lists is returned; with an integer case the single argument-list for that case is returned, ready to do.call() against the scenario's simulator.

Usage

get_scenario(scenario, case = NULL)

Arguments

Value

When case = NULL, a list of named argument-lists. When case is an integer, a single named argument-list.

Examples

get_scenario("power_ttest")
get_scenario("power_ttest", case = 1)

Description

A collection of ~1000 culturally diverse names from around the world, organized by region for use in social network simulations.

Usage

GLOBAL_NAMES

Format

A named list of character vectors, with each element containing names from a specific region.

Details

Regions are organized geographically and include:

Europe:

• western_europe: UK, Ireland, France, Germany, Netherlands, Belgium

• eastern_europe: Russia, Ukraine, Poland, Czech, Romania, Hungary, Bulgaria

• southern_europe: Spain, Italy, Portugal, Greece

• nordic: Sweden, Norway, Denmark, Finland, Iceland

Middle East & Central Asia:

• arab: Gulf states, Levant, Egypt

• persian: Iran, Afghanistan, Tajikistan

• turkish: Turkey, Azerbaijan

• central_asia: Kazakhstan, Uzbekistan, Kyrgyzstan, Turkmenistan

Asia:

• south_asia: India, Pakistan, Bangladesh, Sri Lanka, Nepal

• east_asia: China, Japan, Korea, Mongolia

• southeast_asia: Vietnam, Thailand, Indonesia, Philippines, Malaysia

Africa:

• west_africa: Nigeria, Ghana, Senegal, Mali

• east_africa: Kenya, Ethiopia, Tanzania, Somalia, Uganda

• southern_africa: South Africa, Zimbabwe, Botswana, Namibia

• north_africa: Morocco, Algeria, Tunisia, Libya

• central_africa: DRC, Cameroon, Congo

Americas:

• north_america: USA, Canada

• latin_america: Mexico, Central America, South America, Brazil

• caribbean: Jamaica, Haiti, Cuba, Trinidad, Dominican Republic

• indigenous_americas: Native American, First Nations, Mayan, Incan

Oceania:

• australia_nz: Australia, New Zealand

• pacific_islands: Hawaii, Samoa, Tonga, Fiji, PNG

• indigenous_oceania: Maori, Aboriginal Australian

Other:

• jewish_hebrew: Hebrew/Jewish names

• armenian_georgian: Armenia, Georgia

See Also

get_global_names for sampling names, list_name_regions for exploring available regions.

Examples

# View all region names
names(GLOBAL_NAMES)

# View names from a specific region
GLOBAL_NAMES$arab
GLOBAL_NAMES$east_asia

# Count names per region
sapply(GLOBAL_NAMES, length)

# Total names available
sum(sapply(GLOBAL_NAMES, length))

Description

The 9 standard group regulation (SSRL) actions used in collaborative learning research.

Usage

GROUP_REGULATION_ACTIONS

Format

A character vector of 9 actions.

Details

These actions represent Socially Shared Regulation of Learning (SSRL):

adapt

Adjusting strategies based on feedback

cohesion

Building and maintaining group unity

consensus

Reaching group agreement

coregulate

Mutually regulating each other's learning

discuss

Engaging in group discussion

emotion

Expressing or regulating emotions

monitor

Tracking and evaluating progress

plan

Planning group activities and strategies

synthesis

Integrating and combining ideas

Examples

GROUP_REGULATION_ACTIONS

# Use in simulation
data <- simulate_long_data(
  n_groups = 10,
  states = GROUP_REGULATION_ACTIONS,
  seed = 42
)

Description

Take an existing complete data.frame and inject missing values (NA) into target columns under a chosen, well-defined missingness mechanism. This is a transformer, not a generator: the returned object is the same data.frame with some cells replaced by NA, carrying an attached "missing_info" attribute that records exactly which cells were made missing and how. Useful for testing imputation methods and missing-data-aware estimators against a known ground truth.

The three mechanisms follow the standard Rubin taxonomy:

"MCAR"

Missing Completely At Random. Each cell of the target columns is independently set missing with probability prop.

"MAR"

Missing At Random. The probability that a target cell is missing depends on an observed predictor column, never on the to-be-missing value itself. Probabilities are calibrated (via a rank/logistic weighting on the predictor) so the average missing fraction is approximately prop.

"MNAR"

Missing Not At Random. The probability that a target cell is missing depends on that cell's own (numeric) value: larger values are more likely to go missing. Calibrated so the average missing fraction per column is approximately prop.

Usage

inject_missingness(
  data,
  mechanism = c("MCAR", "MAR", "MNAR"),
  prop = 0.1,
  cols = NULL,
  predictor = NULL,
  seed = NULL
)

Arguments

Value

The input data.frame with NAs injected into the target columns. The returned object additionally carries an attribute "missing_info", a list with elements:

mechanism

The resolved mechanism string.

prop

The requested target proportion.

cols

The target column names actually used.

n_missing

Total number of cells set missing.

realized_prop

Realized fraction of target cells set missing (n_missing / (nrow * length(cols))).

indicator

A logical matrix (nrow(data) x length(cols)) marking the cells that were injected as TRUE, with column names matching cols.

Examples

df <- simulate_prediction(
  n = 500,
  coefs = c("(Intercept)" = 1, x1 = 2, x2 = -1),
  seed = 1
)$data

# MCAR: 20% of every column missing at random
mcar <- inject_missingness(df, mechanism = "MCAR", prop = 0.2, seed = 7)
attr(mcar, "missing_info")$realized_prop
str(attr(mcar, "missing_info"))

# MAR: missingness in y driven by observed x1
mar <- inject_missingness(df, mechanism = "MAR", prop = 0.2,
                          cols = "y", predictor = "x1", seed = 7)
colSums(is.na(mar))

# MNAR: large y-values more likely missing
mnar <- inject_missingness(df, mechanism = "MNAR", prop = 0.2,
                           cols = "y", seed = 7)
attr(mnar, "missing_info")$n_missing

Description

Predefined collections of student learning action verbs organized by category. These can be used as state names when generating TNA networks to simulate realistic student learning behavior sequences.

Usage

LEARNING_STATES

Format

A named list with 8 categories of learning verbs.

Details

The verbs are organized into seven categories based on learning science:

metacognitive

Self-regulation and awareness actions: planning, monitoring, evaluating one's own learning.

cognitive

Mental processing actions: understanding, analyzing, synthesizing information.

behavioral

Observable study actions: reading, writing, practicing, note-taking.

social

Interaction and collaboration actions: discussing, helping, teaching, asking.

motivational

Effort and persistence actions: focusing, persisting, engaging, striving.

affective

Emotional and attitudinal states: enjoying, coping, managing stress, curiosity.

group_regulation

Socially shared regulation of learning (SSRL): collaborative planning, monitoring, adapting in groups.

lms

Learning Management System actions: viewing content, accessing resources, submitting assignments, forum posts.

Examples

# Get all available categories
names(get_learning_states())

# Get cognitive verbs only
get_learning_states("cognitive")

# Get multiple categories
get_learning_states(c("metacognitive", "cognitive"))

# Get all verbs combined
get_learning_states("all")

# Random selection of 8 verbs
get_learning_states(n = 8)

# Random 6 verbs from social and cognitive
get_learning_states(c("social", "cognitive"), n = 6)

Description

Display a summary of all available learning state categories and the number of verbs in each.

Usage

list_learning_categories()

Value

A data frame with category names and verb counts.

Examples

list_learning_categories()

Description

Display all available regions and shortcuts for selecting names from GLOBAL_NAMES.

Usage

list_name_regions()

Value

A data frame with region names, counts, and example names.

Examples

list_name_regions()

Description

Return a tidy catalogue of the built-in scenario presets. Each scenario is a hard-coded recipe of argument-lists targeting one simulate_* function. Print the result directly.

Usage

list_scenarios()

Value

A base data.frame with one row per scenario and columns scenario, description, simulator (the target simulate_* function) and n_cases (number of argument-lists in the recipe).

Examples

list_scenarios()

Description

Return the catalogue of simulation types reachable through simulate, one row per type, with the underlying function name and a one-line description. Print it directly.

Note: this lists the explicit-parameter simulators (those returning a saqr_sim). The separate simulate_data entry point provides random, seed-driven generation and returns a bare data.frame; it is not part of this catalogue.

Usage

list_simulators()

Value

A base data.frame with one row per simulator and columns:

type

The type string passed to simulate.

function

The name of the underlying simulator function.

description

A short one-line description.

See Also

simulate

Examples

list_simulators()

Description

Create publication-ready plots for network estimation comparison results. Default is a histogram optimized for high iteration counts.

Usage

plot_network_estimation(
  results,
  metric_name = "Pearson",
  plot_type = "histogram",
  show_stats = TRUE,
  bins = NULL
)

Arguments

Details

The histogram plot is optimized for high iteration counts (100+) and shows:

• Turquoise bars with density overlay

• Green vertical line for mean

• Orange dotted line for median

• Subtitle with exact mean and median values

Value

A ggplot object.

Examples

## Not run: 
results <- compare_network_estimation(group_regulation, iterations = 100)

# Default histogram
plot_network_estimation(results)

# Different metrics
plot_network_estimation(results, metric_name = "Spearman")
plot_network_estimation(results, metric_name = "Euclidean")

# Different plot types
plot_network_estimation(results, plot_type = "boxplot")
plot_network_estimation(results, plot_type = "density")

## End(Not run)

Description

Create a visualization showing the distribution of a single metric's values across all sampling iterations.

Usage

plot_sampling_distribution(individual_results, category, metric)

Arguments

Value

A ggplot object showing the distribution.

Examples

## Not run: 
library(tna)
model <- tna(group_regulation)
results <- run_sampling_analysis(model, iterations = 100)

# Plot Pearson correlation distribution
plot_sampling_distribution(
  results$individual,
  category = "Correlations",
  metric = "Pearson"
)

## End(Not run)

Description

Visualize the distribution of metrics from TNA model comparisons. Supports multiple plot types including histogram (default), boxplot, ridgeline, bar, and density plots.

Usage

plot_tna_comparison(
  results,
  plot_type = "histogram",
  metric_name = "Pearson",
  model_types = NULL,
  binwidth = NULL
)

Arguments

Details

Available plot types:

boxplot

Box plots showing distribution by model type.

ridgeline

Ridge line plots for density comparison.

bar

Bar plots with mean values and error bars.

histogram

Histogram with density overlay (requires metric_name).

density

Density plots with mean/median lines (requires metric_name).

Value

A ggplot object.

Examples

## Not run: 
library(tna)
data(group_regulation)

# Run comparison
results <- compare_tna_models(
  group_regulation,
  model_types = c("tna", "atna"),
  iterations = 30
)

# Boxplot of Pearson correlation
plot_tna_comparison(results$individual, "boxplot", metric_name = "Pearson")

# Histogram of single metric
plot_tna_comparison(results$individual, "histogram", metric_name = "Pearson")

# All metrics as bar chart
plot_tna_comparison(results$individual, "bar")

## End(Not run)

Description

Plot method for network_estimation objects. Default is histogram with density overlay showing mean and median values.

Usage

## S3 method for class 'network_estimation'
plot(x, metric_name = "Pearson", plot_type = "histogram", ...)

Arguments

Value

A ggplot object.

Examples

## Not run: 
results <- compare_network_estimation(group_regulation)
plot(results)  # Histogram of Pearson correlation
plot(results, metric_name = "Spearman")
plot(results, plot_type = "boxplot")

## End(Not run)

Description

Plot Method for TNA Reliability Comparison

Usage

## S3 method for class 'tna_reliability_comparison'
plot(x, metric = "Pearson", type = "scatter", ...)

Arguments

Description

Print Network Estimation Results

Usage

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

Arguments

Description

Print Method for TNA Reliability Comparison

Usage

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

Arguments

Description

Performs a single bootstrap evaluation run: generates sequences, fits a TNA model, runs bootstrap analysis, and computes classification metrics for edge detection compared to ground truth stable transitions.

Usage

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

evaluate_bootstrap(...)

Arguments

Details

The function:

1. Generates sequences using simulate_sequences_advanced().

2. Fits a TNA model and runs bootstrap analysis.

3. Creates a ground truth matrix from stable_transitions.

4. Compares bootstrap-significant edges to ground truth.

5. Computes TP, TN, FP, FN and derived metrics per edge.

An edge is considered "significant" if its p-value < level.

Value

A list containing:

per_edge

Data frame with per-edge results including ground truth, bootstrap significance, TP/TN/FP/FN, p-values, and metrics.

bootstrap_summary_raw

Raw bootstrap summary from tna::bootstrap.

TP_matrix

Matrix of true positives by edge.

TN_matrix

Matrix of true negatives by edge.

FP_matrix

Matrix of false positives by edge.

FN_matrix

Matrix of false negatives by edge.

Returns NULL if bootstrap fails.

Examples

## Not run: 
# Create transition matrix
trans_mat <- matrix(c(
  0.6, 0.3, 0.1,
  0.2, 0.6, 0.2,
  0.1, 0.2, 0.7
), nrow = 3, byrow = TRUE)
rownames(trans_mat) <- colnames(trans_mat) <- c("A", "B", "C")
init_probs <- c(A = 0.33, B = 0.34, C = 0.33)

# Define ground truth stable edges
stable <- list(c("A", "B"), c("B", "C"))

# Run single bootstrap evaluation
result <- run_bootstrap_iteration(
  trans_matrix = trans_mat,
  init_probs = init_probs,
  stable_transitions = stable,
  seq_length = 30,
  n_sequences = 100,
  stability_prob = 0.95,
  unstable_mode = "random_jump",
  unstable_random_transition_prob = 0.5,
  na_range = c(0, 5),
  include_na = TRUE,
  consistency_range = c(0.75, 1.25),
  level = 0.05
)

# Old parameter names still work
result <- run_bootstrap_iteration(
  transition_matrix = trans_mat,
  initial_probabilities = init_probs,
  stable_transitions = stable,
  max_seq_length = 30,
  num_rows = 100
)

## End(Not run)

Description

Simulate and analyze edge recovery across multiple bootstrap runs. Aggregates results to compute overall performance metrics and edge-level significance.

Usage

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

Arguments

Details

For each run, the function calls run_bootstrap_iteration() and accumulates TP/TN/FP/FN counts. After all runs, it computes:

• Overall Performance: Aggregated sensitivity (TPR), specificity (TNR), false positive rate (FPR), and false negative rate (FNR).

• Edge Significance: For each edge, the number of times it was detected as significant, average p-value, average weight, and recovery rate.

Parallel processing uses parallel::mclapply().

Value

A list containing:

aggregated_summary

List with:

• overall_performance: Data frame with Sensitivity, Specificity, FPR, FNR.

• edge_significance: Data frame with per-edge recovery rates and statistics.

individual_runs

List with:

• list_of_summaries: Bootstrap summaries from each run.

• list_of_per_edge_performance: Per-edge results from each run.

successful_runs

Number of successfully completed runs.

Examples

## Not run: 
# First create a TNA model from some data
trans_mat <- matrix(c(
  0.6, 0.3, 0.1,
  0.2, 0.6, 0.2,
  0.1, 0.2, 0.7
), nrow = 3, byrow = TRUE)
rownames(trans_mat) <- colnames(trans_mat) <- c("A", "B", "C")

# Create a mock Model object
Model <- list(
  weights = trans_mat,
  inits = c(A = 0.33, B = 0.34, C = 0.33)
)

# Define stable transitions
stable <- list(c("A", "B"), c("B", "C"))

# Run bootstrap simulation
results <- run_bootstrap_simulation(
  Model = Model,
  stable_transitions = stable,
  num_runs = 50,
  seq_length = 30,
  n_sequences = 100,
  stability_prob = 0.95,
  unstable_mode = "random_jump",
  num_cores = 4
)

# View overall performance
results$aggregated_summary$overall_performance

# View edge-level results
results$aggregated_summary$edge_significance

# Old parameter names still work
results <- run_bootstrap_simulation(
  Model = Model,
  stable_transitions = stable,
  num_runs = 50,
  max_seq_length = 30,
  num_rows = 100
)

## End(Not run)

Description

Execute bootstrap simulations across a grid of parameter combinations. Useful for studying how different settings affect edge recovery performance.

Usage

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

Arguments

Details

The function creates a full factorial grid from:

• n_sequences_vec x seq_length_vec x na_range_list

For each combination, it runs run_bootstrap_simulation() and stores the results along with the parameter values used.

Progress messages are printed to track execution.

Value

A named list where each element corresponds to a parameter combination. Names follow the pattern ⁠nr<n_sequences>_sl<seq_length>_na<min>-<max>⁠. Each element contains:

aggregated_summary

Aggregated performance and edge significance.

individual_runs

Per-run details.

successful_runs

Number of successful runs.

parameters

The parameter values used for this combination.

Examples

## Not run: 
# Create a model
trans_mat <- matrix(c(
  0.6, 0.3, 0.1,
  0.2, 0.6, 0.2,
  0.1, 0.2, 0.7
), nrow = 3, byrow = TRUE)
rownames(trans_mat) <- colnames(trans_mat) <- c("A", "B", "C")

Model <- list(
  weights = trans_mat,
  inits = c(A = 0.33, B = 0.34, C = 0.33)
)

stable <- list(c("A", "B"), c("B", "C"))

# Run grid search
grid_results <- run_grid_simulation(
  Model = Model,
  stable_transitions = stable,
  num_runs = 20,
  n_sequences_vec = c(50, 100, 200),
  seq_length_vec = c(20, 30, 50),
  na_range_list = list(
    list(min = 0, max = 0),
    list(min = 0, max = 5),
    list(min = 5, max = 10)
  ),
  num_cores = 4
)

# Analyze results
summarize_grid_results(grid_results)

# Old parameter names still work
grid_results <- run_grid_simulation(
  Model = Model,
  stable_transitions = stable,
  num_runs = 20,
  num_rows_vec = c(50, 100, 200),
  max_seq_length_vec = c(20, 30, 50)
)

## End(Not run)

Description

Run TNA simulations comparing fitted models to original data. Supports multiple model types, comparison modes, and parallel processing.

Usage

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

Arguments

Details

For each parameter combination and original dataset, the function:

1. Extracts transition probabilities from the original TNA model.

2. Generates simulated sequences using those probabilities.

3. Fits the specified model types to the simulated sequences.

4. Computes comparison metrics against reference models.

Parallel processing uses the future.apply package when enabled.

Value

A list containing:

metrics

Data frame of all comparison metrics from all runs.

summary_stats

Aggregated summary statistics by model and comparison type.

parameters

List of simulation parameters used.

Examples

## Not run: 
# Create some original sequence data
trans_mat <- matrix(c(
  0.7, 0.2, 0.1,
  0.3, 0.5, 0.2,
  0.2, 0.3, 0.5
), nrow = 3, byrow = TRUE)
rownames(trans_mat) <- colnames(trans_mat) <- c("A", "B", "C")
init_probs <- c(A = 0.5, B = 0.3, C = 0.2)

original_data <- simulate_sequences(
  trans_matrix = trans_mat,
  init_probs = init_probs,
  seq_length = 30,
  n_sequences = 100
)

# Run simulations comparing tna and ftna models
results <- run_network_simulation(
  original_data_list = original_data,
  sim_params = list(seq_length = 30, n_sequences = 100),
  models = c("tna", "ftna"),
  comparisons = c("original"),
  num_runs = 5
)

# View summary statistics
results$summary_stats

## End(Not run)

Description

Perform comprehensive TNA model analysis through repeated sampling and statistical comparison. Uses a statistically correct sampling procedure by comparing models built on independent data subsets (sample vs remaining).

Usage

run_sampling_analysis(
  model,
  sampling_percent = 0.3,
  iterations = 100,
  seed = NULL,
  model_scaling = NULL,
  verbose = TRUE
)

Arguments

Details

This function implements a statistically correct sampling procedure:

1. Data Splitting: For each iteration, splits the original data into:

   • Sample set (specified percentage)

   • Remaining set (complement)

2. Model Building: Builds TNA models on both datasets using the original model's type and configurable scaling.

3. Model Comparison: Compares sample model vs remaining model using TNA's compare() function, providing metrics across categories:

   • Correlations (Pearson, Spearman, Kendall)

   • Dissimilarities (Euclidean, Manhattan, etc.)

   • Similarities (Cosine, Jaccard, etc.)

4. Result Aggregation: Collects metrics across all iterations and computes summary statistics (mean, sd, median, quartiles).

This approach is statistically superior to comparing sample vs original because it compares models built on independent data subsets, providing a true measure of sampling variability and model stability.

Value

A list containing:

aggregated

Data frame with aggregated summary statistics by metric.

individual

Data frame with raw metric values from each iteration.

params

Parameters used for the analysis.

Examples

## Not run: 
library(tna)
model <- tna(group_regulation)

# Basic analysis with defaults
results <- run_sampling_analysis(model, iterations = 50)
results$aggregated

# With custom parameters
results <- run_sampling_analysis(
  model,
  sampling_percent = 0.4,
  iterations = 100,
  seed = 42
)

## End(Not run)

Description

Execute every case of a scenario by do.call()-ing its argument-list against the scenario's simulator. Returns a named list of the resulting saqr_sim objects, labelled case1, case2, ...

Usage

run_scenario(scenario, seed = NULL)

Arguments

Value

A named list of saqr_sim objects, one per case, named case1, case2, ...

Examples

s <- run_scenario("power_ttest", seed = 1)
s$case1

Description

Take a TNA model, sample a percentage of its data, and re-estimate a new TNA model from the sampled data using the same parameters.

Usage

sample_tna(model, sampling_percent = 0.3, model_type = NULL, scaling = NULL)

Arguments

Value

A new TNA model object estimated from the sampled data.

Examples

## Not run: 
library(tna)
model <- tna(group_regulation)
sampled <- sample_tna(model, 0.3)

## End(Not run)

Description

Intelligently select learning states based on the number of nodes needed, optionally biasing toward specific categories.

Usage

select_states(
  n_states,
  primary_categories = NULL,
  secondary_categories = NULL,
  primary_ratio = 0.6,
  seed = NULL
)

smart_select_states(...)

Arguments

Details

Selection logic:

• If n_states <= 5: Single category or balanced small set

• If n_states 6-10: 1-2 categories prioritized

• If n_states 11-20: Multiple categories with primary focus

• If n_states > 20: All categories combined

Value

Character vector of selected learning states.

Examples

# 5 states focused on self-regulation
select_states(5, primary_categories = "metacognitive")

# 10 states: mostly cognitive, some behavioral
select_states(10,
  primary_categories = "cognitive",
  secondary_categories = "behavioral"
)

# 15 states: balanced across categories
select_states(15, seed = 42)

Description

A single discoverable entry point over every explicit-parameter simulator in the package. You pass the simulation type plus the named arguments that simulator expects, and simulate() forwards them straight through, returning that simulator's saqr_sim object unchanged. Use list_simulators to see the available types.

For random, seed-driven generation (where the seed picks both the data and the structural parameters) and a bare data.frame return, use the separate simulate_data entry point instead.

Usage

simulate(type, ..., seed = NULL)

Arguments

Value

The saqr_sim object returned by the dispatched simulator (with $data, $params, $type, $seed).

See Also

list_simulators for the catalogue of types, simulate_data for random seed-driven generation.

Examples

simulate("ttest", n_a = 50, n_b = 50, mean_a = 0, mean_b = 0.5, seed = 1)

simulate("anova", n = 30, means = c(10, 12, 15), seed = 1)

Description

Generate data for a one-way ANOVA with fully specified group means and standard deviations. Designed so that aov(score ~ group, data = r$data) recovers the true group effects at large n.

Usage

simulate_anova(n, means, sds = 1, labels = NULL, seed = NULL)

Arguments

Value

A saqr_sim object with:

$data

data.frame with columns group (factor) and score (numeric).

$params

list with means, sds (as vector), n (per-group sizes), labels, eta_squared (true population $\eta^2$).

Examples

r <- simulate_anova(n = 30, means = c(10, 12, 15), seed = 1)
summary(aov(score ~ group, data = r$data))
r$params$eta_squared

# Unequal groups and heteroscedastic
r2 <- simulate_anova(n = c(50, 30, 20), means = c(5, 5, 10),
                      sds = c(1, 2, 3), seed = 42)

Description

Generate multivariate data from a mixture of Gaussians with fully specified cluster centers and standard deviations. Designed for testing clustering algorithms where the ground truth is known.

Usage

simulate_clusters(n, centers, sds = 1, props = NULL, seed = NULL)

Arguments

Value

A saqr_sim object with:

$data

data.frame with columns x1...xd and integer column true_cluster (1...k).

$params

list with centers (matrix), sds (k x d matrix), props (normalised), n (per-cluster sizes).

Examples

centers <- matrix(c(0, 0,
                    5, 5,
                    10, 0), nrow = 3, byrow = TRUE)
r <- simulate_clusters(n = 300, centers = centers, seed = 1)
plot(x2 ~ x1, data = r$data, col = r$data$true_cluster)
r$params$centers

# Per-cluster sizes and SDs
r2 <- simulate_clusters(n = c(100, 50, 150), centers = centers,
                         sds = c(0.5, 1.0, 2.0), seed = 42)

Description

Generate multivariate normal data from an explicit correlation (or covariance) matrix. Designed so that cor(r$data) recovers sigma at large n.

Usage

simulate_correlation(n, sigma, means = NULL, var_names = NULL, seed = NULL)

Arguments

Value

A saqr_sim object with:

$data

data.frame with columns x1...xp.

$params

list with sigma (the input matrix), means, is_correlation (logical).

Examples

# Correlation matrix
R <- matrix(c(1, 0.6, 0.3,
              0.6, 1, 0.5,
              0.3, 0.5, 1), nrow = 3)
r <- simulate_correlation(n = 200, sigma = R, seed = 1)
cor(r$data)           # should approximate R
r$params$sigma        # the true matrix

# With means and custom names
r2 <- simulate_correlation(n = 500, sigma = R,
                            means = c(10, 20, 30),
                            var_names = c("IQ", "GPA", "income"), seed = 42)

Description

Generate synthetic datasets suitable for common statistical analyses. Each dataset type contains real signal so the intended analysis works out of the box. Different seeds produce structurally different datasets (varying n, effect sizes, number of groups/variables).

Usage

simulate_data(type, seed = NULL, complexity = "clean", ..., n_batch = NULL)

Arguments

Value

A data.frame (single dataset) or a list (when n_batch is non-NULL or type = "batch"). Each dataset has attributes type, info, and complexity. Batch items additionally have seed and batch_id.

See Also

simulate_sequences(), simulate_igraph()

Examples

# Single clean dataset
d <- simulate_data("ttest", seed = 42)

# With edge cases
d <- simulate_data("correlation", seed = 1, complexity = "auto")
d <- simulate_data("ttest", seed = 1, complexity = c("na", "outliers"))

# Batch of 100 ttest datasets
batch <- simulate_data("ttest", seed = 1, n_batch = 100)

# All types, 1000 datasets each
all_batches <- simulate_data("batch", seed = 1)

Description

Generate a simulated edge list for social network analysis. Creates random connections between nodes with weights and class assignments.

Usage

simulate_edge_list(
  n_nodes = 20,
  n_edges = NULL,
  edge_density = 3,
  n_classes = 3,
  directed = TRUE,
  allow_self_loops = FALSE,
  weight_range = c(0.1, 1),
  names = NULL,
  class_probs = NULL,
  seed = NULL
)

Arguments

Details

The function generates a random social network edge list with:

• Nodes named using diverse global names (or custom names)

• Random edges between nodes

• Weights uniformly distributed in the specified range

• Class assignments based on specified probabilities

For undirected networks, each edge appears once (no duplicate A-B, B-A pairs).

Value

A data frame with columns:

source

Character. Name of the source node.

target

Character. Name of the target node.

weight

Numeric. Edge weight in the specified range.

class

Integer. Class assignment (1 to n_classes).

See Also

GLOBAL_NAMES, get_global_names

Examples

# Basic usage with defaults
edges <- simulate_edge_list(seed = 42)
head(edges)

# Larger network with 5 classes
edges <- simulate_edge_list(
  n_nodes = 50,
  n_classes = 5,
  edge_density = 4,
  seed = 123
)

# Custom names and specific number of edges
edges <- simulate_edge_list(
  n_nodes = 10,
  n_edges = 30,
  names = c("Alice", "Bob", "Carol", "Dave", "Eve",
            "Frank", "Grace", "Hank", "Ivy", "Jack"),
  n_classes = 2,
  seed = 42
)

# Undirected network with unequal class distribution
edges <- simulate_edge_list(
  n_nodes = 30,
  directed = FALSE,
  n_classes = 3,
  class_probs = c(0.5, 0.3, 0.2),
  seed = 42
)

# View class distribution
table(edges$class)

Description

Generate multivariate normal data from an explicit factor model for factor analysis parameter recovery testing. The implied covariance matrix $\Sigma = \Lambda \Phi \Lambda' + \Psi$ is fully specified and stored in the return value for direct comparison with estimated covariances.

Usage

simulate_fa(loadings, phi = NULL, psi = NULL, n, seed = NULL)

Arguments

Value

A named list with elements:

data

data.frame with columns y1...yp.

params

list with loadings, phi, psi, and sigma_implied (the $p x p$ model-implied covariance matrix).

Examples

# Two orthogonal factors, 6 indicators (3 per factor)
loadings <- matrix(c(0.8, 0.7, 0.6, 0,   0,   0,
                     0,   0,   0,   0.8, 0.7, 0.6),
                   nrow = 6, ncol = 2)  # byrow = FALSE (default)
r <- simulate_fa(loadings = loadings, n = 500, seed = 1)
r$data                  # data.frame: y1..y6
r$params$sigma_implied  # implied covariance matrix

# Oblique model
phi <- matrix(c(1, 0.4, 0.4, 1), nrow = 2)
r2  <- simulate_fa(loadings = loadings, phi = phi, n = 500, seed = 1)

Description

Simulate group TNA network objects (fitted group_tna models) for simulation studies with grouped/clustered data. Each network contains multiple groups (e.g., classrooms, teams) with their own transition patterns.

Usage

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

generate_group_tna_networks(...)

Arguments

Details

This function generates a single group TNA network with multiple groups. It simulates long-format sequence data with group structure, converts it to wide format, and fits a group TNA model using tna::group_model().

Use Cases:

• Simulating classroom-level learning behavior data

• Generating team collaboration sequences

• Creating multi-group datasets for method comparison

Value

A group_tna model object (class "group_tna") containing:

networks

List of TNA networks, one per group

data

The underlying wide-format data

group

The grouping variable name

See Also

simulate_tna_networks for individual TNA models, simulate_long_data for generating long-format group data, fit_network_model for model fitting.

Examples

## Not run: 
# Generate a group TNA network with 4 groups, 15 actors each
group_net <- simulate_group_tna_networks(
  n_groups = 4,
  n_actors = 15,
  n_states = 5,
  seed = 42
)

# Variable group sizes using range notation
var_net <- simulate_group_tna_networks(
  n_groups = 5,
  n_actors = c(8, 15),
  seq_length_range = c(5, 25),
  seed = 123
)

# With specific learning category
ssrl_net <- simulate_group_tna_networks(
  n_groups = 6,
  n_actors = c(10, 20),
  categories = "group_regulation",
  seed = 456
)

# Access individual group networks
names(group_net)
group_net[[1]]$weights

# Old parameter names still work
group_net <- simulate_group_tna_networks(
  actors_per_group = 10,
  min_seq_length = 5,
  max_seq_length = 20,
  seed = 42
)

## End(Not run)

Description

Generate longitudinal data from a linear latent growth-curve model. Each subject draws a random intercept and slope from a bivariate normal with specified means, standard deviations, and correlation, then

$y_{it} = b_{0i} + b_{1i} \, t + e_{it},$

with time coded 0..(n_time - 1). The result is returned in long format. Designed so that the mean per-subject slope recovers slope_mean and the spread of per-subject intercepts recovers intercept_sd at large n.

Usage

simulate_growth(
  n = 200,
  n_time = 5,
  intercept_mean = 0,
  slope_mean = 1,
  intercept_sd = 1,
  slope_sd = 0.5,
  intercept_slope_cor = 0,
  residual_sd = 1,
  seed = NULL
)

Arguments

Value

A saqr_sim object with:

$data

long-format data.frame with columns subject (factor), time (numeric, 0..n_time-1), and y (numeric).

$params

list with means (intercept/slope), sds (intercept/slope), correlation, residual_sd, n_time, subject_intercepts (true $b_{0i}$), and subject_slopes (true $b_{1i}$).

Examples

r <- simulate_growth(n = 300, n_time = 6, slope_mean = 2,
                     intercept_sd = 1.5, seed = 1)
print(r)
head(r)

# Correlated intercepts and slopes
r2 <- simulate_growth(n = 250, intercept_slope_cor = 0.5, seed = 42)
r2$params$correlation

Description

Generate observed symbol sequences from a discrete hidden Markov model (HMM). For each sequence a latent state path is drawn from the Markov chain defined by init (initial distribution) and trans (state transition matrix); each hidden state then emits an observed symbol according to the emission matrix. The true latent paths are returned in $params$hidden_paths for parameter-recovery testing.

Usage

simulate_hmm(
  n_sequences = 50,
  seq_length = 30,
  n_states = 2,
  n_symbols = 3,
  trans = NULL,
  emission = NULL,
  init = NULL,
  seed = NULL
)

Arguments

Details

The within-sequence latent recursion is inherently sequential and is implemented with Reduce(..., accumulate = TRUE) over the time index; the work across sequences is vectorised with Map/vapply.

Value

A saqr_sim object with:

$data

long-format data.frame with columns sequence_id (integer), time (integer, 1...seq_length), and symbol (integer observed symbol in 1...n_symbols).

$params

list with trans, emission, init, n_states, n_symbols, and hidden_paths (an n_sequences x seq_length integer matrix of the TRUE latent state sequences).

Examples

r <- simulate_hmm(n_sequences = 100, seq_length = 40, seed = 1)
print(r)
r$params$trans
r$params$emission
head(as.data.frame(r))

# Explicit three-state model
tr <- matrix(c(0.8, 0.1, 0.1,
               0.1, 0.8, 0.1,
               0.1, 0.1, 0.8), nrow = 3, byrow = TRUE)
em <- matrix(c(0.7, 0.2, 0.1,
               0.1, 0.7, 0.2,
               0.2, 0.1, 0.7), nrow = 3, byrow = TRUE)
r2 <- simulate_hmm(n_sequences = 80, seq_length = 50, n_states = 3,
                   n_symbols = 3, trans = tr, emission = em, seed = 42)
summary(r2)

Description

Generate a transition matrix with multiple node types for hierarchical (HTNA), multilevel (MLNA), or multi-type (MTNA) network analysis. By default creates a 25-node matrix (5 nodes x 5 types) using learning category names.

simulate_htna(), simulate_mlna(), and simulate_mtna() are aliases that produce identical output - use whichever name fits your analysis context.

Usage

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

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

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

Arguments

Value

A list containing:

matrix

Numeric transition matrix (rows sum to 1).

node_types

Named list mapping type names to node names (for plot_htna/plot_mlna).

type_names

Character vector of type names.

n_nodes_per_type

Integer vector of node counts per type.

See Also

simulate_matrix, simulate_tna_matrix

Examples

# Default: 5 types x 5 nodes = 25 node matrix
net <- simulate_htna(seed = 42)
net$matrix
net$node_types  # List format for plot_htna/plot_mlna

# Custom number of types
net <- simulate_htna(n_nodes = 4, n_types = 3, seed = 42)

# Custom type names
net <- simulate_mlna(
  n_nodes = 6,
  type_names = c("Macro", "Meso", "Micro"),
  seed = 42
)

# Use with tna package:
# plot_htna(net$matrix, net$node_types, layout = "polygon")
# plot_mlna(net$matrix, layers = net$node_types)

Description

Generate an igraph network object using common graph algorithms with realistic node names from human names or learning states.

Usage

simulate_igraph(
  n = NULL,
  model = c("er", "ba", "ws", "sbm", "reg", "grg", "ff"),
  name_source = c("human", "states"),
  regions = "all",
  categories = "all",
  names = NULL,
  directed = FALSE,
  weighted = FALSE,
  weights = c(0.1, 1),
  p = 0.1,
  m = NULL,
  power = 1,
  m_ba = 2,
  nei = 2,
  p_rewire = 0.05,
  blocks = 3,
  p_within = 0.3,
  p_between = 0.05,
  k = 4,
  radius = 0.25,
  fw = 0.35,
  bw = 0.32,
  seed = NULL
)

Arguments

Details

This function wraps igraph's graph generation algorithms and adds:

• Meaningful node names (human names or learning states)

• Optional edge weights

• Block/community attributes for SBM

The generated networks are suitable for social network analysis, teaching network concepts, or testing TNA methods.

Value

An igraph object with vertex names and optional edge weights.

See Also

simulate_network for statnet network objects, simulate_matrix for adjacency matrices, simulate_tna_network for fitted TNA models.

Examples

library(igraph)

# Default: Erdos-Renyi with human names from all regions
g <- simulate_igraph(n = 15, seed = 42)
V(g)$name  # Diverse names like "Yuki", "Omar", "Priya"
plot(g)

# Names from specific regions
g_arab <- simulate_igraph(n = 15, regions = "arab", seed = 42)
V(g_arab)$name  # Arab names

g_africa <- simulate_igraph(n = 20, regions = "africa", seed = 42)
V(g_africa)$name  # African names from all sub-regions

# Use learning state names instead
g_states <- simulate_igraph(n = 10, name_source = "states", seed = 42)
V(g_states)$name  # Action verbs like "Plan", "Monitor", "Evaluate"

# Scale-free network (Barabasi-Albert)
g_sf <- simulate_igraph(n = 50, model = "ba", m_ba = 2, seed = 42)
degree_distribution(g_sf)

# Small-world network (Watts-Strogatz)
g_sw <- simulate_igraph(n = 30, model = "ws", nei = 4, p_rewire = 0.1, seed = 42)

# Community structure (Stochastic Block Model)
g_sbm <- simulate_igraph(n = 30, model = "sbm", blocks = 3,
                         p_within = 0.5, p_between = 0.05, seed = 42)
V(g_sbm)$block  # Community assignments

# Weighted network with custom names
g_custom <- simulate_igraph(
  n = 10,
  model = "er",
  weighted = TRUE,
  names = c("Alice", "Bob", "Carol", "Dave", "Eve",
            "Frank", "Grace", "Heidi", "Ivan", "Judy"),
  seed = 42
)
E(g_custom)$weight

Description

Generate item-response data under a known IRT model with ground-truth item and person parameters. Supports the 1PL (Rasch), 2PL, 3PL dichotomous models and the graded response model (GRM) for ordered polytomous items. Designed so that, at large n_persons, item proportion-correct recovers item difficulty (negatively) and person total score recovers true ability (positively).

Response probabilities are computed for the whole person-by-item grid in one vectorised pass (outer() / matrix ops) and responses are drawn with a single comparison against a uniform random matrix – no loops.

Usage

simulate_irt(
  n_persons = 500,
  n_items = 20,
  model = c("2PL", "1PL", "3PL", "GRM"),
  n_categories = 2,
  a = NULL,
  b = NULL,
  c = NULL,
  theta = NULL,
  seed = NULL
)

Arguments

Value

A saqr_sim object with:

$data

data.frame with n_persons rows and columns item1...itemJ. Values are 0/1 for dichotomous models and 0...n_categories - 1 for GRM.

$params

list with model, a, b, c (as used), theta (true abilities), thresholds (GRM category thresholds matrix, NULL otherwise), and n_categories.

Examples

# 2PL with default auto-generated parameters
fit <- simulate_irt(n_persons = 500, n_items = 20, model = "2PL", seed = 1)
print(fit)
fit$params$b

# Recover difficulty: easier items are answered correctly more often
prop_correct <- colMeans(as.data.frame(fit))
cor(prop_correct, fit$params$b)        # strongly negative

# Recover ability: higher total score tracks higher true theta
total <- rowSums(as.data.frame(fit))
cor(total, fit$params$theta)           # strongly positive

# Rasch (1PL): discrimination fixed at 1
simulate_irt(n_persons = 300, n_items = 10, model = "1PL", seed = 2)

# Graded response model with 4 ordered categories
simulate_irt(n_persons = 400, n_items = 8, model = "GRM",
             n_categories = 4, seed = 3)

Description

Generate synthetic binary-indicator data with known latent class structure. All item response probabilities are explicitly specified.

Usage

simulate_lca(item_probs, class_probs, n, seed = NULL)

Arguments

Value

A named list with elements:

data

data.frame with binary columns item1...itemm and integer column true_class (labels 1...K).

params

list with item_probs and class_probs (as supplied, un-normalised).

Examples

item_probs <- matrix(c(0.9, 0.1, 0.9, 0.1,
                       0.1, 0.9, 0.1, 0.9), nrow = 4, ncol = 2)
r <- simulate_lca(item_probs = item_probs, class_probs = c(0.5, 0.5),
                  n = 200, seed = 1)
r$data        # data.frame
r$params      # ground-truth parameters