.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Bio::Tools::Run::Phylo::Phyml 3pm"
.TH Bio::Tools::Run::Phylo::Phyml 3pm "2023-01-22" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Bio::Tools::Run::Phylo::Phyml \- Wrapper for rapid reconstruction of phylogenies using Phyml
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  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(\*(AqDayhoff\*(Aq);
\&  #  Pass the factory an alignment and run
\&  $inputfilename = \*(Aqt/data/protpars.phy\*(Aq;
\&  $tree = $factory\->run($inputfilename); # $tree is a Bio::Tree::Tree object.
\&
\&
\&  # or set parameters at object creation
\&  my %args = (
\&      \-data_type => \*(Aqdna\*(Aq,
\&      \-model => \*(AqHKY\*(Aq,
\&      \-kappa => 4,
\&      \-invar => \*(Aqe\*(Aq,
\&      \-category_number => 4,
\&      \-alpha => \*(Aqe\*(Aq,
\&      \-tree => \*(AqBIONJ\*(Aq,
\&      \-opt_topology => \*(Aq0\*(Aq,
\&      \-opt_lengths => \*(Aq1\*(Aq,
\&      );
\&  $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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
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/
.SS "Installing"
.IX Subsection "Installing"
After downloading, you need to rename a the copy of the program that
runs under your operating system. I.e. \f(CW\*(C`phyml_linux\*(C'\fR into \f(CW\*(C`phyml\*(C'\fR.
.PP
You will need to help this Phyml wrapper to find the \f(CW\*(C`phyml\*(C'\fR program.
This can be done in (at least) three ways:
.IP "1." 4
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.
.IP "2." 4
Define an environmental variable \s-1PHYMLDIR\s0 which is a
directory which contains the 'phyml' application: In bash:
.Sp
.Vb 1
\&  export PHYMLDIR=/home/username/phyml_v2.4.4/exe
.Ve
.Sp
In csh/tcsh:
.Sp
.Vb 1
\&  setenv PHYMLDIR /home/username/phyml_v2.4.4/exe
.Ve
.IP "3." 4
Include a definition of an environmental variable \s-1PHYMLDIR\s0 in
every script that will use this Phyml wrapper module, e.g.:
.Sp
.Vb 2
\&  BEGIN { $ENV{PHYMLDIR} = \*(Aq/home/username/phyml_v2.4.4/exe\*(Aq }
\&  use Bio::Tools::Run::Phylo::Phyml;
.Ve
.SS "Running"
.IX Subsection "Running"
This wrapper has been tested with \s-1PHYML\s0 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.
.PP
In its current state, the wrapper supports only input of one \s-1MSA\s0 and
output of one tree. It can easily be extended to support more advanced
capabilities of \f(CW\*(C`phyml\*(C'\fR.
.PP
Two convienience methods have been added on top of the standard
BioPerl WrapperBase ones: \fBstats()\fR and \fBtree_string()\fR. You can call them
to after running the phyml program to retrieve into a string the statistics
and the tree in Newick format.
.SH "FEEDBACK"
.IX Header "FEEDBACK"
.SS "Mailing Lists"
.IX Subsection "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.
.PP
.Vb 2
\&  bioperl\-l@bioperl.org                  \- General discussion
\&  http://bioperl.org/wiki/Mailing_lists  \- About the mailing lists
.Ve
.SS "Support"
.IX Subsection "Support"
Please direct usage questions or support issues to the mailing list:
.PP
\&\fIbioperl\-l@bioperl.org\fR
.PP
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.
.SS "Reporting Bugs"
.IX Subsection "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:
.PP
.Vb 1
\&  http://bugzilla.open\-bio.org/
.Ve
.SH "AUTHOR \- Heikki Lehvaslaiho"
.IX Header "AUTHOR - Heikki Lehvaslaiho"
heikki at bioperl dot org
.SH "APPENDIX"
.IX Header "APPENDIX"
The rest of the documentation details each of the object methods.
Internal methods are usually preceded with a _
.SS "new"
.IX Subsection "new"
.Vb 10
\& Title   : new
\& Usage   : $factory = Bio::Tools::Run::Phylo::Phyml\->new(@params)
\& Function: creates a new Phyml factory
\& Returns : Bio::Tools::Run::Phylo::Phyml
\& Args    : Optionally, provide any of the following (default in []):
\&           \-data_type       => \*(Aqdna\*(Aq or \*(Aqprotein\*(Aq,   [protein]
\&           \-dataset_count   => integer,             [1]
\&           \-model           => \*(AqHKY\*(Aq... ,            [HKY|JTT]
\&           \-kappa           => \*(Aqe\*(Aq or float,         [e]
\&           \-invar           => \*(Aqe\*(Aq or float,         [e]
\&           \-category_number => integer,              [1]
\&           \-alpha           => \*(Aqe\*(Aq or float (int v3),[e]
\&           \-tree            => \*(AqBIONJ\*(Aq or your own,  [BION]
\&           \-bootstrap       => integer               [123]
\&           \-opt_topology    => boolean               [1]
\&           \-opt_lengths     => boolean               [1]
\&           \-no_memory_check => boolean               [1]
\&           \-program_name    => string
.Ve
.SS "program_name"
.IX Subsection "program_name"
.Vb 5
\& Title   : program_name
\& Usage   : $factory>program_name()
\& Function: holds the program name
\& Returns : string
\& Args    : None
.Ve
.SS "program_dir"
.IX Subsection "program_dir"
.Vb 5
\& Title   : program_dir
\& Usage   : $factory\->program_dir(@params)
\& Function: returns the program directory, obtained from ENV variable.
\& Returns : string
\& Args    : None
.Ve
.SS "version"
.IX Subsection "version"
.Vb 6
\& Title   : version
\& Usage   : exit if $prog\->version < 1.8
\& Function: Determine the version number of the program
\& Example :
\& Returns : float or undef
\& Args    : none
.Ve
.PP
Phyml before 3.0 did not display the version. Assume 2.44 when can not
determine it.
.PP
Some releases do not state version number, only date, so the
version might have to be inferred from this date.
.SS "run"
.IX Subsection "run"
.Vb 8
\& 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  Bio::Align::AlignI
\&           compliant object (eg. Bio::SimpleAlign).
.Ve
.SS "stats"
.IX Subsection "stats"
.Vb 5
\& Title   : stats
\& Usage   : $factory\->stats;
\& Function: Returns the contents of the phyml \*(Aq_phyml_stat.txt\*(Aq output file
\& Returns : string with statistics about the run, undef before run()
\& Args    : none
.Ve
.SS "tree_string"
.IX Subsection "tree_string"
.Vb 6
\& Title   : tree_string
\& Usage   : $factory\->tree_string;
\&           $factory\->run($align_object);
\& Function: Returns the contents of the phyml \*(Aq_phyml_tree.txt\*(Aq output file
\& Returns : string with tree in Newick format, undef before run()
\& Args    : none
.Ve
.SS "Getsetters"
.IX Subsection "Getsetters"
These methods are used to set and get program parameters before running.
.SS "data_type"
.IX Subsection "data_type"
.Vb 6
\& Title   : data_type
\& Usage   : $phyml\->data_type(\*(Aqnt\*(Aq);
\& Function: Sets sequence alphabet to \*(Aqdna\*(Aq (nt in v3) or \*(Aqaa\*(Aq
\&           If leaved unset, will be set automatically
\& Returns : set value, defaults to  \*(Aqprotein\*(Aq
\& Args    : None to get, \*(Aqdna\*(Aq (\*(Aqnt\*(Aq) or \*(Aqaa\*(Aq to set.
.Ve
.SS "data_format"
.IX Subsection "data_format"
.Vb 6
\& Title   : data_format
\& Usage   : $phyml\->data_format(\*(Aqs\*(Aq);
\& Function: Sets PHYLIP format to \*(Aqi\*(Aq interleaved or
\&           \*(Aqs\*(Aq sequential
\& Returns : set value, defaults to  \*(Aqi\*(Aq
\& Args    : None to get, \*(Aqi\*(Aq or \*(Aqs\*(Aq to set.
.Ve
.SS "dataset_count"
.IX Subsection "dataset_count"
.Vb 5
\& Title   : dataset_count
\& Usage   : $phyml\->dataset_count(3);
\& Function: Sets dataset number to deal with
\& Returns : set value, defaults to 1
\& Args    : None to get, positive integer to set.
.Ve
.SS "model"
.IX Subsection "model"
.Vb 3
\& Title   : model
\& Usage   : $phyml\->model(\*(AqHKY\*(Aq);
\& 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.
.Ve
.SS "kappa"
.IX Subsection "kappa"
.Vb 5
\& Title   : kappa
\& Usage   : $phyml\->kappa(4);
\& Function: Sets transition/transversion ratio, leave unset to estimate
\& Returns : set value, defaults to \*(Aqe\*(Aq
\& Args    : None to get, float or integer to set.
.Ve
.SS "invar"
.IX Subsection "invar"
.Vb 5
\& Title   : invar
\& Usage   : $phyml\->invar(.3);
\& Function: Sets proportion of invariable sites, leave unset to estimate
\& Returns : set value, defaults to \*(Aqe\*(Aq
\& Args    : None to get, float or integer to set.
.Ve
.SS "category_number"
.IX Subsection "category_number"
.Vb 5
\& Title   : category_number
\& Usage   : $phyml\->category_number(4);
\& Function: Sets number of relative substitution rate categories
\& Returns : set value, defaults to 1
\& Args    : None to get, integer to set.
.Ve
.SS "alpha"
.IX Subsection "alpha"
.Vb 5
\& Title   : alpha
\& Usage   : $phyml\->alpha(1.0);
\& Function: Sets  gamma distribution parameter, leave unset to estimate
\& Returns : set value, defaults to \*(Aqe\*(Aq
\& Args    : None to get, float or integer to set.
.Ve
.SS "tree"
.IX Subsection "tree"
.Vb 5
\& Title   : tree
\& Usage   : $phyml\->tree(\*(Aq/tmp/tree.nwk\*(Aq);
\& Function: Sets starting tree, leave unset to estimate a distance tree
\& Returns : set value, defaults to \*(AqBIONJ\*(Aq
\& Args    : None to get, newick tree file name to set.
.Ve
.SS "v2 options"
.IX Subsection "v2 options"
These methods can be used with PhyML v2* only.
.SS "opt_topology"
.IX Subsection "opt_topology"
.Vb 5
\& 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.
.Ve
.PP
v2.* only
.SS "opt_lengths"
.IX Subsection "opt_lengths"
.Vb 5
\& 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.
.Ve
.PP
v2.* only
.SS "v3 options"
.IX Subsection "v3 options"
These methods can be used with PhyML v3* only.
.SS "freq"
.IX Subsection "freq"
.Vb 6
\& 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.
.Ve
.PP
v3 only.
.SS "opt"
.IX Subsection "opt"
.Vb 5
\& 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.
.Ve
.PP
v3.* only
.SS "search"
.IX Subsection "search"
.Vb 5
\& 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.
.Ve
.PP
v3.* only
.SS "rand_start"
.IX Subsection "rand_start"
.Vb 5
\& 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.
.Ve
.PP
v3.* only; only meaningful if \f(CW$prog\fR\->search is '\s-1SPR\s0'
.SS "rand_starts"
.IX Subsection "rand_starts"
.Vb 5
\& 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.
.Ve
.PP
v3.* only; only valid if \f(CW$prog\fR\->search is '\s-1SPR\s0'
.SS "rand_seed"
.IX Subsection "rand_seed"
.Vb 5
\& Title   : rand_seed
\& Usage   : $factory\->rand_seed(1769876);
\& Function: Seeds the random number generator
\& Returns : random integer
\& Args    : None to get, integer to set.
.Ve
.PP
v3.* only; only valid if \f(CW$prog\fR\->search is '\s-1SPR\s0'
.PP
Uses perl \fBrand()\fR to initialize if not explicitely set.
.SS "no_memory_check"
.IX Subsection "no_memory_check"
.Vb 5
\& Title   : no_memory_check
\& Usage   : $factory\->no_memory_check(1);
\& Function:
\& Returns : boolean (defaults to false)
\& Args    : None to get, integer to set.
.Ve
.SS "bootstrap"
.IX Subsection "bootstrap"
.Vb 5
\& Title   : bootstrap
\& Usage   : $factory\->bootstrap(100);
\& Function: Set number of bootstraps
\& Returns :
\& Args    : None to get, integer to set.
.Ve
.SS "command"
.IX Subsection "command"
.Vb 5
\& Title   : command
\& Usage   : $factory\->command(...);
\& Function:
\& Returns : string
\& Args    : None to get, integer to set.
.Ve
.SS "Internal methods"
.IX Subsection "Internal methods"
These methods are private and should not be called outside this class.
.SS "_setparams"
.IX Subsection "_setparams"
.Vb 5
\& 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
.Ve
.SS "_write_phylip_align_file"
.IX Subsection "_write_phylip_align_file"
.Vb 3
\& 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
.Ve