1Bio::Tools::Run::Phylo:U:sPehrymClo(n3t)ributed Perl DocBuimoe:n:tTaotoilosn::Run::Phylo::Phyml(3)
2
6 Bio::Tools::Run::Phylo::Phyml - Wrapper for rapid reconstruction of
7 phylogenies using Phyml
8
10 use Bio::Tools::Run::Phylo::Phyml;
11 # Make a Phyml factory
13 $factory = Bio::Tools::Run::Phylo::Phyml->new(-verbose => 2);
14 # it defaults to protein alignment
15 # change parameters
16 $factory->model('Dayhoff');
17 # Pass the factory an alignment and run
18 $inputfilename = 't/data/protpars.phy';
19 $tree = $factory->run($inputfilename); # $tree is a Bio::Tree::Tree object.
20 # or set parameters at object creation
23 my %args = (
24 -data_type => 'dna',
25 -model => 'HKY',
26 -kappa => 4,
27 -invar => 'e',
28 -category_number => 4,
29 -alpha => 'e',
30 -tree => 'BIONJ',
31 -opt_topology => '0',
32 -opt_lengths => '1',
33 );
34 $factory = Bio::Tools::Run::Phylo::Phyml->new(%args);
35 # if you need the output files do
36 $factory->save_tempfiles(1);
37 $factory->tempdir($workdir);
38 # and get a Bio::Align::AlignI (SimpleAlign) object from somewhere
40 $tree = $factory->run($aln);
41
43 This is a wrapper for running the phyml application by Stephane Guindon
44 and Olivier Gascuel. You can download it from:
45 http://atgc.lirmm.fr/phyml/
46 Installing
48 After downloading, you need to rename a the copy of the program that
49 runs under your operating system. I.e. "phyml_linux" into "phyml".
50 You will need to help this Phyml wrapper to find the "phyml" program.
52 This can be done in (at least) three ways:
53 1. Make sure the Phyml executable is in your path. Copy it to, or
55 create a symbolic link from a directory that is in your path.
56 2. Define an environmental variable PHYMLDIR which is a directory
58 which contains the 'phyml' application: In bash:
59 export PHYMLDIR=/home/username/phyml_v2.4.4/exe
61 In csh/tcsh:
63 setenv PHYMLDIR /home/username/phyml_v2.4.4/exe
65 3. Include a definition of an environmental variable PHYMLDIR in every
67 script that will use this Phyml wrapper module, e.g.:
68 BEGIN { $ENV{PHYMLDIR} = '/home/username/phyml_v2.4.4/exe' }
70 use Bio::Tools::Run::Phylo::Phyml;
71 Running
73 This wrapper has been tested with PHYML v2.4.4 and v.3.0
74 In its current state, the wrapper supports only input of one MSA and
76 output of one tree. It can easily be extended to support more advanced
77 capabilities of "phyml".
78 Two convienience methods have been added on top of the standard BioPerl
80 WrapperBase ones: stats() and tree_string(). You can call them to after
81 running the phyml program to retrieve into a string the statistics and
82 the tree in Newick format.
83
85 Mailing Lists
86 User feedback is an integral part of the evolution of this and other
87 Bioperl modules. Send your comments and suggestions preferably to the
88 Bioperl mailing list. Your participation is much appreciated.
89 bioperl-l@bioperl.org - General discussion
91 http://bioperl.org/wiki/Mailing_lists - About the mailing lists
92 Support
94 Please direct usage questions or support issues to the mailing list:
95 bioperl-l@bioperl.org
97 rather than to the module maintainer directly. Many experienced and
99 reponsive experts will be able look at the problem and quickly address
100 it. Please include a thorough description of the problem with code and
101 data examples if at all possible.
102 Reporting Bugs
104 Report bugs to the Bioperl bug tracking system to help us keep track of
105 the bugs and their resolution. Bug reports can be submitted via the
106 web:
107 http://bugzilla.open-bio.org/
109
111 heikki at bioperl dot org
112
114 The rest of the documentation details each of the object methods.
115 Internal methods are usually preceded with a _
116 new
118 Title : new
119 Usage : $factory = Bio::Tools::Run::Phylo::Phyml->new(@params)
120 Function: creates a new Phyml factory
121 Returns : Bio::Tools::Run::Phylo::Phyml
122 Args : Optionally, provide any of the following (default in []):
123 -data_type => 'dna' or 'protein', [protein]
124 -dataset_count => 'integer, [1]
125 -model => 'HKY'... , [HKY|JTT]
126 -kappa => 'e' or float, [e]
127 -invar => 'e' or float, [e]
128 -category_number => integer, [1]
129 -alpha => 'e' or float (int v3),[e]
130 -tree => 'BIONJ' or your own, [BION]
131 -opt_topology => boolean [y]
132 -opt_lengths => boolean [y]
133 program_name
135 Title : program_name
136 Usage : $factory>program_name()
137 Function: holds the program name
138 Returns : string
139 Args : None
140 program_dir
142 Title : program_dir
143 Usage : $factory->program_dir(@params)
144 Function: returns the program directory, obtained from ENV variable.
145 Returns : string
146 Args : None
147 version
149 Title : version
150 Usage : exit if $prog->version < 1.8
151 Function: Determine the version number of the program
152 Example :
153 Returns : float or undef
154 Args : none
155 Phyml before 3.0 did not display the version. Assume 2.44 when can not
157 determine it.
158 run
160 Title : run
161 Usage : $factory->run($aln_file);
162 $factory->run($align_object);
163 Function: Runs Phyml to generate a tree
164 Returns : Bio::Tree::Tree object
165 Args : file name for your input alignment in a format
166 recognised by AlignIO, OR Bio::Align::AlignI
167 complient object (eg. Bio::SimpleAlign).
168 stats
170 Title : stats
171 Usage : $factory->stats;
172 Function: Returns the contents of the phyml '_phyml_stat.txt' output file
173 Returns : string with statistics about the run, undef before run()
174 Args : none
175 tree_string
177 Title : tree_string
178 Usage : $factory->tree_string;
179 $factory->run($align_object);
180 Function: Returns the contents of the phyml '_phyml_tree.txt' ouput file
181 Returns : string with tree in Newick format, undef before run()
182 Args : none
183 Getsetters
185 These methods are used to set and get program parameters before
186 running.
187 data_type
189 Title : data_type
190 Usage : $phyml->data_type('nt');
191 Function: Sets sequence alphabet to 'dna' (nt in v3) or 'aa'
192 If leaved unset, will be set automatically
193 Returns : set value, defaults to 'protein'
194 Args : None to get, 'dna' ('nt') or 'aa' to set.
195 data_format
197 Title : data_format
198 Usage : $phyml->data_format('s');
199 Function: Sets PHYLIP format to 'i' interleaved or
200 's' sequential
201 Returns : set value, defaults to 'i'
202 Args : None to get, 'i' or 's' to set.
203 dataset_count
205 Title : dataset_count
206 Usage : $phyml->dataset_count(3);
207 Function: Sets dataset number to deal with
208 Returns : set value, defaults to 1
209 Args : None to get, positive integer to set.
210 model
212 Title : model
213 Usage : $phyml->model('HKY');
214 Function: Choose the substitution model to use. One of
215 JC69 | K2P | F81 | HKY | F84 | TN93 | GTR (DNA)
217 JTT | MtREV | Dayhoff | WAG (amino acids)
218 v3.0:
220 HKY85 (default) | JC69 | K80 | F81 | F84 |
221 TN93 | GTR (DNA)
222 WAG (default) | JTT | MtREV | Dayhoff | DCMut |
223 RtREV | CpREV | VT | Blosum62 | MtMam | MtArt |
224 HIVw | HIVb (amino acids)
225 Returns : Name of the model, defaults to {HKY|JTT}
227 Args : None to get, string to set.
228 kappa
230 Title : kappa
231 Usage : $phyml->kappa(4);
232 Function: Sets transition/transversion ratio, leave unset to estimate
233 Returns : set value, defaults to 'e'
234 Args : None to get, float or integer to set.
235 invar
237 Title : invar
238 Usage : $phyml->invar(.3);
239 Function: Sets proportion of invariable sites, leave unset to estimate
240 Returns : set value, defaults to 'e'
241 Args : None to get, float or integer to set.
242 category_number
244 Title : category_number
245 Usage : $phyml->category_number(4);
246 Function: Sets number of relative substitution rate categories
247 Returns : set value, defaults to 1
248 Args : None to get, integer to set.
249 alpha
251 Title : alpha
252 Usage : $phyml->alpha(1.0);
253 Function: Sets gamma distribution parameter, leave unset to estimate
254 Returns : set value, defaults to 'e'
255 Args : None to get, float or integer to set.
256 tree
258 Title : tree
259 Usage : $phyml->tree('/tmp/tree.nwk');
260 Function: Sets starting tree, leave unset to estimate a distance tree
261 Returns : set value, defaults to 'BIONJ'
262 Args : None to get, newick tree file name to set.
263 v2 options
265 These methods can be used with PhyML v2* only.
266 opt_topology
268 Title : opt_topology
269 Usage : $factory->opt_topology(1);
270 Function: Choose to optimise the tree topology
271 Returns : {y|n} (default y)
272 Args : None to get, boolean to set.
273 v2.* only
275 opt_lengths
277 Title : opt_lengths
278 Usage : $factory->opt_lengths(0);
279 Function: Choose to optimise branch lengths and rate parameters
280 Returns : {y|n} (default y)
281 Args : None to get, boolean to set.
282 v2.* only
284 v3 options
286 These methods can be used with PhyML v3* only.
287 freq
289 Title : freq
290 Usage : $phyml->freq(e); $phyml->freq("0.2, 0.6, 0.6, 0.2");
291 Function: Sets nucleotide frequences or asks residue to be estimated
292 according to two models: e or d
293 Returns : set value,
294 Args : None to get, string to set.
295 v3 only.
297 opt
299 Title : opt
300 Usage : $factory->opt(1);
301 Function: Optimise tree parameters: tlr|tl|tr|l|n
302 Returns : {value|n} (default n)
303 Args : None to get, string to set.
304 v3.* only
306 search
308 Title : search
309 Usage : $factory->search(SPR);
310 Function: Tree topology search operation algorithm: NNI|SPR|BEST
311 Returns : string (defaults to NNI)
312 Args : None to get, string to set.
313 v3.* only
315 rand_start
317 Title : rand_start
318 Usage : $factory->rand_start(1);
319 Function: Sets the initial SPR tree to random.
320 Returns : boolean (defaults to false)
321 Args : None to get, boolean to set.
322 v3.* only; only meaningful if $prog->search is 'SPR'
324 rand_starts
326 Title : rand_starts
327 Usage : $factory->rand_starts(10);
328 Function: Sets the number of initial random SPR trees
329 Returns : integer (defaults to 1)
330 Args : None to get, integer to set.
331 v3.* only; only valid if $prog->search is 'SPR'
333 rand_seed
335 Title : rand_seed
336 Usage : $factory->rand_seed(1769876);
337 Function: Seeds the random number generator
338 Returns : random integer
339 Args : None to get, integer to set.
340 v3.* only; only valid if $prog->search is 'SPR'
342 Uses perl rand() to initialize if not explicitely set.
344 Internal methods
346 These methods are private and should not be called outside this class.
347 _setparams
349 Title : _setparams
350 Usage : Internal function, not to be called directly
351 Function: Creates a string of params to be used in the command string
352 Returns : string of params
353 Args : none
354 _write_phylip_align_file
356 Title : _write_phylip_align_file
357 Usage : obj->__write_phylip_align_file($aln)
358 Function: Internal (not to be used directly)
359 Writes the alignment into the tmp directory
361 in PHYLIP interlieved format
362 Returns : filename
364 Args : Bio::Align::AlignI
365perl v5.12.0 2010-04-29 Bio::Tools::Run::Phylo::Phyml(3)