Linux Certif

Toute la documentation sur la certification Linux LPI

Bio::Tree::Statistics.3pm

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:

   http://bugzilla.open-bio.org/
 
 

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 desciptors 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.

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 calculats parsimony scores and then fitch_down that should resolve most of the trait/character state ambiguities.

Fitch, W.M., 1971. Toward dei.XXning the course of evolution: minimal change for a specii.XXc 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.

ps

   Example    : ps($tree, $key, $node);
   Description: Calculates Parsimony Score (PS) from Fitch 1971
                parsimony algorithm for the subtree a 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 ambiguos 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 a 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 guarantied 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 is a measure of the stability 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
 
 

TStatratio 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).

ai

   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.  Identii.XXcation of shared populations of human immunodei.XXciency
   Virus Type 1 infecting microglia and tissue macrophages outside the
   central nervous system. J. Virol. 75 (23), 11686-11699.
 
 

mc

   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 Immunodei.XXciency 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.