% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/mpm_to_table.R
\name{mpm_to_table}
\alias{mpm_to_table}
\title{Generate a life table from a matrix population model}
\usage{
mpm_to_table(
  matU,
  matR = NULL,
  matF = NULL,
  matC = NULL,
  start = 1L,
  xmax = 1000,
  lx_crit = 0.01,
  radix = 1,
  remove_final = FALSE
)
}
\arguments{
\item{matU}{The survival component of a matrix population model (i.e., a
square projection matrix reflecting survival-related transitions; e.g.,
progression, stasis, and/or retrogression). Optionally with named rows and
columns indicating the corresponding life stage names.}

\item{matR}{The reproductive component of a matrix population model (i.e., a
square projection matrix only reflecting transitions due to reproduction;
either sexual, clonal, or both). If \code{matR} is supplied, \code{matF}
and \code{matC} are ignored. Otherwise, \code{matR} is constructed by
summing \code{matF} and \code{matC}.}

\item{matF}{The matrix reflecting sexual reproduction. If provided
without \code{matC}, \code{matC} is assumed to be a zero matrix. If
\code{matR} is provided, this argument is ignored.}

\item{matC}{The matrix reflecting clonal (asexual) reproduction.
If provided without \code{matF}, \code{matF} is assumed to be a zero
matrix. If \code{matR} is provided, this argument is ignored.}

\item{start}{The index (or stage name) of the first stage at which the author
considers the beginning of life. Defaults to \code{1}. Alternately, a
numeric vector giving the starting population vector (in which case
\code{length(start)} must match \code{ncol(matU))}. See section
\emph{Starting from multiple stages}.}

\item{xmax}{Maximum age to which the life table will be calculated (defaults
to \code{1000}). Time steps are in the same units as the matrix population
model (see MatrixPeriodicity metadata variable COM(P)ADRE).}

\item{lx_crit}{Minimum value of lx to which age-specific traits will be
calculated (defaults to \code{0.01}).}

\item{radix}{The starting number of individuals in the synthetic life table
(defaults to \code{1}). If \code{radix} is set to 1, a simplified life
table is produced.}

\item{remove_final}{Life table calculations typically assume that the final
age class is closed and that all individuals die in that age class. This
can mean that mortality/hazard is artificially inflated for this age class.
Users can prevent this by setting `remove_final` to `TRUE` (the default is
`FALSE`).}
}
\value{
A \code{data.frame} containing a variable number columns, depending
  on input variables. Columns include:

  \item{x}{age at the start of the age interval \code{[x, x+1)}}
  \item{Nx}{The number of individuals alive at age x. The initial number is
  set with \code{radix}}
  \item{Dx}{proportion of original cohort dying during the age interval
  \code{[x, x+1)}}
  \item{lx}{survivorship, defined as the proportion of initial cohort
  surviving to the start of age interval \code{[x, x+1)}}
  \item{dx}{proportion of original cohort dying in the age interval \code{[x,
  x+1)}}
  \item{ax}{The average time survived within the interval by those that die
  during the age interval \code{[x, x+1)}. Assumed to be 0.5}
  \item{hx}{force of mortality (hazard) during the age interval \code{[x,
  x+1)}}
  \item{qx}{probability of death during the interval \code{[x, x+1)} for
  those entering the interval}
  \item{px}{probability of survival for the interval \code{[x, x+1)} for
  those entering the interval}
  \item{Lx}{total person-years lived during the interval \code{[x, x+1)}}
  \item{Tx}{total person years lived beyond age x}
  \item{ex}{remaining life expectancy at age x}

If \code{matF} is provided, also includes:
  \item{mx}{per-capita rate of sexual reproduction during the interval
   \code{[x, x+1)} }
  \item{lxmx}{expected number of sexual offspring per original
  cohort member produced during the interval \code{[x, x+1)}}

If \code{matC} is provided, also includes:
  \item{cx}{per-capita rate of clonal reproduction  during the interval
  \code{[x, x+1)}}
  \item{lxcx}{expected number of clonal offspring per original
  cohort member produced during the interval \code{[x, x+1)}}

If only \code{matR} is provided, the calculations proceed as with \code{matF}.

If both \code{matF} and \code{matC} are provided, also includes:
  \item{mxcx}{per-capita rate of total reproduction (sexual + clonal) during
  the interval \code{[x, x+1)}}
  \item{lxmxcx}{expected number of total offspring (sexual + clonal) per
  original cohort member produced during the interval \code{[x, x+1)}}
}
\description{
This function uses age-from-stage decomposition methods to generate a life
table from a matrix population model. A detailed description of these methods
can be found in section 5.3 "Age-specific traits from stage-specific models"
of Caswell (2001).
}
\note{
The life table is calculated recursively until the age class (x)
  reaches \code{xmax} or survivorship (lx) falls below \code{lx_crit} —
  whichever comes first. To force calculation to \code{xmax}, set
  \code{lx_crit = 0}. Conversely, to force calculation to \code{lx_crit}, set
  \code{xmax = Inf}.

The life table calculations assume that the final age interval is
  closed and that all remaining individuals die in this interval. Therefore,
  for this interval, the probability of death \code{qx} is 1, the probability
  of survival \code{px} is 0 and, because we assume that deaths are evenly
  distributed during the interval, the remaining life expectancy for
  individuals at the start of the interval is 0.5. Depending on analyses, it
  may be a good idea to remove the final row of the table.

  If \code{lx_crit} is sufficiently small that only a very small proportion
  of the cohort reach this age (i.e., < 0.05), this should have minimal
  impact on results. Nevertheless, for many analyses, the final row of the
  life table should be treated with caution and perhaps removed from
  subsequent analyses.

If reproduction columns are included, the resulting \code{mx},
  \code{cx}, and related trajectories reflect reproductive output as
  represented at the census boundary. As a result, reproductive trajectories
  from pre-breeding and post-breeding models are not necessarily directly
  comparable. See Kendall et al. (2019).

Note that the units of time (e.g.. `x` and `ex`) in the returned life
  table are the same as the projection interval (`ProjectionInterval`) of the
  MPM.
}
\section{Starting from multiple stages}{
 Rather than specifying argument
  \code{start} as a single stage class from which all individuals start life,
  it may sometimes be desirable to allow for multiple starting stage classes.
  For example, if the user wants to start the calculation of age-specific
  traits from reproductive maturity (i.e., first reproduction), the user
  should account for the possibility that there may be multiple stage classes
  in which an individual could first reproduce.

To specify multiple starting stage classes, specify argument \code{start} as
the desired starting population vector (\strong{n1}), giving the proportion
of individuals starting in each stage class (the length of \code{start}
should match the number of columns in the relevant MPM).

See function \code{\link{mature_distrib}} for calculating the proportion of
individuals achieving reproductive maturity in each stage class.
}

\examples{
data(mpm1)

mpm_to_table(matU = mpm1$matU, start = 2, xmax = 15)

# equivalent using named life stages
mpm_to_table(matU = mpm1$matU, start = "small", xmax = 15)
mpm_to_table(matU = mpm1$matU, matR = mpm1$matF, start = 2, xmax = 15)

### starting from first reproduction
repStages <- repro_stages(mpm1$matF)
n1 <- mature_distrib(matU = mpm1$matU, start = 2, repro_stages = repStages)
mpm_to_table(matU = mpm1$matU, start = n1)
}
\references{
Caswell, H. 2001. Matrix Population Models: Construction, Analysis, and
Interpretation. Sinauer Associates; 2nd edition. ISBN: 978-0878930968

Caswell, H. 2006. Applications of Markov chains in demography. pp. 319-334 in
A.N. Langville and W.J. Stewart (editors) MAM2006: Markov Anniversary
Meeting. Boson Books, Raleigh, North Caroline, USA

Horvitz, C. & Tuljapurkar, S. 2008. Stage dynamics, period survival, and
mortality plateaus. The American Naturalist 172: 203-2015.
<doi:10.1086/589453>

Jones, O. R., Scheuerlein, A., Salguero-Gomez, R., Camarda, C. G., Schaible,
R., Casper, B. B., Dahlgren, J. P., Ehrlén, J., García, M. B., Menges, E.,
Quintana-Ascencio, P. F., Caswell, H., Baudisch, A. & Vaupel, J. 2014.
Diversity of ageing across the tree of life. Nature 505, 169-173.
<doi:10.1038/nature12789>

Jones O. R. 2021. Life tables: Construction and interpretation In:
Demographic Methods Across the Tree of Life. Edited by Salguero-Gomez R &
Gamelon M. Oxford University Press. Oxford, UK. ISBN: 9780198838609

Preston, S., Heuveline, P., & Guillot, M. 2000. Demography: Measuring and
Modeling Population Processes. Wiley. ISBN: 9781557864512
}
\seealso{
Other life tables: 
\code{\link{age_from_stage}},
\code{\link{lifetable_convert}},
\code{\link{qsd_converge}()}
}
\author{
Owen R. Jones <jones@biology.sdu.dk>

Roberto Salguero-Gómez <rob.salguero@zoo.ox.ac.uk>

Hal Caswell <h.caswell@uva.nl>
}
\concept{life tables}
