tna (version 1.3.1)

random_group_tna: Build a Random Group Transition Network Analysis Model

Description

Construct a fully-functional group_tna object from synthetic parameters. Each group receives its own randomly drawn transition matrix and initial probabilities over a shared alphabet, so groups have heterogeneous dynamics by default. Per-group overrides allow custom group sizes, sparsity, stickiness, or hand-supplied transition matrices.

Usage

random_group_tna(
  n_groups = NULL,
  group_names = NULL,
  n_states = NULL,
  states = NULL,
  category = NULL,
  alpha = NULL,
  diag_boost = NULL,
  n_sequences = NULL,
  seq_length = NULL,
  type = "relative",
  per_group = NULL,
  seed = NULL
)

Value

A group_tna object.

Arguments

n_groups

An integer giving the number of groups. If NULL (the default), a value is drawn from 2:4 on each call.

group_names

An optional character vector of group names of length n_groups. Defaults to "Group 1", "Group 2", ...

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.

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

per_group

An optional list of length n_groups. Each element is itself a list of overrides applied to that group only. Recognised override names: alpha, diag_boost, trans_matrix, init_probs, n_sequences, seq_length. Unset entries fall back to the top-level defaults (which may themselves be drawn at random when NULL).

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_tna(), random_tna_mmm(), simulate.group_tna(), simulate.tna()

Examples

# Fresh random group model on every call
model <- random_group_tna()

# Explicit two-group engagement demo with per-group differences
model <- random_group_tna(
  n_groups  = 2,
  n_states  = 3,
  category  = "engagement",
  per_group = list(
    list(n_sequences = 400, diag_boost = 3),
    list(n_sequences = 100, alpha = 0.3)
  ),
  seed = 42
)