man/read.tree.Rd

   1 \name{read.tree}
   2 \alias{read.tree}
   3 \title{Read Tree File in Parenthetic Format}
   4 \usage{
   5 read.tree(file = "", text = NULL, tree.names = NULL,
   6           skip = 0, comment.char = "#", ...)
   7 }
   8 \arguments{
   9   \item{file}{a file name specified by either a variable of mode character,
  10     or a double-quoted string; if \code{file = ""} (the default) then the
  11     tree is input on the keyboard, the entry being terminated with a
  12     blank line.}
  13   \item{text}{alternatively, the name of a variable of mode character
  14     which contains the tree(s) in parenthetic format. By default, this
  15     is ignored (set to \code{NULL}, meaning that the tree is read in a
  16     file); if \code{text} is not \code{NULL}, then the argument
  17     \code{file} is ignored.}
  18   \item{tree.names}{if there are several trees to be read, a vector of
  19     mode character that gives names to the individual trees; if
  20     \code{NULL} (the default), the trees are named \code{"tree1"},
  21     \code{"tree2"}, ...}
  22   \item{skip}{the number of lines of the input file to skip before
  23     beginning to read data (this is passed directly to\code{ scan()}).}
  24   \item{comment.char}{a single character, the remaining of the line
  25     after this character is ignored (this is passed directly to
  26     \code{scan()}).}
  27   \item{...}{Further arguments to be passed to \code{scan()}.}
  28 }
  29 \description{
  30   This function reads a file which contains one or several trees in
  31   parenthetic format known as the Newick or New Hampshire format.
  32 }
  33 \details{
  34   The default option for \code{file} allows to type directly the tree on
  35   the keyboard (or possibly to copy from an editor and paste in R's
  36   console) with, e.g., \code{mytree <- read.tree()}.
  37
  38   `read.tree' tries to represent correctly trees with a badly
  39   represented root edge (i.e. with an extra pair of parentheses). For
  40   instance, the tree "((A:1,B:1):10);" will be read like "(A:1,B:1):10;"
  41   but a warning message will be issued in the former case as this is
  42   apparently not a valid Newick format. If there are two root edges
  43   (e.g., "(((A:1,B:1):10):10);"), then the tree is not read and an error
  44   message is issued.
  45 }
  46 \value{
  47   an object of class \code{"phylo"} with the following components:
  48   \item{edge}{a two-column matrix of mode numeric where each row
  49     represents an edge of the tree; the nodes and the tips are
  50     symbolized with numbers; the tips are numbered 1, 2, \dots, and the
  51     nodes are numbered after the tips. For each row, the first column
  52     gives the ancestor.}
  53   \item{edge.length}{(optional) a numeric vector giving the lengths of the
  54     branches given by \code{edge}.}
  55   \item{tip.label}{a vector of mode character giving the names of the
  56     tips; the order of the names in this vector corresponds to the
  57     (positive) number in \code{edge}.}
  58   \item{Nnode}{the number of (internal) nodes.}
  59   \item{node.label}{(optional) a vector of mode character giving the
  60     names of the nodes.}
  61   \item{root.edge}{(optional) a numeric value giving the length of the
  62     branch at the root if it exists.}
  63
  64   If several trees are read in the file, the returned object is of class
  65   \code{"multiPhylo"}, and is a list of objects of class \code{"phylo"}.
  66 }
  67 \references{
  68   Felsenstein, J. The Newick tree format.
  69   \url{http://evolution.genetics.washington.edu/phylip/newicktree.html}
  70
  71   Olsen, G. Interpretation of the "Newick's 8:45" tree format standard.
  72   \url{http://evolution.genetics.washington.edu/phylip/newick_doc.html}
  73
  74   Paradis, E. (2006) Definition of Formats for Coding Phylogenetic Trees
  75   in R. \url{http://pbil.univ-lyon1.fr/R/ape/misc/FormatTreeR_4Dec2006.pdf}
  76 }
  77
  78 \author{Emmanuel Paradis \email{Emmanuel.Paradis@mpl.ird.fr}}
  79 \seealso{
  80   \code{\link{write.tree}}, \code{\link{read.nexus}},
  81   \code{\link{write.nexus}}, \code{\link[base]{scan}} for the basic R
  82   function to read data in a file
  83 }
  84 \examples{
  85 ### An extract from Sibley and Ahlquist (1990)
  86 cat("(((Strix_aluco:4.2,Asio_otus:4.2):3.1,",
  87    "Athene_noctua:7.3):6.3,Tyto_alba:13.5);",
  88    file = "ex.tre", sep = "\n")
  89 tree.owls <- read.tree("ex.tre")
  90 str(tree.owls)
  91 tree.owls
  92 unlink("ex.tre") # delete the file "ex.tre"
  93 ### Only the first three species using the option `text'
  94 TREE <- "((Strix_aluco:4.2,Asio_otus:4.2):3.1,Athene_noctua:7.3);"
  95 TREE
  96 tree.owls.bis <- read.tree(text = TREE)
  97 str(tree.owls.bis)
  98 tree.owls.bis
  99 }
 100 \keyword{manip}
 101 \keyword{IO}