Bio::Phylo::Forest::Tree - The tree object.
# 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"
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.
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.
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
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 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 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
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 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.
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
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
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.
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.
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:
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
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.
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
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
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
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
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 ) )
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
Calculates I2 imbalance.
Type : Calculation Title : calc_i2 Usage : my $ci2 = $tree->calc_i2; Function: Calculates I2 imbalance. Returns : FLOAT Args : NONE Comments:
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
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
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
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
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
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
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.
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
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
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
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
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 ';';
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 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 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 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 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 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:
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:
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:
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.
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).
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:
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:
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:
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:
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 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.
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:
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
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
The Bio::Phylo::Forest::Tree object inherits from the Bio::Phylo::Listable object, so the methods defined therein also apply to trees.
Also see the manual: Bio::Phylo::Manual.
$Id: Tree.pm 4265 2007-07-20 14:14:44Z rvosa $
