Provided by: libbio-perl-perl_1.7.2-2_all bug


       Bio::Tree::Tree - An implementation of the TreeI interface.


           use Bio::TreeIO;

           # like from a TreeIO
           my $treeio = Bio::TreeIO->new(-format => 'newick', -file => 'treefile.dnd');
           my $tree = $treeio->next_tree;
           my @nodes = $tree->get_nodes;
           my $root = $tree->get_root_node;


       This object holds handles to Nodes which make up a tree.


       This implementation of Bio::Tree::Tree contains Bio::Tree:::NodeI; mainly linked via the
       root node. As NodeI can potentially contain circular references (as nodes will need to
       refer to both parent and child nodes), Bio::Tree::Tree will remove those circular
       references when the object is garbage-collected. This has some side effects; primarily,
       one must keep the Tree in scope or have at least one reference to it if working with
       nodes. The fix is to count the references to the nodes and if it is greater than expected
       retain all of them, but it requires an additional prereq and thus may not be worth the
       effort.  This only shows up in minor edge cases, though (see Bug #2869).

       Example of issue:

         # tree is not assigned to a variable, so passes from memory after
         # root node is passed
         my $root = Bio::TreeIO->new(-format => 'newick', -file => 'foo.txt')->next_tree

         # gets nothing, as all Node links are broken when Tree is garbage-collected above
         my @descendents = $root->get_all_Descendents;


   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.
                  - General discussion  - About the mailing lists

       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:

AUTHOR - Jason Stajich



       Aaron Mackey Sendu Bala Mark A. Jensen


       The rest of the documentation details each of the object methods.  Internal methods are
       usually preceded with a _

        Title   : new
        Usage   : my $obj = Bio::Tree::Tree->new();
        Function: Builds a new Bio::Tree::Tree object
        Returns : Bio::Tree::Tree
        Args    : -root     => L<Bio::Tree::NodeI> object which is the root
                  -node     => L<Bio::Tree::NodeI> object from which the root will be

                  -nodelete => boolean, whether or not to try and cleanup all
                               the nodes when this this tree goes out of scope.
                  -id       => optional tree ID
                  -score    => optional tree score value

        Title   : nodelete
        Usage   : $obj->nodelete($newval)
        Function: Get/Set Boolean whether or not to delete the underlying
                  nodes when it goes out of scope.  By default this is false
                  meaning trees are cleaned up.
        Returns : boolean
        Args    : on set, new boolean value

        Title   : get_nodes
        Usage   : my @nodes = $tree->get_nodes()
        Function: Return list of Bio::Tree::NodeI objects
        Returns : array of Bio::Tree::NodeI objects
        Args    : (named values) hash with one value
                  order => 'b|breadth' first order or 'd|depth' first order
                  sortby => [optional] "height", "creation", "alpha", "revalpha",
                  or coderef to be used to sort the order of children nodes. See L<Bio::Tree::Node> for details

        Title   : get_root_node
        Usage   : my $node = $tree->get_root_node();
        Function: Get the Top Node in the tree, in this implementation
                  Trees only have one top node.
        Returns : Bio::Tree::NodeI object
        Args    : none

        Title   : set_root_node
        Usage   : $tree->set_root_node($node)
        Function: Set the Root Node for the Tree
        Returns : Bio::Tree::NodeI
        Args    : Bio::Tree::NodeI

        Title   : total_branch_length
        Usage   : my $size = $tree->total_branch_length
        Function: Returns the sum of the length of all branches
        Returns : real
        Args    : none

        Title   : subtree_length
        Usage   : my $subtree_size = $tree->subtree_length($internal_node)
        Function: Returns the sum of the length of all branches in a subtree
                  under the node. Calculates the size of the whole tree
                  without an argument (but only if root node is defined)
        Returns : real or undef
        Args    : Bio::Tree::NodeI object, defaults to the root node

        Title   : id
        Usage   : my $id = $tree->id();
        Function: An id value for the tree
        Returns : scalar
        Args    : [optional] new value to set

        Title   : score
        Usage   : $obj->score($newval)
        Function: Sets the associated score with this tree
                  This is a generic slot which is probably best used
                  for log likelihood or other overall tree score
        Returns : value of score
        Args    : newvalue (optional)

        Title   : height
        Usage   : my $height = $tree->height
        Function: Gets the height of tree - this LOG_2($number_nodes)
                  WARNING: this is only true for strict binary trees.  The TreeIO
                  system is capable of building non-binary trees, for which this
                  method will currently return an incorrect value!!
        Returns : integer
        Args    : none

        Title   : number_nodes
        Usage   : my $size = $tree->number_nodes
        Function: Returns the number of nodes in the tree
        Returns : integer
        Args    : none

        Title   : as_text
        Usage   : my $tree_as_string = $tree->as_text($format)
        Function: Returns the tree as a string representation in the
                  desired format, e.g.: 'newick', 'nhx' or 'tabtree' (the default)
        Returns : scalar string
        Args    : format type as specified by Bio::TreeIO
        Note    : This method loads the Bio::TreeIO::$format module
                  on the fly, and commandeers the _write_tree_Helper
                  routine therein to create the tree string.

   Methods for associating Tag/Values with a Tree
       These methods associate tag/value pairs with a Tree

        Title   : set_tag_value
        Usage   : $tree->set_tag_value($tag,$value)
        Function: Sets a tag value(s) to a tree. Replaces old values.
        Returns : number of values stored for this tag
        Args    : $tag   - tag name
                  $value - value to store for the tag

        Title   : add_tag_value
        Usage   : $tree->add_tag_value($tag,$value)
        Function: Adds a tag value to a tree
        Returns : number of values stored for this tag
        Args    : $tag   - tag name
                  $value - value to store for the tag

        Title   : remove_tag
        Usage   : $tree->remove_tag($tag)
        Function: Remove the tag and all values for this tag
        Returns : boolean representing success (0 if tag does not exist)
        Args    : $tag - tagname to remove

        Title   : remove_all_tags
        Usage   : $tree->remove_all_tags()
        Function: Removes all tags
        Returns : None
        Args    : None

        Title   : get_all_tags
        Usage   : my @tags = $tree->get_all_tags()
        Function: Gets all the tag names for this Tree
        Returns : Array of tagnames
        Args    : None

        Title   : get_tag_values
        Usage   : my @values = $tree->get_tag_values($tag)
        Function: Gets the values for given tag ($tag)
        Returns : Array of values or empty list if tag does not exist
        Args    : $tag - tag name

        Title   : has_tag
        Usage   : $tree->has_tag($tag)
        Function: Boolean test if tag exists in the Tree
        Returns : Boolean
        Args    : $tag - tagname

        Title   : clone
        Alias   : _clone
        Usage   : $tree_copy = $tree->clone();
                  $subtree_copy = $tree->clone($internal_node);
        Function: Safe tree clone that doesn't segfault
        Returns : Bio::Tree::Tree object
        Args    : [optional] $start_node, Bio::Tree::Node object