Warning

This document is for an old release of Galaxy. You can alternatively view this page in the latest release if it exists or view the top of the latest release's documentation.

Galaxy Tool XML File

The XML File for a Galaxy tool, generally referred to as the “tool config file” or “wrapper”, serves a number of purposes. First, it lays out the user interface for the tool (e.g. form fields, text, help, etc.). Second, it provides the glue that links your tool to Galaxy by telling Galaxy how to invoke it, what options to pass, and what files it will produce as output.

If you find a bug please report it here.

This document serves as reference documentation. If you would like to learn how to build tools for Galaxy, Planemo features a number of tutorials on building Galaxy tools that would better serve that purpose.

Table of contents

tool

The outer-most tag set of tool XML files. Attributes on this tag apply to the tool as a whole.

Examples

A normal tool:

<tool id="seqtk_seq"
      name="Convert FASTQ to FASTA"
      version="1.0.0"
      profile="16.04"
>

A data_source tool contains a few more relevant attributes.

<tool id="ucsc_table_direct1"
      name="UCSC Main"
      version="1.0.0"
      hidden="false"
      profile="16.01"
      tool_type="data_source"
      URL_method="post">

Best Practices

Find the Intergalactic Utilities Commision suggested best practices for this element here.

Attributes

Attr ibut e Deta ils Requ ired
``id `` Must be uniq ue acro ss all tool s; shou ld be lowe rcas e and cont ain only lett ers, numb ers, and unde rsco res. It allo ws for tool vers ioni ng and metr ics of the numb er of time s a tool is used , amon g othe r thin gs. Find the Inte rgal acti c Util itie s Comm isio n sugg este d best prac tice s for this elem ent `her e <h ttps ://p lane mo.r eadt hedo cs.i o/en /lat est/ stan dard s/do cs/b est_ prac tice s/to ol_x ml.h tml# tool -ids >`__ . True
na me This stri ng is what is disp laye d as a hype rlin k in the tool menu . Find the Inte rgal acti c Util itie s Comm isio n sugg este d best prac tice s for this elem ent her e <h ttps ://p lane mo.r eadt hedo cs.i o/en /lat est/ stan dard s/do cs/b est_ prac tice s/to ol_x ml.h tml# tool -nam es> __. True
ve rsio n This stri ng defa ults to ``1. 0.0` ` if it is not incl uded in the tag. It allo ws for tool vers ioni ng and shou ld be incr ease d with each new vers ion of the tool . Find the Inte rgal acti c Util itie s Comm isio n sugg este d best prac tice s for this elem ent her e _. Fals e
``hi dden `` Allo ws for tool s to be load ed upon serv er star tup, but not disp laye d in the tool menu . This attr ibut e shou ld be appl ied in the tool box conf igur atio n inst ead and so shou ld be cons ider ed depr ecat ed. Fals e
``di spla y_in terf ace` ` Disa ble the disp lay the tool ‘s grap hica l tool form by sett ing this to ``fa lse` `. Fals e
``to ol_t ype` ` Allo ws for cert ain fram ewor k func tion alit y to be perf orme d on cert ain type s of tool s. Norm al tool s that exec ute typi cal comm and- line jobs do not need to spec ify this , spec ial kind s of tool s such as Dat a Sour ce < http s:// gala xypr ojec t.or g/ad min/ inte rnal s/da ta-s ourc es/> `__ and `Dat a Mana ger _ tool s shou ld set this to have valu es such as da ta_s ourc e or ma nage _dat a. Fals e
pr ofil e This stri ng spec ifie d the mini mum Gala xy vers ion that shou ld be requ ired to run this tool . Cert ain lega cy beha vior s such as usin g stan dard erro r cont ent to dete ct erro rs inst ead of exit code are disa bled auto mati call y if prof ile is set to any vers ion newe r than ``16 .01` , such as ``16 .04 `. Fals e
wo rkfl ow_c ompa tibl e This attr ibut e indi cate s if this tool is usab le with in a work flow (def ault s to tr ue for norm al tool s and ``fa lse` ` for data sour ces) . Fals e
``UR L_me thod `` Only used if to ol_t ype` ` attr ibut e valu e is ``da ta_s ourc e - this attr ibut e defi nes the HTTP requ est meth od to use when comm unic atin g with an exte rnal data sour ce appl icat ion (the defa ult is ge t) . Fals e

tool > description

The value is displayed in the tool menu immediately following the hyperlink for the tool (based on the name attribute of the <tool> tag set described above).

Example

<description>table browser</description>

Best Practices

Find the Intergalactic Utilities Commision suggested best practices for this element here.

tool > version_command

Specifies the command to be run in order to get the tool’s version string. The resulting value will be found in the “Info” field of the history dataset.

Unlike the command tag, with the exception of the string $__tool_directory__ this value is taken as a literal and so there is no need to escape values like $ and command inputs are not available for variable substitution.

Examples

A simple example for a TopHat tool definition might just be:

<version_command>tophat -version</version_command>

An example that leverages a Python script (e.g. count_reads.py) shipped with the tool might be:

<version_command>python $__tool_directory__/count_reads.py</version_command>

Examples are included in the test tools directory including:

Attributes

Attr ibut e Deta ils Requ ired
in terp rete r Dep reca ted : Pref ix the vers ion comm and with an inte rpre ter and the tool dire ctor y in orde r to exec ute a scri pt ship ped with the tool . It is bett er to just use <i nter pret er> $__t ool_ dire ctor y__/ <scr ipt_ name >. Fals e

tool > command

This tag specifies how Galaxy should invoke the tool’s executable, passing its required input parameter values (the command line specification links the parameters supplied in the form with the actual tool executable). Any word inside it starting with a dollar sign ($) will be treated as a variable whose values can be acquired from one of three sources: parameters, metadata, or output files. After the substitution of variables with their values, the content is interpreted with Cheetah and finally given to the interpreter specified in the corresponding attribute (if any).

Examples

The following uses a compiled executable (bedtools).

<command>bed12ToBed6 -i '$input' > '$output'</command>

A few things to note about even this simple example:

  • Input and output variables (boringly named input and output) are expanded into paths using the $ Cheetah directive.
  • Paths should be quoted so that the Galaxy database files may contain spaces.
  • We are building up a shell script - so special characters like > can be used (in this case the standard output of the bedtools call is written to the path specified by '$output').

The bed12ToBed6 tool can be found here.

A more sophisticated bedtools example demonstrates the use of loops, conditionals, and uses whitespace to make a complex command very readable can be found in annotateBed tool.

<command><![CDATA[
bedtools annotate
        -i "${inputA}"
        #if $names.names_select == 'yes':
            -files
            #for $bed in $names.beds:
                '${bed.input}'
            #end for
            -names
            #for $bed in $names.beds:
                '${bed.inputName}'
            #end for
        #else:
            #set files = '" "'.join( [ str( $file ) for $file in $names.beds ] )
            -files '${files}'
            #set names = '" "'.join( [ str( $name.display_name ) for $name in $names.beds ] )
            -names '${names}'
        #end if
        $strand
        $counts
        $both
        > "${output}"
]]></command>

The following example (taken from xpath tool) uses an interpreted executable. In this case a Perl script is shipped with the tool and the directory of the tool itself is referenced with $__tool_directory__.

<command>
  perl $__tool_directory__/xpath -q -e '$expression' '$input' > '$output'
</command>

The following example demonstrates accessing metadata from datasets. Metadata values (e.g., ${input.metadata.chromCol}) are acquired from the Metadata model associated with the objects selected as the values of each of the relative form field parameters in the tool form. Accessing this information is generally enabled using the following feature components.

A set of “metadata information” is defined for each supported data type (see the MetadataElement objects in the various data types classes in /lib/galaxy/datatypes. The DatasetFilenameWrapper class in the /lib/galaxy/tools/wrappers.py code file wraps a metadata collection to return metadata parameters wrapped according to the Metadata spec.

<command><![CDATA[
        #set genome = $input.metadata.dbkey
        #set datatype = $input.datatype
        mkdir -p output_dir &&
        python $__tool_directory__/extract_genomic_dna.py
        --input '$input'
        --genome '$genome'
        #if $input.is_of_type("gff"):
            --input_format "gff"
            --columns "1,4,5,7"
            --interpret_features $interpret_features
        #else:
            --input_format "interval"
            --columns "${input.metadata.chromCol},${input.metadata.startCol},${input.metadata.endCol},${input.metadata.strandCol},${input.metadata.nameCol}"
        #end if
        --reference_genome_source $reference_genome_cond.reference_genome_source
        #if str($reference_genome_cond.reference_genome_source) == "cached"
            --reference_genome $reference_genome_cond.reference_genome.fields.path
        #else:
            --reference_genome $reference_genome_cond.reference_genome
        #end if
        --output_format $output_format_cond.output_format
        #if str($output_format_cond.output_format) == "fasta":
            --fasta_header_type $output_format_cond.fasta_header_type_cond.fasta_header_type
            #if str($output_format_cond.fasta_header_type_cond.fasta_header_type) == "char_delimited":
                --fasta_header_delimiter $output_format_cond.fasta_header_type_cond.fasta_header_delimiter
            #end if
        #end if
        --output '$output'
]]></command>

In additon to demonstrating accessing metadata, this example demonstrates:

  • $input.is_of_type("gff") which can be used to check if an input is of a given datatype.
  • #set datatype = $input.datatype which is the syntax for defining variables in Cheetah.

Reserved Variables

Galaxy provides a few pre-defined variables which can be used in your command line, even though they don’t appear in your tool’s parameters.

Name Description
$__ tool_ direc tory_ _ The directory the tool description (XML file) currently resides in (new in 15.03)
``$__ new_f ile_p ath__ `` config/gal axy.ini’s new_file_p ath value
$__ tool_ data_ path_ _ config/gal axy.ini’s tool_data_ path value
``$__ root_ dir__ `` Top-level Galaxy source directory made absolute via os.path.ab spath()
$__ datat ypes_ confi g__ config/gal axy.ini’s datatypes_c onfig value
``$__ user_ id__` ` Email’s numeric ID (id column of galaxy_use r table in the database)
$__ user_ email __ User’s email address
``$__ app__ `` The galaxy.app .UniverseApp lication instance, gives access to all other configuratio n file variables (e.g. $app.c onfig.output _size_limi t). Should be used as a last resort, may go away in future releases.

Additional runtime properties are available as environment variables. Since these are not Cheetah variables (the values aren’t available until runtime) these should likely be escaped with a backslash (\) when appearing in command or configfile elements.

Name Description
\${ GALAX Y_SLO TS:-4 } Number of cores/thread s allocated by the job runner or resource manager to the tool for the given job (here 4 is the default number of threads to use if running via custom runner that does not configure GALAXY_SLOT S or in an older Galaxy runtime).

See the Planemo docs on the topic of GALAXY_SLOTS for more information and examples.

Attributes

detect_errors

If present on the command tag, this attribute can be one of:

  • default no-op fallback to stdio tags and erroring on standard error output (for legacy tools).
  • exit_code error if tool exit code is not 0. (The @jmchilton recommendation).
  • aggressive error if tool exit code is not 0 or either Exception: or Error: appears in standard error/output. (The @bgruening recommendation).

For newer tools with profile>=16.04, the default behavior is exit_code. Legacy tools default to default behavior described above (erroring if the tool produces any standard error output).

See pull request 117 for more implementation information and discussion on the detect_errors attribute.

strict

This boolean forces the #set -e directive on in shell scripts - so that in a multi-part command if any part fails the job exits with a non-zero exit code. This is enabled by default for tools with profile>=16.04 and disabled on legacy tools.

interpreter

Older tools may define an intepreter attribute on the command, but this is deprecated and using the $__tool_directory__ variable is superior.

Best Practices

Find the Intergalactic Utilities Commision suggested best practices for this element here.

tool > inputs

Consists of all tag sets that define the tool’s input parameters. Each <param> tag within the <inputs> tag set maps to a command line parameter within the command tag. Most tools will not need to specify any attributes on this tag itself.

Attributes

Attr ibut e Deta ils Requ ired
``ac tion `` URL used by data sour ce tool s. Fals e
ch eck_ valu es Set to ``fa lse` ` to disa ble para mete r chec king in data sour ce tool s. Fals e
``me thod `` Data sour ce HTTP acti on (e.g . ge t or pu t) to use. Fals e
``ta rget `` UI link targ et to use for data sour ce tool s (e.g . _t op ). Fals e
ng inx_ uplo ad This bool ean indi cate s if this is an uplo ad tool or not. Fals e

tool > inputs > section

This tag is used to group parameters into sections of the interface. Sections are implemented to replace the commonly used tactic of hiding advanced options behind a conditional, with sections you can easily visually group a related set of options.

Example

The XML configuration is relatively trivial for sections:

<inputs>
    <section name="adv" title="Advanced Options" expanded="False">
        <param name="plot_color" type="color" label="Track color" />
    </section>
</inputs>

In your command template, you’ll need to include the section name to access the variable:

--color $adv.plot_color

Further examples can be found in the test case from pull request #35.

Attributes

Attr ibut e Deta ils Requ ired
na me The inte rnal key used for the sect ion. True
``ti tle` ` Huma n read able labe l for the sect ion. True
ex pand ed Whet her the sect ion shou ld be expa nded by defa ult or not. If not, the defa ult set valu es are used . Fals e
he lp Shor t help desc ript ion for sect ion, rend ered just belo w the sect ion. Fals e

tool > inputs > repeat

See xy_plot.xml for an example of how to use this tag set. This is a container for any tag sets that can be contained within the <inputs> tag set. When this is used, the tool will allow the user to add any number of additional sets of the contained parameters (an option to add new iterations will be displayed on the tool form). All input parameters contained within the <repeat> tag can be retrieved by enumerating over $<name_of_repeat_tag_set> in the relevant Cheetah code. This returns the rank and the parameter objects of the repeat container. See the Cheetah code below.

Example

This part is contained in the <inputs> tag set.

<repeat name="series" title="Series">
    <param name="input" type="data" format="tabular" label="Dataset"/>
    <param name="xcol" type="data_column" data_ref="input" label="Column for x axis"/>
    <param name="ycol" type="data_column" data_ref="input" label="Column for y axis"/>
</repeat>

This Cheetah code can be used in the <command> tag set or the <configfile> tag set.

#for $i, $s in enumerate( $series )
    rank_of_series=$i
    input_path='${s.input}'
    x_colom=${s.xcol}
    y_colom=${s.ycol}
#end for

Testing

This is an example test case with multiple repeat elements for the example above.

<test>
    <repeat name="series">
        <param name="input" value="tabular1.tsv" ftype="tabular"/>
        <param name="xcol" value="1"/>
        <param name="ycol" value="2"/>
    </repeat>
    <repeat name="series">
        <param name="input" value="tabular2.tsv" ftype="tabular"/>
        <param name="xcol" value="4"/>
        <param name="ycol" value="2"/>
    </repeat>
    <output name="out_file1" file="cool.pdf" ftype="pdf" />
</test>

See the documentation on the repeat test directive.

An older way to specify repeats in a test is by instances that are created by referring to names with a special format: “_|”

<test>
    <param name="series_0|input" value="tabular1.tsv" ftype="tabular"/>
    <param name="series_0|xcol" value="1"/>
    <param name="series_0|ycol" value="2"/>
    <param name="series_1|input" value="tabular2.tsv" ftype="tabular"/>
    <param name="series_1|xcol" value="4"/>
    <param name="series_1|ycol" value="2"/>
    <output name="out_file1" file="cool.pdf" ftype="pdf" />
</test>

The test tool disambiguate_repeats.xml demonstrates both testing strategies.

Attributes

Attr ibut e Deta ils Requ ired
na me Name for this elem ent Fals e
``ti tle` ` The titl e of the repe at sect ion, whic h will be disp laye d on the tool form . True
mi n The mini mum numb er of repe at unit s. Fals e
ma x The maxi mum numb er of repe at unit s. Fals e
de faul t The defa ult numb er of repe at unit s. Fals e
he lp Shor t help desc ript ion for repe at elem ent. Fals e

tool > inputs > conditional

This is a container for conditional parameters in the tool (must contain ‘when’ tag sets) - the command line (or portions thereof) are then wrapped in an if-else statement. A good example tool that demonstrates many conditional parameters is biom_convert.xml.

<conditional name="input_type">
    <param name="input_type_selector" type="select" label="Choose the source BIOM format">
        <option value="tsv" selected="True">Tabular File</option>
        <option value="biom">BIOM File</option>
    </param>
    <when value="tsv">
        <param name="input_table" type="data" format="tabular" label="Tabular File" argument="--input-fp"/>
        <param name="process_obs_metadata" type="select" label="Process metadata associated with observations when converting" argument="--process-obs-metadata">
            <option value="" selected="True">Do Not process metadata</option>
            <option value="taxonomy">taxonomy</option>
            <option value="naive">naive</option>
            <option value="sc_separated">sc_separated</option>
        </param>
    </when>
    <when value="biom">
        <param name="input_table" type="data" format="biom1" label="Tabular File" argument="--input-fp"/>
    </when>
</conditional>

The first directive following the conditional is a param, this param must be of type select or boolean. Depending on the value a user selects for this “test” parameter - different UI elements will be shown. These different paths are described by the following the when blocks shown above.

The following Cheetah block demonstrates the use of the conditional shown above:

biom convert -i "${input_type.input_table}" -o "${output_table}"
#if str( $input_type.input_type_selector ) == "tsv":
    #if $input_type.process_obs_metadata:
        --process-obs-metadata "${input_type.process_obs_metadata}"
    #end if
#end if

Notice that the parameter input_table appears down both when clauses so ${input_type.input_table} appears unconditionally but we need to conditionally reference ${input_type.process_obs_metadata} with a Cheetah if statement.

A common use of the conditional wrapper is to select between reference data managed by the Galaxy admins (for instance via data managers ) and history files. A good example tool that demonstrates this is the Bowtie 2 wrapper.

<conditional name="reference_genome">
  <param name="source" type="select" label="Will you select a reference genome from your history or use a built-in index?" help="Built-ins were indexed using default options. See `Indexes` section of help below">
    <option value="indexed">Use a built-in genome index</option>
    <option value="history">Use a genome from the history and build index</option>
  </param>
  <when value="indexed">
    <param name="index" type="select" label="Select reference genome" help="If your genome of interest is not listed, contact the Galaxy team">
      <options from_data_table="bowtie2_indexes">
        <filter type="sort_by" column="2"/>
        <validator type="no_options" message="No indexes are available for the selected input dataset"/>
      </options>
    </param>
  </when>
  <when value="history">
    <param name="own_file" type="data" format="fasta" label="Select reference genome" />
  </when>
</conditional>

The Bowtie 2 wrapper also demonstrates other conditional paths - such as choosing between paired inputs of single stranded inputs.

Attributes

Attr ibut e Deta ils Requ ired
na me Name for this elem ent Fals e
``va lue_ from `` Infr eque ntly used opti on to dyna mica lly acce ss Gala xy inte rnal s, this shou ld be avoi ded. Gala xy meth od to exec ute. Fals e
``va lue_ ref` ` Infr eque ntly used opti on to dyna mica lly acce ss Gala xy inte rnal s, this shou ld be avoi ded. Refe renc ed para mete r to pass meth od. Fals e
``va lue_ ref_ in_g roup `` Infr eque ntly used opti on to dyna mica lly acce ss Gala xy inte rnal s, this shou ld be avoi ded. Is refe renc ed para mete r is the same grou p. Fals e
``la bel` ` Huma n read able desc ript ion for the cond itio nal, unus ed in the Gala xy UI curr entl y. Fals e

tool > inputs > conditional > when

This directive describes one potential set of input for the tool at this depth. See documentation for the conditional block for more details and examples (XML and corresponding Cheetah conditionals).

Attributes

Attr ibut e Deta ils Requ ired
``va lue` ` Valu e for the tool form test para mete r corr espo ndin g to this wh en bloc k. True

tool > inputs > param

Contained within the <inputs> tag set - each of these specifies a field that will be displayed on the tool form. Ultimately, the values of these form fields will be passed as the command line parameters to the tool’s executable.

Common Attributes

The attributes valid for this tag vary wildly based on the type of the parameter being described. All the attributes for the param element are documented below for completeness, but here are the common ones for each type are as follows:

Attributes

Attr ibut e Deta ils Requ ired
ty pe Desc ribe s the para mete r type - each diff eren t type as diff eren t sema ntic s and the tool form widg et is diff eren t. Curr entl y vali d para mete r type s are: te xt , in tege r, fl oat` `, ``bo olea n, ge nome buil d, se lect ``, ``co lor` `, ``da ta_c olum n, hi dden ``, ``hi dden _dat a, ba seur l, fi le , ft pfil e, da ta , da ta_c olle ctio n, li brar y_da ta , dr ill_ down ``. The defi niti on of supp orte d para mete r type s as defi ned in the ``pa rame ter_ type s dict iona ry in `/li b/ga laxy /too ls/p aram eter s/ba sic. py < http s:// gith ub.c om/g alax ypro ject /gal axy/ blob /mas ter/ lib/ gala xy/t ools /par amet ers/ basi c.py >`__ . True
na me Name for this elem ent. This na me is used as the Chee tah vari able cont aini ng the user -sup plie d para mete r name in co mman d and co nfig file `` elem ents . The name shou ld not cont ain pipe s or peri ods (e.g . ``.` `). Some "res erve d" name s are ``RE DIRE CT_U RL , DA TA_U RL , ``GA LAXY _URL ``. Fals e
ar gume nt If the para mete r refl ects just one comm and line argu ment of a cert ain tool , this tag shou ld be set to that part icul ar argu ment . It is rend ered in pare nthe sis afte r the help sect ion, and it will crea te the name attr ibut e from the argu ment attr ibut e by stri ppin g the dash es (e.g . if ar gume nt=" --se nsit ive" `` then ``na me=" sens itiv e" is impl icit ). Fals e
``la bel` ` The attr ibut e valu e will be disp laye d on the tool page as the labe l of the form fiel d (l abel ="So rt Q uery ") . Fals e
he lp Shor t bit of text , rend ered on the tool form just belo w the asso ciat ed fiel d to prov ide info rmat ion abou t the fiel d. Find the Inte rgal acti c Util itie s Comm isio n sugg este d best prac tice s for this elem ent her e <h ttps ://p lane mo.r eadt hedo cs.i o/en /lat est/ stan dard s/do cs/b est_ prac tice s/to ol_x ml.h tml# para mete r-he lp> __. Fals e
op tion al If ``fa lse` `, para mete r must have a valu e. Defa ults to “fal se”. Fals e
``re fres h_on _cha nge` ` Forc e a relo ad of the tool pane l when the valu e of this para mete r chan ges to allo w co de file proc essi ng. See depr ecat ion- like noti ce for co de bloc ks. Fals e

Parameter Types

text

When type="text", the parameter is free form text and appears as a text box in the tool form.

Examples

Sometimes you need labels for data or graph axes, chart titles, etc. This can be done using a text field. The following will create a text box 30 characters wide with the default value of “V1”.

<param name="xlab" size="30" type="text" value="V1" label="Label for x axis"/>

The size parameter can be two dimensional, if it is the textbox will be rendered on the tool form as a text area instead of a single line text box.

<param name="foo" type="text" area="True" size="5x25" />

As of 17.01, text parameters can also supply a static list of preset defaults options. The user may be presented with the option to select one of these but will be allowed to supply an arbitrary text value.

<param name="foo" type="text" value="foo 1">
    <option value="foo 1">Foo 1 Display</option>
    <option value="foo 2">Foo 2 Display</option>
</param>

See param_text_option.xml for a demonstration of this.

Attributes
Attr ibut e Deta ils Requ ired
ar ea Bool ean indi cati ng if this shou ld be rend ered as a one line text box (if fa lse` `) or a mult i-li ne text area (if ``tr ue ). Fals e
``va lue` ` The defa ult valu e for this para mete r. Fals e
si ze Used only if ty pe attr ibut e valu e is te xt . To crea te a mult i-li ne text box add an ar ea=" True " attr ibut e to the para m tag. This can be one dime nsio nal (e.g . si ze=" 40"` `) or two dime nsio nal (e.g . ``si ze=" 5x25 ") . Fals e

integer and float

These parameters represent whole number and real numbers, respectively.

Example
<param name="region_size" size="4" type="integer" value="1" label="flanking regions of size" />
Attributes
Attr ibut e Deta ils Requ ired
``va lue` ` The defa ult valu e for this para mete r. Fals e
mi n Mini mum vali d para mete r valu e - only vali d when ty pe is in tege r or ``fl oat` `. Fals e
ma x Maxi mum vali d para mete r valu e - only vali d when ty pe is in tege r or ``fl oat` `. Fals e

boolean

This represents a binary true or false value.

Attributes
Attr ibut e Deta ils Requ ired
ch ecke d Set to tr ue if the bo olea n para mete r shou ld be chec ked (or tr ue ) by defa ult. Fals e
``tr ueva lue` ` The para mete r valu e in the Chee tah temp late if the para mete r is tr ue or chec ked by the user . Only vali d if ty pe is bo olea n. Fals e
``fa lsev alue `` The para mete r valu e in the Chee tah temp late if the para mete r is fa lse` ` or not chec ked by the user . Only vali d if ``ty pe is bo olea n. Fals e

data

A dataset from the current history. Multiple types might be used for the param form.

Examples

The following will find all “coordinate interval files” contained within the current history and dynamically populate a select list with them. If they are selected, their destination and internal file name will be passed to the appropriate command line variable.

<param name="interval_file" type="data" format="interval" label="near intervals in"/>

The following demonstrates a param which may accept multiple files and multiple formats.

<param format="sam,bam" multiple="true" name="bamOrSamFile" type="data"
       label="Alignments in BAM or SAM format"
       help="The set of aligned reads." />

Perhaps counter-intuitively, a multiple="true" data parameter requires at least one data input. If optional="true" is specified, this condition is relaxed and the user is allowed to select 0 datasets. Unfortunately, if 0 datasets are selected the resulting value for the parameter during Cheetah templating (such as in a command block) will effectively be a list with one None-like entity in it.

The following idiom can be used to iterate over such a list and build a hypothetical -B parameter for each file - the if block is used to handle the case where a None-like entity appears in the list because no files were selected:

#for $input in $input1
    #if $input
        -B "$input"
    #end if
#end for

Some example tools using multiple="true" data parameters include:

Additionally, a detailed discussion of handling multiple homogenous files can be found in the the Planemo Documentation on this topic.

Attributes
Attr ibut e Deta ils Requ ired
``fo rmat `` Only if ty pe attr ibut e valu e is da ta or da ta_c olle ctio n - the list of supp orte d data form ats is cont aine d in the /co nfig /dat atyp es_ conf .xml .sam ple <htt ps:/ /git hub. com/ gala xypr ojec t/ga laxy /blo b/de v/co nfig /dat atyp es_c onf. xml. samp le> __ file . Use the file exte nsio n. Fals e
mu ltip le Allo w mult iple valu s to be sele cted . Vali d with da ta and ``se lect `` para mete rs. Fals e

select

The following will create a select list containing the options “Downstream” and “Upstream”. Depending on the selection, a d or u value will be passed to the $upstream_or_down variable on the command line.

<param name="upstream_or_down" type="select" label="Get">
  <option value="u">Upstream</option>
  <option value="d">Downstream</option>
</param>

The following will create a checkbox list allowing the user to select “Downstream”, “Upstream”, both, or neither. Depending on the selection, the value of $upstream_or_down will be d, u, u,d, or “”.

<param name="upstream_or_down" type="select" label="Get" multiple="true" display="checkboxes">
  <option value="u">Upstream</option>
  <option value="d">Downstream</option>
</param>
Attributes
Attr ibut e Deta ils Requ ired
da ta_r ef Only vali d if ty pe attr ibut e valu e is se lect `` or ``da ta_c olum n. Used with sele ct list s whos e opti ons are dyna mica lly gene rate d base d on cert ain meta data attr ibut es of the data set upon whic h this para mete r depe nds (usu ally but not alwa ys the tool ‘s inpu t data set) . Fals e
di spla y This attr ibut e is used only if ty pe attr ibut e valu e is ``se lect `` - rend er a sele ct list as a set of chec k boxe s or radi o butt ons. Defa ults to a drop -dow n menu sele ct list . Fals e
mu ltip le Allo w mult iple valu s to be sele cted . Vali d with da ta and ``se lect `` para mete rs. Fals e
dy nami c_op tion s Depr ecat ed/d isco urag ed meth od to allo w acce ss to Pyth on code to gene rate opti ons for a sele ct list . See co de ‘s docu ment atio n for an exam ple. Fals e

data_column

This parameter type is used to select columns from a parameter.

Attributes
Attr ibut e Deta ils Requ ired
fo rce_ sele ct Used only if the ty pe attr ibut e valu e is da ta_c olum n, this is depr ecat ed and the inve rse of op tion al . Set to ``fa lse` ` to not forc e user to sele ct an opti on in the list . Fals e
``nu meri cal` ` Used only if the ty pe attr ibut e valu e is da ta_c olum n, if tr ue the colu mn will be trea ted as nume rica l when filt erin g colu mns base d on meta data . Fals e

drill_down

Attributes
Attr ibut e Deta ils Requ ired
``hi erar chy` ` Used only if the ty pe attr ibut e valu e is ``dr ill_ down ``, this attr ibut e dete rmin es the dril l down is ``re curs ive` ` or ``ex act` `. Fals e

data_collection

The following will create a parameter that only accepts paired FASTQ files grouped into a collection.

Examples
<param name="inputs" type="data_collection" collection_type="paired" label="Input FASTQs" format="fastq">
</param>

More detailed information on writing tools that consume collections can be found in the planemo documentation.

Attributes
Attr ibut e Deta ils Requ ired
``fo rmat `` Only if ty pe attr ibut e valu e is da ta or da ta_c olle ctio n - the list of supp orte d data form ats is cont aine d in the /co nfig /dat atyp es_ conf .xml .sam ple <htt ps:/ /git hub. com/ gala xypr ojec t/ga laxy /blo b/de v/co nfig /dat atyp es_c onf. xml. samp le> __ file . Use the file exte nsio n. Fals e
co llec tion _typ e This is only vali d if ty pe is da ta_c olle ctio n. Rest rict the kind of coll ecti on that can be cons umed by this para mete r (e.g . pa ired ``, ``li st:p aire d, li st ). Mult iple such coll ecti on type s can be spec ifie d here as a comm a sepa rate d list . Fals e

color

Examples

The following example will create a color selector parameter.

<param name="feature_color" type="color" label="Default feature color" value="#ff00ff">
</param>

Given that the output includes a pound sign, it is often convenient to use a sanitizer to prevent Galaxy from escaping the result.

<param name="feature_color" type="color" label="Default feature color" value="#ff00ff">
  <sanitizer>
    <valid initial="string.letters,string.digits">
      <add value="#" />
    </valid>
  </sanitizer>
</param>
Attributes
Attr ibut e Deta ils Requ ired
``va lue` ` The defa ult valu e for this para mete r. Fals e
rg b If fa lse` `, the retu rned valu e will be in Hex colo r code . If ``tr ue it will be a RGB valu e e.g. 0,0, 255. This attr ibut e is only vali d when ty pe is ``co lor` `. Fals e

This covers examples of the most common parameter types, the remaining parameter types are more obsecure and less likely to be useful for most tool authors.

Attributes

Attr ibut e Deta ils Requ ired
ty pe Desc ribe s the para mete r type - each diff eren t type as diff eren t sema ntic s and the tool form widg et is diff eren t. Curr entl y vali d para mete r type s are: te xt , in tege r, fl oat` `, ``bo olea n, ge nome buil d, se lect ``, ``co lor` `, ``da ta_c olum n, hi dden ``, ``hi dden _dat a, ba seur l, fi le , ft pfil e, da ta , da ta_c olle ctio n, li brar y_da ta , dr ill_ down ``. The defi niti on of supp orte d para mete r type s as defi ned in the ``pa rame ter_ type s dict iona ry in `/li b/ga laxy /too ls/p aram eter s/ba sic. py < http s:// gith ub.c om/g alax ypro ject /gal axy/ blob /mas ter/ lib/ gala xy/t ools /par amet ers/ basi c.py >`__ . True
na me Name for this elem ent. This na me is used as the Chee tah vari able cont aini ng the user -sup plie d para mete r name in co mman d and co nfig file `` elem ents . The name shou ld not cont ain pipe s or peri ods (e.g . ``.` `). Some "res erve d" name s are ``RE DIRE CT_U RL , DA TA_U RL , ``GA LAXY _URL ``. Fals e
ar ea Bool ean indi cati ng if this shou ld be rend ered as a one line text box (if fa lse` `) or a mult i-li ne text area (if ``tr ue ). Fals e
ar gume nt If the para mete r refl ects just one comm and line argu ment of a cert ain tool , this tag shou ld be set to that part icul ar argu ment . It is rend ered in pare nthe sis afte r the help sect ion, and it will crea te the name attr ibut e from the argu ment attr ibut e by stri ppin g the dash es (e.g . if ar gume nt=" --se nsit ive" `` then ``na me=" sens itiv e" is impl icit ). Fals e
``la bel` ` The attr ibut e valu e will be disp laye d on the tool page as the labe l of the form fiel d (l abel ="So rt Q uery ") . Fals e
he lp Shor t bit of text , rend ered on the tool form just belo w the asso ciat ed fiel d to prov ide info rmat ion abou t the fiel d. Find the Inte rgal acti c Util itie s Comm isio n sugg este d best prac tice s for this elem ent her e <h ttps ://p lane mo.r eadt hedo cs.i o/en /lat est/ stan dard s/do cs/b est_ prac tice s/to ol_x ml.h tml# para mete r-he lp> __. Fals e
``va lue` ` The defa ult valu e for this para mete r. Fals e
``de faul t_va lue` ` Depr ecat ed way to spec ify defa ult valu e for colu mn para mete rs (use ``va lue` ` inst ead) . Fals e
op tion al If ``fa lse` `, para mete r must have a valu e. Defa ults to “fal se”. Fals e
rg b If fa lse` `, the retu rned valu e will be in Hex colo r code . If ``tr ue it will be a RGB valu e e.g. 0,0, 255. This attr ibut e is only vali d when ty pe is ``co lor` `. Fals e
mi n Mini mum vali d para mete r valu e - only vali d when ty pe is in tege r or ``fl oat` `. Fals e
ma x Maxi mum vali d para mete r valu e - only vali d when ty pe is in tege r or ``fl oat` `. Fals e
``fo rmat `` Only if ty pe attr ibut e valu e is da ta or da ta_c olle ctio n - the list of supp orte d data form ats is cont aine d in the /co nfig /dat atyp es_ conf .xml .sam ple <htt ps:/ /git hub. com/ gala xypr ojec t/ga laxy /blo b/de v/co nfig /dat atyp es_c onf. xml. samp le> __ file . Use the file exte nsio n. Fals e
co llec tion _typ e This is only vali d if ty pe is da ta_c olle ctio n. Rest rict the kind of coll ecti on that can be cons umed by this para mete r (e.g . pa ired ``, ``li st:p aire d, li st ). Mult iple such coll ecti on type s can be spec ifie d here as a comm a sepa rate d list . Fals e
da ta_r ef Only vali d if ty pe attr ibut e valu e is se lect `` or ``da ta_c olum n. Used with sele ct list s whos e opti ons are dyna mica lly gene rate d base d on cert ain meta data attr ibut es of the data set upon whic h this para mete r depe nds (usu ally but not alwa ys the tool ‘s inpu t data set) . Fals e
``ac cept _def ault `` Docu ment atio n for Perm issi veBo olea n Fals e
``re fres h_on _cha nge` ` Forc e a relo ad of the tool pane l when the valu e of this para mete r chan ges to allo w co de file proc essi ng. See depr ecat ion- like noti ce for co de bloc ks. Fals e
fo rce_ sele ct Used only if the ty pe attr ibut e valu e is da ta_c olum n, this is depr ecat ed and the inve rse of op tion al . Set to ``fa lse` ` to not forc e user to sele ct an opti on in the list . Fals e
us e_he ader _nam es Used only if the ty pe attr ibut e valu e is da ta_c olum n, if tr ue Gala xy assu mes firs t row of da ta_r ef is a head er and buil ds the sele ct list with thes e valu es rath er than the more gene ric ``c1 `` … ``cN ``. Fals e
di spla y This attr ibut e is used only if ty pe attr ibut e valu e is ``se lect `` - rend er a sele ct list as a set of chec k boxe s or radi o butt ons. Defa ults to a drop -dow n menu sele ct list . Fals e
mu ltip le Allo w mult iple valu s to be sele cted . Vali d with da ta and ``se lect `` para mete rs. Fals e
``nu meri cal` ` Used only if the ty pe attr ibut e valu e is da ta_c olum n, if tr ue the colu mn will be trea ted as nume rica l when filt erin g colu mns base d on meta data . Fals e
``hi erar chy` ` Used only if the ty pe attr ibut e valu e is ``dr ill_ down ``, this attr ibut e dete rmin es the dril l down is ``re curs ive` ` or ``ex act` `. Fals e
ch ecke d Set to tr ue if the bo olea n para mete r shou ld be chec ked (or tr ue ) by defa ult. Fals e
``tr ueva lue` ` The para mete r valu e in the Chee tah temp late if the para mete r is tr ue or chec ked by the user . Only vali d if ty pe is bo olea n. Fals e
``fa lsev alue `` The para mete r valu e in the Chee tah temp late if the para mete r is fa lse` ` or not chec ked by the user . Only vali d if ``ty pe is bo olea n. Fals e
si ze Used only if ty pe attr ibut e valu e is te xt . To crea te a mult i-li ne text box add an ar ea=" True " attr ibut e to the para m tag. This can be one dime nsio nal (e.g . si ze=" 40"` `) or two dime nsio nal (e.g . ``si ze=" 5x25 ") . Fals e
dy nami c_op tion s Depr ecat ed/d isco urag ed meth od to allo w acce ss to Pyth on code to gene rate opti ons for a sele ct list . See co de ‘s docu ment atio n for an exam ple. Fals e

tool > inputs > param > validator

See the annotation_profiler tool for an example of how to use this tag set. This tag set is contained within the tag set - it applies a validator to the containing parameter.

Examples

The following demonstrates a simple validator unspecified_build ensuring that a dbkey is present on the selected dataset. This example is taken from the extract_genomic_dna tool.

<param name="input" type="data" format="gff,interval" label="Fetch sequences for intervals in">
    <validator type="unspecified_build" />
</param>

Along the same line, the following example taken from samtools_mpileup ensures that a dbkey is present and that FASTA indices in the fasta_indexes tool data table are present.

<param format="bam" label="BAM file(s)" name="input_bam" type="data" min="1" multiple="True">
    <validator type="unspecified_build" />
    <validator type="dataset_metadata_in_data_table" metadata_name="dbkey" table_name="fasta_indexes" metadata_column="1"
               message="Sequences are not currently available for the specified build." />
</param>

In this older, somewhat deprecated example - a genome build of the dataset must be stored in Galaxy clusters and the name of the genome (dbkey) must be one of the values in the first column of file alignseq.loc - that could be expressed with the validator. In general, dataset_metadata_in_file should be considered deprecated in favor of

<validator type="dataset_metadata_in_file"
           filename="alignseq.loc"
           metadata_name="dbkey"
           metadata_column="1"
           message="Sequences are not currently available for the specified build."
           split=" "
           line_startswith="seq" />

A very common validator is simply ensure a Python expression is valid for a specified value. In the following example - paths/names that downstream tools use in filenames may not contain ...

<validator type="expression" message="No two dots (..) allowed">'..' not in value</validator>

Attributes

Attr ibut e Deta ils Requ ired
ty pe The list of supp orte d vali dato rs is in the va lida tor_ type s dict iona ry in /li b/ga laxy /too ls/p aram eter s/va lida tion .py <htt ps:/ /git hub. com/ gala xypr ojec t/ga laxy /blo b/de v/li b/ga laxy /too ls/p aram eter s/va lida tion .py> `__. Vali d valu es incl ude: ``ex pres sion `, re gex` `, ``in _ran ge , le ngth ``, ``me tada ta , un spec ifie d_bu ild` `, ``no _opt ions ``, ``em pty_ fiel d, da tase t_me tada ta_i n_fi le , da tase t_me tada ta_i n_da ta_t able ``, ``da tase t_ok _val idat or True
me ssag e The erro r mess age disp laye d on the tool form if vali dati on fail s. Fals e
``ch eck` ` Comm a-se pera ted list of meta data fiel ds to chec k for if type is me tada ta . If not spec ifie d, all non- opti onal meta data fiel ds will be chec ked unle ss they appe ar in the list of fiel ds spec ifie d by the sk ip attr ibut e. Fals e
``ta ble_ name ``

Tool data tabl e name to chec k agai nst if ty pe is ``da tase t_me tada ta_i n_to ol_d ata` `. See the docu ment atio n for `too l data tabl es < http s:// wiki .gal axyp roje ct.o rg/A dmin /Too ls/D ata% 20Ta bles >`__ and `dat a mana gers

<ht

tps: //ga laxy proj ect. org/ admi n/to ols/ data -man ager s/>` __ for more info rmat ion.

Fals e
fi lena me Tool data file name to chec k agai nst if ty pe is da tase t_me tada ta_i n_fi le . File shou ld be pres ent Gala xy’s ``to ol-d ata` ` dire ctor y. Fals e
``me tada ta_n ame` ` Targ et meta data attr ibut e name for da tase t_me tada ta_i n_da ta_t able `` and ``da tase t_me tada ta_i n_fi le opti ons. Fals e
me tada ta_c olum n Targ et colu mn for meta data attr ibut e in da tase t_me tada ta_i n_da ta_t able `` and ``da tase t_me tada ta_i n_fi le opti ons. This can be an inte ger inde x to the colu mn or a colu mn name . Fals e
li ne_s tart swit h Used to indi cate line s in the file bein g used for vali dati on star t with a this attr ibut e valu e. Fals e
mi n When the ty pe attr ibut e valu e is in _ran ge - this is the mini mum numb er allo wed. Fals e
ma x When the ty pe attr ibut e valu e is in _ran ge - this is the maxi mum numb er allo wed. Fals e
ex clud e_mi n When the ty pe attr ibut e valu e is in _ran ge - this bool ean indi cate s if the mi n valu e is allo wed. Fals e
ex clud e_ma x When the ty pe attr ibut e valu e is in _ran ge - this bool ean indi cate s if the ma x valu e is allo wed. Fals e
``sp lit` `

If ty pe is `da tase t_m etad ata_in_fil e` `, t his attr ibut e is

the col

umn sepa rato r to

use for val

ues in t he s peci fied

fil

e. T his defa ult is`` \t

nd d ue t o a bug in o lder

ver

sion s of

Gal
axy,
sho

uld not be m odif ied.

F

alse ``skip `` | Co mma- sepe rate d li st o f me tada ta f ield s to

ski
p if
typ

e is ``meta data `` . If

not spe

cifi ed, all non- opti onal

met

adat a fi elds

wil
l be
che
cked
unl

ess` `c heck `` attr ibut e is spec ifie d.

Fals e

tool > inputs > param > option

See /tools/filters/sorter.xml for typical examples of how to use this tag set. This directive is used to described static lists of options and is contained within the param directive when the type attribute value is select (i.e. <param type="select" ...>).

Example

<param name="style" type="select" label="with flavor">
    <option value="num">Numerical sort</option>
    <option value="gennum">General numeric sort</option>
    <option value="alpha">Alphabetical sort</option>
</param>

An option can also be annotated with selected="true" to specify a default option.

<param name="col" type="select" label="From">
    <option value="0" selected="true">Column 1 / Sequence name</option>
    <option value="1">Column 2 / Source</option>
    <option value="2">Column 3 / Feature</option>
    <option value="6">Column 7 / Strand</option>
    <option value="7">Column 8 / Frame</option>
</param>

Attributes

Attr ibut e Deta ils Requ ired
``va lue` ` The valu e of the corr espo ndin g vari able when used the Chee tah temp late . Also the valu e that shou ld be used in buil ding test case s and used when buil ding requ ests for the API. Fals e
se lect ed A bool ean para mete r indi cati ng if the corr espo ndin g opti on is sele cted by defa ult (the defa ult is ``fa lse` `). Fals e

tool > inputs > param > conversion

A contrived example of a tool that uses this is the test tool explicit_conversion.xml.

This directive is optionally contained within the <param> tag when the type attribute value is data and is used to dynamically generated a converted dataset for the contained input of the type specified using the type tag.

Attributes

Attr ibut e Deta ils Requ ired
na me Name of chee tah vari able to crea te for conv erte d data set. Fals e
ty pe The shor t exte nsio n desc ribi ng the data type to conv ert to - Gala xy must have a data type conv erte r from the pare nt inpu t’s type to this . Fals e

tool > inputs > param > options

See /tools/extract/liftOver_wrapper.xml for an example of how to use this tag set. This tag set is optionally contained within the <param> tag when the type attribute value is select or data and used to dynamically generated lists of options. This tag set dynamically creates a list of options whose values can be obtained from a predefined file stored locally or a dataset selected from the current history.

There are at least five basic ways to use this tag - four of these correspond to a from_XXX attribute on the options directive and the other is to exclusively use filters to populate options.

  • from_data_table - The options for the select list are dynamically obtained from a file specified in the Galaxy configuration file tool_data_table_conf.xml or from a Tool Shed installed data manager.
  • from_dataset - The options for the select list are dynamically obtained from input dataset selected for the tool from the current history.
  • from_file - The options for the select list are dynamically obtained from a file. This mechanis is discourage in favor of the more generic from_data_table.
  • from_parameter - The options for the select list are dynamically obtained from a parameter.
  • Using filters - various filters can be used to populate options, see examples in the filter documentation.

from_data_table

See Galaxy’s data tables documentation for information on setting up data tables.

Once a data table has been configured and populated, these can be easily leveraged via tools.

This conditional block in the bowtie2 wrapper demonstrates using from_data_table options as an alternative to local reference data.

<conditional name="reference_genome">
  <param name="source" type="select" label="Will you select a reference genome from your history or use a built-in index?" help="Built-ins were indexed using default options. See `Indexes` section of help below">
    <option value="indexed">Use a built-in genome index</option>
    <option value="history">Use a genome from the history and build index</option>
  </param>
  <when value="indexed">
    <param name="index" type="select" label="Select reference genome" help="If your genome of interest is not listed, contact the Galaxy team">
      <options from_data_table="bowtie2_indexes">
        <filter type="sort_by" column="2"/>
        <validator type="no_options" message="No indexes are available for the selected input dataset"/>
      </options>
    </param>
  </when>
  <when value="history">
    <param name="own_file" type="data" format="fasta" label="Select reference genome" />
  </when>
</conditional>

A minimal example wouldn’t even need the filter or validator above, but they are frequently nice features to add to your wrapper and can improve the user experience of a tool.

from_dataset

The following example is taken from the Mothur tool remove.lineage.xml and demonstrates generating options from a dataset directly.

<param name="taxonomy" type="data" format="mothur.seq.taxonomy" label="taxonomy - Taxonomy" help="please make sure your file has no quotation marks in it"/>
<param name="taxons" type="select" size="120" optional="true" multiple="true" label="Browse Taxons from Taxonomy">
    <options from_dataset="taxonomy">
        <column name="name" index="1"/>
        <column name="value" index="1"/>
        <filter type="unique_value" name="unique_taxon" column="1"/>
        <filter type="sort_by" name="sorted_taxon" column="1"/>
    </options>
    <sanitizer>
        <valid initial="default">
            <add preset="string.printable"/>
            <add value=";"/>
            <remove value="&quot;"/>
            <remove value="&apos;"/>
        </valid>
    </sanitizer>
</param>

Filters can be used to generate options from dataset directly also as the example below demonstrates (many more examples are present in the filter documentation).

<param name="species1" type="select" label="When Species" multiple="false">
    <options>
        <filter type="data_meta" ref="input1" key="species" />
    </options>
</param>

from_file

The following example is for Blast databases. In this example users maybe select a database that is pre-formatted and cached in Galaxy clusters. When a new dataset is available, admins must add the database to the local file named “blastdb.loc”. All such databases in that file are included in the options of the select list. For a local instance, the file (e.g. blastdb.loc or alignseq.loc) must be stored in the configured tool_data_path directory. In this example, the option names and values are taken from column 0 of the file.

<param name="source_select" type="select" display="radio" label="Choose target database">
    <options from_file="blastdb.loc">
        <column name="name" index="0"/>
        <column name="value" index="0"/>
    </options>
</param>

In general, from_file should be considered deprecated and from_data_table should be prefered.

from_parameter

This variant of the options directive is discouraged because it exposes internal Galaxy structures. See the older bowtie wrappers for an example of these.

Other Ways to Dynamically Generate Options

Though deprecated and discouraged, code blocks can also be used to generate dynamic options.

Attributes

Attribute Details Required
from_dataset Documentation for from_dataset False
from_file Documentation for from_file False
from_data_table Documentation for from_data_table False
from_parameter Documentation for from_parameter False
options_filter_attribute Documentation for options_filter_attribute False
transform_lines Documentation for transform_lines False
startswith Documentation for startswith False

tool > inputs > param > options > column

Optionally contained within an <options> tag set - specifies columns used in building select options from a file stored locally (i.e. index or tool data) or a dataset in the current history.

Any number of columns may be described, but at least one must be given the name value and it will serve as the value of this parameter in the Cheetah template and elsewhwere (e.g. in API for instance).

If a column named name is defined, this too has special meaning and it will be the value the tool form user sees for each option. If no name column appears, value will serve as the name.

Examples

The following fragment shows options from the dataset in the current history that has been selected as the value of the parameter named input1.

<options from_dataset="input1">
    <column name="name" index="0"/>
    <column name="value" index="0"/>
</options>

The interval2maf tool makes use of this tag with files from a history, and the star_fusion tool makes use of this to reference a data table.

Attributes

Attr ibut e Deta ils Requ ired
na me Name give n to the colu mn with inde x in dex` `, the name s ``na me and ``va lue` ` have spec ial mean ing as desc ribe d abov e. True
``in dex` ` 0-ba sed inde x of the colu mn in the targ et file . True

tool > inputs > param > options > filter

Optionally contained within an <options> tag set - filter out values obtained from a locally stored file (e.g. a tool data table) or a dataset in the current history.

Examples

The following example from Mothur’s remove.groups.xml tool demonstrates filtering a select list based on the metadata of an input to to the tool.

<param name="group_in" type="data" format="mothur.groups,mothur.count_table" label="group or count table - Groups"/>
<param name="groups" type="select" label="groups - Pick groups to remove" multiple="true" optional="false">
    <options>
        <filter type="data_meta" ref="group_in" key="groups"/>
    </options>
</param>

This more advanced example, taken from Mothur’s remove.lineage.xml tool demonstrates using filters to sort a list and remove duplicate entries.

<param name="taxonomy" type="data" format="mothur.cons.taxonomy" label="constaxonomy - Constaxonomy file. Provide either a constaxonomy file or a taxonomy file" help="please make sure your file has no quotation marks in it"/>
<param name="taxons" type="select" size="120" optional="true" multiple="true" label="Browse Taxons from Taxonomy">
    <options from_dataset="taxonomy">
        <column name="name" index="2"/>
        <column name="value" index="2"/>
        <filter type="unique_value" name="unique_taxon" column="2"/>
        <filter type="sort_by" name="sorted_taxon" column="2"/>
    </options>
    <sanitizer>
        <valid initial="default">
            <add preset="string.printable"/>
            <add value=";"/>
            <remove value="&quot;"/>
            <remove value="&apos;"/>
        </valid>
    </sanitizer>
</param>

This example taken from the hisat2 tool demonstrates filtering values from a tool data table.

<param help="If your genome of interest is not listed, contact the Galaxy team" label="Select a reference genome" name="index" type="select">
    <options from_data_table="hisat2_indexes">
        <filter column="2" type="sort_by" />
        <validator message="No genomes are available for the selected input dataset" type="no_options" />
    </options>
</param>

The gemini_load.xml tool demonstrates adding values to an option list using filters.

<param name="infile" type="data" format="vcf" label="VCF file to be loaded in the GEMINI database" help="Only build 37 (aka hg19) of the human genome is supported.">
    <options>
        <filter type="add_value" value="hg19" />
        <filter type="add_value" value="Homo_sapiens_nuHg19_mtrCRS" />
        <filter type="add_value" value="hg_g1k_v37" />
    </options>
</param>

While this fragment from maf_to_interval.xml demonstrates removing items.

<param name="species" type="select" label="Select additional species"
       display="checkboxes" multiple="true"
       help="The species matching the dbkey of the alignment is always included.
       A separate history item will be created for each species.">
    <options>
        <filter type="data_meta" ref="input1" key="species" />
        <filter type="remove_value" meta_ref="input1" key="dbkey" />
    </options>
</param>

This example taken from snpSift_dbnsfp.xml demonstrates splitting up strings into multiple values.

<param name="annotations" type="select" multiple="true" display="checkboxes" label="Annotate with">
    <options from_data_table="snpsift_dbnsfps">
        <column name="name" index="4"/>
        <column name="value" index="4"/>
        <filter type="param_value" ref="dbnsfp" column="3" />
        <filter type="multiple_splitter" column="4" separator=","/>
    </options>
</param>

Attributes

Attr ibut e Deta ils Requ ired
ty pe Thes e valu es are defi ned in the modu le /li b/ga laxy /too ls/p aram eter s/dy nami c_o ptio ns.p y _ in the fi lter _typ es dict iona ry. Curr entl y defi ned valu es are: da ta_m eta` `, ``pa ram_ valu e, st atic _val ue , un ique _val ue , mu ltip le_s plit ter` `, ``at trib ute_ valu e_sp litt er , ad d_va lue` `, ``re move _val ue , and so rt_b y True
``co lumn `` Colu mn targ eted by this filt er - this attr ibut e is unus ed and inva lid if ty pe is ad d_va lue` ` or ``re move _val ue . This can be a colu mn inde x or a colu mn name . Fals e
na me Name disp laye d for valu e to add (onl y used with ty pe of ``ad d_va lue` `). Fals e
re f The attr ibut e name of the refe renc e file (too l data ) or inpu t data set. Only used when ty pe is da ta_m eta` ` (req uire d), ``pa ram_ valu e (req uire d), or re move _val ue (opt iona l). Fals e
ke y When ty pe is da ta_m eta` `, ``pa ram_ valu e, or re move _val ue - this is the name of the meta data key to filt er by. Fals e
mu ltip le For type s da ta_m eta` ` and ``re move _val ue , whet her opti on valu es are mult iple . Colu mns will be spli t by sepa rato r. Defa ults to ``fa lse` `. Fals e
``se para tor` ` When ty pe is da ta_m eta` `, ``mu ltip le_s plit ter` `, or ``re move _val ue - this is used to spli t one valu e into mult iple part s. When ty pe is da ta_m eta` ` or ``re move _val ue this is only used if mu ltip le is set to tr ue . Fals e
ke ep If tr ue , keep colu mns matc hing the valu e, if fa lse` ` disc ard colu mns matc hing the valu e. Used when ``ty pe is eith er st atic _val ue or pa ram_ valu e. Fals e
``va lue` ` Targ et valu e of the oper atio ns - has slig htly diff eren t mean ings depe ndin g on ty pe . For inst ance when ty pe is ad d_va lue` ` it is the valu e to add to the list and when ``ty pe is st atic _val ue it is the valu e comp ared agai nst. Fals e
``re f_at trib ute` ` Only used when ty pe is pa ram_ valu e. Peri od (. ``) sepa rate d attr ibut e chai n of inpu t (``r ef ) attr ibut es to use as valu e for filt er. Fals e
``in dex` ` Used when ty pe is ``ad d_va lue` `, it is the inde x into the list to add the opti on to. If not set, the opti on will be adde d to the end of the list . Fals e
me ta_r ef Only used when ty pe is re move _val ue . Data set to look for the valu e of meta data ke y to remo ve from the list . Fals e

tool > inputs > param > sanitizer

See /tools/filters/grep.xml for a typical example of how to use this tag set. This tag set is used to replace the basic parameter sanitization with custom directives. This tag set is contained within the <param> tag set - it contains a set of <valid> and <mapping> tags.

Examples

This example replaces the invalid character default of X with the empty string (so invalid characters are effectively dropped instead of replaced with X) and indicates the only valid characters for this input are ASCII letters, ASCII digits, and _.

<param name="mystring" type="text" label="Say something interesting">
    <sanitizer invalid_char="">
        <valid initial="string.letters,string.digits"><add value="_" /> </valid>
    </sanitizer>
</param>

This example allows many more valid characters and specifies that & will just be dropped from the input.

<sanitizer>
    <valid initial="string.printable">
        <remove value="&apos;"/>
    </valid>
    <mapping initial="none">
        <add source="&apos;" target=""/>
    </mapping>
</sanitizer>

Attributes

Attr ibut e Deta ils Requ ired
sa niti ze This bool ean para mete r dete rmin es if the inpu t is sani tize d at all (the defa ult is tr ue ). Fals e
in vali d_ch ar The attr ibut e spec ifie s the char acte r used as a repl acem ent for inva lid char acte rs. Fals e

tool > inputs > param > sanitizer > valid

Contained within the <sanitizer> tag set, these are used to specify a list of allowed characters. Contains <add> and <remove> tags.

Attributes

Attr ibut e Deta ils Requ ired
in itia l

This desc ribe s the init ial char acte rs to allo w as vali d, the defa ult is ``st ring .let ters

  • s

trin g.di gits

-=_

.()/ +*^, :?!” ``

Fals e

tool > inputs > param > sanitizer > valid > add

This directive is used to add individual characters or preset lists of characters. Character must not be allowed as a valid input for the mapping to occur. Preset lists include default and none as well as those available from string.* (e.g. string.printable).

Attributes

Attr ibut e Deta ils Requ ired
``pr eset `` Add targ et char acte rs from the list of vali d char acte rs (e.g . st ring .pri ntab le ). Fals e
``va lue` ` Add a char acte r to the list of vali d char acte rs. Fals e

tool > inputs > param > sanitizer > valid > remove

This directive is used to remove individual characters or preset lists of characters. Character must not be allowed as a valid input for the mapping to occur. Preset lists include default and none as well as those available from string.* (e.g. string.printable).

Attributes

Attr ibut e Deta ils Requ ired
``pr eset `` Remo ve char acte rs from the list of vali d char acte rs (e.g . st ring .pri ntab le ). Fals e
``va lue` ` A char acte r to remo ve from the list of vali d char acte rs. Fals e

tool > inputs > param > sanitizer > mapping

Contained within the tag set. Used to specify a mapping of disallowed character to replacement string. Contains and tags.

Attributes

Attr ibut e Deta ils Requ ired
in itia l init ial char acte r mapp ing (def ault is ga laxy .uti l.ma pped _cha rs ) Fals e

tool > inputs > param > sanitizer > mapping > add

Use to add character mapping during sanitization. Character must not be allowed as a valid input for the mapping to occur.

Attributes

Attr ibut e Deta ils Requ ired
``so urce `` Repl ace all occu rren ces of this char acte r with the stri ng of ``ta rget ``. Fals e
``ta rget `` Repl ace all occu rren ces of ``so urce `` with this stri ng Fals e

tool > inputs > param > sanitizer > mapping > remove

Use to remove character mapping during sanitization.

Attributes

Attribute Details Required
source Character to remove from mapping. False

tool > configfiles

See xy_plot.xml for an example of how this tag set is used in a tool. This tag set is a container for <configfile> and <inputs> tag sets - which can be used to setup configuration files for use by tools.

tool > configfiles > configfile

This tag set is contained within the <configfiles> tag set. It allows for the creation of a temporary file for file-based parameter transfer.

Example

The following is taken from the xy_plot.xml tool config.

<configfiles>
    <configfile name="script_file">
      ## Setup R error handling to go to stderr
      options( show.error.messages=F, error = function () { cat( geterrmessage(), file=stderr() ); q( "no", 1, F ) } )
      ## Determine range of all series in the plot
      xrange = c( NULL, NULL )
      yrange = c( NULL, NULL )
      #for $i, $s in enumerate( $series )
          s${i} = read.table( "${s.input.file_name}" )
          x${i} = s${i}[,${s.xcol}]
          y${i} = s${i}[,${s.ycol}]
          xrange = range( x${i}, xrange )
          yrange = range( y${i}, yrange )
      #end for
      ## Open output PDF file
      pdf( "${out_file1}" )
      ## Dummy plot for axis / labels
      plot( NULL, type="n", xlim=xrange, ylim=yrange, main="${main}", xlab="${xlab}", ylab="${ylab}" )
      ## Plot each series
      #for $i, $s in enumerate( $series )
          #if $s.series_type['type'] == "line"
              lines( x${i}, y${i}, lty=${s.series_type.lty}, lwd=${s.series_type.lwd}, col=${s.series_type.col} )
          #elif $s.series_type.type == "points"
              points( x${i}, y${i}, pch=${s.series_type.pch}, cex=${s.series_type.cex}, col=${s.series_type.col} )
          #end if
      #end for
      ## Close the PDF file
      devname = dev.off()
    </configfile>
</configfiles>

This file is then used in the command block of the tool as follows:

<command>bash "$__tool_directory__/r_wrapper.sh" "$script_file"</command>

Attributes

Attr ibut e Deta ils Requ ired
na me Chee tah vari able used to refe renc e the path to the file crea ted with this dire ctiv e. Fals e

tool > configfiles > inputs

This tag set is contained within the tag set. It tells Galaxy to write out a JSON representation of the tool parameters .

Example

The following will create a cheetah variable that can be evaluated as $inputs that will contain the tool parameter inputs.

<configfiles>
    <inputs name="inputs" />
<configfiles>

The following will instead write the inputs to the tool’s working directory with the specified name (i.e. inputs.json).

<configfiles>
    <inputs name="inputs" filename="inputs.json" />
<configfiles>

A contrived example of a tool that uses this is the test tool inputs_as_json.xml.

Attributes

Attr ibut e Deta ils Requ ired
na me Chee tah vari able to popu late the path to the inpu ts JSON file crea ted in resp onse to this dire ctiv e. Fals e
fi lena me Path rela tive to the work ing dire ctor y of the tool for the inpu ts JSON file crea ted in resp onse to this dire ctiv e. Fals e

tool > environment_variables

This directive should contain one or more environment_variable definition.

tool > environment_variables > environment_variable

This directive defines an environment variable that will be available when the tool executes. The body should be a Cheetah template block that may reference the tool’s inputs as demonstrated below.

Example

The following demonstrates a couple environment_variable definitions.

<environment_variables>
    <environment_variable name="INTVAR">$inttest</environment_variable>
    <environment_variable name="IFTEST">#if int($inttest) == 3
ISTHREE
#else#
NOTTHREE
#end if#</environment_variable>
    </environment_variables>
</environment_variables>

If these environment variables are used in another Cheetah context, such as in the command block, the $ used indicate shell expansion of a variable should be escaped with a \ so prevent it from being evaluated as a Cheetah variable instead of shell variable.

<command>
    echo "\$INTVAR"  >  $out_file1;
    echo "\$IFTEST"  >> $out_file1;
</command>

Attributes

Attribute Details Required
name Name of the environment variable to define. False

tool > outputs

Container tag set for the <data> and <collection> tag sets. The files and collections created by tools as a result of their execution are named by Galaxy. You specify the number and type of your output files using the contained <data> and <collection> tags. These may be passed to your tool executable through using line variables just like the parameters described in the <inputs> documentation.

Attributes

Attr ibut e Deta ils Requ ired
pr ovid ed_m etad ata_ styl e

Styl e used for tool prov ided meta data file (i.e . `gal axy. json

<ht

tp:/ /pla nemo .rea dthe docs .io/ en/l ates t/wr itin g_ad vanc ed.h tml# tool -pro vide d-me tada ta>` __) - this can be eith er “leg acy” or “def ault “. The defa ult of tool s with a prof ile of 17.0 9 or newe r are “def ault “, and “leg acy” for olde r and tool s and tool s with out a spec ifie d prof ile. A disc ussi on of the diff eren ces betw een the styl es can be foun d at http s:// gith ub.c om/g alax ypro ject /gal axy/ pull /443 7.

Fals e
``pr ovid ed_m etad ata_ file `` Path rela tive to tool ‘s work ing dire ctor y to load tool prov ided meta data from . This meta data can desc ribe dyna mic data sets to load , dyna mic coll ecti on cont ents , as well as simp le meta data (e.g . name , dbke y, etc. ..) and data type spec ific meta data for decl ared outp uts. More info rmat ion can be foun d `her e <h ttp: //pl anem o.re adth edoc s.io /en/ late st/w riti ng_a dvan ced. html #too l-pr ovid ed-m etad ata> `__. The defa ult is gala xy.j son. Fals e

tool > outputs > data

This tag set is contained within the <outputs> tag set, and it defines the output data description for the files resulting from the tool’s execution. The value of the attribute label can be acquired from input parameters or metadata in the same way that the command line parameters are (discussed in the tag set section above).

Examples

The following will create a variable called $out_file1 with data type pdf.

<outputs>
    <data format="pdf" name="out_file1" />
</outputs>

The valid values for format can be found in /config/datatypes_conf.xml.sample.

The following will create a dataset in the history panel whose data type is the same as that of the input dataset selected (and named input1) for the tool.

<outputs>
    <data format_source="input1" name="out_file1" metadata_source="input1"/>
</outputs>

The following will create datasets in the history panel, setting the output data type to be the same as that of an input dataset named by the format_source attribute. Note that a conditional name is not included, so 2 separate conditional blocks should not contain parameters with the same name.

<inputs>
    <!-- fasta may be an aligned fasta that subclasses Fasta -->
    <param name="fasta" type="data" format="fasta" label="fasta - Sequences"/>
    <conditional name="qual">
        <param name="add" type="select" label="Trim based on a quality file?" help="">
            <option value="no">no</option>
            <option value="yes">yes</option>
        </param>
        <when value="no"/>
        <when value="yes">
            <!-- qual454, qualsolid, qualillumina -->
            <param name="qfile" type="data" format="qual" label="qfile - a quality file"/>
        </when>
    </conditional>
</inputs>
<outputs>
    <data format_source="fasta" name="trim_fasta"
          label="${tool.name} on ${on_string}: trim.fasta"/>
    <data format_source="qfile" name="trim_qual"
          label="${tool.name} on ${on_string}: trim.qual">
        <filter>qual['add'] == 'yes'</filter>
    </data>
</outputs>

Assume that the tool includes an input parameter named database which is a select list (as shown below). Also assume that the user selects the first option in the $database select list. Then the following will ensure that the tool produces a tabular data set whose associated history item has the label Blat on Human (hg18).

<inputs>
    <param format="tabular" name="input" type="data" label="Input stuff"/>
    <param type="select" name="database" label="Database">
        <option value="hg18">Human (hg18)</option>
        <option value="dm3">Fly (dm3)</option>
    </param>
</inputs>
<outputs>
    <data format="input" name="output" label="Blat on ${database.value_label}" />
</outputs>

Attributes

Attr ibut e Deta ils Requ ired
na me Name for this outp ut. This na me is used as the Chee tah vari able cont aini ng the Gala xy assi gned outp ut path in co mman d and ``co nfig file `` elem ents . The name shou ld not cont ain pipe s or peri ods (e.g . ``.` `). Fals e
au to_f orma t If tr ue , this outp ut will snif fed and its form at dete rmin ed auto mati call y by Gala xy. Fals e
``fo rmat `` The shor t name for the outp ut data type . The vali d valu es for form at can be foun d in /co nfig /dat atyp es_ conf .xml .sam ple <htt ps:/ /git hub. com/ gala xypr ojec t/ga laxy /blo b/de v/co nfig /dat atyp es_c onf. xml. samp le> __ (e.g . fo rmat ="pd f" or fo rmat ="fa stqs ange r" ). Fals e
``fo rmat _sou rce` ` This sets the data type of the outp ut file to be the same form at as that of a tool inpu t data set. Fals e
``de faul t_id enti fier _sou rce` ` Sets the sour ce of elem ent iden tifi er to the spec ifie d inpu t. This only appl ies to coll ecti ons that are mapp ed over a non- coll ecti on inpu t and that have equi vale nt stru ctur es. Fals e
me tada ta_s ourc e This copi es the meta data info rmat ion from the tool ‘s inpu t data set. This is part icul arly usef ul for inte rval data type s wher e the orde r of the colu mns is not set. Fals e
``la bel` ` This will be the name of the hist ory item for the outp ut data set. The stri ng can incl ude stru ctur e like ${ <som e pa ram name >.<s ome attr ibut e>}` `, as disc usse d for comm and line para mete rs in the ``<c omma nd>` ` tag set sect ion abov e. The defa ult labe l is ``${ tool .nam e} o n ${ on_s trin g} . Fals e
``fr om_w ork_ dir` ` Rela tive path to a file prod uced by the tool in its work ing dire ctor y. Outp ut’s cont ents are set to this file ‘s cont ents . Fals e
``hi dden `` Bool ean indi cati ng whet her to hide data set in the hist ory view . (Def ault is ``fa lse` `.) Fals e

tool > outputs > data > filter

The <data> tag can contain a <filter> tag which includes a Python code block to be executed to test whether to include this output in the outputs the tool ultimately creates. If the code, when executed, returns True, the output dataset is retained. In these code blocks the tool parameters appear as Python variables and are thus referred to without the $ used for the Cheetah template (used in the <command> tag). Variables that are part of conditionals are accessed using a hash named after the conditional.

Example

<inputs>
  <param type="data" format="fasta" name="reference_genome" label="Reference genome" />
  <param type="data" format="bam" name="input_bam" label="Aligned reads" />
  <conditional name="options">
    <param label="Use advanced options" name="selection_mode" type="select">
      <option selected="True" value="defaults">Use default options</option>
      <option value="advanced">Use advanced options</option>
    </param>
    <when value="defaults"> </when>
    <when value="advanced">
      <param name="vcf_output" type="boolean" checked="false" label="VCF output"
        truevalue="--vcf" falsevalue="" />
    </when>
  <conditional>
</inputs>
<outputs>
  <data format="txt" label="Alignment report on ${on_string}" name="output_txt" />
  <data format="vcf" label="Variant summary on ${on_string}" name="output_vcf">
      <filter>options['selection_mode'] == 'advanced' and options['vcf_output']</filter>
  </data>
</outputs>

tool > outputs > data > change_format

See extract_genomic_dna.xml or the test tool output_format.xml for simple examples of how this tag set is used in a tool. This tag set is optionally contained within the <data> tag set and is the container tag set for the following <when> tag set.

tool > outputs > data > change_format > when

If the data type of the output dataset is the specified type, the data type is changed to the desired type.

Examples

Assume that your tool config includes the following select list parameter structure:

<param name="out_format" type="select" label="Output data type">
    <option value="fasta">FASTA</option>
    <option value="interval">Interval</option>
</param>

Then whenever the user selects the interval option from the select list, the following structure in your tool config will override the format="fasta" setting in the <data> tag set with format="interval".

<outputs>
    <data format="fasta" name="out_file1">
        <change_format>
            <when input="out_format" value="interval" format="interval" />
        </change_format>
    </data>
</outputs>

See extract_genomic_dna.xml or the test tool output_format.xml for more examples.

Attributes

Attr ibut e Deta ils Requ ired
``in put` ` This attr ibut e shou ld be the name of the desi red inpu t para mete r (e.g . ``in put= “out _for mat” `` abov e). Fals e
``va lue` ` This must be a poss ible valu e of the in put` ` para mete r (e.g . ``va lue= "int erva l" abov e), or of the depr ecat ed ``in put_ data set` `’s attr ibut e. True
``fo rmat `` This valu e must be a supp orte d data type (e.g . ``fo rmat =”in terv al”` ). See `/co nfig /dat atyp es_ conf .xml .sam ple <htt ps:/ /git hub. com/ gala xypr ojec t/ga laxy /blo b/de v/co nfig /dat atyp es_c onf. xml. samp le> __ for a list of supp orte d form ats. True
``in put_ data set` ` Depr ecat ed. Fals e
``at trib ute` ` Depr ecat ed. Fals e

tool > outputs > data > actions

The actions directive allows tools to dynamically take actions related to an output either unconditionally or conditionally based on inputs. These actions currently include setting metadata values and the output’s data format.

The examples below will demonstrate that the actions tag contains child conditional tags. The these conditionals are met, additional action directives below the conditional are apply to the data output.

Metadata

The <actions> in the Bowtie 2 wrapper is used in lieu of the deprecated <code> tag to set the dbkey of the output dataset. In bowtie2_wrapper.xml (see below), according to the first action block, if the `reference_genome.source is indexed (not history), then it will assign the dbkey of the output file to be the same as that of the reference file. It does this by looking at through the data table and finding the entry that has the value that’s been selected in the index dropdown box as column 1 of the loc file entry and using the dbkey, in column 0 (ignoring comment lines (starting with #) along the way).

If reference_genome.source is history, it pulls the dbkey from the supplied file.

<data format="bam" name="output" label="${tool.name} on ${on_string}: aligned reads (sorted BAM)">
  <filter>analysis_type['analysis_type_selector'] == "simple" or analysis_type['sam_opt'] is False</filter>
  <actions>
    <conditional name="reference_genome.source">
      <when value="indexed">
        <action type="metadata" name="dbkey">
          <option type="from_data_table" name="bowtie2_indexes" column="1" offset="0">
            <filter type="param_value" column="0" value="#" compare="startswith" keep="False"/>
            <filter type="param_value" ref="reference_genome.index" column="0"/>
          </option>
        </action>
      </when>
      <when value="history">
        <action type="metadata" name="dbkey">
          <option type="from_param" name="reference_genome.own_file" param_attribute="dbkey" />
        </action>
      </when>
    </conditional>
  </actions>
</data>

Format

The Bowtie 2 example also demonstrates conditionally setting an output format based on inputs, as shown below:

<data format="fastqsanger" name="output_unaligned_reads_r" label="${tool.name} on ${on_string}: unaligned reads (R)">
    <filter>( library['type'] == "paired" or library['type'] == "paired_collection" ) and library['unaligned_file'] is True</filter>
    <actions>
        <conditional name="library.type">
            <when value="paired">
                <action type="format">
                    <option type="from_param" name="library.input_2" param_attribute="ext" />
                </action>
            </when>
            <when value="paired_collection">
                <action type="format">
                    <option type="from_param" name="library.input_1" param_attribute="reverse.ext" />
                </action>
            </when>
        </conditional>
    </actions>
</data>

Unconditional Actions and Column Names

For a static file that contains a fixed number of columns, it is straight forward:

<outputs>
    <data format="tabular" name="table">
        <actions>
            <action name="column_names" type="metadata" default="Firstname,Lastname,Age" />
        </actions>
    </data>
</outputs>

It may also be necessary to use column names based on a variable from another input file. This is implemented in the htseq-count and featureCounts wrappers:

<inputs>
    <data name="input_file" type="data" multiple="false">
</inputs>
<outputs>
    <data format="tabular" name="output_short">
        <actions>
            <action name="column_names" type="metadata" default="Geneid,${input_file.name}" />
        </actions>
    </data>
</outputs>

Or in case of multiple files:

<inputs>
    <data name="input_files" type="data" multiple="true">
</inputs>
<outputs>
    <data format="tabular" name="output_short">
        <actions>
            <action name="column_names" type="metadata" default="Geneid,${','.join([ a.name for a in $input_files ])}" />
        </actions>
    </data>
</outputs>

Unconditional Actions - An Older Example

The first approach above to setting dbkey based on tool data tables is prefered, but an older example using so called “loc files” directly is found below.

In addition to demonstrating this lower-level direct access of .loc files, it demonstrates an unconditional action. The second block would not be needed for most cases - it was required in this tool to handle the specific case of a small reference file used for functional testing. It says that if the dbkey has been set to equCab2chrM (which is what the `<filter type="metadata_value"... column="1" /> tag does), then it should be changed to equCab2 (which is the <option type="from_param" ... column="0" ...> tag does).

<actions>
   <conditional name="refGenomeSource.genomeSource">
      <when value="indexed">
           <action type="metadata" name="dbkey">
            <option type="from_file" name="bowtie_indices.loc" column="0" offset="0">
               <filter type="param_value" column="0" value="#" compare="startswith" keep="False"/>
               <filter type="param_value" ref="refGenomeSource.index" column="1"/>
            </option>
         </action>
       </when>
    </conditional>
    <!-- Special casing equCab2chrM to equCab2 -->
    <action type="metadata" name="dbkey">
        <option type="from_param" name="refGenomeSource.genomeSource" column="0" offset="0">
            <filter type="insert_column" column="0" value="equCab2chrM"/>
            <filter type="insert_column" column="0" value="equCab2"/>
            <filter type="metadata_value" ref="output" name="dbkey" column="1" />
        </option>
    </action>
</actions>

tool > outputs > data > actions > conditional

This directive is contained within an output data’s actions directive. This directive describes the state of the inputs required to apply an action (specified as children of the child when directives to this element) to an output.

See actions documentation for examples of this directive.

Attributes

Attr ibut e Deta ils Requ ired
na me Name of the inpu t para mete r to base cond itio nal logi c on. The valu e of this para mete r will be matc hed agai nst nest ed wh en dire ctiv es. True

tool > outputs > data > actions > conditional > when

See actions documentation for examples of this directive.

Attributes

Attr ibut e Deta ils Requ ired
``va lue` ` Valu e to matc h cond itio nal inpu t valu e agai nst. Fals e
da taty pe_i sins tanc e Data type to matc h agai nst (if va lue` ` is unsp ecif ied) . This shou ld be the shor t stri ng desc ribi ng the form at (e.g . ``in terv al ). Fals e

tool > outputs > data > actions > action

This directive is contained within an output data’s actions directive (either directly or beneath a parent conditional tag). This directive describes modifications to either the output’s format or metadata (based on whether type is format or metadata).

See actions documentation for examples of this directive.

Attributes

Attr ibut e Deta ils Requ ired
ty pe Type of acti on (eit her fo rmat `` or ``me tada ta curr entl y). True
na me If ty pe=" meta data ", the name of the meta data elem ent. Fals e
de faul t If ``ty pe=” form at”` `, the defa ult form at if none of the nest ed opti ons appl y. Fals e

tool > outputs > data > discover_datasets

Describe datasets to dynamically collect after the job complete.

There are many simple tools with examples of this element distributed with Galaxy, including:

More information can be found on Planemo’s documentation for multiple output files.

Attributes

Attr ibut e Deta ils Requ ired
``fr om_p rovi ded_ meta data `` Indi cate that data set file name s shou ld simp ly be read from the prov ided meta data file (e.g . gala xy.j son) . If this is set - patt ern and sort must not be set. Fals e
pa tter n Regu lar expr essi on used to find file name s and pars e dyna mic prop erti es. Fals e
``di rect ory` ` Dire ctor y (rel ativ e to work ing dire ctor y) to sear ch for file s. Fals e
``fo rmat `` Form at (or data type ) of disc over ed data sets (an alia s with ex t) . Fals e
ex t Form at (or data type ) of disc over ed data sets (an alia s with ``fo rmat ``). Fals e
vi sibl e Indi cati on if this data set is visi ble in outp ut hist ory. This defa ults to fa lse` `, but prob ably shou ldn' t - be sure to set to ``tr ue if that is your inte ntio n. Fals e
``as sign _pri mary _out put` ` Repl ace the prim ary data set desc ribe d by the para mete r da ta para mete r with the firs t outp ut disc over ed. Fals e

tool > outputs > collection

This tag set is contained within the <outputs> tag set, and it defines the output dataset collection description resulting from the tool’s execution. The value of the attribute label can be acquired from input parameters or metadata in the same way that the command line parameters are (discussed in the command directive).

Creating collections in tools is covered in-depth in planemo’s documentation.

Attributes

Attr ibut e Deta ils Requ ired
na me Name for this outp ut. This na me is used as the Chee tah vari able cont aini ng the Gala xy assi gned outp ut path in co mman d and ``co nfig file `` elem ents . The name shou ld not cont ain pipe s or peri ods (e.g . ``.` `). True
ty pe Coll ecti on type for outp ut (e.g . pa ired ``, ``li st , or ``li st:l ist` `). Fals e
``la bel` ` This will be the name of the hist ory item for the outp ut data set. The stri ng can incl ude stru ctur e like ${ <som e pa ram name >.<s ome attr ibut e>}` `, as disc usse d for comm and line para mete rs in the ``<c omma nd>` ` tag set sect ion abov e. The defa ult labe l is ``${ tool .nam e} o n ${ on_s trin g} . Fals e
``fo rmat _sou rce` ` This is the name of inpu t coll ecti on or data set to deri ve outp ut data set coll ecti on’s elem ent’ s form at/d atat ype from . Fals e
ty pe_s ourc e This is the name of inpu t coll ecti on to deri ve coll ecti on’s type (e.g . co llec tion _typ e) from . Fals e
st ruct ured _lik e This is the name of inpu t coll ecti on or data set to deri ve “str uctu re” of the outp ut from (out put elem ent coun t and iden tifi ers) . For inst ance , if the refe renc ed inpu t has thre e orde red item s with iden tifi ers sa mple 1, sa mple 2, and sa mple 3 Fals e
``in heri t_fo rmat `` If st ruct ured _lik e is set, inhe rit form at of outp uts from form at of corr espo ndin g inpu t. Fals e

tool > outputs > collection > filter

The <data> tag can contain a <filter> tag which includes a Python code block to be executed to test whether to include this output in the outputs the tool ultimately creates. If the code, when executed, returns True, the output dataset is retained. In these code blocks the tool parameters appear as Python variables and are thus referred to without the $ used for the Cheetah template (used in the <command> tag). Variables that are part of conditionals are accessed using a hash named after the conditional.

Example

<inputs>
  <param type="data" format="fasta" name="reference_genome" label="Reference genome" />
  <param type="data" format="bam" name="input_bam" label="Aligned reads" />
  <conditional name="options">
    <param label="Use advanced options" name="selection_mode" type="select">
      <option selected="True" value="defaults">Use default options</option>
      <option value="advanced">Use advanced options</option>
    </param>
    <when value="defaults"> </when>
    <when value="advanced">
      <param name="vcf_output" type="boolean" checked="false" label="VCF output"
        truevalue="--vcf" falsevalue="" />
    </when>
  <conditional>
</inputs>
<outputs>
  <data format="txt" label="Alignment report on ${on_string}" name="output_txt" />
  <data format="vcf" label="Variant summary on ${on_string}" name="output_vcf">
      <filter>options['selection_mode'] == 'advanced' and options['vcf_output']</filter>
  </data>
</outputs>

tool > outputs > collection > discover_datasets

This tag allows one to describe the datasets contained within an output collection dynamically, such that the outputs are “discovered” based on regular expressions after the job is complete.

There are many simple tools with examples of this element distributed with Galaxy, including:

Attributes

Attr ibut e Deta ils Requ ired
``fr om_p rovi ded_ meta data `` Indi cate that data set file name s shou ld simp ly be read from the prov ided meta data file (e.g . gala xy.j son) . If this is set - patt ern and sort must not be set. Fals e
pa tter n Regu lar expr essi on used to find file name s and pars e dyna mic prop erti es. Fals e
``di rect ory` ` Dire ctor y (rel ativ e to work ing dire ctor y) to sear ch for file s. Fals e
``fo rmat `` Form at (or data type ) of disc over ed data sets (an alia s with ex t) . Fals e
ex t Form at (or data type ) of disc over ed data sets (an alia s with ``fo rmat ``). Fals e
vi sibl e Indi cati on if this data set is visi ble in outp ut hist ory. This defa ults to fa lse` `, but prob ably shou ldn' t - be sure to set to ``tr ue if that is your inte ntio n. Fals e

tool > tests

Container tag set to specify tests via the tag sets. Any number of tests can be included, and each test is wrapped within separate tag sets. Functional tests are executed via Planemo or the run_tests.sh shell script distributed with Galaxy.

The documentation contained here is mostly reference documentation, for tutorials on writing tool tests please check out Planemo’s Test-Driven Development documentation or the much older wiki content for WritingTests.

Best Practices

Find the Intergalactic Utilities Commision suggested best practices for this element here.

tool > tests > test

This tag set contains the necessary parameter values for executing the tool via the functional test framework.

Example

The following two tests will execute the /tools/filters/sorter.xml tool. Notice the way that the tool’s inputs and outputs are defined.

<tests>
  <test>
    <param name="input" value="1.bed" ftype="bed" />
    <param name="column" value="1"/>
    <param name="order" value="ASC"/>
    <param name="style" value="num"/>
    <output name="out_file1" file="sort1_num.bed" ftype="bed" />
  </test>
  <test>
    <param name="input" value="7.bed" ftype="bed" />
    <param name="column" value="1"/>
    <param name="order" value="ASC"/>
    <param name="style" value="alpha"/>
    <output name="out_file1" file="sort1_alpha.bed" ftype="bed" />
  </test>
</tests>

The following example, tests the execution of the MAF-to-FASTA converter (/tools/maf/maf_to_fasta.xml).

<tests>
    <test>
        <param name="input1" value="3.maf" ftype="maf"/>
        <param name="species" value="canFam1"/>
        <param name="fasta_type" value="concatenated"/>
        <output name="out_file1" file="cf_maf2fasta_concat.dat" ftype="fasta"/>
    </test>
</tests>

This test demonstrates verifying specific properties about a test output instead of directly comparing it to another file. Here the file attribute is not specified and instead a series of assertions is made about the output.

<test>
    <param name="input" value="maf_stats_interval_in.dat" />
    <param name="lineNum" value="99999"/>
    <output name="out_file1">
        <assert_contents>
            <has_text text="chr7" />
            <not_has_text text="chr8" />
            <has_text_matching expression="1274\d+53" />
            <has_line_matching expression=".*\s+127489808\s+127494553" />
            <!-- &#009; is XML escape code for tab -->
            <has_line line="chr7&#009;127471195&#009;127489808" />
            <has_n_columns n="3" />
        </assert_contents>
    </output>
</test>

Attributes

Attr ibut e Deta ils Requ ired
ex pect _exi t_co de Desc ribe the job’ s expe cted exit code . Fals e
``ex pect _num _out puts `` Asse rt the numb er of outp uts this test shou ld prod uce, this is usef ul to ensu re ``fi lter `` dire ctiv es are impl emen ted corr ectl y. Fals e
``ex pect _fai lure `` Sett ing this to tr ue indi cate s the expe ctat ion is for the job fail . If set to tr ue no job outp ut chec ks may be pres ent in te st defi niti on. Fals e
``ma xsec onds `` Maxi mum amou nt of time to let test run. Fals e

tool > tests > test > param

This tag set defines the tool’s input parameters for executing the tool via the functional test framework. See test documentation for some simple examples of parameters.

Attributes

Attr ibut e Deta ils Requ ired
na me This valu e must matc h the name of the asso ciat ed inpu t para mete r (``p aram ``). True
``va lue` ` This valu e must be one of the lega l valu es that can be assi gned to an inpu t para mete r. Fals e
``ft ype` ` This attr ibut e name shou ld be incl uded only with para mete rs of ty pe da ta for the tool . If this attr ibut e name is not incl uded , the func tion al test fram ewor k will atte mpt to dete rmin e the data type for the inpu t data set usin g the data type snif fers . Fals e
``db key` ` Spec ifie s a db key` ` valu e for the refe renc ed inpu t data set. This is only vali d if the corr espo ndin g para mete r is of ``ty pe da ta . Fals e

tool > tests > test > repeat

Specify test parameters below an iteration of a repeat block with this element.

param elements in a test block can be arranged into nested repeat, conditional, and select structures to match the inputs. While this might be overkill for simple tests, it helps prevent ambiguous definitions and keeps things organized in large test cases. A future profile version of Galaxy tools may require repeat blocks be explicitly defined with this directive.

Examples

The test tool disambiguate_repeats.xml demonstrates the use of this directive.

This first test case demonstrates that this block allows different values for the param named input to be tested even though this parameter name appears in two different <repeat> elements in the <inputs> definition.

<!-- Can disambiguate repeats and specify multiple blocks using,
     nested structure. -->
<test>
    <repeat name="queries">
        <param name="input" value="simple_line.txt"/>
    </repeat>
    <repeat name="more_queries">
        <param name="input" value="simple_line_alternative.txt"/>
    </repeat>
    <output name="out_file1">
        <assert_contents>
            <has_line line="This is a line of text." />
            <has_line line="This is a different line of text." />
        </assert_contents>
    </output>
</test>

The second definition in that file demonstrates repeated <repeat> blocks allowing multiple instances of a single repeat to be specified.

<!-- Multiple such blocks can be specified but only with newer API
     driven tests. -->
<test>
    <repeat name="queries">
        <param name="input" value="simple_line.txt"/>
    </repeat>
    <repeat name="queries">
        <param name="input" value="simple_line_alternative.txt"/>
    </repeat>
    <repeat name="more_queries">
        <param name="input" value="simple_line.txt"/>
    </repeat>
    <repeat name="more_queries">
        <param name="input" value="simple_line_alternative.txt"/>
    </repeat>
    <output name="out_file1" file="simple_lines_interleaved.txt"/>
</test>

Attributes

Attribute Details Required
name This value must match the name of the associated input repeat. True

tool > tests > test > section

Specify test parameters below a named of a section block matching one in inputs with this element.

param elements in a test block can be arranged into nested repeat, conditional, and select structures to match the inputs. While this might be overkill for simple tests, it helps prevent ambiguous definitions and keeps things organized in large test cases. A future profile version of Galaxy tools may require section blocks be explicitly defined with this directive.

Examples

The test tool demonstrating sections (section.xml) contains a test case demonstrating this block. This test case appears below:

<test>
    <section name="int">
        <param name="inttest" value="12456" />
    </section>
    <section name="float">
        <param name="floattest" value="6.789" />
    </section>
    <output name="out_file1">
        <assert_contents>
            <has_line line="12456" />
            <has_line line="6.789" />
        </assert_contents>
    </output>
</test>

Attributes

Attribute Details Required
name This value must match the name of the associated input section. True

tool > tests > test > conditional

Specify test parameters below a named of a conditional block matching one in inputs with this element.

param elements in a test block can be arranged into nested repeat, conditional, and select structures to match the inputs. While this might be overkill for simple tests, it helps prevent ambiguous definitions and keeps things organized in large test cases. A future profile version of Galaxy tools may require conditional blocks be explicitly defined with this directive.

Examples

The following example demonstrates disambiguation of a parameter (named use) which appears in multiple param names in conditionals in the inputs definition of the disambiguate_cond.xml tool.

<!-- Can use nested conditional blocks as shown below to disambiguate
     various nested parameters. -->
<test>
    <conditional name="p1">
        <param name="use" value="False"/>
    </conditional>
    <conditional name="p2">
        <param name="use" value="True"/>
    </conditional>
    <conditional name="p3">
        <param name="use" value="False"/>
    </conditional>
    <conditional name="files">
        <param name="attach_files" value="True" />
        <conditional name="p4">
            <param name="use" value="True"/>
            <param name="file" value="simple_line_alternative.txt" />
        </conditional>
    </conditional>
    <output name="out_file1">
        <assert_contents>
            <has_line line="7 4 7" />
            <has_line line="This is a different line of text." />
        </assert_contents>
    </output>
</test>

The tophat2 tool demonstrates a real tool that benefits from more structured test cases using the conditional test directive. One such test case from that tool is shown below.

<!-- Test base-space paired-end reads with user-supplied reference fasta and full parameters -->
<test>
    <!-- TopHat commands:
    tophat2 -o tmp_dir -r 20 -p 1 -a 8 -m 0 -i 70 -I 500000 -g 40 +coverage-search +min-coverage-intron 50 +max-coverage-intro 20000 +segment-mismatches 2 +segment-length 25 +microexon-search +report_discordant_pairs tophat_in1 test-data/tophat_in2.fastqsanger test-data/tophat_in3.fastqsanger
    Replace the + with double-dash
    Rename the files in tmp_dir appropriately
    -->
    <conditional name="singlePaired">
      <param name="sPaired" value="paired"/>
      <param name="input1" ftype="fastqsanger" value="tophat_in2.fastqsanger"/>
      <param name="input2" ftype="fastqsanger" value="tophat_in3.fastqsanger"/>
      <param name="mate_inner_distance" value="20"/>
      <param name="report_discordant_pairs" value="Yes" />
    </conditional>
    <param name="genomeSource" value="indexed"/>
    <param name="index" value="tophat_test"/>
    <conditional name="params">
      <param name="settingsType" value="full"/>
      <param name="library_type" value="FR Unstranded"/>
      <param name="read_mismatches" value="5"/>
      <!-- Error: the read mismatches (5) and the read gap length (2) should be less than or equal to the read edit dist (2) -->
      <param name="read_edit_dist" value="5" />
      <param name="bowtie_n" value="Yes"/>
      <param name="mate_std_dev" value="20"/>
      <param name="anchor_length" value="8"/>
      <param name="splice_mismatches" value="0"/>
      <param name="min_intron_length" value="70"/>
      <param name="max_intron_length" value="500000"/>
      <param name="max_multihits" value="40"/>
      <param name="min_segment_intron" value="50" />
      <param name="max_segment_intron" value="500000" />
      <param name="seg_mismatches" value="2"/>
      <param name="seg_length" value="25"/>
      <conditional name="indel_search">
        <param name="allow_indel_search" value="No"/>
      </conditional>
      <conditional name="own_junctions">
        <param name="use_junctions" value="Yes" />
        <conditional name="gene_model_ann">
          <param name="use_annotations" value="No" />
        </conditional>
        <conditional name="raw_juncs">
          <param name="use_juncs" value="No" />
        </conditional>
        <conditional name="no_novel_juncs">
          <param name="no_novel_juncs" value="No" />
        </conditional>
      </conditional>
      <conditional name="coverage_search">
        <param name="use_search" value="No" />
      </conditional>
      <param name="microexon_search" value="Yes" />
      <conditional name="bowtie2_settings">
        <param name="b2_settings" value="No" />
      </conditional>
      <!-- Fusion search params -->
      <conditional name="fusion_search">
        <param name="do_search" value="Yes" />
        <param name="anchor_len" value="21" />
        <param name="min_dist" value="10000021" />
        <param name="read_mismatches" value="3" />
        <param name="multireads" value="4" />
        <param name="multipairs" value="5" />
        <param name="ignore_chromosomes" value="chrM"/>
      </conditional>
    </conditional>
    <conditional name="readGroup">
      <param name="specReadGroup" value="no" />
    </conditional>
    <output name="junctions" file="tophat2_out4j.bed" />
    <output name="accepted_hits" file="tophat_out4h.bam" compare="sim_size" />
</test>

Attributes

Attr ibut e Deta ils Requ ired
na me This valu e must matc h the name of the asso ciat ed inpu t co ndit iona l. True

tool > tests > test > output

This tag set defines the variable that names the output dataset for the functional test framework. The functional test framework will execute the tool using the parameters defined in the <param> tag sets and generate a temporary file, which will either be compared with the file named in the file attribute value or checked against assertions made by a child assert_contents tag to verify that the tool is functionally correct.

Attributes

Attr ibut e Deta ils Requ ired
na me This valu e is the same as the valu e of the na me attr ibut e of the ``<d ata> `` tag set cont aine d with in the tool ‘s ``<o utpu ts>` ` tag set. Fals e
fi le If spec ifie d, this valu e is the name of the outp ut file stor ed in the targ et ``te st-d ata` ` dire ctor y whic h will be used to comp are the resu lts of exec utin g the tool via the func tion al test fram ewor k. Fals e
``ft ype` ` If spec ifie d, this valu e will be chec ked agai nst the corr espo ndin g outp ut’s data type . If thes e do not matc h, the test will fail . Fals e
so rt This flag caus es the line s of the outp ut to be sort ed befo re they are comp ared to the expe cted outp ut. This coul d be usef ul for non- dete rmin isti c outp ut. Fals e
``va lue` ` An alia s for fi le . Fals e
md 5 If spec ifie d, the targ et outp ut’s MD5 hash shou ld matc h the valu e spec ifie d here . For larg e stat ic file s it may be inco nven ient to uplo ad the enti ry file and this can be used inst ead. Fals e
ch ecks um If spec ifie d, the targ et outp ut’s chec ksum shou ld matc h the valu e spec ifie d here . This valu e shou ld have the form ha sh_t ype: hash _val ue (e.g . ``sh a1:8 156d 7ca0 f46e d7ab ac98 f82e 36cf addb 2aca 041` `). For larg e stat ic file s it may be inco nven ient to uplo ad the enti ry file and this can be used inst ead. Fals e
co mpar e Type of comp aris on to use when comp arin g test gene rate d outp ut file s to expe cted outp ut file s. Curr entl y vali d valu e are di ff (the defa ult) , re _mat ch , si m_si ze , re _mat ch_m ulti line ``, and ``co ntai ns . Fals e
``li nes_ diff `` If co mpar e is set to di ff , the numb er of line s of diff eren ce to allo w (eac h line with a modi fica tion is a line adde d and a line remo ved so this coun ts as two line s). Fals e
``de comp ress `` If co mpar e is set to di ff , atte mpt to deco mpre ss both prod uced outp ut and expe cted outp ut file s if need ed befo re perf ormi ng the diff . This flag is usef ul for test ing gzip ped outp uts that are non- dete rmin isti c desp ite havi ng dete rmin isti c deco mpre ssed cont ents . This is avai labl e in Gala xy 17.0 5+ and was intr oduc ed in `pul l requ est #355 0 <h ttps ://g ithu b.co m/ga laxy proj ect/ gala xy/p ull/ 3550 >`__ . Fals e
``de lta` ` If co mpar e is set to si m_si ze , this is the numb er of byte s diff eren t allo wed. Fals e

tool > tests > test > output > discover_dataset

This directive specifies a test for an output’s discovered dataset. It acts as an output test tag in many ways and can define any tests of that tag (e.g. assert_contents, value, compare, md5, checksum, metadata, etc…).

Example

The functional test tool multi_output_assign_primary.xml provides a demonstration of using this tag.

<test>
  <param name="num_param" value="7" />
  <param name="input" ftype="txt" value="simple_line.txt"/>
  <output name="sample">
    <assert_contents>
      <has_line line="1" />
    </assert_contents>
    <!-- no sample1 it was consumed by named output "sample" -->
    <discovered_dataset designation="sample2" ftype="tabular">
      <assert_contents><has_line line="2" /></assert_contents>
    </discovered_dataset>
    <discovered_dataset designation="sample3" ftype="tabular">
      <assert_contents><has_line line="3" /></assert_contents>
    </discovered_dataset>
  </output>
</test>

Attributes

Attribute Details Required
designation The designation of the discovered dataset. False

tool > tests > test > output > metadata

This directive specifies a test for an output’s metadata as an expected key-value pair.

Example

The functional test tool tool_provided_metadata_1.xml provides a demonstration of using this tag.

<test>
  <param name="input1" value="simple_line.txt" />
  <output name="out1" file="simple_line.txt" ftype="txt">
    <metadata name="name" value="my dynamic name" />
    <metadata name="info" value="my dynamic info" />
    <metadata name="dbkey" value="cust1" />
  </output>
</test>

Attributes

Attribute Details Required
name Name of the metdata element to check. True
value Expected value (as a string) of metadata value. True

tool > tests > test > output > assert_contents

This tag set defines a sequence of checks or assertions to run against the target output. This tag requires no attributes, but child tags should be used to define the assertions to make about the output. The functional test framework makes it easy to extend Galaxy with such tags, the following table summarizes many of the default assertion tags that come with Galaxy and examples of each can be found below.

The implementation of these tags are simply Python functions defined in the galaxy.tools.verify.asserts module.

Chil d Elem ent/ Asse rtio n Deta ils
ha s_te xt Asse rts the spec ifie d te xt appe ars in the outp ut (e.g . ``<h as_t ext text =”ch r7”> ``).
no t_ha s_te xt Asse rts the spec ifie d te xt does not appe ar in the outp ut (e.g . <n ot_h as_t ext text ="ch r8" /> ).
``ha s_te xt_m atch ing` `

Asse rts text matc hing the spec ifie d regu lar expr essi on (e xpre ssio n) appe ars in the outp ut (e.g . ``<h as_t ext_ matc hing

exp

ress ion= “127 4d+ 53” />`` ).

ha s_li ne

Asse rts a line matc hing the spec ifie d stri ng (``l ine` `) appe ars in the outp ut (e.g . ``<h as_l ine line =”A full

exa
mple
lin

e.” />`` ).

``ha s_li ne_m atch ing` `

Asse rts a line matc hing the spec ifie d regu lar expr essi on (e xpre ssio n) appe ars in the outp ut (e.g . ``<h as_l ine_ matc hing

exp

ress ion= “.*s+12 7489 808s+12 7494 553”

/>`

`).

``ha s_n_ colu mns` `

Asse rts tabu lar outp ut cont ains the spec ifie d numb er (``n ``) of colu mns (e.g . ``<h as_n _col umns

n=”

3” / >``) .

is _val id_x ml Asse rts the outp ut is a vali d XML file (e.g . <i s_va lid_ xml /> ).
``ha s_el emen t_wi th_p ath` `

Asse rts the XML outp ut cont ains at leas t one elem ent (or tag) with the spec ifie d XPat h-li ke pa th (e.g . ``<h as_e leme nt_w ith_ path

pat

h=”B last Outp ut_p aram /Par amet ers/ Para mete rs_m atri x” / >``) .

ha s_n_ elem ents _wit h_pa th

Asse rts the XML outp ut cont ains the spec ifie d numb er (n ``) of elem ents (or tags ) with the spec ifie d XPat h-li ke ``pa th (e.g . ``<h as_n _ele ment s_wi th_p ath n=”9 ” pa th=” Blas tOut put_ iter atio ns/I tera tion /Ite rati on_h its/ Hit/ Hit_ num”

/>`

`).

el emen t_te xt_i s Asse rts the text of the XML elem ent with the spec ifie d XPat h-li ke pa th is the spec ifie d te xt (e.g . <e leme nt_t ext_ is p ath= "Bla stOu tput _pro gram " te xt=" blas tp" /> ).
el emen t_te xt_m atch es Asse rts the text of the XML elem ent with the spec ifie d XPat h-li ke pa th matc hes the regu lar expr essi on defi ned by ex pres sion `` (e.g . ``<e leme nt_t ext_ matc hes path ="Bl astO utpu t_ve rsio n" e xpre ssio n="B LAST P\s+ 2\.2 .*" /> ).
at trib ute_ is

Asse rts the XML at trib ute` ` for the elem ent (or tag) with the spec ifie d XPat h-li ke ``pa th is the spec ifie d te xt (e.g . ``<a ttri bute _is path =”ou terE leme nt/i nner Elem ent1 ” at trib ute= “foo ” te xt=” bar”

/>`

` ).

``at trib ute_ matc hes` `

Asse rts the XML at trib ute` ` for the elem ent (or tag) with the spec ifie d XPat h-li ke ``pa th matc hes the regu lar expr essi on spec ifie d by ``ex pres sion `` (e.g . ``<a ttri bute _mat ches

pat

h=”o uter Elem ent/ inne rEle ment 2” a ttri bute =”fo o2” expr essi on=” bard+” />`` ).

el emen t_te xt

This tag allo ws the deve lope r to recu risi vely spec ify addi tion al asse rtio ns as chil d elem ents abou t just the text cont aine d in the elem ent spec ifie d by the XPat h-li ke pa th (e.g . ``<e leme nt_t ext path =”Bl astO utpu t_it erat ions /Ite rati on/I tera tion _hit s/Hi t/Hi t_de f”>< not_ has_ text

tex

t=”E DK72 998. 1” / ></e leme nt_t ext> ``).

Examples

The following demonstrtes a wide variety of text-based and tabular assertion statements.

<output name="out_file1">
    <assert_contents>
        <has_text text="chr7" />
        <not_has_text text="chr8" />
        <has_text_matching expression="1274\d+53" />
        <has_line_matching expression=".*\s+127489808\s+127494553" />
        <!-- &#009; is XML escape code for tab -->
        <has_line line="chr7&#009;127471195&#009;127489808" />
        <has_n_columns n="3" />
    </assert_contents>
</output>

The following demonstrtes a wide variety of XML assertion statements.

<output name="out_file1">
    <assert_contents>
        <is_valid_xml />
        <has_element_with_path path="BlastOutput_param/Parameters/Parameters_matrix" />
        <has_n_elements_with_path n="9" path="BlastOutput_iterations/Iteration/Iteration_hits/Hit/Hit_num" />
        <element_text_matches path="BlastOutput_version" expression="BLASTP\s+2\.2.*" />
        <element_text_is path="BlastOutput_program" text="blastp" />
        <element_text path="BlastOutput_iterations/Iteration/Iteration_hits/Hit/Hit_def">
            <not_has_text text="EDK72998.1" />
            <has_text_matching expression="ABK[\d\.]+" />
        </element_text>
    </assert_contents>
</output>

The following demonstrtes verifying XML content with XPath-like expressions.

<output name="out_file1">
    <assert_contents>
        <attribute_is path="outerElement/innerElement1" attribute="foo" text="bar" />
        <attribute_matches path="outerElement/innerElement2" attribute="foo2" expression="bar\d+" />
    </assert_contents>
</output>

tool > tests > test > output_collection

Define tests for extra files corresponding to an output collection.

output_collection directives should specify a name and type attribute to describe the expected output collection as a whole.

Expectations about collecton contents are described using child element directives. For nested collections, these child element directives may themselves contain children.

Examples

The genetrack tool demonstrates basic usage of an output_collection test expectation.

<test>
    <param name="input" value="genetrack_input2.gff" ftype="gff" />
    <param name="input_format" value="gff" />
    <param name="sigma" value="5" />
    <param name="exclusion" value="20" />
    <param name="up_width" value="10" />
    <param name="down_width" value="10" />
    <param name="filter" value="3" />
    <output_collection name="genetrack_output" type="list">
        <element name="s5e20u10d10F3_on_data_1" file="genetrack_output2.gff" ftype="gff" />
    </output_collection>
</test>

The CWPair2 tool demonstrates that elements can specify a compare attribute just like output.

<test>
    <param name="input" value="cwpair2_input1.gff" />
    <param name="up_distance" value="25" />
    <param name="down_distance" value="100" />
    <param name="method" value="all" />
    <param name="binsize" value="1" />
    <param name="threshold_format" value="relative_threshold" />
    <param name="relative_threshold" value="0.0" />
    <param name="output_files" value="matched_pair" />
    <output name="statistics_output" file="statistics1.tabular" ftype="tabular" />
    <output_collection name="MP" type="list">
        <element name="data_MP_closest_f0u25d100_on_data_1.gff" file="closest_mp_output1.gff" ftype="gff" compare="contains"/>
        <element name="data_MP_largest_f0u25d100_on_data_1.gff" file="largest_mp_output1.gff" ftype="gff" compare="contains"/>
        <element name="data_MP_mode_f0u25d100_on_data_1.gff" file="mode_mp_output1.gff" ftype="gff" compare="contains"/>
    </output_collection>
</test>

The collection_creates_dynamic_nested test tool demonstrates the use of nested element directives as described above. Notice also that it tests the output with assert_contents instead of supplying a file attribute. Like hinted at with with compare attribute above, the element tag can specify any of the test attributes that apply to the output (e.g. md5, compare, diff, etc…).

<test>
  <param name="foo" value="bar" />
  <output_collection name="list_output" type="list:list">
    <element name="oe1">
      <element name="ie1">
        <assert_contents>
          <has_text_matching expression="^A\n$" />
        </assert_contents>
      </element>
      <element name="ie2">
        <assert_contents>
          <has_text_matching expression="^B\n$" />
        </assert_contents>
      </element>
    </element>
    <element name="oe2">
      <element name="ie1">
        <assert_contents>
          <has_text_matching expression="^C\n$" />
        </assert_contents>
      </element>
      <element name="ie2">
        <assert_contents>
          <has_text_matching expression="^D\n$" />
        </assert_contents>
      </element>
    </element>
    <element name="oe3">
      <element name="ie1">
        <assert_contents>
          <has_text_matching expression="^E\n$" />
        </assert_contents>
      </element>
      <element name="ie2">
        <assert_contents>
          <has_text_matching expression="^F\n$" />
        </assert_contents>
      </element>
    </element>
  </output_collection>
</test>

Attributes

Attr ibut e Deta ils Requ ired
na me This valu e is the same as the valu e of the na me attr ibut e of the <c olle cton > tag set cont aine d with in the tool ‘s ``<o utpu ts>` ` tag set. True
ty pe Expe cted coll ecti on type (e.g . li st , pa ired ``, or ``li st:p aire d) . Fals e
``co unt` ` Numb er of elem ents in outp ut coll ecti on. Fals e

tool > tests > test > assert_command

Describe assertions about the job’s generated command-line.

This tag set defines a sequence of checks or assertions to run against the target output. This tag requires no attributes, but child tags should be used to define the assertions to make about the output. The functional test framework makes it easy to extend Galaxy with such tags, the following table summarizes many of the default assertion tags that come with Galaxy and examples of each can be found below.

The implementation of these tags are simply Python functions defined in the galaxy.tools.verify.asserts module.

Chil d Elem ent/ Asse rtio n Deta ils
ha s_te xt Asse rts the spec ifie d te xt appe ars in the outp ut (e.g . ``<h as_t ext text =”ch r7”> ``).
no t_ha s_te xt Asse rts the spec ifie d te xt does not appe ar in the outp ut (e.g . <n ot_h as_t ext text ="ch r8" /> ).
``ha s_te xt_m atch ing` `

Asse rts text matc hing the spec ifie d regu lar expr essi on (e xpre ssio n) appe ars in the outp ut (e.g . ``<h as_t ext_ matc hing

exp

ress ion= “127 4d+ 53” />`` ).

ha s_li ne

Asse rts a line matc hing the spec ifie d stri ng (``l ine` `) appe ars in the outp ut (e.g . ``<h as_l ine line =”A full

exa
mple
lin

e.” />`` ).

``ha s_li ne_m atch ing` `

Asse rts a line matc hing the spec ifie d regu lar expr essi on (e xpre ssio n) appe ars in the outp ut (e.g . ``<h as_l ine_ matc hing

exp

ress ion= “.*s+12 7489 808s+12 7494 553”

/>`

`).

``ha s_n_ colu mns` `

Asse rts tabu lar outp ut cont ains the spec ifie d numb er (``n ``) of colu mns (e.g . ``<h as_n _col umns

n=”

3” / >``) .

is _val id_x ml Asse rts the outp ut is a vali d XML file (e.g . <i s_va lid_ xml /> ).
``ha s_el emen t_wi th_p ath` `

Asse rts the XML outp ut cont ains at leas t one elem ent (or tag) with the spec ifie d XPat h-li ke pa th (e.g . ``<h as_e leme nt_w ith_ path

pat

h=”B last Outp ut_p aram /Par amet ers/ Para mete rs_m atri x” / >``) .

ha s_n_ elem ents _wit h_pa th

Asse rts the XML outp ut cont ains the spec ifie d numb er (n ``) of elem ents (or tags ) with the spec ifie d XPat h-li ke ``pa th (e.g . ``<h as_n _ele ment s_wi th_p ath n=”9 ” pa th=” Blas tOut put_ iter atio ns/I tera tion /Ite rati on_h its/ Hit/ Hit_ num”

/>`

`).

el emen t_te xt_i s Asse rts the text of the XML elem ent with the spec ifie d XPat h-li ke pa th is the spec ifie d te xt (e.g . <e leme nt_t ext_ is p ath= "Bla stOu tput _pro gram " te xt=" blas tp" /> ).
el emen t_te xt_m atch es Asse rts the text of the XML elem ent with the spec ifie d XPat h-li ke pa th matc hes the regu lar expr essi on defi ned by ex pres sion `` (e.g . ``<e leme nt_t ext_ matc hes path ="Bl astO utpu t_ve rsio n" e xpre ssio n="B LAST P\s+ 2\.2 .*" /> ).
at trib ute_ is

Asse rts the XML at trib ute` ` for the elem ent (or tag) with the spec ifie d XPat h-li ke ``pa th is the spec ifie d te xt (e.g . ``<a ttri bute _is path =”ou terE leme nt/i nner Elem ent1 ” at trib ute= “foo ” te xt=” bar”

/>`

` ).

``at trib ute_ matc hes` `

Asse rts the XML at trib ute` ` for the elem ent (or tag) with the spec ifie d XPat h-li ke ``pa th matc hes the regu lar expr essi on spec ifie d by ``ex pres sion `` (e.g . ``<a ttri bute _mat ches

pat

h=”o uter Elem ent/ inne rEle ment 2” a ttri bute =”fo o2” expr essi on=” bard+” />`` ).

el emen t_te xt

This tag allo ws the deve lope r to recu risi vely spec ify addi tion al asse rtio ns as chil d elem ents abou t just the text cont aine d in the elem ent spec ifie d by the XPat h-li ke pa th (e.g . ``<e leme nt_t ext path =”Bl astO utpu t_it erat ions /Ite rati on/I tera tion _hit s/Hi t/Hi t_de f”>< not_ has_ text

tex

t=”E DK72 998. 1” / ></e leme nt_t ext> ``).

tool > tests > test > assert_stdout

Describe assertions about the job’s standard output.

This tag set defines a sequence of checks or assertions to run against the target output. This tag requires no attributes, but child tags should be used to define the assertions to make about the output. The functional test framework makes it easy to extend Galaxy with such tags, the following table summarizes many of the default assertion tags that come with Galaxy and examples of each can be found below.

The implementation of these tags are simply Python functions defined in the galaxy.tools.verify.asserts module.

Chil d Elem ent/ Asse rtio n Deta ils
ha s_te xt Asse rts the spec ifie d te xt appe ars in the outp ut (e.g . ``<h as_t ext text =”ch r7”> ``).
no t_ha s_te xt Asse rts the spec ifie d te xt does not appe ar in the outp ut (e.g . <n ot_h as_t ext text ="ch r8" /> ).
``ha s_te xt_m atch ing` `

Asse rts text matc hing the spec ifie d regu lar expr essi on (e xpre ssio n) appe ars in the outp ut (e.g . ``<h as_t ext_ matc hing

exp

ress ion= “127 4d+ 53” />`` ).

ha s_li ne

Asse rts a line matc hing the spec ifie d stri ng (``l ine` `) appe ars in the outp ut (e.g . ``<h as_l ine line =”A full

exa
mple
lin

e.” />`` ).

``ha s_li ne_m atch ing` `

Asse rts a line matc hing the spec ifie d regu lar expr essi on (e xpre ssio n) appe ars in the outp ut (e.g . ``<h as_l ine_ matc hing

exp

ress ion= “.*s+12 7489 808s+12 7494 553”

/>`

`).

``ha s_n_ colu mns` `

Asse rts tabu lar outp ut cont ains the spec ifie d numb er (``n ``) of colu mns (e.g . ``<h as_n _col umns

n=”

3” / >``) .

is _val id_x ml Asse rts the outp ut is a vali d XML file (e.g . <i s_va lid_ xml /> ).
``ha s_el emen t_wi th_p ath` `

Asse rts the XML outp ut cont ains at leas t one elem ent (or tag) with the spec ifie d XPat h-li ke pa th (e.g . ``<h as_e leme nt_w ith_ path

pat

h=”B last Outp ut_p aram /Par amet ers/ Para mete rs_m atri x” / >``) .

ha s_n_ elem ents _wit h_pa th

Asse rts the XML outp ut cont ains the spec ifie d numb er (n ``) of elem ents (or tags ) with the spec ifie d XPat h-li ke ``pa th (e.g . ``<h as_n _ele ment s_wi th_p ath n=”9 ” pa th=” Blas tOut put_ iter atio ns/I tera tion /Ite rati on_h its/ Hit/ Hit_ num”

/>`

`).

el emen t_te xt_i s Asse rts the text of the XML elem ent with the spec ifie d XPat h-li ke pa th is the spec ifie d te xt (e.g . <e leme nt_t ext_ is p ath= "Bla stOu tput _pro gram " te xt=" blas tp" /> ).
el emen t_te xt_m atch es Asse rts the text of the XML elem ent with the spec ifie d XPat h-li ke pa th matc hes the regu lar expr essi on defi ned by ex pres sion `` (e.g . ``<e leme nt_t ext_ matc hes path ="Bl astO utpu t_ve rsio n" e xpre ssio n="B LAST P\s+ 2\.2 .*" /> ).
at trib ute_ is

Asse rts the XML at trib ute` ` for the elem ent (or tag) with the spec ifie d XPat h-li ke ``pa th is the spec ifie d te xt (e.g . ``<a ttri bute _is path =”ou terE leme nt/i nner Elem ent1 ” at trib ute= “foo ” te xt=” bar”

/>`

` ).

``at trib ute_ matc hes` `

Asse rts the XML at trib ute` ` for the elem ent (or tag) with the spec ifie d XPat h-li ke ``pa th matc hes the regu lar expr essi on spec ifie d by ``ex pres sion `` (e.g . ``<a ttri bute _mat ches

pat

h=”o uter Elem ent/ inne rEle ment 2” a ttri bute =”fo o2” expr essi on=” bard+” />`` ).

el emen t_te xt

This tag allo ws the deve lope r to recu risi vely spec ify addi tion al asse rtio ns as chil d elem ents abou t just the text cont aine d in the elem ent spec ifie d by the XPat h-li ke pa th (e.g . ``<e leme nt_t ext path =”Bl astO utpu t_it erat ions /Ite rati on/I tera tion _hit s/Hi t/Hi t_de f”>< not_ has_ text

tex

t=”E DK72 998. 1” / ></e leme nt_t ext> ``).

tool > tests > test > assert_stderr

Describe assertions about the job’s standard error.

This tag set defines a sequence of checks or assertions to run against the target output. This tag requires no attributes, but child tags should be used to define the assertions to make about the output. The functional test framework makes it easy to extend Galaxy with such tags, the following table summarizes many of the default assertion tags that come with Galaxy and examples of each can be found below.

The implementation of these tags are simply Python functions defined in the galaxy.tools.verify.asserts module.

Chil d Elem ent/ Asse rtio n Deta ils
ha s_te xt Asse rts the spec ifie d te xt appe ars in the outp ut (e.g . ``<h as_t ext text =”ch r7”> ``).
no t_ha s_te xt Asse rts the spec ifie d te xt does not appe ar in the outp ut (e.g . <n ot_h as_t ext text ="ch r8" /> ).
``ha s_te xt_m atch ing` `

Asse rts text matc hing the spec ifie d regu lar expr essi on (e xpre ssio n) appe ars in the outp ut (e.g . ``<h as_t ext_ matc hing

exp

ress ion= “127 4d+ 53” />`` ).

ha s_li ne

Asse rts a line matc hing the spec ifie d stri ng (``l ine` `) appe ars in the outp ut (e.g . ``<h as_l ine line =”A full

exa
mple
lin

e.” />`` ).

``ha s_li ne_m atch ing` `

Asse rts a line matc hing the spec ifie d regu lar expr essi on (e xpre ssio n) appe ars in the outp ut (e.g . ``<h as_l ine_ matc hing

exp

ress ion= “.*s+12 7489 808s+12 7494 553”

/>`

`).

``ha s_n_ colu mns` `

Asse rts tabu lar outp ut cont ains the spec ifie d numb er (``n ``) of colu mns (e.g . ``<h as_n _col umns

n=”

3” / >``) .

is _val id_x ml Asse rts the outp ut is a vali d XML file (e.g . <i s_va lid_ xml /> ).
``ha s_el emen t_wi th_p ath` `

Asse rts the XML outp ut cont ains at leas t one elem ent (or tag) with the spec ifie d XPat h-li ke pa th (e.g . ``<h as_e leme nt_w ith_ path

pat

h=”B last Outp ut_p aram /Par amet ers/ Para mete rs_m atri x” / >``) .

ha s_n_ elem ents _wit h_pa th

Asse rts the XML outp ut cont ains the spec ifie d numb er (n ``) of elem ents (or tags ) with the spec ifie d XPat h-li ke ``pa th (e.g . ``<h as_n _ele ment s_wi th_p ath n=”9 ” pa th=” Blas tOut put_ iter atio ns/I tera tion /Ite rati on_h its/ Hit/ Hit_ num”

/>`

`).

el emen t_te xt_i s Asse rts the text of the XML elem ent with the spec ifie d XPat h-li ke pa th is the spec ifie d te xt (e.g . <e leme nt_t ext_ is p ath= "Bla stOu tput _pro gram " te xt=" blas tp" /> ).
el emen t_te xt_m atch es Asse rts the text of the XML elem ent with the spec ifie d XPat h-li ke pa th matc hes the regu lar expr essi on defi ned by ex pres sion `` (e.g . ``<e leme nt_t ext_ matc hes path ="Bl astO utpu t_ve rsio n" e xpre ssio n="B LAST P\s+ 2\.2 .*" /> ).
at trib ute_ is

Asse rts the XML at trib ute` ` for the elem ent (or tag) with the spec ifie d XPat h-li ke ``pa th is the spec ifie d te xt (e.g . ``<a ttri bute _is path =”ou terE leme nt/i nner Elem ent1 ” at trib ute= “foo ” te xt=” bar”

/>`

` ).

``at trib ute_ matc hes` `

Asse rts the XML at trib ute` ` for the elem ent (or tag) with the spec ifie d XPat h-li ke ``pa th matc hes the regu lar expr essi on spec ifie d by ``ex pres sion `` (e.g . ``<a ttri bute _mat ches

pat

h=”o uter Elem ent/ inne rEle ment 2” a ttri bute =”fo o2” expr essi on=” bard+” />`` ).

el emen t_te xt

This tag allo ws the deve lope r to recu risi vely spec ify addi tion al asse rtio ns as chil d elem ents abou t just the text cont aine d in the elem ent spec ifie d by the XPat h-li ke pa th (e.g . ``<e leme nt_t ext path =”Bl astO utpu t_it erat ions /Ite rati on/I tera tion _hit s/Hi t/Hi t_de f”>< not_ has_ text

tex

t=”E DK72 998. 1” / ></e leme nt_t ext> ``).

tool > code

Deprecated Do not use this unless absolutely necessary.

The extensions described here can cause problems using your tool with certain components of Galaxy (like the workflow system). It is highly recommended to avoid these constructs unless absolutely necessary.

This tag set provides detailed control of the way the tool is executed. This (optional) code can be deployed in a separate file in the same directory as the tool’s config file. These hooks are being replaced by new tool config features and methods in the /lib/galaxy/tools/__init__.py code file.

Examples

Dynamic Options

Use associated dynamic select lists where selecting an option in the first select list dynamically re-renders the options in the second select list. In this example, we are populating both dynamic select lists from metadata elements associated with a tool’s single input dataset. The 2 metadata elements we’re using look like this.

MetadataElement( name="field_names", default=[], desc="Field names", readonly=True, optional=True, visible=True, no_value=[] )
# The keys in the field_components map to the list of field_names in the above element
# which ensures order for select list options that are built from it.
MetadataElement( name="field_components", default={}, desc="Field names and components", readonly=True, optional=True, visible=True, no_value={} )

Our tool config includes a code file tag like this.

<code file="tool_form_utils.py" />

Here are the relevant input parameters in our tool config. The first parameter is the input dataset that includes the above metadata elements.

<param name="input" type="data" format="vtkascii,vtkbinary" label="Shape with uncolored surface field">
    <validator type="expression" message="Shape must have an uncolored surface field.">value is not None and len(value.metadata.field_names) > 0</validator>
</param>

The following parameter dynamically renders a select list consisting of the elements in the field_names metadata element associated with the selected input dataset.

<param name="field_name" type="select" label="Field name" refresh_on_change="True">
    <options>
        <filter type="data_meta" ref="input" key="field_names"/>
        <validator type="no_options" message="The selected shape has no uncolored surface fields." />
    </options>
</param>

The following parameter calls the get_field_components_options() function in the tool_form_utils.py code file discussed above. This function returns the value of the input dataset’s field_components metadata element dictionary whose key is the currently selected field_name from the select list parameter above.

<param name="field_component_index" type="select" label="Field component index" dynamic_options="get_field_components_options(input, field_name=field_name)" help="Color will be applied to the selected field's component associated with this index." />

Changing the selected option in the field_name select list will dynamically re-render the options available in the associated field_component_index select list, which is the behavior we want.

The get_field_components_options() method looks like this.

def get_field_components_options( dataset, field_name ):
    options = []
    if dataset.metadata is None:
        return options
    if not hasattr( dataset.metadata, 'field_names' ):
        return options
    if dataset.metadata.field_names is None:
        return options
    if field_name is None:
        # The expression validator that helps populate the select list of input
        # datsets in the icqsol_color_surface_field tool does not filter out
        # datasets with no field field_names, so we need this check.
        if len( dataset.metadata.field_names ) == 0:
            return options
        field_name = dataset.metadata.field_names[0]
    field_components = dataset.metadata.field_components.get( field_name, [] )
    for i, field_component in enumerate( field_components ):
        options.append( ( field_component, field_component, i == 0 ) )
    return options

Parameter Validation

This function is called before the tool is executed. If it raises any exceptions the tool execution will be aborted and the exception’s value will be displayed in an error message box. Here is an example:

def validate(incoming):
    """Validator for the plotting program"""


    bins = incoming.get("bins","")
    col = incoming.get("col","")


    if not bins or not col:
        raise Exception, "You need to specify a number for bins and columns"


    try:
        bins = int(bins)
        col = int(col)
    except:
        raise Exception, "Parameters are not integers, columns:%s, bins:%s" % (col, bins)


    if not 1<bins<100:
        raise Exception, "The number of bins %s must be a number between 1 and 100" % bins

This code will intercept a number of parameter errors and return corresponding error messages. The parameter incoming contains a dictionary with all the parameters that were sent through the web.

Pre-job and pre-process code

The signature of both of these is the same:

def exec_before_job(inp_data, out_data, param_dict, tool):
def exec_before_process(inp_data, out_data, param_dict, tool):

The param_dict is a dictionary that contains all the values in the incoming parameter above plus a number of keys and values generated internally by galaxy. The inp_data and the out_data are dictionaries keyed by parameter name containing the classes that represent the data.

Example:

def exec_before_process(inp_data, out_data, param_dict, tool):
    for name, data in out_data.items():
        data.name = 'New name'

This custom code will change the name of the data that was created for this tool to New name. The difference between these two functions is that the exec_before_job executes before the page returns and the user will see the new name right away. If one were to use exec_before_process the new name would be set only once the job starts to execute.

Post-process code

This code executes after the background process running the tool finishes its run. The example below is more advanced one that replaces the type of the output data depending on the parameter named extension:

from galaxy import datatypes
def exec_after_process(app, inp_data, out_data, param_dict, tool, stdout, stderr):
    ext = param_dict.get('extension', 'text')
    items = out_data.items()
    for name, data in items:
        newdata = datatypes.factory(ext)(id=data.id)
        for key, value in data. __dict__.items():
            setattr(newdata, key, value)
        newdata.ext = ext
        out_data[name] = newdata

The content of stdout and stderr are strings containing the output of the process.

Attributes

Attr ibut e Deta ils Requ ired
fi le This valu e is the name of the exec utab le code file , and is call ed in the ex ec_b efor e_pr oces s()` `, ``ex ec_b efor e_jo b()` `, ``ex ec_a fter _pro cess () and ex ec_a fter _job () meth ods. True

tool > requirements

This is a container tag set for the requirement and container tags described in greater detail below. requirements describe software packages and other individual computing requirements required to execute a tool, while containers describe Docker containers that should be able to serve as complete descriptions of the runtime of a tool.

tool > requirements > requirement

This tag set is contained within the requirements tag set. Third party programs or modules that the tool depends upon are included in this tag set.

When a tool runs, Galaxy attempts to resolve these requirements (also called dependencies). requirements are meant to be abstract and resolvable by multiple different systems (e.g. conda, the Galaxy Tool Shed dependency management system, or environment modules).

Read more about dependency resolvers in Galaxy on docs.galaxyproject.org. The current best practice for tool dependencies is to target Conda, this is discussed in greater detail here.

Examples

This example shows a tool that requires the samtools 0.0.18 package.

This package is available via the Tool Shed (see Tool Shed dependency management ) as well as Conda and can be configured locally to adapt to any other package management system.

<requirements>
    <requirement type="package" version="0.1.18">samtools</requirement>
</requirements>

This older example shows a tool that requires R version 2.15.1. The tool_depensencies.xml should contain matching declarations for Galaxy to actually install the R runtime. The set_envirornment type is only respected by the tool shed and is ignored by the newer and preferred conda dependency resolver.

<requirements>
    <requirement type="set_environment">R_SCRIPT_PATH</requirement>
    <requirement type="package" version="2.15.1">R</requirement>
</requirements>

Attributes

Attr ibut e Deta ils Requ ired
ty pe This valu e defi nes the whic h type of the 3rd part y modu le requ ired by this tool . True
ve rsio n For pack age type requ irem ents this valu e defi nes a spec ific vers ion of the tool depe nden cy. Fals e

tool > requirements > container

This tag set is contained within the ‘requirements’ tag set. Galaxy can be configured to run tools within Docker containers - this tag allows the tool to suggest possible valid Docker containers for this tool.

Read more about configuring Galaxy to run Docker jobs here.

Attributes

Attr ibut e Deta ils Requ ired
ty pe This valu e desc ribe s the type of cont aine r that the tool may be exec uted in and curr entl y must be ``do cker ``. True

tool > stdio

Tools write the bulk of useful data to datasets, but they can also write messages to standard I/O (stdio) channels known as standard output (stdout) and standard error (stderr). Both stdout and stderr are typically written to the executing program’s console or terminal. Previous versions of Galaxy checked stderr for execution errors - if any text showed up on stderr, then the tool’s execution was marked as failed. However, many tools write messages to stderr that are not errors, and using stderr allows programs to redirect other interesting messages to a separate file. Programs may also exit with codes that indicate success or failure. One convention is for programs to return 0 on success and a non-zero exit code on failure.

Legacy tools (ones with profile unspecified or a profile of less than 16.04) will default to checking stderr for errors as described above. Newer tools will instead treat an exit code other than 0 as an error. The detect_error on command can swap between these behaviors but the stdio directive allows more options in defining error conditions (though these aren’t always intuitive).

With stdio directive, Galaxy can use regular expressions to scan stdout and stderr, and it also allows exit codes to be scanned for ranges. The <stdio> tag has two subtags, <regex> and <exit_code>, to define regular expressions and exit code processing, respectively. They are defined below. If a tool does not have any valid <regex> or <exit_code> tags, then Galaxy will use the previous technique for finding errors.

A note should be made on the order in which exit codes and regular expressions are applied and how the processing stops. Exit code rules are applied before regular expression rules. The rationale is that exit codes are more clearly defined and are easier to check computationally, so they are applied first. Exit code rules are applied in the order in which they appear in the tool’s configuration file, and regular expressions are also applied in the order in which they appear in the tool’s configuration file. However, once a rule is triggered that causes a fatal error, no further rules are checked.

tool > stdio > exit_code

Tools may use exit codes to indicate specific execution errors. Many programs use 0 to indicate success and non-zero exit codes to indicate errors. Galaxy allows each tool to specify exit codes that indicate errors. Each tag defines a range of exit codes, and each range can be associated with a description of the error (e.g., “Out of Memory”, “Invalid Sequence File”) and an error level. The description just describes the condition and can be anything. The error level is either a warning or a fatal error. A warning means that stderr will be updated with the error’s description. A fatal error means that the tool’s execution will be marked as having an error and the workflow will stop. Note that, if the error level is not supplied, then a fatal error is assumed to have occurred.

The exit code’s range can be any consecutive group of integers. More advanced ranges, such as noncontiguous ranges, are currently not supported. Ranges can be specified in the form “m:n”, where m is the start integer and n is the end integer. If “:n” is specified, then the exit code will be compared against all integers less than or equal to n. If “m:” is used, then the exit code will be compared against all integers greater than or equal to m. If the exit code matches, then the error level is applied and the error’s description is added to stderr. If a tool’s exit code does not match any of the supplied tags’ ranges, then no errors are applied to the tool’s execution.

Note that most Unix and Linux variants only support positive integers 0 to 255 for exit codes. If an exit code falls out of the range 0 to 255, the usual convention is to only use the lower 8 bits for the exit code. The only known exception is if a job is broken into subtasks using the tasks runner and one of those tasks is stopped with a POSIX signal. (Note that signals should be used as a last resort for terminating processes.) In those cases, the task will receive -1 times the signal number. For example, suppose that a job uses the tasks runner and 8 tasks are created for the job. If one of the tasks hangs, then a sysadmin may choose to send the “kill” signal, SIGKILL, to the process. In that case, the task (and its job) will exit with an exit code of -9. More on POSIX signals can be found at https://en.wikipedia.org/wiki/Unix_signal as well as man pages on “signal”.

The tag’s supported attributes are as follows:

  • range: This indicates the range of exit codes to check. The range can be one of the following:
  • n: the exit code will only be compared to n;
  • [m:n]: the exit code must be greater than or equal to m and less than or equal to n;
  • [m:]: the exit code must be greater than or equal to m;
  • [:n]: the exit code must be less than or equal to n.
  • level: This indicates the error level of the exit code. The level can have one of two values:
  • warning: If an exit code falls in the given range, then a description of the error will be added to the beginning of stderr. A warning-level error will not cause the tool to fail.
  • fatal: If an exit code falls in the given range, then a description of the error will be added to the beginning of stderr. A fatal-level error will cause the tool to fail. If no level is specified, then the fatal error level will be assumed to have occurred.
  • description: This is an optional description of the error that corresponds to the exit code.

The following is an example of the tag:

<stdio>
    <exit_code range="2"   level="fatal"   description="Out of Memory" />
    <exit_code range="3:5" level="warning" description="Low disk space" />
    <exit_code range="6:"  level="fatal"   description="Bad input dataset" />
</stdio>

If the tool returns 0 or 1, then the tool will not be marked as having an error. If the exit code is 2, then the tool will fail with the description Out of Memory added to stderr. If the tool returns 3, 4, or 5, then the tool will not be marked as having failed, but Low disk space will be added to stderr. Finally, if the tool returns any number greater than or equal to 6, then the description Bad input dataset will be added to stderr and the tool will be marked as having failed.

tool > stdio > regex

A regular expression defines a pattern of characters. The patterns include the following:

  • GCTA, which matches on the fixed string “GCTA”;
  • [abcd], which matches on the characters a, b, c, or d;
  • [CG]{12}, which matches on 12 consecutive characters that are C or G;
  • a.*z, which matches on the character “a”, followed by 0 or more characters of any type, followed by a “z”;
  • ^X, which matches the letter X at the beginning of a string;
  • Y$, which matches the letter Y at the end of a string.

There are many more possible regular expressions. A reference to all supported regular expressions can be found under Python Regular Expression Syntax.

A regular expression includes the following attributes:

  • source: This tells whether the regular expression should be matched against stdout, stderr, or both. If this attribute is missing or is incorrect, then both stdout and stderr will be checked. The source can be one of the follwing values:
  • stdout: the regular expression will be applied to stdout;
  • stderr: the regular expression will be applied to stderr;
  • both: the regular expression will be applied to both stderr and stdout (which is the default case).
  • match: This is the regular expression that will be used to match against stdout and/or stderr. If the tag does not contain the match attribute, then the tag will be ignored. The regular expression can be any valid Python regular expression. All regular expressions are performed case insensitively. For example, if match contains the regular expression “actg”, then the regular expression will match against “actg”, “ACTG”, “AcTg”, and so on. Also note that, if double quotes (“) are to be used in the match attribute, then the value ” can be used in place of double quotes. Likewise, if single quotes (‘) are to be used in the match attribute, then the value ‘ can be used if necessary.
  • level: This works very similarly to the tag, except that, when a regular expression matches against its source, the description is added to the beginning of the source. For example, if stdout matches on a regular expression, then the regular expression’s description is added to the beginning of stdout (instead of stderr). The level can be log, warning or fatal as described below.
  • log and warning: If the regular expression matches against its source input (i.e., stdout and/or stderr), then a description of the error will be added to the beginning of the source, prepended with either ‘Log:’ or ‘Warning:’. A log-level/warning-level error will not cause the tool to fail.
  • fatal: If the regular expression matches against its source input, then a description of the error will be added to the beginning of the source. A fatal-level error will cause the tool to fail. If no level is specified, then the fatal error level will be assumed to have occurred.
  • description: Just like its exit_code counterpart, this is an optional description of the regular expression that has matched.

The following is an example of regular expressions that may be used:

<stdio>
    <regex match="low space"
           source="both"
           level="warning"
           description="Low space on device" />
    <regex match="error"
           source="stdout"
           level="fatal"
           description="Unknown error encountered" />
    <regex match="[CG]{12}"
           description="Fatal error - CG island 12 nts long found" />
    <regex match="^Branch A"
           level="warning"
           description="Branch A was taken in execution" />
</stdio>

The regular expression matching proceeds as follows. First, if either stdout or stderr match on low space, then a warning is registered. If stdout contained the string ---LOW SPACE---, then stdout has the string Warning: Low space on device added to its beginning. The same goes for if stderr had contained the string low space. Since only a warning could have occurred, the processing continues.

Next, the regular expression error is matched only against stdout. If stdout contains the string error regardless of its capitalization, then a fatal error has occurred and the processing stops. In that case, stdout would be prepended with the string Fatal: Unknown error encountered. Note that, if stderr contained error, ERROR, or ErRor then it would not matter - stderr was not being scanned.

If the second regular expression did not match, then the third regular expression is checked. The third regular expression does not contain an error level, so an error level of fatal is assumed. The third regular expression also does not contain a source, so both stdout and stderr are checked. The third regular expression looks for 12 consecutive “C”s or “G”s in any order and in uppercase or lowercase. If stdout contained cgccGGCCcGGcG or stderr contained CCCCCCgggGGG, then the regular expression would match, the tool would be marked with a fatal error, and the stream that contained the 12-nucleotide CG island would be prepended with Fatal: Fatal error - CG island 12 nts long found.

Finally, if the tool did not match any of the fatal errors, then the fourth regular expression is checked. Since no source is specified, both stdout and stderr are checked. If Branch A is at the beginning of stdout or stderr, then a warning will be registered and the source that contained Branch A will be prepended with the warning Warning: Branch A was taken in execution.

tool > help

This tag set includes all of the necessary details of how to use the tool. This tag set should be included as the next to the last tag set, before citations, in the tool config. Tool help is written in reStructuredText. Included here is only an overview of a subset of features. For more information see http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html .

tag details
``..
cla
ss::
war

ning mark ``

a yellow warning symbol
``..
cla
ss::
inf

omar k``

a blue informat ion symbol
``..
ima
ge::
pat

h-of -the -fil e.pn g :h eigh t: 5 00 : widt h: 6 00``

insert a png file of height 500 and width 600 at this position
** bold ** bold
*i tali c* italic
``*` ` list
``-` ` list
``:: `` paragrap h
``– —` ` a horizont al line

Examples

Show a warning sign to remind users that this tool accept fasta format files only, followed by an example of the query sequence and a figure.

<help>

.. class:: warningmark

'''TIP''' This tool requires *fasta* format.

----

'''Example'''

Query sequence::
    >seq1
    ATCG...

.. image:: my_figure.png
    :height: 500
    :width: 600

</help>

Best Practices

Find the Intergalactic Utilities Commision suggested best practices for this element here.

tool > citations

Tool files may declare one citations element. Each citations element can contain one or more citation tag elements - each of which specifies tool citation information using either a DOI or a BibTeX entry.

These citations will appear at the bottom of the tool form in a formatted way but the user will have to option to select RAW BibTeX for copying and pasting as well. Likewise, the history menu includes an option allowing users to aggregate all such citations across an analysis in a list of citations.

BibTeX entries for citations annotated with DOIs will be fetched by Galaxy from https://dx.doi.org/ and cached.

<citations>
   <!-- Example of annotating a citation using a DOI. -->
   <citation type="doi">10.1093/bioinformatics/btq281</citation>

   <!-- Example of annotating a citation using a BibTex entry. -->
   <citation type="bibtex">@ARTICLE{Kim07aninterior-point,
   author = {Seung-jean Kim and Kwangmoo Koh and Michael Lustig and Stephen Boyd and Dimitry Gorinevsky},
   title = {An interior-point method for large-scale l1-regularized logistic regression},
   journal = {Journal of Machine Learning Research},
   year = {2007},
   volume = {8},
   pages = {1519-1555}
   }</citation>
 </citations>

For more implementation information see the pull request adding this feature. For more examples of how to add this to tools checkout the following commits adding this to the NCBI BLAST+ suite, phenotype association tools, MAF suite, and MACS2 suite.

This feature was added to the August 2014 release of Galaxy, tools annotated with citations will work in older releases of Galaxy but no citation information will be available to the end user.

tool > citations > citation

Each citations element can contain one or more citation tag elements - each of which specifies tool citation information using either a DOI or a BibTeX entry.

Attributes

Attr ibut e Deta ils Requ ired
ty pe Type of cita tion - curr entl y do i and ``bi btex `` are the only supp orte d opti ons. True