<tool id="hyphy_absrel" name="HyPhy-aBSREL" version="@TOOL_VERSION@+galaxy@VERSION_SUFFIX@" profile="@PROFILE@">
    <description>adaptive Branch Site Random Effects Likelihood</description>
    <macros>
        <import>macros.xml</import>
    </macros>
    <expand macro="bio_tools"/>
    <expand macro="requirements"/>
    <command detect_errors="exit_code"><![CDATA[
        @SYMLINK_FILES@
        ln -s '$absrel_output' ${input_file}.aBSREL.json &&
        @HYPHYMP@ absrel
            --alignment ./$input_file
            @INPUT_TREE@
            --code '$gencodeid'
            @branch_options@
            --output '$absrel_output'
            --multiple-hits $multiple_hits
            @srv_options@
            --blb $blb
            --kill-zero-lengths $kill_zero_lengths > absrel_stdout.md
        @ERRORS@
        ]]></command>
    <inputs>
        <expand macro="inputs"/>
        <expand macro="gencode"/>
        <expand macro="branches"/>
        <section name="advanced_options" title="Advanced Options" expanded="false">
            <param argument="--multiple-hits" type="select" label="Include support for multiple nucleotide substitutions" help="Include support for multiple nucleotide substitutions.">
                <option value="Double">Include branch-specific rates for double nucleotide substitutions</option>
                <option value="Double+Triple">Include branch-specific rates for double and triple nucleotide substitutions</option>
                <option value="None" selected="true">Use standard models which permit only single nucleotide changes to occur instantly</option>
            </param>
            <param argument="--blb" type="float" value="1.0" label="Bag of little bootstrap alignment resampling rate" help="[Advanced option] Bag of Little Bootstraps (BLB) alignment resampling rate (default: 1.0). This parameter controls the fraction of sites to resample for each bootstrap replicate. BLB uses down/upsampling approaches to speed up inference for very long alignments by analyzing subsets of the data."/>
            <conditional name="srv_conditional">
                <param name="srv_enabled" type="select" label="Include synonymous rate variation" help="Include synonymous rate variation.">
                    <option value="true" selected="true">Yes</option>
                    <option value="false">No</option>
                </param>
                <when value="true">
                    <param argument="--syn-rates" type="integer" value="3" min="1" max="10" label="Synonymous rate classes" help="The number of alpha rate classes to include in the model [1-10, default 3]"/>
                </when>
                <when value="false">
                </when>
            </conditional>
            <expand macro="kill_zero_lengths_param"/>
        </section>
    </inputs>
    <outputs>
        <data name="absrel_md_report" format="markdown" from_work_dir="absrel_stdout.md" label="aBSREL Report (Markdown) for ${tool.name} on ${on_string}" />
        <data name="absrel_output" format="hyphy_results.json" />
    </outputs>
    <tests>
        <test expect_num_outputs="2">
            <param name="input_file" ftype="fasta" value="absrel-in1.fa"/>
            <param name="input_nhx" ftype="nhx" value="absrel-in1.nhx"/>
            <output name="absrel_output">
                <assert_contents>
                    <has_text text="fits"/>
                    <has_text text="branch attributes"/>
                    <has_text text="Full adaptive model"/>
                </assert_contents>
            </output>
            <output name="absrel_md_report">
                <assert_contents>
                    <has_text text="found **1** branches under selection among **5** tested"/>
                </assert_contents>
            </output>
        </test>
        <test expect_num_outputs="2">
            <param name="input_file" ftype="fasta" value="absrel-in1.fa"/>
            <param name="input_nhx" ftype="nhx" value="absrel-in1.nhx"/>
            <section name="advanced_options">
                <param name="multiple_hits" value="Double" />
            </section>
            <output name="absrel_output">
                <assert_contents>
                    <has_text text="fits"/>
                    <has_text text="branch attributes"/>
                    <has_text text="Full adaptive model"/>
                </assert_contents>
            </output>
            <output name="absrel_md_report">
                <assert_contents>
                    <has_text text="found **0** branches under selection among **5** tested"/>
                 <has_text text="Branch-level rate at which 2 nucleotides are changed instantly"/>
                </assert_contents>
            </output>
        </test>
        <test expect_num_outputs="2">
            <param name="input_file" ftype="fasta" value="absrel-in1.fa"/>
            <param name="input_nhx" ftype="nhx" value="absrel-in1.nhx"/>
            <section name="advanced_options">
                <param name="multiple_hits" value="Double" />
                <conditional name="srv_conditional">
                    <param name="srv_enabled" value="true" />
                </conditional>
            </section>
            <output name="absrel_output">
                <assert_contents>
                    <has_text text="fits"/>
                    <has_text text="branch attributes"/>
                    <has_text text="Full adaptive model"/>
                </assert_contents>
            </output>
            <output name="absrel_md_report">
                <assert_contents>
                    <has_text text="found **0** branches under selection among **5** tested"/>
                    <has_text text="Branch-level rate at which 2 nucleotides are changed instantly"/>
                    <has_text text="The following rate distribution for site-to-site **synonymous** rate variation was inferred"/>
                </assert_contents>
            </output>
         </test>
    </tests>
    <help><![CDATA[
aBSREL: Adaptive Branch-Site Random Effects Likelihood
======================================================

**What question does this method answer?**

aBSREL (adaptive Branch-Site Random Effects Likelihood) is a powerful method for detecting episodic positive selection. It identifies instances where a proportion of sites along specific branches or lineages of a phylogeny have undergone positive selection.

**Recommended Applications**

1.  **Detecting Episodic Diversifying Selection:** Ideal for exploratory testing to find evidence of lineage-specific positive diversifying selection in alignments of various sizes.
2.  **Targeted Branch Testing:** Suitable for targeted testing of branches hypothesized to be under positive selection, even in alignments that would be computationally prohibitive for older branch-site models.

**Methodology**

aBSREL is an adaptive branch-site random effects likelihood model that allows the dN/dS ratio to vary across sites and branches. The key innovation of aBSREL is its adaptive nature: it infers the optimal number of dN/dS rate classes for each branch, providing a more nuanced and powerful test for positive selection compared to traditional fixed-rate models.

**The Intuition**

Imagine a gene evolving across a phylogeny. On some branches, the gene might be under strong purifying selection, with most non-synonymous mutations being deleterious. On other branches, the gene might be evolving neutrally. And on a few key branches, the gene might be under positive selection, with non-synonymous mutations providing a fitness advantage.

Traditional branch-site models test for positive selection by fitting a model with a fixed number of dN/dS rate classes to each branch. This can be problematic because the evolutionary process is not always so uniform. Some branches might have a simple evolutionary history that can be described by one or two dN/dS rates, while others might have a more complex history that requires more rate classes.

aBSREL addresses this by starting with a simple model for each branch and incrementally adding more rate classes until the model fit no longer improves. This "adaptive" approach allows the model to tailor itself to the complexity of the evolutionary process on each branch, leading to a more accurate and powerful test for positive selection.

**The Test**

For each branch, aBSREL performs a likelihood ratio test to determine if a model that allows for positive selection (i.e., a dN/dS ratio > 1) is a significantly better fit than a model that does not. The p-values from these tests are then corrected for multiple testing to identify branches that show statistically significant evidence of positive 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/aBSREL for an example)

**Further reading**

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


**Tool options**
::

    --alignment         [required] An in-frame codon alignment in one of the formats supported by HyPhy

    --tree              [conditionally required] A phylogenetic tree (optionally annotated with {})

    --code              Which genetic code to use (see tool form for available options)

    --branches          Which branches should be tested for selection?
                            All [default]
                            Internal
                            Leaves
                            Unlabeled branches
                            Custom : Enter a branch label

    --multiple-hits     Include support for multiple nucleotide substitutions
                            Double : Include branch-specific rates for double nucleotide substitutions
                            Double+Triple : Include branch-specific rates for double and triple nucleotide substitutions
                            None [default] : Use standard models which permit only single nucleotide changes to occur instantly

    --srv               Include synonymous rate variation (default: No)
                            If Yes, then:
                                --syn-rates         The number alpha rate classes to include in the model [1-10, default 3]

    --blb               [Advanced option] Bag of Little Bootstraps (BLB) alignment resampling rate (default: 1.0). This parameter controls the fraction of sites to resample for each bootstrap replicate. BLB uses down/upsampling approaches to speed up inference for very long alignments by analyzing subsets of the data. For more details, see https://www.nature.com/articles/s43588-021-00129-5.

    --output            Write the resulting JSON to this file (default is to save to the same path as the alignment file + 'ABSREL.json')



    --kill-zero-lengths Automatically delete internal zero-length branches for computational efficiency
                            Yes [default] : Automatically delete internal zero-length branches for computational efficiency (will not affect results otherwise)
                            Constrain : Keep zero-length branches, but constrain their values to 0
                            No : Keep all branches

    --save-fit          Save full adaptive aBSREL model fit to this file (default is not to save)



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