many changes!

[ape.git] / man / rTraitCont.Rd

diff --git a/man/rTraitCont.Rd b/man/rTraitCont.Rd
index 01d82e2bb60c936342b31872d53ba31101c8c487..6ff347846cad82bbb8a98139980b18864bb18dc2 100644 (file)
--- a/man/rTraitCont.Rd
+++ b/man/rTraitCont.Rd
@@ -2,8 +2,8 @@
 \alias{rTraitCont}
 \title{Continuous Character Simulation}
 \usage{
-rTraitCont(phy, model = "BM", sigma = 0.1, alpha = 1,
-           theta = 0, ancestor = FALSE, root.value = 0)
+rTraitCont(phy, model = "BM", sigma = 0.1, alpha = 1, theta = 0,
+           ancestor = FALSE, root.value = 0, linear = TRUE)
 }
 \arguments{
   \item{phy}{an object of class \code{"phylo"}.}
@@ -20,6 +20,8 @@ rTraitCont(phy, model = "BM", sigma = 0.1, alpha = 1,
     values at the nodes as well (by default, only the values at the tips
     are returned).}
   \item{root.value}{a numeric giving the value at the root.}
+  \item{linear}{a logical indicating which parameterisation of the OU
+    model to use (see details).}
 }
 \description{
   This function simulates the evolution of a continuous character along a
@@ -41,18 +43,28 @@ rTraitCont(phy, model = "BM", sigma = 0.1, alpha = 1,
   \item{\code{"OU"}:}{an Ornstein-Uhlenbeck model is used. The above
   indexing rule is used for the three parameters \code{sigma},
   \code{alpha}, and \code{theta}. This may be more interesting for the
-  last one to model varying phenotypic optima. Be careful that large
-  values of \code{alpha} may give unrealistic output.}
+  last one to model varying phenotypic optima.
+
+  By default the following formula is used:
+
+  \deqn{x_{t''} = x_{t'} - \alpha l (x_{t'} - \theta) + \sigma
+    l \epsilon}{x(t'') = x(t') - alpha l (x(t') - theta) + sigma
+    l epsilon}
+
+  where \eqn{l (= t'' - t')} is the branch length, and \eqn{\epsilon
+  \sim N(0, 1)}{\epsilon ~ N(0, 1)}. If \eqn{\alpha > 1}{alpha > 1},
+  this may lead to chaotic oscillations. Thus an alternative
+  parameterisation is used if \code{linear = FALSE}:
+
+  \deqn{x_{t''} = x_{t'} - (1 - exp(-\alpha l)) * (x_{t'} - \theta) +
+    \sigma l \epsilon}{x(t'') = x(t') - (1 - exp(-alpha l)) * (x(t') -
+    theta) + sigma l epsilon}}
 
   \item{A function:}{it must be of the form \code{foo(x, l)} where
   \code{x} is the trait of the ancestor and \code{l} is the branch
   length. It must return the value of the descendant. The arguments
   \code{sigma}, \code{alpha}, and \code{theta} are ignored.}
 }}
-\note{
-  Currently, the OU model is a bit difficult to tune. Hopefully, this
-  may be improved in the future.
-}
 \value{
   A numeric vector with names taken from the tip labels of
   \code{phy}. If \code{ancestor = TRUE}, the node labels are used if