% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/stage_at_death_dist.R
\name{stage_at_death_dist}
\alias{stage_at_death_dist}
\title{Compute distribution of stage at death from a stage-structured MPM}
\usage{
stage_at_death_dist(matU, start = NULL)
}
\arguments{
\item{matU}{A square numeric matrix giving the survival/transition (\eqn{U})
submatrix of a stage-based (Lefkovitch) matrix population model.}

\item{start}{Optional numeric vector of length \eqn{n} giving the initial
cohort distribution across stages. It will be rescaled to sum to 1.
Defaults to a uniform distribution if \code{NULL}.}
}
\value{
A numeric vector giving the expected contribution of each stage to
  deaths. Names are taken from \code{rownames(U)} when available.
}
\description{
Calculates the expected distribution of deaths across stages for a cohort
governed by the survival/transition submatrix \code{U} of a matrix population
model. The result can be interpreted as the probability of dying in each
stage.
}
\section{Note}{

This function uses the fundamental matrix of the Markov chain implied by
\code{U} to estimate the total expected time spent in each stage, then
combines this with per-stage death probabilities. The output describes where
in the life cycle deaths occur, given a specified starting stage
distribution.
}

\section{Warning}{

Results may be misleading if \code{U} includes reproduction or if any column
sums exceed 1. Use only the survival/transition submatrix. The calculation
also assumes that all stages are transient (i.e. eventual death is certain).
}

\examples{
data(mpm1)

# Uniform starting cohort (default)
stage_at_death_dist(mpm1$matU)

# Starting entirely in stage 1
stage_at_death_dist(mpm1$matU, start = c(1, 0, 0, 0, 0))

# Starting with the SSD (requires the full A matrix)
matA <- mpm1$matU + mpm1$matF
ssd <- popdemo::eigs(matA, "ss")
stage_at_death_dist(mpm1$matU, start = ssd)

}
\seealso{
Other life history traits: 
\code{\link{entropy_d}()},
\code{\link{entropy_k}()},
\code{\link{entropy_k_age}()},
\code{\link{entropy_k_stage}()},
\code{\link{gen_time}()},
\code{\link{life_elas}()},
\code{\link{life_expect_mean}()},
\code{\link{longevity}()},
\code{\link{net_repro_rate}()},
\code{\link{repro_maturity}},
\code{\link{shape_rep}()},
\code{\link{shape_surv}()}
}
\author{
Owen Jones <jones@biology.sdu.dk>
}
\concept{life history traits}
