% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/RcppExports.R
\name{lambda3}
\alias{lambda3}
\title{Estimate Actual or Deterministic Population Growth Rate}
\usage{
lambda3(mpm, style = NULL, force_sparse = NULL)
}
\arguments{
\item{mpm}{A \code{lefkoMat} object, a \code{lefkoMatList} object, a list of
projection matrices, a \code{lefkoProj} object, or a single projection
matrix in either standard or sparse format.}

\item{style}{If \code{mpm} is either a \code{lefkoMat} or
\code{lefkoMatList} object, then style determines whether the dominant
eigenvalues will be calculated for the \code{A} matrices (the default),
the \code{U} matrices (if \code{style = "U"}), or the \code{F} matrices (if
\code{style = "F"}).}

\item{force_sparse}{A logical value or string detailing whether to force
sparse matrix encoding for simple matrix input. Defaults to \code{"auto"},
which only forces sparse matrix coding if simple matrices are input that are
both sparse (i.e, percentage of matrix elements that are non-zero <= 50%)
and have more than 20 rows. Can also be set to \code{"yes"}, \code{"no"},
\code{TRUE}, or \code{FALSE}. Note that sparse matrix coding is always used
for \code{lefkoMat} objects with matrices in sparse format (class
\code{dgCMatrix}). Ignored with \code{lefkoProj} objects.}
}
\value{
The value returned depends on the class of the \code{mpm} argument.
If a \code{lefkoMat} object is provided, then this function will return the
\code{labels} data frame with a new column named \code{lambda} showing the
dominant eigenvalues for each matrix. If a \code{lefkoMatList} object is
provided, then a two element list in which the first element is a vector
composed of the mean lambda values of each \code{lefkoMat} element within
the list is provided, and the second element is a list of \code{lefkoMat}
lambda summaries as previously described. If a list of matrices is provided,
then this function will produce a numeric vector with the dominant
eigenvalues provided in order of matrix. If a single matrix is provided,
then this function will return the dominant eigenvalue of that matrix. Only
the largest real parts of the eigenvalues are returned.

If a \code{lefkoProj} object is provided, then the output consists of a list
with three elements. The second and third elements are lists of matrices
with each lower-level list elements corresponding to \code{labels} rows,
and matrices within these lists showing the actual \eqn{\lambda} and
\code{log} \eqn{\lambda} for each consecutive year or time index (columns)
within each replicate (row).
}
\description{
Function \code{lambda3()} is a generic function that returns the dominant
eigenvalue of a matrix, set of dominant eigenvalues of a set of matrices,
set of dominant eigenvalues for a \code{lefkoMat} object, or actual
\eqn{\lambda} in each year in a \code{lefkoProj} object. It can handle
large and sparse matrices supplied as \code{lefkoMat} objects or as
individual matrices, and can be used with large historical matrices, IPMs, 
age x stage matrices, as well as smaller ahistorical matrices, and general
projetions.
}
\examples{
# Lathyrus example
data(lathyrus)

sizevector <- c(0, 100, 13, 127, 3730, 3800, 0)
stagevector <- c("Sd", "Sdl", "VSm", "Sm", "VLa", "Flo", "Dorm")
repvector <- c(0, 0, 0, 0, 0, 1, 0)
obsvector <- c(0, 1, 1, 1, 1, 1, 0)
matvector <- c(0, 0, 1, 1, 1, 1, 1)
immvector <- c(1, 1, 0, 0, 0, 0, 0)
propvector <- c(1, 0, 0, 0, 0, 0, 0)
indataset <- c(0, 1, 1, 1, 1, 1, 1)
binvec <- c(0, 100, 11, 103, 3500, 3800, 0.5)

lathframe <- sf_create(sizes = sizevector, stagenames = stagevector,
  repstatus = repvector, obsstatus = obsvector, matstatus = matvector,
  immstatus = immvector, indataset = indataset, binhalfwidth = binvec,
  propstatus = propvector)

lathvert <- verticalize3(lathyrus, noyears = 4, firstyear = 1988,
  patchidcol = "SUBPLOT", individcol = "GENET", blocksize = 9,
  juvcol = "Seedling1988", sizeacol = "Volume88", repstracol = "FCODE88",
  fecacol = "Intactseed88", deadacol = "Dead1988",
  nonobsacol = "Dormant1988", stageassign = lathframe, stagesize = "sizea",
  censorcol = "Missing1988", censorkeep = NA, censor = TRUE)

lathsupp3 <- supplemental(stage3 = c("Sd", "Sd", "Sdl", "Sdl", "Sd", "Sdl", "mat"),
  stage2 = c("Sd", "Sd", "Sd", "Sd", "rep", "rep", "Sdl"),
  stage1 = c("Sd", "rep", "Sd", "rep", "npr", "npr", "Sd"),
  eststage3 = c(NA, NA, NA, NA, NA, NA, "mat"),
  eststage2 = c(NA, NA, NA, NA, NA, NA, "Sdl"),
  eststage1 = c(NA, NA, NA, NA, NA, NA, "NotAlive"),
  givenrate = c(0.345, 0.345, 0.054, 0.054, NA, NA, NA),
  multiplier = c(NA, NA, NA, NA, 0.345, 0.054, NA),
  type = c(1, 1, 1, 1, 3, 3, 1), type_t12 = c(1, 2, 1, 2, 1, 1, 1),
  stageframe = lathframe, historical = TRUE)

ehrlen3 <- rlefko3(data = lathvert, stageframe = lathframe, year = "all", 
  stages = c("stage3", "stage2", "stage1"), supplement = lathsupp3,
  yearcol = "year2", indivcol = "individ")

ehrlen3mean <- lmean(ehrlen3)
lambda3(ehrlen3mean)

# Cypripedium example
data(cypdata)

sizevector <- c(0, 0, 0, 0, 0, 0, 1, 2.5, 4.5, 8, 17.5)
stagevector <- c("SD", "P1", "P2", "P3", "SL", "D", "XSm", "Sm", "Md", "Lg",
  "XLg")
repvector <- c(0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1)
obsvector <- c(0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1)
matvector <- c(0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1)
immvector <- c(0, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0)
propvector <- c(1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0)
indataset <- c(0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1)
binvec <- c(0, 0, 0, 0, 0, 0.5, 0.5, 1, 1, 2.5, 7)

cypframe_raw <- sf_create(sizes = sizevector, stagenames = stagevector,
  repstatus = repvector, obsstatus = obsvector, matstatus = matvector,
  propstatus = propvector, immstatus = immvector, indataset = indataset,
  binhalfwidth = binvec)

cypraw_v1 <- verticalize3(data = cypdata, noyears = 6, firstyear = 2004,
  patchidcol = "patch", individcol = "plantid", blocksize = 4,
  sizeacol = "Inf2.04", sizebcol = "Inf.04", sizeccol = "Veg.04",
  repstracol = "Inf.04", repstrbcol = "Inf2.04", fecacol = "Pod.04",
  stageassign = cypframe_raw, stagesize = "sizeadded", NAas0 = TRUE,
  NRasRep = TRUE)

# Here we use supplemental() to provide overwrite and reproductive info
cypsupp2r <- supplemental(stage3 = c("SD", "P1", "P2", "P3", "SL", "D", 
    "XSm", "Sm", "SD", "P1"),
  stage2 = c("SD", "SD", "P1", "P2", "P3", "SL", "SL", "SL", "rep",
    "rep"),
  eststage3 = c(NA, NA, NA, NA, NA, "D", "XSm", "Sm", NA, NA),
  eststage2 = c(NA, NA, NA, NA, NA, "XSm", "XSm", "XSm", NA, NA),
  givenrate = c(0.10, 0.20, 0.20, 0.20, 0.25, NA, NA, NA, NA, NA),
  multiplier = c(NA, NA, NA, NA, NA, NA, NA, NA, 0.5, 0.5),
  type =c(1, 1, 1, 1, 1, 1, 1, 1, 3, 3),
  stageframe = cypframe_raw, historical = FALSE)

cypmatrix2r <- rlefko2(data = cypraw_v1, stageframe = cypframe_raw, 
  year = "all", patch = "all", stages = c("stage3", "stage2", "stage1"),
  size = c("size3added", "size2added"), supplement = cypsupp2r,
  yearcol = "year2", patchcol = "patchid", indivcol = "individ")

lambda3(cypmatrix2r)

}
\seealso{
\code{\link{slambda3}()}
}
