projection3  R Documentation 
Function projection3()
runs projection simulations. It projects the
population and patches forward in time by a userdefined number of
occasions. A given set of matrices is utilized and not recreated, although
elements may be altered if density dependence is set. Projections may be
deterministic or stochastic, and may be density dependent in either case. If
deterministic, then projections will be cyclical if matrices exist covering
multiple occasions for each population or patch. If stochastic, then annual
matrices will be shuffled within patches and populations. Also produces
replicates if set.
projection3(
mpm,
nreps = 1L,
times = 10000L,
historical = FALSE,
stochastic = FALSE,
standardize = FALSE,
growthonly = TRUE,
integeronly = FALSE,
substoch = 0L,
exp_tol = 700,
sub_warnings = TRUE,
quiet = FALSE,
year = NULL,
start_vec = NULL,
start_frame = NULL,
tweights = NULL,
density = NULL,
sparse = NULL
)
mpm 
A matrix projection model of class 
nreps 
The number of replicate projections. 
times 
Number of occasions to iterate per replicate. Defaults to 10,000. 
historical 
An optional logical value only used if object 
stochastic 
A logical value denoting whether to conduct a stochastic projection or a deterministic / cyclical projection. 
standardize 
A logical value denoting whether to restandardize the
population size to 1.0 at each occasion. Defaults to 
growthonly 
A logical value indicating whether to produce only the
projected population size at each occasion, or a vector showing the stage
distribution followed by the reproductive value vector followed by the full
population size at each occasion. Defaults to 
integeronly 
A logical value indicating whether to round the number of
individuals projected in each stage at each occasion to the nearest
integer. Defaults to 
substoch 
An integer value indicating whether to force survival
transition matrices to be substochastic in density dependent simulations.
Defaults to 
exp_tol 
A numeric value used to indicate a maximum value to set
exponents to in the core kernel to prevent numerical overflow. Defaults to

sub_warnings 
A logical value indicating whether to warn the user if
density dependence yields matrix values outside of the realm of possibility.
Generally, this means that survivaltransition elements altered to values
outside of the interval [0, 1], and negative fecundity values, will both
yield warnings. Defaults to 
quiet 
A logical value indicating whether to suppress warnings.
Defaults to 
year 
Either a single integer value corresponding to the year to
project, or a vector of 
start_vec 
An optional numeric vector denoting the starting stage distribution for the projection. Defaults to a single individual of each stage. 
start_frame 
An optional data frame characterizing stages, agestages,
or stagepairs that should be set to nonzero values in the starting vector,
and what those values should be. Can only be used with 
tweights 
An optional numeric vector denoting the probabilistic weightings of annual matrices. Defaults to equal weighting among occasions. 
density 
An optional data frame describing the matrix elements that
will be subject to density dependence, and the exact kind of density
dependence that they will be subject to. The data frame used should be an
object of class 
sparse 
A text string indicating whether to use sparse matrix encoding
( 
A list of class lefkoProj
, which always includes the first
three elements of the following, and also includes the remaining elements
below when a lefkoMat
object is used as input:
projection 
A list of lists of matrices showing the total number of individuals per stage per occasion. The first list corresponds to each poppatch followed by each population. The inner list corresponds to replicates within each poppatch or population. 
stage_dist 
A list of lists of the actual stage distribution in each
occasion in each replicate in each poppatch or population. The list order
is the same as in 
rep_value 
A list of lists of the actual reproductive value in each
occasion in each replicate in each poppatch or population. The list order
is the same as in 
pop_size 
A list of data frames showing the total population size in each occasion per replicate (row within data frame) per poppatch or population (list element). 
labels 
A data frame showing the order of populations and patches in
item 
ahstages 
The original stageframe used in the study. 
hstages 
A data frame showing the order of historical stage pairs. 
agestages 
A data frame showing the order of agestage pairs. 
control 
A short vector indicating the number of replicates and the number of occasions projected per replicate. 
density 
The data frame input under the density option. Only provided if input by the user. 
Projections are run both at the patch level and at the population level. Population level estimates will be noted at the end of the data frame with 0 entries for patch designation.
Weightings given in tweights
do not need to sum to 1. Final
weightings used will be based on the proportion per element of the sum of
elements in the usersupplied vector.
Starting vectors can be input in one of two ways: 1) as start_vec
input, which is a vector of numbers of the numbers of individuals in each
stage, stage pair, or agestage, with the length of the vector necessarily
as long as there are rows in the matrices of the MPM; or 2) as
start_frame
input, which is a data frame showing only those stages,
stage pairs, or agestages that should begin with more than 0 individuals,
and the numbers of individuals that those stages should start with (this
object is created using the start_input()
function). If both
are provided, then start_frame
takes precedence and start_vec
is ignored. If neither is provided, then projection3()
automatically
assumes that each stage, stage pair, or agestage begins with a single
individual. Importantly, if a lefkoMat
object is not used, and a list
of matrices is provided instead, then start_frame
cannot be utilized
and a full start_vec
must be provided to conduct a simulation with
starting numbers of individuals other than 1 per stage.
The resulting data frames in element projection
are separated by
poppatch according to the order provided in element labels
, but the
matrices for each element of projection
have the result of each
replicate stacked in order on top of one another without any break or
indication. Results for each replicate must be separated using the
information provided in elements control
and the 3 stage
descriptor elements.
Density dependent projections are automatically set up if object
density
is input. If this object is not included, then density
independent projections will be set up. Note that currently, density
dependent projections can only be performed with lefkoMat
objects.
When running density dependent simulations involving userset exponents,
such as the beta term in the Ricker function and both the alpha and beta
terms in the Usher function, values above or below the computer limits may
cause unpredictable behavior. Noted odd behavior includes sudden shifts in
population size to negative values. This function produces warnings when
such values are used, and the values used for warnings may be reset with the
exp_tol
term.
The stage distributions and reproductive values produced are not the asymptotic values as would be given by the standardized right and left eigenvectors associated with the dominant eigenvalue of a matrix, but are vectors describing these values at the specific points in time projected. See equations 14.86 and 14.88 and section 14.4 on Sensitivity and Elasticity Analysis under Environmental Stochasticity in Caswell (2001, Matrix Population Models, Sinauer Associates) for more details.
Consistently positive population growth can quickly lead to population size
numbers larger than can be handled computationally. In that circumstance, a
continuously rising population size will suddenly become NaN
for the
remainder of the projection.
Users wishing to run a projection of a single patch in a lefkoMat
object with multiple patches should subset the MPM first to contain only
the patch needed. This can be accomplished with the
subset_lM()
function.
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.
start_input()
density_input()
f_projection3()
# 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"),
stage2 = c("Sd", "Sd", "Sd", "Sd", "rep", "rep"),
stage1 = c("Sd", "rep", "Sd", "rep", "all", "all"),
givenrate = c(0.345, 0.345, 0.054, 0.054, NA, NA),
multiplier = c(NA, NA, NA, NA, 0.345, 0.054),
type = c(1, 1, 1, 1, 3, 3), type_t12 = c(1, 2, 1, 2, 1, 1),
stageframe = lathframe, historical = TRUE)
ehrlen3 < rlefko3(data = lathvert, stageframe = lathframe,
year = c(1989, 1990), stages = c("stage3", "stage2", "stage1"),
supplement = lathsupp3, yearcol = "year2", indivcol = "individ")
lathproj < projection3(ehrlen3, nreps = 5, 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)
cypsupp3r < supplemental(stage3 = c("SD", "SD", "P1", "P1", "P2", "P3", "SL",
"D", "XSm", "Sm", "D", "XSm", "Sm", "mat", "mat", "mat", "SD", "P1"),
stage2 = c("SD", "SD", "SD", "SD", "P1", "P2", "P3", "SL", "SL", "SL", "SL",
"SL", "SL", "D", "XSm", "Sm", "rep", "rep"),
stage1 = c("SD", "rep", "SD", "rep", "SD", "P1", "P2", "P3", "P3", "P3",
"SL", "SL", "SL", "SL", "SL", "SL", "mat", "mat"),
eststage3 = c(NA, NA, NA, NA, NA, NA, NA, "D", "XSm", "Sm", "D", "XSm", "Sm",
"mat", "mat", "mat", NA, NA),
eststage2 = c(NA, NA, NA, NA, NA, NA, NA, "XSm", "XSm", "XSm", "XSm", "XSm",
"XSm", "D", "XSm", "Sm", NA, NA),
eststage1 = c(NA, NA, NA, NA, NA, NA, NA, "XSm", "XSm", "XSm", "XSm", "XSm",
"XSm", "XSm", "XSm", "XSm", NA, NA),
givenrate = c(0.1, 0.1, 0.2, 0.2, 0.2, 0.2, 0.25, NA, NA, NA, NA, NA, NA,
NA, NA, NA, NA, NA),
multiplier = c(NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA,
NA, 0.5, 0.5),
type = c(1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 3, 3),
type_t12 = c(1, 2, 1, 2, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1),
stageframe = cypframe_raw, historical = TRUE)
cypmatrix3r < rlefko3(data = cypraw_v1, stageframe = cypframe_raw,
year = "all", patch = "all", stages = c("stage3", "stage2", "stage1"),
size = c("size3added", "size2added", "size1added"),
supplement = cypsupp3r, yearcol = "year2",
patchcol = "patchid", indivcol = "individ")
cypstoch < projection3(cypmatrix3r, nreps = 5, stochastic = TRUE)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.