R: Create Stageframe for Population Matrix Projection Analysis

sf_create {lefko3}

R Documentation

Create Stageframe for Population Matrix Projection Analysis

Description

Function sf_create() returns a data frame describing each ahistorical life history stage in the life history model. This data frame can be used as input into MPM creation functions including flefko3(), flefko2(), aflefko2(), rlefko3(), rlefko2(), and arlefko2(), in which it determines how each stage is treated during matrix estimation.

Usage

sf_create(
  sizes,
  stagenames = NULL,
  sizesb = NULL,
  sizesc = NULL,
  repstatus = NULL,
  obsstatus = NULL,
  propstatus = NULL,
  matstatus = NULL,
  immstatus = NULL,
  minage = NULL,
  maxage = NULL,
  indataset = NULL,
  sizemin = NULL,
  sizebmin = NULL,
  sizecmin = NULL,
  sizemax = NULL,
  sizebmax = NULL,
  sizecmax = NULL,
  binhalfwidth = NULL,
  binhalfwidthb = NULL,
  binhalfwidthc = NULL,
  group = NULL,
  comments = NULL,
  roundsize = 5L,
  roundsizeb = 5L,
  roundsizec = 5L,
  ipmbins = 100L,
  ipmbinsb = NA_integer_,
  ipmbinsc = NA_integer_
)

Arguments

`sizes`	A numeric vector of the typical or representative size of each life history stage. If making function-based MPMs, then this may be a vector composed of the midpoints of each size bin, or simply of sizes characteristic of the size bins. If denoting the boundary of an automated size classification group, then should denote the absolute minimum size of that group, or the absolute size of that group (see `Notes`).
`stagenames`	A vector of stage names, in the same order as elements in sizes. Can also be set to `ipm` for automated size classification (see `Notes` section).
`sizesb`	An optional numeric vector for a second size metric for each life history stage. Only to be used if stages are defined by at least two size metrics in all cases. Same issues apply as in `sizes`.
`sizesc`	An optional numeric vector for a third size metric for each life history stage. Only to be used if stages are defined by at least three size metrics in all cases. Same issues apply as in `sizes`.
`repstatus`	A vector denoting the binomial reproductive status of each life history stage. Defaults to `1`.
`obsstatus`	A vector denoting the binomial observation status of each life history stage. Defaults to `1`, but may be changed for unobservable stages.
`propstatus`	A vector denoting whether each life history stage is a propagule. Such stages are generally only used in fecundity estimation. Defaults to `0`.
`matstatus`	A vector denoting whether each stage is mature. Must be composed of binomial values if given. Defaults to 1 for all stages defined in `sizes`.
`immstatus`	A vector denoting whether each stage is immature. Must be composed of binomial values if given. Defaults to the complement of vector `matstatus`.
`minage`	An optional vector denoting the minimum age at which a stage can occur. Only used in age x stage matrix development. Defaults to `NA`.
`maxage`	An optional vector denoting the maximum age at which a stage should occur. Only used in age x stage matrix development. Defaults to `NA`.
`indataset`	A vector designating which stages are found within the dataset. While `rlefko2()` and `rlefko3()` can use all stages in the input dataset, `flefko3()` and `flefko2()` can only handle size-classified stages with non-overlapping combinations of size and status variables. Stages that do not actually exist within the dataset should be marked as `0` in this vector.
`sizemin`	A vector giving the absolute minimum values corresponding to each size in the `sizes` vector. Requires associated values for `sizemax` if used. Only required if not using `binhalfwidth`.
`sizebmin`	A vector giving the absolute minimum values corresponding to each size in the `sizesb` vector. Requires associated values for `sizebmax` if used. Only required if not using `binhalfwidthb`.
`sizecmin`	A vector giving the absolute minimum values corresponding to each size in the `sizesc` vector. Requires associated values for `sizecmax` if used. Only required if not using `binhalfwidthc`.
`sizemax`	A vector giving the absolute maximum values corresponding to each size in the `sizes` vector. Requires associated values for `sizemin` if used. Only required if not using `binhalfwidth`.
`sizebmax`	A vector giving the absolute maximum values corresponding to each size in the `sizesb` vector. Requires associated values for `sizebmin` if used. Only required if not using `binhalfwidthb`.
`sizecmax`	A vector giving the absolute maximum values corresponding to each size in the `sizesc` vector. Requires associated values for `sizecmin` if used. Only required if not using `binhalfwidthc`.
`binhalfwidth`	A numeric vector giving the half-width of size bins. Required if `sizemin` and `sizemax` are not used. Defaults to `0.5` for all sizes.
`binhalfwidthb`	A numeric vector giving the half-width of size bins used for the optional second size metric. Required if `sizebmin` and `sizebmax` are not used but two or three size classes are used. Defaults to `0.5` for all sizes.
`binhalfwidthc`	A numeric vector giving the half-width of size bins used for the optional third size metric. Required if `sizecmin` and `sizecmax` are not used but three size classes are used. Defaults to `0.5` for all sizes.
`group`	An integer vector providing information on each respective stage's size classification group. If used, then function-based MPM creation functions `flefko2()`, `flefko3()`, and `aflefko2()` will estimate transitions only within these groups and for allowed cross-group transitions noted within the supplement table. Defaults to `0`.
`comments`	An optional vector of text entries holding useful text descriptions of all stages.
`roundsize`	This parameter sets the precision of size classification, and equals the number of digits used in rounding sizes. Defaults to `5`.
`roundsizeb`	This parameter sets the precision of size classification in the optional second size metric, and equals the number of digits used in rounding sizes. Defaults to `5`.
`roundsizec`	This parameter sets the precision of size classification in the optional third size metric, and equals the number of digits used in rounding sizes. Defaults to `5`.
`ipmbins`	An integer giving the number of size bins to create using the primary size classification variable. This number is in addition to any stages that are not size classified. Defaults to `100`, and numbers greater than this yield a warning about the loss of statistical power and increasing chance of matrix over-parameterization resulting from increasing numbers of stages.
`ipmbinsb`	An optional integer giving the number of size bins to create using the secondary size classification variable. This number is in addition to any stages that are not size classified, as well as in addition to any automated size classification using the primary and tertiary size variables. Defaults to `NA`, and must be set to a positive integer for automated size classification to progress.
`ipmbinsc`	An optional integer giving the number of size bins to create using the tertiary size classification variable. This number is in addition to any stages that are not size classified, as well as in addition to any automated size classification using the primary and secondary size variables. Defaults to `NA`, and must be set to a positive integer for automated size classification to progress.

Value

A data frame of class stageframe, which includes information on the stage name, size, reproductive status, observation status, propagule status, immaturity status, maturity status, presence within the core dataset, stage group classification, raw bin half-width, and the minimum, center, and maximum of each size bin, as well as its width. If minimum and maximum ages were specified, then these are also included. Also includes an empty string variable that can be used to describe stages meaningfully. This object can be used as the stageframe input for flefko3() flefko2(), rlefko3(), and rlefko2().

Variables in this data frame include the following:

`stage`	The unique names of the stages to be analyzed.
`size`	The typical or representative size at which each stage occurs.
`size_b`	Size at which each stage occurs in terms of a second size variable, if one exists.
`size_c`	Size at which each stage occurs in terms of a third size variable, if one exists.
`min_age`	The minimum age at which the stage may occur.
`max_age`	The maximum age at which the stage may occur.
`repstatus`	A binomial variable showing whether each stage is reproductive.
`obsstatus`	A binomial variable showing whether each stage is observable.
`propstatus`	A binomial variable showing whether each stage is a propagule.
`immstatus`	A binomial variable showing whether each stage can occur as immature.
`matstatus`	A binomial variable showing whether each stage occurs in maturity.
`indataset`	A binomial variable describing whether each stage occurs in the input dataset.
`binhalfwidth_raw`	The half-width of the size bin, as input.
`sizebin_min`	The minimum size at which the stage may occur.
`sizebin_max`	The maximum size at which the stage may occur.
`sizebin_center`	The midpoint of the size bin at which the stage may occur.
`sizebin_width`	The width of the size bin corresponding to the stage.
`binhalfwidthb_raw`	The half-width of the size bin of a second size variable, as input.
`sizebinb_min`	The minimum size at which the stage may occur.
`sizebinb_max`	The maximum size at which the stage may occur.
`sizebinb_center`	The midpoint of the size bin at which the stage may occur, in terms of a second size variable.
`sizebinb_width`	The width of the size bin corresponding to the stage, in terms of a second size variable.
`binhalfwidthc_raw`	The half-width of the size bin of a third size variable, as input.
`sizebinc_min`	The minimum size at which the stage may occur, in terms of a third size variable.
`sizebinc_max`	The maximum size at which the stage may occur, in terms of a third size variable.
`sizebinc_center`	The midpoint of the size bin at which the stage may occur, in terms of a third size variable.
`sizebinc_width`	The width of the size bin corresponding to the stage, in terms of a third size variable.
`group`	An integer denoting the size classification group that the stage falls within.
`comments`	A text field for stage descriptions.

Notes

Vectors used to create a stageframe may not mix NA values with non-NA values.

If an IPM or function-based matrix with automated size classification is desired, then two stages that occur within the dataset and represent the lower and upper size limits of the IPM must be marked with ipm in the stagenames vector. These stages should have all characteristics other than size equal, and the size input for whichever size will be classified automatically must include the minimum in one stage and the maximum in the other. The actual characteristics of the first stage encountered in the inputs will be used as the template for the creation of these sizes. Note that ipm refers to size classification with the primary size variable. To automate size classification with the secondary size variable, use ipmb, and to automate size classification with the tertiary size variable, use ipmc. To nest automated size classifications, use ipmab for the primary and secondary size variables, ipmac for the primary and tertiary size variables, ipmbc for the secondary and tertiary size variables, and ipmabc for all three size variables. The primary size variable can also be set with ipma.

If two or more groups of stages, each with its own characteristics, are to be developed for an IPM or function-based MPM, then an even number of stages with two stages marking the minimum and maximum size of each group should be marked with the same code as given above, with all other characteristics equal within each group.

Stage classification groups set with the group variable create zones within function-based matrices in which survival transitions are estimated. These groups should not be set if transitions are possible between all stages regardless of group. To denote specific transitions as estimable between stage groups, use the supplemental() function.

If importing an IPM rather than building one with lefko3: Using the vrm_input approach to building function-based MPMs with provided linear model slope coefficients requires careful attention to the stageframe. Although no hfv data frame needs to be entered in this instance, stages for which vital rates are to be estimated via linear models parameterized with coefficients provided via function vrm_import() should be marked as occurring within the dataset. Stages for which the provided coefficients should not be used should be marked as not occurring within the dataset.

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)

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

[Package lefko3 version 6.2.1 Index]