3 \alias{makeChronosCalib}
4 \alias{chronos.control}
6 \title{Molecular Dating by Penalised Likelihood and Maximum Likelihood}
8 \code{chronos} is the main function fitting a chronogram to a
9 phylogenetic tree whose branch lengths are in number of substitution
12 \code{makeChronosCalib} is a tool to prepare data frames with the
13 calibration points of the phylogenetic tree.
15 \code{chronos.control} creates a list of parameters to be passed
19 chronos(phy, lambda = 1, model = "correlated", quiet = FALSE,
20 calibration = makeChronosCalib(phy),
21 control = chronos.control())
22 \method{print}{chronos}(x, ...)
23 makeChronosCalib(phy, node = "root", age.min = 1,
24 age.max = age.min, interactive = FALSE, soft.bounds = FALSE)
28 \item{phy}{an object of class \code{"phylo"}.}
29 \item{lambda}{value of the smoothing parameter.}
30 \item{model}{a character string specifying the model of substitution
31 rate variation among branches. The possible choices are:
32 ``correlated'', ``relaxed'', ``discrete'', or an unambiguous
33 abbreviation of these.}
34 \item{quiet}{a logical value; by default the calculation progress are
36 \item{calibration}{a data frame (see details).}
37 \item{control}{a list of parameters controlling the optimisation
38 procedure (see details).}
39 \item{x}{an object of class \code{c("chronos", "phylo")}.}
40 \item{node}{a vector of integers giving the node numbers for which a
41 calibration point is given. The default is a short-cut for the
43 \item{age.min, age.max}{vectors of numerical values giving the minimum
44 and maximum ages of the nodes specified in \code{node}.}
45 \item{interactive}{a logical value. If \code{TRUE}, then \code{phy} is
46 plotted and the user is asked to click close to a node and enter the
47 ages on the keyboard.}
48 \item{soft.bounds}{(currently unused)}
49 \item{\dots}{in the case of \code{chronos.control}: one of the five
50 parameters controlling optimisation (unused in the case of
51 \code{print.chronos}).}
54 \code{chronos} replaces \code{chronopl} but with a different interface
55 and some extensions (see References).
57 The known dates (argument \code{calibration}) must be given in a data
58 frame with the following column names: node, age.min, age.max, and
59 soft.bounds (the last one is yet unused). For each row, these are,
60 respectively: the number of the node in the ``phylo'' coding standard,
61 the minimum age for this node, the maximum age, and a logical value
62 specifying whether the bounds are soft. If age.min = age.max, this
63 means that the age is exactly known. This data frame can be built with
64 \code{makeChronosCalib} which returns by default a data frame with a
65 single row giving age = 1 for the root. The data frame can be built
66 interactively by clicking on the plotted tree.
68 The argument \code{control} allows one to change some parameters of
69 the optimisation procedure. This must be a list with names. The
70 available options with their default values are:
73 \item{tol = 1e-8: }{tolerance for the estimation of the substitution
75 \item{iter.max = 1e4: }{the maximum number of iterations at each
77 \item{eval.max = 1e4: }{the maximum number of function evaluations at
78 each optimization step.}
79 \item{nb.rate.cat = 10: }{the number of rate categories if \code{model
80 = "discrete"} (set this parameter to 1 to fit a strict clock
82 \item{dual.iter.max = 20: }{the maximum number of alternative
83 iterations between rates and dates.}
86 The command \code{chronos.control()} returns a list with the default
87 values of these parameters. They may be modified by passing them to
88 this function, or directly in the list.
91 \code{chronos} returns an object of class \code{c("chronos",
92 "phylo")}. There is a print method for it. There are additional
93 attributes which can be visualised with \code{str} or extracted with
96 \code{makeChronosCalib} returns a data frame.
98 \code{chronos.control} returns a list.
101 Kim, J. and Sanderson, M. J. (2008) Penalized likelihood phylogenetic
102 inference: bridging the parsimony-likelihood gap. \emph{Systematic
103 Biology}, \bold{57}, 665--674.
105 Paradis, E. (2012) Molecular dating of phylogenies by likelihood
106 methods: a comparison of models and a new information
107 criterion. \emph{Manuscript}.
109 Sanderson, M. J. (2002) Estimating absolute rates of molecular
110 evolution and divergence times: a penalized likelihood
111 approach. \emph{Molecular Biology and Evolution}, \bold{19},
114 \author{Emmanuel Paradis}
116 \code{\link{chronoMPL}}
120 ### the default is the correlated rate model:
122 ### strict clock model:
123 ctrl <- chronos.control(nb.rate.cat = 1)
124 chr.clock <- chronos(tr, model = "discrete", control = ctrl)
125 ### How different are the rates?
127 attr(chr.clock, "rates")
129 cal <- makeChronosCalib(tr, interactive = TRUE)
131 ### if you made mistakes, you can edit the data frame with:
133 chr <- chronos(tr, calibration = cal)