Galaxy Tool XML File

The XML File for a Galaxy tool, generally referred to as the "tool config file", 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. It would be best to take some time to browse through the various tool configs ( files with a .xml extension ) in the /tools subdirectories of your local Galaxy instance as you read this document.

Pay attention to the following when creating a new tool:

1. Make sure your XML is valid - Improper XML will most likely cause Galaxy to not load your tool. The easiest way to validate your XML is just to open the XML file itself in Firefox, which will either parse the file and display it, or show the error and its location in large letters.
2. Don't forget to restart Galaxy - Galaxy loads and parses XML at run-time, which means you'll have to restart it after updating any XML files. The same does not apply if you only update an executable.
3. Use the -file_strandCol options - Using interval files is more of a pain than using BED files, because the column locations are variable. But by including command line options in your executable and passing them the "automagic" column variables, you can easily handle interval formats. Plus, since BED formats are treated internally as intervals, you don't have to worry about figuring out which one your program is being passed. Everything will be provided as an interval file. Read more about this in the "command line" tag section below.
4. Make sure your parameter names match your command-line variables - Galaxy will populate your command line options from the parameters selected by the user when the tool executes. Form field values are mapped to parameters in the command line via such that "form field name <-> $parameter name in the command line.
5. Provide tool tips and other help - useful for those that will use your tool. The help section provides information on how to use the tool.

A Galaxy tool's config file consists of a subset of the following XML tag sets - each of these is described in detail in the following sections.

Details of XML tag sets

<tool> tag set

The outer-most tag set

Example

The following is an example that contains all of the attributes described above.

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

<description> tag set

The attribute 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

   1 <description>table browser</description>

<version_command> tag set

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. For example:

   1 <version_string>tophat -version</version_string>

<command> tag set

This tag specifies how Galaxy should invoke your tool's executable, passing it's required input parameter values ( the command line specification links the parameters supplied in the form with the actual tool executable ). Anything inside it preceded by a dollar sign ($) will be treated as a variable whose values can be acquired from one of three sources: parameters, metadata, or output files.

Example

The following uses a compiled executable ( see the various tool config files in ~/tools/emboss_5 tools for examples of using compiled executables ).

   1  <command>backtranseq -sequence $input1 -outfile $out_file1 -cfile $cfile -osformat2 $out_format1 -auto</command>

Example

The following uses an interpreted executable. The values of the $<variables> ( e.g., $input ) are acquired from form field parameters in the tool form ( see ~/tools/filters/sorter.xml for an example of using an interpreted executable ).

   1   <command interpreter="python">sorter.py -i $input -o $out_file1 -cols $column -order $order -style $style</command>

Example

The values of the ${<variables>}( e.g., ${input.metadata.chromCol}) are acquired from the Metadata 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/__init__.py code file wraps a Metadata Collection to return Metadata parameters wrapped according to the Metadata spec.

There are a few reserved variables which Galaxy will automatically fill in

Also note the use of the reserved parameter name GALAXY_DATA_INDEX_DIR - it points to the ~/tool-data directory.

   1 <command interpreter="python">
   2  extract_genomic_dna.py $input $out_file1 -1 ${input.metadata.chromCol},${input.metadata.startCol},${input.metadata.endCol},${input.metadata.strandCol} -d $dbkey -o $out_format -g ${GALAXY_DATA_INDEX_DIR}
   3 </command>

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.

<inputs> tag set

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 set described above.

<repeat> tag set

See ~/tools/plotting/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 "Add new <title>" button will be displayed on the tool form ). An example of the use of this tag set is in the ~/tools/plotting/xy_plot.xml tool config.

Example

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

<conditional> tag set

See ~/tools/maf/interval2maf.xml for an example of how to use this tag set. This is a container for conditional parameters in the tool ( must contain <when> tag sets ) - the command line is wrapped in an if-else statement.

Example

Select the alignment target database ( a Galaxy cached genome build or a dataset in the history ). Note the different input variables in the command lines.

   1 <command interpreter="python">
   2     #if $source.source_select=="database" #blat_wrapper.py 0 $source.dbkey $input_query $output1 $iden $tile_size $one_off
   3     #else #blat_wrapper.py 1 $source.input_target $input_query $output1 $iden $tile_size $one_off
   4     #end if
   5 </command>
   6 
   7 <conditional name="source">
   8     <param name="source_select" type="select" label="Target source">
   9         <option value="database">Genome Build</option>
  10         <option value="input_ref">Your Upload File</option>
  11     </param>
  12     <when value="database">
  13         <param name="dbkey" type="genomebuild" label="Genome" />
  14     </when>
  15     <when value="input_ref">
  16         <param name="input_target" type="data" format="fasta" label="Reference sequence" />
  17     </when>
  18 </conditional>	

<when> tag set

Contained within the <conditional> tag set - each <when> tag set contains a set of input parameters, and the conditional variables are usually defined within <option> tag sets.

Example

This example provides details for how to choose the MAF source file, either locally cached data or an history item ( there are two options: "cached" or "user" ). If a user selects "Alignments in Your History", a variable of type "data" will be generated. If the user selects "Locally Cached Alignments", a drop-down selection menu will be generated according to entries contained in the file "maf_index.loc", which is stored in the ~/tool-data directory.

   1 <command>
   2     #if $maf_source_type.maf_source == "user": #your_program $maf_source_type.maf_file
   3     #else: #your_program $maf_source_type.maf_identifier
   4     #end
   5 </command>
   6 
   7 <inputs>
   8     <conditional name="maf_source_type">
   9         <param name="maf_source" type="select" label="MAF Source">
  10             <option value="cached" selected="true">Locally Cached Alignments</option>
  11             <option value="user">Alignments in Your History</option>
  12         </param>
  13         <when value="user">
  14             <param name="maf_file" type="data" format="maf" label="MAF File" />
  15         </when>
  16         <when value="cached">
  17             <param name="maf_identifier" type="select" label="MAF Type" >
  18                 <options from_file="maf_index.loc">
  19                     <column name="name" index="0"/>
  20                     <column name="value" index="1"/>
  21                 </options>
  22             </param>
  23         </when>
  24     </conditional>
  25 </inputs>

<param> tag set

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.

Example
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. Presto! Automatic temporary file management.

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

Example

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.

   1 <param name="upstream_or_down" type="select" format="text">
   2     <label>Get</label>
   3     <option value="u">Upstream</option>
   4     <option value="d">Downstream</option>
   5 </param>

Example

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".

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

Example

The following will create a text box 4 characters wide with the default value of 1 and will restrict values entered to integers:

   1 <param name="region_size" size="4" type="integer" value="1"><label>flanking regions of size</label></param>

<validator> tag set

See ~/tools/annotation_profiler/annotation_profiler.xml for an example of how to use this tag set. This tag set is contained within the <param> tag set - it applies a validator to the containing parameter.

Example

   1 <param format="bed" name="input1" type="data" label="Send this dataset to EpiGRAPH">
   2     <validator type="unspecified_build" />
   3 </param>

Example

The 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.

   1 <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" />

<option> tag set

See ~/tools/filters/sorter.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" ( used for statically generated select lists ).

Example

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

<options> tag set

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" ( used for dynamically generated select lists ). 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.

Example

Select a database that is pre-formatted and cached in Galaxy clusters. When a new dataset is available, it will be added to the local file named "blastdb.loc" and included in the options of the select list. For a local instance, the file ("blastdb.loc" or "alignseq.loc") must be stored in the ~/tool_data directory. In this example, the option names and values are taken from column 0 of the file.

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

Example

Show all of the species that are available in the dataset selected for the parameter named "input1".

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

Example

Select datasets that are available in both the dataset selected for the parameter named "input1" and the binned_scores.loc file locally stored in the ~/tool-data directory.

   1 <param name="datasets" type="select" label="Available datasets" display="radio">
   2   <options from_file="binned_scores.loc">
   3      <column name="name" index="1"/>
   4      <column name="value" index="2"/>
   5      <column name="dbkey" index="0"/>
   6      <filter type="data_meta" ref="input1" key="dbkey" column="0" />
   7    </options>
   8 </param>

from_data_table

Basically, there are 3 steps to using from_data_table:

1. Modify tool_data_table_conf.xml to specify:

    - The bowtie data table
    - The column types in the loc file
    - It should look something like this:

   1 <table name="bowtie_indexes">
   2   <columns>name, value</columns>
   3   <file path="tool-data/bowtie_indices.loc" />
   4 </table>

When defining column names in data_tables, it is suggested that the use of special characters (e.g. hyphens) is avoided. This will allow simplified access to additional fields for a parameter value when e.g. building the command-line; for example if a 'path' value needs to be accessed, it could be done with a syntax of ${param.fields.path}.

2. Create/modify the loc file to correspond with the column types specified in tool_data_table_conf.xml (in this example, the loc file doesn't have to be changed), though we are going to be changing the specification to <columns>value, dbkey, name, path</columns>

3. Modify the Bowtie wrapper to use the data table instead of the loc file directly, replacing this:

   1 <options from_file="bowtie_indices.loc">
   2   <column name="value" index="1" />
   3   <column name="name" index="0" />
   4 </options>

with this:

   1 <options from_data_table="bowtie_indexes"/>

Example

Select a reference genome that is indexed for bowtie. (see ~/tools/sr_mapping/bowtie_wrapper.xml)

   1 <param name="index" type="select" label="Select a reference genome" help="if your genome of interest is not listed - contact Galaxy team">
   2      <options from_data_table="bowtie_indexes"/>          
   3 </param>

<column> tag set

Optionally contained within an <options> tag set - displays columns of values from a file stored locally or a dataset in the current history.

Example

Show options from the dataset in the current history that has been selected as the value of the parameter named "input1".

   1 <options from_dataset="input1">
   2     <column name="name" index="0"/>
   3     <column name="value" index="0"/>
   4 </options>

<filter> tag set

Optionally contained within an <options> tag set - filter out values obtained from a locally stored file or a dataset in the current history.

Example

Filter values in dataset "input".

   1 <param name="to_dbkey" type="select" label="To">
   2     <options from_file="liftOver.loc">
   3         <column name="name" index="1"/>
   4         <column name="value" index="2"/>
   5         <column name="dbkey" index="0"/>
   6         <filter type="data_meta" ref="input" key="dbkey" column="0" />
   7     </options>
   8 </param> 

Example

Show all options contained in the file "encode_datasets.loc", which is locally stored in the ~/tool-data directory.

   1 <options from_file="encode_datasets.loc">
   2     <column name="name" index="2"/>
   3     <column name="value" index="3"/>
   4     <column name="dbkey" index="1"/>
   5     <column name="encode_group" index="0"/>
   6     <column name="uid" index="3"/>
   7     <filter type="static_value" name="encode_group" value="ALD" column="0"/>
   8     <filter type="static_value" name="dbkey" value="hg17" column="1"/>
   9 </options>

<request_param_translation> tag set

See ~/tools/data_source/ucsc_tablebrowser.xml for an example of how to use this tag set. This tag set is used only in "data_source" tools ( the "tool_type" attribute value is "data_source" ). This tag set is contained within the <param> tag set - it contains a set of <request_param> tags.

<request_param> tag set

Contained within the <request_param_translation> tag set ( used only in "data_source" tools ) - the external data source application may send back parameter names like "GENOME" which must be translated to "dbkey" in Galaxy.

Example

   1 <requst_param_translation>
   2     <request_param galaxy_name="organism" remote_name="org" missing="unknown species" />
   3 </request_param_tranlsation>

<append_param> tag set

Optionally contained within the <request_param> tag set if galaxy_name="URL" - some remote data sources ( e.g., Gbrowse, Biomart ) send parameters back to Galaxy in the initial response that must be added to the value of "URL" prior to Galaxy sending the secondary request to the remote data source via URL.

<value> tag set

Contained within the <append_param> tag set - allows for appending a param name / value pair to the value of URL.

Example

   1 <request_param_translation>
   2     <request_param galaxy_name="URL" remote_name="URL" missing="">
   3         <append_param separator="&amp;" first_separator="?" join="=">
   4             <value name="_export" missing="1" />
   5         </append_param>
   6     </request_param>
   7 </request_param_tranlsation>

<value_translation> tag set

Optionally contained within the <request_param> tag set the parameter value received from a remote data source may be named differently in Galaxy, and this tag set allows for the value to be appropriately translated.

<value> tag set

Contained within the <value_translation> tag set - allows for changing the data type value to something supported by Galaxy.

Example

   1 <request_param_translation>
   2     <request_param galaxy_name="data_type" remote_name="hgta_outputType" missing="bed" >
   3         <value_translation>
   4             <value galaxy_value="tabular" remote_value="primaryTable" />
   5         </value_translation>
   6     </request_param>
   7 </request_param_tranlsation>

<sanitizer> tag set

See ~/tools/filters/grep.xml for an 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.

<valid> tag set

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

<add> and <remove> tag set

Contained within the <valid> tag set. Used to add or 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).

<mapping> tag set

Contained within the <sanitizer> tag set. Used to specify a mapping of disallowed character to replacement string. Contains <add> and <remove> tags.

<add> and <remove> tag set

Contained within the <valid> tag set. Used to add or 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).

Example

   1       <sanitizer>
   2         <valid initial="string.printable">
   3          <remove value="&apos;"/>
   4         </valid>
   5         <mapping initial="none">
   6           <add source="&apos;" target=""/>
   7         </mapping>
   8       </sanitizer>

<configfiles> tag set

See ~/tools/maf/maf_filter.xml for an example of how this tag set is used in a tool. This tag set is a container for <configfile> tag sets - it defines an additional configuration section.

<configfile> tag set

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 ~/tools/plotting/xy_plot.xml tool config.

   1 <configfiles>
   2     <configfile name="script_file">
   3       ## Setup R error handling to go to stderr
   4       options( show.error.messages=F, error = function () { cat( geterrmessage(), file=stderr() ); q( "no", 1, F ) } )
   5       ## Determine range of all series in the plot
   6       xrange = c( NULL, NULL )
   7       yrange = c( NULL, NULL )
   8       #for $i, $s in enumerate( $series )
   9           s${i} = read.table( "${s.input.file_name}" )
  10           x${i} = s${i}[,${s.xcol}]
  11           y${i} = s${i}[,${s.ycol}]
  12           xrange = range( x${i}, xrange )
  13           yrange = range( y${i}, yrange )
  14       #end for
  15       ## Open output PDF file
  16       pdf( "${out_file1}" )
  17       ## Dummy plot for axis / labels
  18       plot( NULL, type="n", xlim=xrange, ylim=yrange, main="${main}", xlab="${xlab}", ylab="${ylab}" )
  19       ## Plot each series
  20       #for $i, $s in enumerate( $series )
  21           #if $s.series_type['type'] == "line"
  22               lines( x${i}, y${i}, lty=${s.series_type.lty}, lwd=${s.series_type.lwd}, col=${s.series_type.col} )
  23           #elif $s.series_type.type == "points"
  24               points( x${i}, y${i}, pch=${s.series_type.pch}, cex=${s.series_type.cex}, col=${s.series_type.col} )
  25           #end if
  26       #end for    
  27       ## Close the PDF file
  28       devname = dev.off() 
  29     </configfile>
  30 </configfiles>

<outputs> tag set

Container tag set for the <data> tag set. The files 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> tags. You must pass them to your tool executable through using line variables just like the parameters described in the previous sections.

<data> tag set

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 <command> tag set section above ).

Example

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

   1 <outputs>
   2     <data format="input" name="out_file1" metadata_source="input"/>
   3 </outputs>

Example

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.

   1 <inputs>
   2   <!-- fasta may be an aligned fasta that subclasses Fasta -->
   3   <param name="fasta" type="data" format="fasta" label="fasta - Sequences"/>
   4   <conditional name="qual">
   5    <param name="add" type="select" label="Trim based on a quality file?" help="">
   6     <option value="no">no</option>
   7     <option value="yes">yes</option>
   8    </param>
   9    <when value="no"/>
  10    <when value="yes">    
  11     <!-- qual454, qualsolid, qualillumina -->
  12     <param name="qfile" type="data" format="qual" label="qfile - a quality file"/>
  13    </when>
  14   </conditional>
  15 </inputs>
  16 <outputs>
  17   <data format_source="fasta" name="trim_fasta" label="${tool.name} on ${on_string}: trim.fasta"/>
  18   <data format_source="qfile" name="trim_qual" label="${tool.name} on ${on_string}: trim.qual">
  19    <filter>(qual['add'] == 'yes')</filter>
  20   </data>
  21 </outputs>

Example

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

   1 <outputs>
   2     <data format="pdf" name="out_file1" />
   3 </outputs>

Example

Assume that the tool includes an input parameter named "database" which is a select list ( e.g., assume the following inputs ):

   1 <inputs>
   2     <param format="tabular" name="input" type="data" label="Input stuff"/>
   3     <param type="select" name="database" label="Database">
   4         <option value="alignseq.loc">Human (hg18)</option>
   5         <option value="faseq.loc">Fly (dm3)</option>
   6     </param>
   7 </inputs>

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)".

   1 <outputs>
   2     <data format="input" name="output" label="Blat on ${database.value_label}" />
   3 </outputs>

<change_format> tag set

See ~/tools/extract/extract_genomic_dna.xml for an example 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.

<when> tag set ( change_format )

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

Example

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

   1 <param name="out_format" type="select" label="Output data type">
   2     <option value="fasta">FASTA</option>
   3     <option value="interval">Interval</option>
   4 </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".

   1 <outputs>
   2     <data format="fasta" name="out_file1">
   3         <change_format>
   4             <when input="out_format" value="interval" format="interval" />
   5         </change_format>
   6     </data>
   7 </outputs>

<actions> tag set

The <actions> in the Bowtie wrapper is used in lieu of the deprecated <code> tag to set the dbkey of the output dataset. In bowtie_wrapper.xml (see below), according to the first action block, if the refGenomeSource.genomeSource 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 loc file and finding the line 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 refGenomeSource.genomeSource is "history", it resorts to default behavior for Galaxy, which is that the output is assigned the same value as the first input that has a dbkey specified.

The second block would not be needed for most cases--it is required here to handle the specific case of a small reference file we use for functional testing. It says that if the dbkey has been set to "equCab2chrM" (that's what the <filter type="metadata_value"... column="1" /> tag) does then it should be changed to "equCab2" (the <option type="from_param" ... column="0" ...> tag does).

Example

   1 <actions>
   2    <conditional name="refGenomeSource.genomeSource">
   3       <when value="indexed">
   4            <action type="metadata" name="dbkey">
   5             <option type="from_file" name="bowtie_indices.loc" column="0" offset="0">
   6                <filter type="param_value" column="0" value="#" compare="startswith" keep="False"/>
   7                <filter type="param_value" ref="refGenomeSource.index" column="1"/>
   8             </option>
   9          </action>
  10        </when>
  11     </conditional>
  12     <!-- Special casing equCab2chrM to equCab2 -->
  13     <action type="metadata" name="dbkey">
  14         <option type="from_param" name="refGenomeSource.genomeSource" column="0" offset="0">
  15             <filter type="insert_column" column="0" value="equCab2chrM"/>
  16             <filter type="insert_column" column="0" value="equCab2"/>
  17             <filter type="metadata_value" ref="output" name="dbkey" column="1" />
  18         </option>
  19     </action>
  20 </actions>

<tests> tag set

Container tag set for the <test> tag sets. Functional tests are executed via the ~/run_functional_tests.sh shell script. Any number of tests can be included, and each test is wrapped within separate <test> tag sets.

<test> tag set

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

Example

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

   1   <tests>
   2     <test>
   3       <param name="input" value="1.bed"/>
   4       <param name="column" value="1"/>
   5       <param name="order" value="ASC"/>
   6       <param name="style" value="num"/>
   7       <output name="out_file1" file="sort1_num.bed"/>
   8     </test>
   9     <test>
  10       <param name="input" value="7.bed"/>
  11       <param name="column" value="1"/>
  12       <param name="order" value="ASC"/>
  13       <param name="style" value="alpha"/>
  14       <output name="out_file1" file="sort1_alpha.bed"/>
  15     </test>
  16   </tests>

Example

Test the execution of the MAF-to-FASTA converter ( ~/tools/maf/maf_to_fasta.xml ).

   1 <tests>
   2     <test>
   3         <param name="input1" value="3.maf" ftype="maf"/>
   4         <param name="species" value="canFam1"/>
   5         <param name="fasta_type" value="concatenated"/>
   6         <output name="out_file1" file="cf_maf2fasta_concat.dat" ftype="fasta"/>
   7     </test>
   8 </tests>

Example

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.

   1 <test>
   2     <param name="input" value="maf_stats_interval_in.dat" />
   3     <param name="lineNum" value="99999"/>
   4     <output name="out_file1">
   5         <assert_contents>
   6             <has_text text="chr7" />
   7             <not_has_text text="chr8" />
   8             <has_text_matching expression="1274\d+53" />
   9             <has_line_matching expression=".*\s+127489808\s+127494553" />
  10             <!-- &#009; is XML escape code for tab -->
  11             <has_line line="chr7&#009;127471195&#009;127489808" />
  12             <has_n_columns n="3" />
  13         </assert_contents>
  14     </output>
  15 </test>

<param> tag set (functional tests)

This tag set defines the tool's input parameters for executing the tool via the functional test framework.

Example

The following defines the four input values that are passed to the ~/tools/filters/sorter.xml tool via functional test framework.

   1     <param name="input" value="7.bed"/>
   2     <param name="column" value="1"/>
   3     <param name="order" value="ASC"/>
   4     <param name="style" value="alpha"/>

<output> tag set (functional tests)

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.

<assert_contents> tag set (functional tests)

This tag set defines a sequence of checks or assertions to run against an output dataset for the functional test framework. This tag requires no attributes, but child tags should be used to define the assertions to make about the output dataset. 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.

Example

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

Example

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

Example

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

<page> tag set

This is deprecated since the introduction of the "refresh_on_change" features, so try to stay away from using it for new tools. In older tools, if you needed to split your interface over multiple pages, you could do so by wrapping each page with a <page></page> tag and putting them in order in the XML file.

To create two-page interface:

   1 <page>
   2     <!-- tag sets for the first page -->
   3 </page>
   4 
   5 <page>
   6     <!-- tag sets for the second page -->
   7 </page>

<code> tag set

Deprecated do not use this 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.

Example

The following is taken from the ~/tools/new_operations/coverage.xml tool config.

   1 <code file="operation_filter.py"/>

<requirements> tag set

See ~/tools/extract/phastOdds/phastOdds_tool.xml for an example of how this tag set is used in a tool. This is a container tag set for the <requirement> tag set described below.

<requirement> tag set

This tag set is contained within within the <requirements> tag set. Third party programs or modules that the tool depends upon ( and which not distributed with Galaxy ) are included in this tag set. Before running the tool, Galaxy will check whether the required programs or modules are available on the local machine where Galaxy is set to run. If they are not available, this tool will not be loaded when the Galaxy server is started.

Example

This example shows a tool that requires a python-module named rpy which is not distributed with Galaxy.

   1 <requirements>
   2     <requirement type="python-module">rpy</requirement>
   3 </requirements>

Example

This example shows a tool that requires a python module named numpy, and a binary named taxBuilder, neither of which is distributed with Galaxy.

   1 <requirements>
   2     <requirement type="python-module">numpy</requirement>
   3     <requirement type="binary">taxBuilder</requirement>
   4 </requirements>

<help> tag set

This tag set includes all of the necessary details of how to use the tool. This tag set should be included as the last tag set 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.

Example

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.

   1 <help>
   2 
   3 .. class:: warningmark
   4 
   5 **TIP** This tool requires *fasta* format.
   6 
   7 ----
   8 
   9 **Example**
  10 
  11 Query sequence::
  12     >seq1
  13     >ATCG...
  14 
  15 .. image:: my_figure.png 
  16     :height: 500 
  17     :width: 600
  18 
  19 </help>

Miscellaneous tips and tricks

If you need to label a dataset with its real name (as displayed in the history)

<outputs>
   <data name="output" format="tabular" label="SEQLEN of ${input1.name}" />
</outputs>