annotate hyphy_busted.xml @ 6:f9a193154a55 draft

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

<?xml version="1.0"?>
<tool id="hyphy_busted" name="HyPhy-BUSTED" version="@VERSION@+galaxy0">
    <description>Branch-site Unrestricted Statistical Test for Episodic Diversification</description>
    <macros>
        <import>macros.xml</import>
    </macros>
    <expand macro="requirements"/>
    <command detect_errors="exit_code"><![CDATA[
        ln -s '$input_file' busted_input.fa &&
        ln -s '$input_nhx' busted_input.nhx &&
        hyphy busted
            --alignment ./busted_input.fa
            --tree ./busted_input.nhx
            --code $gencodeid
            --branches '$branches'
            --output '$busted_output'
            > '$busted_log'
        ]]></command>
    <inputs>
        <expand macro="inputs"/>
        <expand macro="gencode"/>
        <expand macro="branches"/>
    </inputs>
    <outputs>
        <data name="busted_log" format="txt"/>
        <data name="busted_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="busted_output" file="busted-out1.json" compare="sim_size"/>
        </test>
    </tests>
    <help><![CDATA[
    
BUSTED : Bayesian UnresTricted Test of Episodic Diversification
===============================================================  
    
What question does this method answer?
--------------------------------------

Is there evidence that some sites in the alignment have been subject to positive diversifying selection, 
either pervasive (throughout the evolutionary tree) or episodic (only on some lineages)? 
In other words, BUSTED asks whether a given gene has been subject to positive, diversifying selection at any site, at any time. 
If a priori information about lineages of interest is available (e.g., due to migration, change in the environment, etc.),
then BUSTED can be restricted to test for selection only on a subset of tree lineages, potentially boosting power.

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

1. Annotating a collection of alignments with a binary attribute: has this alignment been subject to positive diversifying selection (yes/no)? 
2. Testing small or low-divergence alignments (i.e. ~30 sequences) for evidence of positive diversifying selection, where neither branch nor site level methods have sufficient power.

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

BUSTED (branch-site unrestricted statistical test of episodic
diversification) uses a random effects branch-site model fitted jointly
to all or a subset of tree branches in order to test for alignment-wide
evidence of episodic diversifying selection. Assuming there is evidence
of positive selection (i.e. there is an omega > 1), BUSTED will also
perform a quick evidence-ratio style analysis to explore which
individual sites may have been subject to selection. 


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).

For each tested branch the analysis will infer the appropriate number of selective regimes, 
and whether or not there is statistical evidence of positive selection on that branch.

A custom visualization module for viewing these results is available (see http://vision.hyphy.org/BUSTED for an example)

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

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


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/)
    ]]>
    </help>
    <expand macro="citations">
        <citation type="doi">10.1093/molbev/msv035</citation>
    </expand>
</tool>