# chronos

##### Molecular Dating by Penalised Likelihood and Maximum Likelihood

`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`

.

- Keywords
- models

##### Usage

```
chronos(phy, lambda = 1, model = "correlated", quiet = FALSE,
calibration = makeChronosCalib(phy),
control = chronos.control())
# S3 method for 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'', 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.

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.

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

##### Examples

```
# NOT RUN {
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)
# }
```

*Documentation reproduced from package ape, version 4.1, License: GPL (>= 2)*