NAME

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

SYNOPSIS

           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;

DESCRIPTION

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

IMPLEMENTATION NOTE

       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
                        ->get_root_node;

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

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.

         bioperl-l@bioperl.org                  - General discussion
         http://bioperl.org/wiki/Mailing_lists  - About the mailing lists

   Support
       Please direct usage questions or support issues to the mailing list:

       bioperl-l@bioperl.org

       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://redmine.open-bio.org/projects/bioperl/

AUTHOR - Jason Stajich

       Email jason@bioperl.org

CONTRIBUTORS

       Aaron Mackey amackey@virginia.edu Sendu Bala   bix@sendu.me.uk Mark A. Jensen
       maj@fortinbras.us

APPENDIX

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

   new
        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
                     OR
                  -node     => L<Bio::Tree::NodeI> object from which the root will be
                               determined

                  -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

   nodelete
        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

   get_nodes
        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

   get_root_node
        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

   set_root_node
        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

   total_branch_length
        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

   subtree_length
        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

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

   score
        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)

   height
        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

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

   as_text
        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

   set_tag_value
        Title   : set_tag_value
        Usage   : $tree->set_tag_value($tag,$value)
                  $tree->set_tag_value($tag,@values)
        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

   add_tag_value
        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

   remove_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

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

   get_all_tags
        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

   get_tag_values
        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

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

   clone
        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