% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/chain_structure.R
\name{chain_structure}
\alias{chain_structure}
\title{Qualitative structure of a discrete-time Markov chain}
\usage{
chain_structure(x, normalize = TRUE, tol = 1e-10)
}
\arguments{
\item{x}{A \code{netobject}, \code{cograph_network}, \code{tna} model, transition
matrix, or sequence data.frame (passed through \code{build_network()} with
\code{method = "relative"}).}

\item{normalize}{Logical. If \code{TRUE} (default), rows of the transition
matrix are renormalized to sum to 1 before analysis (see
\code{\link[=passage_time]{passage_time()}} for the same convention).}

\item{tol}{Numerical tolerance for the reversibility check (detailed
balance) and for treating near-zero entries as zero when building the
support graph (which drives \code{classification}, \code{communicating_classes},
\code{period}, and \code{hitting_probabilities}). It does \strong{not} govern the
absorbing-state test: a state is absorbing only when \code{P[i, i]} equals
1 to an internal fixed tolerance of \code{.Machine$double.eps^0.5},
independent of \code{tol} (so raising \code{tol} to ignore tiny transition
probabilities never reclassifies a near-deterministic state as
absorbing). Default \code{1e-10}.}
}
\value{
A \code{chain_structure} object: a list with elements
\describe{
\item{\code{states}}{Character vector of state names.}
\item{\code{classification}}{Named character vector. One of \code{"absorbing"},
\code{"recurrent"}, \code{"transient"} per state.}
\item{\code{communicating_classes}}{List of state-name vectors. Each
sublist is a strongly connected component of the support graph.}
\item{\code{recurrent_classes}}{Subset of \code{communicating_classes} that are
closed (no transitions leaving the class).}
\item{\code{transient_classes}}{Subset that are not closed.}
\item{\code{absorbing_states}}{Character vector of states with \code{P[i, i] = 1}
(tested exactly, to within \code{.Machine$double.eps^0.5}; the
user-facing \code{tol} does not relax this).}
\item{\code{period}}{Named integer vector. Period of each recurrent state;
\code{NA} for transient states.}
\item{\code{is_irreducible}}{Logical. \code{TRUE} iff there is exactly one
communicating class.}
\item{\code{is_aperiodic}}{Logical. \code{TRUE} iff every recurrent state has
period 1.}
\item{\code{is_regular}}{Logical. \code{is_irreducible && is_aperiodic}.}
\item{\code{is_reversible}}{Logical or \code{NA}. \code{TRUE} iff the chain
satisfies detailed balance against its stationary distribution.
\code{NA} for non-irreducible chains (no unique stationary).}
\item{\code{hitting_probabilities}}{\verb{n x n} matrix. \verb{[i, j] = P(ever reach j starting from i)}, computed over the same \code{tol}-thresholded support
graph that drives \code{classification} so the two are mutually
consistent (a state classified \code{"absorbing"}/closed never shows
hitting probability to states outside its class).}
\item{\code{absorption_probabilities}}{\verb{n_transient x n_absorbing} matrix
or \code{NULL} if no transient -> absorbing pathway exists. \verb{[i, j] = P(eventual absorption in j | start in i)}.}
\item{\code{mean_absorption_time}}{Named numeric vector or \code{NULL}. Expected
number of steps until absorption from each transient state.}
\item{\code{P}}{The (possibly normalized) transition matrix used.}
}
}
\description{
Computes properties that depend only on the transition matrix support,
not on any starting distribution: state classification, communicating
classes, periods, irreducibility / aperiodicity / regularity /
reversibility, hitting probabilities, and absorption analysis when
absorbing states exist.
}
\details{
Built specifically as a diagnostic to run \emph{before} trusting the output
of \code{\link[=passage_time]{passage_time()}} or \code{\link[=markov_stability]{markov_stability()}}. Both implicitly assume a
regular chain (irreducible + aperiodic) so that the stationary
distribution is unique and meaningful. Use \code{is_regular} to check.

The fundamental-matrix absorption math follows Kemeny & Snell (1976);
the hitting-probability linear system follows Norris (1997).
}
\examples{
net <- build_network(as.data.frame(trajectories), method = "relative")
cs  <- chain_structure(net)
print(cs)
\donttest{
summary(cs)
}

}
\references{
Kemeny, J. G. and Snell, J. L. (1976). \emph{Finite Markov Chains}.
Springer-Verlag.

Norris, J. R. (1997). \emph{Markov Chains}. Cambridge University Press.
}
\seealso{
\code{\link[=passage_time]{passage_time()}}, \code{\link[=markov_stability]{markov_stability()}}, \code{\link[=build_network]{build_network()}}
}
