source: branches/lib/GDE/PHYML20130708/phyml/src/help.c

Last change on this file was 10307, checked in by aboeckma, 12 years ago

added most recent version of phyml
File size: 14.9 KB
Line 
1/*
2
3PhyML:  a program that  computes maximum likelihood phylogenies from
4DNA or AA homologous sequences.
5
6Copyright (C) Stephane Guindon. Oct 2003 onward.
7
8All parts of the source except where indicated are distributed under
9the GNU public licence. See http://www.opensource.org for details.
10
11*/
12
13
14#include "help.h"
15
16
17/* int  T_MAX_FILE; */
18/* phydbl SMALL; */
19/* phydbl UNLIKELY; */
20
21//////////////////////////////////////////////////////////////
22//////////////////////////////////////////////////////////////
23
24
25void Usage()
26{
27
28  char *BOLD=(char *)mCalloc(10,sizeof(char));
29  char *FLAT=(char *)mCalloc(10,sizeof(char));
30  char *LINE=(char *)mCalloc(10,sizeof(char));
31  char *cha;
32
33
34  cha =getenv("OS");
35
36  if(cha!=NULL) 
37    {
38      strcpy(BOLD, "");
39      strcpy(FLAT, "");
40      strcpy(LINE, "");
41    } 
42  else 
43    {
44      strcpy(BOLD, "\033[00;01m");
45      strcpy(FLAT, "\033[00;00m");
46      strcpy(LINE, "\033[00;04m");
47    }
48
49  #ifdef PHYML
50  PhyML_Printf("%sNAME\n"
51         "%s\t- PhyML %s - \n\n"
52         "%s\t\''A simple, fast, and accurate algorithm to estimate\n"
53         "%s\tlarge phylogenies by maximum likelihood\''\n\n"
54         "%s\tStephane Guindon and Olivier Gascuel,\n"
55         "%s\tSystematic Biology 52(5):696-704, 2003.\n\n"
56         "%s\tPlease cite this paper if you use this software in your publications.\n",BOLD,FLAT,VERSION,FLAT,FLAT,FLAT,FLAT,FLAT);
57  #endif
58
59  #ifdef PHYTIME
60  PhyML_Printf("%sNAME\n"
61         "%s\t- PhyTime %s - \n\n"
62         "%s\t'Bayesian estimation of divergence times from large sequence alignments.'\n"
63         "%s\tStephane Guindon,\n"
64         "%s\tMolecular Biology and Evolution 27(8):1768-81, 2010.\n\n"
65         "%s\tPlease cite this paper if you use this software in your publications.\n",BOLD,FLAT,VERSION,FLAT,FLAT,FLAT,FLAT,FLAT);
66  #endif
67
68
69
70  #ifdef PHYML
71  PhyML_Printf("%s\nSYNOPSIS:\n\n"
72         "%s\tphyml %s[command args]\n",BOLD,BOLD,BOLD);
73  #endif
74  #ifdef PHYTIME
75  PhyML_Printf("%s\nSYNOPSIS:\n\n"
76         "%s\tphytime %s[command args]\n",BOLD,BOLD,BOLD);
77  #endif
78
79  #ifdef PHYML
80  PhyML_Printf("%s\n\tAll the options below are optional (except '%s-i%s' if you want to use the command-line interface).\n\n",FLAT,BOLD,FLAT); 
81  #endif
82
83  #ifdef PHYTIME
84  PhyML_Printf("%s\n\tAll the options below are optional except '%s-i%s','%s-u%s' and '%s--calibration%s'.\n\n",FLAT,BOLD,FLAT,BOLD,FLAT,BOLD,FLAT); 
85  #endif
86
87  PhyML_Printf("%s\nCommand options:\n%s",BOLD,FLAT);
88
89  PhyML_Printf("\n\t%s-i (or --input) %sseq_file_name%s\n",BOLD,LINE,FLAT); 
90  PhyML_Printf("\t\t%sseq_file_name%s is the name of the nucleotide or amino-acid sequence file in PHYLIP format.\n",LINE,FLAT);
91  PhyML_Printf("\n");
92
93  PhyML_Printf("%s\n\t-d (or --datatype) ""%sdata_type%s\n",BOLD,LINE,FLAT);
94  PhyML_Printf("\t\t%sdata_type%s is 'nt' for nucleotide (default), 'aa' for amino-acid sequences, or 'generic',\n",LINE,FLAT); 
95  PhyML_Printf("\t\t(use NEXUS file format and the 'symbols' parameter here).\n");
96  PhyML_Printf("\n");
97
98 
99  PhyML_Printf("%s\n\t-q (or --sequential)\n",BOLD);
100  PhyML_Printf("%s\t\tChanges interleaved format (default) to sequential format.\n",FLAT);
101  PhyML_Printf("\n");
102
103
104  #ifndef PHYTIME
105  PhyML_Printf("%s\n\t-n (or --multiple) ""%snb_data_sets%s\n",BOLD,LINE,FLAT);
106  PhyML_Printf("\t\t%snb_data_sets%s is an integer corresponding to the number of data sets to analyse.\n",LINE,FLAT);
107  PhyML_Printf("\n");
108  #endif
109
110
111  #ifndef PHYTIME
112  PhyML_Printf("%s\n\t-p (or --pars)%s\n",BOLD,FLAT);
113  PhyML_Printf("%s\t\tUse a minimum parsimony starting tree. This option is taken into account when the '-u' option\n",FLAT);
114  PhyML_Printf("%s\t\tis absent and when tree topology modifications are to be done.\n",FLAT);
115  PhyML_Printf("\n");
116  #endif
117
118
119  #ifndef PHYTIME
120  PhyML_Printf("%s\n\t-b (or --bootstrap) %sint%s\n",BOLD,LINE,FLAT);
121  PhyML_Printf("\t\t%sint%s >  0: %sint%s is the number of bootstrap replicates.\n",LINE,FLAT,LINE,FLAT);
122  PhyML_Printf("\t\t%sint%s =  0: neither approximate likelihood ratio test nor bootstrap values are computed.\n",LINE,FLAT);
123  PhyML_Printf("\t\t%sint%s = -1: approximate likelihood ratio test returning aLRT statistics.\n",LINE,FLAT);
124  PhyML_Printf("\t\t%sint%s = -2: approximate likelihood ratio test returning Chi2-based parametric branch supports.\n",LINE,FLAT);
125/*   PhyML_Printf("\t\t%sint%s = -3 : minimum of Chi2-based parametric and SH-like branch supports.\n",LINE,FLAT); */
126  PhyML_Printf("\t\t%sint%s = -4: SH-like branch supports alone.\n",LINE,FLAT);
127  PhyML_Printf("\t\t%sint%s = -5: (default) approximate Bayes branch supports.\n",LINE,FLAT);
128  PhyML_Printf("\n");
129  #endif
130
131
132  PhyML_Printf("%s\n\t-m (or --model) %smodel%s\n",BOLD,LINE,FLAT);
133  PhyML_Printf("\t\tmodel%s : substitution model name.\n",FLAT);
134  PhyML_Printf("\t\t%s- %sNucleotide%s-based models : %sHKY85%s (default) | %sJC69%s | %sK80%s | %sF81%s | %sF84%s | %sTN93%s | %sGTR%s | %scustom (*)%s\n",
135         FLAT,LINE,FLAT,LINE,FLAT,LINE,FLAT,LINE,FLAT,LINE,FLAT,LINE,FLAT,LINE,FLAT,LINE,FLAT,LINE,FLAT);
136  PhyML_Printf("\t\t(*) : for the custom option, a string of six digits identifies the model. For instance, 000000\n");
137  PhyML_Printf("\t\t corresponds to F81 (or JC69 provided the distribution of nucleotide frequencies is uniform).\n");
138  PhyML_Printf("\t\t 012345 corresponds to GTR. This option can be used for encoding any model that is a nested within GTR.\n");
139  PhyML_Printf("\n");
140  PhyML_Printf("\t\t%s- %sAmino-acid%s based models : %sLG%s (default) | %sWAG%s | %sJTT%s | %sMtREV%s | %sDayhoff%s | %sDCMut%s | %sRtREV%s | %sCpREV%s | %sVT%s\n",   
141         FLAT,LINE,FLAT,
142         LINE,FLAT,
143         LINE,FLAT,
144         LINE,FLAT,
145         LINE,FLAT,
146         LINE,FLAT,
147         LINE,FLAT,
148         LINE,FLAT,
149         LINE,FLAT,
150         LINE,FLAT);
151  PhyML_Printf("\t\t %sBlosum62%s | %sMtMam%s | %sMtArt%s | %sHIVw%s |  %sHIVb%s | %scustom%s\n",
152         LINE,FLAT,
153         LINE,FLAT,
154         LINE,FLAT,
155         LINE,FLAT,
156         LINE,FLAT,
157         LINE,FLAT);
158
159  PhyML_Printf("\n");
160
161  PhyML_Printf("%s\n\t--aa_rate_file %sfilename%s\n",BOLD,LINE,FLAT);
162  PhyML_Printf("\t\t%sfilename%s is the name of the file that provides the amino acid substitution rate matrix in PAML format.\n",LINE,FLAT);
163  PhyML_Printf("\t\tIt is compulsory to use this option when analysing amino acid sequences with the `custom' model.\n");
164  PhyML_Printf("\n");
165
166
167  #ifndef PHYTIME
168  PhyML_Printf("%s\n\t-f %se%s, %sm%s, or %sfA,fC,fG,fT%s\n",BOLD,LINE,BOLD,LINE,BOLD,LINE,FLAT);
169  PhyML_Printf("\t\t%se%s : the character frequencies are determined as follows : \n",LINE,FLAT);
170  PhyML_Printf("%s\t\t- %sNucleotide%s sequences: (Empirical) the equilibrium base frequencies are estimated by counting\n"
171         "\t\t the occurence of the different bases in the alignment.\n",FLAT,LINE,FLAT);
172  PhyML_Printf("%s\t\t- %sAmino-acid%s sequences: (Empirical) the equilibrium amino-acid frequencies are estimated by counting\n"
173"\t\t the occurence of the different amino-acids in the alignment.\n",FLAT,LINE,FLAT);
174  PhyML_Printf("\n");
175  PhyML_Printf("\t\t%sm%s : the character frequencies are determined as follows : \n",LINE,FLAT);
176  PhyML_Printf("%s\t\t- %sNucleotide%s sequences: (ML) the equilibrium base frequencies are estimated using maximum likelihood \n",FLAT,LINE,FLAT);
177  PhyML_Printf("%s\t\t- %sAmino-acid%s sequences: (Model) the equilibrium amino-acid frequencies are estimated using\n"
178"\t\t the frequencies defined by the substitution model.\n",FLAT,LINE,FLAT);
179  PhyML_Printf("\n");
180  PhyML_Printf("\t\t%s\"fA,fC,fG,fT\"%s : only valid for nucleotide-based models. fA, fC, fG and fT are floating numbers that \n",LINE,FLAT);
181  PhyML_Printf("\t\t correspond to the frequencies of A, C, G and T respectively (WARNING: do not use any blank space between\n");
182  PhyML_Printf("\t\t your values of nucleotide frequencies, only commas!)\n");
183  PhyML_Printf("\n");
184  #endif
185
186  #ifdef PHYTIME
187  PhyML_Printf("%s\n\t--calibration %sfilename%s\n",BOLD,LINE,FLAT);
188  PhyML_Printf("\t\t%sfilename%s is the name of the calibration file that provides a priori defined boundaries for node ages.\n",LINE,FLAT);
189  PhyML_Printf("\t\tPlease read the manual for more information about the format of this file.\n");
190  PhyML_Printf("\n");
191  #endif
192
193
194
195
196  PhyML_Printf("%s\n\t-t (or --ts/tv) %sts/tv_ratio%s\n",BOLD,LINE,FLAT);
197  PhyML_Printf("\t\tts/tv_ratio%s : transition/transversion ratio. DNA sequences only.\n",FLAT);
198  PhyML_Printf("\t\tCan be a fixed positive value (ex:4.0) or %se%s to get the maximum likelihood estimate.\n",LINE,FLAT);
199  PhyML_Printf("\n");
200
201  PhyML_Printf("%s\n\t-v (or --pinv) %sprop_invar%s\n",BOLD,LINE,FLAT);
202  PhyML_Printf("\t\tprop_invar%s : proportion of invariable sites.\n",FLAT);
203  PhyML_Printf("\t\tCan be a fixed value in the [0,1] range or %se%s to get the maximum likelihood estimate.\n",LINE,FLAT);
204  PhyML_Printf("\n");
205
206  PhyML_Printf("%s\n\t-c (or --nclasses) %snb_subst_cat%s\n",BOLD,LINE,FLAT);
207  PhyML_Printf("\t\tnb_subst_cat%s : number of relative substitution rate categories. Default : %snb_subst_cat%s=4.\n",
208         FLAT,LINE,FLAT);
209  PhyML_Printf("\t\tMust be a positive integer.\n");
210  PhyML_Printf("\n");
211 
212  PhyML_Printf("%s\n\t-a (or --alpha) %sgamma%s\n",BOLD,LINE,FLAT);
213  PhyML_Printf("\t\tgamma%s : distribution of the gamma distribution shape parameter.\n",FLAT);
214  PhyML_Printf("\t\tCan be a fixed positive value or %se%s to get the maximum likelihood estimate.\n",LINE,FLAT);
215  PhyML_Printf("\n");
216
217  #ifndef PHYTIME
218  PhyML_Printf("%s\n\t-s (or --search) %smove%s\n",BOLD,LINE,FLAT);
219  PhyML_Printf("\t\tTree topology search operation option.\n");
220  PhyML_Printf("\t\tCan be either %sNNI%s (default, fast) or %sSPR%s (a bit slower than NNI) or %sBEST%s (best of NNI and SPR search).\n",LINE,FLAT,LINE,FLAT,LINE,FLAT);
221  PhyML_Printf("\n");
222  #endif
223
224
225  PhyML_Printf("%s\n\t-u (or --inputtree) %suser_tree_file%s\n",BOLD,LINE,FLAT);
226  PhyML_Printf("\t\tuser_tree_file%s : starting tree filename. The tree must be in Newick format.\n",FLAT);
227  PhyML_Printf("\n");
228
229
230  #ifndef PHYTIME
231  PhyML_Printf("%s\n\t-o %sparams%s\n",BOLD,LINE,FLAT);
232  PhyML_Printf("\t\tThis option focuses on specific parameter optimisation.\n");
233  PhyML_Printf("\t\t%sparams%s=tlr : tree topology (t), branch length (l) and rate parameters (r) are optimised.\n",LINE,FLAT);
234  PhyML_Printf("\t\t%sparams%s=tl  : tree topology and branch length are optimised.\n",LINE,FLAT);
235  PhyML_Printf("\t\t%sparams%s=lr  : branch length and rate parameters are optimised.\n",LINE,FLAT);
236  PhyML_Printf("\t\t%sparams%s=l   : branch length are optimised.\n",LINE,FLAT);
237  PhyML_Printf("\t\t%sparams%s=r   : rate parameters are optimised.\n",LINE,FLAT);
238  PhyML_Printf("\t\t%sparams%s=n   : no parameter is optimised.\n",LINE,FLAT); 
239  PhyML_Printf("\n");
240  #endif
241
242
243  #ifndef PHYTIME
244  PhyML_Printf("%s\n\t--rand_start%s\n",BOLD,FLAT);
245  PhyML_Printf("\t\tThis option sets the initial tree to random.\n");
246  PhyML_Printf("\t\tIt is only valid if SPR searches are to be performed.\n");
247  PhyML_Printf("\n");
248  #endif
249
250  #ifndef PHYTIME
251  PhyML_Printf("%s\n\t--n_rand_starts %snum%s\n",BOLD,LINE,FLAT);
252  PhyML_Printf("\t\tnum%s is the number of initial random trees to be used.\n",FLAT);
253  PhyML_Printf("\t\tIt is only valid if SPR searches are to be performed.\n");
254  PhyML_Printf("\n");
255  #endif
256
257  PhyML_Printf("%s\n\t--r_seed %snum%s\n",BOLD,LINE,FLAT);
258  PhyML_Printf("\t\tnum%s is the seed used to initiate the random number generator.\n",FLAT);
259  PhyML_Printf("\t\tMust be an integer.\n");
260  PhyML_Printf("\n");
261
262  #ifndef PHYTIME
263  PhyML_Printf("%s\n\t--print_site_lnl%s\n",BOLD,FLAT);
264  PhyML_Printf("\t\t%sPrint the likelihood for each site in file *_phyml_lk.txt.\n",FLAT);
265  PhyML_Printf("\n");
266  #endif
267
268  #ifndef PHYTIME
269  PhyML_Printf("%s\n\t--print_trace%s\n",BOLD,FLAT);
270  PhyML_Printf("\t\t%sPrint each phylogeny explored during the tree search process\n",FLAT);
271  PhyML_Printf("\t\t%sin file *_phyml_trace.txt.\n",FLAT);
272  PhyML_Printf("\n");
273  #endif
274
275
276  PhyML_Printf("%s\n\t--run_id %sID_string%s\n",BOLD,LINE,FLAT);
277  PhyML_Printf("\t\t%sAppend the string %sID_string%s at the end of each PhyML output file.\n",FLAT,LINE,FLAT);
278  PhyML_Printf("\t\t%sThis option may be useful when running simulations involving PhyML.\n",FLAT);
279  PhyML_Printf("\n");
280 
281  PhyML_Printf("%s\n\t--quiet%s\n",BOLD,FLAT);
282  PhyML_Printf("\t\t%sNo interactive question (for running in batch mode) and quiet output.\n",FLAT);
283  PhyML_Printf("\n");
284
285
286  PhyML_Printf("%s\n\t--no_memory_check%s\n",BOLD,FLAT);
287  PhyML_Printf("\t\t%sNo interactive question for memory usage (for running in batch mode). Normal ouput otherwise.\n",FLAT);
288  PhyML_Printf("\n");
289
290  #ifndef PHYTIME
291  PhyML_Printf("%s\n\t--alias_subpatt%s\n",BOLD,FLAT);
292  PhyML_Printf("\t\t%sSite aliasing is generalized at the subtree level. Sometimes lead to faster calculations.\n",FLAT);
293  PhyML_Printf("\t\t%sSee Kosakovsky Pond SL, Muse SV, Sytematic Biology (2004) for an example.\n",FLAT);
294  PhyML_Printf("\n");
295  #endif
296
297  #ifndef PHYTIME
298  PhyML_Printf("%s\n\t--boot_progress_display %snum%s (default=20)\n",BOLD,LINE,FLAT);
299  PhyML_Printf("\t\t%snum%s is the frequency at which the bootstrap progress bar will be updated.\n",LINE,FLAT);
300  PhyML_Printf("\t\tMust be an integer.\n");
301  PhyML_Printf("\n");
302  #endif
303
304
305  #ifdef PHYTIME
306  PhyML_Printf("%s\n\t--chain_len %snum%s\n",BOLD,LINE,FLAT);
307  PhyML_Printf("\t\t%snum%s is the number of generations or runs of the Markov Chain Monte Carlo. Set to 1E+6 by default. \n",LINE,FLAT);
308  PhyML_Printf("\t\tMust be an integer.\n");
309  PhyML_Printf("\n"); 
310  #endif
311
312/*   #ifdef PHYTIME */
313/*   PhyML_Printf("%s\n\t--burnin %snum%s\n",BOLD,LINE,FLAT); */
314/*   PhyML_Printf("\t\t%snum%s is the number of generations of runs of the Markov Chain Monte Carlo during the 'burnin' period.\n",LINE,FLAT); */
315/*   PhyML_Printf("\t\t%sSet to 1E+5 by default. Must be an integer. \n",FLAT); */
316/*   PhyML_Printf("\n");   */
317/*   #endif */
318
319  #ifdef PHYTIME
320  PhyML_Printf("%s\n\t--sample_freq %snum%s\n",BOLD,LINE,FLAT);
321  PhyML_Printf("\t\tThe chain is sampled every %snum%s generations. Set to 1E+3 by default. \n",LINE,FLAT);
322  PhyML_Printf("\t\tMust be an integer.\n");
323  PhyML_Printf("\n"); 
324  #endif
325
326
327  #ifdef PHYTIME
328  PhyML_Printf("%s\n\t--no_sequences%s\n",BOLD,FLAT);
329  PhyML_Printf("\t\tUse this option to run the sampler without sequence data.\n");
330  PhyML_Printf("\n"); 
331  #endif
332
333
334  #ifdef PHYTIME
335  PhyML_Printf("%s\n\t--fastlk%s\n",BOLD,FLAT);
336  PhyML_Printf("\t\tUse the multivariate normal approximation to the likelihood and speed up calculations\n");
337  PhyML_Printf("\n"); 
338  #endif
339
340
341  #ifdef PHYML
342  PhyML_Printf("%sPHYLIP-LIKE INTERFACE\n""%s\n\tYou can also use PhyML with no argument, in this case change the value of\n",BOLD,FLAT);
343  PhyML_Printf("%s\ta parameter by typing its corresponding character as shown on screen.\n\n",FLAT);
344  #endif
345
346  #ifdef PHYML
347  PhyML_Printf("%sEXAMPLES\n\n"
348         "%s\tDNA interleaved sequence file, default parameters : ""%s  ./phyml -i seqs1"
349         "%s\n\tAA interleaved sequence file, default parameters :  ""%s  ./phyml -i seqs2 -d aa"
350         "%s\n\tAA sequential sequence file, with customization :   ""%s  ./phyml -i seqs3 -q -d aa -m JTT -c 4 -a e%s\n",BOLD,FLAT,BOLD,FLAT,BOLD,FLAT,BOLD,FLAT);
351  #endif
352
353  Exit("");
354}
355
356//////////////////////////////////////////////////////////////
357//////////////////////////////////////////////////////////////
358
359
360
Note: See TracBrowser for help on using the repository browser.