annotate hyphy_meme.xml @ 26:7d3d3d410c7a draft

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

<?xml version="1.0"?>
<tool id="hyphy_meme" name="HyPhy-MEME" version="@VERSION@+galaxy2" profile="19.09">
    <description>Mixed Effects Model of Evolution</description>
    <macros>
        <import>macros.xml</import>
    </macros>
    <expand macro="requirements"/>
    <command detect_errors="exit_code"><![CDATA[
        @SYMLINK_FILES@
        @HYPHYMPI@ meme
            --alignment ./$input_file
            @INPUT_TREE@
            --code '$gencodeid'
            @branch_options@
            --pvalue '$p_value'
            --output '$meme_output'
            --full-model '$full_model'
        @ERRORS@
    ]]></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_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>