a bunch of modifications and fixes

[ape.git] / man / bd.ext.Rd

diff --git a/man/bd.ext.Rd b/man/bd.ext.Rd
index 2f246c9591c7bf6a917712e2fb0a14b883eefe24..f35236d14d92a953d0fdcaac0da38de2bf26ee69 100644 (file)
--- a/man/bd.ext.Rd
+++ b/man/bd.ext.Rd
@@ -3,11 +3,14 @@
 \title{Extended Version of the Birth-Death Models to Estimate Speciation
   and Extinction Rates}
 \usage{
-bd.ext(phy, S)
+bd.ext(phy, S, conditional = TRUE)
 }
 \arguments{
   \item{phy}{an object of class \code{"phylo"}.}
   \item{S}{a numeric vector giving the number of species for each tip.}
+  \item{conditional}{whether probabilities should be conditioned on no
+    extinction (mainly to compare results with previous analyses; see
+    details).}
 }
 \description{
   This function fits by maximum likelihood a birth-death model to the
@@ -32,12 +35,28 @@ bd.ext(phy, S)
   than the tip labels of \code{phy}, and a warning message is issued.
 
   Note that the function does not check that the tree is effectively
-  ultrametric, so if it is not, the returned result may not be meaningful.
+  ultrametric, so if it is not, the returned result may not be
+  meaningful.
+
+  If \code{conditional = TRUE}, the probabilities of the taxonomic data
+  are calculated conditioned on no extinction (Rabosky et al. 2007). In
+  previous versions of the present function (until ape 2.6-1),
+  unconditional probabilities were used resulting in underestimated
+  extinction rate. Though it does not make much sense to use
+  \code{conditional = FALSE}, this option is provided to compare results
+  from previous analyses: if the species richnesses are relatively low,
+  both versions will give similar results (see examples).
 }
 \references{
   Paradis, E. (2003) Analysis of diversification: combining phylogenetic
   and taxonomic data. \emph{Proceedings of the Royal Society of
     London. Series B. Biological Sciences}, \bold{270}, 2499--2505.
+
+  Rabosky, D. L., Donnellan, S. C., Talaba, A. L. and Lovette,
+  I. J. (2007) Exceptional among-lineage variation in diversification
+  rates during the radiation of Australia's most diverse vertebrate
+  clade. \emph{Proceedings of the Royal Society of London. Series
+  B. Biological Sciences}, \bold{274}, 2915-2923.
 }
 \author{Emmanuel Paradis}
 \seealso{
@@ -53,5 +72,6 @@ data(bird.orders)
 S <- c(10, 47, 69, 214, 161, 17, 355, 51, 56, 10, 39, 152,
        6, 143, 358, 103, 319, 23, 291, 313, 196, 1027, 5712)
 bd.ext(bird.orders, S)
+bd.ext(bird.orders, S, FALSE) # same than older versions
 }
 \keyword{models}