man/read.nexus.Rd

   1 \name{read.nexus}
   2 \alias{read.nexus}
   3 \title{Read Tree File in Nexus Format}
   4 \usage{
   5 read.nexus(file, tree.names = NULL)
   6 }
   7 \arguments{
   8   \item{file}{a file name specified by either a variable of mode character,
   9     or a double-quoted string.}
  10   \item{tree.names}{if there are several trees to be read, a vector of
  11     mode character that gives names to the individual trees.}
  12 }
  13 \description{
  14   This function reads one or several trees in a NEXUS file.
  15 }
  16 \details{
  17   The present implementation tries to follow as much as possible the
  18   NEXUS standard (but see the restriction below on TRANSLATION
  19   tables). Only the block ``TREES'' is read; the other data can be read
  20   with other functions (e.g., \code{\link{read.dna}},
  21   \code{\link[utils]{read.table}}, ...). A trace of the original data is
  22   kept with the attribute \code{"origin"} (see below).
  23
  24   If a TRANSLATION table is present it is assumed that only the tip
  25   labels are translated and they are all translated with integers
  26   without gap. Consequently, if nodes have labels in the tree(s) they
  27   are read as they are and not looked for in the translation table. The
  28   logic behind this is that in the vast majority of cases, node labels
  29   will be support values rather than proper taxa names. This is
  30   consistent with \code{\link{write.nexus}} which translates only the
  31   tip labels.
  32
  33   `read.nexus' tries to represent correctly trees with a badly
  34   represented root edge (i.e. with an extra pair of parentheses). For
  35   instance, the tree "((A:1,B:1):10);" will be read like "(A:1,B:1):10;"
  36   but a warning message will be issued in the former case as this is
  37   apparently not a valid Newick format. If there are two root edges
  38   (e.g., "(((A:1,B:1):10):10);"), then the tree is not read and an error
  39   message is issued.
  40 }
  41 \value{
  42   an object of class \code{"phylo"} with the following components:
  43   \item{edge}{a two-column matrix of mode character where each row
  44     represents an edge of the tree; the nodes and the tips are
  45     symbolized with numbers (these numbers are not treated as numeric,
  46     hence the mode character); the nodes are represented with negative
  47     numbers (the root being \code{"-1"}), and the tips are represented with
  48     positive numbers. For each row, the first column gives the
  49     ancestor. This representation allows an easy manipulation of the
  50     tree, particularly if it is rooted.}
  51   \item{edge.length}{a numeric vector giving the lengths of the
  52     branches given by \code{edge}.}
  53   \item{tip.label}{a vector of mode character giving the names of the
  54     tips; the order of the names in this vector corresponds to the
  55     (positive) number in \code{edge}.}
  56   \item{node.label}{(optional) a vector of mode character giving the
  57     names of the nodes (set to \code{NULL} if not available in the file).}
  58   \item{root.edge}{(optional) a numeric value giving the length of the
  59     branch at the root is it exists (\code{NULL} otherwise).}
  60
  61   If several trees are read in the file, the returned object is of class
  62   \code{"multiPhylo"}, and is a list of objects of class \code{"phylo"}.
  63
  64   An attribute \code{"origin"} is further given to the returned object
  65   which gives the name of the source file (with its path). This is used
  66   to write a tree in a NEXUS file where all the original data must be
  67   written (not only the tree) in accordance to the specifications of
  68   Maddison et al. (1997).
  69 }
  70 \references{
  71   Maddison, D. R., Swofford, D. L. and Maddison, W. P. (1997) NEXUS: an
  72   extensible file format for systematic information. \emph{Systematic
  73     Biology}, \bold{46}, 590--621.
  74 }
  75 \author{Emmanuel Paradis \email{Emmanuel.Paradis@mpl.ird.fr}}
  76 \seealso{
  77   \code{\link{read.tree}}, \code{\link{write.nexus}},
  78   \code{\link{write.tree}}, \code{\link{read.nexus.data}},
  79   \code{\link{write.nexus.data}}
  80 }
  81 \keyword{manip}
  82 \keyword{IO}