chronos {ape}

Molecular Dating by Penalised Likelihood and Maximum Likelihood

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 of print.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 with makeChronosCalib 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 to control.

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 with attr.

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.

See Also

chronoMPL

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)