Permalink
Branch: master
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
5471 lines (4909 sloc) 232 KB
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:gxdocs="http://galaxyproject.org/xml/1.0"
elementFormDefault="qualified"
attributeFormDefault="unqualified"
>
<xs:annotation>
<xs:appinfo>Galaxy Schema</xs:appinfo>
<xs:documentation xml:lang="en">A Galaxy XML tool wrapper</xs:documentation>
</xs:annotation>
<xs:element name="tool">
<xs:annotation gxdocs:best_practices="tools">
<xs:documentation xml:lang="en"><![CDATA[
The outer-most tag set of tool XML files. Attributes on this tag apply to the
tool as a whole.
### Examples
A normal tool:
```xml
<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.
```xml
<tool id="ucsc_table_direct1"
name="UCSC Main"
version="1.0.0"
hidden="false"
profile="16.01"
tool_type="data_source"
URL_method="post">
```
]]></xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:all>
<!-- TODO: Move the anyType further into macros def... -->
<xs:element name="macros" type="Macros" minOccurs="0"/>
<xs:element name="edam_topics" type="EdamTopics" minOccurs="0"/>
<xs:element name="edam_operations" type="EdamOperations" minOccurs="0"/>
<xs:element name="requirements" type="Requirements" minOccurs="0"/>
<xs:element name="description" type="xs:string" minOccurs="0">
<xs:annotation gxdocs:best_practices="tool-descriptions">
<xs:documentation xml:lang="en"><![CDATA[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
```xml
<description>table browser</description>
```
]]></xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="parallelism" type="Parallelism" minOccurs="0"/>
<xs:element name="version_command" type="VersionCommand" minOccurs="0">
</xs:element>
<xs:element name="action" type="ToolAction" minOccurs="0" maxOccurs="1" />
<xs:element name="environment_variables" type="EnvironmentVariables" minOccurs="0" maxOccurs="1"/>
<xs:element name="command" type="Command"/>
<xs:element name="request_param_translation" type="RequestParameterTranslation" minOccurs="0"/>
<xs:element name="configfiles" type="ConfigFiles" minOccurs="0"/>
<xs:element name="outputs" type="Outputs" minOccurs="0"/>
<xs:element name="inputs" type="Inputs" minOccurs="0"/>
<xs:element name="tests" type="Tests" minOccurs="0"/>
<xs:element name="stdio" type="Stdio" minOccurs="0"/>
<xs:element name="help" type="xs:string" minOccurs="0">
<xs:annotation gxdocs:best_practices="help-tag">
<xs:documentation xml:lang="en"><![CDATA[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
--- | -------
``.. class:: warningmark`` | a yellow warning symbol
``.. class:: infomark`` | a blue information symbol
``.. image:: path-of-the-file.png :height: 500 :width: 600`` | insert a png file of height 500 and width 600 at this position |
``**bold**`` | bold
``*italic*`` | italic
``*`` | list
``-`` | list
``::`` | paragraph
``-----`` | a horizontal 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.
```xml
<help>
.. class:: warningmark
'''TIP''' This tool requires *fasta* format.
----
'''Example'''
Query sequence::
>seq1
ATCG...
.. image:: my_figure.png
:height: 500
:width: 600
</help>
```
]]></xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="code" type="Code" minOccurs="0"/>
<xs:element name="uihints" type="UIhints" minOccurs="0"/>
<xs:element name="options" type="Options" minOccurs="0"/>
<xs:element name="trackster_conf" type="TracksterConf" minOccurs="0"/>
<xs:element name="citations" type="Citations" minOccurs="0"/>
</xs:all>
<xs:attribute name="id" type="xs:string" use="required">
<xs:annotation gxdocs:best_practices="tool-ids">
<xs:documentation xml:lang="en">Must be unique across all tools;
should be lowercase and contain only letters, numbers, and underscores.
It allows for tool versioning and metrics of the number of times a tool is used,
among other things.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="name" type="xs:string" use="required">
<xs:annotation gxdocs:best_practices="tool-names">
<xs:documentation xml:lang="en">This string is what is displayed as a
hyperlink in the tool menu.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="version" type="xs:string" default="1.0.0">
<xs:annotation gxdocs:best_practices="tool-versions">
<xs:documentation xml:lang="en">This string allows for tool versioning
and should be increased with each new version of the tool. The value should
follow the [PEP 440](https://www.python.org/dev/peps/pep-0440/) specification.
It defaults to ``1.0.0`` if it is not included in the tag.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="hidden" type="PermissiveBoolean" default="false">
<xs:annotation>
<xs:documentation xml:lang="en">Allows for tools to be loaded upon
server startup, but not displayed in the tool menu. This attribute should be
applied in the toolbox configuration instead and so should be considered
deprecated.
</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="display_interface" type="PermissiveBoolean">
<xs:annotation>
<xs:documentation xml:lang="en">Disable the display the tool's
graphical tool form by setting this to ``false``.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="tool_type" type="ToolTypeType">
<xs:annotation>
<xs:documentation xml:lang="en">Allows for certain framework
functionality to be performed on certain types of tools. Normal tools that execute
typical command-line jobs do not need to specify this, special kinds of tools such
as [Data Source](https://galaxyproject.org/admin/internals/data-sources/) and
[Data Manager](https://galaxyproject.org/admin/tools/data-managers/) tools should
set this to have values such as ``data_source`` or ``manage_data``.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="profile" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en">This string specified the minimum Galaxy
version that should be required to run this tool. Certain legacy behaviors such
as using standard error content to detect errors instead of exit code are disabled
automatically if profile is set to any version newer than ``16.01``, such as
``16.04``.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="workflow_compatible" type="xs:boolean" default="true">
<xs:annotation>
<xs:documentation xml:lang="en">This attribute indicates if
this tool is usable within a workflow (defaults to ``true`` for normal tools and
``false`` for data sources).</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="URL_method" type="URLmethodType">
<xs:annotation>
<xs:documentation xml:lang="en">Only used if ``tool_type`` attribute value
is ``data_source`` - this attribute defines the HTTP request method to use when
communicating with an external data source application (the default is ``get``).</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:complexType>
</xs:element>
<xs:complexType name="Macros">
<xs:annotation>
<xs:documentation xml:lang="en">Frequently, tools may require the same XML
fragments be repeated in a file (for instance similar conditional branches,
repeated options, etc...) or among tools in the same repository. Galaxy tools
have a macro system to address this problem.
For more information, see https://planemo.readthedocs.io/en/latest/writing_advanced.html#macros-reusable-elements</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="import" type="xs:string" minOccurs="0" maxOccurs="unbounded"/>
<xs:element name="token" type="xs:anyType" minOccurs="0" maxOccurs="unbounded"/>
<xs:element name="xml" type="xs:anyType" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="ToolAction">
<xs:annotation>
<xs:documentation xml:lang="en">Describe the backend Python action to execute for this Galaxy tool.</xs:documentation>
</xs:annotation>
<xs:sequence>
</xs:sequence>
<xs:attribute name="module" type="xs:string" use="required">
</xs:attribute>
<xs:attribute name="class" type="xs:string" use="required">
</xs:attribute>
</xs:complexType>
<xs:complexType name="Requirements">
<xs:annotation>
<xs:documentation xml:lang="en"><![CDATA[
This is a container tag set for the ``requirement`` and ``container`` tags
described in greater detail below. ``requirement``s describe software packages
and other individual computing requirements required to execute a tool, while
``container``s describe Docker containers that should be able to serve as
complete descriptions of the runtime of a tool.
]]></xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="requirement" type="Requirement" minOccurs="0" maxOccurs="unbounded"/>
<xs:element name="container" type="Container" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="Requirement">
<xs:annotation>
<xs:documentation xml:lang="en"><![CDATA[
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). ``requirement``s are meant to be abstract and resolvable by
multiple different systems (e.g. [conda](https://conda.io/), the
[Galaxy Tool Shed dependency management system](https://galaxyproject.org/toolshed/tool-features/#Automatic_third-party_tool_dependency_installation_and_compilation_with_installed_repositories),
or [environment modules](http://modules.sourceforge.net/)).
Read more about dependency resolvers in Galaxy on
[docs.galaxyproject.org](https://docs.galaxyproject.org/en/master/admin/dependency_resolvers.html).
The current best practice for tool dependencies is to target Conda, this is
discussed in greater detail
[here](https://docs.galaxyproject.org/en/master/admin/conda_faq.html).
### 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](https://galaxyproject.org/toolshed/tool-features/#Automatic_third-party_tool_dependency_installation_and_compilation_with_installed_repositories)
) as well as [Conda](https://docs.galaxyproject.org/en/master/admin/conda_faq.html)
and can be configured locally to adapt to any other package management system.
```xml
<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.
```xml
<requirements>
<requirement type="set_environment">R_SCRIPT_PATH</requirement>
<requirement type="package" version="2.15.1">R</requirement>
</requirements>
```
]]></xs:documentation>
</xs:annotation>
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="type" type="RequirementType" use="required">
<xs:annotation>
<xs:documentation xml:lang="en">This value defines the type of the 3rd party module required by this tool.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="version" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en">For requirements of type ``package`` this value defines a specific version of the tool dependency.</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
<xs:complexType name="Container">
<xs:annotation>
<xs:documentation xml:lang="en"><![CDATA[
This tag set is contained within the 'requirements' tag set. Galaxy can be
configured to run tools within [Docker](https://www.docker.com/) 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](https://galaxyproject.org/admin/tools/docker/).
]]></xs:documentation>
</xs:annotation>
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="type" type="ContainerType" use="required">
<xs:annotation>
<xs:documentation xml:lang="en">This value describes the type of container that the tool may be executed in and currently must be ``docker``.</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
<xs:complexType name="Parallelism">
<xs:annotation>
<xs:documentation xml:lang="en">Documentation for Parallelism</xs:documentation>
</xs:annotation>
<xs:attribute name="method" type="MethodType">
<xs:annotation>
<xs:documentation xml:lang="en">Documentation for method</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="merge_outputs" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en">Documentation for merge_outputs</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="split_inputs" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en">A comma-separated list of data inputs to split for job parallelization.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="split_size" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en">Documentation for split_size</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="split_mode" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en">Documentation for split_mode</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="shared_inputs" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en">A comma-separated list of data inputs that should not be split for this tool, Galaxy will infer this if not present and so this potentially never needs to be set.</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:complexType>
<xs:complexType name="Code">
<xs:annotation>
<xs:documentation xml:lang="en"><![CDATA[
*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](https://github.com/galaxyproject/galaxy/blob/dev/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.
```python
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.
```xml
<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.
```xml
<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.
```xml
<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.
```xml
<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.
```python
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:
```python
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:
```python
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:
```python
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``:
```python
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.
]]></xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="hook" type="CodeHook" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="file" type="xs:string" use="required">
<xs:annotation>
<xs:documentation xml:lang="en">This value is the name of the executable code file, and is called in the ``exec_before_process()``, ``exec_before_job()``, ``exec_after_process()`` and ``exec_after_job()`` methods.</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:complexType>
<xs:complexType name="CodeHook">
<xs:annotation>
<xs:documentation xml:lang="en">*Deprecated*. Map a hook to a function defined in the code file.</xs:documentation>
</xs:annotation>
<xs:attribute name="exec_after_process" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en">Function defined in the code file to which the ``exec_after_process`` hook should be mapped</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:complexType>
<xs:complexType name="UIhints">
<xs:annotation>
<xs:documentation xml:lang="en">Used only for data source tools, this directive contains UI options (currently only ``minwidth`` is valid).</xs:documentation>
</xs:annotation>
<xs:attribute name="minwidth" type="xs:integer">
<xs:annotation>
<xs:documentation xml:lang="en">Documentation for minwidth</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:complexType>
<xs:complexType name="Options">
<xs:annotation>
<xs:documentation xml:lang="en">This directive is used to specify some rarely modified options.</xs:documentation>
</xs:annotation>
<xs:attribute name="refresh" type="PermissiveBoolean" gxdocs:deprecated="true">
<xs:annotation>
<xs:documentation xml:lang="en">*Deprecated*. Unused attribute.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="sanitize" type="PermissiveBoolean" default="true">
<xs:annotation>
<xs:documentation xml:lang="en">This attribute can be used to turn off all input sanitization for a tool.</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:complexType>
<xs:complexType name="TracksterConf">
<xs:annotation>
<xs:documentation xml:lang="en">This directive is used to specify some rarely modified trackster options.</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="action" type="TracksterAction" minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="TracksterAction">
<xs:annotation>
<xs:documentation xml:lang="en"></xs:documentation>
</xs:annotation>
<xs:attribute name="name" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en"></xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="output_name" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en"></xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:complexType>
<xs:complexType name="Tests">
<xs:annotation gxdocs:best_practices="tests">
<xs:documentation xml:lang="en"><![CDATA[
Container tag set to specify tests via the ``<test>`` tag sets. Any number of tests can be included,
and each test is wrapped within separate ``<test>`` tag sets. Functional tests are
executed via [Planemo](https://planemo.readthedocs.io/) or the
[run_tests.sh](https://github.com/galaxyproject/galaxy/blob/dev/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](https://planemo.readthedocs.io/en/latest/writing_advanced.html#test-driven-development)
documentation or the much older wiki content for
[WritingTests](https://galaxyproject.org/admin/tools/writing-tests/).
]]></xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="test" type="Test" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="Test">
<xs:annotation>
<xs:documentation xml:lang="en"><![CDATA[
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](https://github.com/galaxyproject/galaxy/blob/dev/tools/filters/sorter.xml)
tool. Notice the way that the tool's inputs and outputs are defined.
```xml
<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](https://github.com/galaxyproject/galaxy/blob/master/tools/maf/maf_to_fasta.xml)).
```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.
```xml
<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>
```
]]></xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:group ref="TestParamElement" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="expect_exit_code" type="xs:integer">
<xs:annotation>
<xs:documentation xml:lang="en">Describe the job's expected exit code.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="expect_num_outputs" type="xs:integer">
<xs:annotation>
<xs:documentation xml:lang="en">Assert the number of outputs this test
should produce, this is useful to ensure ``filter`` directives are implemented correctly.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="expect_failure" type="PermissiveBoolean" default="false">
<xs:annotation>
<xs:documentation xml:lang="en">Setting this to ``true`` indicates
the expectation is for the job fail. If set to ``true`` no job output checks may
be present in ``test`` definition.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="maxseconds" type="xs:integer">
<xs:annotation>
<xs:documentation xml:lang="en">Maximum amount of time to let test run.</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:complexType>
<xs:group name="TestParamElement">
<xs:choice>
<xs:element name="param" type="TestParam" />
<xs:element name="repeat" type="TestRepeat" />
<xs:element name="conditional" type="TestConditional" />
<xs:element name="section" type="TestSection" />
<xs:element name="output" type="TestOutput" minOccurs="0" maxOccurs="unbounded"/>
<xs:element name="output_collection" type="TestOutputCollection"/>
<xs:element name="assert_command" type="TestAssertions">
<xs:annotation>
<xs:documentation xml:lang="en">Describe assertions about the job's
generated command-line.
$assertions
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="assert_stdout" type="TestAssertions">
<xs:annotation>
<xs:documentation xml:lang="en">Describe assertions about the job's
standard output.
$assertions
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="assert_stderr" type="TestAssertions">
<xs:annotation>
<xs:documentation xml:lang="en">Describe assertions about the job's
standard error.
$assertions
</xs:documentation>
</xs:annotation>
</xs:element>
</xs:choice>
</xs:group>
<xs:complexType name="TestSection">
<xs:annotation>
<xs:documentation xml:lang="en"><![CDATA[
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](https://github.com/galaxyproject/galaxy/blob/dev/test/functional/tools/section.xml))
contains a test case demonstrating this block. This test case appears below:
```xml
<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>
```
]]>
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:group ref="TestParamElement" minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
<xs:attribute name="name" type="xs:string" use="required">
<xs:annotation>
<xs:documentation xml:lang="en">This value must match the name of the
associated input ``section``.</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:complexType>
<xs:complexType name="TestConditional">
<xs:annotation>
<xs:documentation xml:lang="en"><![CDATA[
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 ``conditional``s in the ``inputs``
definition of the [disambiguate_cond.xml](https://github.com/galaxyproject/galaxy/blob/dev/test/functional/tools/disambiguate_cond.xml)
tool.
```xml
<!-- 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](https://github.com/galaxyproject/tools-devteam/blob/master/tools/tophat2/tophat2_wrapper.xml)
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.
```xml
<!-- 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>
```
]]></xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:group ref="TestParamElement" minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
<xs:attribute name="name" type="xs:string" use="required">
<xs:annotation>
<xs:documentation xml:lang="en">This value must match the name of the
associated input ``conditional``.</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:complexType>
<xs:complexType name="TestRepeat">
<xs:annotation>
<xs:documentation xml:lang="en"><![CDATA[
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](https://github.com/galaxyproject/galaxy/blob/dev/test/functional/tools/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.
```xml
<!-- 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.
```xml
<!-- 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>
```
]]></xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:group ref="TestParamElement" minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
<xs:attribute name="name" type="xs:string" use="required">
<xs:annotation>
<xs:documentation xml:lang="en">This value must match the name of the
associated input ``repeat``.</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:complexType>
<xs:complexType name="TestParam">
<xs:annotation>
<xs:documentation xml:lang="en"><![CDATA[
This tag set defines the tool's input parameters for executing the tool via the
functional test framework. See [test](#tool-tests-test) documentation for
some simple examples of parameters.
]]></xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="collection" type="TestCollection" minOccurs="0" maxOccurs="1" />
<xs:element name="composite_data" type="TestCompositeData" minOccurs="0" maxOccurs="unbounded" />
<xs:element name="metadata" type="TestParamMetadata" minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
<xs:attribute name="name" type="xs:string" use="required">
<xs:annotation>
<xs:documentation xml:lang="en">This value must match the name of the
associated input parameter (``param``).</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="value" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en">This value must be one of the legal
values that can be assigned to an input parameter.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="ftype" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en">This attribute name should be included
only with parameters of ``type`` ``data`` for the tool. If this
attribute name is not included, the functional test framework will attempt to
determine the data type for the input dataset using the data type sniffers.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="dbkey" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en">Specifies a ``dbkey`` value for the
referenced input dataset. This is only valid if the corresponding parameter is
of ``type`` ``data``.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="tags" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en">Comma separated list of tags to apply to the dataset (only works for elements of collections - e.g. ``element`` XML tags).</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:complexType>
<xs:complexType name="TestCompositeData">
<xs:annotation>
<xs:documentation xml:lang="en">Define extra composite input files for test
input. The specified ``ftype`` on the parent ``param`` should specify a composite
datatype with defined static composite files. The order of the defined composite
files on the datatype must match the order specified with these elements and All
non-optional composite inputs must be specified as part of the ``param``.
</xs:documentation>
</xs:annotation>
<xs:attribute name="value" type="xs:string" use="required">
<xs:annotation>
<xs:documentation xml:lang="en">Path relative to test-data of composite file.</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:complexType>
<xs:complexType name="TestCollection">
<xs:annotation>
<xs:documentation xml:lang="en">Definition of a collection for test input.</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="element" type="TestParam" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="type" type="xs:string" use="required">
<xs:annotation>
<xs:documentation xml:lang="en">Type of collection to create.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="tags" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en">Comma separated list of tags to apply to the dataset (only works for elements of collections - e.g. ``element`` XML tags).</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:complexType>
<xs:complexType name="TestOutput">
<xs:annotation>
<xs:documentation xml:lang="en"><![CDATA[
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.
]]></xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:group ref="TestOutputElement" minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
<!-- TODO: This would be more percise if this was required if at the top-level. -->
<xs:attribute name="name" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en"><![CDATA[
This value is the same as the value of the ``name`` attribute of the ``<data>``
tag set contained within the tool's ``<outputs>`` tag set.
]]></xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="file" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en"><![CDATA[
If specified, this value is the name of the output file stored in the target
``test-data`` directory which will be used to compare the results of executing
the tool via the functional test framework.
]]></xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="ftype" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en"><![CDATA[
If specified, this value will be checked against the corresponding output's
data type. If these do not match, the test will fail.
]]></xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="sort" type="PermissiveBoolean">
<xs:annotation>
<xs:documentation xml:lang="en">This flag causes the lines of the output
to be sorted before they are compared to the expected output. This could be
useful for non-deterministic output.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="value" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en">An alias for ``file``.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="md5" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en"><![CDATA[
If specified, the target output's MD5 hash should match the value specified
here. For large static files it may be inconvenient to upload the entiry file
and this can be used instead.
]]></xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="checksum" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en"><![CDATA[
If specified, the target output's checksum should match the value specified
here. This value should have the form ``hash_type:hash_value``
(e.g. ``sha1:8156d7ca0f46ed7abac98f82e36cfaddb2aca041``). For large static files
it may be inconvenient to upload the entiry file and this can be used instead.
]]></xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="compare" type="TestOutputCompareType">
</xs:attribute>
<xs:attribute name="lines_diff" type="xs:integer">
<xs:annotation>
<xs:documentation xml:lang="en">If ``compare`` is set to ``diff``, the number of lines of difference to allow (each line with a modification is a line added and a line removed so this counts as two lines).</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="decompress" type="PermissiveBoolean">
<xs:annotation>
<xs:documentation xml:lang="en"><![CDATA[
If ``compare`` is set to ``diff``, attempt to decompress both produced output and expected output files if needed before performing the diff. This flag is useful for testing gzipped outputs that are non-deterministic despite having deterministic decompressed contents. This is available in Galaxy 17.05+ and was introduced in [pull request #3550](https://github.com/galaxyproject/galaxy/pull/3550).
]]></xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="delta" type="xs:integer">
<xs:annotation>
<xs:documentation xml:lang="en">If ``compare`` is set to ``sim_size``, this is the number of bytes different allowed.</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:complexType>
<xs:group name="TestOutputElement">
<xs:choice>
<xs:element name="element" type="TestOutput"/>
<!-- TODO: This would be more percise if this was only allowed at the top-level. -->
<xs:element name="discovered_dataset" type="TestDiscoveredDataset"/>
<!-- TODO: To be more percise only one assert_contents is allowed - this should not be in here. -->
<xs:element name="assert_contents" type="TestAssertions">
<xs:annotation>
<xs:documentation><![CDATA[
$assertions
### Examples
The following demonstrtes a wide variety of text-based and tabular
assertion statements.
```xml
<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.
```xml
<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.
```xml
<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>
```
]]></xs:documentation>
</xs:annotation>
</xs:element>
<!-- TODO: This would be more percise if this was only allowed at the top-level. -->
<xs:element name="extra_files" type="TestExtraFile" />
<xs:element name="metadata" type="TestOutputMetadata"/>
</xs:choice>
</xs:group>
<xs:complexType name="TestParamMetadata">
<xs:attribute name="name" type="xs:string" use="required">
<xs:annotation>
<xs:documentation xml:lang="en">Documentation for name</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="value" type="xs:string" use="required">
<xs:annotation>
<xs:documentation xml:lang="en">Documentation for value</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:complexType>
<xs:complexType name="TestOutputMetadata">
<xs:annotation>
<xs:documentation xml:lang="en"><![CDATA[
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](https://github.com/galaxyproject/galaxy/blob/dev/test/functional/tools/tool_provided_metadata_1.xml)
provides a demonstration of using this tag.
```xml
<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>
```
]]></xs:documentation>
</xs:annotation>
<xs:attribute name="name" type="xs:string" use="required">
<xs:annotation>
<xs:documentation xml:lang="en">Name of the metadata element to check.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="value" type="xs:string" use="required">
<xs:annotation>
<xs:documentation xml:lang="en">Expected value (as a string) of metadata value.</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:complexType>
<xs:complexType name="TestDiscoveredDataset">
<xs:annotation>
<xs:documentation><![CDATA[
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](https://github.com/galaxyproject/galaxy/blob/dev/test/functional/tools/multi_output_assign_primary.xml)
provides a demonstration of using this tag.
```xml
<outputs>
<data format="tabular" name="sample">
<discover_datasets pattern="(?P&lt;designation&gt;.+)\.report\.tsv" ext="tabular" visible="true" assign_primary_output="true" />
</data>
</outputs>
<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>
```
Note that this tool uses ``assign_primary_output="true"`` for ``<discover_data_sets>``. Hence, the content of the first discovered dataset (which is the first in the alphabetically sorted list of discovered designations) is checked directly in the ``<output>`` tag of the test.
]]></xs:documentation>
</xs:annotation>
<xs:complexContent>
<xs:extension base="TestOutput">
<xs:attribute type="xs:string" name="designation">
<xs:annotation>
<xs:documentation xml:lang="en">The designation of the discovered dataset.</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name="TestExtraFile">
<xs:annotation>
<xs:documentation xml:lang="en">Define test for extra files on corresponding output.</xs:documentation>
</xs:annotation>
<xs:complexContent>
<xs:extension base="TestOutput">
<xs:attribute type="xs:string" name="type">
<xs:annotation>
<xs:documentation xml:lang="en">Extra file type (either ``file`` or ``directory``).</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name="TestOutputCollection">
<xs:annotation>
<xs:documentation xml:lang="en"><![CDATA[
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 collection contents are described using child ``element``
directives. For nested collections, these child ``element`` directives may
themselves contain children.
### Examples
The [genetrack](https://github.com/galaxyproject/tools-iuc/blob/master/tools/genetrack/genetrack.xml)
tool demonstrates basic usage of an ``output_collection`` test expectation.
```xml
<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](https://github.com/galaxyproject/tools-iuc/blob/master/tools/cwpair2/cwpair2.xml)
tool demonstrates that ``element``s can specify a ``compare`` attribute just
like [output](#tool-tests-test-output).
```xml
<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](https://github.com/galaxyproject/galaxy/blob/dev/test/functional/tools/collection_creates_dynamic_nested.xml)
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](#tool-tests-test-output) (e.g. ``md5``, ``compare``, ``diff``,
etc...).
```xml
<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>
```
]]></xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="element" type="TestOutput" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="name" type="xs:string" use="required">
<xs:annotation>
<xs:documentation xml:lang="en"><![CDATA[
This value is the same as the value of the ``name`` attribute of the
``<collection>`` tag set contained within the tool's ``<outputs>`` tag set.
]]></xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="type" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en">Expected collection type (e.g. ``list``, ``paired``,
or ``list:paired``).</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="count" type="xs:integer">
<xs:annotation>
<xs:documentation xml:lang="en">Number of elements in output collection.</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:complexType>
<xs:complexType name="TestAssertions">
<xs:annotation>
<xs:documentation><![CDATA[
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
[/lib/galaxy/tools/verify/asserts](https://github.com/galaxyproject/galaxy/tree/dev/lib/galaxy/tools/verify/asserts)
module.
]]>
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:group ref="TestAssertion" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:group name="TestAssertion">
<xs:choice>
<xs:element name="has_text" type="xs:anyType">
<xs:annotation>
<xs:documentation><![CDATA[Asserts the specified ``text`` appears in the output (e.g. ``<has_text text="chr7">``).]]>
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="not_has_text" type="xs:anyType">
<xs:annotation>
<xs:documentation><![CDATA[Asserts the specified ``text`` does not appear in the output (e.g. ``<not_has_text text="chr8" />``).]]>
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="has_text_matching" type="xs:anyType">
<xs:annotation>
<xs:documentation><![CDATA[Asserts text matching the specified regular expression (``expression``) appears in the output (e.g. ``<has_text_matching expression="1274\d+53" />`` ).]]>
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="has_line" type="xs:anyType">
<xs:annotation>
<xs:documentation><![CDATA[Asserts a line matching the specified string (``line``) appears in the output (e.g. ``<has_line line="A full example line." />``).]]>
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="has_line_matching" type="xs:anyType">
<xs:annotation>
<xs:documentation><![CDATA[Asserts a line matching the specified regular expression (``expression``) appears in the output (e.g. ``<has_line_matching expression=".*\s+127489808\s+127494553" />``).]]>
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="has_n_columns" type="xs:anyType">
<xs:annotation>
<xs:documentation><![CDATA[Asserts tabular output contains the specified number (``n``) of columns (e.g. ``<has_n_columns n="3" />``).]]>
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="is_valid_xml" type="xs:anyType">
<xs:annotation>
<xs:documentation><![CDATA[Asserts the output is a valid XML file (e.g. ``<is_valid_xml />``).]]>
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="has_element_with_path" type="xs:anyType">
<xs:annotation>
<xs:documentation><![CDATA[Asserts the XML output contains at least one element (or tag) with the specified XPath-like ``path`` (e.g. ``<has_element_with_path path="BlastOutput_param/Parameters/Parameters_matrix" />``).]]>
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="has_n_elements_with_path" type="xs:anyType">
<xs:annotation>
<xs:documentation><![CDATA[Asserts the XML output contains the specified number (``n``) of elements (or tags) with the specified XPath-like ``path`` (e.g. ``<has_n_elements_with_path n="9" path="BlastOutput_iterations/Iteration/Iteration_hits/Hit/Hit_num" />``).]]>
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="element_text_is" type="xs:anyType">
<xs:annotation>
<xs:documentation><![CDATA[Asserts the text of the XML element with the specified XPath-like ``path`` is the specified ``text`` (e.g. ``<element_text_is path="BlastOutput_program" text="blastp" />``).]]>
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="element_text_matches">
<xs:annotation>
<xs:documentation><![CDATA[Asserts the text of the XML element with the specified XPath-like ``path`` matches the regular expression defined by ``expression`` (e.g. ``<element_text_matches path="BlastOutput_version" expression="BLASTP\s+2\.2.*" />``).]]>
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="attribute_is" type="xs:anyType">
<xs:annotation>
<xs:documentation><![CDATA[Asserts the XML ``attribute`` for the element (or tag) with the specified XPath-like ``path`` is the specified ``text`` (e.g. ``<attribute_is path="outerElement/innerElement1" attribute="foo" text="bar" />`` ).]]>
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="attribute_matches" type="xs:anyType">
<xs:annotation>
<xs:documentation><![CDATA[Asserts the XML ``attribute`` for the element (or tag) with the specified XPath-like ``path`` matches the regular expression specified by ``expression`` (e.g. ``<attribute_matches path="outerElement/innerElement2" attribute="foo2" expression="bar\d+" />``).]]></xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="element_text" type="xs:anyType">
<xs:annotation>
<xs:documentation><![CDATA[This tag allows the developer to recurisively specify additional assertions as child elements about just the text contained in the element specified by the XPath-like ``path`` (e.g. ``<element_text path="BlastOutput_iterations/Iteration/Iteration_hits/Hit/Hit_def"><not_has_text text="EDK72998.1" /></element_text>``).]]></xs:documentation>
</xs:annotation>
</xs:element>
</xs:choice>
</xs:group>
<xs:complexType name="Inputs">
<xs:annotation>
<xs:documentation xml:lang="en"><![CDATA[Consists of all elements that define the
tool's input parameters. Each [param](#tool-inputs-param) element contained in this element
can be used as a command line parameter within the [command](#tool-command) text content. Most
tools will not need to specify any attributes on this tag itself.]]>
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:group ref="InputElement" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="action" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en">URL used by data source tools.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="check_values" type="PermissiveBoolean" default="true">
<xs:annotation>
<xs:documentation xml:lang="en">Set to ``false`` to disable parameter checking in data source tools.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="method" type="URLmethodType">
<xs:annotation>
<xs:documentation xml:lang="en">Data source HTTP action (e.g. ``get`` or ``put``) to use.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="target" type="TargetType">
<xs:annotation>
<xs:documentation xml:lang="en">UI link target to use for data source tools (e.g. ``_top``).</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="nginx_upload" type="PermissiveBoolean" default="false">
<xs:annotation>
<xs:documentation xml:lang="en">This boolean indicates if this is an upload tool or not.</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:complexType>
<xs:group name="InputElement">
<xs:choice>
<xs:element name="param" type="Param"/>
<xs:element name="repeat" type="Repeat"/>
<xs:element name="conditional" type="Conditional"/>
<xs:element name="section" type="Section"/>
<xs:element name="upload_dataset" type="xs:anyType">
<xs:annotation>
<xs:documentation xml:lang="en">Internal, intentionally undocumented feature.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="display" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en">Documentation for display</xs:documentation>
</xs:annotation>
</xs:element>
</xs:choice>
</xs:group>
<xs:complexType name="InputType" abstract="true">
<xs:annotation>
<xs:documentation xml:lang="en">Documentation for InputType</xs:documentation>
</xs:annotation>
<xs:sequence/>
</xs:complexType>
<xs:complexType name="Conditional">
<xs:annotation>
<xs:documentation xml:lang="en"><![CDATA[
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](https://github.com/galaxyproject/tools-iuc/blob/master/tools/biom_format/biom_convert.xml).
```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](#tool-inputs-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](https://galaxyproject.org/admin/tools/data-managers/)
) and
history files. A good example tool that demonstrates this is
the [Bowtie 2](https://github.com/galaxyproject/tools-iuc/blob/master/tools/bowtie2/bowtie2_wrapper.xml) wrapper.
```xml
<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.
]]></xs:documentation>
</xs:annotation>
<xs:complexContent>
<xs:extension base="InputType">
<xs:sequence>
<xs:group ref="InputElement" minOccurs="0" maxOccurs="1" />
<xs:element name="when" type="ConditionalWhen" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="name" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en">Name for this element</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="value_from" type="xs:string">
<xs:annotation>
<xs:documentation><![CDATA[Infrequently used option to dynamically access Galaxy internals, this should be avoided.
Galaxy method to execute.]]></xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="value_ref" type="xs:string">
<xs:annotation>
<xs:documentation><![CDATA[Infrequently used option to dynamically access Galaxy internals, this should be avoided.
Referenced parameter to pass method.]]></xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="value_ref_in_group" type="PermissiveBoolean">
<xs:annotation>
<xs:documentation><![CDATA[Infrequently used option to dynamically access Galaxy internals, this should be avoided.
Is referenced parameter is the same group.]]></xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="label" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en">Human readable description for the conditional, unused in the Galaxy UI currently.</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name="ConditionalWhen">
<xs:annotation>
<xs:documentation xml:lang="en">This directive describes one potential
set of input for the tool at this depth. See documentation for the
[conditional](#tool-inputs-conditional) block for more details and examples (XML
and corresponding Cheetah conditionals).</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:group ref="InputElement" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="value" type="xs:string" use="required">
<xs:annotation>
<xs:documentation xml:lang="en">Value for the tool form test parameter
corresponding to this ``when`` block.</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:complexType>
<xs:complexType name="Repeat">
<xs:annotation>
<xs:documentation xml:lang="en"><![CDATA[
See
[xy_plot.xml](https://github.com/galaxyproject/tools-devteam/blob/master/tools/xy_plot/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.
```xml
<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.
```xml
<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](#tool-tests-test-repeat).
An older way to specify repeats in a test is by instances that are created by referring to names with a special format: ``<repeat name>_<repeat index>|<param name>``
```xml
<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](https://github.com/galaxyproject/galaxy/blob/dev/test/functional/tools/disambiguate_repeats.xml)
demonstrates both testing strategies.
]]></xs:documentation>
</xs:annotation>
<xs:complexContent>
<xs:extension base="InputType">
<xs:sequence>
<xs:group ref="InputElement" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="name" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en">Name for this element</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="title" type="xs:string" use="required">
<xs:annotation>
<xs:documentation xml:lang="en">The title of the repeat section, which will be displayed on the tool form.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="min" type="xs:integer">
<xs:annotation>
<xs:documentation xml:lang="en">The minimum number of repeat units.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="max" type="xs:integer">
<xs:annotation>
<xs:documentation xml:lang="en">The maximum number of repeat units.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="default" type="xs:integer" default="1">
<xs:annotation>
<xs:documentation xml:lang="en">The default number of repeat units.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="help" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en">Short help description for repeat element.</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name="Section">
<xs:annotation>
<xs:documentation xml:lang="en"><![CDATA[
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:
```xml
<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](https://github.com/galaxyproject/galaxy/blob/master/test/functional/tools/section.xml) from [pull request #35](https://github.com/galaxyproject/galaxy/pull/35).
]]></xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:group ref="InputElement" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="name" type="xs:string" use="required">
<xs:annotation>
<xs:documentation xml:lang="en">The internal key used for the section.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="title" type="xs:string" use="required">
<xs:annotation>
<xs:documentation xml:lang="en">Human readable label for the section.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="expanded" type="PermissiveBoolean" default="false">
<xs:annotation>
<xs:documentation xml:lang="en">Whether the section should be expanded by default or not. If not, the default set values are used.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="help" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en">Short help description for section, rendered just below the section.</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:complexType>
<xs:complexType name="Param">
<xs:annotation>
<xs:documentation xml:lang="en"><![CDATA[
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:
$attribute_list:name,type,optional,label,help,argument,refresh_on_change:4
### 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".
```xml
<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.
```xml
<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.
```xml
<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](https://github.com/galaxyproject/galaxy/blob/dev/test/functional/tools/param_text_option.xml)
for a demonstration of this.
$attribute_list:value,size,area:5
#### ``integer`` and ``float``
These parameters represent whole number and real numbers, respectively.
##### Example
```xml
<param name="region_size" size="4" type="integer" value="1" label="flanking regions of size" />
```
$attribute_list:value,min,max:5
#### ``boolean``
This represents a binary true or false value.
$attribute_list:checked,truevalue,falsevalue:5
#### ``data``
A dataset from the current history. Multiple types might be used for the param form.
#### ``group_tag``
$attribute_list:multiple,date_ref:5
##### 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.
```xml
<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.
```xml
<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:
- [multi_data_param.xml](https://github.com/galaxyproject/galaxy/blob/dev/test/functional/tools/multi_data_param.xml)
- [multi_data_optional.xml](https://github.com/galaxyproject/galaxy/blob/dev/test/functional/tools/multi_data_optional.xml)
Additionally, a detailed discussion of handling multiple homogenous files can be found in the
the [Planemo Documentation](https://planemo.readthedocs.io/en/latest/writing_advanced.html#consuming-collections)
on this topic.
$attribute_list:format,multiple:5
#### ``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.
```xml
<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 "".
```xml
<param name="upstream_or_down" type="select" label="Get" multiple="true" display="checkboxes">
<option value="u">Upstream</option>
<option value="d">Downstream</option>
</param>
```
$attribute_list:data_ref,dynamic_options,display,multiple:5
#### ``data_column``
This parameter type is used to select columns from a parameter.
$attribute_list:force_select,numerical,use_header_name:5
#### ``drill_down``
$attribute_list:hierarchy:5
#### ``data_collection``
The following will create a parameter that only accepts paired FASTQ files grouped into a collection.
##### Examples
```xml
<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](https://planemo.readthedocs.io/en/latest/writing_advanced.html#collections).
$attribute_list:format,collection_type:5
#### ``color``
##### Examples
The following example will create a color selector parameter.
```xml
<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.
```xml
<param name="feature_color" type="color" label="Default feature color" value="#ff00ff">
<sanitizer>
<valid initial="string.ascii_letters,string.digits">
<add value="#" />
</valid>
</sanitizer>
</param>
```
$attribute_list:value,rgb:5
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.
]]></xs:documentation>
</xs:annotation>
<xs:complexContent>
<xs:extension base="InputType">
<xs:sequence>
<xs:group ref="ParamElement" minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
<xs:attribute name="type" type="ParamType" use="required">
<xs:annotation>
<xs:documentation xml:lang="en"><![CDATA[
Describes the parameter type - each different type as different semantics and
the tool form widget is different. Currently valid parameter types are:
``text``, ``integer``, ``float``, ``boolean``, ``genomebuild``, ``select``,
``color``, ``data_column``, ``hidden``, ``hidden_data``, ``baseurl``,
``file``, ``ftpfile``, ``data``, ``data_collection``, ``library_data``,
``drill_down``. The definition of supported parameter types as defined in the
``parameter_types`` dictionary in
[/lib/galaxy/tools/parameters/basic.py](https://github.com/galaxyproject/galaxy/blob/master/lib/galaxy/tools/parameters/basic.py).
]]></xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="name" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en"><![CDATA[Name for this element. This ``name``
is used as the Cheetah variable containing the user-supplied parameter name in
``command`` and ``configfile`` elements. The name should not contain pipes or
periods (e.g. ``.``). Some "reserved" names are ``REDIRECT_URL``,
``DATA_URL``, ``GALAXY_URL``.]]></xs:documentation>
</xs:annotation>
</xs:attribute>
<!-- TODO: add unique constraints... -->
<xs:attribute name="area" type="PermissiveBoolean">
<xs:annotation>
<xs:documentation xml:lang="en">Boolean indicating if this should be
rendered as a one line text box (if ``false``) or a multi-line text area (if
``true``).</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="argument" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en"><![CDATA[
If the parameter reflects just one command line argument of a certain tool, this
tag should be set to that particular argument. It is rendered in parenthesis
after the help section, and it will create the name attribute from the argument
attribute by stripping the dashes (e.g. if ``argument="--sensitive"`` then
``name="sensitive"`` is implicit).
]]></xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="label" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en">The attribute value will be
displayed on the tool page as the label of the form field
(``label="Sort Query"``).</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="help" type="xs:string">
<xs:annotation gxdocs:best_practices="parameter-help">
<xs:documentation xml:lang="en">Short bit of text, rendered on the
tool form just below the associated field to provide information about the
field.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="value" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en">The default value for this
parameter.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="default_value" type="xs:string" gxdocs:deprecated="true">
<xs:annotation>
<xs:documentation xml:lang="en">*Deprecated*. Specify default value for column parameters (use ``value`` instead).</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="optional" type="xs:string" default="false">
<xs:annotation>
<xs:documentation xml:lang="en">If ``false``, parameter must have a
value. Defaults to "false".</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="rgb" type="xs:string" default="false">
<xs:annotation>
<xs:documentation xml:lang="en">If ``false``, the returned value will be in Hex color code. If ``true``
it will be a RGB value e.g. 0,0,255. This attribute is only valid when ``type`` is ``color``.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="min" type="xs:float">
<xs:annotation>
<xs:documentation xml:lang="en">Minimum valid parameter value - only
valid when ``type`` is ``integer`` or ``float``.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="max" type="xs:float">
<xs:annotation>
<xs:documentation xml:lang="en">Maximum valid parameter value - only
valid when ``type`` is ``integer`` or ``float``.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="format" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en">Only if ``type`` attribute value is
``data`` or ``data_collection`` - the list of supported data formats is
contained in the
[/config/datatypes_conf.xml.sample](https://github.com/galaxyproject/galaxy/blob/dev/config/datatypes_conf.xml.sample)
file. Use the file extension.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="collection_type" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en"><![CDATA[
This is only valid if ``type`` is ``data_collection``. Restrict the kind of
collection that can be consumed by this parameter (e.g. ``paired``,
``list:paired``, ``list``). Multiple such collection types can be specified here
as a comma-separated list.
]]></xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="data_ref" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en"><![CDATA[
Only valid if ``type`` attribute value is ``select``, ``data_column``, or
``group_tag``. Used with select lists whose options are dynamically generated
based on certain metadata attributes of the dataset or collection upon which
this parameter depends (usually but not always the tool's input dataset).
]]></xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="accept_default" type="PermissiveBoolean">
<xs:annotation>
<xs:documentation xml:lang="en"></xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="refresh_on_change" type="PermissiveBoolean">
<xs:annotation>
<xs:documentation xml:lang="en">Force a reload of the tool panel when the value of this parameter changes to allow ``code`` file processing. See deprecation-like notice for ``code`` blocks.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="force_select" type="PermissiveBoolean" gxdocs:deprecated="true">
<xs:annotation>
<xs:documentation xml:lang="en">*Deprecated*. Used only if the ``type`` attribute
value is ``data_column``, this is deprecated and the inverse of ``optional``.
Set to ``false`` to not force user to select an option in the list.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="use_header_names" type="PermissiveBoolean">
<xs:annotation>
<xs:documentation xml:lang="en">Used only if the ``type`` attribute
value is ``data_column``, if ``true`` Galaxy assumes first row of ``data_ref``
is a header and builds the select list with these values rather than the more
generic ``c1`` ... ``cN``.
</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="display" type="DisplayType">
<xs:annotation>
<xs:documentation xml:lang="en">This attribute is used only if
``type`` attribute value is ``select`` - render a select list as a set of check
boxes or radio buttons. Defaults to a drop-down menu select list.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="multiple" type="PermissiveBoolean">
<xs:annotation>
<xs:documentation xml:lang="en">Allow multiple valus to be selected.
Valid with ``data`` and ``select`` parameters.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="numerical" type="PermissiveBoolean">
<xs:annotation>
<xs:documentation xml:lang="en">Used only if the ``type`` attribute
value is ``data_column``, if ``true`` the column will be treated as numerical
when filtering columns based on metadata.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="hierarchy" type="HierarchyType">
<xs:annotation>
<xs:documentation xml:lang="en">Used only if the ``type`` attribute
value is ``drill_down``, this attribute determines the drill down is
``recursive`` or ``exact``.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="checked" type="PermissiveBoolean" default="false">
<xs:annotation>
<xs:documentation xml:lang="en">Set to ``true`` if the ``boolean``
parameter should be checked (or ``true``) by default.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="truevalue" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en">The parameter value in the Cheetah
template if the parameter is ``true`` or checked by the user. Only valid if
``type`` is ``boolean``.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="falsevalue" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en">The parameter value in the Cheetah
template if the parameter is ``false`` or not checked by the user. Only valid if
``type`` is ``boolean``.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="size" type="xs:string">
<!-- TODO: can be integer or integerxinteger -->
<xs:annotation>
<xs:documentation xml:lang="en">Used only if ``type`` attribute
value is ``text``. To create a multi-line text box add an ``area="true"``
attribute to the param tag. This can be one dimensional (e.g. ``size="40"``)
or two dimensional (e.g. ``size="5x25"``).</xs:documentation>
</xs:annotation>
</xs:attribute>
<!-- metadata_name appears in some wrappers but I think this is a copy
and paste problem and doesn't reflect something actually used by
Galaxy.
-->
<!--
<xs:attribute name="metadata_name" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en">Documentation for metadata_name</xs:documentation>
</xs:annotation>
</xs:attribute>
-->
<xs:attribute name="dynamic_options" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en">Deprecated/discouraged method to
allow access to Python code to generate options for a select list. See
``code``'s documentation for an example.
</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:group name="ParamElement">
<xs:choice>
<xs:element name="label" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en">Documentation for label</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="conversion" type="ParamConversion" />
<xs:element name="option" type="ParamOption" />
<xs:element name="options" type="ParamOptions"/>
<xs:element name="validator" type="Validator" />
<xs:element name="sanitizer" type="Sanitizer"/>
<xs:element name="help" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en">Documentation for help</xs:documentation>
</xs:annotation>
</xs:element>
</xs:choice>
</xs:group>
<xs:simpleType name="ParamType">
<xs:annotation>
<xs:documentation xml:lang="en">Documentation for ParamType</xs:documentation>
</xs:annotation>
<xs:restriction base="xs:string">
<xs:enumeration value="text"/>
<xs:enumeration value="integer"/>
<xs:enumeration value="float"/>
<xs:enumeration value="color"/>
<xs:enumeration value="boolean"/>
<xs:enumeration value="genomebuild"/>
<xs:enumeration value="library_data"/>
<xs:enumeration value="select"/>
<xs:enumeration value="data_column"/>
<xs:enumeration value="hidden"/>
<xs:enumeration value="hidden_data"/>
<xs:enumeration value="baseurl"/>
<xs:enumeration value="file"/>
<xs:enumeration value="data"/>
<xs:enumeration value="drill_down"/>
<xs:enumeration value="group_tag"/>
<xs:enumeration value="data_collection"/>
</xs:restriction>
</xs:simpleType>
<xs:complexType name="Command">
<xs:annotation gxdocs:best_practices="command-tag">
<xs:documentation xml:lang="en"><![CDATA[
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](https://pythonhosted.org/Cheetah/) and finally given
to the interpreter specified in the corresponding attribute (if any).
### Examples
The following uses a compiled executable ([bedtools](https://bedtools.readthedocs.io/en/latest/)).
```xml
<command><![CDATA[
bed12ToBed6 -i '$input' > '$output'
]]]]><![CDATA[></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](https://github.com/galaxyproject/tools-iuc/blob/master/tools/bedtools/bed12ToBed6.xml).
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](https://github.com/galaxyproject/tools-iuc/blob/master/tools/bedtools/annotateBed.xml)
tool.
```xml
<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}'
]]]]><![CDATA[></command>
```
The following example (taken from [xpath](https://github.com/galaxyproject/tools-iuc/blob/master/tools/xpath/xpath.xml) 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__``.
```xml
<command><![CDATA[
perl '$__tool_directory__/xpath' -q -e '$expression' '$input' > '$output'
]]]]><![CDATA[></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](https://github.com/galaxyproject/galaxy/tree/dev/lib/galaxy/datatypes).
The ``DatasetFilenameWrapper`` class in the
[/lib/galaxy/tools/wrappers.py](https://github.com/galaxyproject/galaxy/blob/dev/lib/galaxy/tools/wrappers.py)
code file wraps a metadata collection to return metadata parameters wrapped
according to the Metadata spec.
```xml
<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'
]]]]><![CDATA[></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_directory__`` | The directory the tool description (XML file) currently resides in (new in 15.03)
``$__new_file_path__`` | ``config/galaxy.ini``'s ``new_file_path`` value
``$__tool_data_path__`` | ``config/galaxy.ini``'s tool_data_path value
``$__root_dir__`` | Top-level Galaxy source directory made absolute via ``os.path.abspath()``
``$__datatypes_config__`` | ``config/galaxy.ini``'s datatypes_config value
``$__user_id__`` | Email's numeric ID (id column of ``galaxy_user`` table in the database)
``$__user_email__`` | User's email address
``$__app__`` | The ``galaxy.app.UniverseApplication`` instance, gives access to all other configuration file variables (e.g. $__app__.config.output_size_limit). 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
---- | -----------
``\${GALAXY_SLOTS:-4}`` | Number of cores/threads 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_SLOTS or in an older Galaxy runtime).
``\$GALAXY_MEMORY_MB`` | Total amount of memory in megabytes (1024^2 bytes) allocated by the administrator (via the resource manager) to the tool for the given job. If unset, tools should not attempt to limit memory usage.
``\$GALAXY_MEMORY_MB_PER_SLOT`` | Amount of memory per slot in megabytes (1024^2 bytes) allocated by the administrator (via the resource manager) to the tool for the given job. If unset, tools should not attempt to limit memory usage.
See the [Planemo docs](https://planemo.readthedocs.io/en/latest/writing_advanced.html#cluster-usage)
on the topic of ``GALAXY_SLOTS`` for more information and examples.
### Error detection
The ``detect_errors`` attribute of ``command``, if present, 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 ``Exception:``, ``Error:``, or
various messages related to being out of memory appear in the standard error or 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](https://github.com/galaxyproject/galaxy/pull/117) for more implementation
information and discussion on the ``detect_errors`` attribute.
]]></xs:documentation>
</xs:annotation>
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="detect_errors" type="xs:string">
<xs:annotation>
<xs:documentation>One of ``default``, ``exit_code``, ``aggressive``. See "Error detection" above for details.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="oom_exit_code" type="xs:integer">
<xs:annotation>
<xs:documentation>Only used if ``detect_errors="exit_code"``, tells Galaxy the specified exit code indicates an out of memory error. Galaxy instances may be configured to retry such jobs on resources with more memory.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="use_shared_home" type="xs:string">
<xs:annotation>
<xs:documentation>When running a job for this tool, do not isolate its ``$HOME`` directory within the job's directory - use either the ``shared_home_dir`` setting in Galaxy or the default ``$HOME`` specified in the job's default environment.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="interpreter" type="xs:string" gxdocs:deprecated="true">
<xs:annotation>
<xs:documentation xml:lang="en"><![CDATA[*Deprecated*. This will prefix the command with the value of this attribute (e.g. ``python`` or ``perl``) and the tool directory, in order to run an executable file shipped with the tool. It is recommended to instead use ``<interpreter> '$__tool_directory__/<executable_name>'`` in the tag content. If this attribute is not specified, the tag should contain a Bash command calling executable(s) available in the ``$PATH``, as modified after loading the requirements.]]></xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="strict" type="xs:boolean">
<xs:annotation>
<xs:documentation xml:lang="en">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.</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
<xs:complexType name="ParamOption">
<xs:annotation>
<xs:documentation xml:lang="en"><![CDATA[
See [/tools/filters/sorter.xml](https://github.com/galaxyproject/galaxy/blob/master/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](#tool-inputs-param) directive when the ``type`` attribute
value is ``select`` (i.e. ``<param type="select" ...>``).
### Example
```xml
<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.
```xml
<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>
```
]]>
</xs:documentation>
</xs:annotation>
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="value" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en"><![CDATA[The value of the
corresponding variable when used the Cheetah template. Also the value that
should be used in building test cases and used when building requests for the
API.]]></xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="selected" type="PermissiveBoolean" default="false">
<xs:annotation>
<xs:documentation xml:lang="en">A boolean parameter indicating
if the corresponding option is selected by default (the default is ``false``).
</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
<xs:complexType name="ParamConversion">
<xs:annotation>
<xs:documentation xml:lang="en"><![CDATA[
A contrived example of a tool that uses this is the test tool
[explicit_conversion.xml](https://github.com/galaxyproject/galaxy/blob/dev/test/functional/tools/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.
]]>
</xs:documentation>
</xs:annotation>
<xs:attribute name="name" type="xs:string" use="required">
<xs:annotation>
<xs:documentation xml:lang="en">Name of Cheetah variable to create for converted dataset.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="type" type="xs:string" use="required">
<xs:annotation>
<xs:documentation xml:lang="en">The short extension describing the datatype to convert to - Galaxy must have a datatype converter from the parent input's type to this.</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:complexType>
<xs:complexType name="ParamOptions">
<xs:annotation>
<xs:documentation xml:lang="en"><![CDATA[
See [/tools/extract/liftOver_wrapper.xml](https://github.com/galaxyproject/galaxy/blob/master/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 ``filter``s 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 ``filter``s - various filters can be used to populate options, see
examples in the [filter](#tool-inputs-param-options-filter) documentation.
### ``from_data_table``
See Galaxy's
[data tables documentation](https://galaxyproject.org/admin/tools/data-tables)
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](https://github.com/galaxyproject/tools-devteam/blob/master/tools/bowtie2/bowtie2_wrapper.xml)
wrapper demonstrates using ``from_data_table`` options as an
alternative to local reference data.
```xml
<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](https://github.com/galaxyproject/tools-iuc/blob/master/tools/mothur/remove.lineage.xml)
and demonstrates generating options from a dataset directly.
```xml
<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](#tool-inputs-param-options-filter) documentation).
```xml
<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](https://github.com/galaxyproject/galaxy/tree/master/tool-data)
directory. In this example, the option names and values are taken from column 0
of the file.
```xml
<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](https://github.com/galaxyproject/tools-devteam/blob/master/tools/bowtie_wrappers/bowtie_wrapper.xml)
wrappers for an example of these.
### Other Ways to Dynamically Generate Options
Though deprecated and discouraged, [code](#tool-code) blocks can also be
used to generate dynamic options.
]]>
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:group ref="OptionsElement" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="from_dataset" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en">Documentation for from_dataset</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="from_file" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en">Documentation for from_file</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="from_data_table" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en">Documentation for from_data_table</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="from_parameter" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en">Documentation for from_parameter</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="options_filter_attribute" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en">Documentation for options_filter_attribute</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="transform_lines" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en">Documentation for transform_lines</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="startswith" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en">Documentation for startswith</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:complexType>
<xs:group name="OptionsElement">
<xs:choice>
<xs:element name="filter" type="Filter" minOccurs="0" maxOccurs="unbounded"/>
<xs:element name="column" type="Column" minOccurs="0" maxOccurs="unbounded"/>
<xs:element name="validator" type="Validator" minOccurs="0" maxOccurs="1"/>
<xs:element name="file" type="xs:string" minOccurs="0" maxOccurs="unbounded">
<xs:annotation>
<xs:documentation xml:lang="en">Documentation for file</xs:documentation>
</xs:annotation>
</xs:element>
</xs:choice>
</xs:group>
<xs:complexType name="Column">
<xs:annotation>
<xs:documentation xml:lang="en"><![CDATA[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``.
```xml
<options from_dataset="input1">
<column name="name" index="0"/>
<column name="value" index="0"/>
</options>
```
The [interval2maf](https://github.com/galaxyproject/galaxy/blob/dev/tools/maf/interval2maf.xml)
tool makes use of this tag with files from a history, and the
[star_fusion](https://github.com/galaxyproject/tools-iuc/blob/master/tools/star_fusion/star_fusion.xml)
tool makes use of this to reference a data table.
]]></xs:documentation>
</xs:annotation>
<xs:attribute name="name" type="xs:string" use="required">
<xs:annotation>
<xs:documentation xml:lang="en">Name given to the column with index
``index``, the names ``name`` and ``value`` have special meaning as described
above.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="index" type="xs:decimal" use="required">
<xs:annotation>
<xs:documentation xml:lang="en">0-based index of the column in the
target file.</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:complexType>
<xs:complexType name="Validator">
<xs:annotation>
<xs:documentation xml:lang="en"><![CDATA[
See the
[annotation_profiler](https://github.com/galaxyproject/tools-devteam/blob/master/tools/annotation_profiler/annotation_profiler.xml)
tool 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.
### 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](https://github.com/galaxyproject/tools-iuc/blob/master/tools/extract_genomic_dna/extract_genomic_dna.xml#L42)
tool.
```xml
<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](https://github.com/galaxyproject/tools-devteam/blob/master/tool_collections/samtools/samtools_mpileup/samtools_mpileup.xml)
ensures that a dbkey is present and that FASTA indices in the ``fasta_indexes``
tool data table are present.
```xml
<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
```xml
<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 ``..``.
```xml
<validator type="expression" message="No two dots (..) allowed">'..' not in value</validator>
```
]]></xs:documentation>
</xs:annotation>
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="type" type="ValidatorType" use="required">
<xs:annotation>
<xs:documentation xml:lang="en"><![CDATA[The list of supported
validators is in the ``validator_types`` dictionary in
[/lib/galaxy/tools/parameters/validation.py](https://github.com/galaxyproject/galaxy/blob/dev/lib/galaxy/tools/parameters/validation.py).
Valid values include: ``expression``, ``regex``, ``in_range``, ``length``,
``metadata``, ``unspecified_build``, ``no_options``, ``empty_field``,
``dataset_metadata_in_file``, ``dataset_metadata_in_data_table``,
``dataset_ok_validator``]]></xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="message" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en">
The error message displayed on the tool form if validation fails.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="check" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en">Comma-seperated list of metadata