Bio::T...tistics(3pm)

📦

version 1.7.8 · 3 versions

1.7.8 · debian bookworm, debian trixie, ubuntu jammy, ubuntu noble (latest)
1.7.8 · ubuntu stonking
1.7.8 · ubuntu resolute

, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

💖 NAME 💖

Bio::Tree::Statistics — Calculate certain statistics for a Tree

(yes bestie, that's the page — Bio::T...tistics(3pm) from the User Contributed Perl Documentation, we're doing tree math today and it's gonna be iconic 🎀)

✨ SYNOPSIS ✨

use Bio::Tree::Statistics;

🌸 DESCRIPTION 🌸

Okay so, the vibe here is: this is supposed to be where Tree statistics get calculated. Originally it was the home of statistics from a Coalescent simulation. That era is over, she's reinvented herself. 💅

Now it contains several methods for calculating Tree-Trait statistics. Glow-up complete.

🫶 FEEDBACK 🫶

📬 Mailing Lists

User feedback is, like, an integral part of the evolution of this and other Bioperl modules. So if you have comments or suggestions, send them preferably to the Bioperl mailing list. Your participation is much appreciated, fr fr.

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. The reason? There are many experienced and responsive experts who will be able to look at the problem and quickly address it. So please include a thorough description of the problem, plus code and data examples if at all possible. The more tea you spill, the faster someone can help. 🍓

🐛 Reporting Bugs

Report bugs to the Bioperl bug tracking system so we can 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,$guide_tree);
Function: Calculates the bootstrap for internal nodes based on the percentage
          of times \@bs_trees agree with each internal node
Returns : L<Bio::Tree::TreeI>
Args    : Arrayref of L<Bio::Tree::TreeI>s
          Guide tree, L<Bio::Tree::TreeI>s

🔥 transfer_bootstrap_expectation 🔥

Title   : transfer_bootstrap_expectation
Usage   : my $tree_with_bs = $stats->transfer_bootstrap_expectation(\@bs_trees,$guide_tree);
Function: Calculates the Transfer Bootstrap Expectation (TBE) for internal nodes based on
          the methods outlined in Lemoine et al, Nature, 2018.
          Currently experimental.
Returns : L<Bio::Tree::TreeI>
Args    : Arrayref of L<Bio::Tree::TreeI>s
          Guide tree, L<Bio::Tree::TreeI>s

Heads up bestie: this one is marked Currently experimental. Treat it accordingly. ✨

🍒 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 — plot twist — this method returns a value even for trees with polytomies. She's flexible like that. 💅

🌳 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 — and the way that works is, one tree can store more than one trait. Multi-tasking queen. 👑

Trees have the 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, which calculates parsimony scores, and then fitch_down, which should resolve most of the trait/character state ambiguities. Two-step process, both steps serving. ✨

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 the 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 than one trait value, especially for the root node. Don't be surprised bestie, the root is doing the most.

📏 ps 📏

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, and that half is enough for calculating the resolved parsimony values. The trait/character states are commonly left in an ambiguous state. To resolve them, run fitch_down. Periodt.

⬆️ 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 it indicates that it performs the first bottom-up tree traversal that calculates the parsimony score — but usually leaves trait/character states ambiguous. If you're interested in internal trait states, running fitch_down should resolve most of the ambiguities. She's not fully committing yet, it's giving situationship. 😭

⬇️ 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). And note that it is not guaranteed that all states are completely resolved. She tries her best, okay. 🙈

🦋 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 descendants of the root in the same generation have to share the same value — no exceptions, we're keeping the group chat on the same page. 🫶