NAME

Bio::Phylo::Forest::Tree - The tree object.

SYNOPSIS

# some way to get a tree
use Bio::Phylo::IO;
my $string = '((A,B),C);';
my $forest = Bio::Phylo::IO->parse(
   -format => 'newick',
   -string => $string
);
my $tree = $forest->first;

# do something:
print $tree->calc_imbalance;

# prints "1"

DESCRIPTION

The object models a phylogenetic tree, a container of Bio::Phylo::Forest::Node objects. The tree object inherits from Bio::Phylo::Listable, so look there for more methods.

METHODS

CONSTRUCTORS

new()

Tree constructor.

Type    : Constructor
Title   : new
Usage   : my $tree = Bio::Phylo::Forest::Tree->new;
Function: Instantiates a Bio::Phylo::Forest::Tree object.
Returns : A Bio::Phylo::Forest::Tree object.
Args    : No required arguments.

new_from_bioperl()

Tree constructor from Bio::Tree::TreeI argument.

Type    : Constructor
Title   : new_from_bioperl
Usage   : my $tree = 
          Bio::Phylo::Forest::Tree->new_from_bioperl(
              $bptree           
          );
Function: Instantiates a 
          Bio::Phylo::Forest::Tree object.
Returns : A Bio::Phylo::Forest::Tree object.
Args    : A tree that implements Bio::Tree::TreeI

QUERIES

get_terminals()

Get terminal nodes.

Type    : Query
Title   : get_terminals
Usage   : my @terminals = @{ $tree->get_terminals };
Function: Retrieves all terminal nodes in
          the Bio::Phylo::Forest::Tree object.
Returns : An array reference of 
          Bio::Phylo::Forest::Node objects.
Args    : NONE
Comments: If the tree is valid, this method 
          retrieves the same set of nodes as 
          $node->get_terminals($root). However, 
          because there is no recursion it may 
          be faster. Also, the node method by 
          the same name does not see orphans.

get_internals()

Get internal nodes.

Type    : Query
Title   : get_internals
Usage   : my @internals = @{ $tree->get_internals };
Function: Retrieves all internal nodes 
          in the Bio::Phylo::Forest::Tree object.
Returns : An array reference of 
          Bio::Phylo::Forest::Node objects.
Args    : NONE
Comments: If the tree is valid, this method 
          retrieves the same set of nodes as 
          $node->get_internals($root). However, 
          because there is no recursion it may 
          be faster. Also, the node method by 
          the same name does not see orphans.

get_root()

Get root node.

Type    : Query
Title   : get_root
Usage   : my $root = $tree->get_root;
Function: Retrieves the first orphan in 
          the current Bio::Phylo::Forest::Tree
          object - which should be the root.
Returns : Bio::Phylo::Forest::Node
Args    : NONE

get_tallest_tip()

Retrieves the node furthest from the root.

Type    : Query
Title   : get_tallest_tip
Usage   : my $tip = $tree->get_tallest_tip;
Function: Retrieves the node furthest from the
          root in the current Bio::Phylo::Forest::Tree
          object.
Returns : Bio::Phylo::Forest::Node
Args    : NONE
Comments: If the tree has branch lengths, the tallest tip is
          based on root-to-tip path length, else it is based
          on number of nodes to root

get_mrca()

Get most recent common ancestor of argument nodes.

Type    : Query
Title   : get_mrca
Usage   : my $mrca = $tree->get_mrca(\@nodes);
Function: Retrieves the most recent 
          common ancestor of \@nodes
Returns : Bio::Phylo::Forest::Node
Args    : A reference to an array of 
          Bio::Phylo::Forest::Node objects 
          in $tree.

TESTS

is_rooted()

Test if tree is rooted.

Type    : Test
Title   : is_rooted
Usage   : if ( $tree->is_rooted ) {
             # do something
          }
Function: Tests whether the invocant 
          object is rooted.
Returns : BOOLEAN
Args    : NONE
Comments: A tree is considered unrooted if the basal
		   split is a polytomy

is_binary()

Test if tree is bifurcating.

Type    : Test
Title   : is_binary
Usage   : if ( $tree->is_binary ) {
             # do something
          }
Function: Tests whether the invocant 
          object is bifurcating.
Returns : BOOLEAN
Args    : NONE

is_ultrametric()

Test if tree is ultrametric.

Type    : Test
Title   : is_ultrametric
Usage   : if ( $tree->is_ultrametric(0.01) ) {
             # do something
          }
Function: Tests whether the invocant is 
          ultrametric.
Returns : BOOLEAN
Args    : Optional margin between pairwise 
          comparisons (default = 0).
Comments: The test is done by performing 
          all pairwise comparisons for
          root-to-tip path lengths. Since many 
          programs introduce rounding errors 
          in branch lengths the optional argument is
          available to test TRUE for nearly 
          ultrametric trees. For example, a value 
          of 0.01 indicates that no pairwise
          comparison may differ by more than 1%. 
          Note: behaviour is undefined for 
          negative branch lengths.

is_monophyletic()

Tests if first argument (node array ref) is monophyletic with respect to second argument.

Type    : Test
Title   : is_monophyletic
Usage   : if ( $tree->is_monophyletic(\@tips, $node) ) {
             # do something
          }
Function: Tests whether the set of \@tips is
          monophyletic w.r.t. $outgroup.
Returns : BOOLEAN
Args    : A reference to a list of nodes, and a node.
Comments: This method is essentially the
          same as 
          &Bio::Phylo::Forest::Node::is_outgroup_of.

is_clade()

Tests if argument (node array ref) forms a clade.

Type    : Test
Title   : is_clade
Usage   : if ( $tree->is_clade(\@tips) ) {
             # do something
          }
Function: Tests whether the set of 
          \@tips forms a clade
Returns : BOOLEAN
Args    : A reference to an array of 
          Bio::Phylo::Forest::Node objects.
Comments:

CALCULATIONS

calc_tree_length()

Calculates the sum of all branch lengths.

Type    : Calculation
Title   : calc_tree_length
Usage   : my $tree_length = 
          $tree->calc_tree_length;
Function: Calculates the sum of all branch 
          lengths (i.e. the tree length).
Returns : FLOAT
Args    : NONE

calc_tree_height()

Calculates the height of the tree.

Type    : Calculation
Title   : calc_tree_height
Usage   : my $tree_height = 
          $tree->calc_tree_height;
Function: Calculates the height 
          of the tree.
Returns : FLOAT
Args    : NONE
Comments: For ultrametric trees this 
          method returns the height, but 
          this is done by averaging over 
          all root-to-tip path lengths, so 
          for additive trees the result 
          should consequently be interpreted
          differently.

calc_number_of_nodes()

Calculates the number of nodes.

Type    : Calculation
Title   : calc_number_of_nodes
Usage   : my $number_of_nodes = 
          $tree->calc_number_of_nodes;
Function: Calculates the number of 
          nodes (internals AND terminals).
Returns : INT
Args    : NONE

calc_number_of_terminals()

Calculates the number of terminal nodes.

Type    : Calculation
Title   : calc_number_of_terminals
Usage   : my $number_of_terminals = 
          $tree->calc_number_of_terminals;
Function: Calculates the number 
          of terminal nodes.
Returns : INT
Args    : NONE

calc_number_of_internals()

Calculates the number of internal nodes.

Type    : Calculation
Title   : calc_number_of_internals
Usage   : my $number_of_internals = 
          $tree->calc_number_of_internals;
Function: Calculates the number 
          of internal nodes.
Returns : INT
Args    : NONE

calc_total_paths()

Calculates the sum of all root-to-tip path lengths.

Type    : Calculation
Title   : calc_total_paths
Usage   : my $total_paths = 
          $tree->calc_total_paths;
Function: Calculates the sum of all 
          root-to-tip path lengths.
Returns : FLOAT
Args    : NONE

calc_redundancy()

Calculates the amount of shared (redundant) history on the total.

Type    : Calculation
Title   : calc_redundancy
Usage   : my $redundancy = 
          $tree->calc_redundancy;
Function: Calculates the amount of shared 
          (redundant) history on the total.
Returns : FLOAT
Args    : NONE
Comments: Redundancy is calculated as
1 / ( treelength - height / ( ntax * height - height ) )

calc_imbalance()

Calculates Colless' coefficient of tree imbalance.

Type    : Calculation
Title   : calc_imbalance
Usage   : my $imbalance = $tree->calc_imbalance;
Function: Calculates Colless' coefficient 
          of tree imbalance.
Returns : FLOAT
Args    : NONE
Comments: As described in Colless, D.H., 1982. 
          The theory and practice of phylogenetic 
          systematics. Systematic Zoology 31(1): 100-104

calc_i2()

Calculates I2 imbalance.

Type    : Calculation
Title   : calc_i2
Usage   : my $ci2 = $tree->calc_i2;
Function: Calculates I2 imbalance.
Returns : FLOAT
Args    : NONE
Comments:

calc_gamma()

Calculates the Pybus gamma statistic.

Type    : Calculation
Title   : calc_gamma
Usage   : my $gamma = $tree->calc_gamma();
Function: Calculates the Pybus gamma statistic
Returns : FLOAT
Args    : NONE
Comments: As described in Pybus, O.G. and 
          Harvey, P.H., 2000. Testing
          macro-evolutionary models using 
          incomplete molecular phylogenies. 
          Proc. R. Soc. Lond. B 267, 2267-2272

calc_fiala_stemminess()

Calculates stemminess measure of Fiala and Sokal (1985).

Type    : Calculation
Title   : calc_fiala_stemminess
Usage   : my $fiala_stemminess = 
          $tree->calc_fiala_stemminess;
Function: Calculates stemminess measure 
          Fiala and Sokal (1985).
Returns : FLOAT
Args    : NONE
Comments: As described in Fiala, K.L. and 
          R.R. Sokal, 1985. Factors 
          determining the accuracy of 
          cladogram estimation: evaluation 
          using computer simulation. 
          Evolution, 39: 609-622

calc_rohlf_stemminess()

Calculates stemminess measure from Rohlf et al. (1990).

Type    : Calculation
Title   : calc_rohlf_stemminess
Usage   : my $rohlf_stemminess = 
          $tree->calc_rohlf_stemminess;
Function: Calculates stemminess measure 
          from Rohlf et al. (1990).
Returns : FLOAT
Args    : NONE
Comments: As described in Rohlf, F.J., 
          W.S. Chang, R.R. Sokal, J. Kim, 
          1990. Accuracy of estimated 
          phylogenies: effects of tree 
          topology and evolutionary model. 
          Evolution, 44(6): 1671-1684

calc_resolution()

Calculates tree resolution.

Type    : Calculation
Title   : calc_resolution
Usage   : my $resolution = 
          $tree->calc_resolution;
Function: Calculates the total number 
          of internal nodes over the
          total number of internal nodes 
          on a fully bifurcating
          tree of the same size.
Returns : FLOAT
Args    : NONE

calc_branching_times()

Calculates branching times.

Type    : Calculation
Title   : calc_branching_times
Usage   : my $branching_times = 
          $tree->calc_branching_times;
Function: Returns a two-dimensional array. 
          The first dimension consists of 
          the "records", so that in the 
          second dimension $AoA[$first][0] 
          contains the internal node references, 
          and $AoA[$first][1] the branching 
          time of the internal node. The 
          records are orderered from root to 
          tips by time from the origin.
Returns : SCALAR[][] or FALSE
Args    : NONE

calc_ltt()

Calculates lineage-through-time data points.

Type    : Calculation
Title   : calc_ltt
Usage   : my $ltt = $tree->calc_ltt;
Function: Returns a two-dimensional array. 
          The first dimension consists of the 
          "records", so that in the second 
          dimension $AoA[$first][0] contains 
          the internal node references, and
          $AoA[$first][1] the branching time 
          of the internal node, and $AoA[$first][2] 
          the cumulative number of lineages over
          time. The records are orderered from 
          root to tips by time from the origin.
Returns : SCALAR[][] or FALSE
Args    : NONE

calc_symdiff()

Calculates the symmetric difference metric between invocant and argument.

Type    : Calculation
Title   : calc_symdiff
Usage   : my $symdiff = 
          $tree->calc_symdiff($other_tree);
Function: Returns the symmetric difference 
          metric between $tree and $other_tree, 
          sensu Penny and Hendy, 1985.
Returns : SCALAR
Args    : A Bio::Phylo::Forest::Tree object
Comments: Trees in comparison must span 
          the same set of terminal taxa
          or results are meaningless.

calc_fp()

Calculates the Fair Proportion value for each terminal.

Type    : Calculation
Title   : calc_fp
Usage   : my $fp = $tree->calc_fp();
Function: Returns the Fair Proportion 
          value for each terminal
Returns : HASHREF
Args    : NONE

calc_es()

Calculates the Equal Splits value for each terminal

Type    : Calculation
Title   : calc_es
Usage   : my $es = $tree->calc_es();
Function: Returns the Equal Splits value for each terminal
Returns : HASHREF
Args    : NONE

calc_pe()

Calculates the Pendant Edge value for each terminal.

Type    : Calculation
Title   : calc_pe
Usage   : my $es = $tree->calc_pe();
Function: Returns the Pendant Edge value for each terminal
Returns : HASHREF
Args    : NONE

calc_shapley()

Calculates the Shapley value for each terminal.

Type    : Calculation
Title   : calc_shapley
Usage   : my $es = $tree->calc_shapley();
Function: Returns the Shapley value for each terminal
Returns : HASHREF
Args    : NONE

VISITOR METHODS

The following methods are a - not entirely true-to-form - implementation of the Visitor design pattern: the nodes in a tree are visited, and rather than having an object operate on them, a set of code references is used. This can be used, for example, to serialize a tree to a string format. To create a newick string without branch lengths you would use something like this (there is a more powerful 'to_newick' method, so this is just an example):

 $tree->visit_depth_first(
	'-pre_daughter'   => sub { print '('             },	
	'-post_daughter'  => sub { print ')'             },	
	'-in'             => sub { print shift->get_name },
	'-pre_sister'     => sub { print ','             },	
 );
 print ';';

visit_depth_first()

Visits nodes depth first

 Type    : Visitor method
 Title   : visit_depth_first
 Usage   : $tree->visit_depth_first( -pre => sub{ ... }, -post => sub { ... } );
 Function: Visits nodes in a depth first traversal, executes subs
 Returns : $tree
 Args    : Optional:
			-pre            => sub { print "pre: ",            shift->get_name, "\n" },
			-pre_daughter   => sub { print "pre_daughter: ",   shift->get_name, "\n" },	
			-post_daughter  => sub { print "post_daughter: ",  shift->get_name, "\n" },		
			-in             => sub { print "in: ",             shift->get_name, "\n" },
			-pre_sister     => sub { print "pre_sister: ",     shift->get_name, "\n" },	
			-post_sister    => sub { print "post_sister: ",    shift->get_name, "\n" },			
			-post           => sub { print "post: ",           shift->get_name, "\n" },
			-order          => 'ltr', # ltr = left-to-right, 'rtl' = right-to-left
 Comments:

visit_breadth_first()

Visits nodes breadth first

 Type    : Visitor method
 Title   : visit_breadth_first
 Usage   : $tree->visit_breadth_first( -pre => sub{ ... }, -post => sub { ... } );
 Function: Visits nodes in a breadth first traversal, executes handlers
 Returns : $tree
 Args    : Optional handlers in the order in which they would be executed on an internal node:
			
			# first event handler, is executed when node is reached in recursion
			-pre            => sub { print "pre: ",            shift->get_name, "\n" },
			
			# is executed if node has a sister, before sister is processed
			-pre_sister     => sub { print "pre_sister: ",     shift->get_name, "\n" },	
			
			# is executed if node has a sister, after sister is processed
			-post_sister    => sub { print "post_sister: ",    shift->get_name, "\n" },			
			
			# is executed whether or not node has sisters, if it does have sisters
			# they're processed first	
			-in             => sub { print "in: ",             shift->get_name, "\n" },			
			
			# is executed if node has a daughter, but before that daughter is processed
			-pre_daughter   => sub { print "pre_daughter: ",   shift->get_name, "\n" },
			
			# is executed if node has a daughter, after daughter has been processed	
			-post_daughter  => sub { print "post_daughter: ",  shift->get_name, "\n" },				
			
			# is executed last			
			-post           => sub { print "post: ",           shift->get_name, "\n" },
			
			# specifies traversal order, default 'ltr' means first_daugher -> next_sister
			# traversal, alternate value 'rtl' means last_daughter -> previous_sister traversal
			-order          => 'ltr', # ltr = left-to-right, 'rtl' = right-to-left
 Comments:

visit_level_order()

Visits nodes in a level order traversal.

Type    : Visitor method
Title   : visit_level_order
Usage   : $tree->visit_level_order( sub{...} );
Function: Visits nodes in a level order traversal, executes sub
Returns : $tree
Args    : A subroutine reference that operates on visited nodes.
Comments:

TREE MANIPULATION

ultrametricize()

Sets all root-to-tip path lengths equal.

Type    : Tree manipulator
Title   : ultrametricize
Usage   : $tree->ultrametricize;
Function: Sets all root-to-tip path 
          lengths equal by stretching
          all terminal branches to the 
          height of the tallest node.
Returns : The modified invocant.
Args    : NONE
Comments: This method is analogous to 
          the 'ultrametricize' command
          in Mesquite, i.e. no rate smoothing 
          or anything like that happens, just 
          a lengthening of terminal branches.

scale()

Scales the tree to the specified height.

Type    : Tree manipulator
Title   : scale
Usage   : $tree->scale($height);
Function: Scales the tree to the 
          specified height.
Returns : The modified invocant.
Args    : $height = a numerical value 
          indicating root-to-tip path length.
Comments: This method uses the 
          $tree->calc_tree_height method, and 
          so for additive trees the *average* 
          root-to-tip path length is scaled to
          $height (i.e. some nodes might be 
          taller than $height, others shorter).

resolve()

Randomly breaks polytomies.

Type    : Tree manipulator
Title   : resolve
Usage   : $tree->resolve;
Function: Randomly breaks polytomies by inserting 
          additional internal nodes.
Returns : The modified invocant.
Args    :
Comments:

prune_tips()

Prunes argument nodes from invocant.

Type    : Tree manipulator
Title   : prune_tips
Usage   : $tree->prune_tips(\@taxa);
Function: Prunes specified taxa from invocant.
Returns : A pruned Bio::Phylo::Forest::Tree object.
Args    : A reference to an array of taxon names.
Comments:

keep_tips()

Keeps argument nodes from invocant (i.e. prunes all others).

Type    : Tree manipulator
Title   : keep_tips
Usage   : $tree->keep_tips(\@taxa);
Function: Keeps specified taxa from invocant.
Returns : The pruned Bio::Phylo::Forest::Tree object.
Args    : An array ref of taxon names or a Bio::Phylo::Taxa object
Comments:

negative_to_zero()

Converts negative branch lengths to zero.

Type    : Tree manipulator
Title   : negative_to_zero
Usage   : $tree->negative_to_zero;
Function: Converts negative branch 
          lengths to zero.
Returns : The modified invocant.
Args    : NONE
Comments:

exponentiate()

Raises branch lengths to argument.

Type    : Tree manipulator
Title   : exponentiate
Usage   : $tree->exponentiate($power);
Function: Raises branch lengths to $power.
Returns : The modified invocant.
Args    : A $power in any of perl's number formats.

log_transform()

Log argument base transform branch lengths.

Type    : Tree manipulator
Title   : log_transform
Usage   : $tree->log_transform($base);
Function: Log $base transforms branch lengths.
Returns : The modified invocant.
Args    : A $base in any of perl's number formats.

remove_unbranched_internals()

Collapses internal nodes with fewer than 2 children.

Type    : Tree manipulator
Title   : remove_unbranched_internals
Usage   : $tree->remove_unbranched_internals;
Function: Collapses internal nodes 
          with fewer than 2 children.
Returns : The modified invocant.
Args    : NONE
Comments:

to_newick()

Serializes invocant to newick string.

Type    : Stringifier
Title   : to_newick
Usage   : my $string = $tree->to_newick;
Function: Turns the invocant tree object 
          into a newick string
Returns : SCALAR
Args    : NONE

to_cipres()

Converts invocant to CIPRES object.

Type    : Format converter
Title   : to_cipres
Usage   : my $ciprestree = $tree->to_cipres;
Function: Turns the invocant tree object 
          into a CIPRES CORBA compliant 
          data structure
Returns : HASHREF
Args    : NONE

REVISION

$Id: Tree.pm 4252 2007-07-19 14:39:42Z rvosa $

To install Bio::Phylo, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Bio::Phylo

CPAN shell

perl -MCPAN -e shell
install Bio::Phylo

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)