Bio/Tree/TreeI.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::Tree::TreeI
   4 #
   5 # Cared for by Jason Stajich <jason@bioperl.org>
   6 #
   7 # Copyright Jason Stajich
   8 #
   9 # You may distribute this module under the same terms as perl itself
  10
  11 # POD documentation - main docs before the code
  12
  13 =head1 NAME
  14
  15 Bio::Tree::TreeI - A Tree object suitable for lots of things, designed
  16   originally for Phylogenetic Trees.
  17
  18 =head1 SYNOPSIS
  19
  20   # get a Bio::Tree::TreeI somehow
  21   # like from a TreeIO
  22   my $treeio = new Bio::TreeIO(-format => 'newick', -file => 'treefile.dnd');
  23   my $tree   = $treeio->next_tree;
  24   my @nodes  = $tree->get_nodes;
  25   my @leaves = $tree->get_leaf_nodes;
  26   my $root   = $tree->get_root_node;
  27
  28 =head1 DESCRIPTION
  29
  30 This object holds a pointer to the Root of a Tree which is a
  31 Bio::Tree::NodeI.
  32
  33 =head1 FEEDBACK
  34
  35 =head2 Mailing Lists
  36
  37 User feedback is an integral part of the evolution of this and other
  38 Bioperl modules. Send your comments and suggestions preferably to
  39 the Bioperl mailing list.  Your participation is much appreciated.
  40
  41   bioperl-l@bioperl.org              - General discussion
  42   http://bioperl.org/MailList.shtml  - About the mailing lists
  43
  44 =head2 Reporting Bugs
  45
  46 Report bugs to the Bioperl bug tracking system to help us keep track
  47 of the bugs and their resolution. Bug reports can be submitted via
  48 the web:
  49
  50   http://bugzilla.bioperl.org/
  51
  52 =head1 AUTHOR - Jason Stajich
  53
  54 Email jason@bioperl.org
  55
  56 =head1 CONTRIBUTORS
  57
  58 Aaron Mackey amackey@virginia.edu
  59 Elia Stupka, elia@fugu-sg.org
  60
  61 =head1 APPENDIX
  62
  63 The rest of the documentation details each of the object methods.
  64 Internal methods are usually preceded with a _
  65
  66 =cut
  67
  68
  69 # Let the code begin...
  70
  71
  72 package Bio::Tree::TreeI;
  73 use Bio::Tree::NodeI;
  74 use vars qw(@ISA);
  75 use strict;
  76
  77 @ISA = qw(Bio::Tree::NodeI);
  78
  79 =head2 get_nodes
  80
  81  Title   : get_nodes
  82  Usage   : my @nodes = $tree->get_nodes()
  83  Function: Return list of Tree::NodeI objects
  84  Returns : array of Tree::NodeI objects
  85  Args    : (named values) hash with one value
  86            order => 'b|breadth' first order or 'd|depth' first order
  87
  88 =cut
  89
  90 sub get_nodes{
  91    my ($self) = @_;
  92    $self->throw_not_implemented();
  93 }
  94
  95 =head2 get_root_node
  96
  97  Title   : get_root_node
  98  Usage   : my $node = $tree->get_root_node();
  99  Function: Get the Top Node in the tree, in this implementation
 100            Trees only have one top node.
 101  Returns : Bio::Tree::NodeI object
 102  Args    : none
 103
 104 =cut
 105
 106 sub get_root_node{
 107    my ($self) = @_;
 108    $self->throw_not_implemented();
 109 }
 110
 111 =head2 number_nodes
 112
 113  Title   : number_nodes
 114  Usage   : my $size = $tree->number_nodes
 115  Function: Returns the number of nodes
 116  Example :
 117  Returns :
 118  Args    :
 119
 120
 121 =cut
 122
 123 sub number_nodes{
 124    my ($self) = @_;
 125    my $root = $self->get_root_node;
 126    if( defined $root && $root->isa('Bio::Tree::NodeI'))  {
 127        return $root->descendent_count;
 128    }
 129    return 0;
 130 }
 131
 132 =head2 total_branch_length
 133
 134  Title   : total_branch_length
 135  Usage   : my $size = $tree->total_branch_length
 136  Function: Returns the sum of the length of all branches
 137  Returns : integer
 138  Args    : none
 139
 140 =cut
 141
 142 sub total_branch_length {
 143    my ($self) = @_;
 144    $self->throw_not_implemented();
 145 }
 146
 147 =head2 height
 148
 149  Title   : height
 150  Usage   : my $height = $tree->height
 151  Function: Gets the height of tree - this LOG_2($number_nodes)
 152            WARNING: this is only true for strict binary trees.  The TreeIO
 153            system is capable of building non-binary trees, for which this
 154            method will currently return an incorrect value!!
 155  Returns : integer
 156  Args    : none
 157
 158 =cut
 159
 160 sub height{
 161    my ($self) = @_;
 162    my $nodect =  $self->number_nodes;
 163    return 0 if( ! $nodect );
 164    return log($nodect) / log(2);
 165 }
 166
 167 =head2 id
 168
 169  Title   : id
 170  Usage   : my $id = $tree->id();
 171  Function: An id value for the tree
 172  Returns : scalar
 173  Args    :
 174
 175
 176 =cut
 177
 178 sub id{
 179    my ($self,@args) = @_;
 180    $self->throw_not_implemented();
 181 }
 182
 183 =head2 score
 184
 185  Title   : score
 186  Usage   : $obj->score($newval)
 187  Function: Sets the associated score with this tree
 188            This is a generic slot which is probably best used
 189            for log likelihood or other overall tree score
 190  Returns : value of score
 191  Args    : newvalue (optional)
 192
 193
 194 =cut
 195
 196 sub score{
 197    my ($self,$value) = @_;
 198    $self->throw_not_implemented();
 199 }
 200
 201 =head2 get_leaf_nodes
 202
 203  Title   : get_leaf_nodes
 204  Usage   : my @leaves = $tree->get_leaf_nodes()
 205  Function: Returns the leaves (tips) of the tree
 206  Returns : Array of Bio::Tree::NodeI objects
 207  Args    : none
 208
 209
 210 =cut
 211
 212 sub get_leaf_nodes{
 213    my ($self) = @_;
 214    return grep { $_->is_Leaf() } $self->get_nodes(-sortby  => 'none');
 215 }
 216
 217
 218 1;