R: Molecular Dating by Penalised Likelihood and Maximum...

chronos {ape} | R Documentation

## 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)

[Package ape version 5.6 Index]