annotate qiime2__diversity_lib__beta_phylogenetic_passthrough.xml @ 1:423e0a6e9a1f draft

planemo upload for repository https://github.com/qiime2/galaxy-tools/tree/main/tools/suite_qiime2__diversity_lib commit 69da7976573cc07a363ac66bdacc9269d7cd3732

<?xml version='1.0' encoding='utf-8'?>
<!--
Copyright (c) 2023, 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: 2022.11.1)
for:
    qiime2 (version: 2022.11.1)
-->
<tool name="qiime2 diversity-lib beta-phylogenetic-passthrough" id="qiime2__diversity_lib__beta_phylogenetic_passthrough" version="2022.11.1+q2galaxy.2022.11.1.2" profile="22.05" license="BSD-3-Clause">
    <description>Beta Phylogenetic Passthrough</description>
    <requirements>
        <container type="docker">quay.io/qiime2/core:2022.11</container>
    </requirements>
    <version_command>q2galaxy version diversity_lib</version_command>
    <command detect_errors="exit_code">q2galaxy run diversity_lib beta_phylogenetic_passthrough '$inputs'</command>
    <configfiles>
        <inputs name="inputs" data_style="paths"/>
    </configfiles>
    <inputs>
        <param name="table" type="data" format="qza" label="table: FeatureTable[Frequency]" help="[required]  The feature table containing the samples over which beta diversity should be computed.">
            <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>
        <param name="phylogeny" type="data" format="qza" label="phylogeny: Phylogeny[Rooted]" help="[required]  Phylogenetic tree containing tip identifiers that correspond to the feature identifiers in the table. This tree can contain tip ids that are not present in the table, but all feature ids in the table must be present in this tree.">
            <options options_filter_attribute="metadata.semantic_type">
                <filter type="add_value" value="Phylogeny[Rooted]"/>
            </options>
            <validator type="expression" message="Incompatible type">hasattr(value.metadata, "semantic_type") and value.metadata.semantic_type in ['Phylogeny[Rooted]']</validator>
        </param>
        <param name="metric" type="select" label="metric: Str % Choices('generalized_unifrac', 'unweighted_unifrac', 'weighted_normalized_unifrac', 'weighted_unifrac')" display="radio">
            <option value="__q2galaxy__::literal::None">Selection required</option>
            <option value="generalized_unifrac">generalized_unifrac</option>
            <option value="unweighted_unifrac">unweighted_unifrac</option>
            <option value="weighted_normalized_unifrac">weighted_normalized_unifrac</option>
            <option value="weighted_unifrac">weighted_unifrac</option>
            <validator type="expression" message="Please verify this parameter.">value != '__q2galaxy__::literal::None'</validator>
        </param>
        <section name="__q2galaxy__GUI__section__extra_opts__" title="Click here for additional options">
            <conditional name="__q2galaxy__GUI__conditional__threads__">
                <param name="__q2galaxy__GUI__select__" type="select" label="threads: Int % Range(1, None) | Str % Choices('auto')" help="[default: 1]  The number of CPU threads to use in performing this calculation. May not exceed the number of available physical cores. If threads = 'auto', one thread will be created for each identified CPU core on the host.">
                    <option value="auto">auto (Str)</option>
                    <option value="__q2galaxy__::control::Int X Range(1__comma__ None)" selected="true">Provide a value (Int % Range(1, None))</option>
                </param>
                <when value="auto">
                    <param name="threads" type="hidden" value="auto"/>
                </when>
                <when value="__q2galaxy__::control::Int X Range(1__comma__ None)">
                    <param name="threads" type="integer" min="1" value="1" label="threads: Int % Range(1, None)" help="[default: 1]  The number of CPU threads to use in performing this calculation. May not exceed the number of available physical cores. If threads = 'auto', one thread will be created for each identified CPU core on the host."/>
                </when>
            </conditional>
            <param name="variance_adjusted" type="boolean" truevalue="__q2galaxy__::literal::True" falsevalue="__q2galaxy__::literal::False" label="variance_adjusted: Bool" help="[default: No]  Perform variance adjustment based on Chang et al. BMC Bioinformatics 2011. Weights distances based on the proportion of the relative abundance represented between the samples at a given node under evaluation."/>
            <param name="alpha" type="float" min="0" max="1" optional="true" label="alpha: Float % Range(0, 1, inclusive_end=True)" help="[optional]  This parameter is only used when the choice of metric is generalized_unifrac. The value of alpha controls importance of sample proportions. 1.0 is weighted normalized UniFrac. 0.0 is close to unweighted UniFrac, but only if the sample proportions are dichotomized."/>
            <param name="bypass_tips" type="boolean" truevalue="__q2galaxy__::literal::True" falsevalue="__q2galaxy__::literal::False" label="bypass_tips: Bool" help="[default: No]  In a bifurcating tree, the tips make up about 50% of the nodes in a tree. By ignoring them, specificity can be traded for reduced compute time. This has the effect of collapsing the phylogeny, and is analogous (in concept) to moving from 99% to 97% OTUs"/>
        </section>
    </inputs>
    <outputs>
        <data name="distance_matrix" format="qza" label="${tool.name} on ${on_string}: distance_matrix.qza" from_work_dir="distance_matrix.qza"/>
    </outputs>
    <tests>
        <test>
            <param name="table" value="beta_phylogenetic_passthrough.test0.feature-table.qza" ftype="qza"/>
            <param name="phylogeny" value="beta_phylogenetic_passthrough.test0.phylogeny.qza" ftype="qza"/>
            <param name="metric" value="weighted_normalized_unifrac"/>
            <output name="distance_matrix" 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: DistanceMatrix"/>
                    </has_archive_member>
                </assert_contents>
            </output>
        </test>
        <test>
            <param name="table" value="beta_phylogenetic_passthrough.test1.feature-table.qza" ftype="qza"/>
            <param name="phylogeny" value="beta_phylogenetic_passthrough.test1.phylogeny.qza" ftype="qza"/>
            <param name="metric" value="weighted_normalized_unifrac"/>
            <conditional name="__q2galaxy__GUI__conditional__threads__">
                <param name="__q2galaxy__GUI__select__" value="__q2galaxy__::control::Int X Range(1__comma__ None)"/>
                <param name="threads" value="1"/>
            </conditional>
            <output name="distance_matrix" 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: DistanceMatrix"/>
                    </has_archive_member>
                </assert_contents>
            </output>
        </test>
        <test>
            <param name="table" value="beta_phylogenetic_passthrough.test2.feature-table.qza" ftype="qza"/>
            <param name="phylogeny" value="beta_phylogenetic_passthrough.test2.phylogeny.qza" ftype="qza"/>
            <param name="metric" value="weighted_normalized_unifrac"/>
            <conditional name="__q2galaxy__GUI__conditional__threads__">
                <param name="__q2galaxy__GUI__select__" value="auto"/>
                <param name="threads" value="auto"/>
            </conditional>
            <output name="distance_matrix" 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: DistanceMatrix"/>
                    </has_archive_member>
                </assert_contents>
            </output>
        </test>
        <test>
            <param name="table" value="beta_phylogenetic_passthrough.test3.feature-table.qza" ftype="qza"/>
            <param name="phylogeny" value="beta_phylogenetic_passthrough.test3.phylogeny.qza" ftype="qza"/>
            <param name="metric" value="weighted_normalized_unifrac"/>
            <conditional name="__q2galaxy__GUI__conditional__threads__">
                <param name="__q2galaxy__GUI__select__" value="auto"/>
                <param name="threads" value="auto"/>
            </conditional>
            <param name="bypass_tips" value="__q2galaxy__::literal::True"/>
            <output name="distance_matrix" 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: DistanceMatrix"/>
                    </has_archive_member>
                </assert_contents>
            </output>
        </test>
        <test>
            <param name="table" value="beta_phylogenetic_passthrough.test4.feature-table.qza" ftype="qza"/>
            <param name="phylogeny" value="beta_phylogenetic_passthrough.test4.phylogeny.qza" ftype="qza"/>
            <param name="metric" value="weighted_unifrac"/>
            <conditional name="__q2galaxy__GUI__conditional__threads__">
                <param name="__q2galaxy__GUI__select__" value="auto"/>
                <param name="threads" value="auto"/>
            </conditional>
            <param name="variance_adjusted" value="__q2galaxy__::literal::True"/>
            <output name="distance_matrix" 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: DistanceMatrix"/>
                    </has_archive_member>
                </assert_contents>
            </output>
        </test>
        <test>
            <param name="table" value="beta_phylogenetic_passthrough.test5.feature-table.qza" ftype="qza"/>
            <param name="phylogeny" value="beta_phylogenetic_passthrough.test5.phylogeny.qza" ftype="qza"/>
            <param name="metric" value="generalized_unifrac"/>
            <output name="distance_matrix" 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: DistanceMatrix"/>
                    </has_archive_member>
                </assert_contents>
            </output>
        </test>
        <test>
            <param name="table" value="beta_phylogenetic_passthrough.test6.feature-table.qza" ftype="qza"/>
            <param name="phylogeny" value="beta_phylogenetic_passthrough.test6.phylogeny.qza" ftype="qza"/>
            <param name="metric" value="generalized_unifrac"/>
            <param name="alpha" value="0.75"/>
            <output name="distance_matrix" 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: DistanceMatrix"/>
                    </has_archive_member>
                </assert_contents>
            </output>
        </test>
    </tests>
    <help>
QIIME 2: diversity-lib beta-phylogenetic-passthrough
====================================================
Beta Phylogenetic Passthrough


Outputs:
--------
:distance_matrix.qza: The resulting distance matrix.

|  

Description:
------------
Computes a distance matrix for all pairs of samples in a feature table using the unifrac implementation of the selected beta diversity metric.

Examples:
---------

run on one core (by default)
****************************
Using the ``qiime2 diversity-lib beta-phylogenetic-passthrough`` tool:
 #. Set *"table"* to ``#: feature-table.qza``
 #. Set *"phylogeny"* to ``#: phylogeny.qza``
 #. Set *"metric"* to ``weighted_normalized_unifrac``
 #. 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 diversity-lib beta-phylogenetic-passthrough [...] : distance_matrix.qza``
      - ``weighted-normalized-unifrac-dm.qza``

to run on n cores, replace 1 here with your preferred integer
*************************************************************
Using the ``qiime2 diversity-lib beta-phylogenetic-passthrough`` tool:
 #. Set *"table"* to ``#: feature-table.qza``
 #. Set *"phylogeny"* to ``#: phylogeny.qza``
 #. Set *"metric"* to ``weighted_normalized_unifrac``
 #. Expand the ``additional options`` section

    - Leave *"threads"* as its default value of ``1``

 #. 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 diversity-lib beta-phylogenetic-passthrough [...] : distance_matrix.qza``
      - ``weighted-normalized-unifrac-dm.qza``

use 'auto' to run on all of host system's available CPU cores
*************************************************************
Using the ``qiime2 diversity-lib beta-phylogenetic-passthrough`` tool:
 #. Set *"table"* to ``#: feature-table.qza``
 #. Set *"phylogeny"* to ``#: phylogeny.qza``
 #. Set *"metric"* to ``weighted_normalized_unifrac``
 #. Expand the ``additional options`` section

    - Set *"threads"* to ``auto``

 #. 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 diversity-lib beta-phylogenetic-passthrough [...] : distance_matrix.qza``
      - ``weighted-normalized-unifrac-dm.qza``

use bypass_tips to trade specificity for reduced compute time
*************************************************************
| bypass_tips can be used with any threads setting, but auto may be a good choice if you're trimming run time.
Using the ``qiime2 diversity-lib beta-phylogenetic-passthrough`` tool:
 #. Set *"table"* to ``#: feature-table.qza``
 #. Set *"phylogeny"* to ``#: phylogeny.qza``
 #. Set *"metric"* to ``weighted_normalized_unifrac``
 #. Expand the ``additional options`` section

    #. Set *"threads"* to ``auto``
    #. Set *"bypass_tips"* to ``Yes``

 #. 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 diversity-lib beta-phylogenetic-passthrough [...] : distance_matrix.qza``
      - ``weighted-normalized-unifrac-dm.qza``

variance adjustment
*******************
| Chang et al's variance adjustment may be applied to any unifrac method by using this passthrough function.
Using the ``qiime2 diversity-lib beta-phylogenetic-passthrough`` tool:
 #. Set *"table"* to ``#: feature-table.qza``
 #. Set *"phylogeny"* to ``#: phylogeny.qza``
 #. Set *"metric"* to ``weighted_unifrac``
 #. Expand the ``additional options`` section

    #. Set *"threads"* to ``auto``
    #. Set *"variance_adjusted"* to ``Yes``

 #. 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 diversity-lib beta-phylogenetic-passthrough [...] : distance_matrix.qza``
      - ``var-adj-weighted-unifrac-dm.qza``

minimal generalized unifrac
***************************
| Generalized unifrac is passed alpha=1 by default. This is roughly equivalent to weighted normalized unifrac, which method will be used instead, because it is better optimized.
Using the ``qiime2 diversity-lib beta-phylogenetic-passthrough`` tool:
 #. Set *"table"* to ``#: feature-table.qza``
 #. Set *"phylogeny"* to ``#: phylogeny.qza``
 #. Set *"metric"* to ``generalized_unifrac``
 #. 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 diversity-lib beta-phylogenetic-passthrough [...] : distance_matrix.qza``
      - ``generalized-unifrac-dm.qza``

generalized unifrac
*******************
| passing a float between 0 and 1 to 'alpha' gives you control over the importance of sample proportions.
Using the ``qiime2 diversity-lib beta-phylogenetic-passthrough`` tool:
 #. Set *"table"* to ``#: feature-table.qza``
 #. Set *"phylogeny"* to ``#: phylogeny.qza``
 #. Set *"metric"* to ``generalized_unifrac``
 #. Expand the ``additional options`` section

    - Set *"alpha"* to ``0.75``

 #. 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 diversity-lib beta-phylogenetic-passthrough [...] : distance_matrix.qza``
      - ``generalized-unifrac-dm.qza``


|  

</help>
    <citations>
        <citation type="doi">10.1128/AEM.71.12.8228-8235.2005</citation>
        <citation type="doi">10.1128/AEM.01996-06</citation>
        <citation type="doi">10.1038/ismej.2009.97</citation>
        <citation type="doi">10.1038/ismej.2010.133</citation>
        <citation type="doi">10.1038/s41592-018-0187-8</citation>
        <citation type="doi">10.1186/1471-2105-12-118</citation>
        <citation type="doi">10.1093/bioinformatics/bts342</citation>
        <citation type="bibtex">@article{cite8,
 author = {Sfiligoi, Igor and Armstrong, George and Gonzalez, Antonio and McDonald, Daniel and Knight, Rob},
 journal = {mSystems},
 title = {Optimizing UniFrac with OpenACC yields &gt;1000x speed increase},
 year = {in press}
}
</citation>
        <citation type="doi">10.1038/s41587-019-0209-9</citation>
    </citations>
</tool>