% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/transition_entropy.R
\name{transition_entropy}
\alias{transition_entropy}
\title{Transition Entropy of a Markov Chain}
\usage{
transition_entropy(x, base = 2, normalize = TRUE)
}
\arguments{
\item{x}{A \code{netobject}, \code{cograph_network}, \code{tna} object,
row-stochastic numeric transition matrix, or a wide sequence data.frame
(rows = actors, columns = time-steps; a relative transition network is
built automatically). Group dispatch on \code{netobject_group}.}

\item{base}{Numeric. Logarithm base. \code{2} (default) for bits,
\code{exp(1)} for nats, \code{10} for hartleys.}

\item{normalize}{Logical. If \code{TRUE} (default), rows that do not sum
to 1 are normalised automatically (with a warning).}
}
\value{
An object of class \code{"net_transition_entropy"} with:
\describe{
\item{row_entropy}{Named numeric vector, length \eqn{n}. Per-state
branching entropy \eqn{H(P_{i\cdot}) = -\sum_j P_{ij} \log P_{ij}}.}
\item{row_entropy_norm}{Named numeric vector. \code{row_entropy}
divided by the ceiling \eqn{\log_b n} (in \eqn{[0, 1]}; all zeros
when \eqn{n = 1}).}
\item{stationary}{Named numeric vector. Stationary distribution
\eqn{\pi}.}
\item{stationary_entropy}{Scalar. \eqn{H(\pi) = -\sum_i \pi_i \log \pi_i}
- the entropy of \eqn{\pi} treated as an i.i.d. distribution. Upper
bound on the entropy rate.}
\item{stationary_entropy_norm}{Scalar. \code{stationary_entropy}
divided by the ceiling \eqn{\log_b n}.}
\item{entropy_rate}{Scalar. \eqn{h(P) = \sum_i \pi_i H(P_{i\cdot})} -
the Shannon-McMillan-Breiman entropy rate.}
\item{entropy_rate_norm}{Scalar. \code{entropy_rate} divided by the
ceiling \eqn{\log_b n}.}
\item{redundancy}{Scalar. \eqn{H(\pi) - h(P)}, the entropy deficit
attributable to serial dependence; zero for an i.i.d. chain (rows of
\eqn{P} all equal \eqn{\pi}).}
\item{redundancy_norm}{Scalar. The \emph{relative} redundancy
\eqn{(H(\pi) - h(P)) / H(\pi)} (the fraction of the stationary
entropy removed by order-1 memory), \strong{not}
\code{redundancy} divided by \eqn{\log_b n}; \code{0} when
\eqn{H(\pi) = 0}.}
\item{max_entropy}{Scalar. The normalising ceiling \eqn{\log_b n}.}
\item{base}{Logarithm base used.}
\item{states}{Character vector of state names.}
}
}
\description{
Computes per-state branching entropy, stationary entropy, and the
chain-level entropy rate of a Markov transition process. The entropy rate
is the Shannon-McMillan-Breiman per-step uncertainty of trajectories under
the stationary distribution; it is the canonical information-theoretic
summary of a transition matrix.
}
\details{
Convention \eqn{0 \log 0 := 0} is applied, so absorbing or
deterministic rows contribute zero per-row entropy. The chain need not be
irreducible; \eqn{\pi} is computed from the eigendecomposition of
\eqn{P^\top} as elsewhere in the package. For non-ergodic chains the
returned \eqn{\pi} is one stationary distribution among many - interpret
with the help of \code{\link{chain_structure}}.

The relation \eqn{h(P) \leq H(\pi)} holds with equality iff successive
states are independent. The deficit \eqn{H(\pi) - h(P)} is reported as
\code{redundancy} - a measure of how much memory the chain has at order 1.
}
\examples{
\donttest{
net <- build_network(as.data.frame(trajectories), method = "relative")
te  <- transition_entropy(net)
print(te)
summary(te)
plot(te)
}

}
\references{
Cover, T.M. & Thomas, J.A. (2006). \emph{Elements of Information Theory},
2nd ed., chapter 4. Wiley.

Shannon, C.E. (1948). A mathematical theory of communication.
\emph{Bell System Technical Journal}, 27, 379-423.
}
\seealso{
\code{\link{markov_stability}}, \code{\link{passage_time}},
\code{\link{markov_order_test}}, \code{\link{chain_structure}}
}
