invade3 {adapt3} | R Documentation |
Run Pairwise and Multiple Invasion Analysis
Description
Function invade3
runs pairwise and multiple invasion analyses.
Usage
invade3(
axis = NULL,
mpm = NULL,
vrm = NULL,
stageframe = NULL,
supplement = NULL,
equivalence = NULL,
starts = NULL,
years = NULL,
patches = NULL,
tweights = NULL,
format = NULL,
entry_time = NULL,
sp_density = NULL,
ind_terms = NULL,
dev_terms = NULL,
fb_sparse = NULL,
firstage = NULL,
finalage = NULL,
fecage_min = NULL,
fecage_max = NULL,
cont = NULL,
prebreeding = NULL,
fecmod = NULL,
density = NULL,
density_vr = NULL,
stochastic = NULL,
A_only = NULL,
integeronly = NULL,
fitness_table = NULL,
trait_optima = NULL,
zap_min = NULL,
converged_only = NULL,
err_check = NULL,
var_per_run = 2L,
substoch = 0L,
elast_mult = 0.995,
nreps = 1L,
times = 10000L,
fitness_times = 100L,
exp_tol = 700,
theta_tol = 1e+08,
threshold = 1e-08,
loop_max = 150L
)
Arguments
axis |
The |
mpm |
An MPM of class |
vrm |
A |
stageframe |
A stageframe defining stages and the life cycle for the
entered object in argument |
supplement |
An optional data frame of class |
equivalence |
An optional object of class |
starts |
An optional |
years |
An optional term corresponding to a single integer vector of
time |
patches |
An optional single string giving a single pop-patch to be used during invasion analysis. Defaults to the population-level set or the first patch, depending on whether the former exists. |
tweights |
An optional numeric vector or matrice denoting the probabilities of choosing each matrix in each MPM in a stochastic projection. If a matrix, 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 an element of the list is a vector, then the choice of annual matrix is assumed to be independent of the current matrix. Defaults to equal weighting among matrices. |
format |
An optional integer indicating the kind of function-based MPM
to create, if argument |
entry_time |
An optional integer vector giving the entry time for each
variant into each simulation. Defaults to a zero vector with length equal to
the number of variants to run concurrently in each simulation, as given by
argument |
sp_density |
An optional argument for use with argument |
ind_terms |
An optional argument providing values of individual or
environmental covariate values for argument |
dev_terms |
An optional data frame including 14 columns and up to
|
fb_sparse |
A logical value indicating whether function-based MPMs
should be produced in sparse matrix format. Defaults to |
firstage |
An optional integer used for function-based Leslie and
age-by-stage MPMs giving the starting age in such MPMs. Use only if the MPM
is both function-based and has age structure. Typically, the starting age in
such MPMs should be set to |
finalage |
An optional integer used for function-based Leslie and age-by-stage MPMs giving the final age in such MPMs. Use only if the MPM is both function-based and has age structure. |
fecage_min |
An optional integer used for function-based Leslie MPMs
giving the first age at which organisms can reproduce. Use only if the MPM
is both function-based and has age structure. Defaults to the value given in
|
fecage_max |
An optional integer used for function-based Leslie MPMs
giving the final age at which organisms can reproduce. Use only if the MPM
is both function-based and has age structure. Defaults to the value given in
|
cont |
An optional logical value for function-based Leslie and age-by-stage MPMs stating whether the MPM should should include a stasis transition within the final age. This should be used only when an organism can maintain the demographic characteristics of the final described age after reaching that age. |
prebreeding |
An optional logical value indicating whether the life
cycle is prebreeding ( |
fecmod |
An optional numeric value for function-based MPMs giving scalar multipliers for fecundity terms, when two fecundity variables are used for a collective fecundity per individual. |
density |
An optional data frames of class |
density_vr |
An optional data frame of class |
stochastic |
A logical value indicating whether the projection will be
run as a temporally stochastic projection. Defaults to |
A_only |
A logical value indicating whether to alter survival and
fecundity matrix elements separately prior to creating the overall |
integeronly |
A logical value indicating whether to round the number of
individuals projected in each stage at each occasion down to the next lower
integer. Defaults to |
fitness_table |
A logical value dictating whether to include a data
frame giving Lyapunov coefficients for all combinations of variants tested.
Necessary for the creation of pairwise invasibility plots (PIPs). Defaults
to |
trait_optima |
A logical value indicating whether to assess the optimal
values of traits, generally as kinds of evolutionary stage equilibrium (ESS)
points. Trait optimization is conducted via elasticity analysis of traits
that are variable within the |
zap_min |
A logical value indicating whether to treat traits and
fitness as 0 when their absolute values are less than the value given in
argument |
converged_only |
A logical value indicating whether to show predicted
trait optima only in cases where the Lyapunov coefficient in elasticity
analysis has converged to 0. Defaults to |
err_check |
A logical value indicating whether to include an extra list
of output objects for error checking. Can also be set to the text value
|
var_per_run |
The number of variants to run in each simulation.
Defaults to |
substoch |
An integer value indicating whether to force survival-
transition matrices to be substochastic in density dependent and density
independent simulations. Defaults to |
elast_mult |
A multiplier for traits to assess the elasticity of
fitness in trait optimization. Defaults to |
nreps |
The number of replicate projections. Defaults to |
times |
Number of occasions to iterate per replicate. Defaults to
|
fitness_times |
An integer giving the number of time steps at the end
of each run to use to estimate the fitness of the respective genotype.
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
|
theta_tol |
A numeric value used to indicate a maximum value to theta as
used in the negative binomial probability density kernel. Defaults to
|
threshold |
The lower limit for the absolute value of fitness, below which fitness is rounded to 0. Defaults to 0.00000001. |
loop_max |
An integer value denoting the number of search cycles allowed per ESS during ESS optimization. Defaults to 150. |
Value
A list of class adaptInv
, with the following elements:
fitness |
A data frame giving the Lyapunov coefficients estimated for each variant, per replicate. |
variants_out |
A two-level list with the top level list having number of elements equal to the number of variants, and the lower level corresponding to the number of replicates. Each element of the lower level list is a matrix showing the number of individuals in each stage (row) at each time (column). |
N_out |
A list with the number of elements equal to the number of replicates. Each element within this list is data frame showing the number of individuals of each species or genotype alive at each time. The number of rows are equal to the number of MPMs used, and the columns correspond to the time steps. |
stageframe_list |
A list in which each element is the stageframe for each MPM used. |
hstages_list |
A list giving the used |
agestages_list |
A list giving the used |
labels |
A small data frame giving the the population and patch identities for each MPM entered. |
err_check |
An optional list composed of an additional six lists, each
of which has the number of elements equal to the number of MPMs utilized.
List output include |
Notes
The argument var_per_run
establishes the style of simulation to run.
Entering var_per_run = 1
runs each variant singly. Entering
var_per_run = 2
runs pairwise invasibility analysis, trying each pair
permutation of variants. Greater values will lead to multiple invasibility
analysis with different permutations of groups. For example,
var_per_run = 3
runs each permutation of groups of three. The integer
set must be positive, and must not be larger than the number of variants.
When optima = TRUE
, ESS values for traits that vary in the input
adaptAxis
data frame are evaluated. The methodology is that
originally developed in Benton and Grant (1999, Evolution 53:677-688), as
communicated in Roff (2010, Modeling evolution: an introduction to numerical
methods, Oxford University Press). In essence, function invade3
determines which traits vary among all traits noted in the input trait axis.
A new trait axis is then created with values of variable traits multiplied
by 0.995, and this new trait axis is composed entirely of invaders that will
be paired against each respective row in the original trait axis. These two
trait axis frames are then used to conduct pairwise invasibility elasticity
analyses, particularly noting where fitness values and trends invert. Note
that this optimization approach really only works with one variable trait.
Examples
library(lefko3)
data(cypdata)
sizevector <- c(0, 0, 0, 0, 1, 2.5, 4.5, 8, 17.5)
stagevector <- c("SD", "P1", "SL", "D", "XSm", "Sm", "Md", "Lg", "XLg")
repvector <- c(0, 0, 0, 0, 1, 1, 1, 1, 1)
obsvector <- c(0, 0, 0, 0, 1, 1, 1, 1, 1)
matvector <- c(0, 0, 0, 1, 1, 1, 1, 1, 1)
immvector <- c(0, 1, 1, 0, 0, 0, 0, 0, 0)
propvector <- c(1, 0, 0, 0, 0, 0, 0, 0, 0)
indataset <- c(0, 0, 0, 1, 1, 1, 1, 1, 1)
binvec <- c(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", "SL", "D",
"XSm", "Sm", "SD", "P1"),
stage2 = c("SD", "SD", "P1", "SL", "SL", "SL", "rep",
"rep"),
eststage3 = c(NA, NA, NA, "D", "XSm", "Sm", NA, NA),
eststage2 = c(NA, NA, NA, "XSm", "XSm", "XSm", NA, NA),
givenrate = c(0.10, 0.40, 0.25, NA, NA, NA, NA, NA),
multiplier = c(NA, NA, NA, NA, NA, NA, 1000, 1000),
type =c(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")
cypmean <- lmean(cypmatrix2r)
cyp_start <- start_input(cypmean, stage2 = c("SD", "P1", "D"),
value = c(1000, 200, 4))
c2d_4 <- density_input(cypmean, stage3 = c("P1", "P1"), stage2= c("SD", "rep"),
style = 2, time_delay = 1, alpha = 0.005, beta = 0.000005, type = c(2, 2))
# A simple projection allows us to find a combination of density dependence
# and running time that produces a stable quasi-equilibrium
cyp_proj <- projection3(cypmean, times = 250, start_frame = cyp_start,
density = c2d_4, integeronly = TRUE)
plot(cyp_proj)
cyp_ta <- trait_axis(stageframe = cypframe_raw,
stage3 = rep("P1", 15),
stage2 = rep("rep", 15),
multiplier = seq(from = 0.1, to = 10.0, length.out = 15),
type = rep(2, 15))
cyp_inv <- invade3(axis = cyp_ta, mpm = cypmean, density = c2d_4, times = 350,
starts = cyp_start, entry_time = c(0, 250), fitness_times = 30,
var_per_run = 2)
plot(cyp_inv)