castor (version 1.6.1)

read_tree: Load a tree from a string or file in Newick (parenthetic) format.

Description

Load a phylogenetic tree from a file or a string, in Newick (parenthetic) format. Any valid Newick format is acceptable. Extended variants including edge labels and edge numbers are also supported.

Usage

read_tree(  string  = "", 
            file    = "", 
            edge_order              = "cladewise",
            include_edge_lengths    = TRUE, 
            look_for_edge_labels    = FALSE, 
            look_for_edge_numbers   = FALSE, 
            include_node_labels     = TRUE, 
            underscores_as_blanks   = FALSE, 
            check_label_uniqueness  = FALSE,
            interpret_quotes        = FALSE)

Arguments

string

A character containing a single tree in Newick format. Can be used alternatively to file.

file

Character, a path to an input text file containing a single tree in Newick format. Can be used alternatively to string.

edge_order

Character, one of ``cladewise'' or ``pruningwise'', specifying the order in which edges should be listed in the returned tree. This does not influence the topology of the tree or the tip/node labeling, it only affects the way edges are numbered internally.

include_edge_lengths

Logical, specifying whether edge lengths (if available) should be included in the returned tree.

look_for_edge_labels

Logical, specifying whether edge labels may be present in the input tree. If edge labels are found, they are included in the returned tree as a character vector edge.label. Edge labels are sought inside square brackets, which are not part of the standard Newick format but used by some tree creation software (Matsen 2012). If look_for_edge_labels==FALSE, square brackets are read verbatim just like any other character.

look_for_edge_numbers

Logical, specifying whether edge numbers (non-negative integers) may be present in the input tree. If edge numbers are found, they are included in the returned tree as an integer vector edge.number. Edge numbers are sought inside curly braces, which are not part of the standard Newick format but used by some tree creation software (Matsen 2012). If look_for_edge_numbers==FALSE, curly braces are read verbatim just like any other character.

include_node_labels

Logical, specifying whether node labels (if available) should be included in the returned tree.

underscores_as_blanks

Logical, specifying whether underscores ("_") in tip and node labels should be replaced by spaces (" "). This is common behavior in other tree parsers. In any case, tip, node and edge labels (if available) are also allowed to contain explicit whitespace (except for newline characters).

check_label_uniqueness

Logical, specifying whether to check if all tip labels are unique.

interpret_quotes

Logical, specifying whether to interpret quotes as delimiters of tip/node/edge labels. If FALSE, then quotes are read verbatim just like any other character.

Value

A single rooted phylogenetic tree in ``phylo'' format.

Details

This function is comparable to (but typically much faster than) the ape function read.tree. The function supports trees with monofurcations and multifurcations, trees with or without tip/node labels, and trees with or without edge lengths. The time complexity is linear in the number of edges in the tree.

Either file or string must be specified, but not both. The tree may be arbitrarily split across multiple lines, but no other non-whitespace text is permitted in string or in the input file. Flanking whitespace (space, tab, newlines) is ignored.

References

Frederick A. Matsen et al. (2012). A format for phylogenetic placements. PLOS One. 7:e31009

See Also

write_tree

Examples

# NOT RUN {
# generate a random tree
tree = generate_random_tree(list(birth_rate_intercept=1),max_tips=100)$tree

# obtain a string representation of the tree in Newick format
Newick_string = write_tree(tree)

# re-parse tree from string
parsed_tree = read_tree(Newick_string)
# }