annotate hyphy_fel.xml @ 7:f40d481b7c8b draft

"planemo upload for repository https://github.com/galaxyproject/tools-iuc/tree/master/tools/hyphy/ commit f953137ef9ed4e9e1dcce3d93ee26fdc5d2bba53"

<?xml version="1.0"?>
<tool id="hyphy_fel" name="HyPhy-FEL" version="@VERSION@+galaxy0">
    <description>Fixed Effects Likelihood</description>
    <macros>
        <import>macros.xml</import>
    </macros>
    <expand macro="requirements"/>
    <command detect_errors="exit_code"><![CDATA[
        ln -s '$input_file' fel_input.fa &&
        ln -s '$input_nhx' fel_input.nhx &&
        @HYPHYMPI@ fel
            --alignment ./fel_input.fa
            --tree ./fel_input.nhx
            --code '$gencodeid'
            --branches '$branches'
            --srv '$include_srv'
            --pvalue '$p_value'
            --output '$fel_output'
            > '$fel_log'
    ]]></command>
    <inputs>
        <expand macro="inputs"/>
        <expand macro="gencode"/>
        <expand macro="branches"/>
        <param name="p_value" type="float" value=".1" min="0" max="1" label="P-value"/>
        <param name="include_srv" type="select" label="Include synonymous rate variation" help = "Allow synonymous rates to vary from site to site">
            <option value="Yes">Yes (recommended)</option>
            <option value="No">No</option>
        </param>
    </inputs>
    <outputs>
        <data name="fel_log" format="txt"/>
        <data name="fel_output" format="hyphy_results.json" />
    </outputs>
    <tests>
        <test>
            <param name="input_file" ftype="fasta" value="absrel-in1.fa"/>
            <param name="input_nhx" ftype="nhx" value="absrel-in1.nhx"/>
            <output name="fel_output" file="fel-out1.json" compare="sim_size"/>
        </test>
    </tests>
    <help><![CDATA[
FEL : Fixed effects likelihood
==============================
    
What question does this method answer?
--------------------------------------

Which site(s) in a gene are subject to pervasive, i.e. consistently across the entire phylogeny, diversifying selection?

Recommended Applications
------------------------

The phenomenon of pervasive selection is generally most prevalent in pathogen evolution and any biological system influenced by evolutionary arms race dynamics 
(or balancing selection), including adaptive immune escape by viruses. As such, FEL is ideally suited to identify sites under positive selection which 
represent candidate sites subject to strong selective pressures across the entire phylogeny. 

FEL is our recommended method for analyzing small-to-medium size datasets when one wishes only to study pervasive selection at individual sites.

Brief description
-----------------

FEL (Fixed Effects Likelihood) estimates site-wise synonymous (alpha)
and non-synonymous rates (beta), and uses a likelihood ratio test to
determine if beta != alpha at a site. The estimates aggregate
information over all branches, so the signal is derived from pervasive
diversification or conservation. A subset of branches can be selected
for testing as well, in which case an additional (nuisance) parameter
will be inferred -- the non-synonymous rate on branches NOT selected for
testing. 


Input
-----

1. A *FASTA* sequence alignment.
2. A phylogenetic tree in the *Newick* format

Note: the names of sequences in the alignment must match the names of the sequences in the tree.


Output
------

A JSON file with analysis results (http://hyphy.org/resources/json-fields.pdf).
A custom visualization module for viewing these results is available (see http://vision.hyphy.org/FEL for an example)

Further reading
---------------

http://hyphy.org/methods/selection-methods/#FEL


Tool options
------------

::

    --code              Which genetic code to use 

    --branches          Which branches should be tested for selection?
                            All [default] : test all branches
                        
                            Internal : test only internal branches (suitable for 
                            intra-host pathogen evolution for example, where terminal branches
                            may contain polymorphism data)
                        
                            Leaves: test only terminal (leaf) branches
                        
                            Unlabeled: if the Newick string is labeled using the {} notation,
                            test only branches without explicit labels 
                            (see http://hyphy.org/tutorials/phylotree/)    
                        
     --pvalue           The significance level used to determine significance
 
     --srv              Include site-to-site synonymous rate variation?
                            Yes [default] or No



                            
]]>

    </help>
    
    <expand macro="citations">
        <citation type="doi">10.1093/molbev/msi105</citation>
    </expand>
</tool>