annotate hyphy_meme.xml @ 23:2f07f5b4e47b draft

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

<?xml version="1.0"?>
<tool id="hyphy_meme" name="HyPhy-MEME" version="@VERSION@+galaxy1" profile="19.09">
    <description>Mixed Effects Model of Evolution</description>
    <macros>
        <import>macros.xml</import>
        <token name="@OPERATION@">MEME</token>
        <token name="@operation@">meme</token>
    </macros>
    <expand macro="requirements"/>
    <command detect_errors="exit_code"><![CDATA[
        @SYMLINK_FILES@
        @HYPHYMPI@ meme
            --alignment ./$input_file
            #if $input_nhx:
                --tree ./input.nhx
            #end if
            --code '$gencodeid'
            --branches '$branches'
            --pvalue '$p_value'
            --output '$meme_output'
            --full-model '$full_model'
            > '$meme_log'
            ;
        @CATCH_ERROR@
    ]]></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 threshold"/>
        <param argument="--full-model" type="boolean" truevalue="Yes" falsevalue="No" label="Perform branch length re-optimization under the full codon model" />
    </inputs>
    <outputs>
        <data name="meme_log" format="txt"/>
        <data name="meme_output" format="hyphy_results.json" />
    </outputs>
    <tests>
        <test>
            <param name="input_file" ftype="fasta" value="meme-in1.fa"/>
            <param name="input_nhx" ftype="nhx" value="meme-in1.nhx"/>
            <param name="branches" value="All"/>
            <param name="p_value" value="0.1"/>
            <output name="meme_output" file="meme-out1.json" compare="sim_size" delta="25000"/>
        </test>
    </tests>
    <help><![CDATA[
MEME: Mixed Effects Model of Evolution
======================================

What question does this method answer?
--------------------------------------

Which site(s) in a gene are subject to pervasive or *episodic*, i.e. only on a
single lineage or subset of lineages, 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.
MEME is ideally suited to identify sites under positive selection which
represent candidate sites subject to strong selective pressures across the entire phylogeny or only on parts of the phylogeny.

MEME is the sole method in HyPhy for detecting selection at individual sites that considers both pervasive and episodic selection.
MEME is therefore our recommended method if maximum power is desired.


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

MEME (Mixed Effects Model of Evolution) estimates a site-wise synonymous
(alpha) and a two-category mixture of non-synonymous (beta-, with
proportion p-, and beta+ with proportion [1-p-]) rates, and uses a
likelihood ratio test to determine if beta+ > &alpha; at a site. The
estimates aggregate information over a proportion of branches at a site,
so the signal is derived from episodic diversification, which is a
combination of strength of selection [effect size] and the proportion of
the tree affected. 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/MEME for an example)

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

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


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


    ]]></help>
    <expand macro="citations">
        <citation type="doi">10.1371/journal.pgen.1002764</citation>
    </expand>
</tool>