<tool id="hyphy_sm19" name="HyPhy-SM2019" version="@TOOL_VERSION@+galaxy@VERSION_SUFFIX@" profile="@PROFILE@">
    <description>Partition Tree using Modified Slatkin-Maddison Test</description>
    <macros>
        <import>macros.xml</import>
    </macros>
    <expand macro="bio_tools"/>
    <expand macro="requirements"/>
    <command detect_errors="exit_code"><![CDATA[
        ln -s '$input_file' sm19_input.nhx &&
        @HYPHYMP@ sm --tree ./sm19_input.nhx
        --groups '$len($partitions)'
        #for $n, $partition in enumerate($partitions):
            --description-${n+1} '${partition.label}'
            --regexp-${n+1} '${partition.regex}'
        #end for
        --replicates '$replicates'
        --weight '$weight'
        --use-bootstrap '$use_bootstrap'
        --output '$sm19_output' > sm19_stdout.md
        @ERRORS@
        ]]></command>
    <inputs>
        <param name="input_file" type="data" format="nhx,newick,nexus" label="Input tree" help="The Newick tree string defining the topology to use for testing."/>
        <repeat name="partitions" min="2" max="50" title="Partitions">
            <param name="label" type="text" label="Partition label" help="Description for sequences in this compartment."/>
            <param name="regex" type="text" label="Regular expression" help="Regular expression to select the branches in this compartment.">
                <expand macro="regex_sanitizer"/>
            </param>
        </repeat>
        <param name="replicates" type="integer" min="1" max="1000000" value="100" label="Number of bootstrap replicates" help="The number of bootstrap replicates."/>
        <param argument="--weight" type="float" value="0.2" min="0" max="1" label="Probability of branch selection for structured permutation" help="0 = classical Slatkin-Maddison, 1 = fully structured."/>
        <param argument="--use-bootstrap" type="boolean" truevalue="Yes" falsevalue="No" checked="true" label="Use bootstrap weights to respect well supported clades" help="Use bootstrap weights to respect well supported clades."/>
    </inputs>
    <outputs>
        <data name="sm19_output" format="hyphy_results.json" label="SM2019 results on ${on_string}" />
        <data name="sm19_md_report" format="markdown" from_work_dir="sm19_stdout.md" label="SM2019 Report (Markdown) for ${tool.name} on ${on_string}" />
    </outputs>
    <tests>
        <test expect_num_outputs="2">
            <param name="input_file" value="sm19-in1.nhx"/>
            <repeat name="partitions">
                <param name="label" value="Blood"/>
                <param name="regex" value="B[0-9]+"/>
            </repeat>
            <repeat name="partitions">
                <param name="label" value="Semen"/>
                <param name="regex" value="S[0-9]+"/>
            </repeat>
            <param name="replicates" value="1000"/>
            <param name="weight" value="0.2"/>
            <param name="use_bootstrap" value="Yes"/>
            <output name="sm19_output">
                <assert_contents>
                    <has_text text='"compartments":2'/>
                    <has_text text='"leaf-count":50'/>
                </assert_contents>
            </output>
            <output name="sm19_md_report">
                <assert_contents>
                    <has_text text="Inferred **16** migration events"/>
                </assert_contents>
            </output>
        </test>
        <test expect_num_outputs="2">
            <param name="input_file" value="sm19-in2.nhx"/>
            <repeat name="partitions">
                <param name="label" value="Blood"/>
                <param name="regex" value="B[0-9]+"/>
            </repeat>
            <repeat name="partitions">
                <param name="label" value="Semen"/>
                <param name="regex" value="S[0-9]+"/>
            </repeat>
            <param name="replicates" value="1000"/>
            <param name="weight" value="0.2"/>
            <param name="use_bootstrap" value="Yes"/>
            <output name="sm19_output">
                <assert_contents>
                    <has_text text='"compartments":2'/>
                    <has_text text='"leaf-count":64'/>
                </assert_contents>
            </output>
            <output name="sm19_md_report">
                <assert_contents>
                    <has_text text="Inferred **18** migration events"/>
                </assert_contents>
            </output>
        </test>
    </tests>
    <help><![CDATA[
SM2019 : Structured Slatkin-Maddison
====================================

**What does this do?**

Test for evidence of genetically segregated populations, using a "detuned" version of
the Slatkin-Maddison test.

Method
------

The SM2019 tool implements canonical and modified versions of the Slatkin-Maddison phylogeny-based test for population segregation. This method is used to detect evidence of genetically segregated populations within a phylogenetic tree.

**The Slatkin-Maddison Test: Intuition**

The core idea of the Slatkin-Maddison test is to quantify the amount of "mixing" or "segregation" of different populations (or compartments) within a phylogenetic tree. It does this by mapping discrete character states (e.g., population labels like "Blood" or "Semen") onto the tips of the tree. Then, using a parsimony approach, it infers the minimum number of "migration events" (changes in character state) that must have occurred along the branches of the tree to explain the observed distribution of states at the tips.

-   **Minimum Migration Events:** A lower number of inferred migration events suggests stronger population segregation, as fewer changes are needed to explain the observed pattern. A higher number suggests more mixing.

**Hypothesis Testing**

The tool then performs permutation tests to evaluate the significance of the observed number of migration events:

1.  **Panmictic Permutation (Unstructured Population):** Leaf labels are randomly permuted across the tips of the tree. The minimum number of migration events is calculated for each permuted tree. This generates a null distribution representing what would be expected if there were no population structure (i.e., a panmictic population where individuals mix freely). If the observed number of migration events is significantly lower than this null distribution, it suggests evidence for population segregation.

2.  **Structured Permutation (Detuned Test):** This is a modified version of the test. Instead of completely random permutations, leaf labels are permuted partially, respecting the underlying subtree structure (block permutations). This "detuned" approach can be more powerful in detecting subtle population structure by accounting for phylogenetic relationships. The `weight` parameter controls the degree of structure in these permutations.

**Interpretation of Results**

-   A significant p-value (typically < 0.05) from the panmictic permutation test indicates that the observed population structure (segregation) is unlikely to have arisen by chance in an unstructured population.
-   The structured permutation test provides a more nuanced view, accounting for some phylogenetic signal.

**Output:** The tool outputs the inferred number of migration events and p-values for both panmictic and structured permutations, allowing for a comprehensive assessment of population segregation.

**Input**

- **Input tree:** A phylogenetic tree in Newick format. Leaf names should be partitionable into sets using regular expressions.

**Tool Options**

- **Input tree:** The Newick tree string defining the topology to use for testing.
- **Partitions:** Define the compartments (groups of leaves) for the analysis.
    - **Partition label:** A descriptive label for the compartment.
    - **Regular expression:** A regular expression to select the branches belonging to this compartment.
- **Number of bootstrap replicates:** The number of bootstrap replicates to perform for the permutation tests.
- **Probability of branch selection for structured permutation:** This parameter controls the type of permutation. A value of 0 corresponds to the classical Slatkin-Maddison test (full panmixia), while a value of 1 corresponds to a fully structured permutation.
- **Use bootstrap weights to respect well supported clades:** If set to Yes, bootstrap weights are used to respect well-supported clades during permutations.

**Output**

- A JSON file with detailed analysis results, including migration events, p-values for panmictic and structured permutations, and partition counts.
- A Markdown report summarizing the analysis and results.

**Further reading**

- https://www.ncbi.nlm.nih.gov/pubmed/2599370
- https://github.com/veg/hyphy-analyses/tree/master/SlatkinMaddison
    ]]></help>
    <expand macro="citations">
        <citation type="bibtex">
            @PUBLISHED{slatkin,
                author = "Slatkin M, Maddison WP",
                title = "A cladistic measure of gene flow inferred from the phylogenies of alleles",
                year = "1989",
                note = "Genetics 123(3):603-613",
                url = "https://www.ncbi.nlm.nih.gov/pubmed/2599370"}
        </citation>
    </expand>
</tool>