/ 
BioPerl-1.007000_004
River stage two • 60 direct dependents • 65 total dependents
/ Bio::Tree::TreeFunctionsI

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 implementated 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 requirment
          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).