annotate heatmap.xml @ 4:14695ae019be draft default tip

planemo upload for repository https://github.com/galaxyproject/tools-iuc/tree/master/tools/ampvis2 commit ab75ba7665d7fb5c18ad08dfbba92b273f991dfc

<tool id="ampvis2_heatmap" name="ampvis2 heatmap" version="@TOOL_VERSION@+galaxy@VERSION_SUFFIX@" profile="@PROFILE@" license="MIT">
    <description></description>
    <macros>
        <import>macros.xml</import>
    </macros>
    <expand macro="header"/>
    <command detect_errors="exit_code"><![CDATA[
        Rscript '$rscript'
    ]]></command>
    <configfiles>
        <configfile name="rscript"><![CDATA[
            #if $tax_add
                #set ta='c("' + '", "'.join(str($tax_add).split(",")) + '")'
            #else
                #set ta='NULL'
            #end if
            library(ampvis2, quietly = TRUE)
            d <- readRDS("$data")
            #if $output_options.out_format == "tabular"
                raw <-
            #else
                plot <-
            #end if
            amp_heatmap(
                d
                ,
                #if $group_by
                    group_by = "$group_by",
                #end if
                #if $facet_by
                    facet_by = "$facet_by",
                #end if
                normalise = $normalise,
                tax_aggregate = "$tax_aggregate",
                tax_add = $ta,
                @TAX_SHOW@
                showRemainingTaxa = $showRemainingTaxa,
                ## tax_class = NULL,
                tax_empty = "$tax_empty",
                ## TODO giving the order of the columns is difficult but "cluster" would be nice I guess
                ## order_x_by = NULL,
                ## order_y_by = NULL,
                plot_values = $plot_values_cond.plot_values,
                #if $plot_values_cond.plot_values == "TRUE"
                    plot_values_size = $plot_values_cond.plot_values_size,
                #end if
                ## plot_legendbreaks = NULL,
                plot_colorscale = "$plot_colorscale",
                plot_na = $plot_na,
                measure = "$measure",
                #if str($min_abundance) != ''
                    min_abundance = $min_abundance,
                #end if
                #if str($max_abundance) != ''
                    max_abundance = $max_abundance,
                #end if
                #if $sort_by_cond.sort_by_sel != 'no'
                    sort_by = "$sort_by_cond.sort_by",
                #end if
                #if $normalise_by
                    normalise_by = "$normalise_by",
                #end if
                #if $scale_by
                    scale_by = "$scale_by",
                #end if
                ## color_vector = NULL
                ## round = 1,
                #if $output_options.out_format == "tabular"
                    textmap = TRUE,
                #else
                    textmap = FALSE,
                #end if
                #if $plot_functions_cond.plot_functions_sel != "no"
                    plot_functions = TRUE,
                    #if $plot_functions_cond.plot_functions_sel == "file"
                        function_data = read.table("$plot_functions_cond.function_data", header = TRUE, sep = "\t"),
                    #end if
                    #set foo='c("' + '", "'.join(str($plot_functions_cond.functions).split(",")) + '")'
                    functions = $foo,
                #end if
                rel_widths = c(0.75, 0.25) 
            )
            #if $output_options.out_format != "tabular"
                @OUTPUT_TOKEN@
            #else
                write.table(raw, file = "$plot_raw", sep = "\t") 
            #end if
        ]]></configfile>
    </configfiles>
    <inputs>
        <expand macro="rds_metadata_input_macro"/>
        <expand macro="metadata_select_discrete" argument="group_by" label="Group samples" help="By a categorical variable in the metadata"/>
        <expand macro="metadata_select_discrete" argument="facet_by" label="Facet the samples" help="By a categorical variable in the metadata."/>
        <expand macro="normalise_macro" checked="true"/>
        <expand macro="taxlevel_macro" argument="tax_aggregate" label="The taxonomic level to aggregate the OTUs">
            <option value="Phylum" selected="true">Phylum</option>
        </expand>
        <expand macro="taxlevel_macro" argument="tax_add" multiple="true" optional="true" label="Additional taxonomic level(s) to display"/>
        <expand macro="tax_show_macro" value="10"/>
        <param argument="showRemainingTaxa" type="boolean" truevalue="TRUE" falsevalue="FALSE" label="Display sum of remaining taxa" help="Add an additional row at the bottom displaying the sum of all remaining taxa that are not part of the top tax_show most abundant taxa."/>
        <expand macro="tax_empty_macro"/>
        <conditional name="plot_values_cond">
            <param argument="plot_values" type="select" label="Plot the values on the heatmap">
                <option value="TRUE">Yes</option>
                <option value="FALSE">No</option>
            </param>
            <when value="TRUE">
                <param name="plot_values_size" type="integer" value="4" label="Size of the plotted values"/>
            </when>
            <when value="FALSE"/>
        </conditional>
        <param argument="plot_colorscale" type="select" label="Type of scale used for coloring abundances">
            <option value="sqrt">Square root (sqrt)</option>
            <option value="log10" selected="true">Log (log10)</option>
        </param>
        <param argument="plot_na" type="boolean" truevalue="TRUE" falsevalue="FALSE" label="Color missing values with the lowest color in the scale"/>
        <param argument="measure" type="select" label="Value to show across the groups">
            <option value="mean">Mean</option>
            <option value="max">Maximum</option>
            <option value="median">Median</option>
        </param>
        <param argument="min_abundance" type="float" value="0.1" min="0" optional="true" label="Maximum abundance" help="All values below this value are given the same color."/>
        <param argument="max_abundance" type="float" value="" min="0" optional="true" label="Maximum abundance" help="All values above this value are given the same color." />

        <conditional name="sort_by_cond">
            <param name="sort_by_sel" type="select" label="Sort heatmap by most abundant taxa">
                <option value="no">No</option>
                <option value="group">in a group of samples</option>
                <option value="sample">in a specific sample</option>
            </param>
            <when value="no"/>
            <when value="group">
                <param argument="sort_by" type="select" optional="true" label="Group to sort by">
                    <options from_dataset="metadata_list">
                        <column name="name" index="1"/>
                        <column name="value" index="1"/>
                        <filter type="param_value" column="0" ref="group_by"/>
                        <filter type="unique_value" column="1"/>
                    </options>
                </param>
            </when>
            <when value="sample">
                <param argument="sort_by" type="select" optional="true" label="Sample to sort by">
                    <options from_dataset="metadata_list">
                        <column name="name" index="1"/>
                        <column name="value" index="1"/>
                        <filter type="static_value" value="TRUE" column="2"/> <!-- filter samples -->
                        <filter type="unique_value" column="1"/>
                    </options>
                </param>
            </when>
        </conditional>
        <!-- https://github.com/KasperSkytte/ampvis2/issues/168 
            if this is possible again reuse: metadata_sample_or_variable_select ? -->
        <expand macro="metadata_sample_select" argument="normalise_by" label="Normalize counts by a variable or a specific sample"/>
        <expand macro="metadata_select_discrete" argument="scale_by" label="Scale the abundances by a variable in the metadata"/>

        <conditional name="plot_functions_cond">
            <param name="plot_functions_sel" type="select" label="Show functional information about the Genus-level OTUs" help="Produces a 2-column grid plot, showing known functional information about the Genus-level OTUs next to the heatmap. When using this feature, make sure that either tax_aggregate or tax_add is set to Genus and that Genus is the lowest level in either.">
                <option value="no">No</option>
                <option value="midasfieldguide">Use data from midasfieldguide.org</option>
                <option value="file">Use data from a dataset in the history</option>
            </param>
            <when value="no"/>
            <when value="file">
                <!-- neeed tsv here since tabular does not fill the column_names
                     metadata and therefore the data_meta filter in the functions
                     select would not work-->
                <param argument="function_data" type="data" format="tsv" label="Tabular dataset with functional information at Genus level" help="See help"/>
                <param argument="functions" type="select" multiple="true" label="Function(s) to include">
                    <options>
                        <filter type="data_meta" ref="function_data" key="column_names"/>
                        <filter type="remove_value" value="Genus"/>
                    </options>
                </param>
            </when>
            <when value="midasfieldguide">
                <param name="functions" type="select" multiple="true" label="Function(s) to include">
                    <option value="MiDAS" selected="true">MiDAS</option>
                    <option value="Filamentous" selected="true">Filamentous</option>
                    <option value="AOB" selected="true">AOB</option>
                    <option value="NOB" selected="true">PAO</option>
                    <option value="GAO" selected="true">GAO</option>
                </param>
            </when>
        </conditional>
        <expand macro="out_format_macro">
            <option value="tabular">Table</option>
        </expand>
    </inputs>
    <outputs>
        <expand macro="out_macro">
            <filter>output_options["out_format"] != "tabular"</filter>
        </expand>
        <data name="plot_raw" format="tabular" label="${tool.name} on ${on_string}: Table">
            <filter>output_options["out_format"] == "tabular"</filter>
        </data>
    </outputs>
    <tests>
        <!-- defaults -->
        <test expect_num_outputs="1">
            <param name="data" value="AalborgWWTPs.rds" ftype="ampvis2"/> 
            <output name="plot" value="AalborgWWTPs-heatmap.pdf" ftype="pdf" compare="sim_size"/>
        </test>
        <!-- group and facet-->
        <test expect_num_outputs="1">
            <param name="data" value="AalborgWWTPs.rds" ftype="ampvis2"/> 
            <param name="metadata_list" value="AalborgWWTPs-metadata.list"/> 
            <param name="group_by" value="Plant"/>
            <param name="facet_by" value="Year"/>
            <output name="plot_raw" value="AalborgWWTPs-heatmap-group-facet.pdf" ftype="pdf" compare="sim_size"/>
        </test>
        <!-- group and facet and test raw output -->
        <test expect_num_outputs="1">
            <param name="data" value="AalborgWWTPs.rds" ftype="ampvis2"/> 
            <param name="metadata_list" value="AalborgWWTPs-metadata.list"/> 
            <param name="group_by" value="Plant"/>
            <param name="facet_by" value="Year"/>
            <param name="out_format" value="tabular"/>
            <output name="plot_raw" value="AalborgWWTPs-heatmap-group-facet.tsv" ftype="tabular"/>
        </test>
        <!-- normalise -->
        <test expect_num_outputs="1">
            <param name="data" value="AalborgWWTPs.rds" ftype="ampvis2"/> 
            <param name="normalise" value="true"/>
            <output name="plot" value="AalborgWWTPs-heatmap-normalise.pdf" ftype="pdf" compare="sim_size"/>
        </test>
        <!-- normalise by a specific sample -->
        <test expect_num_outputs="1">
            <param name="data" value="AalborgWWTPs.rds" ftype="ampvis2"/> 
            <param name="metadata_list" value="AalborgWWTPs-metadata.list"/> 
            <param name="normalise" value="true"/>
            <param name="normalise_by" value="16SAMP-747"/>
            <output name="plot" value="AalborgWWTPs-heatmap-normalise_by_sample.pdf" ftype="pdf" compare="sim_size"/>
        </test>
        <!-- normalise by a metadata variable
            https://github.com/KasperSkytte/ampvis2/issues/168 -->
        <!-- <test expect_num_outputs="1">
            <param name="data" value="AalborgWWTPs.rds" ftype="ampvis2"/> 
            <param name="metadata_list" value="AalborgWWTPs-metadata.list"/> 
            <param name="group_by" value="Plant"/>
            <conditional name="normalise_by_cond">
                <param name="normalise_by_sel" value="variable"/>
                <param name="normalise_by" value="Plant"/>
            </conditional>
            <output name="plot" value="AalborgWWTPs-heatmap-normalise_by_variable.pdf" ftype="pdf"/>
        </test> -->
        <!-- tax options -->
        <test expect_num_outputs="1">
            <param name="data" value="AalborgWWTPs.rds" ftype="ampvis2"/> 
            <param name="tax_aggregate" value="Order"/>
            <param name="tax_add" value="Class"/>
            <param name="tax_show" value="5"/>
            <param name="showRemainingTaxa" value="true"/>
            <output name="plot" value="AalborgWWTPs-heatmap-tax.pdf" ftype="pdf" compare="sim_size"/>
        </test>
        <!-- sort by a specific sample -->
        <test expect_num_outputs="1">
            <param name="data" value="AalborgWWTPs.rds" ftype="ampvis2"/> 
            <param name="metadata_list" value="AalborgWWTPs-metadata.list"/> 
            <conditional name="sort_by_cond">
                <param name="sort_by_sel" value="sample"/>
                <param name="sort_by" value="16SAMP-747"/>
            </conditional>
            <output name="plot" value="AalborgWWTPs-heatmap-sort_by_sample.pdf" ftype="pdf" compare="sim_size"/>
        </test>
        <!-- sort by a group of samples -->
        <test expect_num_outputs="1">
            <param name="data" value="AalborgWWTPs.rds" ftype="ampvis2"/> 
            <param name="metadata_list" value="AalborgWWTPs-metadata.list"/> 
            <param name="group_by" value="Period"/>
            <conditional name="sort_by_cond">
                <param name="sort_by_sel" value="group"/>
                <param name="sort_by" value="Winter"/>
            </conditional>
            <output name="plot" value="AalborgWWTPs-heatmap-sort_by_group.pdf" ftype="pdf" compare="sim_size"/>
        </test>
        <test expect_num_outputs="1">
            <param name="data" value="AalborgWWTPs.rds" ftype="ampvis2"/> 
            <param name="tax_aggregate" value="Genus"/>
            <conditional name="plot_functions_cond">
                <param name="plot_functions_sel" value="midasfieldguide"/>
                <param name="functions" value="MiDAS,Filamentous,AOB,NOB,GAO"/>
            </conditional>
            <output name="plot" value="AalborgWWTPs-heatmap-plot_foo_midas.pdf" ftype="pdf" compare="sim_size"/>
        </test>
        <test expect_num_outputs="1">
            <param name="data" value="AalborgWWTPs.rds" ftype="ampvis2"/> 
            <param name="tax_aggregate" value="Genus"/>
            <conditional name="plot_functions_cond">
                <param name="plot_functions_sel" value="file"/>
                <param name="function_data" value="AalborgWWTPs-functions.tsv" ftype="tsv"/>
                <param name="functions" value="Foo,Bar"/>
            </conditional>
            <output name="plot" value="AalborgWWTPs-heatmap-plot_foo_file.pdf" ftype="pdf" compare="sim_size"/>
        </test>
    
    </tests>
    <help><![CDATA[
What it does
============

Generates a heatmap of amplicon data by using sample metadata to aggregate
samples and taxonomy to aggregate OTUs.

The Galaxy tool calls the `amp_heatmap
<https://kasperskytte.github.io/ampvis2/reference/amp_heatmap.html>`_ function
of the ampvis2 package. 

@HELP_RELATIVE_ABUNDANCES@

Input
=====

@HELP_RDS_INPUT@

@HELP_METADATA_LIST_INPUT@

Funtional data at genus level can be added to the plot. By default the
information is taken from `midasfieldguide <https://midasfieldguide.org/>`_ but
it can also be given by a dataset (parameter function_data): 

- The first column must be the Genus names and 
- any other column(s) can be any property or metabolic function of the individual Genera. 

Output
======

Heatmap in the chosen output format. 
If table output is chosen the data presented in the heatmap is written into a tabular dataset.
    ]]></help>
    <expand macro="citations"/>
</tool>