R/default_params_doc.R

In xieshu95/Trait_dependent_TraiSIE: Dynamical Assembly of Islands by Speciation, Immigration and Extinction

#' Defailt parameter documentation
#'
#' @param 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.\cr The first element of the list has two three
#' components: \cr \cr \code{$island_age} - the island age \cr Then, depending
#' on whether a distinction between types is made, we have:\cr
#' \code{$not_present} - the number of mainland lineages that are not present
#' on the island \cr or:\cr \code{$not_present_type1} - the number of mainland
#' lineages of type 1 that are not present on the island \cr
#' \code{$not_present_type2} - the number of mainland lineages of type 2 that
#' are not present on the island \cr \cr The remaining elements of the list
#' each contains information on a single colonist lineage on the island and has
#' 5 components:\cr \cr \code{$colonist_name} - the name of the species or
#' clade that colonized the island \cr \code{$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.\cr \code{$stac} - the status of the colonist
#' \cr \cr * Non_endemic_MaxAge: 1 \cr * Endemic: 2 \cr * Endemic&Non_Endemic:
#' 3 \cr * Non_Endemic: 4 \cr * Endemic_Singleton_MaxAge: 5 \cr *
#' Endemic_Clade_MaxAge: 6 \cr * Endemic&Non_Endemic_Clade_MaxAge: 7 \cr \cr
#' \code{$missing_species} - number of island species that were not sampled for
#' particular clade (only applicable for endemic clades) \cr \code{$type1or2} -
#' whether the colonist belongs to type 1 or type 2 \cr
#' @param datatype Sets the type of data: 'single' for a single island or
#' archipelago treated as one, and 'multiple' for multiple archipelagoes
#' potentially sharing the same parameters
#' @param initparsopt The initial values of the parameters that must be
#' optimized
#' @param idparsopt The ids of the parameters that must be optimized. The ids
#' are defined as follows: \cr \cr id = 1 corresponds to lambda^c (cladogenesis
#' rate) \cr id = 2 corresponds to mu (extinction rate) \cr id = 3 corresponds
#' to K (clade-level carrying capacity) \cr id = 4 corresponds to gamma
#' (immigration rate) \cr id = 5 corresponds to lambda^a (anagenesis rate) \cr
#' id = 6 corresponds to lambda^c (cladogenesis rate) for an optional subset of
#' the species \cr id = 7 corresponds to mu (extinction rate) for an optional
#' subset of the species\cr id = 8 corresponds to K (clade-level carrying
#' capacity) for an optional subset of the species\cr id = 9 corresponds to
#' gamma (immigration rate) for an optional subset of the species\cr id = 10
#' corresponds to lambda^a (anagenesis rate) for an optional subset of the
#' species\cr id = 11 corresponds to p_f (fraction of mainland species that
#' belongs to the second subset of species
#' @param 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.
#' @param parsfix The values of the parameters that should not be optimized
#' @param idparsnoshift For datatype = 'single' only: The ids of the parameters
#' that should not be different between two groups of species; This can only
#' apply to ids 6:10, e.g. idparsnoshift = c(6,7) means that lambda^c and mu
#' have the same values for both groups
#' @param idparsmat For datatype = 'multiple' only: Matrix containing the ids
#' of the parameters, linking them to initparsopt and parsfix. Per island
#' system we use the following order: \cr \cr * lac = (initial) cladogenesis
#' rate \cr * mu = extinction rate \cr * K = maximum number of species possible
#' in the clade \cr * gam = (initial) immigration rate \cr * laa = (initial)
#' anagenesis rate \cr Example: idparsmat = rbind(c(1,2,3,4,5),c(1,2,3,6,7))
#' has different rates of immigration and anagenesis for the two islands.
#' @param res Sets the maximum number of species for which a probability must
#' be computed, must be larger than the size of the largest clade
#' @param ddmodel Sets the model of diversity-dependence: \cr \cr ddmodel = 0 :
#' no diversity dependence \cr ddmodel = 1 : linear dependence in speciation
#' rate \cr ddmodel = 11: linear dependence in speciation rate and in
#' immigration rate \cr ddmodel = 2 : exponential dependence in speciation
#' rate\cr ddmodel = 21: exponential dependence in speciation rate and in
#' immigration rate\cr
#' @param cond cond = 0 : conditioning on island age \cr cond = 1 :
#' conditioning on island age and non-extinction of the island biota \cr
#' @param island_ontogeny type of island ontonogeny. A string describing the 
#' type of island ontogeny. If NA, then constant ontogeny is assumed.Can 
#' be \code{"const"}, \code{"beta"}.
#' @param eqmodel Sets the equilibrium constraint that can be used during the
#' likelihood optimization. Only available for datatype = 'single'.\cr\cr
#' eqmodel = 0 : no equilibrium is assumed \cr eqmodel = 13 : near-equilibrium
#' is assumed on endemics using deterministic equation for endemics and
#' immigrants. Endemics must be within x_E of the equilibrium value\cr eqmodel
#' = 15 : near-equilibrium is assumed on endemics and immigrants using
#' deterministic equation for endemics and immigrants. Endemics must be within
#' x_E of the equilibrium value, while non-endemics must be within x_I of the
#' equilibrium value
#' @param x_E Sets the fraction of the equlibrium endemic diversity above which
#' the endemics are assumed to be in equilibrium; only active for eqmodel = 13
#' or 15
#' @param x_I Sets the fraction of the equlibrium non-endemic diversity above
#' which the system is assumed to be in equilibrium; only active for eqmodel =
#' 15
#' @param tol Sets the tolerances in the optimization. Consists of: \cr reltolx
#' = relative tolerance of parameter values in optimization \cr reltolf =
#' relative tolerance of function value in optimization \cr abstolx = absolute
#' tolerance of parameter values in optimization
#' @param maxiter Sets the maximum number of iterations in the optimization
#' @param methode Method of the ODE-solver. See package deSolve for details.
#' Default is "lsodes"
#' @param optimmethod Method used in likelihood optimization. Default is
#' "subplex" (see subplex package). Alternative is 'simplex' which was the
#' method in previous versions.
#' @param CS_version For internal testing purposes only. Default is 1, the
#' original DAISIE code.
#' @param verbose sets whether parameters and likelihood should be printed (1)
#' or not (0)
#' @param tolint Vector of two elements containing the absolute and relative
#' tolerance of the integration
#' @param time Length of the simulation in time units. For examples, if an
#' island is known to be 4 million years old, setting time = 4 will simulate 
#' the entire life span of the island; setting time = 2 will stop the 
#' simulation at the mid-life of the island.
#' @param M The size of mainland pool, i.e. the number of species that can 
#' potentially colonize the island.
#' @param pars Contains the model parameters: \cr \cr \code{pars[1]}
#' corresponds to lambda^c (cladogenesis rate) \cr \code{pars[2]} corresponds
#' to mu (extinction rate) \cr \code{pars[3]} corresponds to K (clade-level
#' carrying capacity). Set K=Inf for non-diversity dependence.\cr
#' \code{pars[4]} corresponds to gamma (immigration rate) \cr \code{pars[5]}
#' corresponds to lambda^a (anagenesis rate) \cr \code{pars[6]} corresponds to
#' lambda^c (cladogenesis rate) for type 2 species \cr \code{pars[7]}
#' corresponds to mu (extinction rate) for type 2 species\cr \code{pars[8]}
#' corresponds to K (clade-level carrying capacity) for type 2 species.  Set
#' K=Inf for non-diversity dependence.\cr \code{pars[9]} corresponds to gamma
#' (immigration rate) for type 2 species\cr \code{pars[10]} corresponds to
#' lambda^a (anagenesis rate) for type 2 species\cr The elements 6:10 are
#' optional and are required only when type 2 species are included.
#' @param replicates Number of island replicates to be simulated.
#' @param mainland_params mainland_params parameters for simulation mainland 
#' processes. If NULL, the mainland is assumed to be static, following the 
#' assumptions of Valente et al., 2015.
#' @param divdepmodel Option divdepmodel = 'CS' runs a model with clade-specific 
#' carrying capacity, where diversity-dependence operates only within single 
#' clades, i.e. only among species originating from the same mainland colonist.
#' Option divdepmodel = 'IW' runs a model with island-wide carrying capacity,
#' where diversity-dependence operates within and among clades.
#' @param prop_type2_pool Fraction of mainland species that belongs to the
#' second subset of species (type 2). Applies only when two types of species
#' are simulated (length(pars) = 10).
#' @param replicates_apply_type2 Applies only when two types of species are
#' being simulated. Default replicates_apply_type2 = TRUE runs simulations 
#' until the number of islands where a type 2 species has colonised is equal to
#' the specified number of replicates. This is recommended if prop_type2_pool
#' is small of if the rate of immigration of type two species (pars[9]) is low,
#' meaning that more replicates are needed to achieved an adequate sample size
#' of islands with type 2 species. Setting replicates_apply_type2 = FALSE
#' simulates islands up to the specified number of replicates regardless of 
#' whether type 2 species have colonised or not.
#' @param sample_freq Specifies the number of units times should be divided by
#' for plotting purposes. Larger values will lead to plots with higher 
#' resolution, but will also run slower.
#' @param ddmodel_sim A numeric which sets the model of diversity-depedence when
#' running simulations.
#' @param island_type oceanic or non-oceanic island
#' @param nonoceanic parameters for non-oceanic island model
#' @param plot_sims Default = TRUE plots species-through-time (STT) plots.
#' @param Apars A numeric vector:
#' \itemize{
#'   \item{[1]: maximum area}
#'   \item{[2]: vale from 0 to 1 indicating where in the island's history the
#'   peak area is achieved}
#'   \item{[3]: sharpness of peak}
#'   \item{[4]: total island age}
#' }
#' @param Epars A numeric vector:
#' \itemize{
#'   \item{[1]: minimum extinction when area is at peak}
#'   \item{[2]: extinction rate when current area is 0.10 of maximum area}
#' }
#' @param Tpars A named list containing diversification rates considering two trait states:
#' \itemize{
#'   \item{[1]:A numeric with the per capita transition rate with state1}
#'   \item{[2]:A numeric with the per capita immigration rate with state2}
#'   \item{[3]:A numeric with the per capita extinction rate with state2}
#'   \item{[4]:A numeric with the per capita anagenesis rate with state2}
#'   \item{[5]:A numeric with the per capita cladogenesis rate with state2}
#'   \item{[6]:A numeric with the per capita transition rate with state2} 
#'   \item{[7]:A carrying capacity with trait state 2 on mainland}
#'   \item{[8]:A numeric with the number of species with trait state 2 on mainland} 
#' }
#' @param keep_final_state logical indicating if final state of simulation 
#' should be returned. Default is \code{FALSE}.
#' @param stored_data output of DAISIE_sim function when run with 
#' keep_final_state. If not \code{NULL}.
#' @param island_replicates Island replicates in DAISIE format (produced in
#'   \code{\link{DAISIE_sim}} with \code{format = TRUE} option). Minimally, this must be 
#'   a list, that has as much elements as replicates. Each element must be a
#'   list with the elements \code{island_age}, \code{not_present} 
#'   and \code{stt_all}. \code{stt_all} must be a data frame with
#'   the column names \code{Time}, \code{nI}, \code{nA}, \code{nC} 
#'   and \code{present}.
#'
#' @return Nothing
#'
default_params_doc <- function(
  datalist,
  datatype,
  initparsopt,
  idparsopt,
  parsfix,
  idparsfix,
  idparsnoshift,
  idparsmat,
  res,
  ddmodel,
  cond,
  island_ontogeny,
  eqmodel,
  x_E,
  x_I,
  tol,
  maxiter,
  methode,
  optimmethod,
  CS_version,
  verbose,
  tolint,
  time,
  M,
  pars,
  replicates, 
  mainland_params, 
  divdepmodel,
  prop_type2_pool, 
  replicates_apply_type2, 
  sample_freq,
  ddmodel_sim,
  island_type,
  nonoceanic,
  plot_sims,
  Apars,
  Epars,
  Tpars,
  keep_final_state,
  stored_data,
  island_replicates
) {
  # Nothing
}