Package Bio :: Package Phylo :: Package Applications :: Module _Raxml
[hide private]
[frames] | no frames]

Source Code for Module Bio.Phylo.Applications._Raxml

  1  # Copyright 2012 by Eric Talevich.  All rights reserved. 
  2  # This code is part of the Biopython distribution and governed by its license. 
  3  # Please see the LICENSE file that should have been included as part of this 
  4  # package. 
  5  """Command-line wrapper for the tree inference program RAxML. 
  6   
  7  Derived from the help page for RAxML version 7.3 by Alexandros Stamatakis, but 
  8  should work for any version 7.X (and probably earlier for most options). 
  9  """ 
 10  from __future__ import print_function 
 11  from Bio._py3k import basestring 
 12   
 13  from Bio.Application import _Option, _Switch, AbstractCommandline 
 14   
 15   
16 -class RaxmlCommandline(AbstractCommandline):
17 """Command-line wrapper for the tree inference program RAxML. 18 19 The required parameters are 'sequences' (-s), 'model' (-m) and 'name' (-n). 20 The parameter 'parsimony_seed' (-p) must also be set for RAxML, but if you 21 do not specify it, this wrapper will set the seed to 10000 for you. 22 23 Example: 24 25 >>> from Bio.Phylo.Applications import RaxmlCommandline 26 >>> raxml_cline = RaxmlCommandline(sequences="Tests/Phylip/interlaced2.phy", 27 ... model="PROTCATWAG", name="interlaced2") 28 >>> print(raxml_cline) 29 raxmlHPC -m PROTCATWAG -n interlaced2 -p 10000 -s Tests/Phylip/interlaced2.phy 30 31 You would typically run the command line with raxml_cline() or via 32 the Python subprocess module, as described in the Biopython tutorial. 33 34 Citation: 35 36 Stamatakis A. 37 RAxML-VI-HPC: Maximum Likelihood-based Phylogenetic Analyses with 38 Thousands of Taxa and Mixed Models. 39 Bioinformatics 2006, 22(21):2688-2690. 40 41 Homepage: http://sco.h-its.org/exelixis/software.html 42 """ 43
44 - def __init__(self, cmd='raxmlHPC', **kwargs):
45 self.parameters = [ 46 _Option(['-a', 'weight_filename'], 47 "Name of a column weight file to assign individual weights " 48 "to each column of the alignment. Those weights must be " 49 "integers separated by any type and number of whitespaces " 50 "within a separate file.", 51 filename=True, 52 equate=False, 53 ), 54 55 _Option(['-b', 'bootstrap_seed'], 56 "Random seed for bootstrapping.", 57 equate=False, 58 ), 59 60 _Option(['-c', 'num_categories'], 61 "Number of distinct rate categories for RAxML when " 62 "evolution model is set to GTRCAT or GTRMIX." 63 "Individual per-site rates are categorized into this " 64 "many rate categories to accelerate computations. " 65 "Default: 25.", 66 equate=False, 67 ), 68 69 _Switch(['-d', 'random_starting_tree'], 70 "Start ML optimization from random starting tree." 71 ), 72 73 _Option(['-e', 'epsilon'], 74 "Set model optimization precision in log likelihood units " 75 "for final optimization of tree topology under MIX/MIXI " 76 "or GAMMA/GAMMAI." 77 "Default: 0.1 for models not using proportion of " 78 "invariant sites estimate; 0.001 for models using " 79 "proportion of invariant sites estimate.", 80 equate=False, 81 ), 82 83 _Option(['-E', 'exclude_filename'], 84 "An exclude file name, containing a specification of " 85 "alignment positions you wish to exclude. Format is " 86 "similar to Nexus, the file shall contain entries like " 87 "'100-200 300-400'; to exclude a single column write, " 88 "e.g., '100-100'. If you use a mixed model, an " 89 "appropriately adapted model file will be written.", 90 filename=True, 91 equate=False, 92 ), 93 94 _Option(['-f', 'algorithm'], 95 """Select algorithm: 96 97 a: Rapid Bootstrap analysis and search for best-scoring ML 98 tree in one program run. 99 b: Draw bipartition information on a tree provided with '-t' 100 based on multiple trees (e.g. form a bootstrap) in a file 101 specifed by '-z'. 102 c: Check if the alignment can be properly read by RAxML. 103 d: New rapid hill-climbing (DEFAULT). 104 e: Optimize model+branch lengths for given input tree under 105 GAMMA/GAMMAI only. 106 g: Compute per site log Likelihoods for one ore more trees 107 passed via '-z' and write them to a file that can be read 108 by CONSEL. 109 h: Compute log likelihood test (SH-test) between best tree 110 passed via '-t' and a bunch of other trees passed via '-z'. 111 i: Perform a really thorough bootstrap, refinement of final 112 bootstrap tree under GAMMA and a more exhaustive algorithm. 113 j: Generate a bunch of bootstrapped alignment files from an 114 original alignemnt file. 115 m: Compare bipartitions between two bunches of trees passed 116 via '-t' and '-z' respectively. This will return the 117 Pearson correlation between all bipartitions found in the 118 two tree files. A file called 119 RAxML_bipartitionFrequencies.outputFileName will be 120 printed that contains the pair-wise bipartition 121 frequencies of the two sets. 122 n: Compute the log likelihood score of all trees contained 123 in a tree file provided by '-z' under GAMMA or 124 GAMMA+P-Invar. 125 o: Old and slower rapid hill-climbing. 126 p: Perform pure stepwise MP addition of new sequences to an 127 incomplete starting tree. 128 s: Split up a multi-gene partitioned alignment into the 129 respective subalignments. 130 t: Do randomized tree searches on one fixed starting tree. 131 w: Compute ELW test on a bunch of trees passed via '-z'. 132 x: Compute pair-wise ML distances, ML model parameters will 133 be estimated on an MP starting tree or a user-defined 134 tree passed via '-t', only allowed for GAMMA-based models 135 of rate heterogeneity.""", 136 checker_function=(lambda x: 137 isinstance(x, basestring) and len(x) == 1), 138 equate=False, 139 ), 140 141 _Option(['-g', 'grouping_constraint'], 142 "File name of a multifurcating constraint tree. " 143 "this tree does not need to be comprehensive, i.e. " 144 "contain all taxa.", 145 filename=True, 146 equate=False, 147 ), 148 149 _Option(['-i', 'rearrangements'], 150 "Initial rearrangement setting for the subsequent " 151 "application of topological changes phase.", 152 equate=False, 153 ), 154 155 _Switch(['-j', 'checkpoints'], 156 "Write checkpoints (intermediate tree topologies)." 157 ), 158 159 _Switch(['-k', 'bootstrap_branch_lengths'], 160 "Print bootstrapped trees with branch lengths. " 161 "The bootstraps will run a bit longer, because model " 162 "parameters will be optimized at the end of each run. " 163 "Use with CATMIX/PROTMIX or GAMMA/GAMMAI." 164 ), 165 166 _Option(['-l', 'cluster_threshold'], 167 "Threshold for sequence similarity clustering. " 168 "RAxML will then print out an alignment to a file " 169 "called sequenceFileName.reducedBy.threshold that " 170 "only contains sequences <= the specified threshold " 171 "that must be between 0.0 and 1.0. RAxML uses the " 172 "QT-clustering algorithm to perform this task. " 173 "In addition, a file called " 174 "RAxML_reducedList.outputFileName will be written " 175 "that contains clustering information.", 176 equate=False, 177 ), 178 179 _Option(['-L', 'cluster_threshold_fast'], 180 "Same functionality as '-l', but uses a less " 181 "exhaustive and thus faster clustering algorithm. " 182 "This is intended for very large datasets with more " 183 "than 20,000-30,000 sequences.", 184 equate=False, 185 ), 186 187 _Option(['-m', 'model'], 188 """Model of Nucleotide or Amino Acid Substitution: 189 190 NUCLEOTIDES: 191 192 GTRCAT : GTR + Optimization of substitution rates + Optimization of site-specific 193 evolutionary rates which are categorized into numberOfCategories distinct 194 rate categories for greater computational efficiency 195 if you do a multiple analysis with '-#' or '-N' but without bootstrapping the program 196 will use GTRMIX instead 197 GTRGAMMA : GTR + Optimization of substitution rates + GAMMA model of rate 198 heterogeneity (alpha parameter will be estimated) 199 GTRMIX : Inference of the tree under GTRCAT 200 and thereafter evaluation of the final tree topology under GTRGAMMA 201 GTRCAT_GAMMA : Inference of the tree with site-specific evolutionary rates. 202 However, here rates are categorized using the 4 discrete GAMMA rates. 203 Evaluation of the final tree topology under GTRGAMMA 204 GTRGAMMAI : Same as GTRGAMMA, but with estimate of proportion of invariable sites 205 GTRMIXI : Same as GTRMIX, but with estimate of proportion of invariable sites 206 GTRCAT_GAMMAI : Same as GTRCAT_GAMMA, but with estimate of proportion of invariable sites 207 208 AMINO ACIDS: 209 210 PROTCATmatrixName[F] : specified AA matrix + Optimization of substitution rates + Optimization of site-specific 211 evolutionary rates which are categorized into numberOfCategories distinct 212 rate categories for greater computational efficiency 213 if you do a multiple analysis with '-#' or '-N' but without bootstrapping the program 214 will use PROTMIX... instead 215 PROTGAMMAmatrixName[F] : specified AA matrix + Optimization of substitution rates + GAMMA model of rate 216 heterogeneity (alpha parameter will be estimated) 217 PROTMIXmatrixName[F] : Inference of the tree under specified AA matrix + CAT 218 and thereafter evaluation of the final tree topology under specified AA matrix + GAMMA 219 PROTCAT_GAMMAmatrixName[F] : Inference of the tree under specified AA matrix and site-specific evolutionary rates. 220 However, here rates are categorized using the 4 discrete GAMMA rates. 221 Evaluation of the final tree topology under specified AA matrix + GAMMA 222 PROTGAMMAImatrixName[F] : Same as PROTGAMMAmatrixName[F], but with estimate of proportion of invariable sites 223 PROTMIXImatrixName[F] : Same as PROTMIXmatrixName[F], but with estimate of proportion of invariable sites 224 PROTCAT_GAMMAImatrixName[F] : Same as PROTCAT_GAMMAmatrixName[F], but with estimate of proportion of invariable sites 225 226 Available AA substitution models: DAYHOFF, DCMUT, JTT, MTREV, WAG, RTREV, CPREV, VT, BLOSUM62, MTMAM, GTR 227 With the optional 'F' appendix you can specify if you want to use empirical base frequencies 228 Please not that for mixed models you can in addition specify the per-gene AA model in 229 the mixed model file (see manual for details) 230 """, 231 equate=False, 232 ), 233 234 _Switch(['-M', 'partition_branch_lengths'], 235 "Switch on estimation of individual per-partition " 236 "branch lengths. Only has effect when used in " 237 "combination with 'partition_filename' ('-q'). " 238 "Branch lengths for individual partitions will be " 239 "printed to separate files. A weighted average of the " 240 "branch lengths is computed by using the respective " 241 "partition lengths. " 242 ), 243 244 _Option(['-n', 'name'], 245 "Name used in the output files.", 246 filename=True, 247 equate=False, 248 ), 249 250 _Option(['-o', 'outgroup'], 251 "Name of a single outgroup or a comma-separated list " 252 "of outgroups, eg '-o Rat' or '-o Rat,Mouse'. In case " 253 "that multiple outgroups are not monophyletic the " 254 "first name in the list will be selected as outgroup. " 255 "Don't leave spaces between taxon names!", 256 checker_function=lambda x: len(x.split()) == 1, 257 equate=False, 258 ), 259 260 _Option(['-q', 'partition_filename'], 261 "File name containing the assignment of models to " 262 "alignment partitions for multiple models of " 263 "substitution. For the syntax of this file please " 264 "consult the RAxML manual.", 265 filename=True, 266 equate=False, 267 ), 268 269 _Option(['-p', 'parsimony_seed'], 270 "Random number seed for the parsimony inferences. " 271 "This allows you to reproduce your results and will " 272 "help developers debug the program. This option HAS " 273 "NO EFFECT in the parallel MPI version.", 274 equate=False, 275 ), 276 277 _Option(['-P', 'protein_model'], 278 "File name of a user-defined AA (Protein) substitution " 279 "model. This file must contain 420 entries, the first " 280 "400 being the AA substitution rates (this must be a " 281 "symmetric matrix) and the last 20 are the empirical " 282 "base frequencies.", 283 filename=True, 284 equate=False, 285 ), 286 287 _Option(['-r', 'binary_constraint'], 288 "File name of a binary constraint tree. " 289 "This tree does not need to be comprehensive, i.e. " 290 "contain all taxa.", 291 filename=True, 292 equate=False, 293 ), 294 295 _Option(['-s', 'sequences'], 296 "Name of the alignment data file, in PHYLIP format.", 297 filename=True, 298 equate=False, 299 ), 300 301 _Option(['-t', 'starting_tree'], 302 "File name of a user starting tree, in Newick format.", 303 filename=True, 304 equate=False, 305 ), 306 307 _Option(['-T', 'threads'], 308 "Number of threads to run. " 309 "PTHREADS VERSION ONLY! " 310 "Make sure to set this at most the number of CPUs " 311 "you have on your machine, otherwise, there will be " 312 "a huge performance decrease!", 313 equate=False, 314 ), 315 316 _Option(['-u', 'num_bootstrap_searches'], 317 "Number of multiple bootstrap searches per replicate. " 318 "Use this to obtain better ML trees for each " 319 "replicate. Default: 1 ML search per bootstrap " 320 "replicate.", 321 equate=False, 322 ), 323 324 _Switch(['-v', 'version'], 325 "Display version information." 326 ), 327 328 _Option(['-w', 'working_dir'], 329 "Name of the working directory where RAxML will " 330 "write its output files. Default: current directory.", 331 filename=True, 332 equate=False, 333 ), 334 335 _Option(['-x', 'rapid_bootstrap_seed'], 336 "Random seed for rapid bootstrapping.", 337 equate=False, 338 ), 339 340 _Switch(['-y', 'parsimony'], 341 "Only compute a parsimony starting tree, then exit." 342 ), 343 344 _Option(['-z', 'bipartition_filename'], 345 "Name of a file containing multiple trees, e.g. from " 346 "a bootstrap run, that shall be used to draw " 347 "bipartition values onto a tree provided with '-t'. " 348 "It can also be used to compute per-site log " 349 "likelihoods in combination with '-f g', and to read " 350 "a bunch of trees for a couple of other options " 351 "('-f h', '-f m', '-f n').", 352 filename=True, 353 equate=False, 354 ), 355 356 _Option(['-N', '-#', 'num_replicates'], 357 "Number of alternative runs on distinct starting trees. " 358 "In combination with the '-b' option, this will invoke a " 359 "multiple bootstrap analysis. " 360 "DEFAULT: 1 single analysis." 361 "Note that '-N' has been added as an alternative since " 362 "'-#' sometimes caused problems with certain MPI job " 363 "submission systems, since '-#' is often used to start " 364 "comments. ", 365 equate=False, 366 ), 367 ] 368 AbstractCommandline.__init__(self, cmd, **kwargs) 369 # ENH: enforce -s, -n and -m 370 if not self.parsimony_seed: 371 self.parsimony_seed = 10000
372 373 374 if __name__ == "__main__": 375 from Bio._utils import run_doctest 376 run_doctest() 377