% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/popdyn.R
\name{elasticity3.lefkoMatList}
\alias{elasticity3.lefkoMatList}
\title{Estimate Elasticity of Population Growth Rate of a lefkoMatList Object}
\usage{
\method{elasticity3}{lefkoMatList}(
  mats,
  stochastic = FALSE,
  times = 10000,
  tweights = NA,
  seed = NA,
  sparse = "auto",
  append_mats = FALSE,
  ...
)
}
\arguments{
\item{mats}{An object of class \code{lefkoMatList}.}

\item{stochastic}{A logical value determining whether to conduct a
deterministic (FALSE) or stochastic (TRUE) elasticity analysis. Defaults to
FALSE.}

\item{times}{The number of occasions to project forward in stochastic
simulation. Defaults to 10,000.}

\item{tweights}{An optional numeric vector or matrix denoting the
probabilities of choosing each matrix in a stochastic projection. If a matrix
is input, then a first-order Markovian environment is assumed, in which the
probability of choosing a specific annual matrix depends on which annual
matrix is currently chosen. If a vector is input, then the choice of annual
matrix is assumed to be independent of the current matrix. Defaults to equal
weighting among matrices.}

\item{seed}{A number to use as a random number seed in stochastic projection.}

\item{sparse}{A text string indicating whether to use sparse matrix encoding
(\code{"yes"}) or dense matrix encoding (\code{"no"}). Defaults to
\code{"auto"}, in which case sparse matrix encoding is used with square
matrices with at least 50 rows and no more than 50\% of elements with values
greater than zero.}

\item{append_mats}{A logical value indicating whether to include the original
A, U, and F matrices in the output \code{lefkoElas} object.}

\item{...}{Other parameters.}
}
\value{
This function returns a list with two elements. The first is an
object of class \code{lefkoElas} that contains the mean elasticity matrices
of the bootstrapped sensitivity matrices. The second is a list containing
\code{lefkoElas} objects giving the elasticity matrices of all bootstrapped
matrices.

Within these lists are objects of class \code{lefkoElas}, which are comprised
of lists of 8 elements. The first, \code{h_elasmats}, is a list of historical
elasticity matrices (\code{NULL} if an ahMPM is used as input). The second,
\code{ah_elasmats}, is a list of either ahistorical elasticity matrices if an
ahMPM is used as input, or, if an hMPM is used as input, then the result is a
list of elasticity matrices in which historical elasticities have been summed
by the stage in occasions \emph{t} and \emph{t}+1 to produce
historically-corrected elasticity matrices, which are equivalent in dimension
to ahistorical elasticity matrices but reflect the effects of stage in
occasion \emph{t}-1. The third element, \code{hstages}, is a data frame
showing historical stage pairs (NULL if ahMPM used as input). The fourth
element, \code{agestages}, shows age-stage combinations in the order used in
age-by-stage MPMs, if suppled. The fifth element, \code{ahstages}, is a data
frame showing the order of ahistorical stages. The last 3 elements are the A,
U, and F portions of the input.
}
\description{
\code{elasticity3.lefkoMatList()} returns the elasticities of population growth
growth rate to elements of all \code{A} matrices in all bootstrapped
\code{lefkoMat} objects within an entered object of class
\code{lefkoMatList}. If deterministic, then \eqn{\lambda} is taken as the
population growth rate. If stochastic, then stochastic \eqn{\lambda}, or
the stochastic growth rate, is taken as the population growth rate. This
function can handle large and sparse matrices, and so can be used with large
historical matrices, IPMs, age x stage matrices, as well as smaller
ahistorical matrices.
}
\section{Notes}{

Deterministic elasticities are estimated as eqn. 9.72 in Caswell (2001,
Matrix Population Models). Stochastic elasticities are estimated as eqn.
14.99 in Caswell (2001). Note that stochastic elasticities are of the
stochastic \eqn{\lambda}, while stochastic sensitivities are with regard to
the log of the stochastic \eqn{\lambda}.

Speed can sometimes be increased by shifting from automatic sparse matrix
determination to forced dense or sparse matrix projection. This will most
likely occur when matrices have between 30 and 300 rows and columns.
Defaults work best when matrices are very small and dense, or very large and
sparse.

The \code{time_weights}, \code{steps}, and \code{force_sparse} arguments are
now deprecated. Instead, please use the \code{tweights}, \code{times}, and
\code{sparse} arguments.
}

\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)

lathvert_boot <- bootstrap3(lathvert, reps = 3)

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_boot <- rlefko3(data = lathvert_boot, stageframe = lathframe,
  year = "all", stages = c("stage3", "stage2", "stage1"),
  supplement = lathsupp3, yearcol = "year2", indivcol = "individ")

elasticity3(ehrlen3_boot, stochastic = TRUE)

# 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)

cypraw_v1_boot <- bootstrap3(cypraw_v1, reps = 3)

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_boot <- rlefko2(data = cypraw_v1_boot, stageframe = cypframe_raw, 
  year = "all", patch = "all", stages = c("stage3", "stage2", "stage1"),
  size = c("size3added", "size2added"), supplement = cypsupp2r,
  yearcol = "year2", patchcol = "patchid", indivcol = "individ")

elasticity3(cypmatrix2r_boot)

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

\code{\link{elasticity3.lefkoMat}()}

\code{\link{elasticity3.dgCMatrix}()}

\code{\link{elasticity3.matrix}()}

\code{\link{elasticity3.list}()}

\code{\link{summary.lefkoElas}()}
}
