Molecular Dating by Penalised Likelihood and Maximum... (original) (raw)

Description

chronos is the main function fitting a chronogram to a phylogenetic tree whose branch lengths are in number of substitution per sites.

makeChronosCalib is a tool to prepare data frames with the calibration points of the phylogenetic tree.

chronos.control creates a list of parameters to be passed to chronos.

Usage

chronos(phy, lambda = 1, model = "correlated", quiet = FALSE,
        calibration = makeChronosCalib(phy),
        control = chronos.control())
## S3 method for class 'chronos'
print(x, ...)
makeChronosCalib(phy, node = "root", age.min = 1,
   age.max = age.min, interactive = FALSE, soft.bounds = FALSE)
chronos.control(...)

Arguments

phy	an object of class "phylo".
lambda	value of the smoothing parameter.
model	a character string specifying the model of substitution rate variation among branches. The possible choices are: “correlated”, “relaxed”, “discrete”, “clock”, or an unambiguous abbreviation of these.
quiet	a logical value; by default the calculation progress are displayed.
calibration	a data frame (see details).
control	a list of parameters controlling the optimisation procedure (see details).
x	an object of class c("chronos", "phylo").
node	a vector of integers giving the node numbers for which a calibration point is given. The default is a short-cut for the root.
age.min, age.max	vectors of numerical values giving the minimum and maximum ages of the nodes specified in node.
interactive	a logical value. If TRUE, then phy is plotted and the user is asked to click close to a node and enter the ages on the keyboard.
soft.bounds	(currently unused)
...	in the case of chronos.control: one of the five parameters controlling optimisation (unused in the case ofprint.chronos).

Details

chronos replaces chronopl but with a different interface and some extensions (see References).

The known dates (argument calibration) must be given in a data frame with the following column names: node, age.min, age.max, and soft.bounds (the last one is yet unused). For each row, these are, respectively: the number of the node in the “phylo” coding standard, the minimum age for this node, the maximum age, and a logical value specifying whether the bounds are soft. If age.min = age.max, this means that the age is exactly known. This data frame can be built withmakeChronosCalib which returns by default a data frame with a single row giving age = 1 for the root. The data frame can be built interactively by clicking on the plotted tree.

The argument control allows one to change some parameters of the optimisation procedure. This must be a list with names. The available options with their default values are:

tol = 1e-8: tolerance for the estimation of the substitution rates.
iter.max = 1e4: the maximum number of iterations at each optimization step.
eval.max = 1e4: the maximum number of function evaluations at each optimization step.
nb.rate.cat = 10: the number of rate categories if model = "discrete" (set this parameter to 1 to fit a strict clock model).
dual.iter.max = 20: the maximum number of alternative iterations between rates and dates.
epsilon = 1e-6: the convergence diagnostic criterion.

Using model = "clock" is actually a short-cut to model = "discrete" and setting nb.rate.cat = 1 in the list passed tocontrol.

The command chronos.control() returns a list with the default values of these parameters. They may be modified by passing them to this function, or directly in the list.

Value

chronos returns an object of class c("chronos", "phylo"). There is a print method for it. There are additional attributes which can be visualised with str or extracted withattr.

makeChronosCalib returns a data frame.

chronos.control returns a list.

Author(s)

Emmanuel Paradis, Santiago Claramunt, Guillaume Louvel

References

Kim, J. and Sanderson, M. J. (2008) Penalized likelihood phylogenetic inference: bridging the parsimony-likelihood gap. Systematic Biology, 57, 665–674.

Paradis, E. (2013) Molecular dating of phylogenies by likelihood methods: a comparison of models and a new information criterion. Molecular Phylogenetics and Evolution, 67, 436–444.

Sanderson, M. J. (2002) Estimating absolute rates of molecular evolution and divergence times: a penalized likelihood approach. Molecular Biology and Evolution, 19, 101–109.

Examples

library(ape)
tr <- rtree(10)
### the default is the correlated rate model:
chr <- chronos(tr)
### strict clock model:
ctrl <- chronos.control(nb.rate.cat = 1)
chr.clock <- chronos(tr, model = "discrete", control = ctrl)
### How different are the rates?
attr(chr, "rates")
attr(chr.clock, "rates")
## Not run: 
cal <- makeChronosCalib(tr, interactive = TRUE)
cal
### if you made mistakes, you can edit the data frame with:
### fix(cal)
chr <- chronos(tr, calibration = cal)

## End(Not run)