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

NAME

       Bio::Tree::TreeFunctionsI - Decorated Interface implementing basic Tree exploration
       methods

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 implemented 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.

         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://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.edu

CONTRIBUTORS

       Sendu Bala, bix@sendu.me.uk

       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 requirement
                  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).