mss_cedp: Likelihood approach for estimating colonization/extinction...

In island: Stochastic Island Biogeography Theory Made Easy

Likelihood approach for estimating colonization/extinction with perfect or imperfect detectability

Description

mss_cedp conducts maximum likelihood estimation of colonization/extinction parameters of different data sets. This function can handle imperfect detectability and missing data defining a heterogeneous sampling structure across input data matrix rows.

Usage

mss_cedp(
  Data,
  Time,
  Factor,
  Tags,
  Colonization = 1,
  Extinction = 1,
  Detectability_Value = 0.5,
  Phi_Time_0_Value = 0.5,
  Tol = 1e-08,
  MIT = 100,
  C_MAX = 10,
  C_min = 0,
  E_MAX = 10,
  E_min = 0,
  D_MAX = 0.99,
  D_min = 0,
  P_MAX = 0.99,
  P_min = 0.01,
  I_0 = 0,
  I_1 = 1,
  I_2 = 2,
  I_3 = 3,
  z = 2,
  Minimization = 1,
  Verbose = 0,
  MV_FLAG = 0.1,
  PerfectDetectability = TRUE
)

Arguments

Data	data frame containing presence data per time (in cols) and sites (in rows)
Time	an array of length n containing increasing sampling times
Factor	column number containing the 'data frame' factor used to split total data into level-based groups
Tags	array of names (one short for each level of the factor analyzed)
Colonization	guess value to initiate search / parameter value
Extinction	guess value to initiate search / parameter value
Detectability_Value	guess value to initiate search / parameter value
Phi_Time_0_Value	guess value to initiate search / parameter value
Tol	stopping criteria of the search algorithm.
MIT	max number of iterations of the search algorithm.
C_MAX	max value for the possible range of colonization values
C_min	min value for the possible range of colonization values
E_MAX	max value for the possible range of colonization values
E_min	min value for the possible range of colonization values
D_MAX	max value for the possible range of colonization values
D_min	min value for the possible range of colonization values
P_MAX	max value for the possible range of colonization values
P_min	min value for the possible range of colonization values
I_0	has to be 0 or 1. Defaults to 0
I_1	has to be 0 or 1. Defaults to 1
I_2	has to be 0, 1, 2, or 3. Defaults to 2
I_3	has to be 0, 1, 2, or 3. Defaults to 3
z	dimension of the parameter subspace for which the optimization process will take place. Defaults to 2
Minimization,	1/0. If Minimization is 0, then no minimization is performed.
Verbose	more/less (1/0) information about the optimization algorithm will be printed out.
MV_FLAG	missing Value Flag (to specify sites and times where no sample exists)
PerfectDetectability	TRUE means 'Perfect Detectability'. Of course, FALSE means 'Imperfect Detectability'

Details

The input is a data frame containing presence data per time (in cols). Different factors (for instance, OTU, location, etc) can slide the initial data frame accordingly. Model parameters will be estimated for each of these groups independently that correspond to each level of the chosen factor. If Minimization is 0, then no maximum likelihood estimation is performed and only the likelihood evaluation at the input model parameter values is returned. Searches are based on the Nelder-Mead simplex method, but conducted in a bounded parameter space which means that in case a neg loglikelihood (NLL) evaluation is called out from these boundaries, the returned value for this NLL evaluation is artifically given as the maximum number the machine can hold. Each group is named by a short-length-character label (ideally, 3 or 4 characters). All labels should have the same character length to fulfill memmory alignment requirements of the shared object called by .C(...) function. I_0, I_1, I_2, I_3 are model parameter keys. They are used to define a 4D-vector (Index). The search will take place on the full parameter space defined by model parameters (I_0, I_1) if PefectDetectability is TRUE or, alternatively, defined by (I_0, I_1, I_2, I_3) if PerfectDetectability is FALSE. Model parameter keys correspond to colonization (0), extinction (1), detectability (2), and P_0 (3) model parameters. For instance, if (I_0, I_1) is (1, 0), the search will take place whitin the paremeter space defined by extinction, as the first axis, and colonization, as the second.

Value

The function generates, as an output, either a 3-column matrix (Colonization, Extinction, Negative LogLikelihood) or 5-column matrix (Colonization, Extinction, Detectability, P_0, Negative LogLikelihood), depending on the value of the input parameter PerfectDetectability (either TRUE or FALSE).

Examples

Data <- lakshadweepPLUS[[1]]
Guild_Tag = c("Alg", "Cor", "Mac", "Mic", "Omn", "Pis", "Zoo")
Time <- as.vector(c(2000, 2000, 2001, 2001, 2001, 2001, 2002, 2002, 2002,
2002, 2003, 2003, 2003, 2003, 2010, 2010, 2011, 2011, 2011, 2011, 2012,
2012, 2012, 2012, 2013, 2013, 2013, 2013))
R <- mss_cedp(Data, Time, Factor = 3, Tags = Guild_Tag,
PerfectDetectability = FALSE, z = 4)
Guild_Tag = c("Agt", "Kad", "Kvt")
R <- mss_cedp(Data, Time, Factor = 2, Tags = Guild_Tag,
PerfectDetectability = FALSE, z = 4)

island documentation built on Jan. 23, 2023, 5:30 p.m.