annotate qiime2__composition__ancombc2.xml @ 2:be06c0928b48 draft default tip

planemo upload for repository https://github.com/qiime2/galaxy-tools/tree/main/tools/suite_qiime2__composition commit 64ed09f1f1c680ad8373d261bd6be43a4f8a8d5b

<?xml version='1.0' encoding='utf-8'?>
<!--
Copyright (c) 2025, QIIME 2 development team.

Distributed under the terms of the Modified BSD License. (SPDX: BSD-3-Clause)
-->
<!--
This tool was automatically generated by:
    q2galaxy (version: 2025.10.0)
for:
    qiime2 (version: 2025.10.0)
-->
<tool name="qiime2 composition ancombc2" id="qiime2__composition__ancombc2" version="2025.10.0+q2galaxy.2025.10.0" profile="22.05" license="BSD-3-Clause">
    <description>ANCOM-BC2: Analysis of Composition of Microbiomes with Bias Correction 2.</description>
    <xrefs>
        <xref type="bio.tools">qiime2</xref>
    </xrefs>
    <requirements>
        <container type="docker">quay.io/qiime2/amplicon:2025.10</container>
    </requirements>
    <version_command>q2galaxy version composition</version_command>
    <command detect_errors="exit_code">q2galaxy run composition ancombc2 '$inputs'</command>
    <configfiles>
        <inputs name="inputs" data_style="staging_path_and_source_path"/>
    </configfiles>
    <inputs>
        <param name="table" type="data" format="qza" label="table: FeatureTable[Frequency]" help="[required]  The feature table to be used for ANCOM-BC2 computation.">
            <options options_filter_attribute="metadata.semantic_type">
                <filter type="add_value" value="FeatureTable[Frequency]"/>
            </options>
            <validator type="expression" message="Incompatible type">hasattr(value.metadata, "semantic_type") and value.metadata.semantic_type in ['FeatureTable[Frequency]']</validator>
        </param>
        <repeat name="metadata" min="1" help="[required]  The per-sample metadata." title="metadata: Metadata">
            <conditional name="__q2galaxy__GUI__conditional__metadata__">
                <param name="type" type="select" label="metadata: Metadata">
                    <option value="tsv" selected="true">Metadata from TSV</option>
                    <option value="qza">Metadata from Artifact</option>
                </param>
                <when value="tsv">
                    <param name="source" type="data" format="tabular,qiime2.tabular" label="Metadata Source"/>
                </when>
                <when value="qza">
                    <param name="source" type="data" format="qza" label="Metadata Source"/>
                </when>
            </conditional>
        </repeat>
        <param name="fixed_effects_formula" type="text" label="fixed_effects_formula: Str" help="[required]  A formula that expresses how the feature absolute abundances in the feature table depend on the fixed effects of variables (columns) in the metadata. Do not include the dependent variable. Reference the `formula` function in the `stats` R package for a specification of valid formulae.">
            <sanitizer>
                <valid initial="string.printable"/>
            </sanitizer>
            <validator type="expression" message="Please verify this parameter.">value is not None and len(value) &gt; 0</validator>
        </param>
        <section name="__q2galaxy__GUI__section__extra_opts__" title="Click here for additional options">
            <conditional name="__q2galaxy__GUI__conditional__random_effects_formula__" label="random_effects_formula: Str">
                <param name="__q2galaxy__GUI__select__" type="select" label="random_effects_formula: Str" help="[optional]  A formula that expresses how the feature absolute abundances in the feature table depend on the random effects of variables (columns) in the metadata. Do not include the dependent variable. For example, to specify `MyVariable` as a random intercept use the syntax `(1 | MyVariable)`. Reference the `lmerTest` R package for a specification of valid formulae.">
                    <option value="__q2galaxy__::control::default" selected="true">None (Use default behavior)</option>
                    <option value="__q2galaxy__::control::provide">Provide a value</option>
                </param>
                <when value="__q2galaxy__::control::default">
                    <param name="random_effects_formula" type="hidden" value="__q2galaxy__::literal::None"/>
                </when>
                <when value="__q2galaxy__::control::provide">
                    <param name="random_effects_formula" type="text">
                        <sanitizer>
                            <valid initial="string.printable"/>
                        </sanitizer>
                    </param>
                </when>
            </conditional>
            <repeat name="reference_levels" help="[optional]  Specify reference levels for one or more categorical metadata variables (columns). The method of specification is &quot;column_name::column_value&quot;. E.g. &quot;sex::female&quot; sets the &quot;female&quot; category of the &quot;sex&quot; variable to be the reference level. Separate multiple specifications by spaces." title="reference_levels: List[Str]">
                <param name="element" type="text" label="element: Str" help="[required]">
                    <sanitizer>
                        <valid initial="string.printable"/>
                    </sanitizer>
                    <validator type="expression" message="Please verify this parameter.">value is not None and len(value) &gt; 0</validator>
                </param>
            </repeat>
            <param name="p_adjust_method" type="text" value="holm" label="p_adjust_method: Str" help="[default: 'holm']  The method used to adjust p-values. Choose from &quot;holm&quot;, &quot;hochberg&quot;, &quot;hommel&quot;, &quot;bonferroni&quot;,  &quot;BH&quot;, &quot;BY&quot;, &quot;fdr&quot;, &quot;none&quot;. See the `p.adjust` method in the `stats` R package for explanations of each option.">
                <sanitizer>
                    <valid initial="string.printable"/>
                </sanitizer>
            </param>
            <param name="prevalence_cutoff" type="float" min="0.0" max="1.0" value="0.1" label="prevalence_cutoff: Float % Range(0.0, 1.0, inclusive_end=True)" help="[default: 0.1]  Features with prevalences less than this threshold will be excluded from the analysis."/>
            <conditional name="__q2galaxy__GUI__conditional__group__" label="group: Str">
                <param name="__q2galaxy__GUI__select__" type="select" label="group: Str" help="[optional]  The name of the group variable in the metadata. The group variable must be categorical and is required to detect structural zeros.">
                    <option value="__q2galaxy__::control::default" selected="true">None (Use default behavior)</option>
                    <option value="__q2galaxy__::control::provide">Provide a value</option>
                </param>
                <when value="__q2galaxy__::control::default">
                    <param name="group" type="hidden" value="__q2galaxy__::literal::None"/>
                </when>
                <when value="__q2galaxy__::control::provide">
                    <param name="group" type="text">
                        <sanitizer>
                            <valid initial="string.printable"/>
                        </sanitizer>
                    </param>
                </when>
            </conditional>
            <param name="structural_zeros" type="boolean" truevalue="__q2galaxy__::literal::True" falsevalue="__q2galaxy__::literal::False" label="structural_zeros: Bool" help="[default: No]  Whether to detect structurual zeros based on the `group` variable. Refer to the ANCOM-BC2 paper for an expalanation of the use of structural zeros."/>
            <param name="asymptotic_cutoff" type="boolean" truevalue="__q2galaxy__::literal::True" falsevalue="__q2galaxy__::literal::False" label="asymptotic_cutoff: Bool" help="[default: No]  Whether to classify a taxon as a structural zero using its asymptotic lower bound. Generally, it is recommended to set this parameter when the sample size per group is relatively large (n &gt; 30). When this parameter is not set, a feature is classified as a structural zero in a group if its frequency is zero in that group. See the ANCOM-BC2 publication for details."/>
            <param name="alpha" type="float" min="1e-06" max="1.0" value="0.05" label="alpha: Float % Range(0.0, 1.0, inclusive_start=False, inclusive_end=True)" help="[default: 0.05]  The significance level."/>
        </section>
    </inputs>
    <outputs>
        <data name="ancombc2_output" format="qza" label="${tool.name} on ${on_string}: ancombc2_output.qza" from_work_dir="ancombc2_output.qza"/>
    </outputs>
    <tests>
        <test>
            <param name="table" value="ancombc2.test0.table.qza" ftype="qza"/>
            <repeat name="metadata">
                <conditional name="__q2galaxy__GUI__conditional__metadata__">
                    <param name="type" value="tsv"/>
                    <param name="source" value="ancombc2.test0.metadata.tsv" ftype="qiime2.tabular"/>
                </conditional>
            </repeat>
            <param name="fixed_effects_formula" value="bodysite"/>
            <output name="ancombc2_output" ftype="qza">
                <assert_contents>
                    <has_archive_member path="[0-9a-f]{8}-[0-9a-f]{4}-[4][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\/metadata.yaml">
                        <has_line_matching expression="type: FeatureData\[ANCOMBC2Output\]"/>
                    </has_archive_member>
                </assert_contents>
            </output>
        </test>
        <test>
            <param name="table" value="ancombc2.test1.table.qza" ftype="qza"/>
            <repeat name="metadata">
                <conditional name="__q2galaxy__GUI__conditional__metadata__">
                    <param name="type" value="tsv"/>
                    <param name="source" value="ancombc2.test1.metadata.tsv" ftype="qiime2.tabular"/>
                </conditional>
            </repeat>
            <param name="fixed_effects_formula" value="bodysite + animal"/>
            <repeat name="reference_levels">
                <param name="element" value="bodysite::tongue"/>
            </repeat>
            <repeat name="reference_levels">
                <param name="element" value="animal::dog"/>
            </repeat>
            <output name="ancombc2_output" ftype="qza">
                <assert_contents>
                    <has_archive_member path="[0-9a-f]{8}-[0-9a-f]{4}-[4][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\/metadata.yaml">
                        <has_line_matching expression="type: FeatureData\[ANCOMBC2Output\]"/>
                    </has_archive_member>
                </assert_contents>
            </output>
        </test>
    </tests>
    <help>
QIIME 2: composition ancombc2
=============================
ANCOM-BC2: Analysis of Composition of Microbiomes with Bias Correction 2.


Outputs:
--------
:ancombc2_output.qza: The estimated log fold changes and their standard errors for the variables included in the mixed effects model. Also includes the structural zero designations if the `structural_zeros` parameter is passed.

|  

Description:
------------
Calls the `ancombc2` function of the ANCOMBC software package. See the ANCOM-BC2 publication and source code for details.

Sensitivity Analysis for Pseudo-Count Addition: To assess robustness, a series of pseudo-counts (0.01 to 0.5, in 0.01 increments) is added to zero counts, and a linear model is fitted to the bias-corrected log-abundance data for each. A sensitivity score is calculated as the proportion of p-values above the specified alpha. Taxa with consistent significance across all pseudo-counts, and agreement with complete-data results, are flagged as robust (diff_robust = TRUE). Note: Results depend on the selected alpha value.

Examples:
---------

single-variable
***************
Using the ``qiime2 composition ancombc2`` tool:
 #. Set *"table"* to ``#: table.qza``
 #. For *"metadata"*:

    - Perform the following steps.

      #. Leave as ``Metadata from TSV``
      #. Set *"Metadata Source"* to ``metadata.tsv``


 #. Set *"fixed_effects_formula"* to ``bodysite``
 #. Press the ``Execute`` button.

Once completed, for the new entry in your history, use the ``Edit`` button to set the name as follows:
 (Renaming is optional, but it will make any subsequent steps easier to complete.)

 .. list-table::
    :align: left
    :header-rows: 1

    * - History Name
      - *"Name"* to set (be sure to press ``Save``)
    * - ``#: qiime2 composition ancombc2 [...] : ancombc2_output.qza``
      - ``abc2-output.qza``

multi-variable-reference
************************
Using the ``qiime2 composition ancombc2`` tool:
 #. Set *"table"* to ``#: table.qza``
 #. For *"metadata"*:

    - Perform the following steps.

      #. Leave as ``Metadata from TSV``
      #. Set *"Metadata Source"* to ``metadata.tsv``


 #. Set *"fixed_effects_formula"* to ``bodysite + animal``
 #. Expand the ``additional options`` section

    - For *"reference_levels"*, use the ``+ reference_levels`` button to add the corresponding values:

      #. Add *"element"* set to ``bodysite::tongue``
      #. Add *"element"* set to ``animal::dog``


 #. Press the ``Execute`` button.

Once completed, for the new entry in your history, use the ``Edit`` button to set the name as follows:
 (Renaming is optional, but it will make any subsequent steps easier to complete.)

 .. list-table::
    :align: left
    :header-rows: 1

    * - History Name
      - *"Name"* to set (be sure to press ``Save``)
    * - ``#: qiime2 composition ancombc2 [...] : ancombc2_output.qza``
      - ``abc2-output.qza``


|  

</help>
    <citations>
        <citation type="doi">https://www.nature.com/articles/s41592-023-02092-7</citation>
        <citation type="doi">10.1038/s41587-019-0209-9</citation>
    </citations>
</tool>