stablestage3.lefkoMatList: Estimate Stable Stage Distribution of Matrices in...
In lefko3: Historical and Ahistorical Population Projection Matrix Analysis
stablestage3.lefkoMatList R Documentation
Estimate Stable Stage Distribution of Matrices in lefkoMatList Object
Description
stablestage3.lefkoMatList() returns the deterministic stable stage
distributions of all A matrices in all objects of class
lefkoMat stored within the entered lefkoMatList object, as well
as the long-run projected mean stage distribution in stochastic analysis.
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 ahistorical
matrices.
Usage
## S3 method for class 'lefkoMatList'
stablestage3(
mats,
stochastic = FALSE,
times = 10000,
tweights = NA,
seed = NA,
force_sparse = "auto",
...
)
Arguments
mats
An object of class lefkoMatList.
stochastic
A logical value indicating whether to use deterministic
(FALSE) or stochastic (TRUE) analysis. Defaults to
FALSE.
times
An integer variable indicating number of occasions to project if
using stochastic analysis. Defaults to 10000.
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.
seed
A number to use as a random number seed in stochastic projection.
force_sparse
A text string indicating whether to use sparse matrix
encoding ("yes") if standard matrices are provided. Defaults to
"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.
...
Other parameters.
Value
This function returns a list with two elements. The first is the mean
stable stage distribution (and long-run mean stage distributions from
stochastic analysis), and the second is a list of stable stage distributions
(and long-run mean stage distributions from stochastic analysis)
corresponding to the lefkoMat objects in the original mats
list.
The format of distributions in both cases depends on whether the
lefkoMat objects used as input are ahistorical or historical, and
whether the analysis is deterministic or stochastic. If deterministic and
ahistorical, then a single data frame is output, which includes the number of
the matrix within the A element of the input lefkoMat object,
followed by the stage id (numeric and assigned through
sf_create()), the stage name, and the estimated proportion of
the stable stage distribution (ss_prop). If stochastic and
ahistorical, then a single data frame is output starting with the number of
the population-patch (matrix_set), a string concatenating the names of
the population and the patch (poppatch), the assigned stage id number
(stage_id), and the stage name (stage), and the long-run
average stage distribution (ss_prop).
If historical matrices are used as input, then two data frames are output
into a list object. The hist element describes the historical
stage-pair distribution, while the ahist element describes the stage
distribution. If deterministic, then hist contains a data frame
including the matrix number (matrix), the numeric stage designations for
stages in occasions t and t-1, (stage_id_2 and
stage_id_1, respectively), followed by the respective stage names (
stage_2 and stage_1), and ending with the estimated stable
stage-pair distribution. The associated ahist element is as before. If
stochastic, then the hist element contains a single data frame with
the number of the population-patch (matrix_set), a string
concatenating the names of the population and the patch (poppatch),
the assigned stage id numbers in times t and t-1 (
stage_id_2 and stage_id_2, respectively), and the associated
stage names (stage_2 and stage_1, respectively), and the
long-run average stage distribution (ss_prop). The associated
ahist element is as before in the ahistorical, stochastic case.
In addition to the data frames noted above, stochastic analysis will result
in the additional output of a list of matrices containing the actual
projected stage distributions across all projected occasions, in the order of
population-patch combinations in the lefkoMat input.
Notes
In stochastic analysis, the projected mean distribution is the arithmetic
mean across the final 1000 projected occasions if the simulation is at least
2000 projected occasions long. If between 500 and 2000 projected occasions
long, then only the final 200 are used, and if fewer than 500 occasions are
used, then all are used. Note that because stage distributions in stochastic
simulations can change greatly in the initial portion of the run, we
encourage a minimum of 2000 projected occasions per simulation, with 10000
preferred.
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.
See Also
stablestage3()
stablestage3.list()
stablestage3.matrix()
stablestage3.dgCMatrix()
stablestage3.lefkoMat()
Examples
# Lathyrus deterministic 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")
ehrlen3mean <- lmean(ehrlen3_boot)
stablestage3(ehrlen3mean)
# Cypripedium stochastic 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)
# Here we use supplemental() to provide overwrite and reproductive info
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")
stablestage3(cypmatrix2r_boot, stochastic = TRUE)
lefko3 documentation built on Nov. 5, 2025, 7:20 p.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.
| stablestage3.lefkoMatList | R Documentation |
Estimate Stable Stage Distribution of Matrices in lefkoMatList Object
Description
stablestage3.lefkoMatList() returns the deterministic stable stage
distributions of all A matrices in all objects of class
lefkoMat stored within the entered lefkoMatList object, as well
as the long-run projected mean stage distribution in stochastic analysis.
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 ahistorical
matrices.
Usage
## S3 method for class 'lefkoMatList'
stablestage3(
mats,
stochastic = FALSE,
times = 10000,
tweights = NA,
seed = NA,
force_sparse = "auto",
...
)
Arguments
mats |
An object of class |
stochastic |
A logical value indicating whether to use deterministic
( |
times |
An integer variable indicating number of occasions to project if using stochastic analysis. Defaults to 10000. |
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. |
seed |
A number to use as a random number seed in stochastic projection. |
force_sparse |
A text string indicating whether to use sparse matrix
encoding ( |
... |
Other parameters. |
Value
This function returns a list with two elements. The first is the mean
stable stage distribution (and long-run mean stage distributions from
stochastic analysis), and the second is a list of stable stage distributions
(and long-run mean stage distributions from stochastic analysis)
corresponding to the lefkoMat objects in the original mats
list.
The format of distributions in both cases depends on whether the
lefkoMat objects used as input are ahistorical or historical, and
whether the analysis is deterministic or stochastic. If deterministic and
ahistorical, then a single data frame is output, which includes the number of
the matrix within the A element of the input lefkoMat object,
followed by the stage id (numeric and assigned through
sf_create()), the stage name, and the estimated proportion of
the stable stage distribution (ss_prop). If stochastic and
ahistorical, then a single data frame is output starting with the number of
the population-patch (matrix_set), a string concatenating the names of
the population and the patch (poppatch), the assigned stage id number
(stage_id), and the stage name (stage), and the long-run
average stage distribution (ss_prop).
If historical matrices are used as input, then two data frames are output
into a list object. The hist element describes the historical
stage-pair distribution, while the ahist element describes the stage
distribution. If deterministic, then hist contains a data frame
including the matrix number (matrix), the numeric stage designations for
stages in occasions t and t-1, (stage_id_2 and
stage_id_1, respectively), followed by the respective stage names (
stage_2 and stage_1), and ending with the estimated stable
stage-pair distribution. The associated ahist element is as before. If
stochastic, then the hist element contains a single data frame with
the number of the population-patch (matrix_set), a string
concatenating the names of the population and the patch (poppatch),
the assigned stage id numbers in times t and t-1 (
stage_id_2 and stage_id_2, respectively), and the associated
stage names (stage_2 and stage_1, respectively), and the
long-run average stage distribution (ss_prop). The associated
ahist element is as before in the ahistorical, stochastic case.
In addition to the data frames noted above, stochastic analysis will result
in the additional output of a list of matrices containing the actual
projected stage distributions across all projected occasions, in the order of
population-patch combinations in the lefkoMat input.
Notes
In stochastic analysis, the projected mean distribution is the arithmetic mean across the final 1000 projected occasions if the simulation is at least 2000 projected occasions long. If between 500 and 2000 projected occasions long, then only the final 200 are used, and if fewer than 500 occasions are used, then all are used. Note that because stage distributions in stochastic simulations can change greatly in the initial portion of the run, we encourage a minimum of 2000 projected occasions per simulation, with 10000 preferred.
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.
See Also
stablestage3()
stablestage3.list()
stablestage3.matrix()
stablestage3.dgCMatrix()
stablestage3.lefkoMat()
Examples
# Lathyrus deterministic 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")
ehrlen3mean <- lmean(ehrlen3_boot)
stablestage3(ehrlen3mean)
# Cypripedium stochastic 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)
# Here we use supplemental() to provide overwrite and reproductive info
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")
stablestage3(cypmatrix2r_boot, stochastic = TRUE)
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.