supplemental: Create a Data Frame of Supplemental Data for MPM Development
In lefko3: Historical and Ahistorical Population Projection Matrix Analysis
supplemental R Documentation
Create a Data Frame of Supplemental Data for MPM Development
Description
Function supplemental() provides all necessary supplemental data for
matrix estimation. It allows the establishment of proxy rates, the entry of
data to overwrite or offset existing rates, the identification of complete
reproductive transitions, and the entry of rate multipliers. The function
should be used to incorporate data that affects all matrices to be created.
To edit MPMs after creation, use edit_lM() instead.
Usage
supplemental(
historical = TRUE,
stagebased = TRUE,
agebased = FALSE,
stageframe = NULL,
stage3 = NULL,
stage2 = NULL,
stage1 = NULL,
age2 = NULL,
eststage3 = NULL,
eststage2 = NULL,
eststage1 = NULL,
estage2 = NULL,
givenrate = NULL,
offset = NULL,
multiplier = NULL,
type = NULL,
type_t12 = NULL
)
Arguments
historical
A logical value indicating whether the MPMs intended will
be historical or ahistorical. Defaults to TRUE.
stagebased
A logical value indicating whether the MPM will be stage-
based or age-by-stage. Defaults to TRUE.
agebased
A logical value indicating whether the MPM will be age-based
or age-by-stage. Defaults to FALSE.
stageframe
The stageframe used to produce the MPM. Required if
producing any stage-based or age-by-stage MPM. Must be omitted for purely
age-based MPMs.
stage3
The name of the stage in occasion t+1 in the transition
to be replaced. Abbreviations for groups of stages are also usable (see
Notes). Required in all stage-based and age-by-stage MPMs.
stage2
The name of the stage in occasion t in the transition
to be replaced. Abbreviations for groups of stages are also usable (see
Notes). Required in all stage-based and age-by-stage MPMs.
stage1
The name of the stage in occasion t-1 in the transition
to be replaced. Only needed if a historical matrix is to be produced.
Abbreviations for groups of stages are also usable (see Notes).
Required for historical stage-based MPMs.
age2
An integer vector of the ages in occasion t to use in
transitions to be changed or replaced. Required for all age- and
age-by-stage MPMs.
eststage3
The name of the stage to replace stage3 in a proxy
transition. Only needed if a transition will be replaced by another
estimated transition, and only in stage-based and age-by-stage MPMs.
eststage2
The name of the stage to replace stage2 in a proxy
transition. Only needed if a transition will be replaced by another
estimated transition, and only in stage-based and age-by-stage MPMs.
eststage1
The name of the stage to replace stage1 in a proxy
historical transition. Only needed if a transition will be replaced by
another estimated transition, and the matrix to be estimated is historical
and stage-based. Stage NotAlive is also possible for raw hMPMs as a
means of handling the prior stage for individuals entering the population in
occasion t.
estage2
The age at time t to replace age2 in a proxy
transition. Only needed if a transition will be replaced by another
estimated transition, and only in age-based and age-by-stage MPMs.
givenrate
A fixed rate or probability to replace for the transition
described by stage3, stage2, stage1, and/or
age2.
offset
A fixed numeric value to add to the transition described by
stage3, stage2, stage1, and/or age2.
multiplier
A vector of numeric multipliers for the transition
described by stage3, stage2, stage1, and/or
age2, or for the proxy transitions described by eststage3,
eststage2, eststage1, and/or estage2. Defaults to
1.
type
A vector denoting the kind of transition between occasions
t and t+1 to be replaced. This should be entered as 1,
S, or s for the replacement of a survival transition;
2, F, or f for the replacement of a fecundity
transition; or 3, R, or r for a fecundity set value /
general multiplier. If empty or not provided, then defaults to 1 for
survival transition.
type_t12
An optional vector denoting the kind of transition between
occasions t-1 and t. Only necessary if a historical MPM in
deVries format is desired. This should be entered as 1, S, or
s for a survival transition; or 2, F, or f for a
fecundity transitions. Defaults to 1 for survival transition, with
impacts only on the construction of deVries-format hMPMs.
Value
A data frame of class lefkoSD. This object can be used as
input in flefko3(), flefko2(),
rlefko3(), rlefko2(), and
aflefko2().
Variables in this object include the following:
stage3
Stage at occasion t+1 in the transition to be
replaced.
stage2
Stage at occasion t in the transition to be replaced.
stage1
Stage at occasion t-1 in the transition to be
replaced.
age2
Age at occasion t in the transition to be replaced.
eststage3
Stage at occasion t+1 in the transition to replace
the transition designated by stage3, stage2, and
stage1.
eststage2
Stage at occasion t in the transition to replace the
transition designated by stage3, stage2, and stage1.
eststage1
Stage at occasion t-1 in the transition to replace
the transition designated by stage3, stage2, and
stage1.
estage2
Age at occasion t in the transition to replace the
transition designated by age2.
givenrate
A constant to be used as the value of the transition.
offset
A constant value to be added to the transition or proxy
transition.
multiplier
A multiplier for proxy transitions or for fecundity.
convtype
Designates whether the transition from occasion t to
occasion t+1 is a survival transition probability (1), a fecundity
rate (2), or a fecundity multiplier (3).
convtype_t12
Designates whether the transition from occasion
t-1 to occasion t is a survival transition probability (1), a
fecundity rate (2).
Notes
Negative values are not allowed in givenrate and multiplier
input, but are allowed in offset, if values are to be subtracted from
specific estimated transitions. Stage entries should not be used for purely
age-based MPMs, and age entries should not be used for purely stage-based
MPMs.
Fecundity multiplier data supplied via the supplemental() function
acts in the same way as non-zero entries supplied via a reproductive matrix,
but gets priority in all matrix creations. Thus, in cases where fecundity
multipliers are provided for the same function via the reproductive matrix
and function supplemental(), the latter is used.
Entries in stage3, stage2, and stage1 can include
abbreviations for groups of stages. Use rep if all reproductive
stages are to be used, nrep if all mature but non-reproductive stages
are to be used, mat if all mature stages are to be used, immat
if all immature stages are to be used, prop if all propagule stages
are to be used, npr if all non-propagule stages are to be used,
obs if all observable stages are to be used, nobs if all
unobservable stages are to be used, and leave empty or use all if all
stages in stageframe are to be used. Also use groupX to denote all
stages in group X (e.g. group1 will use all stages in the respective
stageframe's group 1).
Type 3 conversions are referred to as fecundity set values, or general
fecundity multipliers. These set the transitions to be used as fecundity
transitions. Transitions set here will be interpreted as being generally
reproductive, meaning that the from and to stages will be used to determine
the general fecundity transitions to incorporate into stage-based MPMs,
while the age portion of the input will be used to incorporate the actual
multiplier(s) specified. If only stage transitions at certain ages are
expected to be the sole contributors to fecundity, then type 2 conversions
should also be included in the supplement (Type 1 and 2 conversions can be
purely age-specific, and do not set reproductive transitions in MPM
creation). For example, if all stage 2 to stage 3 transitions above age 2
yield fecundity, then stage 2 to stage 3 can be set to
multiplier = 1.0 with convtype = 3, and the same transition
for age2 = c(1, 2) can be set to multiplier = c(0, 0).
Several operations may be included per transition. Operations on the same
row of the resulting data frame are generally handled with given rate
substitutions first, then with proxy transitions, then by additive offsets,
and finally by multipliers. This order can be manipulated by ordering
operations across rows, with higher numbered rows in the data frame being
performed later.
See Also
edit_lM()
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")
# 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)
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")
lefko3 documentation built on April 4, 2025, 2:53 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| supplemental | R Documentation |
Create a Data Frame of Supplemental Data for MPM Development
Description
Function supplemental() provides all necessary supplemental data for
matrix estimation. It allows the establishment of proxy rates, the entry of
data to overwrite or offset existing rates, the identification of complete
reproductive transitions, and the entry of rate multipliers. The function
should be used to incorporate data that affects all matrices to be created.
To edit MPMs after creation, use edit_lM() instead.
Usage
supplemental(
historical = TRUE,
stagebased = TRUE,
agebased = FALSE,
stageframe = NULL,
stage3 = NULL,
stage2 = NULL,
stage1 = NULL,
age2 = NULL,
eststage3 = NULL,
eststage2 = NULL,
eststage1 = NULL,
estage2 = NULL,
givenrate = NULL,
offset = NULL,
multiplier = NULL,
type = NULL,
type_t12 = NULL
)
Arguments
historical |
A logical value indicating whether the MPMs intended will
be historical or ahistorical. Defaults to |
stagebased |
A logical value indicating whether the MPM will be stage-
based or age-by-stage. Defaults to |
agebased |
A logical value indicating whether the MPM will be age-based
or age-by-stage. Defaults to |
stageframe |
The stageframe used to produce the MPM. Required if producing any stage-based or age-by-stage MPM. Must be omitted for purely age-based MPMs. |
stage3 |
The name of the stage in occasion t+1 in the transition
to be replaced. Abbreviations for groups of stages are also usable (see
|
stage2 |
The name of the stage in occasion t in the transition
to be replaced. Abbreviations for groups of stages are also usable (see
|
stage1 |
The name of the stage in occasion t-1 in the transition
to be replaced. Only needed if a historical matrix is to be produced.
Abbreviations for groups of stages are also usable (see |
age2 |
An integer vector of the ages in occasion t to use in transitions to be changed or replaced. Required for all age- and age-by-stage MPMs. |
eststage3 |
The name of the stage to replace |
eststage2 |
The name of the stage to replace |
eststage1 |
The name of the stage to replace |
estage2 |
The age at time t to replace |
givenrate |
A fixed rate or probability to replace for the transition
described by |
offset |
A fixed numeric value to add to the transition described by
|
multiplier |
A vector of numeric multipliers for the transition
described by |
type |
A vector denoting the kind of transition between occasions
t and t+1 to be replaced. This should be entered as |
type_t12 |
An optional vector denoting the kind of transition between
occasions t-1 and t. Only necessary if a historical MPM in
deVries format is desired. This should be entered as |
Value
A data frame of class lefkoSD. This object can be used as
input in flefko3(), flefko2(),
rlefko3(), rlefko2(), and
aflefko2().
Variables in this object include the following:
stage3 |
Stage at occasion t+1 in the transition to be replaced. |
stage2 |
Stage at occasion t in the transition to be replaced. |
stage1 |
Stage at occasion t-1 in the transition to be replaced. |
age2 |
Age at occasion t in the transition to be replaced. |
eststage3 |
Stage at occasion t+1 in the transition to replace
the transition designated by |
eststage2 |
Stage at occasion t in the transition to replace the
transition designated by |
eststage1 |
Stage at occasion t-1 in the transition to replace
the transition designated by |
estage2 |
Age at occasion t in the transition to replace the
transition designated by |
givenrate |
A constant to be used as the value of the transition. |
offset |
A constant value to be added to the transition or proxy transition. |
multiplier |
A multiplier for proxy transitions or for fecundity. |
convtype |
Designates whether the transition from occasion t to occasion t+1 is a survival transition probability (1), a fecundity rate (2), or a fecundity multiplier (3). |
convtype_t12 |
Designates whether the transition from occasion t-1 to occasion t is a survival transition probability (1), a fecundity rate (2). |
Notes
Negative values are not allowed in givenrate and multiplier
input, but are allowed in offset, if values are to be subtracted from
specific estimated transitions. Stage entries should not be used for purely
age-based MPMs, and age entries should not be used for purely stage-based
MPMs.
Fecundity multiplier data supplied via the supplemental() function
acts in the same way as non-zero entries supplied via a reproductive matrix,
but gets priority in all matrix creations. Thus, in cases where fecundity
multipliers are provided for the same function via the reproductive matrix
and function supplemental(), the latter is used.
Entries in stage3, stage2, and stage1 can include
abbreviations for groups of stages. Use rep if all reproductive
stages are to be used, nrep if all mature but non-reproductive stages
are to be used, mat if all mature stages are to be used, immat
if all immature stages are to be used, prop if all propagule stages
are to be used, npr if all non-propagule stages are to be used,
obs if all observable stages are to be used, nobs if all
unobservable stages are to be used, and leave empty or use all if all
stages in stageframe are to be used. Also use groupX to denote all
stages in group X (e.g. group1 will use all stages in the respective
stageframe's group 1).
Type 3 conversions are referred to as fecundity set values, or general
fecundity multipliers. These set the transitions to be used as fecundity
transitions. Transitions set here will be interpreted as being generally
reproductive, meaning that the from and to stages will be used to determine
the general fecundity transitions to incorporate into stage-based MPMs,
while the age portion of the input will be used to incorporate the actual
multiplier(s) specified. If only stage transitions at certain ages are
expected to be the sole contributors to fecundity, then type 2 conversions
should also be included in the supplement (Type 1 and 2 conversions can be
purely age-specific, and do not set reproductive transitions in MPM
creation). For example, if all stage 2 to stage 3 transitions above age 2
yield fecundity, then stage 2 to stage 3 can be set to
multiplier = 1.0 with convtype = 3, and the same transition
for age2 = c(1, 2) can be set to multiplier = c(0, 0).
Several operations may be included per transition. Operations on the same row of the resulting data frame are generally handled with given rate substitutions first, then with proxy transitions, then by additive offsets, and finally by multipliers. This order can be manipulated by ordering operations across rows, with higher numbered rows in the data frame being performed later.
See Also
edit_lM()
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")
# 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)
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")
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.