% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/random.R
\name{random_group_tna}
\alias{random_group_tna}
\title{Build a Random Group Transition Network Analysis Model}
\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
)
}
\arguments{
\item{n_groups}{An \code{integer} giving the number of groups. If \code{NULL}
(the default), a value is drawn from \code{2:4} on each call.}

\item{group_names}{An optional \code{character} vector of group names of
length \code{n_groups}. Defaults to \code{"Group 1"}, \code{"Group 2"}, ...}

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

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

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

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

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

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

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

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

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

\item{seed}{An \code{integer} random seed for reproducibility, or \code{NULL}
(the default) for fresh randomness on every call.}
}
\value{
A \code{group_tna} object.
}
\description{
Construct a fully-functional \code{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.
}
\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
)

}
\seealso{
Other data: 
\code{\link{import_data}()},
\code{\link{import_onehot}()},
\code{\link{list_random_state_pools}()},
\code{\link{prepare_data}()},
\code{\link{print.tna_data}()},
\code{\link{random_tna}()},
\code{\link{random_tna_mmm}()},
\code{\link{simulate.group_tna}()},
\code{\link{simulate.tna}()}
}
\concept{data}
