Christopher Fields > BioPerl-1.6.901 > Bio::Tree::TreeFunctionsI

Download:
BioPerl-1.6.901.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  10
Open  4
View/Report Bugs
Module Version: 1.006901   Source   Latest Release: BioPerl-1.6.924

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

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: Get the full lineage of a node (all its ancestors, in the order
           root->most recent ancestor)
 Returns : list of nodes
 Args    : either Bio::Tree::NodeI or string of the node id

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 : n/a
 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

  Example    : $key = $tree->add_trait($trait_file, 3);
  Description: Add traits to a Bio::Tree:Tree nodes
               of a tree from a file.
  Returns    : trait name
  Exceptions : log an error if a node has no value in the file
  Args       : name of trait file (scalar string), 
               index of trait file column (scalar int)
  Caller     : main()

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. Columns numbering starts from 0. The default trait column is the second (1). The returned hashref has one special key, my_trait_name, that holds the trait name. Single or double quotes are removed.

syntax highlighting: