Read Tree in Binary Format

This function reads one tree from a file in binary format.

read_one_binary_tree(file, index = 1, address = NA, metadata = NA)

Arguments

file	A file name.
index	The index of the tree that should be read (starting from 1).
address	The address (i.e. byte offset from the start of the file) of the tree that should be read.
metadata	An object of class "BinaryTreeMetadata" containing the metadata extracted from the tree file. If this is not provided, it will be read from the file (see details).

Value

An object of class "phylo", compatible with the ape package.

In addition to the elements described in the documentation for the read.tree function of the ape package, a "phylo" object produced by this function will also have the following components:

tip.attributes

A named list of attributes for the tips of the tree. Each element of this list is a vector of mode character or numeric (depending on the attribute).

node.attributes

A named list of attributes for the internal nodes of the tree. Each element of this list is a vector of mode character or numeric (depending on the attribute).

Details

This function extracts only one tree from the file. The information provided by metadata is used to determine where in the file the requested tree starts. If this is not provided, this function will read the metadata from the file (using the read_binary_tree_metadata function).

Reusing the metadata is efficient when multiple trees need to be read from the same file (so that the metadata only needs to be read once).

Node attributes (e.g. support values, rates, ages...) are parsed by this function and returned in the tip.attributes and node.attributes elements of the returned "phylo" objects.

Attribute names may appear in any kind of casing (e.g. Name, name or NAME), but they should be treated using case-insensitive comparisons.

Due to limitations with R's integral types, this function may have issues with files larger than 2GB.

References

https://github.com/arklumpus/TreeNode/blob/master/BinaryTree.md

See also

read_binary_trees, read_binary_tree_metadata, ape, read.tree

Other functions to read trees: read_binary_trees(), read_nwka_nexus(), read_nwka_tree()

Examples

# Tree file (replace with your own)
treeFile <- system.file("extdata", "manyTrees.tbi", package="TreeNode")

# Read the 5th tree in the file
tree <- read_one_binary_tree(treeFile, 5)
#Do something with the tree


# Read the binary tree metadata
meta <- read_binary_tree_metadata(treeFile)

# Process every tree in the file
for (add in meta$TreeAddresses)
{
    tree <- read_one_binary_tree(treeFile, address = add, metadata = meta)
    #Do something with the tree
}