man/chronos.Rd

   1 \name{chronos}
   2 \alias{chronos}
   3 \alias{makeChronosCalib}
   4 \alias{chronos.control}
   5 \alias{print.chronos}
   6 \title{Molecular Dating by Penalised Likelihood and Maximum Likelihood}
   7 \description{
   8   \code{chronos} is the main function fitting a chronogram to a
   9   phylogenetic tree whose branch lengths are in number of substitution
  10   per sites.
  11
  12   \code{makeChronosCalib} is a tool to prepare data frames with the
  13   calibration points of the phylogenetic tree.
  14
  15   \code{chronos.control} creates a list of parameters to be passed
  16   to \code{chronos}.
  17 }
  18 \usage{
  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)
  25 chronos.control(...)
  26 }
  27 \arguments{
  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
  35     displayed.}
  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
  42     root.}
  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}).}
  52 }
  53 \details{
  54   \code{chronos} replaces \code{chronopl} but with a different interface
  55   and some extensions (see References).
  56
  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.
  67
  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:
  71
  72   \itemize{
  73     \item{tol = 1e-8: }{tolerance for the estimation of the substitution
  74       rates.}
  75     \item{iter.max = 1e4: }{the maximum number of iterations at each
  76       optimization step.}
  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
  81       model).}
  82     \item{dual.iter.max = 20: }{the maximum number of alternative
  83       iterations between rates and dates.}
  84   }
  85
  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.
  89 }
  90 \value{
  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
  94   \code{attr}.
  95
  96   \code{makeChronosCalib} returns a data frame.
  97
  98   \code{chronos.control} returns a list.
  99 }
 100 \references{
 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.
 104
 105   Paradis, E. (2013) Molecular dating of phylogenies by likelihood
 106   methods: a comparison of models and a new information
 107   criterion. \emph{Molecular Phylogenetics and Evolution}, in press.
 108
 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},
 112   101--109.
 113 }
 114 \author{Emmanuel Paradis}
 115 \seealso{
 116   \code{\link{chronoMPL}}
 117 }
 118 \examples{
 119 tr <- rtree(10)
 120 ### the default is the correlated rate model:
 121 chr <- chronos(tr)
 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?
 126 attr(chr, "rates")
 127 attr(chr.clock, "rates")
 128 \dontrun{
 129 cal <- makeChronosCalib(tr, interactive = TRUE)
 130 cal
 131 ### if you made mistakes, you can edit the data frame with:
 132 ### fix(cal)
 133 chr <- chronos(tr, calibration = cal)
 134 }
 135 }
 136 \keyword{models}