<tool id="ampvis2_octave" name="ampvis2 octave plot" 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[
            library(ampvis2, quietly = TRUE)
            d <- readRDS("$data")
            plot <- amp_octave(
                d,
                tax_aggregate = "$tax_aggregate",
                #if $group_by
                    group_by = "$group_by",
                    #if $scales
                        scales = "$scales",
                    #end if
                #end if
                num_threads = 1
            )
            @OUTPUT_TOKEN@
        ]]></configfile>
    </configfiles>
    <inputs>
        <expand macro="rds_metadata_input_macro"/>
        <expand macro="taxlevel_macro" argument="tax_aggregate" label="Aggregate (sum) OTU's to a taxonomic level initially." help="OTU's that have not been assigned at the chosen level will be removed with a message.">
            <option value="OTU" selected="true">OTU/ASV</option>
        </expand>
        <expand macro="metadata_select" argument="group_by" label="Group the samples based on a metadata variable." help="Variable needs to be categorical/discrete"/>
        <expand macro="facet_scales_macro" argument="scales" help="Only relevant if for group_by a value is selected"/>
        <expand macro="out_format_macro"/>
    </inputs>
    <outputs>
        <expand macro="out_macro"/>
    </outputs>
    <tests>
        <test>
            <param name="data" value="AalborgWWTPs.rds" ftype="ampvis2"/> 
            <output name="plot" value="AalborgWWTPs-octave.pdf" ftype="pdf"/>
        </test>
        <test>
            <param name="data" value="AalborgWWTPs.rds" ftype="ampvis2"/> 
            <param name="tax_aggregate" value="Class"/> 
            <param name="out_format" value="png"/> 
            <output name="plot" value="AalborgWWTPs-octave.png" ftype="png"/>
        </test>
        <test>
            <param name="data" value="AalborgWWTPs.rds" ftype="ampvis2"/> 
            <param name="metadata_list" value="AalborgWWTPs-metadata.list"/> 
            <param name="group_by" value="Year"/> 
            <param name="scales" value="free"/> 
            <param name="out_format" value="svg"/> 
            <output name="plot" value="AalborgWWTPs-octave.svg" ftype="svg"/>
        </test>
    </tests>
    <help><![CDATA[
What it does
============

Generates an octave plot to assess alpha diversity. An octave plot is a
histogram of the number of taxa observed by bins of read counts, where the bin
ranges increase exponentially, see details.

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


Details
=======

The n-th bin in the histogram has the range ``r(n)=2n...2n+1-1``. The height of the
bars then reflect the number of unique taxa with read counts in each bin. By
judging the distribution one can assess whether the samples have been sequenced
deeply enough at the chosen taxonomic level. A full symmetrical bell-shaped
distribution with the left part far from the y-axis is the ideal. A high amount
of OTU's with a low amount of reads indicates noise, chimeras, and even cross
talk.

Aggregating OTU's using ``tax_aggregate`` is useful to assess whether the samples
have been sequenced deep enough to capture the full diversity at the given
level, but ONLY applies to OTU's that have assigned taxonomy at the given level.

It is recommended to look at samples individually as grouping samples will
almost always look ideal. It is better to identify "bad" samples individually
and remove them.

Input
=====

@HELP_RDS_INPUT@

@HELP_METADATA_LIST_INPUT@

Output
======

Octave plot in the chosen output format.

    ]]></help>
    <expand macro="citations"/>
</tool>