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

🌸 NAME 🌸

Bio::Tools::Run::Phylo::Phyml — the wrapper that lets you do rapid reconstruction of phylogenies using Phyml. Yes bestie, this is the Bio::T...::Phyml(3pm) page, and we're reading it together 💖

---

✨ SYNOPSIS ✨

Okay so here's the whole vibe in code form, no notes:

use Bio::Tools::Run::Phylo::Phyml;

#  Make a Phyml factory
$factory = Bio::Tools::Run::Phylo::Phyml->new(-verbose => 2);
# it defaults to protein alignment
# change parameters
$factory->model('Dayhoff');
#  Pass the factory an alignment and run
$inputfilename = 't/data/protpars.phy';
$tree = $factory->run($inputfilename); # $tree is a Bio::Tree::Tree object.

# or set parameters at object creation
my %args = (
    -data_type => 'dna',
    -model => 'HKY',
    -kappa => 4,
    -invar => 'e',
    -category_number => 4,
    -alpha => 'e',
    -tree => 'BIONJ',
    -opt_topology => '0',
    -opt_lengths => '1',
    );
$factory = Bio::Tools::Run::Phylo::Phyml->new(%args);
# if you need the output files do
$factory->save_tempfiles(1);
$factory->tempdir($workdir);

# and get a Bio::Align::AlignI (SimpleAlign) object from somewhere
$tree = $factory->run($aln);

Periodt. That's the whole thing. 🫶

---

💫 DESCRIPTION 💫

So basically this is a wrapper for running the phyml application by Stephane Guindon and Olivier Gascuel. You can download it from:

http://atgc.lirmm.fr/phyml/

🎀 Installing 🎀

After downloading, you need to rename the copy of the program that runs under your operating system. I.e. phyml_linux into phyml.

You will need to help this Phyml wrapper find the phyml program. This can be done in (at least) three ways:

1. Make sure the Phyml executable is in your path. Copy it to, or create a symbolic link from a directory that is in your path.
2. Define an environmental variable PHYMLDIR which is a directory which contains the 'phyml' application. In bash:

export PHYMLDIR=/home/username/phyml_v2.4.4/exe

In csh/tcsh:

setenv PHYMLDIR /home/username/phyml_v2.4.4/exe

3. Include a definition of an environmental variable PHYMLDIR in every script that will use this Phyml wrapper module, e.g.:

BEGIN { $ENV{PHYMLDIR} = '/home/username/phyml_v2.4.4/exe' }
use Bio::Tools::Run::Phylo::Phyml;

🌈 Running 🌈

This wrapper has been tested with PHYML v2.4.4 and v.3.0. It may work with recent Phyml releases using a date format for the format, but the wrapper hasn't been extensively tested in these cases, so for the moment only the simpler numbered versions are supported. Lowkey important, bestie.

In its current state, the wrapper supports only input of one MSA and output of one tree. It can easily be extended to support more advanced capabilities of phyml.

Two convienience methods have been added on top of the standard BioPerl WrapperBase ones: stats() and tree_string(). You can call them to after running the phyml program to retrieve into a string the statistics and the tree in Newick format. Obsessed, honestly. ✨

---

💌 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. (fr fr, the more context the better 💅)

🐛 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 - Heikki Lehvaslaiho 👑

heikki at bioperl dot org

---

more coming, bestie — don't go anywhere 💜

✨ APPENDIX ✨

okay bestie, here's the deep lore 💅 the rest of the docs walk through every single object method one by one. and psst — the internal ones (the ones with a lil underscore _ in front) are private, so don't go poking them from outside the class, mkay?

---

🌸 new

• Title — new
• Usage — $factory = Bio::Tools::Run::Phylo::Phyml->new(@params)
• Function — spins up a brand new Phyml factory, iconic behaviour ✨
• Returns — Bio::Tools::Run::Phylo::Phyml
• Args — optional, but you can hand it any of these (defaults are in the square brackets):

-data_type       => 'dna' or 'protein',   [protein]
-dataset_count   => integer,             [1]
-model           => 'HKY'... ,            [HKY|JTT]
-kappa           => 'e' or float,         [e]
-invar           => 'e' or float,         [e]
-category_number => integer,              [1]
-alpha           => 'e' or float (int v3),[e]
-tree            => 'BIONJ' or your own,  [BION]
-bootstrap       => integer               [123]
-opt_topology    => boolean               [1]
-opt_lengths     => boolean               [1]
-no_memory_check => boolean               [1]
-program_name    => string

🧚 program_name

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

🧚 program_dir

• Title — program_dir
• Usage — $factory->program_dir(@params)
• Function — returns the program directory, grabbed straight from an ENV variable
• Returns — string
• Args — None

🧚 version

• Title — version
• Usage — exit if $prog->version < 1.8
• Function — figures out the version number of the program
• Example —
• Returns — float or undef
• Args — none

heads up: Phyml before 3.0 did not display the version. Assume 2.44 when can not determine it.

also: some releases do not state version number, only date, so the version might have to be inferred from this date. 😭 detective work fr fr

🌈 run

• Title — run
• Usage —

$factory->run($aln_file);
$factory->run($align_object);

• Function — runs Phyml to generate a tree 🌳
• Returns — Bio::Tree::Tree object
• Args — file name for your input alignment in a format recognised by AlignIO, OR a Bio::Align::AlignI compliant object (eg. Bio::SimpleAlign).

🍓 stats

• Title — stats
• Usage — $factory->stats;
• Function — returns the contents of the phyml '_phyml_stat.txt' output file
• Returns — string with statistics about the run, undef before run()
• Args — none

🍓 tree_string

• Title — tree_string
• Usage —

$factory->tree_string;
$factory->run($align_object);

• Function — returns the contents of the phyml '_phyml_tree.txt' output file
• Returns — string with tree in Newick format, undef before run()
• Args — none

---

💅 Getsetters

these methods are used to set and get program parameters before running. get it? get + set. getsetters. the way that naming ate 😌

🦋 data_type

• Title — data_type
• Usage — $phyml->data_type('nt');
• Function — sets the sequence alphabet to 'dna' (nt in v3) or 'aa'. If leaved unset, will be set automatically
• Returns — set value, defaults to 'protein'
• Args — None to get, 'dna' ('nt') or 'aa' to set.

🦋 data_format

• Title — data_format
• Usage — $phyml->data_format('s');
• Function — sets PHYLIP format to 'i' interleaved or 's' sequential
• Returns — set value, defaults to 'i'
• Args — None to get, 'i' or 's' to set.

🦋 dataset_count

• Title — dataset_count
• Usage — $phyml->dataset_count(3);
• Function — sets the dataset number to deal with
• Returns — set value, defaults to 1
• Args — None to get, positive integer to set.

👑 model

• Title — model
• Usage — $phyml->model('HKY');
• Function — choose the substitution model to use. one of:

JC69 | K2P | F81 | HKY | F84 | TN93 | GTR (DNA)
JTT | MtREV | Dayhoff | WAG (amino acids)

v3.0:

HKY85 (default) | JC69 | K80 | F81 | F84 |
TN93 | GTR (DNA)
LG (default) | WAG | JTT | MtREV | Dayhoff | DCMut |
RtREV | CpREV | VT | Blosum62 | MtMam | MtArt |
HIVw |  HIVb (amino acids)

• Returns — name of the model, v2.4.4 defaults to {HKY|JTT}
• Args — None to get, string to set.

🦋 kappa

• Title — kappa
• Usage — $phyml->kappa(4);
• Function — sets the transition/transversion ratio, leave unset to estimate
• Returns — set value, defaults to 'e'
• Args — None to get, float or integer to set.

🦋 invar

• Title — invar
• Usage — $phyml->invar(.3);
• Function — sets the proportion of invariable sites, leave unset to estimate
• Returns — set value, defaults to 'e'
• Args — None to get, float or integer to set.

🦋 category_number

• Title — category_number
• Usage — $phyml->category_number(4);
• Function — sets the number of relative substitution rate categories
• Returns — set value, defaults to 1
• Args — None to get, integer to set.

🦋 alpha

• Title — alpha
• Usage — $phyml->alpha(1.0);
• Function — sets the gamma distribution parameter, leave unset to estimate
• Returns — set value, defaults to 'e'
• Args — None to get, float or integer to set.

🌳 tree

• Title — tree
• Usage — $phyml->tree('/tmp/tree.nwk');
• Function — sets the starting tree, leave unset to estimate a distance tree
• Returns — set value, defaults to 'BIONJ'
• Args — None to get, newick tree file name to set.

---

🫶 v2 options

these methods can be used with PhyML v2* only. vintage era, we respect it 💜

🎀 opt_topology

• Title — opt_topology
• Usage — $factory->opt_topology(1);
• Function — choose to optimise the tree topology
• Returns — 1 or 0. Default is 1.
• Args — None to get, boolean to set.

v2.* only

🎀 opt_lengths

• Title — opt_lengths
• Usage — $factory->opt_lengths(0);
• Function — choose to optimise branch lengths and rate parameters
• Returns — 1 or 0. Default is 1.
• Args — None to get, boolean to set.

v2.* only

---

🔥 v3 options

these methods can be used with PhyML v3* only. the glow-up era, no cap ✨

⭐ freq

• Title — freq
• Usage — $phyml->freq(e); $phyml->freq("0.2, 0.6, 0.6, 0.2");
• Function — sets nucleotide frequences or asks residue to be estimated according to two models: e or d
• Returns — set value,
• Args — None to get, string to set.

v3 only.

⭐ opt

• Title — opt
• Usage — $factory->opt(1);
• Function — optimise tree parameters: tlr|tl|tr|l|n
• Returns — {value|n} (default n)
• Args — None to get, string to set.

v3.* only

⭐ search

• Title — search
• Usage — $factory->search(SPR);
• Function — tree topology search operation algorithm: NNI|SPR|BEST
• Returns — string (defaults to NNI)
• Args — None to get, string to set.

v3.* only

⭐ rand_start

• Title — rand_start
• Usage — $factory->rand_start(1);
• Function — sets the initial SPR tree to random.
• Returns — boolean (defaults to false)
• Args — None to get, boolean to set.

v3.* only; only meaningful if $prog->search is 'SPR'

⭐ rand_starts

• Title — rand_starts
• Usage — $factory->rand_starts(10);
• Function — sets the number of initial random SPR trees
• Returns — integer (defaults to 1)
• Args — None to get, integer to set.

v3.* only; only valid if $prog->search is 'SPR'

⭐ rand_seed

• Title — rand_seed
• Usage — $factory->rand_seed(1769876);
• Function — seeds the random number generator
• Returns — random integer
• Args — None to get, integer to set.

v3.* only; only valid if $prog->search is 'SPR'

Uses perl rand() to initialize if not explicitely set.

🧁 no_memory_check

• Title — no_memory_check
• Usage — $factory->no_memory_check(1);
• Function —
• Returns — boolean (defaults to false)
• Args — None to get, integer to set.

🧁 bootstrap

• Title — bootstrap
• Usage — $factory->bootstrap(100);
• Function — set number of bootstraps
• Returns —
• Args — None to get, integer to set.

🧁 command

• Title — command
• Usage — $factory->command(...);
• Function —
• Returns — string
• Args — None to get, integer to set.

---

🙈 Internal methods

these methods are private and should not be called outside this class. bestie i'm serious, stay out of the group chat that isn't yours 💀

💜 _setparams

• Title — _setparams
• Usage — Internal function, not to be called directly
• Function — creates a string of params to be used in the command string
• Returns — string of params
• Args — none

💜 _write_phylip_align_file

• Title — _write_phylip_align_file
• Usage — obj->__write_phylip_align_file($aln)
• Function — Internal (not to be used directly)

writes the alignment into the tmp directory in PHYLIP interlieved format

• Returns — filename
• Args — Bio::Align::AlignI

---

and that's the whole page, bestie, you made it to the end 🎀🫶 this was perl v5.36.0, dated 2023-01-22, from the Bio::T...::Phyml(3pm) manual — go build some iconic trees, you absolute legend 💖