annotate macros.xml @ 3:ceda8519e440 draft

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

<macros>
    <token name="@TOOL_VERSION@">2.8.6</token>
    <token name="@VERSION_SUFFIX@">0</token>
    <token name="@PROFILE@">22.01</token>
    <xml name="header">
        <xrefs>
            <xref type="bio.tools">ampvis</xref>
        </xrefs>
        <requirements>
            <requirement type="package" version="@TOOL_VERSION@">r-ampvis2</requirement>
            <requirement type="package" version="2.1.5">r-readr</requirement>
            <requirement type="package" version="1.46.0">bioconductor-phyloseq</requirement>
        </requirements>
        <version_command><![CDATA[
echo $(R --version | grep "R version")", ampvis2 version" $(R --vanilla --slave -e "library(ampvis2, quietly = TRUE); sessionInfo()\$otherPkgs\$ampvis2\$Version" 2> /dev/null | grep -v -i "WARNING: ")
        ]]></version_command>

    </xml>
    <xml name="citations">
        <citations>
            <citation type="doi">10.1101/299537</citation>
            <yield/>
        </citations>
    </xml>

    <xml name="rds_input_macro" token_multiple="false">
        <param argument="data" type="data" format="ampvis2" multiple="@MULTIPLE@" label="Ampvis2 RDS dataset" help="Generated with ampvis2: load"/>
    </xml>
    
    <xml name="rds_metadata_input_macro" token_metadata_optional="true">
        <expand macro="rds_input_macro"/>
        <param name="metadata_list" type="data" optional="@METADATA_OPTIONAL@" format="tabular" label="Metadata list">
            <validator type="expression" message="The metadatalist file must have 3 columns"><![CDATA[value.metadata.columns == 4]]></validator>
        </param>
    </xml>

    <token name="@SAVE_TAX_LIST@"><![CDATA[
                for(level in colnames(data\$tax)){
                    for(u in unique(data\$tax[level])){
                        write(paste(u, level, sep="\t"), file="$taxonomy_list_out", append=T)
                    }
                }
    ]]></token>

    <token name="@SAVE_METADATA_LIST@"><![CDATA[
                classes <- sapply(data\$metadata, class)
                for(name in names(data\$metadata)){
                    ## check if it is the column containing the sample names
                    ## the additional column in the ist file can the be used
                    ## to filter SampleIDs from select inputs
                    ## (check for character columns only .. since data in the column is otherwise converted to the corresponding type .. which fails)
                    if(classes[[name]] == "character" && all(data\$metadata[[name]] == rownames(data\$metadata))){
                        sample_names <- TRUE;
                    }else{
                        sample_names <- FALSE;
                    }
                    for(m in unique(data\$metadata[[name]])){
                        write(paste(name, m, sample_names, classes[[name]], sep="\t"), file="$metadata_list_out", append=T);
                    }
                }
    ]]></token>

    <!-- defaults can be set by redefining an on option with selected="true" -->
    <xml name="taxlevel_macro" token_argument="" token_multiple="false" token_optional="false" token_label="" token_help="">
        <param argument="@ARGUMENT@" type="select" optional="@OPTIONAL@" multiple="@MULTIPLE@" label="@LABEL@" help="@HELP@">
            <option value="OTU">OTU/ASV</option>
            <option value="Species">Species</option>
            <option value="Genus">Genus</option>
            <option value="Family">Family</option>
            <option value="Order">Order</option>
            <option value="Class">Class</option>
            <option value="Phylum">Phylum</option>
            <option value="Kingdom">Kingdom</option>
            <yield/>
        </param>
    </xml>

    <xml name="tax_empty_macro">
        <param argument="tax_empty" type="select" label="How to show OTUs without taxonomic information">
            <option value="remove">Remove OTUs without taxonomic information</option>
            <option value="best" selected="true">Use the best classification possible</option>
            <option value="OTU">Display the OTU name</option>
        </param>
    </xml>

    <token name="@TAX_SHOW@"><![CDATA[
                #if $tax_show_cond.tax_show_sel == "number"
                    tax_show = $tax_show_cond.tax_show,
                #else
                    #set tax_show_list='c("' + '", "'.join(str($tax_show_cond.tax_show).split(",")) + '")'
                    tax_show = $tax_show_list
                #end if
    ]]></token> 
    <xml name="tax_show_macro" token_value="">
        <conditional name="tax_show_cond">
            <param name="tax_show_sel" type="select" label="Limit the number of shown taxa">
                <option value="number">Select a number of taxa to show</option>
                <option value="explicit">Manually select taxa to show</option>
            </param>
            <when value="number">
                <param argument="tax_show" type="integer" value="@VALUE@" min="1" label="Number of taxa to show"/>
            </when>
            <when value="explicit">
                <param name="taxonomy_list" format="tabular" type="data" optional="false" label="Taxonomy list" help="Generated with ampvis2: load"/>
                <param argument="tax_show" type="select" multiple="true" optional="false" label="Taxa to show">
                    <options from_dataset="taxonomy_list">
                        <column name="name" index="0"/>
                        <column name="value" index="0"/>
                        <!-- TODO filter by tax_aggregate level? -->
                    </options>
                </param>
            </when>
        </conditional>
    </xml>

    <xml name="metadata_select" token_quote="__" tokens="argument,label" token_an="argument" token_optional="true" token_multiple="false" token_help="">
        <param __AN__="__ARGUMENT__" type="select" optional="__OPTIONAL__" multiple="__MULTIPLE__" label="__LABEL__" help="In order to select values a metadata list needs to be selected first. __HELP__">
            <options from_dataset="metadata_list">
                <column name="name" index="0"/>
                <column name="value" index="0"/>
                <filter type="unique_value" column="0"/>
                <yield name="options"/>
            </options>
            <yield/>
        </param>
    </xml>

    <xml name="metadata_select_discrete" tokens="argument,label" token_optional="true" token_multiple="false" token_help="">
        <expand macro="metadata_select" argument="@ARGUMENT@" optional="@OPTIONAL@" multiple="@MULTIPLE@" label="@LABEL@" help="@HELP@">
            <token name="options">
                <filter type="static_value" column="3" value="numeric" keep="false"/>
            </token>
            <yield/>
        </expand>
    </xml>

    <xml name="metadata_select_numeric" tokens="argument,label" token_optional="true" token_multiple="false" token_help="">
        <expand macro="metadata_select" argument="@ARGUMENT@" optional="@OPTIONAL@" multiple="@MULTIPLE@" label="@LABEL@" help="@HELP@">
            <token name="options">
                <filter type="static_value" column="3" value="character" keep="false"/>
                <filter type="static_value" column="3" value="Date" keep="false"/>
            </token>
            <yield/>
        </expand>
    </xml>

    <xml name="metadata_select_date" tokens="argument,label" token_optional="true" token_multiple="false" token_help="">
        <expand macro="metadata_select" argument="@ARGUMENT@" optional="@OPTIONAL@" multiple="@MULTIPLE@" label="@LABEL@" help="@HELP@">
            <token name="options">
                <filter type="static_value" column="3" value="Date" keep="true"/>
            </token>
            <yield/>
        </expand>
    </xml>

    <!-- metadata_sample_or_variable_select is currently unused (heatmap is documented to allow normalize by
         sample or variable, but only sample seems possible https://github.com/KasperSkytte/ampvis2/issues/168
         leaving it for now in case it can be fixed .. then metadata_sample_select could be removed) -->
    <xml name="metadata_sample_select" token_argument="">
        <param argument="@ARGUMENT@" type="select" optional="true">
            <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>
    </xml>
    <xml name="metadata_sample_or_variable_select" token_argument="">
        <conditional name="@ARGUMENT@_cond">
            <param name="@ARGUMENT@_sel" type="select">
                <option value="no">No</option>
                <option value="variable">Metadata variable</option>
                <option value="sample">Specific sample</option>
            </param>
            <when value="no"/>
            <when value="variable">
                <expand macro="metadata_select" argument="@ARGUMENT@" label="Metadata variable"/>
            </when>
            <when value="sample">
                <expand macro="metadata_sample_select"/>
            </when>
        </conditional>
    </xml>

    <xml name="taxonomy_select_macro" token_argument="" token_optional="false" token_multiple="true">
        <param argument="@ARGUMENT@" type="select" optional="@OPTIONAL@" multiple="@MULTIPLE@">
            <options from_dataset="taxonomy_list">
                <column name="name" index="0"/>
                <column name="value" index="0"/>
                <filter type="unique_value" column="0"/>
            </options>
            <yield/>
        </param>
    </xml>

    <xml name="facet_scales_macro" token_argument="" token_label="Scales of the facets" token_help="">
        <param argument="@ARGUMENT@" type="select" optional="true" label="@LABEL@" help="@HELP@">
            <option value="fixed">Same scale</option>
            <option value="free">Free scale</option>
            <option value="free_x">Free x-scale</option>
            <option value="free_y">Free y-scale</option>
        </param>
    </xml>

    <token name="@OUTPUT_TOKEN@">
            ggsave("$plot", 
                print(plot),
                device="$output_options.out_format"
                #if str($output_options.plot_width) != ''
                    , width = $output_options.plot_width
                #end if
                #if str($output_options.plot_height) != ''
                    , height = $output_options.plot_height
                #end if
                )
    </token>
    <xml name="out_macro" token_name="plot" token_label="">
        <data name="@NAME@" format="pdf" label="${tool.name} on ${on_string}@LABEL@">
            <yield/>
            <change_format>
                <when input="output_options.out_format" value="png" format="png" />
                <when input="output_options.out_format" value="svg" format="svg" />
            </change_format>
        </data>
    </xml>
    <xml name="out_format_macro">
        <section name="output_options" title="Output options" expanded="false">
            <param name="out_format" type="select" label="Output format">
                <option value="pdf" selected="true">PDF</option>
                <option value="png">PNG</option>
                <option value="svg">SVG</option>
                <yield/>
            </param>
            <param name="plot_width" type="float" value="" min="1" optional="true" label="Plot width in cm"/>
            <param name="plot_height" type="float" value="" min="1" optional="true" label="Plot height in cm"/>
        </section>
    </xml>

    <token name="@RAREFY_TOKEN@">
            #if str($rarefy) != ""
                , rarefy = $rarefy
            #end if
    </token>
    <xml name="rarefy_macro" token_help="">
        <param argument="rarefy" type="integer" optional="true" value="" min="0" label="Rarefy species richness to this value" help="@HELP@"/>
    </xml>

    <xml name="normalise_macro" token_checked="false">
        <param argument="normalise" type="boolean" truevalue="TRUE" falsevalue="FALSE" checked="@CHECKED@" label="Normalise read counts" help="Transform the OTU read counts to be in percent per sample."/>
    </xml>

    <token name="@HELP_RDS_INPUT@">
        An ampvis2 RDS dataset obtained by the ``ampvis2: load`` tool (or ``ampvis2: mergereplicates`` or one of the
        ``ampvis2: subset ...`` tools).
    </token>
    <token name="@HELP_METADATA_LIST_INPUT@">
        The metadata list output of the ``ampvis2: load`` tool (or ``ampvis2: mergereplicates`` or the
        ``ampvis2: subset sample`` tool).  This input is only used for providing
        values to the parameters alowing to select metadata variables or values.
    </token>

    <token name="@HELP_RELATIVE_ABUNDANCES@">
Preserving relative abundances in a subset of larger data
=========================================================

By default the raw read counts in the abundance matrix are normalised
(transformed to percentages) by some ampvis2 plotting tools (for
example ``ampvis2: heatmap``, ``ampvis2: timeseries``, and more). 
If this is applied to data generated by one of the ``ampvis2: subset ...`` tools
this means that the relative
abundances shown will be calculated based on the remaining taxa after the
subset, not including the removed taxa, if any. To circumvent this, enable
``normalise`` when subsetting with the ``ampvis2: subset ...``` tools,
and then disable ``normalise`` in the plotting tool. This will
transform the OTU counts to relative abundances BEFORE the subset.
    </token>
</macros>