[Mattice-commits] r120 - in pkg: inst/doc misc
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Tue Dec 30 07:45:38 CET 2008
Author: andrew_hipp
Date: 2008-12-30 07:45:38 +0100 (Tue, 30 Dec 2008)
New Revision: 120
Added:
pkg/inst/doc/maticce.Rnw
Removed:
pkg/misc/maticce.Rnw
Log:
moved vignette to inst/doc
Added: pkg/inst/doc/maticce.Rnw
===================================================================
--- pkg/inst/doc/maticce.Rnw (rev 0)
+++ pkg/inst/doc/maticce.Rnw 2008-12-30 06:45:38 UTC (rev 120)
@@ -0,0 +1,122 @@
+\documentclass{article}
+%\VignettePackage{maticce}
+% \VignetteIndexEntry{maticce: Mapping Transitions in Continuous Character Evolution}
+\usepackage{graphicx}
+\usepackage[colorlinks=true,urlcolor=blue]{hyperref}
+\usepackage{array}
+\usepackage{color}
+\SweaveOpts{keep.source=TRUE}
+\usepackage[utf8]{inputenc} % for UTF-8/single quotes from sQuote()
+\newcommand{\code}{\texttt}
+\newcommand{\pkg}{\textsf}
+\title{Utilizing \pkg{maticce} to estimate transitions in continuous character evolution}
+\author{Andrew Hipp}
+\date{\today}
+\begin{document}
+\maketitle
+
+\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 regimes 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.
+
+\section{Package Overview}
+
+The \pkg{maticce} package currently implements functions in the following categories:
+
+\begin{itemize}
+ \item Extracting information from \pkg{ouch}-style (S4 class \code{ouchtree}) trees
+ \item Painting regimes on a batch of \pkg{ouch}-style trees
+ \item Performing batch analyses in \pkg{ouch} over trees and over regimes
+ \item Summarizing analyses
+\end{itemize}
+
+Functions in the first two categories will be of general utility to \pkg{ouch} users; functions in the third category are utilized to perform analyses over trees and over models, and in the fourth to summarize these with regard to the hypothesis that there has been a shift in continuous character on a given branch of a phylogenetic tree. While these latter two categories are more specific, the functions can be easily modified to address other multiple-tree / multiple-model questions.
+
+\section{Getting started}
+
+In case you aren't familiar with \code{R}, the following commands will get you started.
+
+<<startAnalysis, fig=FALSE>>=
+# library(maticce) # load the maticce package into memory; also loads the required ouch package
+library(ouch)
+load('C:/Documents and Settings/Mortonarb/My Documents/mattice/pkg/DATA/carex.rda') # load demonstration data
+attach(carex)
+ovales.tree <- ape2ouch(ovales.tree) # make the tree an ouchtree object
+@
+
+Note that although the sample tree provided (\code{carex[['ovales.tree']]}) is ultrametric, this is not strictly required.
+
+\section{Extracting information from trees}
+
+Three functions are available to extract information from an \code{ouchtree} object:
+
+\begin{itemize}
+ \item \code{isMonophyletic}: returns a \code{T} or \code{F} depending on whether the taxa identified are monophyletic on the tree provided
+ \item \code{nodeDescendents}: identifies all descendents of a given node on a tree
+ \item \code{mrcaOUCH}: identifies the most recent common ancestor of a given set of taxa
+\end{itemize}
+
+These functions can be used interactively to identify nodes on the tree for analysis. Because the batch-analysis functions in \pkg{maticce} identify nodes based on taxa (see explanation in the section on 'Performing batch analyses'), nodes are provided as a list of vectors, each vector containing all taxa descendent from the node of interest. You can generate these lists manually by typing lists of names into vectors, or you could use the following if you want to explicitly designate all taxa for each node by selecting from a list:
+
+\begin{verbatim}
+ > nodes <- list(8) # assuming you want 8 nodes}
+ > for(i in 1:length(nodes)) nodes[[i]] <- select.list(otree at nodelabels, multiple = T)}
+\end{verbatim}
+
+Alternatively, if you want to designate the node more quickly by just selecting the most recent common ancestor of a set of taxa:
+
+\begin{verbatim}
+ > for(i in 1:length(nodes)) {
+ > ancestor <- mrcaOUCH(select.list(otree at nodelabels, multiple = T), otree)
+ > nodes[[i]] <- nodeDescendents(otree, ancestor)
+ > }
+\end{verbatim}
+
+These functions are all documented under \code{isMonophyletic}.
+
+\section{Painting regimes}
+
+Two functions are available for painting selective regimes that may be used in the \code{hansen} function of \pkg{ouch}:
+
+\begin{itemize}
+ \item \code{paintBranches}: returns the single regime for changes occuring at all specified nodes
+ \item \code{regimeVectors}: returns all possible regimes for specified nodes, up to a maximum of \code{maxNodes} + 1 optima
+ \item \code{regimeMaker}: returns regimes defined by a matrix, with each row specifying which nodes the optimz change at
+\end{itemize}
+
+The \code{paintBranches} function is typically called from within \code{regimeVectors}, but it can be called separately. Nodes can be designated by number or taxa; the function assumes the latter only if it receives a list to evaluate instead of a vector.
+
+<<paintingOne,fig=FALSE>>=
+ou2 <- paintBranches(list(ovales.nodes[[2]]), ovales.tree)
+@
+
+The regime can be used directly in a call to \code{hansen} or the \code{plot} method for an \code{ouchtree} object (Figure 1).
+
+\begin{figure}[h]
+\centering
+<<ov2, fig=TRUE, width=30, height =15>>=
+plot(ovales.tree, regimes = ou2, cex = 1.2)
+@
+\caption{\code{ovales.tree} with coloring according to \code{ou2}}
+\end{figure}
+
+\section{Batch analyses}
+
+<<runBatch, fig=FALSE, echo=TRUE>>=
+ha.4.2 <- runBatchHansen(ovales.tree, ovales.data, ovales.nodes[1:4], maxNodes = 2, brown = T)
+print(summary(ha.4.2))
+@
+
+\begin{figure}[h]
+\centering
+<<ouSim, fig=TRUE, width=30, height =15, echo=TRUE>>=
+ouSim.ha.4.2 <- ouSim(ha.4.2, ovales.tree)
+plot(ouSim.ha.4.2, colors = ou2)
+@
+\caption{Simulated character on \code{ovales.tree} at model-averaged theta values, with coloring according to \code{ou2}}
+\end{figure}
+
+
+\end{document}
Deleted: pkg/misc/maticce.Rnw
===================================================================
--- pkg/misc/maticce.Rnw 2008-12-30 06:45:12 UTC (rev 119)
+++ pkg/misc/maticce.Rnw 2008-12-30 06:45:38 UTC (rev 120)
@@ -1,122 +0,0 @@
-\documentclass{article}
-%\VignettePackage{maticce}
-% \VignetteIndexEntry{maticce: Mapping Transitions in Continuous Character Evolution}
-\usepackage{graphicx}
-\usepackage[colorlinks=true,urlcolor=blue]{hyperref}
-\usepackage{array}
-\usepackage{color}
-\SweaveOpts{keep.source=TRUE}
-\usepackage[utf8]{inputenc} % for UTF-8/single quotes from sQuote()
-\newcommand{\code}{\texttt}
-\newcommand{\pkg}{\textsf}
-\title{Utilizing \pkg{maticce} to estimate transitions in continuous character evolution}
-\author{Andrew Hipp}
-\date{\today}
-\begin{document}
-\maketitle
-
-\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 regimes 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.
-
-\section{Package Overview}
-
-The \pkg{maticce} package currently implements functions in the following categories:
-
-\begin{itemize}
- \item Extracting information from \pkg{ouch}-style (S4 class \code{ouchtree}) trees
- \item Painting regimes on a batch of \pkg{ouch}-style trees
- \item Performing batch analyses in \pkg{ouch} over trees and over regimes
- \item Summarizing analyses
-\end{itemize}
-
-Functions in the first two categories will be of general utility to \pkg{ouch} users; functions in the third category are utilized to perform analyses over trees and over models, and in the fourth to summarize these with regard to the hypothesis that there has been a shift in continuous character on a given branch of a phylogenetic tree. While these latter two categories are more specific, the functions can be easily modified to address other multiple-tree / multiple-model questions.
-
-\section{Getting started}
-
-In case you aren't familiar with \code{R}, the following commands will get you started.
-
-<<startAnalysis, fig=FALSE>>=
-# library(maticce) # load the maticce package into memory; also loads the required ouch package
-library(ouch)
-load('C:/Documents and Settings/Mortonarb/My Documents/mattice/pkg/DATA/carex.rda') # load demonstration data
-attach(carex)
-ovales.tree <- ape2ouch(ovales.tree) # make the tree an ouchtree object
-@
-
-Note that although the sample tree provided (\code{carex[['ovales.tree']]}) is ultrametric, this is not strictly required.
-
-\section{Extracting information from trees}
-
-Three functions are available to extract information from an \code{ouchtree} object:
-
-\begin{itemize}
- \item \code{isMonophyletic}: returns a \code{T} or \code{F} depending on whether the taxa identified are monophyletic on the tree provided
- \item \code{nodeDescendents}: identifies all descendents of a given node on a tree
- \item \code{mrcaOUCH}: identifies the most recent common ancestor of a given set of taxa
-\end{itemize}
-
-These functions can be used interactively to identify nodes on the tree for analysis. Because the batch-analysis functions in \pkg{maticce} identify nodes based on taxa (see explanation in the section on 'Performing batch analyses'), nodes are provided as a list of vectors, each vector containing all taxa descendent from the node of interest. You can generate these lists manually by typing lists of names into vectors, or you could use the following if you want to explicitly designate all taxa for each node by selecting from a list:
-
-\begin{verbatim}
- > nodes <- list(8) # assuming you want 8 nodes}
- > for(i in 1:length(nodes)) nodes[[i]] <- select.list(otree at nodelabels, multiple = T)}
-\end{verbatim}
-
-Alternatively, if you want to designate the node more quickly by just selecting the most recent common ancestor of a set of taxa:
-
-\begin{verbatim}
- > for(i in 1:length(nodes)) {
- > ancestor <- mrcaOUCH(select.list(otree at nodelabels, multiple = T), otree)
- > nodes[[i]] <- nodeDescendents(otree, ancestor)
- > }
-\end{verbatim}
-
-These functions are all documented under \code{isMonophyletic}.
-
-\section{Painting regimes}
-
-Two functions are available for painting selective regimes that may be used in the \code{hansen} function of \pkg{ouch}:
-
-\begin{itemize}
- \item \code{paintBranches}: returns the single regime for changes occuring at all specified nodes
- \item \code{regimeVectors}: returns all possible regimes for specified nodes, up to a maximum of \code{maxNodes} + 1 optima
- \item \code{regimeMaker}: returns regimes defined by a matrix, with each row specifying which nodes the optimz change at
-\end{itemize}
-
-The \code{paintBranches} function is typically called from within \code{regimeVectors}, but it can be called separately. Nodes can be designated by number or taxa; the function assumes the latter only if it receives a list to evaluate instead of a vector.
-
-<<paintingOne,fig=FALSE>>=
-ou2 <- paintBranches(list(ovales.nodes[[2]]), ovales.tree)
-@
-
-The regime can be used directly in a call to \code{hansen} or the \code{plot} method for an \code{ouchtree} object (Figure 1).
-
-\begin{figure}[h]
-\centering
-<<ov2, fig=TRUE, width=30, height =15>>=
-plot(ovales.tree, regimes = ou2, cex = 1.2)
-@
-\caption{\code{ovales.tree} with coloring according to \code{ou2}}
-\end{figure}
-
-\section{Batch analyses}
-
-<<runBatch, fig=FALSE, echo=TRUE>>=
-ha.4.2 <- runBatchHansen(ovales.tree, ovales.data, ovales.nodes[1:4], maxNodes = 2, brown = T)
-print(summary(ha.4.2))
-@
-
-\begin{figure}[h]
-\centering
-<<ouSim, fig=TRUE, width=30, height =15, echo=TRUE>>=
-ouSim.ha.4.2 <- ouSim(ha.4.2, ovales.tree)
-plot(ouSim.ha.4.2, colors = ou2)
-@
-\caption{Simulated character on \code{ovales.tree} at model-averaged theta values, with coloring according to \code{ou2}}
-\end{figure}
-
-
-\end{document}
More information about the Mattice-commits
mailing list