[Mattice-commits] r159 - pkg/inst/doc

[noreply at r-forge.r-project.org]

Author: andrew_hipp
Date: 2009-01-15 00:26:14 +0100 (Thu, 15 Jan 2009)
New Revision: 159

Modified:
   pkg/inst/doc/maticce.Rnw
Log:
removing dQuote

Modified: pkg/inst/doc/maticce.Rnw
===================================================================
--- pkg/inst/doc/maticce.Rnw	2009-01-14 23:20:11 UTC (rev 158)
+++ pkg/inst/doc/maticce.Rnw	2009-01-14 23:26:14 UTC (rev 159)
@@ -17,7 +17,7 @@
 
 \section{Introduction}
 
-This document provides an overview of the \pkg{maticce} package, which serves three primary purposes. First, it implements an information-theoretic approach to estimating where on a phylogeny there has been a transition in a continuous character. As currently implemented, the approach assumes that (1) such transitions are appropriately modeled as shifts in optimum / equilibrium of a character evolving according to an Ornstein-Uhlenbeck process; (2) strength of constraint / rate of evolution toward the optimum is constant over the tree, as is variance; and (3) all branches on which a change could occur are identified. These assumptions can be relaxed in future versions if needed. Second, the package provides helper functions for the \pkg{ouch} package, in which all likelihood calculations are performed. For example, the package automates the process of painting \dQuote{regimes} (described in the \dQuote{Painting Regimes} section below) for the \code{hansen} function of \pkg{ouch}, specifying nodes at which the regime changes. It also provides functions for identifying most recent common ancestors and all descendents of a particular node. Users of \pkg{ouch} who want to handle large numbers of analyses may find the routines for summarizing analyses over trees and over regimes useful as well. Finally, \pkg{maticce} provides a flexible set of simulation functions for visualizing how different model parameters affect (i.e., what they 'say' about) our inference of the evolution of a continuous character on a phylogenetic tree.
+This document provides an overview of the \pkg{maticce} package, which serves three primary purposes. First, it implements an information-theoretic approach to estimating where on a phylogeny there has been a transition in a continuous character. As currently implemented, the approach assumes that (1) such transitions are appropriately modeled as shifts in optimum / equilibrium of a character evolving according to an Ornstein-Uhlenbeck process; (2) strength of constraint / rate of evolution toward the optimum is constant over the tree, as is variance; and (3) all branches on which a change could occur are identified. These assumptions can be relaxed in future versions if needed. Second, the package provides helper functions for the \pkg{ouch} package, in which all likelihood calculations are performed. For example, the package automates the process of painting regimes (described in the \emph{Painting Regimes} section below) for the \code{hansen} function of \pkg{ouch}, specifying nodes at which the regime changes. It also provides functions for identifying most recent common ancestors and all descendents of a particular node. Users of \pkg{ouch} who want to handle large numbers of analyses may find the routines for summarizing analyses over trees and over regimes useful as well. Finally, \pkg{maticce} provides a flexible set of simulation functions for visualizing how different model parameters affect (i.e., what they 'say' about) our inference of the evolution of a continuous character on a phylogenetic tree.
 
 This document also provides a worked example of analyzing a continuous character dataset that illustrates most of the \pkg{maticce} features. Working through this example will I expect address most questions that should come up during a typical analysis.
 
@@ -78,7 +78,7 @@
 
 \section{Painting regimes}
 
-In the \code{hansen} function of \pkg{ouch}, Ornstein-Uhlenbeck models are specified by specifying for each phylogenetic branch one and only one selective regime that governs the evolution of individuals that occupy that branch. In the \pkg{maticce} approach, \dQuote{selective regime} is an overly specific description, because the dynamics of trait evolution may shift significantly at cladogenesis for reasons that have nothing to do with natural selection. For consistency with \pkg{ouch}, the term \dQuote{regime} is retained in \pkg{maticce}, but it is used here to refer to the entire set of lineage-specific stationary distributions on a tree rather than the branch-specific set of selective pressures that is implied by dQuote{selective regime}. Hereafter, and in the \pkg{maticce} documentation, dQuote{regime} is used interchangeably for the tree-based model (the vector returned by \code{paintBranches} and visualized using \code{plot(tree, regimes=regime)}). Two functions are available for painting regimes; both return objects that may be used directly in the \code{hansen} function of \pkg{ouch}:
+In the \code{hansen} function of \pkg{ouch}, Ornstein-Uhlenbeck models are specified by specifying for each phylogenetic branch one and only one selective regime that governs the evolution of individuals that occupy that branch. In the \pkg{maticce} approach, \emph{selective regime} is an overly specific description, because the dynamics of trait evolution may shift significantly at cladogenesis for reasons that have nothing to do with natural selection. For consistency with \pkg{ouch}, the term \emph{regime} is retained in \pkg{maticce}, but it is used here to refer to the entire set of lineage-specific stationary distributions on a tree rather than the branch-specific set of selective pressures that is implied by \emph{selective regime}. Hereafter, and in the \pkg{maticce} documentation, \emph{regime} is used interchangeably for the tree-based model (the vector returned by \code{paintBranches} and visualized using \code{plot(tree, regimes=regime)}). Two functions are available for painting regimes; both return objects that may be used directly in the \code{hansen} function of \pkg{ouch}:
 
 \begin{itemize}
   \item \code{paintBranches}: returns the single regime for character transitions occuring at all specified nodes
@@ -109,7 +109,7 @@
 
 \begin{itemize}
   \item \emph{Which nodes are you interested in testing?} The choice of which nodes you are considering will have the strongest effect on your estimates of the support for a character transition having occurred at those nodes. This is a standard issue in model-fitting: the choice of which models to consider is the primary question once you have data in hand.
-  \item \emph{How many transitions are plausible on a single tree?} The feasibility of studying a large number of nodes is governed by how many simultaneous transitions you allow. Suppose you have 15 nodes that are of interest. Testing models that allow transitions at anywhere between zero and 15 nodes would entail testing 2^15 = 32,768 models. This would be too long to be feasible. Allowing changes at anywhere between zero and four nodes would entail testing a more manageable 1,941 models.
+  \item \emph{How many transitions are plausible on a single tree?} The feasibility of studying a large number of nodes is governed by how many simultaneous transitions you allow. Suppose you have 15 nodes that are of interest. Testing models that allow transitions at anywhere between zero and 15 nodes would entail testing 32,768 models. This would be too long to be feasible. Allowing changes at anywhere between zero and four nodes would entail testing a more manageable 1,941 models.
   \item \emph{How much do you trust poorly-supported nodes? Do you want to consider them at all?} \pkg{maticce} allows you to analyze over a set of trees, e.g. trees visited in a Bayesian (MCMC) analysis or a set of bootstrap trees. The \code{summary} function will give you an estimate of the support for a transition at each node you specify, both conditioned on trees that possess that node and averaged over all trees. If you have some reason for trusting the node in spite of low support (because, for example, it holds together a morphologically coherent group), you might want to give some credence to the support value that conditions only on trees that possess that node.
 \end{itemize}