% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/markov.R
\name{passage_time}
\alias{passage_time}
\alias{summary.net_mpt}
\alias{plot.net_mpt}
\title{Mean First Passage Times}
\usage{
passage_time(x, states = NULL, normalize = TRUE)

\method{summary}{net_mpt}(object, ...)

\method{plot}{net_mpt}(
  x,
  log_scale = TRUE,
  digits = 1,
  title = "Mean First Passage Times",
  low = "#004d00",
  high = "#ccffcc",
  ...
)
}
\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).}

\item{states}{Character vector. Restrict output to these states.
\code{NULL} (default) keeps all states.}

\item{normalize}{Logical. If \code{TRUE} (default), rows that do not sum
to 1 are normalized automatically (with a warning).}

\item{object}{A \code{net_mpt} object (for \code{summary}).}

\item{...}{Ignored.}

\item{log_scale}{Logical. Apply log transform to the fill scale for better
contrast? Default \code{TRUE}.}

\item{digits}{Integer. Decimal places displayed in cells. Default \code{1}.}

\item{title}{Character. Plot title.}

\item{low}{Character. Hex colour for the low end (short passage time).
Default dark green \code{"#004d00"}.}

\item{high}{Character. Hex colour for the high end (long passage time).
Default pale green \code{"#ccffcc"}.}
}
\value{
An object of class \code{"net_mpt"} with:
\describe{
\item{matrix}{Full \eqn{n \times n} MFPT matrix. Row \eqn{i}, column
\eqn{j} = expected steps from state \eqn{i} to state \eqn{j}.
Diagonal = mean recurrence time \eqn{1/\pi_i}.}
\item{stationary}{Named numeric vector: stationary distribution \eqn{\pi}.}
\item{return_times}{Named numeric vector: \eqn{1/\pi_i} per state.}
\item{states}{Character vector of state names.}
}

\code{summary.net_mpt} returns a data frame with one row per state
and columns \code{state}, \code{return_time}, \code{stationary},
\code{mean_out} (mean steps to other states), \code{mean_in} (mean steps
from other states).
}
\description{
Computes the full matrix of mean first passage times (MFPT) for a Markov
chain. Element \eqn{M_{ij}} is the expected number of steps to travel from
state \eqn{i} to state \eqn{j} for the first time. The diagonal equals
the mean recurrence time \eqn{1/\pi_i}.
}
\details{
Uses the Kemeny-Snell fundamental matrix formula:
\deqn{M_{ij} = \frac{Z_{jj} - Z_{ij}}{\pi_j}, \quad
      Z = (I - P + \Pi)^{-1}}
where \eqn{\Pi_{ij} = \pi_j}. Requires an ergodic (irreducible,
aperiodic) chain.
}
\examples{
net <- build_network(as.data.frame(trajectories), method = "relative")
pt  <- passage_time(net)
print(pt)
\donttest{
plot(pt)
}

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