% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/markov.R
\name{markov_stability}
\alias{markov_stability}
\alias{plot.net_markov_stability}
\title{Markov Stability Analysis}
\usage{
markov_stability(x, normalize = TRUE)

\method{plot}{net_markov_stability}(
  x,
  metrics = c("persistence", "stationary_prob", "return_time", "sojourn_time",
    "avg_time_to_others", "avg_time_from_others"),
  combined = 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).}

\item{normalize}{Logical. Normalize rows to sum to 1? Default \code{TRUE}.}

\item{metrics}{Character vector. Which metrics to plot. Options:
\code{"persistence"}, \code{"stationary_prob"}, \code{"return_time"},
\code{"sojourn_time"}, \code{"avg_time_to_others"},
\code{"avg_time_from_others"}. Default: all six.}

\item{combined}{When \code{TRUE} (default), all selected metrics are
shown in one ggplot via \code{facet_wrap(~ metric)}. When \code{FALSE},
returns a named list of single-panel ggplots, one per metric, so each
can be printed, saved, or re-laid-out independently.}

\item{...}{Ignored.}
}
\value{
An object of class \code{"net_markov_stability"} with:
\describe{
\item{stability}{Data frame with one row per state and columns:
\code{state}, \code{persistence} (\eqn{P_{ii}}),
\code{stationary_prob} (\eqn{\pi_i}),
\code{return_time} (\eqn{1/\pi_i}),
\code{sojourn_time} (\eqn{1/(1-P_{ii})}),
\code{avg_time_to_others} (mean MFPT leaving state \eqn{i}),
\code{avg_time_from_others} (mean MFPT arriving at state \eqn{i}).}
\item{mpt}{The underlying \code{net_mpt} object.}
}
}
\description{
Computes per-state stability metrics from a transition network:
persistence (self-loop probability), stationary distribution, mean
recurrence time, sojourn time, and mean accessibility to/from other states.
}
\details{
\strong{Sojourn time} is the expected consecutive time steps spent in a
state before leaving: \eqn{1/(1-P_{ii})}. States with
\code{persistence = 1} have \code{sojourn_time = Inf}.

\strong{avg_time_to_others}: mean passage time from this state to all
others; reflects how "sticky" or "isolated" the state is.

\strong{avg_time_from_others}: mean passage time from all other states
to this one; reflects accessibility (attractor strength).
}
\examples{
net <- build_network(as.data.frame(trajectories), method = "relative")
ms  <- markov_stability(net)
print(ms)
\donttest{
plot(ms)
}

}
\seealso{
\code{\link{passage_time}}
}
