% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/scale_mpm_to_lambda1.R
\name{scale_mpm_to_lambda1}
\alias{scale_mpm_to_lambda1}
\title{Scale a matrix population model so that lambda equals 1}
\usage{
scale_mpm_to_lambda1(matU = NULL, matF = NULL, matC = NULL, matA = NULL)
}
\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 retrogression). Required when using component
inputs.}

\item{matF}{The sexual reproduction component of a matrix population model.
Optional if \code{matC} is supplied. If omitted while \code{matC} is
supplied, it is assumed to be a zero matrix.}

\item{matC}{The clonal reproduction component of a matrix population model.
Optional if \code{matF} is supplied. If omitted while \code{matF} is
supplied, it is assumed to be a zero matrix.}

\item{matA}{The full projection matrix of a matrix population model.
Optional if component matrices are supplied. If supplied together with
components, it must equal \code{matU + matF + matC}.}
}
\value{
A list with six elements:
\describe{
  \item{matA}{The scaled full projection matrix.}
  \item{matU}{The scaled survival matrix. Returned as \code{NULL} if only
  \code{matA} is supplied.}
  \item{matF}{The scaled sexual reproduction matrix. Returned as \code{NULL}
  if only \code{matA} is supplied.}
  \item{matC}{The scaled clonal reproduction matrix. Returned as \code{NULL}
  if only \code{matA} is supplied.}
  \item{lambda_original}{The dominant eigenvalue of the original projection
  matrix.}
  \item{lambda_scaled}{The dominant eigenvalue of the scaled projection
  matrix.}
}
}
\description{
Scales a matrix population model (MPM) so that the dominant eigenvalue
(\eqn{\lambda}) of the full projection matrix equals 1. The function accepts
either a full projection matrix (\code{matA}) or a set of component matrices
consisting of the survival component (\code{matU}) plus at least one
reproductive component (\code{matF} and/or \code{matC}).
}
\details{
When component matrices are used, \code{matU} must be supplied
together with at least one of \code{matF} or \code{matC}. Missing
reproductive components are treated as zero matrices of the appropriate
dimension.
}
\examples{
data(mpm1)

# scale from the full projection matrix
matA <- mpm1$matU + mpm1$matF
scale_mpm_to_lambda1(matA = matA)

# scale from component matrices, assuming no clonal reproduction
scale_mpm_to_lambda1(matU = mpm1$matU, matF = mpm1$matF)

}
\seealso{
Other transformation: 
\code{\link{is_leslie_matrix}()},
\code{\link{leslie_collapse}()},
\code{\link{mpm_collapse}()},
\code{\link{mpm_rearrange}()},
\code{\link{mpm_split}()},
\code{\link{mpm_standardize}()},
\code{\link{name_stages}()},
\code{\link{repro_stages}()},
\code{\link{standard_stages}()}
}
\author{
Owen R. Jones <jones@biology.sdu.dk>
}
\concept{transformation}
