mpm_create  R Documentation 
Function mpm_create()
is the core workhorse function that creates
all flavors of MPM in lefko3
. All other MPM creation functions act
as wrappers for this function. As such, this function provides the most
general and most detailed control over the MPM creation process.
mpm_create(
historical = FALSE,
stage = TRUE,
age = FALSE,
devries = FALSE,
reduce = FALSE,
simple = FALSE,
err_check = FALSE,
data = NULL,
year = NULL,
pop = NULL,
patch = NULL,
stageframe = NULL,
supplement = NULL,
overwrite = NULL,
repmatrix = NULL,
alive = NULL,
obsst = NULL,
size = NULL,
sizeb = NULL,
sizec = NULL,
repst = NULL,
matst = NULL,
fec = NULL,
stages = NULL,
yearcol = NULL,
popcol = NULL,
patchcol = NULL,
indivcol = NULL,
agecol = NULL,
censorcol = NULL,
modelsuite = NULL,
paramnames = NULL,
inda = NULL,
indb = NULL,
indc = NULL,
dev_terms = NULL,
density = NA_real_,
CDF = TRUE,
random_inda = FALSE,
random_indb = FALSE,
random_indc = FALSE,
negfec = FALSE,
exp_tol = 700L,
theta_tol = 100000000L,
censor = FALSE,
censorkeep = NULL,
start_age = NA_integer_,
last_age = NA_integer_,
fecage_min = NA_integer_,
fecage_max = NA_integer_,
fectime = 2L,
fecmod = 1,
cont = TRUE,
prebreeding = TRUE,
stage_NRasRep = FALSE,
sparse_output = FALSE
)
historical 
A logical value indicating whether to build a historical
MPM. Defaults to 
stage 
A logical value indicating whether to build a stagebased MPM.
If both 
age 
A logical value indicating whether to build an agebased MPM. If
both 
devries 
A logical value indicating whether to use deVries format
for historical MPMs. Defaults to 
reduce 
A logical value denoting whether to remove ages, ahistorical
stages, or historical stages associated exclusively with zero transitions.
These are removed only if the respective row and column sums in ALL matrices
estimated equal 0. Defaults to 
simple 
A logical value indicating whether to produce 
err_check 
A logical value indicating whether to append extra
information used in matrix calculation within the output list. Defaults to

data 
A data frame of class 
year 
A variable corresponding to observation occasion, or a set of
such values, given in values associated with the 
pop 
A variable designating which populations will have matrices
estimated. Should be set to specific population names, or to 
patch 
A variable designating which patches or subpopulations will have
matrices estimated. Should be set to specific patch names, or to 
stageframe 
An object of class 
supplement 
An optional data frame of class 
overwrite 
An optional data frame developed with the

repmatrix 
An optional reproduction matrix. This matrix is composed
mostly of 
alive 
A vector of names of binomial variables corresponding to status
as alive ( 
obsst 
A vector of names of binomial variables corresponding to
observation status in occasions t+1, t, and t1,
respectively. Defaults to 
size 
A vector of names of variables coding the primary size variable
in occasions t+1, t, and t1, respectively. Defaults to

sizeb 
A vector of names of variables coding the secondary size variable in occasions t+1, t, and t1, respectively. Defaults to an empty set, assuming that secondary size is not used. Only needed for raw, stagebased MPMs. 
sizec 
A vector of names of variables coding the tertiary size variable in occasions t+1, t, and t1, respectively. Defaults to an empty set, assuming that tertiary size is not used. Only needed for raw, stagebased MPMs. 
repst 
A vector of names of binomial variables corresponding to
reproductive status in occasions t+1, t, and t1,
respectively. Defaults to 
matst 
A vector of names of binomial variables corresponding to
maturity status in occasions t+1, t, and t1,
respectively. Defaults to 
fec 
A vector of names of variables coding for fecundity in occasions
t+1, t, and t1, respectively. Defaults to

stages 
An optional vector denoting the names of the variables within
the main vertical dataset coding for the stages of each individual in
occasions t+1 and t, and t1, if historical. The names
of stages in these variables should match those used in the

yearcol 
The variable name or column number corresponding to occasion
t in the dataset. Defaults to 
popcol 
The variable name or column number corresponding to the
identity of the population. Defaults to 
patchcol 
The variable name or column number corresponding to patch in
the dataset. Defaults to 
indivcol 
The variable name or column number coding individual identity. Only needed for raw MPMs. 
agecol 
The variable name or column corresponding to age in time
t. Defaults to 
censorcol 
The variable name or column number denoting the censor
status. Only needed in raw MPMs, and only if 
modelsuite 
One of three kinds of lists. The first is a

paramnames 
A data frame with three columns, the first describing all
terms used in linear modeling, the second (must be called 
inda 
Can be a single value to use for individual covariate 
indb 
Can be a single value to use for individual covariate 
indc 
Can be a single value to use for individual covariate 
dev_terms 
A numeric vector of 2 elements in the case of a Leslie MPM,
and of 14 elements in all other cases. Consists of scalar additions to the
yintercepts of vital rate linear models used to estimate vital rates in
functionbased MPMs. Defaults to 
density 
A numeric value indicating density value to use to propagate
matrices. Only needed if density is an explanatory term used in one or more
vital rate models. Defaults to 
CDF 
A logical value indicating whether to use the cumulative
distribution function to estimate size transition probabilities in
functionbased MPMs. Defaults to 
random_inda 
A logical value denoting whether to treat individual
covariate 
random_indb 
A logical value denoting whether to treat individual
covariate 
random_indc 
A logical value denoting whether to treat individual
covariate 
negfec 
A logical value denoting whether fecundity values estimated to
be negative should be reset 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

theta_tol 
A numeric value used to indicate a maximum value to theta
as used in the negative binomial probability density kernel. Defaults to

censor 
If 
censorkeep 
The value of the censor variable denoting data elements to
keep. Defaults to 
start_age 
The age from which to start the matrix. Defaults to

last_age 
The final age to use in the matrix. Defaults to 
fecage_min 
The minimum age at which reproduction is possible.
Defaults to 
fecage_max 
The maximum age at which reproduction is possible.
Defaults to 
fectime 
An integer indicating whether to estimate fecundity using
the variable given for 
fecmod 
A scalar multiplier for fecundity. Only used for purely
agebased MPMs. Defaults to 
cont 
A logical value designating whether to allow continued survival
of individuals past the final age noted in agebased and agebystage MPMs,
using the demographic characteristics of the final age. Defaults to

prebreeding 
A logical value indicating whether the life history model
is a prebreeding model. Defaults to 
stage_NRasRep 
A logical value indicating whether to treat
nonreproductive individuals as reproductive. Used only in raw, stagebased
MPMs in cases where stage assignment must still be handled. Not used in
functionbased MPMs, and in stagebased MPMs in which a valid 
sparse_output 
A logical value indicating whether to output matrices
in sparse format. Defaults to 
An object of class lefkoMat
. This is a list that holds the
matrix projection model and all of its metadata. The structure has the
following elements:
A 
A list of full projection matrices in order of sorted patches and
occasion times. All matrices output in R's 
U 
A list of survival transition matrices sorted as in 
F 
A list of fecundity matrices sorted as in 
hstages 
A data frame matrix showing the pairing of ahistorical stages used to create historical stage pairs. Only used in historical MPMs. 
agestages 
A data frame showing agestage pairs. Only used in agebystage MPMs. 
ahstages 
A data frame detailing the characteristics of associated ahistorical stages, in the form of a modified stageframe that includes status as an entry stage through reproduction. Used in all stagebased and agebystage MPMs. 
labels 
A data frame giving the population, patch, and year of each matrix in order. 
dataqc 
A vector showing the numbers of individuals and rows in the vertical dataset used as input. 
matrixqc 
A short vector describing the number of nonzero elements in

modelqc 
This is the 
prob_out 
An optional element only added if 
allstages 
An optional element only added if 
data 
An optional element only added if 
This function automatically determines whether to create a raw or functionbased MPM given inputs supplied by the user.
If used, the reproduction matrix (field repmatrix
) may be supplied as
either historical or ahistorical. If provided as historical, then
a historical MPM must be estimated.
If neither a supplement nor a reproduction matrix are used, and the MPM to create is stagebased, then fecundity will be assumed to occur from all reproductive stages to all propagule and immature stages.
Users may at times wish to estimate MPMs using a dataset incorporating
multiple patches or subpopulations, but without discriminating between those
patches or subpopulations. Should the aim of analysis be a general MPM that
does not distinguish these patches or subpopulations, the
modelsearch()
run should not include patch terms.
Input options including multiple variable names must be entered in the order of variables in occasion t+1, t, and t1. Rearranging the order will lead to erroneous calculations, and will may lead to fatal errors.
This function provides two different means of estimating the probability of
size transition. The midpoint method (CDF = FALSE
) refers to the
method in which the probability is estimated by first estimating the
probability associated with transition from the exact size at the midpoint
of the size class using the corresponding probability density function, and
then multiplying that value by the bin width of the size class. Doak et al.
2021 (Ecological Monographs) noted that this method can produce biased
results, with total size transitions associated with a specific size not
totaling to 1.0 and even specific size transition probabilities capable of
being estimated at values greater than 1.0. The alternative and default
method (CDF = TRUE
) uses the cumulative density function to estimate
the probability of size transition as the cumulative probability of size
transition at the greater limit of the size class minus the cumulative
probability of size transition at the lower limit of the size class. This
latter method avoids this bias. Note, however, that both methods are exact
and unbiased for negative binomial and Poisson distributions.
Under the Gaussian and gamma size distributions, the number of estimated
parameters may differ between the two ipm_method
settings. Because
the midpoint method has a tendency to incorporate upward bias in the
estimation of size transition probabilities, it is more likely to yield non
zero values when the true probability is extremely close to 0. This will
result in the summary.lefkoMat()
function yielding higher numbers of
estimated parameters than the ipm_method = "CDF"
yields in some cases.
data(lathyrus)
sizevector < c(0, 4.6, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 1, 2, 3, 4, 5, 6, 7, 8,
9)
stagevector < c("Sd", "Sdl", "Dorm", "Sz1nr", "Sz2nr", "Sz3nr", "Sz4nr",
"Sz5nr", "Sz6nr", "Sz7nr", "Sz8nr", "Sz9nr", "Sz1r", "Sz2r", "Sz3r",
"Sz4r", "Sz5r", "Sz6r", "Sz7r", "Sz8r", "Sz9r")
repvector < c(0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 1)
obsvector < c(0, 1, 0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1)
matvector < c(0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1)
immvector < c(1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0)
propvector < c(1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
0)
indataset < c(0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1)
binvec < c(0, 4.6, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5,
0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5)
lathframeln < sf_create(sizes = sizevector, stagenames = stagevector,
repstatus = repvector, obsstatus = obsvector, matstatus = matvector,
immstatus = immvector, indataset = indataset, binhalfwidth = binvec,
propstatus = propvector)
lathvertln < verticalize3(lathyrus, noyears = 4, firstyear = 1988,
patchidcol = "SUBPLOT", individcol = "GENET", blocksize = 9,
juvcol = "Seedling1988", sizeacol = "lnVol88", repstracol = "Intactseed88",
fecacol = "Intactseed88", deadacol = "Dead1988",
nonobsacol = "Dormant1988", stageassign = lathframeln, stagesize = "sizea",
censorcol = "Missing1988", censorkeep = NA, NAas0 = TRUE, censor = TRUE)
lathvertln$feca2 < round(lathvertln$feca2)
lathvertln$feca1 < round(lathvertln$feca1)
lathvertln$feca3 < round(lathvertln$feca3)
lathvertln_adults < subset(lathvertln, stage2index > 2)
surv_model < glm(alive3 ~ sizea2 + sizea1 + as.factor(patchid) +
as.factor(year2), data = lathvertln_adults, family = "binomial")
obs_data < subset(lathvertln_adults, alive3 == 1)
obs_model < glm(obsstatus3 ~ as.factor(patchid), data = obs_data,
family = "binomial")
size_data < subset(obs_data, obsstatus3 == 1)
siz_model < lm(sizea3 ~ sizea2 + sizea1 + repstatus1 + as.factor(patchid) +
as.factor(year2), data = size_data)
reps_model < glm(repstatus3 ~ sizea2 + sizea1 + as.factor(patchid) +
as.factor(year2), data = size_data, family = "binomial")
fec_data < subset(lathvertln_adults, repstatus2 == 1)
fec_model < glm(feca2 ~ sizea2 + sizea1 + repstatus1 + as.factor(patchid),
data = fec_data, family = "poisson")
lathvertln_juvs < subset(lathvertln, stage2index < 3)
jsurv_model < glm(alive3 ~ as.factor(patchid), data = lathvertln_juvs,
family = "binomial")
jobs_data < subset(lathvertln_juvs, alive3 == 1)
jobs_model < glm(obsstatus3 ~ 1, family = "binomial", data = jobs_data)
jsize_data < subset(jobs_data, obsstatus3 == 1)
jsiz_model < lm(sizea3 ~ as.factor(year2), data = jsize_data)
jrepst_model < 0
jmatst_model < 1
mod_params < create_pm(name_terms = TRUE)
mod_params$modelparams[3] < "patchid"
mod_params$modelparams[4] < "alive3"
mod_params$modelparams[5] < "obsstatus3"
mod_params$modelparams[6] < "sizea3"
mod_params$modelparams[9] < "repstatus3"
mod_params$modelparams[11] < "feca2"
mod_params$modelparams[12] < "sizea2"
mod_params$modelparams[13] < "sizea1"
mod_params$modelparams[18] < "repstatus2"
mod_params$modelparams[19] < "repstatus1"
used_models < list(survival_model = surv_model, observation_model = obs_model,
size_model = siz_model, sizeb_model = 1, sizec_model = 1,
repstatus_model = reps_model, fecundity_model = fec_model,
juv_survival_model = jsurv_model, juv_observation_model = jobs_model,
juv_size_model = jsiz_model, juv_sizeb_model = 1, juv_sizec_model = 1,
juv_reproduction_model = 0, juv_maturity_model = 1, paramnames = mod_params)
lathsupp3 < supplemental(stage3 = c("Sd", "Sd", "Sdl", "Sdl", "mat", "Sd", "Sdl"),
stage2 = c("Sd", "Sd", "Sd", "Sd", "Sdl", "rep", "rep"),
stage1 = c("Sd", "rep", "Sd", "rep", "Sd", "mat", "mat"),
eststage3 = c(NA, NA, NA, NA, "mat", NA, NA),
eststage2 = c(NA, NA, NA, NA, "Sdl", NA, NA),
eststage1 = c(NA, NA, NA, NA, "Sdl", NA, NA),
givenrate = c(0.345, 0.345, 0.054, 0.054, NA, NA, NA),
multiplier = c(NA, NA, NA, NA, NA, 0.345, 0.054),
type = c(1, 1, 1, 1, 1, 3, 3), type_t12 = c(1, 2, 1, 2, 1, 1, 1),
stageframe = lathframeln, historical = TRUE)
# While we do not use MPMs to initialize f_projections3(), we do use MPMs to
# initialize functions start_input() and density_input().
lathmat3ln < mpm_create(historical = TRUE, year = "all", patch = "all",
data = lathvertln, stageframe = lathframeln, supplement = lathsupp3,
modelsuite = used_models, reduce = FALSE)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.