man/trex.Rd

   1 \name{trex}
   2 \alias{trex}
   3 \title{Tree Explorer With Multiple Devices}
   4 \description{
   5   This functions requires a plotted tree: the user is invited to click
   6   close to a node and the corresponding subtree (or clade) is plotted on
   7   a new window.
   8 }
   9 \usage{
  10 trex(phy, title = TRUE, subbg = "lightyellow3",
  11      return.tree = FALSE, ...)
  12 }
  13 \arguments{
  14   \item{phy}{an object of class \code{"phylo"}.}
  15   \item{title}{a logical or a character string (see details).}
  16   \item{subbg}{a character string giving the background colour for the
  17     subtree.}
  18   \item{return.tree}{a logical: if \code{TRUE}, the subtree is returned
  19     after being plotted and the operation is stopped.}
  20   \item{\dots}{further arguments to pass to \code{plot.phylo}.}
  21 }
  22 \details{
  23   This function works with a tree (freshly) plotted on an interactive
  24   graphical device (i.e., not a file). After calling \code{trex}, the
  25   user clicks close to a node of the tree, then the clade from this node
  26   is plotted on a \emph{new} window. The user can click as many times on
  27   the main tree: the clades are plotted successively on the \emph{same}
  28   new window. The process is stopped by a right-click. If the user clicks
  29   too close to the tips, a message ``Try again!'' is printed.
  30
  31   Each time \code{trex} is called, the subtree is plotted on a new
  32   window without closing or deleting those possibly already
  33   plotted. They may be distinguished with the options \code{title}
  34   and/or \code{subbg}.
  35
  36   In all cases, the device where \code{phy} is plotted is the active
  37   window after the operation. It should \emph{not} be closed during the
  38   whole process.
  39
  40   If \code{title = TRUE}, a default title is printed on the new window
  41   using the node label, or the node number if there are no node labels
  42   in the tree. If \code{title = FALSE}, no title is printed. If
  43   \code{title} is a character string, this is used for the title.
  44 }
  45 \value{
  46   an object of class \code{"phylo"} if \code{return.tree = TRUE}
  47 }
  48 \author{Emmanuel Paradis}
  49 \seealso{
  50   \code{\link{plot.phylo}}, \code{\link{identify.phylo}}
  51 }
  52 \examples{
  53 \dontrun{
  54 tr <- rcoal(1000)
  55 plot(tr, show.tip.label = FALSE)
  56 trex(tr) # left-click as many times as you want, then right-click
  57 tr <- makeNodeLabel(tr)
  58 trex(tr, subbg = "lightgreen") # id.
  59
  60 ## generate a random colour with control on the darkness:
  61 rRGB <- function(a, b)
  62     rgb(runif(1, a, b), runif(1, a, b), runif(1, a, b))
  63
  64 ### with a random pale background:
  65 trex(tr, subbg = rRGB(0.8, 1))
  66 ## the above can be called many times...
  67 graphics.off() # close all graphical devices
  68 }}
  69 \keyword{hplot}