Back to index

python-biopython  1.60
_Raxml.py
Go to the documentation of this file.
00001 # Copyright 2012 by Eric Talevich.  All rights reserved.
00002 # This code is part of the Biopython distribution and governed by its license.
00003 # Please see the LICENSE file that should have been included as part of this
00004 # package.
00005 """Command-line wrapper for the tree inference program RAxML.
00006 
00007 Derived from the help page for RAxML version 7.3 by Alexandros Stamatakis, but
00008 should work for any version 7.X (and probably earlier for most options).
00009 """
00010 __docformat__ = "restructuredtext en"
00011 
00012 from Bio.Application import _Option, _Switch, AbstractCommandline
00013 
00014 
00015 class RaxmlCommandline(AbstractCommandline):
00016     """Command-line wrapper for the tree inference program RAxML.
00017 
00018     The required parameters are 'sequences' (-s), 'model' (-m) and 'name' (-n).
00019     The parameter 'parsimony_seed' (-p) must also be set for RAxML, but if you
00020     do not specify it, this wrapper will set the seed to 10000 for you.
00021 
00022     Example:
00023 
00024     >>> from Bio.Phylo.Applications import RaxmlCommandline
00025     >>> raxml_cline = RaxmlCommandline(sequences="Tests/Phylip/interlaced2.phy",
00026     ...                                model="PROTCATWAG", name="interlaced2")
00027     >>> print raxml_cline
00028     raxmlHPC -m PROTCATWAG -n interlaced2 -p 10000 -s Tests/Phylip/interlaced2.phy
00029 
00030     You would typically run the command line with raxml_cline() or via
00031     the Python subprocess module, as described in the Biopython tutorial.
00032 
00033     Citation:
00034 
00035     Stamatakis A.
00036     RAxML-VI-HPC: Maximum Likelihood-based Phylogenetic Analyses with
00037     Thousands of Taxa and Mixed Models.
00038     Bioinformatics 2006, 22(21):2688-2690.
00039 
00040     Homepage: http://sco.h-its.org/exelixis/software.html
00041     """
00042 
00043     def __init__(self, cmd='raxmlHPC', **kwargs):
00044         self.parameters = [
00045                 _Option(['-a', 'weight_filename'],
00046                     "Name of a column weight file to assign individual weights "
00047                     "to each column of the alignment. Those weights must be "
00048                     "integers separated by any type and number of whitespaces "
00049                     "within a separate file.",
00050                     filename=True,
00051                     equate=False,
00052                     ),
00053 
00054                 _Option(['-b', 'bootstrap_seed'],
00055                     "Random seed for bootstrapping.",
00056                     equate=False,
00057                     ),
00058 
00059                 _Option(['-c', 'num_categories'],
00060                     "Number of distinct rate categories for RAxML when "
00061                     "evolution model is set to GTRCAT or GTRMIX."
00062                     "Individual per-site rates are categorized into this "
00063                     "many rate categories to accelerate computations. "
00064                     "Default: 25.",
00065                     equate=False,
00066                     ),
00067 
00068                 _Switch(['-d', 'random_starting_tree'],
00069                     "Start ML optimization from random starting tree."
00070                     ),
00071 
00072                 _Option(['-e', 'epsilon'],
00073                     "Set model optimization precision in log likelihood units "
00074                     "for final optimization of tree topology under MIX/MIXI "
00075                     "or GAMMA/GAMMAI."
00076                     "Default: 0.1 for models not using proportion of "
00077                     "invariant sites estimate; 0.001 for models using "
00078                     "proportion of invariant sites estimate.",
00079                     equate=False,
00080                     ),
00081 
00082                 _Option(['-E', 'exclude_filename'],
00083                     "An exclude file name, containing a specification of "
00084                     "alignment positions you wish to exclude.  Format is "
00085                     "similar to Nexus, the file shall contain entries like "
00086                     "'100-200 300-400'; to exclude a single column write, "
00087                     "e.g., '100-100'. If you use a mixed model, an "
00088                     "appropriately adapted model file will be written.",
00089                     filename=True,
00090                     equate=False,
00091                     ),
00092 
00093                 _Option(['-f', 'algorithm'],
00094                     """Select algorithm:
00095                     a: Rapid Bootstrap analysis and search for best-scoring ML
00096                        tree in one program run.
00097                     b: Draw bipartition information on a tree provided with '-t'
00098                        based on multiple trees (e.g. form a bootstrap) in a file
00099                        specifed by '-z'.
00100                     c: Check if the alignment can be properly read by RAxML.
00101                     d: New rapid hill-climbing (DEFAULT).
00102                     e: Optimize model+branch lengths for given input tree under
00103                        GAMMA/GAMMAI only.
00104                     g: Compute per site log Likelihoods for one ore more trees
00105                        passed via '-z' and write them to a file that can be read
00106                        by CONSEL.
00107                     h: Compute log likelihood test (SH-test) between best tree
00108                        passed via '-t' and a bunch of other trees passed via '-z'.
00109                     i: Perform a really thorough bootstrap, refinement of final
00110                        bootstrap tree under GAMMA and a more exhaustive algorithm.
00111                     j: Generate a bunch of bootstrapped alignment files from an
00112                        original alignemnt file.
00113                     m: Compare bipartitions between two bunches of trees passed
00114                        via '-t' and '-z' respectively. This will return the
00115                        Pearson correlation between all bipartitions found in the
00116                        two tree files. A file called
00117                        RAxML_bipartitionFrequencies.outputFileName will be
00118                        printed that contains the pair-wise bipartition
00119                        frequencies of the two sets.
00120                     n: Compute the log likelihood score of all trees contained
00121                        in a tree file provided by '-z' under GAMMA or
00122                        GAMMA+P-Invar.
00123                     o: Old and slower rapid hill-climbing.
00124                     p: Perform pure stepwise MP addition of new sequences to an
00125                        incomplete starting tree.
00126                     s: Split up a multi-gene partitioned alignment into the
00127                        respective subalignments.
00128                     t: Do randomized tree searches on one fixed starting tree.
00129                     w: Compute ELW test on a bunch of trees passed via '-z'.
00130                     x: Compute pair-wise ML distances, ML model parameters will
00131                        be estimated on an MP starting tree or a user-defined
00132                        tree passed via '-t', only allowed for GAMMA-based models
00133                        of rate heterogeneity.""",
00134                     checker_function=(lambda x:
00135                         isinstance(x, basestring) and len(x) == 1),
00136                     equate=False,
00137                     ),
00138 
00139                 _Option(['-g', 'grouping_constraint'],
00140                         "File name of a multifurcating constraint tree. "
00141                         "this tree does not need to be comprehensive, i.e. "
00142                         "contain all taxa.",
00143                         filename=True,
00144                         equate=False,
00145                         ),
00146 
00147                 _Option(['-i', 'rearrangements'],
00148                         "Initial rearrangement setting for the subsequent "
00149                         "application of topological changes phase.",
00150                         equate=False,
00151                         ),
00152 
00153                 _Switch(['-j', 'checkpoints'],
00154                         "Write checkpoints (intermediate tree topologies)."
00155                         ),
00156 
00157                 _Switch(['-k', 'bootstrap_branch_lengths'],
00158                         "Print bootstrapped trees with branch lengths. "
00159                         "The bootstraps will run a bit longer, because model "
00160                         "parameters will be optimized at the end of each run. "
00161                         "Use with CATMIX/PROTMIX or GAMMA/GAMMAI."
00162                         ),
00163 
00164                 _Option(['-l', 'cluster_threshold'],
00165                         "Threshold for sequence similarity clustering. "
00166                         "RAxML will then print out an alignment to a file "
00167                         "called sequenceFileName.reducedBy.threshold that "
00168                         "only contains sequences <= the specified threshold "
00169                         "that must be between 0.0 and 1.0. RAxML uses the "
00170                         "QT-clustering algorithm to perform this task. "
00171                         "In addition, a file called "
00172                         "RAxML_reducedList.outputFileName will be written "
00173                         "that contains clustering information.",
00174                         equate=False,
00175                         ),
00176 
00177                 _Option(['-L', 'cluster_threshold_fast'],
00178                         "Same functionality as '-l', but uses a less "
00179                         "exhaustive and thus faster clustering algorithm. "
00180                         "This is intended for very large datasets with more "
00181                         "than 20,000-30,000 sequences.",
00182                         equate=False,
00183                         ),
00184 
00185                 _Option(['-m', 'model'],
00186                         """Model of Nucleotide or Amino Acid Substitution:
00187 
00188               NUCLEOTIDES:
00189 
00190                     GTRCAT         : GTR + Optimization of substitution rates + Optimization of site-specific
00191                                      evolutionary rates which are categorized into numberOfCategories distinct
00192                                      rate categories for greater computational efficiency
00193                                      if you do a multiple analysis with  '-#' or '-N' but without bootstrapping the program
00194                                      will use GTRMIX instead
00195                     GTRGAMMA       : GTR + Optimization of substitution rates + GAMMA model of rate
00196                                      heterogeneity (alpha parameter will be estimated)
00197                     GTRMIX         : Inference of the tree under GTRCAT
00198                                      and thereafter evaluation of the final tree topology under GTRGAMMA
00199                     GTRCAT_GAMMA   : Inference of the tree with site-specific evolutionary rates.
00200                                      However, here rates are categorized using the 4 discrete GAMMA rates.
00201                                      Evaluation of the final tree topology under GTRGAMMA
00202                     GTRGAMMAI      : Same as GTRGAMMA, but with estimate of proportion of invariable sites
00203                     GTRMIXI        : Same as GTRMIX, but with estimate of proportion of invariable sites
00204                     GTRCAT_GAMMAI  : Same as GTRCAT_GAMMA, but with estimate of proportion of invariable sites
00205 
00206               AMINO ACIDS:
00207 
00208                     PROTCATmatrixName[F]        : specified AA matrix + Optimization of substitution rates + Optimization of site-specific
00209                                                   evolutionary rates which are categorized into numberOfCategories distinct
00210                                                   rate categories for greater computational efficiency
00211                                                   if you do a multiple analysis with  '-#' or '-N' but without bootstrapping the program
00212                                                   will use PROTMIX... instead
00213                     PROTGAMMAmatrixName[F]      : specified AA matrix + Optimization of substitution rates + GAMMA model of rate
00214                                                   heterogeneity (alpha parameter will be estimated)
00215                     PROTMIXmatrixName[F]        : Inference of the tree under specified AA matrix + CAT
00216                                                   and thereafter evaluation of the final tree topology under specified AA matrix + GAMMA
00217                     PROTCAT_GAMMAmatrixName[F]  : Inference of the tree under specified AA matrix and site-specific evolutionary rates.
00218                                                   However, here rates are categorized using the 4 discrete GAMMA rates.
00219                                                   Evaluation of the final tree topology under specified AA matrix + GAMMA
00220                     PROTGAMMAImatrixName[F]     : Same as PROTGAMMAmatrixName[F], but with estimate of proportion of invariable sites
00221                     PROTMIXImatrixName[F]       : Same as PROTMIXmatrixName[F], but with estimate of proportion of invariable sites
00222                     PROTCAT_GAMMAImatrixName[F] : Same as PROTCAT_GAMMAmatrixName[F], but with estimate of proportion of invariable sites
00223 
00224                 Available AA substitution models: DAYHOFF, DCMUT, JTT, MTREV, WAG, RTREV, CPREV, VT, BLOSUM62, MTMAM, GTR
00225                 With the optional 'F' appendix you can specify if you want to use empirical base frequencies
00226                 Please not that for mixed models you can in addition specify the per-gene AA model in
00227                 the mixed model file (see manual for details)
00228                 """,
00229                 equate=False,
00230                 ),
00231 
00232                 _Switch(['-M', 'partition_branch_lengths'],
00233                         "Switch on estimation of individual per-partition "
00234                         "branch lengths. Only has effect when used in "
00235                         "combination with 'partition_filename' ('-q'). "
00236                         "Branch lengths for individual partitions will be "
00237                         "printed to separate files.  A weighted average of the "
00238                         "branch lengths is computed by using the respective "
00239                         "partition lengths. "
00240                         ),
00241 
00242                 _Option(['-n', 'name'],
00243                         "Name used in the output files.",
00244                         filename=True,
00245                         equate=False,
00246                         ),
00247 
00248                 _Option(['-o', 'outgroup'],
00249                         "Name of a single outgroup or a comma-separated list "
00250                         "of outgroups, eg '-o Rat' or '-o Rat,Mouse'. In case "
00251                         "that multiple outgroups are not monophyletic the "
00252                         "first name in the list will be selected as outgroup. "
00253                         "Don't leave spaces between taxon names!",
00254                         checker_function=lambda x: len(x.split()) == 1,
00255                         equate=False,
00256                         ),
00257 
00258                 _Option(['-q', 'partition_filename'],
00259                         "File name containing the assignment of models to "
00260                         "alignment partitions for multiple models of "
00261                         "substitution. For the syntax of this file please "
00262                         "consult the RAxML manual.",
00263                         filename=True,
00264                         equate=False,
00265                         ),
00266 
00267                 _Option(['-p', 'parsimony_seed'],
00268                         "Random number seed for the parsimony inferences. "
00269                         "This allows you to reproduce your results and will "
00270                         "help developers debug the program. This option HAS "
00271                         "NO EFFECT in the parallel MPI version.",
00272                         equate=False,
00273                         ),
00274 
00275                 _Option(['-P', 'protein_model'],
00276                         "File name of a user-defined AA (Protein) substitution "
00277                         "model. This file must contain 420 entries, the first "
00278                         "400 being the AA substitution rates (this must be a "
00279                         "symmetric matrix) and the last 20 are the empirical "
00280                         "base frequencies.",
00281                         filename=True,
00282                         equate=False,
00283                         ),
00284 
00285                 _Option(['-r', 'binary_constraint'],
00286                         "File name of a binary constraint tree. "
00287                         "This tree does not need to be comprehensive, i.e. "
00288                         "contain all taxa.",
00289                         filename=True,
00290                         equate=False,
00291                         ),
00292 
00293                 _Option(['-s', 'sequences'],
00294                         "Name of the alignment data file, in PHYLIP format.",
00295                         filename=True,
00296                         equate=False,
00297                         ),
00298 
00299                 _Option(['-t', 'starting_tree'],
00300                         "File name of a user starting tree, in Newick format.",
00301                         filename=True,
00302                         equate=False,
00303                         ),
00304 
00305                 _Option(['-T', 'threads'],
00306                         "Number of threads to run. "
00307                         "PTHREADS VERSION ONLY! "
00308                         "Make sure to set this at most the number of CPUs "
00309                         "you have on your machine, otherwise, there will be "
00310                         "a huge performance decrease!",
00311                         equate=False,
00312                         ),
00313 
00314                 _Option(['-u', 'num_bootstrap_searches'],
00315                         "Number of multiple bootstrap searches per replicate. "
00316                         "Use this to obtain better ML trees for each "
00317                         "replicate. Default: 1 ML search per bootstrap "
00318                         "replicate.",
00319                         equate=False,
00320                         ),
00321 
00322                 _Switch(['-v', 'version'],
00323                         "Display version information."
00324                         ),
00325 
00326                 _Option(['-w', 'working_dir'],
00327                         "Name of the working directory where RAxML will "
00328                         "write its output files. Default: current directory.",
00329                         filename=True,
00330                         ),
00331 
00332                 _Option(['-x', 'rapid_bootstrap_seed'],
00333                         "Random seed for rapid bootstrapping.",
00334                         equate=False,
00335                         ),
00336 
00337                 _Switch(['-y', 'parsimony'],
00338                         "Only compute a parsimony starting tree, then exit."
00339                         ),
00340 
00341                 _Option(['-z', 'bipartition_filename'],
00342                         "Name of a file containing multiple trees, e.g. from "
00343                         "a bootstrap run, that shall be used to draw "
00344                         "bipartition values onto a tree provided with '-t'. "
00345                         "It can also be used to compute per-site log "
00346                         "likelihoods in combination with '-f g', and to read "
00347                         "a bunch of trees for a couple of other options "
00348                         "('-f h', '-f m', '-f n').",
00349                         filename=True,
00350                         equate=False,
00351                         ),
00352 
00353                 _Option(['-N', '-#', 'num_replicates'],
00354                     "Number of alternative runs on distinct starting trees. "
00355                     "In combination with the '-b' option, this will invoke a "
00356                     "multiple boostrap analysis. "
00357                     "DEFAULT: 1 single analysis."
00358                     "Note that '-N' has been added as an alternative since "
00359                     "'-#' sometimes caused problems with certain MPI job "
00360                     "submission systems, since '-#' is often used to start "
00361                     "comments. "
00362                     ,
00363                     equate=False,
00364                     ),
00365                 ]
00366         AbstractCommandline.__init__(self, cmd, **kwargs)
00367         # ENH: enforce -s, -n and -m
00368         if not self.parsimony_seed:
00369             self.parsimony_seed = 10000
00370