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

📦
version 1.7.8 · 3 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

💖 Bio::Tree::DistanceFactory 💖

okay bestie, gather round, because today we're building phylogenetic trees from distance matrices and it's gonna be iconic. this is Bio::Tree::DistanceFactory, a lil factory class from the Perl world (User Contributed Perl Documentation, if you're keeping score 🎀), and it's here to turn your pairwise sequence distances into an actual tree. no cap.

✨ SYNOPSIS ✨

use Bio::Tree::DistanceFactory;
use Bio::AlignIO;
use Bio::Align::DNAStatistics;
my $tfactory = Bio::Tree::DistanceFactory->new(-method => "NJ");
my $stats    = Bio::Align::DNAStatistics->new();

my $alnin    = Bio::AlignIO->new(-format => 'clustalw',
                                 -file   => 'file.aln');
my $aln = $alnin->next_aln;
# Of course matrix can come from a different place
# like PHYLIP if you prefer, Bio::Matrix::IO should be able
# to parse many things
my $jcmatrix = $stats->distance(-align => $aln,
                                -method => 'Jukes-Cantor');
my $tree = $tfactory->make_tree($jcmatrix);

like, look at her go 🦋. you read an alignment, you compute a distance matrix, you hand it to the factory, tree pops out. main character energy fr fr.

🌸 DESCRIPTION 🌸

so this is a factory — meaning it makes stuff for you — and the stuff it makes is a phylogenetic tree, built from the pairwise sequence distances for a set of sequences. that's the whole vibe.

right now, two tree-construction methods are implemented, and they are:

  • UPGMA (Sokal and Michener 1958)
  • NJ (Saitou and Nei 1987)

that's it, that's the menu. both iconic, both in the codebase. periodt. 👑

📚 REFERENCES 📚

the receipts, bestie — you know we cite our sources:

Eddy SR, Durbin R, Krogh A, Mitchison G, (1998) "Biological Sequence Analysis", Cambridge Univ Press, Cambridge, UK.

Howe K, Bateman A, Durbin R, (2002) "QuickTree: building huge Neighbour-Joining trees of protein sequences." Bioinformatics 18(11):1546-1547.

Saitou N and Nei M, (1987) "The neighbor-joining method: a new method for reconstructing phylogenetic trees." Mol Biol Evol 4(4):406-25.

🫶 FEEDBACK 🫶

💌 Mailing Lists

user feedback is, like, an integral part of the evolution of this and every other Bioperl module. so if you have comments or suggestions, send them preferably to the Bioperl mailing list. your participation is much appreciated, and we mean that 💜

bioperl-l@bioperl.org                  - General discussion
http://bioperl.org/wiki/Mailing_lists  - About the mailing lists

🛟 Support

okay so, for usage questions or support issues, please direct them to the mailing list:

bioperl-l@bioperl.org

rather than to the module maintainer directly. why? because there are many experienced and reponsive experts hanging out there who can look at your problem and quickly address it. team effort, slay. and please include a thorough description of the problem with code and data examples if at all possible — the more context the better, fr fr.

🐛 Reporting Bugs

found a bug? report it to the Bioperl bug tracking system so we can keep track of the bugs and their resolution. bug reports can be submitted on the web:

https://github.com/bioperl/bioperl-live/issues

👑 AUTHOR - Jason Stajich 👑

Email jason-at-bioperl.org

🧚 APPENDIX 🧚

the rest of the documentation breaks down each of the object methods, one by one. internal methods are usually preceded with an underscore (_), so if you see one of those, you know it's the behind-the-scenes stuff. iykyk 💅

🌟 new

Title   : new
Usage   : my $obj = Bio::Tree::DistanceFactory->new();
Function: Builds a new Bio::Tree::DistanceFactory object
Returns : an instance of Bio::Tree::DistanceFactory
Args    : -method => 'NJ' or 'UPGMA'

basically the constructor, bestie. builds you a brand new Bio::Tree::DistanceFactory object, hands you back an instance, and you tell it which method you want with -method => 'NJ' or -method => 'UPGMA'. pick your fighter ✨

🌟 make_tree

Title   : make_tree
Usage   : my $tree = $disttreefact->make_tree($matrix);
Function: Build a Tree based on a distance matrix
Returns : L<Bio::Tree::TreeI>
Args    : L<Bio::Matrix::MatrixI> object

the main event!! you give it a Bio::Matrix::MatrixI object, it gives you back a L<Bio::Tree::TreeI>. tree built, distance matrix consumed, we love to see it 🌈

🌟 _nj

Title   : _nj
Usage   : my $tree = $disttreefact->_nj($matrix);
Function: Construct a tree based on distance matrix using the
          Neighbor Joining algorithm (Saitou and Nei, 1987)
          Implementation based on Kevin Howe's Quicktree implementation
          and uses his tricks (some based on Bill Bruno's work) to eliminate
          negative branch lengths
Returns : L<Bio::Tree::TreeI>
Args    : L<Bio::Matrix::MatrixI> object

so this is the internal one that does the Neighbor Joining algorithm (Saitou and Nei, 1987). the implementation is based on Kevin Howe's Quicktree implementation, and it uses his tricks — some of which are based on Bill Bruno's work — to eliminate negative branch lengths. no negative branches on our watch 💀. takes a Bio::Matrix::MatrixI object, returns a L<Bio::Tree::TreeI>.

🌟 _upgma

Title   : _upgma
Usage   : my $tree = $disttreefact->_upgma($matrix);
Function: Construct a tree based on alignment using UPGMA
Returns : L<Bio::Tree::TreeI>
Args    : L<Bio::Matrix::MatrixI> object

the other internal one — constructs a tree based on alignment using UPGMA. same deal: Bio::Matrix::MatrixI object in, L<Bio::Tree::TreeI> out. 🍓

🌟 method

Title   : method
Usage   : $obj->method($newval)
Function:
Example :
Returns : value of method (a scalar)
Args    : on set, new value (a scalar or undef, optional)

a lil accessor, bestie. returns the value of method (a scalar), and on set you pass the new value — a scalar or undef, optional. lowkey simple, highkey useful. note the Function and Example slots are just... empty. she's mysterious like that 🙈

🌟 check_additivity

Title     : check_additivity
Usage     : if( $distance->check_additivity($matrix) ) {
            }
Function  : See if matrix obeys additivity principal
Returns   : boolean
Args      : Bio::Matrix::MatrixI
References: Based on a Java implementation by
            Peter Sestoft, sestoft@dina.kvl.dk 1999-12-07 version 0.3
            http://www.dina.kvl.dk/~sestoft/bsa.html
            which in turn is based on algorithms described in
            R. Durbin, S. Eddy, A. Krogh, G. Mitchison.
            Biological Sequence Analysis CUP 1998, Chapter 7.

vibe check for your matrix 🧚 — this one sees if the matrix obeys additivity principal. takes a Bio::Matrix::MatrixI, returns a boolean. perfect for an if( ... ) { } moment.

the references, for the record: based on a Java implementation by Peter Sestoft, sestoft@dina.kvl.dk 1999-12-07 version 0.3 — http://www.dina.kvl.dk/~sestoft/bsa.html — which in turn is based on algorithms described in R. Durbin, S. Eddy, A. Krogh, G. Mitchison. Biological Sequence Analysis CUP 1998, Chapter 7. academic lineage goes crazy, we love a documented ancestry 💜

okay that's the whole page!! 🎀 this lovely thing is perl v5.32.1, dated 2021-08-15, and honestly? a classic. go build some trees, bestie, you've got this 🌸🦋💖

📦 where this page comes from