SYNOPSIS
use Bio::TreeIO;
my $in = Bio::TreeIO->new(-format => 'newick', -file => 'tree.tre');
my $tree = $in->next_tree;
my @nodes = $tree->find_node('id1');
if( $tree->is_monophyletic(-nodes => \@nodes, -outgroup => $outnode) ){
#...
}
DESCRIPTION
This interface provides a set of implementated Tree functions which only use the defined methods in the TreeI or NodeI interface.FEEDBACK
Mailing Lists
User feedback is an integral part of the evolution of this and other Bioperl modules. Send your comments and suggestions preferably to the Bioperl mailing list. Your participation is much appreciated.
[email protected] - General discussion http://bioperl.org/wiki/Mailing_lists - About the mailing lists
Support
Please direct usage questions or support issues to the mailing list:rather than to the module maintainer directly. Many experienced and reponsive experts will be able look at the problem and quickly address it. Please include a thorough description of the problem with code and data examples if at all possible.
Reporting Bugs
Report bugs to the Bioperl bug tracking system to help us keep track of the bugs and their resolution. Bug reports can be submitted via the web:
https://github.com/bioperl/bioperl-live/issues
AUTHOR - Jason Stajich, Aaron Mackey, Justin Reese
Email jason-at-bioperl-dot-org Email amackey-at-virginia.edu Email jtr4v-at-virginia.eduCONTRIBUTORS
Sendu Bala, [email protected]Rerooting code was worked on by
Daniel Barker d.barker-at-reading.ac.uk Ramiro Barrantes Ramiro.Barrantes-at-uvm.edu
APPENDIX
The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _find_node
Title : find_node Usage : my @nodes = $self->find_node(-id => 'node1'); Function: returns all nodes that match a specific field, by default this is id, but different branch_length, Returns : List of nodes which matched search Args : text string to search for OR -fieldname => $textstring
remove_Node
Title : remove_Node Usage : $tree->remove_Node($node) Function: Removes a node from the tree Returns : boolean represent status of success Args : either Bio::Tree::NodeI or string of the node id
get_lineage_nodes
Title : get_lineage_nodes Usage : my @nodes = $tree->get_lineage_nodes($node); Function: Given a node or its ID, get its full lineage, i.e. all its ancestors, from the root to the most recent ancestor. Only use the node ID as input if the nodes have been added to the tree. Returns : list of nodes Args : either Bio::Tree::NodeI (or string of the node id)
get_lineage_string
Title : get_lineage_string Usage : my $lineage = $tree->get_lineage_string($node); Function: Get the string representation of the full lineage of a node, e.g. for the Enterobacteriales node, return Bacteria;Proteobacteria;Gammaproteobacteria;Enterobacteriales. This method uses get_lineage_nodes internally and therefore inherits of all of its caveats. Returns : string Args : * either Bio::Tree::NodeI (or string of the node id) * an optional separator (default: ';')
splice
Title : splice Usage : $tree->splice(-remove_id => \@ids); Function: Remove all the nodes from a tree that correspond to the supplied args, making all the descendents of a removed node the descendents of the removed node's ancestor. You can ask to explicitly remove certain nodes by using -remove_*, remove them conditionally by using -remove_* in combination with -keep_*, or remove everything except certain nodes by using only -keep_*. Returns : n/a Args : just a list of Bio::Tree::NodeI objects to remove, OR -key => value pairs, where -key has the prefix 'remove' or 'keep', followed by an underscore, followed by a fieldname (like for the method find_node). Value should be a scalar or an array ref of scalars (again, like you might supply to find_node). So (-remove_id => [1, 2]) will remove all nodes from the tree that have an id() of '1' or '2', while (-remove_id => [1, 2], -keep_id => [2]) will remove all nodes with an id() of '1'. (-keep_id => [2]) will remove all nodes unless they have an id() of '2' (note, no -remove_*). -preserve_lengths => 1 : setting this argument will splice out intermediate nodes, preserving the original total length between the ancestor and the descendants of the spliced node. Undef by default.
get_lca
Title : get_lca Usage : get_lca(-nodes => \@nodes ); OR get_lca(@nodes); Function: given two or more nodes, returns the lowest common ancestor (aka most recent common ancestor) Returns : node object or undef if there is no common ancestor Args : -nodes => arrayref of nodes to test, OR just a list of nodes
merge_lineage
Title : merge_lineage Usage : merge_lineage($node) Function: Merge a lineage of nodes with this tree. Returns : true for success, false (and a warning) otherwise Args : Bio::Tree::TreeI with only one leaf, OR Bio::Tree::NodeI which has an ancestor For example, if we are the tree $tree: +---B | A | +---C and we want to merge the lineage $other_tree: A---C---D After calling $tree->merge_lineage($other_tree), $tree looks like: +---B | A | +---C---D
contract_linear_paths
Title : contract_linear_paths Usage : contract_linear_paths() Function: Splices out all nodes in the tree that have an ancestor and only one descendent. Returns : n/a Args : none for normal behaviour, true to dis-regard the ancestor requirment and re-root the tree as necessary For example, if we are the tree $tree: +---E | A---B---C---D | +---F After calling $tree->contract_linear_paths(), $tree looks like: +---E | A---D | +---F Instead, $tree->contract_linear_paths(1) would have given: +---E | D | +---F
is_binary
Example : is_binary(); is_binary($node); Description: Finds if the tree or subtree defined by the internal node is a true binary tree without polytomies Returns : boolean Exceptions : Args : Internal node Bio::Tree::NodeI, optional
force_binary
Title : force_binary Usage : force_binary() Function: Forces the tree into a binary tree, splitting branches arbitrarily and creating extra nodes as necessary, such that all nodes have exactly two or zero descendants. Returns : n/a Args : none For example, if we are the tree $tree: +---G | +---F | +---E | A | +---D | +---C | +---B (A has 6 descendants B-G) After calling $tree->force_binary(), $tree looks like: +---X | +---X | | | +---X | +---X | | | | +---G | | | | +---X | | | +---F A | +---E | | | +---X | | | | | +---D | | +---X | | +---C | | +---X | +---B (Where X are artificially created nodes with ids 'artificial_n', where n is an integer making the id unique within the tree)
simplify_to_leaves_string
Title : simplify_to_leaves_string Usage : my $leaves_string = $tree->simplify_to_leaves_string() Function: Creates a simple textual representation of the relationship between leaves in self. It forces the tree to be binary, so the result may not strictly correspond to the tree (if the tree wasn't binary), but will be as close as possible. The tree object is not altered. Only leaf node ids are output, in a newick-like format. Returns : string Args : none
distance
Title : distance Usage : distance(-nodes => \@nodes ) Function: returns the distance between two given nodes Returns : numerical distance Args : -nodes => arrayref of nodes to test or ($node1, $node2)
is_monophyletic
Title : is_monophyletic Usage : if( $tree->is_monophyletic(-nodes => \@nodes, -outgroup => $outgroup) Function: Will do a test of monophyly for the nodes specified in comparison to a chosen outgroup Returns : boolean Args : -nodes => arrayref of nodes to test -outgroup => outgroup to serve as a reference
is_paraphyletic
Title : is_paraphyletic Usage : if( $tree->is_paraphyletic(-nodes =>\@nodes, -outgroup => $node) ){ } Function: Tests whether or not a given set of nodes are paraphyletic (representing the full clade) given an outgroup Returns : [-1,0,1] , -1 if the group is not monophyletic 0 if the group is not paraphyletic 1 if the group is paraphyletic Args : -nodes => Array of Bio::Tree::NodeI objects which are in the tree -outgroup => a Bio::Tree::NodeI to compare the nodes to
reroot
Title : reroot Usage : $tree->reroot($node); Function: Reroots a tree making a new node the root Returns : 1 on success, 0 on failure Args : Bio::Tree::NodeI that is in the tree, but is not the current root
reroot_at_midpoint
Title : reroot_at_midpoint Usage : $tree->reroot_at_midpoint($node, $new_root_id); Function: Reroots a tree on a new node created halfway between the argument and its ancestor Returns : the new midpoint Bio::Tree::NodeIon success, 0 on failure Args : non-root Bio::Tree::NodeI currently in $tree scalar string, id for new node (optional)
findnode_by_id
Title : findnode_by_id Usage : my $node = $tree->findnode_by_id($id); Function: Get a node by its id (which should be unique for the tree) Returns : L<Bio::Tree::NodeI> Args : node id
move_id_to_bootstrap
Title : move_id_to_bootstrap Usage : $tree->move_id_to_bootstrap Function: Move internal IDs to bootstrap slot Returns : undef Args : undef
add_trait
Title : add_trait Usage : my $key = $tree->add_trait($trait_file, 3); Function: Add traits to the leaf nodes of a Bio::Tree:Tree from a file. The trait file is a tab-delimited text file and needs to have a header line giving names to traits. The first column contains the leaf node ids. Subsequent columns contain different trait value sets. Single or double quotes are removed from the trait values. Traits are added to leaf nodes as a tag named $key using the add_tag_value() method. This means that you can retrieve the trait values using the get_tag_values() method (see the documentation for Bio::Tree::Node). Returns : Trait name (a scalar) on success, undef on failure (for example, if the column index requested was too large). Args : * Name of trait file (scalar string). * Index of trait file column (scalar int). Note that numbering starts at 0. Default: 1 (second column). * Ignore missing values. Typically, if a leaf node has no value in the trait file, an exception is thrown. If you set this option to 1, then no trait will be given to the node (no exception thrown).