NAME¶
Bio::Tree::Statistics - Calculate certain statistics for a Tree
SYNOPSIS¶
use Bio::Tree::Statistics;
DESCRIPTION¶
This should be where Tree statistics are calculated. It was previously where
statistics from a Coalescent simulation.
It now contains several methods for calculating Tree-Trait statistics.
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¶
Email jason AT bioperl.org
CONTRIBUTORS¶
Heikki Lehvaslaiho, heikki at bioperl dot org
APPENDIX¶
The rest of the documentation details each of the object methods. Internal
methods are usually preceded with a _
new¶
Title : new
Usage : my $obj = Bio::Tree::Statistics->new();
Function: Builds a new Bio::Tree::Statistics object
Returns : Bio::Tree::Statistics
Args :
assess_bootstrap¶
Title : assess_bootstrap
Usage : my $tree_with_bs = $stats->assess_bootstrap(\@bs_trees);
Function: Calculates the bootstrap for internal nodes based on
Returns : L<Bio::Tree::TreeI>
Args : Arrayref of L<Bio::Tree::TreeI>s
cherries¶
Example : cherries($tree, $node);
Description: Count number of paired leaf nodes
in a binary tree
Returns : integer
Exceptions :
Args : 1. Bio::Tree::TreeI object
2. Bio::Tree::NodeI object within the tree, optional
Commonly used statistics assume a binary tree, but this methods returns a value
even for trees with polytomies.
Tree-Trait statistics¶
The following methods produce descriptors of trait distribution among leaf nodes
within the trees. They require that a trait has been set for each leaf node.
The tag methods of Bio::Tree::Node are used to store them as key/value pairs.
In this way, one tree can store more than one trait.
Trees have method
add_traits() to set trait values from a file. See the
add_trait() method in Bio::Tree::TreeFunctionsI.
fitch¶
Example : fitch($tree, $key, $node);
Description: Calculates Parsimony Score (PS) and internal trait
values using the Fitch 1971 parsimony algorithm for
the subtree a defined by the (internal) node.
Node defaults to the root.
Returns : true on success
Exceptions : leaf nodes have to have the trait defined
Args : 1. Bio::Tree::TreeI object
2. trait name string
3. Bio::Tree::NodeI object within the tree, optional
Runs first fitch_up that calculates parsimony scores and then fitch_down that
should resolve most of the trait/character state ambiguities.
Fitch, W.M., 1971. Toward defining the course of evolution: minimal change for a
specific tree topology. Syst. Zool. 20, 406-416.
You can access calculated parsimony values using:
$score = $node->->get_tag_values('ps_score');
and the trait value with:
$traitvalue = $node->->get_tag_values('ps_trait'); # only the first
@traitvalues = $node->->get_tag_values('ps_trait');
Note that there can be more that one trait value, especially for the root node.
Example : ps($tree, $key, $node);
Description: Calculates Parsimony Score (PS) from Fitch 1971
parsimony algorithm for the subtree as defined
by the (internal) node.
Node defaults to the root.
Returns : integer, 1 < PS < n, where n is number of branches
Exceptions : leaf nodes have to have the trait defined
Args : 1. Bio::Tree::TreeI object
2. trait name string
3. Bio::Tree::NodeI object within the tree, optional
This is the first half of the Fitch algorithm that is enough for calculating the
resolved parsimony values. The trait/chararacter states are commonly left in
ambiguous state. To resolve them, run fitch_down.
fitch_up¶
Example : fitch_up($tree, $key, $node);
Description: Calculates Parsimony Score (PS) from the Fitch 1971
parsimony algorithm for the subtree as defined
by the (internal) node.
Node defaults to the root.
Returns : integer, 1< PS < n, where n is number of branches
Exceptions : leaf nodes have to have the trait defined
Args : 1. Bio::Tree::TreeI object
2. trait name string
3. Bio::Tree::NodeI object within the tree, optional
This is a more generic name for ps and indicates that it performs the first
bottom-up tree traversal that calculates the parsimony score but usually
leaves trait/character states ambiguous. If you are interested in internal
trait states, running fitch_down should resolve most of the ambiguities.
fitch_down¶
Example : fitch_down($tree, $node);
Description: Runs the second pass from Fitch 1971
parsimony algorithm to resolve ambiguous
trait states left by first pass.
by the (internal) node.
Node defaults to the root.
Returns : true
Exceptions : dies unless the trait is defined in all nodes
Args : 1. Bio::Tree::TreeI object
2. Bio::Tree::NodeI object within the tree, optional
Before running this method you should have ran fitch_up (alias to ps ). Note
that it is not guaranteed that all states are completely resolved.
persistence¶
Example : persistence($tree, $node);
Description: Calculates the persistence
for node in the subtree defined by the (internal)
node. Node defaults to the root.
Returns : int, number of generations trait value has to remain same
Exceptions : all the nodes need to have the trait defined
Args : 1. Bio::Tree::TreeI object
2. Bio::Tree::NodeI object within the tree, optional
Persistence measures the stability that the trait value has in a tree. It
expresses the number of generations the trait value remains the same. All the
decendants of the root in the same generation have to share the same value.
Depends on Fitch's parsimony score (PS).
count_subclusters¶
Example : count_clusters($tree, $node);
Description: Calculates the number of sub-clusters
in the subtree defined by the (internal)
node. Node defaults to the root.
Returns : int, count
Exceptions : all the nodes need to have the trait defined
Args : 1. Bio::Tree::TreeI object
2. Bio::Tree::NodeI object within the tree, optional
Depends on Fitch's parsimony score (PS).
count_leaves¶
Example : count_leaves($tree, $node);
Description: Calculates the number of leaves with same trait
value as root in the subtree defined by the (internal)
node. Requires an unbroken line of identical trait values.
Node defaults to the root.
Returns : int, number of leaves with this trait value
Exceptions : all the nodes need to have the trait defined
Args : 1. Bio::Tree::TreeI object
2. Bio::Tree::NodeI object within the tree, optional
Depends on Fitch's parsimony score (PS).
phylotype_length¶
Example : phylotype_length($tree, $node);
Description: Sums up the branch lengths within phylotype
exluding the subclusters where the trait values
are different
Returns : float, length
Exceptions : all the nodes need to have the trait defined
Args : 1. Bio::Tree::TreeI object
2. Bio::Tree::NodeI object within the tree, optional
Depends on Fitch's parsimony score (PS).
sum_of_leaf_distances¶
Example : sum_of_leaf_distances($tree, $node);
Description: Sums up the branch lengths from root to leaf
exluding the subclusters where the trait values
are different
Returns : float, length
Exceptions : all the nodes need to have the trait defined
Args : 1. Bio::Tree::TreeI object
2. Bio::Tree::NodeI object within the tree, optional
Depends on Fitch's parsimony score (PS).
genetic_diversity¶
Example : genetic_diversity($tree, $node);
Description: Diversity is the sum of root to leaf distances
within the phylotype normalised by number of leaf
nodes
Returns : float, value of genetic diversity
Exceptions : all the nodes need to have the trait defined
Args : 1. Bio::Tree::TreeI object
2. Bio::Tree::NodeI object within the tree, optional
Depends on Fitch's parsimony score (PS).
statratio¶
Example : statratio($tree, $node);
Description: Ratio of the stem length and the genetic diversity of the
phylotype L<genetic_diversity>
Returns : float, separation score
Exceptions : all the nodes need to have the trait defined
Args : 1. Bio::Tree::TreeI object
2. Bio::Tree::NodeI object within the tree, optional
Statratio gives a measure of separation and variability within the phylotype.
Larger values identify more rapidly evolving and recent phylotypes.
Depends on Fitch's parsimony score (PS).
Example : ai($tree, $key, $node);
Description: Calculates the Association Index (AI) of Whang et
al. 2001 for the subtree defined by the (internal)
node. Node defaults to the root.
Returns : real
Exceptions : leaf nodes have to have the trait defined
Args : 1. Bio::Tree::TreeI object
2. trait name string
3. Bio::Tree::NodeI object within the tree, optional
Association index (AI) gives a more fine grained results than PS since
the result is a real number. ~0 E<lt>= AI.
Wang, T.H., Donaldson, Y.K., Brettle, R.P., Bell, J.E., Simmonds, P.,
2001. Identification of shared populations of human immunodeficiency
Virus Type 1 infecting microglia and tissue macrophages outside the
central nervous system. J. Virol. 75 (23), 11686-11699.
Example : mc($tree, $key, $node);
Description: Calculates the Monophyletic Clade (MC) size statistics
for the subtree a defined by the (internal) node.
Node defaults to the root;
Returns : hashref with trait values as keys
Exceptions : leaf nodes have to have the trait defined
Args : 1. Bio::Tree::TreeI object
2. trait name string
3. Bio::Tree::NodeI object within the tree, optional
Monophyletic Clade (MC) size statistics by Salemi at al 2005. It is
calculated for each trait value. 1 E<lt>= MC E<lt>= nx, where nx is the
number of tips with value x:
pick the internal node with maximim value for
number of of tips with only trait x
MC was defined by Parker et al 2008.
Salemi, M., Lamers, S.L., Yu, S., de Oliveira, T., Fitch, W.M., McGrath, M.S.,
2005. Phylodynamic analysis of Human Immunodeficiency Virus Type 1 in
distinct brain compartments provides a model for the neuropathogenesis of
AIDS. J. Virol. 79 (17), 11343-11352.
Parker, J., Rambaut A., Pybus O., 2008. Correlating viral phenotypes
with phylogeny: Accounting for phylogenetic uncertainty Infection,
Genetics and Evolution 8 (2008), 239-246.