tna (version 1.3.1)

random_tna: Build a Random Transition Network Analysis Model

Description

Construct a fully-functional tna object from synthetic parameters without needing pre-existing sequence data. Random transition probabilities are drawn from a Dirichlet distribution, sequences are simulated from the resulting model, and a canonical tna object is fitted on those sequences.

Calling random_tna() with no arguments returns a fresh, sticky network with a coherent alphabet, drawn fresh on every call.

Usage

random_tna(
  n_states = NULL,
  states = NULL,
  category = NULL,
  alpha = NULL,
  diag_boost = NULL,
  trans_matrix = NULL,
  init_probs = NULL,
  n_sequences = NULL,
  seq_length = NULL,
  type = "relative",
  return_params = FALSE,
  seed = NULL
)

Value

A tna object, or a list with elements model, trans_matrix, init_probs, sequences, labels, and category

when return_params = TRUE.

Arguments

n_states

An integer >= 2 giving the number of states. If NULL (the default), a value is drawn from 7:11 on each call.

states

An optional character vector of state labels of length at least n_states. The first n_states are used. If NULL (the default), labels are taken from category or auto-picked from a built-in pool that fits n_states.

category

An optional character string naming a built-in label pool. Available pools are returned by list_random_state_pools(). When NULL (the default), a pool whose size is at least n_states is sampled at random. Ignored when states is supplied.

alpha

A positive numeric Dirichlet concentration parameter. Small values (e.g. 0.3) produce sparse, peaked transitions; large values (e.g. 5) produce near-uniform transitions. If NULL (the default), a value is drawn from Uniform(0.5, 1.0) on each call.

diag_boost

A non-negative numeric added to the diagonal of the transition matrix before re-normalising rows. Larger values make states "stickier" (more self-transitions). If NULL (the default), a value is drawn from Uniform(1.5, 3.0) on each call.

trans_matrix

An optional square numeric matrix of transition probabilities. When supplied, alpha and diag_boost are ignored for the transition matrix. Rows are renormalised to sum to one.

init_probs

An optional numeric vector of initial state probabilities. Renormalised to sum to one. If NULL, drawn from a Dirichlet on the same alphabet.

n_sequences

An integer giving the number of sequences to simulate from the true parameters. If NULL (the default), a value is drawn from 500:800 on each call.

seq_length

An integer giving the length of each simulated sequence. If NULL (the default), a value is drawn from 6:20 on each call.

type

A character string giving the model type. One of "relative" (the default), "frequency", "co-occurrence", "attention".

return_params

A logical. If TRUE, returns a list with the fitted model and the ground-truth parameters used to generate it. Default is FALSE.

seed

An integer random seed for reproducibility, or NULL (the default) for fresh randomness on every call.

See Also

Other data: import_data(), import_onehot(), list_random_state_pools(), prepare_data(), print.tna_data(), random_group_tna(), random_tna_mmm(), simulate.group_tna(), simulate.tna()

Examples

# Fresh random model on every call
model <- random_tna()

# Explicit small-state demo using the engagement pool
model <- random_tna(n_states = 3, category = "engagement")

# Reproducible model
model <- random_tna(seed = 42)

# Recover the ground-truth parameters
out <- random_tna(seed = 7, return_params = TRUE)
out$trans_matrix