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

📦
version 1.7.3 · 3 versions
, in debian bookworm, ubuntu noble

💖 Bio::T...otDist(3pm) 💖

okay so bestie, welcome to the User Contributed Perl Documentation page for Bio::T...otDist(3pm). pull up a chair, grab a boba, we're doing protein distance matrices today and honestly? it's giving iconic. 🧬✨

✨ NAME ✨

Bio::Tools::Run::Phylo::Phylip::ProtDist — it's the wrapper for the phylip program protdist, no cap. 💅

🦋 SYNOPSIS 🦋

#Create a SimpleAlign object
@params = ('ktuple' => 2, 'matrix' => 'BLOSUM');
$factory = Bio::Tools::Run::Alignment::Clustalw->new(@params);
$inputfilename = 't/data/cysprot.fa';
$aln = $factory->run($inputfilename); # $aln is a SimpleAlign object.

# Create the Distance Matrix using a default PAM matrix and id name
# lengths limit of 30 note to use id name length greater than the
# standard 10 in protdist, you will need to modify the protdist source
# code

@params = ('MODEL' => 'PAM');
$protdist_factory = Bio::Tools::Run::Phylo::Phylip::ProtDist->new(@params);

my ($matrix)  = $protdist_factory->run($aln); # an array of Bio::Matrix::PhylipDist matrix

#finding the distance between two sequences
my $distance = $matrix->get_entry('protein_name_1','protein_name_2');
my @column   = $matrix->get_column('protein_name_1');
my @row      = $martrix->get_row('protein_name_1');
my @diag     = $matrix->get_diagonal();
print $matrix->print_matrix;

#Alternatively, one can create the matrix by passing in a file
#name containing a multiple alignment in phylip format
$protdist_factory = Bio::Tools::Run::Phylo::Phylip::ProtDist->new(@params);
my ($matrix)  = $protdist_factory->run('/home/shawnh/prot.phy');

# To prevent PHYLIP from truncating sequence names:
# Step 1. Shelf the original names:
  my ($aln_safe, $ref_name)=                    #   $aln_safe has serial names
             $aln->set_displayname_safe();      #   $ref_name holds original names
# Step 2. Run ProtDist and Neighbor:
  ($matrix) = $protdist_factory->
             create_distance_matrix($aln_safe); #  Use $aln_safe instead of $aln
  ($tree) = $neighbor_factory->run($matrix);
# Step 3. Retrieve orgininal OTU names:
  use Bio::Tree::Tree;
  my @nodes=$tree->get_nodes();
  foreach my $nd (@nodes){
     $nd->id($ref_name->{$nd->id_output}) if $nd->is_Leaf;
  }

🌸 DESCRIPTION 🌸

It's a wrapper for protdist (Joseph Felsentein's baby 💫) that builds a distance matrix comparing protein sequences — from either a multiple alignment file or a Bio::SimpleAlign object — and hands you back a Bio::Matrix::PhylipDist object. periodt. 🫶

VERSION Support

This wrapper currently supports v3.5 of phylip. There is also support for v3.6. slay.

🎀 PARAMETERS FOR PROTDIST COMPUTATION 🎀

MODEL

  • Title — MODEL
  • Description — (optional)

This sets the model of amino acid substitution used in the calculation of the distances. 3 different models are supported:

  • PAM — Dayhoff PAM Matrix (default)
  • KIMURA — Kimura's Distance
  • CAT — Categories Distance

Usage:

@params = ('model'=>'X');#where X is one of the values above

Defaults to PAM. For more information on the usage of the different models, please refer to the documentation defaults to Equal (0.25,0.25,0.25,0.25) found in the phylip package.

Additional models in PHYLIP 3.6:

  • PMB — Henikoff/Tillier PMB matrix
  • JTT — Jones/Taylor/Thornton

MULTIPLE

  • Title — MULTIPLE
  • Description — (optional)

This allows multiple distance matrices to be generated from multiple MSA. 👑

Usage: @params = ('MULTIPLE'=>100) where the value specifyies the number of aligments given.

ALL SUBSEQUENT PARAMETERS WILL ONLY WORK IN CONJUNCTION WITH

THE Categories Distance MODEL*

bestie read this twice. everything below this line only does anything when you're on the Categories Distance model. no exceptions, fr fr. 💀

GENCODE

  • Title — GENCODE
  • Description — (optional)

This option allows the user to select among various nuclear and mitochondrial genetic codes.

Acceptable Values:

  • U — Universal
  • M — Mitochondrial
  • V — Vertebrate mitochondrial
  • F — Fly mitochondrial
  • Y — Yeast mitochondrial

Usage: @params = ('gencode'=>'X'); where X is one of the letters above Defaults to U

CATEGORY

  • Title — CATEGORY
  • Description — (optional)

This option sets the categorization of amino acids — all have groups: (Glu Gln Asp Asn), (Lys Arg His), (Phe Tyr Trp) plus:

  • G — George/Hunt/Barker:
    • (Cys), (Met Val Leu Ileu), (Gly Ala Ser Thr Pro)
  • C — Chemical:
    • (Cys Met), (Val Leu Ileu Gly Ala Ser Thr), (Pro)
  • H — Hall:
    • (Cys), (Met Val Leu Ileu), (Gly Ala Ser Thr), (Pro)

Usage: @params = ('category'=>'X'); where X is one of the letters above Defaults to G

PROBCHANGE

  • Title — PROBCHANGE
  • Description — (optional)

This option sets the ease of changing category of amino acid. (1.0 if no difficulty of changing, less if less easy. Can't be negative)

Usage: @params = ('probchange'=>X) where 0<=X<=1 Defaults to 0.4570

TRANS

  • Title — TRANS
  • Description — (optional)

This option sets transition/transversion ratio — can be any positive number.

Usage: @params = ('trans'=>X) where X >= 0 Defaults to 2

FREQ

  • Title — FREQ
  • Description — (optional)

This option sets the frequency of each base (A,C,G,T). The sum of the frequency must sum to 1. For example A,C,G,T = (0.25,0.5,0.125,0.125)

Usage: @params = ('freq'=>('W','X','Y','Z') where W + X + Y + Z = 1 Defaults to Equal (0.25,0.25,0.25,0.25)

🫶 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 one of the Bioperl mailing lists. Your participation is much appreciated. (we literally love you for it 🥹)

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 the bugs and their resolution. Bug reports can be submitted via the web:

http://redmine.open-bio.org/projects/bioperl/

👑 AUTHOR - Shawn Hoon 👑

Email shawnh@fugu-sg.org

🌈 APPENDIX 🌈

The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _

program_name

  • Title — program_name
  • Usage — >program_name()
  • Function — holds the program name
  • Returns — string
  • Args — None

program_dir

  • Title — program_dir
  • Usage — ->program_dir()
  • Function — returns the program directory, obtained from ENV variable.
  • Returns — string
  • Args —

idlength

  • Title — idlength
  • Usage — $obj->idlength ($newval)
  • Function —
  • Returns — value of idlength
  • Args — newvalue (optional)

run

  • Title — run
  • Usage —
$inputfilename = 't/data/prot.phy';
$matrix= $prodistfactory->run($inputfilename);

or

$seq_array_ref = \@seq_array; @seq_array is array of Seq objs
$aln = $protdistfactory->align($seq_array_ref);
$matrix = $protdistfactory->run($aln);
  • Function — Create a distance matrix from a SimpleAlign object or a multiple alignment file
  • Example —
  • Returns — Bio::Matrix::PhylipDist
  • Args — Name of a file containing a multiple alignment in Phylip format or an SimpleAlign object

Throws an exception if argument is not either a string (eg a filename) or a Bio::SimpleAlign object. If argument is string, throws exception if file corresponding to string name can not be found. 🚨

_run

  • Title — _run
  • Usage — Internal function, not to be called directly
  • Function — makes actual system call to protdist program
  • Example —
  • Returns — Bio::Tree object
  • Args — Name of a file containing a set of multiple alignments in Phylip format and a parameter string to be passed to protdist

create_distance_matrix

  • Title — create_distance_matrix
  • Usage — my $file = $app->create_distance_matrix($treefile);
  • Function — This method is deprecated. Please use run method. (bestie it's old news, move on 💅)
  • Returns — Bio::Matrix::PhylipDist
  • Args — Name of a file containing a multiple alignment in Phylip format or an SimpleAlign object

Throws an exception if argument is not either a string (eg a filename) or a Bio::SimpleAlign object. If argument is string, throws exception if file corresponding to string name can not be found. 🚨

_setinput()

  • Title — _setinput
  • Usage — Internal function, not to be called directly
  • Function — Create input file for protdist program
  • Example —
  • Returns — name of file containing a multiple alignment in Phylip format
  • Args — SimpleAlign object reference or input file name

_setparams()

  • Title — _setparams
  • Usage — Internal function, not to be called directly
  • Function — Create parameter inputs for protdist program
  • Example —
  • Returns — parameter string to be passed to protdist
  • Args — name of calling object

✨ Bio::Tools::Run::Wrapper methods ✨

okay so before we get into the actual ProtDist stuff, here's the lil' housekeeping squad 💅 — every single one of these comes from Bio::Tools::Run::Wrapper, the parent class doing the behind-the-scenes admin so you don't have to. They're inherited, they're handy, and they keep your run from turning into a hot mess. Let's go 🦋

🎀 no_param_checks

  • Title: no_param_checks
  • Usage: $obj->no_param_checks($newval)
  • Function: a boolean flag deciding whether we should trust the sanity checks for parameter values or just... vibe 💀
  • Returns: the value of no_param_checks
  • Args: newvalue (optional, so you can set it if you want)

tl;dr it's the "do we double-check ur params or nah" switch, bestie.

🎀 save_tempfiles

  • Title: save_tempfiles
  • Usage: $obj->save_tempfiles($newval)
  • Function: the docs literally leave this one blank 🙈 — not me inventing behaviour, i would never, i'm just telling you what's on the page
  • Returns: the value of save_tempfiles
  • Args: newvalue (optional)

🎀 outfile_name

  • Title: outfile_name
  • Usage:
my $outfile = $protdist->outfile_name();
  • Function: get/set the name of the output file for this run — for when you wanna do something special with it ✨
  • Returns: string
  • Args: [optional] string to set the value to

🎀 tempdir

  • Title: tempdir
  • Usage:
my $tmpdir = $self->tempdir();
  • Function: grab a temporary directory name (and it actually gets created, no cap — it's not just a name floating in the void)
  • Returns: string, which is the name of that temporary directory
  • Args: none

🎀 cleanup

  • Title: cleanup
  • Usage:
$codeml->cleanup();
  • Function: will cleanup the tempdir directory after a ProtDist run 🧹 (yes the example says $codeml and yes we're keeping it exactly like that, copy-paste fidelity is the whole point 💖)
  • Returns: none
  • Args: none
don't skip this one if you care about your disk, bestie. temp dirs pile up like unread notifications 😭

🎀 io

  • Title: io
  • Usage: $obj->io($newval)
  • Function: gets a Bio::Root::IO object
  • Returns: Bio::Root::IO
  • Args: none

and that's the whole wrapper gang 🫶 every one of them inherited, every one of them doing its little job so your ProtDist run stays iconic. go forth and compute, main character 👑

this page is from the Perl v5.36.0 docs, dated 2023-01-22, and the page itself is Bio::T...otDist(3pm) — mwah, take care of her 💖🎀

📦 where this page comes from