2 # BioPerl module for Bio::Tree::NodeI
4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
6 # Cared for by Jason Stajich <jason@bioperl.org>
8 # Copyright Jason Stajich
10 # You may distribute this module under the same terms as perl itself
12 # POD documentation - main docs before the code
16 Bio::Tree::NodeI - Interface describing a Tree Node
20 # get a Tree::NodeI somehow
23 # read in a clustalw NJ in phylip/newick format
24 my $treeio = Bio::TreeIO->new(-format => 'newick', -file => 'file.dnd');
26 my $tree = $treeio->next_tree; # we'll assume it worked for demo purposes
27 # you might want to test that it was defined
29 my $rootnode = $tree->get_root_node;
31 # process just the next generation
32 foreach my $node ( $rootnode->each_Descendent() ) {
33 print "branch len is ", $node->branch_length, "\n";
36 # process all the children
37 my $example_leaf_node;
38 foreach my $node ( $rootnode->get_all_Descendents() ) {
39 if( $node->is_Leaf ) {
40 print "node is a leaf ... ";
41 # for example use below
42 $example_leaf_node = $node unless defined $example_leaf_node;
44 print "branch len is ", $node->branch_length, "\n";
47 # The ancestor() method points to the parent of a node
48 # A node can only have one parent
50 my $parent = $example_leaf_node->ancestor;
52 # parent won't likely have an description because it is an internal node
53 # but child will because it is a leaf
55 print "Parent id: ", $parent->id," child id: ",
56 $example_leaf_node->id, "\n";
61 A NodeI is capable of the basic structure of building a tree and
62 storing the branch length between nodes. The branch length is the
63 length of the branch between the node and its ancestor, thus a root
64 node in a Tree will not typically have a valid branch length.
66 Various implementations of NodeI may extend the basic functions and
67 allow storing of other information (like attatching a species object
68 or full sequences used to build a tree or alternative sequences). If
69 you don't know how to extend a Bioperl object please ask, happy to
70 help, we would also greatly appreciate contributions with improvements
71 or extensions of the objects back to the Bioperl code base so that
72 others don't have to reinvent your ideas.
79 User feedback is an integral part of the evolution of this and other
80 Bioperl modules. Send your comments and suggestions preferably to
81 the Bioperl mailing list. Your participation is much appreciated.
83 bioperl-l@bioperl.org - General discussion
84 http://bioperl.org/wiki/Mailing_lists - About the mailing lists
88 Please direct usage questions or support issues to the mailing list:
90 I<bioperl-l@bioperl.org>
92 rather than to the module maintainer directly. Many experienced and
93 reponsive experts will be able look at the problem and quickly
94 address it. Please include a thorough description of the problem
95 with code and data examples if at all possible.
99 Report bugs to the Bioperl bug tracking system to help us keep track
100 of the bugs and their resolution. Bug reports can be submitted via
103 https://redmine.open-bio.org/projects/bioperl/
105 =head1 AUTHOR - Jason Stajich
107 Email jason@bioperl.org
111 Aaron Mackey amackey@virginia.edu
115 The rest of the documentation details each of the object methods.
116 Internal methods are usually preceded with a _
120 # Let the code begin...
122 package Bio
::Tree
::NodeI
;
124 no warnings
'recursion';
126 use base
qw(Bio::Root::RootI);
128 =head2 add_Descendent
130 Title : add_Descendent
131 Usage : $node->add_Descendent($node);
132 Function: Adds a descendent to a node
133 Returns : number of current descendents for this node
134 Args : Bio::Node::NodeI
140 my ($self,@args) = @_;
142 $self->throw_not_implemented();
146 =head2 each_Descendent
148 Title : each_Descendent
149 Usage : my @nodes = $node->each_Descendent;
150 Function: all the descendents for this Node (but not their descendents
151 i.e. not a recursive fetchall)
152 Returns : Array of Bio::Tree::NodeI objects
159 $self->throw_not_implemented();
162 =head2 Decorated Interface methods
166 =head2 get_all_Descendents
168 Title : get_all_Descendents($sortby)
169 Usage : my @nodes = $node->get_all_Descendents;
170 Function: Recursively fetch all the nodes and their descendents
171 *NOTE* This is different from each_Descendent
172 Returns : Array or Bio::Tree::NodeI objects
173 Args : $sortby [optional] "height", "creation", "alpha", "revalpha",
174 or a coderef to be used to sort the order of children nodes.
178 sub get_all_Descendents
{
179 my ($self, $sortby) = @_;
182 foreach my $node ( $self->each_Descendent($sortby) ) {
183 push @nodes, ($node,$node->get_all_Descendents($sortby));
188 *get_Descendents
= \
&get_all_Descendents
;
193 Usage : if( $node->is_Leaf )
194 Function: Get Leaf status
202 $self->throw_not_implemented();
205 =head2 descendent_count
207 Title : descendent_count
208 Usage : my $count = $node->descendent_count;
209 Function: Counts the number of descendents a node has
210 (and all of their subnodes)
216 sub descendent_count
{
220 foreach my $node ( $self->each_Descendent ) {
222 $node->can('descendent_count') ?
$count += $node->descendent_count : next;
230 Usage : my $str = $node->to_string()
231 Function: For debugging, provide a node as a string
240 return join('',defined $self->id_output ?
$self->id_output : '',
241 defined $self->branch_length ?
':' . $self->branch_length
248 Usage : my $len = $node->height
249 Function: Returns the height of the tree starting at this
250 node. Height is the maximum branchlength to get to the tip.
251 Returns : The longest length (weighting branches with branch_length) to a leaf
259 return 0 if( $self->is_Leaf );
262 foreach my $subnode ( $self->each_Descendent ) {
263 my $s = $subnode->height + $subnode->branch_length;;
264 if( $s > $max ) { $max = $s; }
272 Usage : my $len = $node->depth
273 Function: Returns the depth of the tree starting at this
274 node. Depth is the distance from this node to the root.
275 Returns : The branch length to the root.
285 while( defined $node->ancestor ) {
286 $depth += $node->branch_length;
287 $node = $node->ancestor;
292 =head2 Get/Set methods
298 Title : branch_length
299 Usage : $obj->branch_length()
300 Function: Get/Set the branch length
301 Returns : value of branch_length
302 Args : newvalue (optional)
309 $self->throw_not_implemented();
315 Usage : $obj->id($newval)
316 Function: The human readable identifier for the node
317 Returns : value of human readable id
318 Args : newvalue (optional)
325 $self->throw_not_implemented();
331 Usage : my $internalid = $node->internal_id
332 Function: Returns the internal unique id for this Node
340 $self->throw_not_implemented();
346 Usage : $obj->description($newval)
347 Function: Get/Set the description string
348 Returns : value of description
349 Args : newvalue (optional)
356 $self->throw_not_implemented();
362 Usage : $obj->bootstrap($newval)
363 Function: Get/Set the bootstrap value
364 Returns : value of bootstrap
365 Args : newvalue (optional)
372 $self->throw_not_implemented();
378 Usage : my $node = $node->ancestor;
379 Function: Get/Set the ancestor node pointer for a Node
380 Returns : Null if this is top level node
387 my ($self,@args) = @_;
388 $self->throw_not_implemented();
391 =head2 invalidate_height
393 Title : invalidate_height
394 Usage : private helper method
395 Function: Invalidate our cached value of the node height in the tree
401 sub invalidate_height
{
402 shift->throw_not_implemented();
405 =head2 Methods for associating Tag/Values with a Node
407 These methods associate tag/value pairs with a Node
411 Title : set_tag_value
412 Usage : $node->set_tag_value($tag,$value)
413 $node->set_tag_value($tag,@values)
414 Function: Sets a tag value(s) to a node. Replaces old values.
415 Returns : number of values stored for this tag
416 Args : $tag - tag name
417 $value - value to store for the tag
422 shift->throw_not_implemented();
427 Title : add_tag_value
428 Usage : $node->add_tag_value($tag,$value)
429 Function: Adds a tag value to a node
430 Returns : number of values stored for this tag
431 Args : $tag - tag name
432 $value - value to store for the tag
438 shift->throw_not_implemented();
444 Usage : $node->remove_tag($tag)
445 Function: Remove the tag and all values for this tag
446 Returns : boolean representing success (0 if tag does not exist)
447 Args : $tag - tagname to remove
453 shift->throw_not_implemented();
456 =head2 remove_all_tags
458 Title : remove_all_tags
459 Usage : $node->remove_all_tags()
460 Function: Removes all tags
468 shift->throw_not_implemented();
474 Usage : my @tags = $node->get_all_tags()
475 Function: Gets all the tag names for this Node
476 Returns : Array of tagnames
483 shift->throw_not_implemented();
486 =head2 get_tag_values
488 Title : get_tag_values
489 Usage : my @values = $node->get_tag_values($tag)
490 Function: Gets the values for given tag ($tag)
491 Returns : Array of values or empty list if tag does not exist
492 Args : $tag - tag name
498 shift->throw_not_implemented();
504 Usage : $node->has_tag($tag)
505 Function: Boolean test if tag exists in the Node
507 Args : $tag - tagname
513 shift->throw_not_implemented();
517 =head2 Helper Functions
524 Usage : my $id = $node->id_output;
525 Function: Return an id suitable for output in format like newick
526 so that if it contains spaces or ():; characters it is properly
528 Returns : $id string if $node->id has a value
537 return unless( defined $id && length($id ) );
538 # single quotes must become double quotes
540 if( $id =~ /[\(\);:,\s]/ ) {