Maximization of the loglikelihood under the DAISIE model with clade-specific diversity-dependence

This function computes the maximum likelihood estimates of the parameters of the DAISIE model with clade-specific diversity-dependence and a shift in parameters for data from lineages colonizing an island. It also outputs the corresponding loglikelihood that can be used in model comparisons.

The result of sort(c(idparsopt, idparsfix, idparsnoshift)) should be identical to c(1:10). If not, an error is reported that the input is incoherent. The same happens when the length of initparsopt is different from the length of idparsopt, and the length of parsfix is different from the length of idparsfix.
Including the 11th parameter (p_f) in either idparsopt or idparsfix (and therefore initparsopt or parsfix) is optional. If this parameter is not specified, then the information in the data is used, otherwise the information in the data is overruled.

Usage

DAISIE_SR_ML_CS(
  datalist,
  initparsopt,
  idparsopt,
  parsfix,
  idparsfix,
  idparsnoshift = 6:10,
  res = 100,
  ddmodel = 0,
  cond = 0,
  island_ontogeny = NA,
  tol = c(1e-04, 1e-05, 1e-07),
  maxiter = 1000 * round((1.25)^length(idparsopt)),
  methode = "lsodes",
  optimmethod = "subplex",
  CS_version = 1,
  verbose = 0,
  tolint = c(1e-16, 1e-10),
  jitter = 0,
  num_cycles = 1
)

Arguments

datalist

Data object containing information on colonisation and branching times. This object can be generated using the DAISIE_dataprep function, which converts a user-specified data table into a data object, but the object can of course also be entered directly. It is an R list object with the following elements.
The first element of the list has two three components:

$island_age - the island age
Then, depending on whether a distinction between types is made, we have:
$not_present - the number of mainland lineages that are not present on the island

The remaining elements of the list each contains information on a single colonist lineage on the island and has 5 components:

$colonist_name - the name of the species or clade that colonized the island
$branching_times - island age and stem age of the population/species in the case of Non-endemic, Non-endemic_MaxAge and Endemic anagenetic species. For cladogenetic species these should be island age and branching times of the radiation including the stem age of the radiation.
$stac - the status of the colonist

* Non_endemic_MaxAge: 1
* Endemic: 2
* Endemic&Non_Endemic: 3
* Non_endemic: 4
* Endemic_MaxAge: 5

$missing_species - number of island species that were not sampled for particular clade (only applicable for endemic clades)

initparsopt

The initial values of the parameters that must be optimized

idparsopt

The ids of the parameters that must be optimized. The ids are defined as follows:

id = 1 corresponds to lambda^c (cladogenesis rate)
id = 2 corresponds to mu (extinction rate)
id = 3 corresponds to K (clade-level carrying capacity)
id = 4 corresponds to gamma (immigration rate)
id = 5 corresponds to lambda^a (anagenesis rate)
id = 6 corresponds to lambda^c (cladogenesis rate) after the shift
id = 7 corresponds to mu (extinction rate) after the shift
id = 8 corresponds to K (clade-level carrying capacity) after the shift
id = 9 corresponds to gamma (immigration rate) after the shift
id = 10 corresponds to lambda^a (anagenesis rate) after the shift
id = 11 corresponds to the time of shift

parsfix

The values of the parameters that should not be optimized

idparsfix

The ids of the parameters that should not be optimized, e.g. c(1,3) if lambda^c and K should not be optimized.

idparsnoshift

The ids of the parameters that should not be different before and after the shift.

res

Sets the maximum number of species for which a probability must be computed, must be larger than the size of the largest clade

ddmodel

Sets the model of diversity-dependence:

ddmodel = 0 : no diversity dependence
ddmodel = 1 : linear dependence in speciation rate
ddmodel = 11: linear dependence in speciation rate and in immigration rate
ddmodel = 2 : exponential dependence in speciation rate
ddmodel = 21: exponential dependence in speciation rate and in immigration rate.

cond

cond = 0 : conditioning on island age
cond = 1 : conditioning on island age and non-extinction of the island biota

island_ontogeny

type of island ontonogeny. If NA, then constant ontogeny is assumed.

tol

Sets the tolerances in the optimization. Consists of:
reltolx = relative tolerance of parameter values in optimization
reltolf = relative tolerance of function value in optimization
abstolx = absolute tolerance of parameter values in optimization.

maxiter

Sets the maximum number of iterations in the optimization.

methode

Method of the ODE-solver. See package deSolve for details. Default is "lsodes"

optimmethod

Method used in likelihood optimization. Default is "subplex" (see subplex package). Alternative is 'simplex' which was the method in previous versions.

CS_version

a numeric or list. Default is 1 for the standard DAISIE model, for a relaxed-rate model a list with the following elements:

model: the CS model to run, options are 1 for single rate DAISIE model, 2 for multi-rate DAISIE, or 0 for IW test model.
relaxed_par: the parameter to relax (integrate over). Options are "cladogenesis", "extinction", "carrying_capacity", "immigration", or "anagenesis".

verbose

sets whether parameters and likelihood should be printed (1) or not (0).

tolint

Vector of two elements containing the absolute and relative tolerance of the integration.

jitter

Numeric for optimizer(). Jitters the parameters being optimized by the specified amount which should be very small, e.g. 1e-5. Jitter when link[subplex]{subplex}() produces incorrect output due to parameter transformation.

num_cycles

The number of cycles the optimizer will go through. Default is 1.

Value

The output is a dataframe containing estimated parameters and maximum loglikelihood.

lambda_c: gives the maximum likelihood estimate of lambda^c, the rate of cladogenesis
mu: gives the maximum likelihood estimate of mu, the extinction rate
K: gives the maximum likelihood estimate of K, the carrying-capacity
gamma: gives the maximum likelihood estimate of gamma, the immigration rate
lambda_a: gives the maximum likelihood estimate of lambda^a, the rate of anagenesis
lambda_c2: gives the maximum likelihood estimate of lambda^c2, the rate of cladogenesis for the optional second group of species
mu2: gives the maximum likelihood estimate of mu2, the extinction rate for the optional second group of species
K2: gives the maximum likelihood estimate of K2, the carrying-capacity for the optional second group of species
gamma2: gives the maximum likelihood estimate of gamma2, the immigration rate for the optional second group of species
lambda_a2: gives the maximum likelihood estimate of lambda^a2, the rate of anagenesis for the optional second group of species
loglik: gives the maximum loglikelihood
df: gives the number of estimated parameters, i.e. degrees of feedom
conv: gives a message on convergence of optimization; conv = 0 means convergence

References

Valente, L.M., A.B. Phillimore and R.S. Etienne (2015). Equilibrium and non-equilibrium dynamics simultaneously operate in the Galapagos islands. Ecology Letters 18: 844-852. <DOI:10.1111/ele.12461>.

Author

Rampal S. Etienne

Examples


# \donttest{
## In all following DAISIE_ML calls very high tolerances and low system size
## are used  for fast computation for this example. Use default or better
## tol, tolint an res values in actual analyses.
##################
### When all species have the same rates, and we want to optimize all 5
### parameters, we use:
utils::data(Galapagos_datalist)
DAISIE_ML(
   datalist = Galapagos_datalist,
   initparsopt = c(2.5,2.7,20,0.009,1.01),
   ddmodel = 11,
   idparsopt = 1:5,
   parsfix = NULL,
   idparsfix = NULL,
   tol = c(0.1, 0.02, 0.01),
   tolint = c(1e-4, 1e-2),
   res = 50
)
#>   lambda_c       mu  K gamma lambda_a    loglik df conv
#> 1  2.15493 2.153129 20 0.009     1.01 -81.28596  5    0

### When all species have the same rates, and we want to optimize all parameters
# except K (which we set equal to Inf), we use:

utils::data(Galapagos_datalist)
DAISIE_ML(
   datalist = Galapagos_datalist,
   initparsopt = c(2.5,2.7,0.009,1.01),
   idparsopt = c(1,2,4,5),
   parsfix = Inf,
   idparsfix = 3,
   tol = c(0.1, 0.02, 0.01),
   tolint = c(1e-4, 1e-2),
   res = 50
   )
#>   lambda_c       mu   K gamma lambda_a    loglik df conv
#> 1 3.180506 3.172027 Inf 0.009     1.01 -73.14958  4    0

### When all species have the same rates except that the finches have a different
# rate of cladogenesis, and we want to optimize all parameters except K (which we
# set equal to Inf), fixing the proportion of finch-type species at 0.163, we use:

utils::data(Galapagos_datalist_2types)
DAISIE_ML(
   datalist = Galapagos_datalist_2types,
   initparsopt = c(0.38,0.55,0.004,1.1,2.28),
   idparsopt = c(1,2,4,5,6),
   parsfix = c(Inf,Inf,0.163),
   idparsfix = c(3,8,11),
   idparsnoshift = c(7,9,10),
   tol = c(0.1, 0.02, 0.01),
   tolint = c(1e-4, 1e-2),
   res = 50
   )
#>    lambda_c        mu   K       gamma lambda_a lambda_c2       mu2  K2
#> 1 0.3840537 0.6146573 Inf 0.003956464 1.193755  3.079965 0.6146573 Inf
#>        gamma2 lambda_a2 prop_type2    loglik df conv
#> 1 0.003956464  1.193755      0.163 -69.57021  5    0

### When all species have the same rates except that the finches have a different
# rate of cladogenesis, extinction and a different K, and we want to optimize all
# parameters, fixing the proportion of finch-type species at 0.163, we use:

utils::data(Galapagos_datalist_2types)
DAISIE_ML(
   datalist = Galapagos_datalist_2types,
   ddmodel = 11,
   initparsopt = c(0.19,0.09,0.002,0.87,20,8.9,15),
   idparsopt = c(1,2,4,5,6,7,8),
   parsfix = c(Inf,0.163),
   idparsfix = c(3,11),
   idparsnoshift = c(9,10),
   tol = c(0.1, 0.02, 0.01),
   tolint = c(1e-4, 1e-2),
   res = 50
   )
#>    lambda_c        mu   K       gamma lambda_a lambda_c2     mu2       K2
#> 1 0.2085388 0.1294331 Inf 0.002834096 1.115621  17.09695 6.32994 18.72603
#>        gamma2 lambda_a2 prop_type2    loglik df conv
#> 1 0.002834096  1.115621      0.163 -64.80759  7    0


### When all species have the same rates except that the finches have a different
# rate of extinction, and we want to optimize all parameters except K (which we
# set equal to Inf), and we also# want to estimate the fraction of finch species
# in the mainland pool. we use:

utils::data(Galapagos_datalist_2types)
DAISIE_ML(
   datalist = Galapagos_datalist_2types,
   initparsopt = c(2.48,2.7,0.009,1.01,2.25,0.163),
   idparsopt = c(1,2,4,5,7,11),
   parsfix = c(Inf,Inf),
   idparsfix = c(3,8),
   idparsnoshift = c(6,9,10),
   tol = c(0.1, 0.02, 0.01),
   tolint = c(1e-4, 1e-2),
   res = 50
   )
#>   lambda_c       mu   K       gamma lambda_a lambda_c2      mu2  K2      gamma2
#> 1  2.55745 3.239773 Inf 0.009729946 1.739499   2.55745 1.599674 Inf 0.009729946
#>   lambda_a2  prop_type2    loglik df conv
#> 1  1.739499 0.001157252 -71.91278  6    0

### When we have two islands with the same rates except for immigration and anagenesis rate,
# and we want to optimize all parameters, we use:

utils::data(Galapagos_datalist)
DAISIE_ML(
   datalist = list(Galapagos_datalist,Galapagos_datalist),
   datatype = 'multiple',
   initparsopt = c(2.5,2.7,20,0.009,1.01,0.009,1.01),
   idparsmat = rbind(1:5,c(1:3,6,7)),
   idparsopt = 1:7,
   parsfix = NULL,
   idparsfix = NULL,
   tol = c(0.1, 0.02, 0.01),
   tolint = c(1e-4, 1e-2),
   res = 50
)
#>   lambda_c       mu        K       gamma lambda_a    loglik df conv
#> 1   2.3754 2.276205 12.28802 0.008006759 1.223171 -147.3063  7    0
#> 2   2.3754 2.276205 12.28802 0.006590183 1.054042 -147.3063  7    0

### When we consider the four Macaronesia archipelagoes and set all parameters the same
# except for rates of cladogenesis, extinction and immigration for Canary Islands,
# rate of cladogenesis is fixed to 0 for the other archipelagoes,
# diversity-dependence is assumed to be absent
# and we want to optimize all parameters, we use:

utils::data(Macaronesia_datalist)
DAISIE_ML(
   datalist = Macaronesia_datalist,
   datatype = 'multiple',
   initparsopt = c(1.053151832,0.052148979,0.512939011,0.133766934,0.152763179),
   idparsmat = rbind(1:5,c(6,2,3,7,5),1:5,1:5),
   idparsopt = c(2,4,5,6,7),
   parsfix = c(0,Inf),
   idparsfix = c(1,3),
   tol = c(0.1, 0.02, 0.01),
   tolint = c(1e-4, 1e-2),
   res = 50
)
#>     lambda_c       mu   K      gamma lambda_a    loglik df conv
#> 1 0.00000000 1.053152 Inf 0.05214898 0.512939 -447.8626  5    0
#> 2 0.09497184 1.053152 Inf 0.15276318 0.512939 -447.8626  5    0
#> 3 0.00000000 1.053152 Inf 0.05214898 0.512939 -447.8626  5    0
#> 4 0.00000000 1.053152 Inf 0.05214898 0.512939 -447.8626  5    0

# }