https://github.com/cran/ape
Tip revision: 4498162033af49c3fcc98e830182872d87c783fd authored by Emmanuel Paradis on 22 October 2011, 00:00:00 UTC
version 2.8
version 2.8
Tip revision: 4498162
bd.time.Rd
\name{bd.time}
\alias{bd.time}
\title{Time-Dependent Birth-Death Models}
\description{
This function fits a used-defined time-dependent birth-death
model.
}
\usage{
bd.time(phy, birth, death, BIRTH = NULL, DEATH = NULL,
ip, lower, upper, fast = FALSE, boot = 0, trace = 0)
}
\arguments{
\item{phy}{an object of class \code{"phylo"}.}
\item{birth}{either a numeric (if speciation rate is assumed
constant), or a (vectorized) function specifying how the birth
(speciation) probability changes through time (see details).}
\item{death}{id. for extinction probability.}
\item{BIRTH}{(optional) a vectorized function giving the primitive
of \code{birth}.}
\item{DEATH}{id. for \code{death}.}
\item{ip}{a numeric vector used as initial values for the estimation
procedure. If missing, these values are guessed.}
\item{lower, upper}{the lower and upper bounds of the parameters. If
missing, these values are guessed too.}
\item{fast}{a logical value specifying whether to use faster
integration (see details).}
\item{boot}{the number of bootstrap replicates to assess the
confidence intervals of the parameters. Not run by default.}
\item{trace}{an integer value. If non-zero, the fitting procedure is
printed every \code{trace} steps. This can be helpful if convergence
is particularly slow.}
}
\details{
Details on how to specify the birth and death functions and their
primitives can be found in the help page of \code{\link{yule.time}}.
The model is fitted by minimizing the least squares deviation between
the observed and the predicted distributions of branching times. These
computations rely heavily on numerical integrations. If \code{fast =
FALSE}, integrations are done with R's \code{\link[stats]{integrate}}
function. If \code{fast = TRUE}, a faster but less accurate function
provided in \pkg{ape} is used. If fitting a complex model to a large
phylogeny, a strategy might be to first use the latter option, and
then to use the estimates as starting values with \code{fast = FALSE}.
}
\value{
A list with the following components:
\itemize{
\item{par}{a vector of estimates with names taken from the parameters
in the specified functions.}
\item{SS}{the minimized sum of squares.}
\item{convergence}{output convergence criterion from
\code{\link[stats]{nlminb}}.}
\item{message}{id.}
\item{iterations}{id.}
\item{evaluations}{id.}
}}
\references{
Paradis, E. (2011) Time-dependent speciation and extinction from
phylogenies: a least squares approach. \emph{Evolution}, \bold{65},
661--672.
}
\author{Emmanuel Paradis}
\seealso{
\code{\link{ltt.plot}}, \code{\link{birthdeath}},
\code{\link{yule.time}}
}
\examples{
set.seed(3)
tr <- rbdtree(0.1, 0.02)
bd.time(tr, 0, 0) # fits a simple BD model
bd.time(tr, 0, 0, ip = c(.1, .01)) # 'ip' is useful here
## the classic logistic:
birth.logis <- function(a, b) 1/(1 + exp(-a*t - b))
\dontrun{
bd.time(tr, birth.logis, 0, ip = c(0, -2, 0.01))
## slow to get:
## $par
## a b death
## -0.003486961 -1.995983179 0.016496454
##
## $SS
## [1] 20.73023
}
}