% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/random.R
\name{random_tna}
\alias{random_tna}
\title{Build a Random Transition Network Analysis Model}
\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
)
}
\arguments{
\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{trans_matrix}{An optional square \code{numeric} matrix of transition
probabilities. When supplied, \code{alpha} and \code{diag_boost} are ignored
for the transition matrix. Rows are renormalised to sum to one.}

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

\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{return_params}{A \code{logical}. If \code{TRUE}, returns a \code{list} with the
fitted model and the ground-truth parameters used to generate it.
Default is \code{FALSE}.}

\item{seed}{An \code{integer} random seed for reproducibility, or \code{NULL}
(the default) for fresh randomness on every call.}
}
\value{
A \code{tna} object, or a \code{list} with elements \code{model},
\code{trans_matrix}, \code{init_probs}, \code{sequences}, \code{labels}, and \code{category}
when \code{return_params = TRUE}.
}
\description{
Construct a fully-functional \code{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 \code{tna} object is fitted on those sequences.

Calling \code{random_tna()} with no arguments returns a fresh, sticky network
with a coherent alphabet, drawn fresh on every call.
}
\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

}
\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_group_tna}()},
\code{\link{random_tna_mmm}()},
\code{\link{simulate.group_tna}()},
\code{\link{simulate.tna}()}
}
\concept{data}
