Bio::Tree::TreeFunctionsI.3pm

Langue: en

Version: 2010-05-19 (ubuntu - 24/10/10)

Section: 3 (Bibliothèques de fonctions)

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:
   http://bugzilla.open-bio.org/
 
 

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
 
 

clone()

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

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
 
 

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_traits

   Example    : $key = $stat->add_traits($tree, $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
   Caller     : main()
 
 

The trait file is a tab-delimied text file and need 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.