ete evol: optimizing and testing models of molecular evolution with a single command line

ete-evol is a tool that automates CodeML and Slr analyses by using pre-configured evolutionary models and directly producing a graphical representation of the results.
Highlighted features:
Pre-configured models include site (Yang et al. 2000; Massingham and Goldman 2005), branch (Yang and Nielsen 2002) branch-site (Zhang et al. 2005) and clade (Yang and Nielsen 2002; Bielawski and Yang 2004) models.
Multiple evolutionary models can be tested and visualized with a single command.
Input trees can be marked interactively using the ETE GUI
CodeML analyses can be fine tuned (use --codeml_help for options)
Multithreading options allow running multiple tests in parallel
To run a ete3 evol workflow we need a fasta file, a tree file and a model name. Also, if branch, or branch-site models are called, extra information should be passed in order to apply specific evolutionary constraints on sections of the tree.
"Model names" correspond to several predefined evolutionary models that were based on previously published research (see table in next section, and PAML and Slr documentations).
Any of these predefined models can be modified easily with the command line, for example --codeml_param getSE,1.
Once run, the models can be compared with likelihood-ratio test (LRT). This can be done either automatically (default), or using pre-defined comparisons (--tests option).
Several predefined evolutionary models can be called with the tool.
They can be passed sequentially, and run in parallel:
Available predefined models are:
After a short time (2-5 minutes), CodeML/Slr input and output files should appear in the results/ folder, including (if graphics capabilities were available in your system) an image of your tree and the used alignment (Figure 2).
One of the main difficulty with automatizing CodeML for several trees is to mark branches specifically for each model to run. ete3 evol allows to pass lists of marks to be applied on each wanted branch model.
The tree can be marked with the command line like this:
The three comas mean that the tree will be marked from the common ancestor of the surrounding species. To mark at the ancestral node we would have to put only two comas.
This coma-code allows to mark easily any part of the tree, using single coma new marks are created. Finally spaces between parameters under --marks separate sets of marks. Each branch model will be run on each set of marks. For example:
this, will in the first place, mark the tree as in Figure 3, and in second place as in Figure 4.
When, as in the example above, consecutive marks are passed, the given models ("b_neut" and "b_free" in this case) will be run independently for each group of marks.
By default ete3 evol will display the result of site models with histograms (above and bellow the alignments), and the result of the free-branch model on the tree changing its branch-lengths and showing the omega value as colored disks on the nodes (Figure 2).
This image is saved as pdf in the output directory unless the --noimg is used. The option --view allows to view this image in the ETE GUI and interact with it. The GUI allows to browse all run models and compare the different estimates of evolutionary rates. Finally new models can also be run directly from the GUI (see the GUI section).
In order to compare which of the different models computed fits better to the input data, the ete3 evol tool tests, with a LRT, any pairs of computed models. By default it will do the most classical comparisons, as the ones included in the table bellow.
Specific tests can also be calculated using the --tests flag. For example:
Will give this result, with only the tests computed between branch models, not sites even if computed:
As previously mentioned ETE GUI's possibilities goes beyond the visualization of results, and allows to run "on the fly" any default evolutionary model (see Evolutionary models).
See Figure 5 for an example on how to mark a branch and run a model using the GUI.
--clear_all: Clear any data present in the output directory.
--prev_models: directory where pre-calculated models are stored, followed by coma model-name. example: --prev_models /path1/,M2 /path2/,M1 will load models from path1 under the name 'M2', and from path2 into 'M1'
--clean_layout Other visualization option, with omega values, synonymous rates and non-synonymous rates written on branches
--histface: Type of histogram face to be used for site models. If preceded by '+-' error bars are also drawn (can be bar, stick or curve).
--codeml_param extra parameter to be interpreted by CodeML and modify the default settings of models. available keywords are accepted [default values]:
--codeml_help show detailed description on codeml parameters for model configuration and exit.
--cpu: Maximum number of CPU cores available in the execution host. If higher than 1, tasks with multi-threading capabilities will enabled (if 0 all available) cores will be used.
--codeml_binary: path to CodeML binary.
--slr_binary: path to Slr binary.
The following files are used in the examples on the left
This dataset is from a previously published work (Joseph P. Bielawski (2004)) where it was used as an example of differential selective pressure in the paralogous genes ECP and EDN in primates (Figure 1).
This page shows the basic usage of ete-evol. More options and examples are available as a collection of notebooks.