best.locale: A function to assess and rank possible locations for their...

In wpeterman/ssmc: Assess source-sink population status using Monte Carlo simulation

A function to assess and rank possible locations for their contribution to the metapopulation

Description

A function to assess and rank possible locations for their contribution to the metapopulation

Usage

best.locale(sites,
restore = FALSE,
potential.sites = NULL,
pop.abun,
met.size=NULL,
prop.philo=.85,
sd.philo = 0.05,
lower.upper_philo=c(lower=0, upper=1),
prop.survive=0.2,
sd.survive = 0.075,
lower.upper_survive = c(lower=0, upper=1),
dispersal,
sd.dispersal,
lower.upper_dispersal = c(lower=1, upper=Inf),
eps = 1,
mu = 2,
eta = 0.5,
iterations,
seed=NULL)

Arguments

sites	A four-column matrix or data frame providing the name of the site (column 1) and the xy coordinates of current sites (columns 2 & 3), and area of the habitat patch (column 4)
restore	Logical. If TRUE, then potential.sites does not need to be specified. Instead, existing sites provided in sites that are currently unoccupied (abundance = 0) will be iteratively assessed at the mean of all occupied sites.
potential.sites	A three column matrix providing the name of the site (column 1) and the xy coordinates of current sites (columns 2 & 3)
pop.abun	A two-column data frame with mean population size in column 1 and standard deviation in column 2
met.size	(Default = NULL) If specified, must be a two-column data frame with the mean (column 1) and standard deviation (column 2) of the size of metamoprhs or late-stage larvae. See Details for more information concerning this parameter.
prop.philo	(Default = 0.85) Mean proportion of population that are philopatric to their natal population
sd.philo	(Default = 0.05) Standard deviation of proportion of population that are philopatric to their natal population
lower.upper_philo	(Default = c(lower=0, upper=1)) Threshold lower and upper values for the proportion of philopatric individuals. Must be provided as a two-element vector with lower value first. See Details for use
prop.survive	(Default = 0.2) Mean survival of to adulthood. Ignored if met.size is specified. See Details for more information.
sd.survive	(Default = 0.075) Standard deviation of survival of to adulthood.
lower.upper_survive	(Default = c(lower=0, upper=1))Threshold lower and upper values for the proportion of individuals surviving to adulthood. Must be provided as a two-element vector with lower value first. See Details
dispersal	Mean dispersal distance. Should be specified in units meaningful to the coordinate system describing the spatial location of populations. See Details for how dispersal is estimated.
sd.dispersal	Standard deviation of dispersal distance.
lower.upper_dispersal	(Default = c(lower=1, upper=Inf))Threshold lower and upper values for average dispersal distance. Must be provided as a two-element vector with minimum value first. See Details
eps	Coefficient ([0,1]) relating to minimum patch size (Default = 1). See Details
mu	Number of immigrants needed for successful colonization (Default = 2). See Details
eta	Scaling parameter (Default = 0.5). See Details
iterations	Number of Monte Carlo iterations to run
seed	Optional to set the seed for repeatability among model runs (Default = NULL)

Details

If met.size is specified, the probability of surviving to adulthood is determined using the equation:

logit(p.survive) = -1.366 + 0.87 * size

This equation comes from Altwegg & Reyer (2003). Mean and standard deviation values for met.size must be reported in standard units such that the mean and standard deviation of observations equal zero and one, respectively (i.e. scale and center observations). In the absence of metamorph data, survival probability and variation can be specified using prop.survive.

This model assumes uncertainty or variability in:
(1) population size;
(2) size of metamorphs OR proportion surviving;
(3) proportion of population that is philopatric;
(4) mean dispersal distance.

Uncertainty in these parameters is incorporated through repeated draws from normal distibutions with a mean and standard deviation as specified. Because some values are unrealistic (e.g., survival > 1), a truncated normal distribution is used, which requires the specification of lower and upper values. If there are no limits on the lower or upper values, then -Inf or Inf should be specified. Lower and upper values must be provided as a two-element vector (e.g., c(0,1)) for lower.upper_philo, lower.upper_survive, and lower.upper_dispersal

Probability of dispersal between two populations is determined using an incidence function wherein the probability of connectivity is a negative exponential relationship with 1/mean dispersal controlling the rate of decay.

Value

This function returns a list with two components: (1) $summary.df is a data frame with the results averaged over all Monte Carlo iterations, and (2) $results.list is a list of length equal to the number of Monte Carlo iterations and contains the raw results from the analysis.

Elements of the summary data frame include:
(1) mmlt: The log10 of the Metapopulation Mean Lifetime;
(2) rank: The rank order importance based on mmlt;
(3) frq_col: The frequency that 2 or more individuals immigrated into a population. This metric is used to adjust mmlt for likelihood of colonization;
(4) mmlt_col: The product of mmlt and frq_col;
(5) rank_adj: The rank importance of each potential location based on the product of mmlt and the frequency of colonization (frq_col)

Author(s)

Bill Peterman <[e-mail]>

References

Altwegg, R., and H.-U. Reyer. 2003. Patterns of natural selection on size at metamorphosis in water frogs. Evolution 57:872-882.

See Also

ssmc_summary

Examples

   ## Assess potential new locations
   best_results <- best.locale(sites = site.dat[,1:4],
   potential.sites = potential.dat,
   pop.abun = site.dat[,5:6],
   met.size = site.dat[,7:8],
   prop.philo = 0.95,
   sd.philo = 0.05,
   lower.upper_philo=c(lower=0, upper=1),
   # prop.survive=0.2,      ## Not needed b/c met.size is specified
   # sd.survive = 0.075,    ## Not needed b/c met.size is specified
   lower.upper_survive = c(lower=0, upper=1),
   dispersal = 25,
   sd.dispersal = 10,
   lower.upper_dispersal = c(lower=10, upper=Inf),
   eps = 1,
   mu = 2,
   eta = 0.5,
   iterations = 10,
   seed = 123)

   ## Assess existing locations for restoration
   best_results <- best.locale(sites = site.dat[,1:4],
   restore = TRUE,
   pop.abun = site.dat[,5:6],
   met.size = site.dat[,7:8],
   prop.philo = 0.95,
   sd.philo = 0.05,
   lower.upper_philo=c(lower=0, upper=1),
   # prop.survive=0.2,      ## Not needed b/c met.size is specified
   # sd.survive = 0.075,    ## Not needed b/c met.size is specified
   lower.upper_survive = c(lower=0, upper=1),
   dispersal = 25,
   sd.dispersal = 10,
   lower.upper_dispersal = c(lower=10, upper=Inf),
   eps = 1,
   mu = 2,
   eta = 0.5,
   iterations = 10,
   seed = 123)

wpeterman/ssmc documentation built on Sept. 22, 2022, 8:37 a.m.