% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cluster-metrics.R
\name{as_tna}
\alias{as_tna}
\alias{as_tna.cluster_summary}
\alias{as_tna.mcml}
\alias{as_tna.default}
\title{Convert cluster_summary to tna Objects}
\usage{
as_tna(x)

\method{as_tna}{cluster_summary}(x)

\method{as_tna}{mcml}(x)

\method{as_tna}{default}(x)
}
\arguments{
\item{x}{A \code{cluster_summary} object created by \code{\link{cluster_summary}}.
The cluster_summary should typically be created with \code{type = "tna"} to
ensure row-normalized transition probabilities. If created with
\code{type = "raw"}, the raw counts will be passed to \code{tna::tna()}
which will normalize them.}
}
\value{
A \code{group_tna} object (S3 class) -- a flat named list of tna
objects. The first element is named \code{"macro"} and represents the
cluster-level transitions. Subsequent elements are named by cluster name
and represent internal transitions within each cluster.
\describe{
\item{macro}{A tna object representing cluster-level transitions.
Contains \code{$weights} (k x k transition matrix), \code{$inits}
(initial distribution), and \code{$labels} (cluster names).
Use this for analyzing how learners/entities move between high-level
groups or phases.}
\item{<cluster_name>}{Per-cluster tna objects, one per cluster. Each tna
object represents internal transitions within that cluster. Contains
\code{$weights} (n_i x n_i matrix), \code{$inits} (initial distribution),
and \code{$labels} (node labels). Clusters with single nodes or zero-row
nodes are excluded (tna requires positive row sums).}
}

A \code{group_tna} object (flat list of tna objects: macro + per-cluster).

A \code{group_tna} object (flat list of tna objects: macro + per-cluster).

A \code{tna} object constructed from the input.
}
\description{
Converts a \code{cluster_summary} object to proper tna objects that can be
used with all functions from the tna package. Creates a macro (cluster-level)
tna model and per-cluster tna models (internal transitions within each
cluster), returned as a flat \code{group_tna} object.
}
\details{
This is the final step in the MCML workflow, enabling full integration with
the tna package for centrality analysis, bootstrap validation, permutation
tests, and visualization.
\subsection{Requirements}{

The tna package must be installed. If not available, the function throws
an error with installation instructions.
}

\subsection{Workflow}{

\preformatted{
# Full MCML workflow
net <- cograph(edges, nodes = nodes)
net$nodes$clusters <- group_assignments
cs <- cluster_summary(net, type = "tna")
tna_models <- as_tna(cs)

# Now use tna package functions
plot(tna_models$macro)
tna::centralities(tna_models$macro)
tna::bootstrap(tna_models$macro, iter = 1000)

# Analyze per-cluster patterns
plot(tna_models$ClusterA)
tna::centralities(tna_models$ClusterA)
}
}

\subsection{Excluded Clusters}{

A per-cluster tna cannot be created when:
\itemize{
\item The cluster has only 1 node (no internal transitions possible)
\item Some nodes in the cluster have no outgoing edges (row sums to 0)
}

These clusters are silently excluded. The macro (cluster-level)
model still includes all clusters.
}
}
\examples{
# -----------------------------------------------------
# Basic usage
# -----------------------------------------------------
mat <- matrix(runif(36), 6, 6)
diag(mat) <- 0
rownames(mat) <- colnames(mat) <- LETTERS[1:6]

clusters <- list(
  G1 = c("A", "B"),
  G2 = c("C", "D"),
  G3 = c("E", "F")
)

cs <- cluster_summary(mat, clusters, type = "tna")
tna_models <- as_tna(cs)

# Print summary
tna_models

# -----------------------------------------------------
# Access components
# -----------------------------------------------------
# Macro (cluster-level) tna
tna_models$macro
tna_models$macro$weights  # 3x3 transition matrix
tna_models$macro$inits    # Initial distribution
tna_models$macro$labels   # c("G1", "G2", "G3")

# Per-cluster tnas
names(tna_models)          # "macro", "G1", "G2", "G3"
tna_models$G1              # tna for cluster G1
tna_models$G1$weights      # 2x2 matrix (A, B)

# -----------------------------------------------------
# Use with tna package (requires tna)
# -----------------------------------------------------
if (requireNamespace("tna", quietly = TRUE)) {
  # Plot
  plot(tna_models$macro)
  plot(tna_models$G1)

  # Centrality analysis
  tna::centralities(tna_models$macro)
  tna::centralities(tna_models$G1)
  tna::centralities(tna_models$G2)
}

\dontrun{
# Bootstrap requires a tna object built from raw sequence data (has $data)
# as_tna() returns weight-matrix-based tnas which don't satisfy that requirement
if (requireNamespace("tna", quietly = TRUE)) {
  boot <- tna::bootstrap(tna_models$macro, iter = 1000)
  summary(boot)
}
}

# -----------------------------------------------------
# Check which within-cluster models were created
# -----------------------------------------------------
cs <- cluster_summary(mat, clusters, type = "tna")
tna_models <- as_tna(cs)

# All cluster names
names(cs$cluster_members)

# Clusters with valid per-cluster models
setdiff(names(tna_models), "macro")

# Clusters excluded (single node or zero rows)
setdiff(names(cs$cluster_members), names(tna_models))
}
\seealso{
\code{\link{cluster_summary}} to create the input object,
\code{\link{plot_mcml}} for visualization without conversion,
\code{tna::tna} for the underlying tna constructor
}
