read.nexus: Read Tree File in Nexus Format

In emmanuelparadis/ape: Analyses of Phylogenetics and Evolution

Read Tree File in Nexus Format

Description

This function reads one or several trees in a NEXUS file.

Usage

read.nexus(file, tree.names = NULL, force.multi = FALSE)

Arguments

file	a file name specified by either a variable of mode character, or a double-quoted string.
tree.names	if there are several trees to be read, a vector of mode character giving names to the individual trees (by default, this uses the labels in the NEXUS file if these are present).
force.multi	a logical value; if TRUE, an object of class "multiPhylo" is always returned even if the file contains a single tree (see details).

Details

The present implementation tries to follow as much as possible the NEXUS standard. Only the block “TREES” is read; the other data can be read with other functions (e.g., read.dna, read.table, ...).

Until ape version 5.8-1, if a TRANSLATION table was present it was assumed that only the tip labels are translated with integers without gap and nodes labels were not looked for in the translation table. Recent versions of ape now conforms more closely to the NEXUS standard as described in Maddison et al (1997). Note that write.nexus translates only the tip labels.

Using force.multi = TRUE when the file contains a single tree makes possible to keep the tree name (as names of the list).

‘read.nexus’ 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.

Value

an object of class "phylo" or "multiPhylo".

Note

NEXUS is not a particularly efficient format to store very large collections of trees. For 1000 trees each with 1000 tips, the NEXUS file is (roughly) 30 MB, and it takes 5 sec to read it with this function. The file can be compressed with GZIP making it about twice smaller for about the same time to read it (thanks to the ability of scan to read directly compressed files). On the other hand, saving the same list of trees with saveRDS creates a file of about 20 MB which can be read with readRDS in 0.2 sec.

Author(s)

Emmanuel Paradis

References

Maddison, D. R., Swofford, D. L. and Maddison, W. P. (1997) NEXUS: an extensible file format for systematic information. Systematic Biology, 46, 590–621.

See Also

read.tree, write.nexus, write.tree, read.nexus.data, write.nexus.data

emmanuelparadis/ape documentation built on June 9, 2025, 1:50 p.m.