ape (version 4.0)

read.tree: Read Tree File in Parenthetic Format

Description

This function reads a file which contains one or several trees in parenthetic format known as the Newick or New Hampshire format.

Usage

read.tree(file = "", text = NULL, tree.names = NULL, skip = 0, comment.char = "#", keep.multi = FALSE, ...)

Arguments

file

a file name specified by either a variable of mode character, or a double-quoted string; if file = "" (the default) then the tree is input on the keyboard, the entry being terminated with a blank line.

text

alternatively, the name of a variable of mode character which contains the tree(s) in parenthetic format. By default, this is ignored (set to NULL, meaning that the tree is read in a file); if text is not NULL, then the argument file is ignored.

tree.names

if there are several trees to be read, a vector of mode character that gives names to the individual trees; if NULL (the default), the trees are named "tree1", "tree2", ...

skip

the number of lines of the input file to skip before beginning to read data (this is passed directly to scan()).

comment.char

a single character, the remaining of the line after this character is ignored (this is passed directly to scan()).

keep.multi

if TRUE and tree.names = NULL then single trees are returned in "multiPhylo" format, with any name that is present (see details). Default is FALSE.

...

further arguments to be passed to scan().

Value

an object of class "phylo" with the following components:If several trees are read in the file, the returned object is of class "multiPhylo", and is a list of objects of class "phylo". The name of each tree can be specified by tree.names, or can be read from the file (see details).

Details

The default option for file allows to type directly the tree on the keyboard (or possibly to copy from an editor and paste in R's console) with, e.g., mytree <- read.tree().

`read.tree' tries to represent correctly trees with a badly represented root edge (i.e. with an extra pair of parentheses). For instance, the tree "((A:1,B:1):10);" will be read like "(A:1,B:1):10;" but a warning message will be issued in the former case as this is apparently not a valid Newick format. If there are two root edges (e.g., "(((A:1,B:1):10):10);"), then the tree is not read and an error message is issued.

If there are any characters preceding the first "(" in a line then this is assigned to the name. This is returned when a "multiPhylo" object is returned and tree.names = NULL.

References

Felsenstein, J. The Newick tree format. http://evolution.genetics.washington.edu/phylip/newicktree.html

Olsen, G. Interpretation of the "Newick's 8:45" tree format standard. http://evolution.genetics.washington.edu/phylip/newick_doc.html

Paradis, E. (2008) Definition of Formats for Coding Phylogenetic Trees in R. http://ape-package.ird.fr/misc/FormatTreeR_24Oct2012.pdf

Paradis, E. (2012) Analysis of Phylogenetics and Evolution with R (Second Edition). New York: Springer.

See Also

write.tree, read.nexus, write.nexus, scan for the basic R function to read data in a file

Examples

### An extract from Sibley and Ahlquist (1990)
s <- "owls(((Strix_aluco:4.2,Asio_otus:4.2):3.1,Athene_noctua:7.3):6.3,Tyto_alba:13.5);"
cat(s, file = "ex.tre", sep = "\n")
tree.owls <- read.tree("ex.tre")
str(tree.owls)
tree.owls
tree.owls <- read.tree("ex.tre", keep.multi = TRUE)
tree.owls
names(tree.owls)
unlink("ex.tre") # delete the file "ex.tre"
### Only the first three species using the option `text'
TREE <- "((Strix_aluco:4.2,Asio_otus:4.2):3.1,Athene_noctua:7.3);"
TREE
tree.owls.bis <- read.tree(text = TREE)
str(tree.owls.bis)
tree.owls.bis