annotate codeml.xml @ 1:ba71e26d5bdc draft

planemo upload for repository https://github.com/galaxyproject/tools-iuc/tree/master/tools/codeml commit 43935edeb0abb95b08b191b379e160ec25cb33c0

<tool name="codeML" id="codeml" version="1.0">
    <description>
        Detects positive selection (paml package)
    </description>

    <macros>
        <import>macros.xml</import>
    </macros>

    <requirements>
        <requirement type="package" version="4.9">paml</requirement>
    </requirements>

    <version_command><![CDATA[ codeml /dev/null 2>&1 | tail -1 ]]></version_command>

    <command><![CDATA[
codeml '$codeml_ctl'
&&
mv '$codeml_ctl' '$ctl'
    ]]></command>

    <configfiles>
        <configfile name="codeml_ctl"><![CDATA[
      seqfile = $concat_nuc * sequence data file name
      outfile = run_codeml * main result file name
     treefile = $tree * tree structure file name
        noisy = 9  * 0,1,2,3,9: how much rubbish on the screen
      verbose = $adv.verbose  * 1: detailed output, 0: concise output
      runmode = $adv.runmode  * 0: user tree;  1: semi-automatic;  2: automatic
                   * 3: StepwiseAddition; (4,5):PerturbationNNI; -2: pairwise
      seqtype = $adv.seqtype  * 1:codons; 2:AAs; 3:codons-->AAs
    CodonFreq = $adv.CodonFreq  * 0:1/61 each, 1:F1X4, 2:F3X4, 3:codon table
        clock = $adv.clock   * 0:no clock, 1:clock; 2:local clock
       aaDist = $adv.aaDist  * 0:equal, +:geometric; -:linear, 1-6:G1974,Miyata,c,p,v,a
                   * 7:AAClasses
   aaRatefile = $adv.aaRateFile * only used for aa seqs with model=empirical(_F)
                  * dayhoff.dat, jones.dat, wag.dat, mtmam.dat, or your own
        model = $compat_model.brmodel
                   * models for codons:
                       * 0:one, 1:b, 2:2 or more dN/dS ratios for branches
                   * models for AAs or codon-translated AAs:
                       * 0:poisson, 1:proportional,2:Empirical,3:Empirical+F
                       * 6:FromCodon, 8:REVaa_0, 9:REVaa(nr=189)
      NSsites = $compat_model.NSsites  * 0:one w;1:neutral;2:selection; 3:discrete;4:freqs;
                   * 5:gamma;6:2gamma;7:beta;8:beta&w;9:beta&gamma;
                   * 10:beta&gamma+1; 11:beta&normal>1; 12:0&2normal>1;
                   * 13:3normal>0
        icode = $adv.icode  * 0:universal code; 1:mammalian mt; 2-11:see below
        Mgene = $adv.Mgene  * 0:rates, 1:separate;
    fix_kappa = $adv.fix_kappa  * 1: kappa fixed, 0: kappa to be estimated
        kappa = $adv.kappa  * initial or fixed kappa
    fix_omega = $adv.fix_omega  * 1: omega or omega_1 fixed, 0: estimate
        omega = $adv.omega * initial or fixed omega, for codons or codon-based AAs
    fix_alpha = $adv.fix_alpha  * 0: estimate gamma shape parameter; 1: fix it at alpha
        alpha = $adv.alpha * initial or fixed alpha, 0:infinity (constant rate)
       Malpha = $adv.Malpha  * 1: different alphas for genes, 0 : one alpha
        ncatG = $adv.ncatG  * # of categories in dG of NSsites models
      fix_rho = $adv.fix_rho  * 0: estimate rho; 1: fix it at rho
          rho = $adv.rho * initial or fixed rho,   0:no correlation
        getSE = $adv.getSE  * 0: don't want them, 1: want S.E.s of estimates
 RateAncestor = $adv.RateAncestor  * (0,1,2): rates (alpha>0) or ancestral states (1 or 2)
   Small_Diff = $adv.Small_Diff
    cleandata = $adv.cleandata  * remove sites with ambiguity data (1:yes, 0:no)?
  fix_blength = $adv.fix_blength   * 0: ignore, -1: random, 1: initial, 2: fixed
       method = $adv.method   * 0: simultaneous; 1: one branch at a time
        ]]></configfile>
    </configfiles>

    <inputs>
        <param name="concat_nuc" type="data" format="fasta" label="Sequences file" help="The fasta file with the sequences to be analyzed" />
        <param name="tree" type="data" format="nhx" label="tree file" help="Tree file in Newick format" />

        <conditional name="compat_model" >
            <param argument="brmodel" type="select" label="Branch model ; for tree file editing in model 2 and 3, see paml manual (chap.3)" >
                <option value="0" selected="true">'0' : one dN/dS ratio for all branches (e.g. basic model if NSsites=0)</option>
                <option value="1">'1' : one dN/dS ratio for each branch ("free-ratio model") ; its use is discouraged</option>
                <option value="2">'2' : arbitrary number of ratios ; implies to manually edit your tree file</option>
                <option value="3">'3' : clade-model ; implies to manually edit your tree file</option>
            </param>

            <when value="0" >
                <expand macro="FSsites_br0" />
            </when>
            <when value="1">
                <expand macro="FSsites_br1" />
            </when>
            <when value="2" >
                <expand macro="FSsites_br2_and_3" />
            </when>
            <when value="3" >
                <expand macro="FSsites_br2_and_3" />
            </when>
        </conditional>

        <!-- advanced parameters -->
        <section name="adv" title="Advanced Options" expanded="False" >
            <param argument="verbose" type="select" label="Set the level of details in the log file">
                <option value="0" selected="true">0 : concise output</option>
                <option value="1">1 : detailed output</option>
            </param>

            <param argument="runmode" type="select" label="Tree analysis mode" >
                <option value="0" selected="true">0 : user tree</option>
                <option value="1">1 : heuristic tree search  starting from a multifurcating tree from the tree structure file</option>
                <option value="2">2 : heuristic tree search starting from the tree file</option>
                <option value="3">3 : StepwiseAddition</option>
                <option value="4">4 : PerturbationNNI with the starting tree obtained by a parsimony algorithm</option>
                <option value="5">5 : PerturbationNNI with the starting tree read from the tree structure file</option>
                <option value="-2">-2 : ML estimation of dS and dN in pairwise comparisons of protein-coding sequences</option>
            </param>

            <param argument="seqtype" type="select" label="Sequences format in the fasta file" >
                <option value="1" selected="true">1 : codons</option>
                <option value="2">2 : Amino acids (only compatible with FSsites=0) </option>
                <option value="3">3 : codons--&gt;amino acids (only compatible with FSsites=0)</option>
            </param>

            <param argument="CodonFreq" type="select" label="Equilibrium codon frequencies in codon substitution model">
                <option value="0">0 : 1/61 each:</option>
                <option value="1" selected="true">1 : FIX4</option>
                <option value="2">2 : codon table</option>
            </param>

            <param argument="clock" type="select" label="Specifies models concerning rate constancy or variation among lineages" >
                <option value="0" selected="true">0 : no clock ; An unrooted tree should be used under this model</option>
                <option value="1">1 : clock</option>
                <option value="2">2 : local clock (needed : branch labels in the tree)</option>
            </param>

            <param argument="aaDist" type="select" label="Amino acid distances" >
                <option value="0" selected="true">0 : equal (warning : the only one compatible with NSsites and seqtype=codons</option>
                <option value="+">+ : geometric</option>
                <option value="-">- : linear</option>
                <option value="1">1 : G1974</option>
                <option value="2">2 : Miyata</option>
                <option value="3">3 : c</option>
                <option value="4">4 : p</option>
                <option value="5">5 : v</option>
                <option value="6">6 : a</option>
                <option value="7">7 : AAClasses</option>
            </param>

            <param argument="aaRateFile" type="select" label="Amino acide substitution rate matrix" >
                <option value="wag.dat" selected="true">wag.dat</option>
                <option value="dayhoff.dat">dayhoff.dat</option>
                <option value="jones.dat">jones.dat</option>
                <option value="mtmam.dat">mtmam.dat</option>
            </param>

            <param argument="icode" type="select" label="Icode : specifies the genetic code" >
                <option value="0" selected="true">0 : universal code</option>
                <option value="1">1 : mammalian mt</option>
                <option value="3">3 : mold mt</option>
                <option value="4">4 : invertebrate mt</option>
                <option value="5">5 : ciliate nuclear code mt</option>
                <option value="6">6 : echinoderm mt</option>
                <option value="7">7 : euplotid mt</option>
                <option value="8">8 : alternative yeast nuclear</option>
                <option value="9">9 : scidian mt</option>
                <option value="10">10 : blepharisma nuclear</option>
                <option value="11">11 : Yang's regularized code</option>
            </param>

            <param argument="Mgene" type="select" value="0" label="Multiple genes"
                help="Used in combination with option G in the sequence data file, for combined analysis of data from multiple genes or multiple site partitions" >
                <option value="0">0 : complete homogeneity among genes </option>
                <option value="1">1 : equivalent to a separate analysis</option>
                <option value="2">2 : different frequency parameters for different genes but the same rate ratio parameters</option>
                <option value="3">3 : different rate ratio parameters and the same frequency parameters</option>
                <option value="4">4 : both different rate ratio parameters and different frequency parameters for different genes </option>
            </param>

            <param argument="fix_kappa" type="select" label="Specifies wether kappa in  K80, F84, or HKY85 is fixed or estimated">
                <option value="0" selected="true">0 : estimated</option>
                <option value="1">1 : fixed (the next parameter below)</option>
            </param>

            <param argument="kappa" type="float" value="2" label="Initial or fixed value of kappa" help="kappa refers to the transition/tranversion rate ratio"/>

            <param argument="fix_omega" type="select" label="Fixed or estimated omega" >
                <option value="0" selected="true">0 : estimated</option>
                <option value="1">1 : fixed</option>
            </param>

            <param argument="omega" type="float" value="0.2" label="Initial or fixed omega (according to your choice for fix_omega), for codons or codon-based AAs"/>

            <param argument="fix_alpha" type="select" label="Estimated or fixed gamma shape parameter" >
                <option value="0">0 : estimate gamma shape parameter. Not recommended</option>
                <option value="1" selected="true">1 : fix it at alpha (the next parameter below)</option>
            </param>

            <param argument="alpha" type="float" value="0" label="Initial or fixed value of alpha (gamma shape parameter)"
                help="0: constant rate. fix_alpha !=1 and alpha !=0 are not compatible with NSsites !=0"/>

            <param argument="Malpha" type="select" label="Different alphas for genes" >
                <option value="0">0 : one gamma distribution will be applied across all sites (one alpha)</option>
                <option value="1">1 : different gamma distribution is used for each gene or codon position (different alphas for genes)</option>
            </param>

            <param argument="ncatG" type="integer" value="3" label="# of categories in dG of NSsites models" />

            <param argument="fix_rho" type="select" label="Independence or correlation of rates at adjacent sites" >
                <option value="0">0 : estimate rho</option>
                <option value="1" selected="true">1 : fix it at rho (the next parameter below)</option>
            </param>

            <param argument="rho" type="float" value="0" label="Initial or fixed rho" help="fix_rho=1 and rho=0 : independent rates" />

            <param argument="getSE" type="select" label="Estimates of the standard errors of estimated parameters." >
                <option value="0" selected="true">0 : don't want them</option>
                <option value="1">1 : want S.E.s of estimates</option>
            </param>

            <param argument="RateAncestor" type="select" label="RateAncestor ; set 1 to force the program to do two additional analyses" >
                <option value="0" selected="true">0 : usually use 0</option>
                <option value="1">1 :  model of variable rates across site + empirical Bayesian reconstruction of ancestral sequences</option>
            </param>

            <param argument="Small_Diff" type="float" value=".5e-6" label="Value used in the difference approximation of derivatives"/>

            <param argument="cleandata" type="select" label="Remove sites with ambiguity data" help="Warning : choosing 'yes' may remove a lot (possibly all) of data.">
                <option value="0" selected="true">0 : no (don't remove ambiguous data)</option>
                <option value="1">1 : yes (remove ambiguous data)</option>
            </param>

            <param argument="fix_blength" type="select" label="branch length dealing" >
                <option value="0" selected="true">0 : ignore branch lengths</option>
                <option value="-1">-1 : start from random starting points</option>
                <option value="1">1 : initial values as written in the tree file</option>
                <option value="2">2 : fixed at values in the tree file</option>
            </param>

            <param argument="method" type="select" label="Controls the iteration algorithm for estimating branch lengths" >
                <option value="0" selected="true">0 : simultaneous (old paml algorithm)</option>
                <option value="1">1 : one branch at a time (newly implemented in paml ; does not work with clock=1,2,3)</option>
            </param>
        </section>
    </inputs>

    <outputs>
        <data format="txt" name="ctl" label="${tool.name} on ${on_string}: codeml.ctl" />
        <data format="txt" name="2ngdn" from_work_dir="2NG.dN" label="${tool.name} on ${on_string}: 2NG.dN" >
            <filter>adv['seqtype']=="1"</filter>
        </data>
        <data format="txt" name="2ngds" from_work_dir="2NG.dS" label="${tool.name} on ${on_string}: 2NG.dS" >
            <filter>adv['seqtype']=="1"</filter>
        </data>
        <data format="txt" name="2ngt" from_work_dir="2NG.t" label="${tool.name} on ${on_string}: 2NG.t" >
            <filter>adv['seqtype']=="1"</filter>
        </data>
        <data format="txt" name="lnf" from_work_dir="lnf" label="${tool.name} on ${on_string}: lnf"/>
        <data format="txt" name="rst" from_work_dir="rst" label="${tool.name} on ${on_string}: rst"/>
        <data format="txt" name="rst1" from_work_dir="rst1" label="${tool.name} on ${on_string}: rst1"/>
        <data format="txt" name="rub" from_work_dir="rub" label="${tool.name} on ${on_string}: rub"/>
        <data format="txt" name="run" from_work_dir="run_codeml" label="${tool.name} on ${on_string}: run_codeml"/>
        <data format="txt" name="4fold" from_work_dir="4fold.nuc" label="${tool.name} on ${on_string}: 4fold.nuc">
            <filter>adv['verbose']=="1"</filter>
        </data>
    </outputs>

    <tests>
        <test>
            <conditional name="compat_model" >
                <param name="brmodel" value="0" />
                <param name="NSsites" value="0" />
            </conditional>
            <param name="adv.fix_omega" value="0" />
            <param name="adv.omega" value="0.2" />
            <param name="RateAncestor" value="1" />
            <param name="concat_nuc" ftype="fasta" value="concat.fasta" />
            <param name="tree" ftype="txt" value="RAxML_bestTree" />
            <output name="2ngdn" value="1_2ngdn" />
            <output name="2ngds" value="1_2ngds" />
            <output name="2ngt" value="1_2ngt" />
            <output name="run" value="1_run_codeml" lines_diff="20"/>
            <output name="ctl" value="1_codeml.ctl" lines_diff="4" />
        </test>
        <test>
            <conditional name="compat_model" >
                <param name="brmodel" value="2" />
                <param name="NSsites" value="0" />
            </conditional>
            <param name="adv.fix_omega" value="0" />
            <param name="adv.omega" value="0.2" />
            <param name="RateAncestor" value="1" />
            <param name="concat_nuc" ftype="fasta" value="concat.fasta" />
            <param name="tree" ftype="txt" value="tree_model2" />
            <output name="2ngdn" value="2_2ngdn" />
            <output name="2ngds" value="2_2ngds" />
            <output name="2ngt" value="2_2ngt" />
            <output name="run" value="2_run_codeml" lines_diff="20" />
            <output name="ctl" value="2_codeml.ctl" lines_diff="4" />
        </test>
        <test>
            <conditional name="compat_model" >
                <param name="brmodel" value="3" />
                <param name="NSsites" value="2" />
            </conditional>
            <param name="adv.fix_omega" value="0" />
            <param name="adv.omega" value="0.2" />
            <param name="RateAncestor" value="1" />
            <param name="concat_nuc" ftype="fasta" value="concat.fasta" />
            <param name="tree" ftype="txt" value="tree_model3" />
            <output name="2ngdn" value="3_2ngdn" />
            <output name="2ngds" value="3_2ngds" />
            <output name="2ngt" value="3_2ngt" />
            <output name="run" value="3_run_codeml" lines_diff="20"/>
            <output name="ctl" value="3_codeml.ctl" lines_diff="4" />
        </test>
    </tests>

    <help><![CDATA[
.. class:: infomark

**Galaxy integration** Victor Mataigne and ABIMS TEAM.

Contact [e-mail] for any questions or concerns about the Galaxy implementation of this tool.

----------

**CompCodeML (from paml package)**

A few help is detailed below ; full and detailed codeml readme can be found on the paml website_.

.. _website: http://abacus.gene.ucl.ac.uk/software/paml.html

.. class:: warningmark

Due to their high number, some parameters incompatibility can remain.

This Galaxy implementation :

- handles incompatibilities between branch and sites models (the tool CANNOT be run with incompatible models).
- warns the user in a help section when an advanced parameter has known incompatibilities (the tool CAN be run, but the output files will be empty).

We recommand to have a look at the full paml manual before looking at the advanced parameters, in order to spot parameters incompatibilities and to know what each model does. If you choose by mistake incompatible parameters, the output files will be empty, except the log file ("run_codeml" output) which will normally explicit the error.

.. class:: infomark

Known incompatibilities:

- 'seqtype' = 3 : only compatible with 'FSsites' = 0.
- 'clock' = 2 : needs branch labels in the tree.
- fix_alpha !=1 combined with alpha !=0 are not compatible with NSsites !=0
- 'aaDist' = 0 is the only one compatible with 'NSsites' different than 0 and 'seqtype' = 1.
- 'method' = 1 : does not work with 'clock' different than 0.

----------

**Description**

.. class:: infomark

codeML finds positive selection within branches or codons within a tree and a set of sequences.

----------

**Input files**

- a treefile in Newick format (with or without branch lengths).
- a fasta file with sequences from the species of the tree file (one header/sequence per species) and run codeml (from the paml suite).

----------

**Parameters**

Several models are available.

- branch models ("model" parameter).
- sites models ("NSsites" parameter, model is left at 0).
- branch-sites models (when model = 2 NSsites=2,3).
- Clade models (when model=3 NSsites=2,3).

Basically, this tool write a configfile called codeml.ctl with the specified parameters and then launches codeml.

.. class:: infomark

Branch models allow the omega ratio to vary among branches in the phylogeny and are useful for detecting positive selection acting on particular lineages. Sites models allow the omega ratio to vary among sites (codons or amino acids).

Two pairs of models appear to be particularly useful, forming two likelihood ratio tests of positive selection.  The first compares M1a ('NearlyNeutral', NSsites=1) and M2a ('PositiveSelection', NSsites=2), while the second compares M7 ('beta', NSsites=7) and M8 ('beta&ω', NSsites=8).

**Other examples of model**

How to run the branch-site models (A &amp; B in Yang &amp; Nielsen 2002 MBE) ?
The options are :

- Model A: (model=2, NSsites=2).
- Model B: (model=2, NSsites=3).

How to run the M0 (one-ratio) model :

    model = 0, NSsites= = 0.

----------

**Advanced Parameters**

.. class:: infomark

See paml complete manual and FAQ on the paml website_.

.. _website: http://abacus.gene.ucl.ac.uk/software/paml.html

**Details of some parameters :**

- 'kappa' denotes the transition/transversion rate ratio.
- 'fix_kappa' specifies whether kappa in K80, F84, or HKY85 is given at a fixed value or is to be estimated by iteration from the data.

  -> If fix_kappa = 1 (fixed), the value of kappa is the given value

  -> If fix_kappa = 0 (estimated) the value of kappa is used as the initial estimate for iteration.

- 'alpha' refers to the shape parameter alpha of the gamma distribution for variable substitution rates across sites (Yang 1994a).
- 'fix_alpha' works in a similar way that fix_kappa.

  -> The model of a single rate for all sites is specified as fix_alpha = 1 and alpha = 0 (0 means infinity)

  -> The (discrete-) gamma model is specified by a positive value for alpha, and 'ncatG' is then the number of categories for the discrete-gamma model. Values such as 5, 4, 8, or 10 are reasonable.

- fix_rho and rho work in a similar way and concern independence or correlation of rates at adjacent sites, where rho is the correlation parameter of the auto-discrete-gamma model (Yang 1995).

  -> The model of independent rates for sites is specified as fix_rho = 1 and rho = 0; choosing alpha = 0 further means a constant rate for all sites.

  -> The auto-discrete-gamma model is specified by positive values for both alpha and rho.

  -> The model of a constant rate for sites is a special case of the (discrete) gamma model with alpha = 0 (means infinity).

  -> The model of independent rates for sites is a special case of the auto-discrete-gamma model with rho = 0.

----------

**Output files**

- codeml.ctl : a copy of the control file (list of all the parameters used for the codeml run).
- run_codeml : main result file name.
- The 2NG.dN and 2NG.dS files are the Nei an Gojobori (1986) dN and dS values;
- lnf, rst and rst1: Supplemental results.
- rub : records of the iteration progress (i.e. the minimization of the negative log-likelihood).

----------

**How to edit manually the tree file : Branch or node labels**

Some models implemented in codeml allow several groups of branches on the tree, which are assigned different parameters of interest.

- For example, in the local clock models (clock = 2 or 3), you can have, say, 3 branch rate groups, with low, medium, and high rates respectively.
- Also the branch-specific codon models (model = 2 or 3 or codonml) allow different branch groups to have different ωs, leading to so called “two-ratios” and “three-ratios” models.
- All those models require branches or nodes in the tree to be labeled. Branch labels are specified in the same way as branch lengths except that the symbol “#” is used rather than “:”. The branch labels are consecutive integers starting from 0, which is the default and does not have to be specified.

In ((Hsa_Human, Hla_gibbon) #1, ((Cgu/Can_colobus, Pne_langur), Mmu_rhesus), (Ssc_squirrelM, Cja_marmoset)); :
    The internal branch ancestral to human and gibbon has the ratio ω1, while all other branches (with the default label #0) have the background ratio ω0.

The following trees are equivalent:
- ((rabbit, rat) $1, human), goat_cow, marsupial);
- (((rabbit #1, rat #1) #1, human), goat_cow, marsupial);

$ is the symbol for clade labels.

Rules concerning nested clade labels : The symbol # takes precedence over the symbol $, and clade labels close to the tips take precedence over clade labels for ancestral nodes close to the root.

In the tree ((((rabbit, rat) $2, human #3), goat_cow) $1, marsupial); :
    $1 is first applied to the whole clade of placental mammals (except for the human lineage), and then $2 is applied to the rabbit-rat clade.
    Equivalent tree with only '#' :
    ((((rabbit #2, rat #2) #2, human #3) #1, goat_cow #1) #1, marsupial);
    ]]></help>

    <citations>
        <citation type="doi">10.1093/molbev/msm088</citation>
    </citations>
</tool>