Warning
This document is for an old release of Galaxy. You can alternatively view this page in the latest release if it exists or view the top of the latest release's documentation.
Galaxy Tool XML File¶
The XML File for a Galaxy tool, generally referred to as the “tool config file” or “wrapper”, serves a number of purposes. First, it lays out the user interface for the tool (e.g. form fields, text, help, etc.). Second, it provides the glue that links your tool to Galaxy by telling Galaxy how to invoke it, what options to pass, and what files it will produce as output.
If you find a bug please report it here.
This document serves as reference documentation. If you would like to learn how to build tools for Galaxy, Planemo features a number of tutorials on building Galaxy tools that would better serve that purpose.
tool
¶
The outer-most tag set of tool XML files. Attributes on this tag apply to the tool as a whole.
Tool profile¶
List of behavior changes associated with profile versions:
16.04¶
Disable implicit extra file collection. All dynamic extra file collection requires a
discover_datasets
tag.Disable
format="input"
and require explicit metadata targets (metadata_source
,format_source
).Disable
interpreter
use$__tool_directory__
.Disable
$param_file
useconfigfile
.Disable default tool version of 1.0.0.
Use non zero exit code as default stdio error condition (before non-empty stderr).
18.01¶
Use a separate home directory for each job.
Introduce
provided_metadata_style
with default"default"
before"legacy"
.
18.09¶
References to other inputs need to be fully qualified by using
|
.Do not allow provided but illegal default values.
Do not use Galaxy python environment for
manage_data
tools.
19.05¶
Change default Python version from 2.7 to 3.5
20.05¶
json config files:
unselected optional
select
anddata_column
parameters getNone
instead of"None"
multiple
select
anddata_column
parameters are lists (before comma separated string)
20.09¶
Exit immediately if a command exits with a non-zero status (
set -e
).Assume sort order for collection elements.
21.09¶
Do not strip leading and trailing whitespaces in
from_work_dir
attribute.
23.0¶
Text parameters that are inferred to be optional (i.e the
optional
tag is not set, but the tool parameter accepts an empty string) are set toNone
for templating in Cheetah. Older tools receive the empty string""
as the templated value.
Examples¶
A normal tool:
<tool id="seqtk_seq"
name="Convert FASTQ to FASTA"
version="1.0.0"
profile="16.04"
>
A data_source
tool contains a few more relevant attributes.
<tool id="ucsc_table_direct1"
name="UCSC Main"
version="1.0.0"
hidden="false"
profile="16.01"
tool_type="data_source"
URL_method="post">
Best Practices¶
Find the Intergalactic Utilities Commision suggested best practices for this element here.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
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. Find the Intergalactic Utilities Commision suggested best practices for this element here. |
True |
|
This string is what is displayed as a hyperlink in the tool menu. Find the Intergalactic Utilities Commision suggested best practices for this element here. |
True |
|
This string allows for tool versioning and should be increased with each new version of the tool. The value should follow the PEP 440 specification. It defaults to |
False |
|
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. |
False |
|
Disable the display the tool’s graphical tool form by setting this to |
False |
|
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 and Data Manager tools should set this to have values such as |
False |
|
This string specifies 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 |
False |
|
This string specifies any full URI or a a short SPDX identifier for a license for this tool wrapper. The tool wrapper version can be indepedent of the underlying tool. This license covers the tool XML and associated scripts shipped with the tool. This is interpreted as schema.org/license property. |
False |
|
This string specifies the minimum Python version that is able to fill the Cheetah sections of the tool. If unset defaults to 2.7 if the profile is older than 19.05, otherwise defaults to 3.5. Galaxy will attempt to convert Python statements in Cheetah sections using future if Galaxy is run on Python 3 and |
False |
|
This attribute indicates if this tool is usable within a workflow (defaults to |
False |
|
Only used if |
False |
tool
> description
¶
The value is displayed in
the tool menu immediately following the hyperlink for the tool (based on the
name
attribute of the <tool>
tag set described above).
Example¶
<description>table browser</description>
Best Practices¶
Find the Intergalactic Utilities Commision suggested best practices for this element here.
tool
> macros
¶
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 planemo documentation
tool
> edam_topics
¶
Container tag set for the <edam_topic>
tags.
A tool can have any number of EDAM topic references.
<!-- Example: this tool is about 'Statistics and probability' (http://edamontology.org/topic_2269) -->
<edam_topics>
<edam_topic>topic_2269</edam_topic>
</edam_topics>
tool
> edam_operations
¶
Container tag set for the <edam_operation>
tags.
A tool can have any number of EDAM operation references.
<!-- Example: this tool performs a 'Conversion' operation (http://edamontology.org/operation_3434) -->
<edam_operations>
<edam_operation>operation_3434</edam_operation>
</edam_operations>
tool
> xrefs
¶
Container tag set for the <xref>
tags.
A tool can refer multiple reference IDs.
<!-- Example: this tool is dada2 -->
<xrefs>
<xref type="bio.tools">dada2</xref>
<xref type="bioconductor">dada2</xref>
</xrefs>
<!-- https://bio.tools/dada2 -->
tool
> xrefs
> xref
¶
The xref
element specifies reference
information according to a catalog.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Type of reference - currently |
True |
tool
> creator
¶
The creator(s) of this work. See schema.org/creator.
tool
> creator
> person
¶
Describes a person. Tries to stay close to schema.org/Person.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
False |
|
|
False |
|
|
False |
|
|
False |
|
|
False |
|
|
False |
|
|
False |
|
|
False |
|
|
False |
|
|
False |
|
|
False |
|
|
False |
|
|
False |
|
|
False |
tool
> creator
> organization
¶
Describes an organization. Tries to stay close to schema.org/Organization.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
False |
|
|
False |
|
|
False |
|
|
False |
|
|
False |
|
|
False |
|
|
False |
|
|
False |
|
|
False |
tool
> requirements
¶
This is a container tag set for the requirement
, resource
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 or Singularity containers that should be able to
serve as complete descriptions of the runtime of a tool.
tool
> requirements
> requirement
¶
This tag set is contained within the <requirements>
tag set. Third party
programs or modules that the tool depends upon are included in this tag set.
When a tool runs, Galaxy attempts to resolve these requirements (also called
dependencies). requirement
s are meant to be abstract and resolvable by
multiple different dependency resolvers (e.g. conda, the
Galaxy Tool Shed dependency management system,
or environment modules).
The current best practice for tool dependencies is to target Conda.
Examples¶
This example shows a tool that requires the samtools 0.0.18 package.
This package is available via the Tool Shed (see Tool Shed dependency management ) as well as Conda and can be configured locally to adapt to any other package management system.
<requirements>
<requirement type="package" version="0.1.18">samtools</requirement>
</requirements>
This older example shows a tool that requires R version 2.15.1. The
tool_dependencies.xml
should contain matching declarations for Galaxy to
actually install the R runtime. The set_envirornment
type is only respected
by the tool shed and is ignored by the newer and preferred conda dependency
resolver.
<requirements>
<requirement type="set_environment">R_SCRIPT_PATH</requirement>
<requirement type="package" version="2.15.1">R</requirement>
</requirements>
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Valid values are |
True |
|
For requirements of type |
False |
tool
> requirements
> container
¶
This tag set is contained within the ‘requirements’ tag set. Galaxy can be
configured to run tools within Docker or Singularity
containers - this tag allows the tool to suggest possible valid containers for this tool. The contents of the tag should
be a container image identifier appropriate for the particular container runtime being used, e.g.
quay.io/biocontainers/fastqc:0.11.2--1
for Docker or docker://quay.io/biocontainers/fastqc:0.11.2--1
(or alternatively /opt/containers/fastqc.simg
if your Galaxy installation will be loading the image from a filesystem path)
for Singularity. The requirements
tag can contain multiple container
tags describing suitable container options, in
which case the first container that is found by the Galaxy container resolver at runtime will be used.
Example:
<requirements>
<container type="docker">quay.io/biocontainers/fastqc:0.11.2--1</container>
</requirements>
Read more about configuring Galaxy to run Docker jobs here.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
This value describes the type of container that the tool may be executed in and currently may be |
True |
tool
> required_files
¶
This declaration is used to define files that must be shipped from the tool directory for the tool to function properly in remote environments where the tool directory is not available to the job.
All includes should be list before excludes. By default, the exclude list includes the tool-data/, test-data/, and .hg/** glob patterns.
Pulsar hacks to implicitly find referenced files from the tool directory will be disabled when this block is used. A future Galaxy tool profile version may disable these hacks altogether and specifying this block for all referenced files should be considered a best practice.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Set this to |
False |
tool
> required_files
> include
¶
Describe files to include when relocating tool directory for remote execution.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Type of file reference |
False |
|
Path to referenced files - this should be relative to the tool’s directory (this is the file the tool is located in not the repository directory if these conflict). |
False |
tool
> required_files
> exclude
¶
Describe files to exclude when relocating tool directory for remote execution.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Type of file reference |
False |
|
Path to referenced files - this should be relative to the tool’s directory (this is the file the tool is located in not the repository directory if these conflict). |
False |
tool
> code
¶
Deprecated. Do not use this unless absolutely necessary.
The extensions described here can cause problems using your tool with certain components of Galaxy (like the workflow system). It is highly recommended to avoid these constructs unless absolutely necessary.
This tag set provides detailed control of the way the tool is executed. This (optional) code can be deployed in a separate file in the same directory as the tool’s config file. These hooks are being replaced by new tool config features and methods in the /lib/galaxy/tools/_init_.py code file.
Examples¶
Dynamic Options¶
Use associated dynamic select lists where selecting an option in the first select list dynamically re-renders the options in the second select list. In this example, we are populating both dynamic select lists from metadata elements associated with a tool’s single input dataset. The 2 metadata elements we’re using look like this.
MetadataElement(name="field_names", default=[], desc="Field names", readonly=True, optional=True, visible=True, no_value=[])
# The keys in the field_components map to the list of field_names in the above element
# which ensures order for select list options that are built from it.
MetadataElement(name="field_components", default={}, desc="Field names and components", readonly=True, optional=True, visible=True, no_value={})
Our tool config includes a code file tag like this.
<code file="tool_form_utils.py" />
Here are the relevant input parameters in our tool config. The first parameter is the input dataset that includes the above metadata elements.
<param name="input" type="data" format="vtkascii,vtkbinary" label="Shape with uncolored surface field">
<validator type="expression" message="Shape must have an uncolored surface field.">value is not None and len(value.metadata.field_names) > 0</validator>
</param>
The following parameter dynamically renders a select list consisting of the
elements in the field_names
metadata element associated with the selected
input dataset.
<param name="field_name" type="select" label="Field name" refresh_on_change="true">
<options>
<filter type="data_meta" ref="input" key="field_names"/>
</options>
<validator type="no_options" message="The selected shape has no uncolored surface fields." />
</param>
The following parameter calls the get_field_components_options()
function in
the tool_form_utils.py
code file discussed above. This function returns the
value of the input dataset’s field_components
metadata element dictionary
whose key is the currently selected field_name
from the select list parameter
above.
<param name="field_component_index" type="select" label="Field component index" dynamic_options="get_field_components_options(input, field_name=field_name)" help="Color will be applied to the selected field's component associated with this index." />
Changing the selected option in the field_name
select list will dynamically
re-render the options available in the associated field_component_index
select
list, which is the behavior we want.
The get_field_components_options()
method looks like this.
def get_field_components_options(dataset, field_name):
options = []
if dataset.metadata is None:
return options
if not hasattr(dataset.metadata, 'field_names'):
return options
if dataset.metadata.field_names is None:
return options
if field_name is None:
# The expression validator that helps populate the select list of input
# datsets in the icqsol_color_surface_field tool does not filter out
# datasets with no field field_names, so we need this check.
if len(dataset.metadata.field_names) == 0:
return options
field_name = dataset.metadata.field_names[0]
field_components = dataset.metadata.field_components.get(field_name, [])
for i, field_component in enumerate(field_components):
options.append((field_component, field_component, i == 0))
return options
Parameter Validation¶
This function is called before the tool is executed. If it raises any exceptions the tool execution will be aborted and the exception’s value will be displayed in an error message box. Here is an example:
def validate(incoming):
"""Validator for the plotting program"""
bins = incoming.get("bins","")
col = incoming.get("col","")
if not bins or not col:
raise Exception, "You need to specify a number for bins and columns"
try:
bins = int(bins)
col = int(col)
except:
raise Exception, "Parameters are not integers, columns:%s, bins:%s" % (col, bins)
if not 1<bins<100:
raise Exception, "The number of bins %s must be a number between 1 and 100" % bins
This code will intercept a number of parameter errors and return corresponding error messages. The parameter incoming
contains a dictionary with all the parameters that were sent through the web.
Pre-job and pre-process code¶
The signature of both of these is the same:
def exec_before_job(inp_data, out_data, param_dict, tool):
def exec_before_process(inp_data, out_data, param_dict, tool):
The param_dict
is a dictionary that contains all the values in the incoming
parameter above plus a number of keys and values generated internally by galaxy. The inp_data
and the out_data
are dictionaries keyed by parameter name containing the classes that represent the data.
Example:
def exec_before_process(inp_data, out_data, param_dict, tool):
for name, data in out_data.items():
data.name = 'New name'
This custom code will change the name of the data that was created for this tool to New name. The difference between these two functions is that the exec_before_job
executes before the page returns and the user will see the new name right away. If one were to use exec_before_process
the new name would be set only once the job starts to execute.
Post-process code¶
This code executes after the background process running the tool finishes its run. The example below is more advanced one that replaces the type of the output data depending on the parameter named extension
:
from galaxy import datatypes
def exec_after_process(app, inp_data, out_data, param_dict, tool, stdout, stderr):
ext = param_dict.get('extension', 'text')
items = out_data.items()
for name, data in items:
newdata = datatypes.factory(ext)(id=data.id)
for key, value in data. __dict__.items():
setattr(newdata, key, value)
newdata.ext = ext
out_data[name] = newdata
The content of stdout
and stderr
are strings containing the output of the process.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
This value is the name of the executable code file, and is called in the |
True |
tool
> stdio
¶
Tools write the bulk of useful data to datasets, but they can also write messages to standard I/O (stdio) channels known as standard output (stdout) and standard error (stderr). Both stdout and stderr are typically written to the executing program’s console or terminal. Previous versions of Galaxy checked stderr for execution errors - if any text showed up on stderr, then the tool’s execution was marked as failed. However, many tools write messages to stderr that are not errors, and using stderr allows programs to redirect other interesting messages to a separate file. Programs may also exit with codes that indicate success or failure. One convention is for programs to return 0 on success and a non-zero exit code on failure.
Legacy tools (ones with profile
unspecified or a profile
of less than
16.04) will default to checking stderr for errors as described above. Newer
tools will instead treat an exit code other than 0 as an error. The
detect_errors
on command
can swap between these behaviors but the
stdio
directive allows more options in defining error conditions (though
these aren’t always intuitive).
With stdio
directive, Galaxy can use regular expressions to scan stdout and
stderr, and it also allows exit codes to be scanned for ranges. The <stdio>
tag has two subtags, <regex>
and <exit_code>
, to define regular
expressions and exit code processing, respectively. They are defined below. If a
tool does not have any valid <regex>
or <exit_code>
tags, then Galaxy
will use the previous technique for finding errors.
A note should be made on the order in which exit codes and regular expressions are applied and how the processing stops. Exit code rules are applied before regular expression rules. The rationale is that exit codes are more clearly defined and are easier to check computationally, so they are applied first. Exit code rules are applied in the order in which they appear in the tool’s configuration file, and regular expressions are also applied in the order in which they appear in the tool’s configuration file. However, once a rule is triggered that causes a fatal error, no further rules are checked.
tool
> stdio
> exit_code
¶
Tools may use exit codes to indicate specific execution errors. Many programs use 0 to indicate success and non-zero exit codes to indicate errors. Galaxy allows each tool to specify exit codes that indicate errors. Each <exit_code>
tag defines a range of exit codes, and each range can be associated with a description of the error (e.g., “Out of Memory”, “Invalid Sequence File”) and an error level. The description just describes the condition and can be anything. The error level is either log, warning, fatal error, or fatal_oom. A warning means that stderr will be updated with the error’s description. A fatal error means that the tool’s execution will be marked as having an error and the workflow will stop. A fatal_oom indicates an out of memory condition and the job might be resubmitted if Galaxy is configured appropriately. Note that, if the error level is not supplied, then a fatal error is assumed to have occurred.
The exit code’s range can be any consecutive group of integers. More advanced ranges, such as noncontiguous ranges, are currently not supported. Ranges can be specified in the form “m:n”, where m is the start integer and n is the end integer. If “:n” is specified, then the exit code will be compared against all integers less than or equal to n. If “m:” is used, then the exit code will be compared against all integers greater than or equal to m. If the exit code matches, then the error level is applied and the error’s description is added to stderr. If a tool’s exit code does not match any of the supplied <exit_code>
tags’ ranges, then no errors are applied to the tool’s execution.
Note that most Unix and Linux variants only support positive integers 0 to 255 for exit codes. If an exit code falls outside of this range, the usual convention is to only use the lower 8 bits for the exit code. The only known exception is if a job is broken into subtasks using the tasks runner and one of those tasks is stopped with a POSIX signal. (Note that signals should be used as a last resort for terminating processes.) In those cases, the task will receive -1 times the signal number. For example, suppose that a job uses the tasks runner and 8 tasks are created for the job. If one of the tasks hangs, then a sysadmin may choose to send the “kill” signal, SIGKILL, to the process. In that case, the task (and its job) will exit with an exit code of -9. More on POSIX signals can be found on Wikipedia as well as on the man page for “signal” (man 7 signal
).
The <exit_code>
tag’s supported attributes are as follows:
range
: This indicates the range of exit codes to check. The range can be one of the following:n
: the exit code will only be compared to n;m:n
: the exit code must be greater than or equal to m and less than or equal to n;m:
: the exit code must be greater than or equal to m;:n
: the exit code must be less than or equal to n.
level
: This indicates the error level of the exit code. If no level is specified, then the fatal error level will be assumed to have occurred. The level can have one of following values:log
,qc
, andwarning
: If an exit code falls in the given range, then a description of the error will be added to the beginning of the source, prepended with either ‘QC:’, ‘Log:’ or ‘Warning:’. This will not cause the tool to fail.fatal
: If an exit code falls in the given range, then a description of the error will be added to the beginning of stderr. A fatal-level error will cause the tool to fail.fatal_oom
: If an exit code falls in the given range, then a description of the error will be added to the beginning of stderr. Depending on the job configuration, a fatal_oom-level error will cause the tool to be resubmitted or fail.
description
: This is an optional description of the error that corresponds to the exit code.
The following is an example of the <exit_code>
tag:
<stdio>
<exit_code range="3:5" level="warning" description="Low disk space" />
<exit_code range="6:" level="fatal" description="Bad input dataset" />
<!-- Catching fatal_oom allows the job runner to potentially resubmit to a resource with more
memory if Galaxy is configured to do this. -->
<exit_code range="2" level="fatal_oom" description="Out of Memory" />
</stdio>
If the tool returns 0 or 1, then the tool will not be marked as having an error.
If the exit code is 2, then the tool will fail with the description Out of Memory
added to stderr. If the tool returns 3, 4, or 5, then the tool will not
be marked as having failed, but Low disk space
will be added to stderr.
Finally, if the tool returns any number greater than or equal to 6, then the
description Bad input dataset
will be added to stderr and the tool will be
marked as having failed.
tool
> stdio
> regex
¶
A regular expression defines a pattern of characters. The patterns include the following:
GCTA
, which matches on the fixed string “GCTA”;[abcd]
, which matches on the characters a, b, c, or d;[CG]{12}
, which matches on 12 consecutive characters that are C or G;a.*z
, which matches on the character “a”, followed by 0 or more characters of any type, followed by a “z”;^X
, which matches the letter X at the beginning of a string;Y$
, which matches the letter Y at the end of a string.
There are many more possible regular expressions. A reference to all supported regular expressions can be found under Python Regular Expression Syntax.
A regular expression includes the following attributes:
source
: This tells whether the regular expression should be matched against stdout, stderr, or both. If this attribute is missing or is incorrect, then both stdout and stderr will be checked. The source can be one of the following values:stdout
: the regular expression will be applied to stdout;stderr
: the regular expression will be applied to stderr;both
: the regular expression will be applied to both stderr and stdout (which is the default case).
match
: This is the regular expression that will be used to match against stdout and/or stderr. If the<regex>
tag does not contain the match attribute, then the<regex>
tag will be ignored. The regular expression can be any valid Python regular expression. All regular expressions are performed case insensitively. For example, if match contains the regular expression “actg”, then the regular expression will match against “actg”, “ACTG”, “AcTg”, and so on. Also note that, if double quotes (”) are to be used in the match attribute, then the value ” can be used in place of double quotes. Likewise, if single quotes (’) are to be used in the match attribute, then the value ‘ can be used if necessary.level
: This works very similarly to the<exit_code>
tag, except that, when a regular expression matches against its source, the description is added to the beginning of the source. For example, if stdout matches on a regular expression, then the regular expression’s description is added to the beginning of stdout (instead of stderr). If no level is specified, then the fatal error level will be assumed to have occurred. The level can have one of following values:log
,qc
, andwarning
: If the regular expression matches against its source input (i.e., stdout and/or stderr), then a description of the error will be added to the beginning of the source, prepended with either ‘QC:’, ‘Log:’, or ‘Warning:’. This will not cause the tool to fail.fatal
: If the regular expression matches against its source input, then a description of the error will be added to the beginning of the source. A fatal-level error will cause the tool to fail.fatal_oom
: In contrast to fatal the job might be resubmitted if possible according to the job configuration.
description
: Just like itsexit_code
counterpart, this is an optional description of the regular expression that has matched.
The following is an example of regular expressions that may be used:
<stdio>
<regex match="low space"
source="both"
level="warning"
description="Low space on device" />
<regex match="error"
source="stdout"
level="fatal"
description="Unknown error encountered" />
<!-- Catching fatal_oom allows the job runner to potentially resubmit to a resource with more
memory if Galaxy is configured to do this. -->
<regex match="out of memory"
source="stdout"
level="fatal_oom"
description="Out of memory error occurred" />
<regex match="[CG]{12}"
description="Fatal error - CG island 12 nts long found" />
<regex match="^Branch A"
level="warning"
description="Branch A was taken in execution" />
</stdio>
The regular expression matching proceeds as follows. First, if either stdout or
stderr match on low space
, then a warning is registered. If stdout contained
the string ---LOW SPACE---
, then stdout has the string Warning: Low space on device
added to its beginning. The same goes for if stderr had contained the
string low space
. Since only a warning could have occurred, the processing
continues.
Next, the regular expression error
is matched only against stdout. If stdout
contains the string error
regardless of its capitalization, then a fatal
error has occurred and the processing stops. In that case, stdout would be
prepended with the string Fatal: Unknown error encountered
. Note that, if
stderr contained error
, ERROR
, or ErRor
then it would not matter -
stderr was not being scanned.
If the second regular expression does not match, the regular expression “out of memory” is checked on stdout. If found, Galaxy tries to resubmit the job with more memory if configured correctly, otherwise the job fails.
If the previous regular expressions does not match, then the fourth regular
expression is checked. The fourth regular expression does not contain an error
level, so an error level of fatal
is assumed. The fourth regular expression
also does not contain a source, so both stdout and stderr are checked. The fourth
regular expression looks for 12 consecutive “C”s or “G”s in any order and in
uppercase or lowercase. If stdout contained cgccGGCCcGGcG
or stderr
contained CCCCCCgggGGG
, then the regular expression would match, the tool
would be marked with a fatal error, and the stream that contained the
12-nucleotide CG island would be prepended with Fatal: Fatal error - CG island 12 nts long found
.
Finally, if the tool did not match any of the fatal errors, then the fifth
regular expression is checked. Since no source is specified, both stdout and
stderr are checked. If Branch A
is at the beginning of stdout or stderr, then
a warning will be registered and the source that contained Branch A
will be
prepended with the warning Warning: Branch A was taken in execution
.
tool
> version_command
¶
Specifies the command to be run in order to get the tool’s version string. The resulting value will be found in the “Info” field of the history dataset.
Unlike the command tag, with the exception of the string
$__tool_directory__
this value is taken as a literal and so there is no
need to escape values like $
and command inputs are not available for variable
substitution.
Examples¶
A simple example for a TopHat tool definition might just be:
<version_command>tophat -version</version_command>
An example that leverages a Python script (e.g. count_reads.py
) shipped with
the tool might be:
<version_command>python '$__tool_directory__/count_reads.py'</version_command>
Examples are included in the test tools directory including:
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Deprecated. This will prefix the version command with the value of this attribute (e.g. |
False |
tool
> command
¶
This tag specifies how Galaxy should invoke the tool’s executable, passing its
required input parameter values (the command line specification links the
parameters supplied in the form with the actual tool executable). Any word
inside it starting with a dollar sign ($
) will be treated as a variable whose
values can be acquired from one of three sources: parameters, metadata, or
output files. After the substitution of variables with their values, the content
is interpreted with Cheetah and finally given
to the interpreter specified in the corresponding attribute (if any).
Examples¶
The following uses a compiled executable (bedtools).
<command><![CDATA[
bed12ToBed6 -i '$input' > '$output'
]]></command>
A few things to note about even this simple example:
Input and output variables (boringly named
input
andoutput
) are expanded into paths using the$
Cheetah directive.Paths should be quoted so that the Galaxy database files may contain spaces.
We are building up a shell script - so special characters like
>
can be used (in this case the standard output of the bedtools call is written to the path specified by'$output'
).
The bed12ToBed6 tool can be found here.
A more sophisticated bedtools example demonstrates the use of loops, conditionals, and uses whitespace to make a complex command very readable can be found in annotateBed tool.
<command><![CDATA[
bedtools annotate
-i '${inputA}'
#if $names.names_select == 'yes':
-files
#for $bed in $names.beds:
'${bed.input}'
#end for
-names
#for $bed in $names.beds:
'${bed.inputName}'
#end for
#else:
#set files = '" "'.join([str($file) for $file in $names.beds])
-files '${files}'
#set names = '" "'.join([str($name.display_name) for $name in $names.beds])
-names '${names}'
#end if
$strand
$counts
$both
> '${output}'
]]></command>
The following example (taken from xpath tool)
uses an interpreted executable. In this case a Perl script is shipped with the
tool and the directory of the tool itself is referenced with $__tool_directory__
.
<command><![CDATA[
perl '$__tool_directory__/xpath' -q -e '$expression' '$input' > '$output'
]]></command>
The following example demonstrates accessing metadata from datasets. Metadata values
(e.g., ${input.metadata.chromCol}
) are acquired from the Metadata
model associated
with the objects selected as the values of each of the relative form field
parameters in the tool form. Accessing this information is generally enabled using
the following feature components.
A set of “metadata information” is defined for each supported data type (see the
MetadataElement
objects in the various data types classes in
/lib/galaxy/datatypes.
The DatasetFilenameWrapper
class in the
/lib/galaxy/tools/wrappers.py
code file wraps a metadata collection to return metadata parameters wrapped
according to the Metadata spec.
<command><![CDATA[
#set genome = $input.metadata.dbkey
#set datatype = $input.datatype
mkdir -p output_dir &&
python '$__tool_directory__/extract_genomic_dna.py'
--input '$input'
--genome '$genome'
#if $input.is_of_type("gff"):
--input_format "gff"
--columns "1,4,5,7"
--interpret_features $interpret_features
#else:
--input_format "interval"
--columns "${input.metadata.chromCol},${input.metadata.startCol},${input.metadata.endCol},${input.metadata.strandCol},${input.metadata.nameCol}"
#end if
--reference_genome_source $reference_genome_cond.reference_genome_source
#if str($reference_genome_cond.reference_genome_source) == "cached"
--reference_genome $reference_genome_cond.reference_genome.fields.path
#else:
--reference_genome $reference_genome_cond.reference_genome
#end if
--output_format $output_format_cond.output_format
#if str($output_format_cond.output_format) == "fasta":
--fasta_header_type $output_format_cond.fasta_header_type_cond.fasta_header_type
#if str($output_format_cond.fasta_header_type_cond.fasta_header_type) == "char_delimited":
--fasta_header_delimiter $output_format_cond.fasta_header_type_cond.fasta_header_delimiter
#end if
#end if
--output '$output'
]]></command>
In additon to demonstrating accessing metadata, this example demonstrates:
$input.is_of_type("gff")
which can be used to check if an input is of a given datatype.#set datatype = $input.datatype
which is the syntax for defining variables in Cheetah.
Reserved Variables¶
Galaxy provides a few pre-defined variables which can be used in your command line, even though they don’t appear in your tool’s parameters.
Name |
Description |
---|---|
|
The directory the tool description (XML file) currently resides in (new in 15.03) |
|
|
|
|
|
Top-level Galaxy source directory made absolute via |
|
|
|
Email’s numeric ID (id column of |
|
User’s email address |
|
The |
|
Only available in converter tools when run internally by Galaxy. Contains the target datatype of the conversion |
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.
For internal converter tools using $__target_datatype__
it is recommended to add a select
input parameter with name __target_datatype__
in order to make the tool testable, see
for instance the biom converter.
Name |
Description |
---|---|
|
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). |
|
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. |
|
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. |
|
Path to an empty directory in the job’s working directory that can be used as a temporary directory. |
See the Planemo docs
on the topic of GALAXY_SLOTS
for more information and examples.
Error detection¶
The detect_errors
attribute of command
, if present, loads a preset of error detection checks (for exit codes and content of stdio to indicate fatal tool errors or fatal out of memory errors). It can be one of:
default
: for non-legacy tools with absent stdio block non-zero exit codes are added. For legacy tools or if a stdio block is present nothing is added.exit_code
: adds checks for non zero exit codes (The @jmchilton recommendation). Theoom_exit_code
parameter can be used to add an additional out of memory indicating exit code.aggressive
: adds checks for non zero exit codes, and checks forException:
,Error:
in the standard error. Additionally checks for messages in the standard error that indicate an out of memory error (MemoryError
,std::bad_alloc
,java.lang.OutOfMemoryError
,Out of memory
). (The @bgruening recommendation).
Prior to Galaxy release 19.01 the stdio block has only been used for non-legacy tools using default
. From release 19.01 checks defined in the stdio tag are prepended to the checks defined by the presets loaded in the command block.
Best Practices¶
Find the Intergalactic Utilities Commision suggested best practices for this element here.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
The |
False |
|
Only used if |
False |
|
When running a job for this tool, do not isolate its |
False |
|
Deprecated. This will prefix the command with the value of this attribute (e.g. |
False |
|
This boolean forces the |
False |
tool
> environment_variables
¶
This directive should contain one or more environment_variable
definition.
tool
> environment_variables
> environment_variable
¶
This directive defines an environment variable that will be available when the tool executes. The body should be a Cheetah template block that may reference the tool’s inputs as demonstrated below.
Example¶
The following demonstrates a couple environment_variable
definitions.
<environment_variables>
<environment_variable name="INTVAR">$inttest</environment_variable>
<environment_variable name="IFTEST">#if int($inttest) == 3
ISTHREE
#else#
NOTTHREE
#end if#</environment_variable>
</environment_variables>
</environment_variables>
If these environment variables are used in another Cheetah context, such as in
the command
block, the $
used indicate shell expansion of a variable
should be escaped with a \
so prevent it from being evaluated as a Cheetah
variable instead of shell variable.
<command>
echo "\$INTVAR" > $out_file1;
echo "\$IFTEST" >> $out_file1;
</command>
inject¶
The Galaxy user’s API key can be injected into an environment variable by setting inject
attribute to api_key
(e.g. inject="api_key"
).
<environment_variables>
<environment_variable name="GALAXY_API_KEY" inject="api_key" />
</environment_variables>
The framework allows setting this via environment variable and not via templating variables in order to discourage setting the actual values of these keys as command line arguments. On shared systems this provides some security by preventing a simple process listing command from exposing keys.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Name of the environment variable to define. |
False |
|
Special variable to inject into the environment variable. Currently ‘api_key’ is the only option and will cause the user’s API key to be injected via this environment variable. |
False |
|
Whether to strip leading and trailing whitespace from the calculated value before exporting the environment variable. |
False |
tool
> configfiles
¶
See
xy_plot.xml
for an example of how this tag set is used in a tool. This tag set is a
container for <configfile>
and <inputs>
tag sets - which can be used
to setup configuration files for use by tools.
tool
> configfiles
> configfile
¶
This tag set is contained within the <configfiles>
tag set. It allows for
the creation of a temporary file for file-based parameter transfer.
Example
The following is taken from the xy_plot.xml tool config.
<configfiles>
<configfile name="script_file">
## Setup R error handling to go to stderr
options(show.error.messages=F, error = function () { cat(geterrmessage(), file=stderr()); q("no", 1, F) })
## Determine range of all series in the plot
xrange = c(NULL, NULL)
yrange = c(NULL, NULL)
#for $i, $s in enumerate($series)
s${i} = read.table("${s.input.file_name}")
x${i} = s${i}[,${s.xcol}]
y${i} = s${i}[,${s.ycol}]
xrange = range(x${i}, xrange)
yrange = range(y${i}, yrange)
#end for
## Open output PDF file
pdf("${out_file1}")
## Dummy plot for axis / labels
plot(NULL, type="n", xlim=xrange, ylim=yrange, main="${main}", xlab="${xlab}", ylab="${ylab}")
## Plot each series
#for $i, $s in enumerate($series)
#if $s.series_type['type'] == "line"
lines(x${i}, y${i}, lty=${s.series_type.lty}, lwd=${s.series_type.lwd}, col=${s.series_type.col})
#elif $s.series_type.type == "points"
points(x${i}, y${i}, pch=${s.series_type.pch}, cex=${s.series_type.cex}, col=${s.series_type.col})
#end if
#end for
## Close the PDF file
devname = dev.off()
</configfile>
</configfiles>
This file is then used in the command
block of the tool as follows:
<command>bash '$__tool_directory__/r_wrapper.sh' '$script_file'</command>
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Cheetah variable used to reference the path to the file created with this directive. |
False |
|
Path relative to the working directory of the tool for the configfile created in response to this directive. |
False |
tool
> configfiles
> inputs
¶
This tag set is contained within the <configfiles>
tag set. It tells Galaxy to
write out a JSON representation of the tool parameters.
Example
The following will create a Cheetah variable that can be evaluated as $inputs
that
will contain the tool parameter inputs.
<configfiles>
<inputs name="inputs" />
</configfiles>
The following will instead write the inputs to the tool’s working directory with
the specified name (i.e. inputs.json
).
<configfiles>
<inputs name="inputs" filename="inputs.json" />
</configfiles>
A contrived example of a tool that uses this is the test tool inputs_as_json.xml.
By default this file will not contain paths for data or collection inputs. To include simple
paths for data or collection inputs set the data_style
attribute to paths
(see inputs_as_json_with_paths.xml for an example).
To include a dictionary with staging paths, paths and metadata files set the data_style
attribute to staging_path_and_source_path
.
An example tool that uses staging_path_and_source_path
is inputs_as_json_with_staging_path_and_source_path.xml
For tools with profile >= 20.05 a select with multiple="true"
is rendered as an array which is empty if nothing is selected. For older profile versions select lists are rendered as comma separated strings or a literal null
in case nothing is selected.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Cheetah variable to populate the path to the inputs JSON file created in response to this directive. |
False |
|
Path relative to the working directory of the tool for the inputs JSON file created in response to this directive. |
False |
|
Set to ‘paths’ to include dataset paths in the resulting file. Set to ‘staging_path_and_source_path’ to include a staging path, a source path and all metadata files. |
False |
tool
> inputs
¶
Consists of all elements that define the tool’s input parameters. Each param element contained in this element can be used as a command line parameter within the command text content. Most tools will not need to specify any attributes on this tag itself.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
URL used by data source tools. |
False |
|
Set to |
False |
|
Data source HTTP action (e.g. |
False |
|
UI link target to use for data source tools (e.g. |
False |
|
This boolean indicates if this is an upload tool or not. |
False |
tool
> inputs
> section
¶
This tag is used to group parameters into sections of the interface. Sections are implemented to replace the commonly used tactic of hiding advanced options behind a conditional, with sections you can easily visually group a related set of options.
Example¶
The XML configuration is relatively trivial for sections:
<inputs>
<section name="section_name" title="Section Title" >
<param name="parameter_name" type="text" label="A parameter label" />
</section>
</inputs>
In your command template, you’ll need to include the section name to access the variable:
$section_name.parameter_name
In output filters sections are represented as dictionary with the same name as the section:
<filter>section_name['parameter_name']</filter>
In order to reference parameters in sections from tags in the <outputs>
section, e.g. in the format_source
attribute of <data>
tags, the syntax is currently:
<data name="output" format_source="parameter_name" metadata_source="parameter_name"/>
Note that references to other parameters in the <inputs>
section are only possible if the reference is in the same section or its parents (and is defined earlier), therefore only parameter_name
is used.
<param name="foo" type="data" format="tabular"/>
<param name="bar" type="data_column" data_ref="foo"/>
<section>
<param name="qux" type="data_column" data_ref="foo"/>
<param name="foo" type="data" format="tabular"/>
<param name="baz" type="data_column" data_ref="foo"/>
</section>
In the above example bar
and qux
will refer to the first foo outside of the section and baz
to the foo
inside the section. This illustrates why non-unique parameter names are strongly discouraged.
The following will not work:
<section>
<param name="foo" type="data" format="tabular"/>
</section>
<param name="bar" type="data_column" data_ref="foo"/>
Further examples can be found in the test case from pull request #35.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
The internal key used for the section. |
True |
|
Human readable label for the section. |
True |
|
Whether the section should be expanded by default or not. If not, the default set values are used. |
False |
|
Short help description for section, rendered just below the section. |
False |
tool
> inputs
> repeat
¶
See
xy_plot.xml
for an example of how to use this tag set. This is a container for any tag sets
that can be contained within the <inputs>
tag set. When this is used, the
tool will allow the user to add any number of additional sets of the contained
parameters (an option to add new iterations will be displayed on the tool form).
All input parameters contained within the <repeat>
tag can be retrieved by
enumerating over $<name_of_repeat_tag_set>
in the relevant Cheetah code.
This returns the rank and the parameter objects of the repeat container. See the
Cheetah code below.
Example¶
This part is contained in the <inputs>
tag set.
<repeat name="series" title="Series">
<param name="input" type="data" format="tabular" label="Dataset"/>
<param name="xcol" type="data_column" data_ref="input" label="Column for x axis"/>
<param name="ycol" type="data_column" data_ref="input" label="Column for y axis"/>
</repeat>
This Cheetah code can be used in the <command>
tag set or the
<configfile>
tag set.
#for $i, $s in enumerate($series)
rank_of_series=$i
input_path='${s.input}'
x_colom=${s.xcol}
y_colom=${s.ycol}
#end for
Testing¶
This is an example test case with multiple repeat elements for the example above.
<test>
<repeat name="series">
<param name="input" value="tabular1.tsv" ftype="tabular"/>
<param name="xcol" value="1"/>
<param name="ycol" value="2"/>
</repeat>
<repeat name="series">
<param name="input" value="tabular2.tsv" ftype="tabular"/>
<param name="xcol" value="4"/>
<param name="ycol" value="2"/>
</repeat>
<output name="out_file1" file="cool.pdf" ftype="pdf" />
</test>
See the documentation on the repeat test directive.
An older way to specify repeats in a test is by instances that are created by referring to names with a special format: <repeat name>_<repeat index>|<param name>
<test>
<param name="series_0|input" value="tabular1.tsv" ftype="tabular"/>
<param name="series_0|xcol" value="1"/>
<param name="series_0|ycol" value="2"/>
<param name="series_1|input" value="tabular2.tsv" ftype="tabular"/>
<param name="series_1|xcol" value="4"/>
<param name="series_1|ycol" value="2"/>
<output name="out_file1" file="cool.pdf" ftype="pdf" />
</test>
The test tool disambiguate_repeats.xml demonstrates both testing strategies.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Name for this element |
True |
|
The title of the repeat section, which will be displayed on the tool form. |
True |
|
The minimum number of repeat units. |
False |
|
The maximum number of repeat units. |
False |
|
The default number of repeat units. |
False |
|
Short help description for repeat element. |
False |
tool
> inputs
> conditional
¶
This is a container for conditional parameters in the tool (must contain ‘when’ tag sets) - the command line (or portions thereof) are then wrapped in an if-else statement. A good example tool that demonstrates many conditional parameters is biom_convert.xml.
<conditional name="input_type">
<param name="input_type_selector" type="select" label="Choose the source BIOM format">
<option value="tsv" selected="true">Tabular File</option>
<option value="biom">BIOM File</option>
</param>
<when value="tsv">
<param name="input_table" type="data" format="tabular" label="Tabular File" argument="--input-fp"/>
<param argument="--process-obs-metadata" type="select" label="Process metadata associated with observations when converting">
<option value="" selected="true">Do Not process metadata</option>
<option value="taxonomy">taxonomy</option>
<option value="naive">naive</option>
<option value="sc_separated">sc_separated</option>
</param>
</when>
<when value="biom">
<param name="input_table" type="data" format="biom1" label="Tabular File" argument="--input-fp"/>
</when>
</conditional>
The first directive following the conditional is a param,
this param must be of type select
or boolean
. Depending on the value a
user selects for this “test” parameter - different UI elements will be shown.
These different paths are described by the following the when
blocks shown
above.
The following Cheetah block demonstrates the use of the conditional
shown above:
biom convert -i "${input_type.input_table}" -o "${output_table}"
#if str($input_type.input_type_selector) == "tsv":
#if $input_type.process_obs_metadata:
--process-obs-metadata "${input_type.process_obs_metadata}"
#end if
#end if
Notice that the parameter input_table
appears down both when
clauses
so ${input_type.input_table}
appears unconditionally but we need to
conditionally reference ${input_type.process_obs_metadata}
with a Cheetah
if
statement.
A common use of the conditional wrapper is to select between reference data managed by the Galaxy admins (for instance via data managers ) and history files. A good example tool that demonstrates this is the Bowtie 2 wrapper.
<conditional name="reference_genome">
<param name="source" type="select" label="Will you select a reference genome from your history or use a built-in index?" help="Built-ins were indexed using default options. See `Indexes` section of help below">
<option value="indexed">Use a built-in genome index</option>
<option value="history">Use a genome from the history and build index</option>
</param>
<when value="indexed">
<param name="index" type="select" label="Select reference genome" help="If your genome of interest is not listed, contact the Galaxy team">
<options from_data_table="bowtie2_indexes">
<filter type="sort_by" column="2"/>
</options>
<validator type="no_options" message="No indexes are available for the selected input dataset"/>
</param>
</when>
<when value="history">
<param name="own_file" type="data" format="fasta" label="Select reference genome" />
</when>
</conditional>
The Bowtie 2 wrapper also demonstrates other conditional paths - such as choosing between paired inputs of single stranded inputs.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Name for this element |
False |
|
Infrequently used option to dynamically access Galaxy internals, this should be avoided. Galaxy method to execute. |
False |
|
Infrequently used option to dynamically access Galaxy internals, this should be avoided. Referenced parameter to pass method. |
False |
|
Infrequently used option to dynamically access Galaxy internals, this should be avoided. Is referenced parameter is the same group. |
False |
|
Human readable description for the conditional, unused in the Galaxy UI currently. |
False |
tool
> inputs
> conditional
> when
¶
This directive describes one potential set of input for the tool at this depth. See documentation for the conditional block for more details and examples (XML and corresponding Cheetah conditionals).
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Value for the tool form test parameter corresponding to this |
True |
tool
> inputs
> param
¶
Contained within the <inputs>
tag set - each of these specifies a field that
will be displayed on the tool form. Ultimately, the values of these form fields
will be passed as the command line parameters to the tool’s executable.
Common Attributes¶
The attributes valid for this tag vary wildly based on the type
of the
parameter being described. All the attributes for the param
element are
documented below for completeness, but here are the common ones for each
type are as follows:
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Describes the parameter type - each different type as different semantics and the tool form widget is different. Currently valid parameter types are: |
True |
|
Name for this element. This |
False |
|
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 (if not given explicitly) from the argument attribute by stripping leading dashes and replacing all remaining dashes by underscores (e.g. if |
False |
|
The attribute value will be displayed on the tool page as the label of the form field ( |
False |
|
Short bit of text, rendered on the tool form just below the associated field to provide information about the field. Find the Intergalactic Utilities Commision suggested best practices for this element here. |
False |
|
If |
False |
|
Force a reload of the tool panel when the value of this parameter changes to allow |
False |
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 with the default value of “V1”.
<param name="xlab" type="text" value="V1" label="Label for x axis" />
The area
boolean attribute can be used to change the text
parameter to a
two-dimensional text area instead of a single line text box.
<param name="foo" type="text" area="true" />
Since release 17.01, text
parameters can also supply a static list of preset
defaults options. The user may be presented with the option to select one of
these but will be allowed to supply an arbitrary text value.
<param name="foo" type="text" value="foo 1">
<option value="foo 1">Foo 1 Display</option>
<option value="foo 2">Foo 2 Display</option>
</param>
See param_text_option.xml for a demonstration of this.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Boolean indicating if this should be rendered as a one line text box (if |
False |
|
The default value for this parameter. |
False |
|
Deprecated. Completely ignored since release 16.10. Used only when the |
False |
integer
and float
¶
These parameters represent whole number and real numbers, respectively.
Example¶
<param name="region_size" type="integer" value="1" label="Size of the flanking regions" />
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
The default value for this parameter. |
False |
|
Minimum valid parameter value. Used only when the |
False |
|
Maximum valid parameter value. Used only when the |
False |
boolean
¶
This represents a binary true or false value.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Set to |
False |
|
The parameter value in the Cheetah template if the parameter is |
False |
|
The parameter value in the Cheetah template if the parameter is |
False |
data
¶
A dataset from the current history. Multiple types might be used for the param form.
Examples¶
The following will find all “coordinate interval files” contained within the current history and dynamically populate a select list with them. If they are selected, their destination and internal file name will be passed to the appropriate command line variable.
<param name="interval_file" type="data" format="interval" label="near intervals in"/>
The following demonstrates a param
which may accept multiple files and
multiple formats.
<param format="sam,bam" multiple="true" name="bamOrSamFile" type="data"
label="Alignments in BAM or SAM format"
help="The set of aligned reads." />
Perhaps counter-intuitively, a multiple="true"
data parameter requires at least one
data input. If optional="true"
is specified, this condition is relaxed and the user
is allowed to select 0 datasets. Unfortunately, if 0 datasets are selected the resulting
value for the parameter during Cheetah templating (such as in a command
block) will
effectively be a list with one None
-like entity in it.
The following idiom can be used to iterate over such a list and build a hypothetical -B
parameter for each file - the if
block is used to handle the case where a None
-like
entity appears in the list because no files were selected:
#for $input in $input1
#if $input
-B "$input"
#end if
#end for
Some example tools using multiple="true"
data parameters include:
Additionally, a detailed discussion of handling multiple homogenous files can be found in the the Planemo Documentation on this topic.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Number of bytes that should be loaded into the |
False |
|
If |
False |
|
Minimum valid parameter value. Used only when the |
False |
|
Maximum valid parameter value. Used only when the |
False |
|
The comma-separated list of accepted data formats for this input. The list of supported data formats is contained in the /config/datatypes_conf.xml.sample file (use the file extension). Used only when the |
False |
|
Allow multiple values to be selected. |
False |
group_tag
¶
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Allow multiple values to be selected. |
False |
select
¶
The following will create a select list containing the options “Downstream” and
“Upstream”. Depending on the selection, a d
or u
value will be passed to
the $upstream_or_down
variable on the command line.
<param name="upstream_or_down" type="select" label="Get">
<option value="u">Upstream</option>
<option value="d">Downstream</option>
</param>
The following will create a checkbox list allowing the user to select
“Downstream”, “Upstream”, both, or neither. Depending on the selection, the
value of $upstream_or_down
will be d
, u
, u,d
, or “”.
<param name="upstream_or_down" type="select" label="Get" multiple="true" display="checkboxes">
<option value="u">Upstream</option>
<option value="d">Downstream</option>
</param>
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
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). Used only when the |
False |
|
Render a select list as a set of checkboxes ( |
False |
|
Allow multiple values to be selected. |
False |
|
Deprecated/discouraged method to allow access to Python code to generate options for a select list. See |
False |
data_column
¶
This parameter type is used to select columns from a parameter.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Deprecated. This is the inverse of |
False |
|
Allow multiple values to be selected. |
False |
|
If |
False |
drill_down
¶
Allows to select values from a hierarchy. The default (hierarchy="exact"
) is
that only exactly the selected options are used. With hierarchy="recurse"
all leaf nodes in the subtree are used.
See drill_down.xml
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Allow multiple values to be selected. |
False |
|
Determine if a drill down is |
False |
data_collection
¶
The following will create a parameter that only accepts paired FASTQ files grouped into a collection.
Examples¶
<param name="inputs" type="data_collection" collection_type="paired" label="Input FASTQs" format="fastq">
</param>
More detailed information on writing tools that consume collections can be found in the planemo documentation.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
The comma-separated list of accepted data formats for this input. The list of supported data formats is contained in the /config/datatypes_conf.xml.sample file (use the file extension). Used only when the |
False |
|
Restrict the kind of collection that can be consumed by this parameter. Simple collections are either |
False |
color
¶
Examples¶
The following example will create a color selector parameter.
<param name="feature_color" type="color" label="Default feature color" value="#ff00ff">
</param>
Given that the output includes a pound sign, it is often convenient to use a sanitizer to prevent Galaxy from escaping the result.
<param name="feature_color" type="color" label="Default feature color" value="#ff00ff">
<sanitizer>
<valid initial="string.ascii_letters,string.digits">
<add value="#" />
</valid>
</sanitizer>
</param>
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
The default value for this parameter. |
False |
|
If |
False |
directory_uri
¶
This is used to tie into galaxy.files URI infrastructure. This should only be used by core Galaxy tools until the interface around files has stabilized.
Currently directory_uri
parameters provide user’s the option of selecting a writable
directory destination for unstructured outputs of tools (e.g. history exports).
This covers examples of the most common parameter types, the remaining parameter types are more obsecure and less likely to be useful for most tool authors.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Describes the parameter type - each different type as different semantics and the tool form widget is different. Currently valid parameter types are: |
True |
|
Name for this element. This |
False |
|
Boolean indicating if this should be rendered as a one line text box (if |
False |
|
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 (if not given explicitly) from the argument attribute by stripping leading dashes and replacing all remaining dashes by underscores (e.g. if |
False |
|
The attribute value will be displayed on the tool page as the label of the form field ( |
False |
|
Short bit of text, rendered on the tool form just below the associated field to provide information about the field. Find the Intergalactic Utilities Commision suggested best practices for this element here. |
False |
|
Number of bytes that should be loaded into the |
False |
|
The default value for this parameter. |
False |
|
Deprecated. Specify default value for column parameters (use |
False |
|
If |
False |
|
If |
False |
|
Minimum valid parameter value. Used only when the |
False |
|
Maximum valid parameter value. Used only when the |
False |
|
The comma-separated list of accepted data formats for this input. The list of supported data formats is contained in the /config/datatypes_conf.xml.sample file (use the file extension). Used only when the |
False |
|
Restrict the kind of collection that can be consumed by this parameter. Simple collections are either |
False |
|
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). Used only when the |
False |
|
Deprecated. Take the value given by |
False |
|
Force a reload of the tool panel when the value of this parameter changes to allow |
False |
|
Deprecated. This is the inverse of |
False |
|
If |
False |
|
Render a select list as a set of checkboxes ( |
False |
|
Allow multiple values to be selected. |
False |
|
If |
False |
|
Determine if a drill down is |
False |
|
Set to |
False |
|
The parameter value in the Cheetah template if the parameter is |
False |
|
The parameter value in the Cheetah template if the parameter is |
False |
|
Deprecated. Completely ignored since release 16.10. Used only when the |
False |
|
Deprecated/discouraged method to allow access to Python code to generate options for a select list. See |
False |
tool
> inputs
> param
> validator
¶
This tag set is contained within the <param>
tag set - it applies a
validator to the containing parameter. Tool submission will fail if a
single validator fails. See the
annotation_profiler
tool for an example of how to use this tag set.
Note that validators for parameters with optional="true"
are not
executed if no value is given.
Generic validators¶
expression
: Check if a one line python expression given expression evaluates to True. The expression is given is the content of the validator tag.
Validators for data
and data_collection
parameters¶
In case of data_collection
parameters and
data
parameters with multiple="true"
these validators are executed
separately for each of the contained data sets. Note that, for data
parameters a metadata
validator is added automatically.
metadata
: Check for missing metadata. The set of (optional) metadata to be checked can be set using either thecheck
orskip
attribute. Note that each data parameter has automatically a metadata validator that checks if all non-optional metadata are set, i.e.<validator type="metadata/>
.unspecified_build
: Check of a build is defined.dataset_ok_validator
: Check if the data set is in state OK.dataset_metadata_in_range
: Check if a numeric metadata value is within a given range.dataset_metadata_in_data_table
: Check if a metadata value is contained in a column of a data table.dataset_metadata_not_in_data_table
: Equivalent todataset_metadata_in_data_table
withnegate="true"
.
Deprecated data validators:
dataset_metadata_in_file
: Use data tables withdataset_metadata_in_data_table
. Check if a metadata value is contained in a specific column of a file in thetool_data_path
(which is set in Galaxy’s config).
Validators for textual inputs (text
, select
, …)¶
regex
: Check if a regular expression matches the value, i.e. appears at the beginning of the value. To enforce a match of the complete value use$
at the end of the expression. The expression is given is the content of the validator tag. Note that forselects
each option is checked separately.length
: Check if the length of the value is within a range.empty_field
: Check if the string is not emptyvalue_in_data_table
: Check if the value is contained in a column of a given data table.value_not_in_data_table
: Equivalent tovalue_in_data_table
withnegate="true"
.
For selects (in particular with dynamically defined options) the following validator is useful:
no_options
: Check if options are available for a select
parameter.
Useful for parameters with dynamically defined options.
Validators for numeric inputs (integer
, float
)¶
in_range
: Check if the value is in a given range.
Examples¶
The following demonstrates a simple validator unspecified_build
ensuring
that a dbkey is present on the selected dataset. This example is taken from the
extract_genomic_dna
tool.
<param name="input" type="data" format="gff,interval" label="Fetch sequences for intervals in">
<validator type="unspecified_build" />
</param>
Along the same line, the following example taken from
samtools_mpileup
ensures that a dbkey is present and that FASTA indices in the fasta_indexes
tool data table are present.
<param format="bam" label="BAM file(s)" name="input_bam" type="data" min="1" multiple="true">
<validator type="unspecified_build" />
<validator type="dataset_metadata_in_data_table" metadata_name="dbkey" table_name="fasta_indexes" metadata_column="1"
message="Sequences are not currently available for the specified build." />
</param>
In this older, somewhat deprecated example - a genome build of the dataset must
be stored in Galaxy clusters and the name of the genome (dbkey
) must be one
of the values in the first column of file alignseq.loc
- that could be
expressed with the validator. In general, dataset_metadata_in_file
should be
considered deprecated in favor of
<validator type="dataset_metadata_in_data_table"
metadata_name="dbkey"
metadata_column="1"
message="Sequences are not currently available for the specified build." />
A very common validator is simply ensure a Python expression is valid for a
specified value. In the following example - paths/names that downstream tools
use in filenames may not contain ..
.
<validator type="expression" message="No two dots (..) allowed">'..' not in value</validator>
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Valid values are: |
True |
|
The error message displayed on the tool form if validation fails. A placeholder string |
False |
|
Negates the result of the validator. |
False |
|
Comma-seperated list of metadata fields to check for if type is |
False |
|
Tool data table name to check against if |
False |
|
Deprecated: use |
False |
|
Target metadata attribute name for |
False |
|
Target column for metadata attribute in |
False |
|
When the |
False |
|
When the |
False |
|
When the |
False |
|
When the |
False |
|
If |
False |
|
Comma-seperated list of metadata fields to skip if type is |
False |
|
Deprecated. Used to indicate lines in the file being used for validation start with a this attribute value. For use with validator |
False |
|
Deprecated. This is now always done. |
False |
tool
> inputs
> param
> option
¶
See /tools/filters/sorter.xml
for typical examples of how to use this tag set. This directive is used to described
static lists of options and is contained
within the param directive when the type
attribute
value is select
(i.e. <param type="select" ...>
).
Example¶
<param name="style" type="select" label="with flavor">
<option value="num">Numerical sort</option>
<option value="gennum">General numeric sort</option>
<option value="alpha">Alphabetical sort</option>
</param>
An option can also be annotated with selected="true"
to specify a
default option (note that the first option is selected automatically
if optional="false"
).
<param name="col" type="select" label="From">
<option value="0">Column 1 / Sequence name</option>
<option value="1" selected="true">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>
In general the values and the texts for the options need to be unique,
but it is possible to specify an option two times if the 2nd has a different
value for the selected
attribute. This is handy if an option list is
defined in a macro and different default value(s) are used.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
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. |
False |
|
A boolean parameter indicating if the corresponding option is selected by default (the default is |
False |
tool
> inputs
> param
> conversion
¶
A contrived example of a tool that uses this is the test tool explicit_conversion.xml.
This directive is optionally contained within the <param>
tag when the
type
attribute value is data
and is used to dynamically generated a converted
dataset for the contained input of the type specified using the type
tag.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Name of Cheetah variable to create for converted dataset. |
True |
|
The short extension describing the datatype to convert to - Galaxy must have a datatype converter from the parent input’s type to this. |
True |
tool
> inputs
> param
> options
¶
See /tools/extract/liftOver_wrapper.xml
for an example of how to use this tag set. This tag set is optionally contained
within the <param>
tag when the type
attribute value is select
or
data
and used to dynamically generated lists of options.
For data parameters this tag can be used to restrict possible input datasets to datasets that match the dbkey
of another data input by including a data_meta
filter. See for
instance here: /tools/maf/interval2maf.xml
For select parameters 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 filetool_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 mechanism is discouraged in favor of the more genericfrom_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 documentation.
from_data_table
¶
See Galaxy’s data tables documentation for information on setting up data tables.
Once a data table has been configured and populated, these can be easily leveraged via tools.
This conditional
block in the
bowtie2
wrapper demonstrates using from_data_table
options as an
alternative to local reference data.
<conditional name="reference_genome">
<param name="source" type="select" label="Will you select a reference genome from your history or use a built-in index?" help="Built-ins were indexed using default options. See `Indexes` section of help below">
<option value="indexed">Use a built-in genome index</option>
<option value="history">Use a genome from the history and build index</option>
</param>
<when value="indexed">
<param name="index" type="select" label="Select reference genome" help="If your genome of interest is not listed, contact the Galaxy team">
<options from_data_table="bowtie2_indexes">
<filter type="sort_by" column="2"/>
</options>
<validator type="no_options" message="No indexes are available for the selected input dataset"/>
</param>
</when>
<when value="history">
<param name="own_file" type="data" format="fasta" label="Select reference genome" />
</when>
</conditional>
A minimal example wouldn’t even need the filter
or validator
above, but
they are frequently nice features to add to your wrapper and can improve the user
experience of a tool.
from_dataset
¶
The following example is taken from the Mothur tool remove.lineage.xml and demonstrates generating options from a dataset directly.
<param name="taxonomy" type="data" format="mothur.seq.taxonomy" label="taxonomy - Taxonomy" help="please make sure your file has no quotation marks in it"/>
<param name="taxons" type="select" 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="""/>
<remove value="'"/>
</valid>
</sanitizer>
</param>
Starting from Galaxy v21.01, meta_file_key
can be used together with
from_dataset
. In such cases, options are generated using the dataset’s
medadata file that the meta_file_key
implies, instead of the dataset
itself.
Note that in any case only the first mega byte of the referred dataset (or file)
is considered. Lines starting with #
are ignored. By using the startswith
attribute also lines starting with other strings can be ignored.
<param name="input" type="data" format="maf" label="MAF File"/>
<param name="species" type="select" optional="False" label="Select species for the input dataset" multiple="True">
<options from_dataset="input" meta_file_key="species_chromosomes">
<column name="name" index="0"/>
<column name="value" index="0"/>
</options>
</param>
<param name="input_2" type="data_collection" collection_type="list" format="maf" label="MAF Collection" multiple="true" />
<param name="species_2" type="select" optional="false" label="Select species for the input dataset" multiple="true">
<options from_dataset="input_2" meta_file_key="species_chromosomes" >
<column name="name" index="0"/>
<column name="value" index="0"/>
<filter type="unique_value" name="unique_param" column="0"/>
</options>
</param>
Filters can be used to generate options from dataset directly also as the example below demonstrates (many more examples are present in the filter documentation).
<param name="species1" type="select" label="When Species" multiple="false">
<options>
<filter type="data_meta" ref="input1" key="species" />
</options>
</param>
from_file
¶
The following example is for Blast databases. In this example users maybe select
a database that is pre-formatted and cached in Galaxy clusters. When a new
dataset is available, admins must add the database to the local file named
“blastdb.loc”. All such databases in that file are included in the options of
the select list. For a local instance, the file (e.g. blastdb.loc
or
alignseq.loc
) must be stored in the configured
tool_data_path
directory. In this example, the option names and values are taken from column 0
of the file.
<param name="source_select" type="select" display="radio" label="Choose target database">
<options from_file="blastdb.loc">
<column name="name" index="0"/>
<column name="value" index="0"/>
</options>
</param>
In general, from_file
should be considered deprecated and from_data_table
should be prefered.
from_parameter
¶
This variant of the options
directive is discouraged because it exposes
internal Galaxy structures. See the older
bowtie
wrappers for an example of these.
Other Ways to Dynamically Generate Options¶
Though deprecated and discouraged, code blocks can also be used to generate dynamic options.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Determine options from (the first MB of) the dataset given in the referred input parameter. If ‘meta_file_key’ is given, the options are determined from (the first MB of) the data in the metadata file of the input. |
False |
|
Deprecated. |
False |
|
Determine options from a data table. |
False |
|
Deprecated. |
False |
|
Deprecated. |
False |
|
Deprecated. |
False |
|
Keep only lines starting with the given string. |
False |
|
Works with from_dataset only. See docs |
False |
|
Split tabular data with this character (default is tab) |
False |
tool
> inputs
> param
> options
> column
¶
Optionally contained within an
<options>
tag set - specifies columns used in building select options from a
file stored locally (i.e. index or tool data) or a dataset in the
current history.
Any number of columns may be described, but at least one must be given the name
value
and it will serve as the value of this parameter in the Cheetah
template and elsewhwere (e.g. in API for instance).
If a column named name
is defined, this too has special meaning and it will
be the value the tool form user sees for each option. If no name
column
appears, value
will serve as the name.
Examples¶
The following fragment shows options from the dataset in the current history
that has been selected as the value of the parameter named input1
.
<options from_dataset="input1">
<column name="name" index="0"/>
<column name="value" index="0"/>
</options>
The gff_filter_by_feature_count tool makes use of this tag with files from a history, and the star_fusion tool makes use of this to reference a data table.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Name given to the column with index |
True |
|
0-based index of the column in the target file. |
True |
tool
> inputs
> param
> options
> filter
¶
Optionally contained within an
<options>
tag set - modify (e.g. remove, add, sort, …) the list of values obtained from a locally stored file (e.g.
a tool data table) or a dataset in the current history.
Currently the following filters are defined:
static_value
filter options for which the entry in a givencolumn
of the referenced file based on equality to thevalue
attribute of the filter.regexp
similar to thestatic_value
filter, but checks if the regular expression given byvalue
matches the entry.param_value
filter options for which the entry in a givencolumn
of the referenced file based on properties of another input parameter specified byref
. This property is by default the value of the parameter, but also the values of another attribute (ref_attribute
) of the parameter can be used, e.g. the extension of a data input.data_meta
populate or filter options based on the metadata of another input parameter specified byref
. If acolumn
is given options are filtered for which the entry in this columncolumn
is equal to metadata of the input parameter specified byref
. If nocolumn
is given the metadata value of the referenced input is added to the options list (in this case the correspondingoptions
tag must not have thefrom_data_table
orfrom_dataset
attributes). In both cases the desired metadata is selected bykey
.
The static_value
and regexp
filters can be inverted by setting keep
to true.
add_value
: add an option with a givenname
andvalue
to the options. By default, the new option is appended, withindex
the insertion position can be specified.remove_value
: remove a value from the options. Either specified explicitly withvalue
, the value of another input specified withref
, or the metadatakey
of another inputmeta_ref
.unique_value
: remove options that have duplicate entries in the givencolumn
.sort_by
: sort options by the entries of a givencolumn
. Ifreverse_sort_order
is set totrue
, reverse sort order from ascending to descending.multiple_splitter
: split the entries of the specifiedcolumn
(s) in the referenced file using aseparator
. Thereby the number of columns is increased.attribute_value_splitter
: split the attribute-value pairs within the specifiedcolumn
in the referenced file usingpair_separator
andname_val_separator
. Thereby a new column is introduced beforecolumn
containing a list of all attribute names.
Examples¶
The following example from Mothur’s remove.groups.xml tool demonstrates filtering a select list based on the metadata of an input to to the tool.
<param name="group_in" type="data" format="mothur.groups,mothur.count_table" label="group or count table - Groups"/>
<param name="groups" type="select" label="groups - Pick groups to remove" multiple="true" optional="false">
<options>
<filter type="data_meta" ref="group_in" key="groups"/>
</options>
</param>
This more advanced example, taken from Mothur’s remove.lineage.xml tool demonstrates using filters to sort a list and remove duplicate entries.
<param name="taxonomy" type="data" format="mothur.cons.taxonomy" label="constaxonomy - Constaxonomy file. Provide either a constaxonomy file or a taxonomy file" help="please make sure your file has no quotation marks in it"/>
<param name="taxons" type="select" optional="true" multiple="true" label="Browse Taxons from Taxonomy">
<options from_dataset="taxonomy">
<column name="name" index="2"/>
<column name="value" index="2"/>
<filter type="unique_value" name="unique_taxon" column="2"/>
<filter type="sort_by" name="sorted_taxon" column="2"/>
</options>
<sanitizer>
<valid initial="default">
<add preset="string.printable"/>
<add value=";"/>
<remove value="""/>
<remove value="'"/>
</valid>
</sanitizer>
</param>
This example taken from the hisat2 tool demonstrates filtering values from a tool data table.
<param help="If your genome of interest is not listed, contact the Galaxy team" label="Select a reference genome" name="index" type="select">
<options from_data_table="hisat2_indexes">
<filter column="2" type="sort_by" />
</options>
<validator message="No genomes are available for the selected input dataset" type="no_options" />
</param>
The
gemini_load.xml
tool demonstrates adding values to an option list using filter
s.
<param name="infile" type="data" format="vcf" label="VCF file to be loaded in the GEMINI database" help="Only build 37 (aka hg19) of the human genome is supported.">
<options>
<filter type="add_value" value="hg19" />
<filter type="add_value" value="Homo_sapiens_nuHg19_mtrCRS" />
<filter type="add_value" value="hg_g1k_v37" />
</options>
</param>
While this fragment from maf_to_interval.xml demonstrates removing items.
<param name="species" type="select" label="Select additional species"
display="checkboxes" multiple="true"
help="The species matching the dbkey of the alignment is always included.
A separate history item will be created for each species.">
<options>
<filter type="data_meta" ref="input1" key="species" />
<filter type="remove_value" meta_ref="input1" key="dbkey" />
</options>
</param>
This example taken from snpSift_dbnsfp.xml demonstrates splitting up strings into multiple values.
<param name="annotations" type="select" multiple="true" display="checkboxes" label="Annotate with">
<options from_data_table="snpsift_dbnsfps">
<column name="name" index="4"/>
<column name="value" index="4"/>
<filter type="param_value" ref="dbnsfp" column="3" />
<filter type="multiple_splitter" column="4" separator=","/>
</options>
</param>
This example demonstrates compiling a list of available attributes by parsing a GFF containing a column of multiple attribute-value pairs formatted in the input as gene_id=ABC;transcript_id=abc;transcript_biotype=mRNA
<param name="available_attributes" type="select" label="List of all attributes mentioned in a GFF">
<options from_data_table="a_gff_as_table">
<column name="name" index="8"/>
<column name="value" index="8"/>
<filter type="attribute_value_splitter" column="8" pair_separator=";" name_val_separator="="/>
</options>
</param>
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Currently the filters in the |
True |
|
Column targeted by this filter given as column index or a column name. Invalid if |
False |
|
Name displayed for value to add (only used with |
False |
|
The attribute name of the reference file (tool data) or input dataset. Only used when |
False |
|
When |
False |
|
For types |
False |
|
When |
False |
|
If |
False |
|
Target value of the operations - has slightly different meanings depending on |
False |
|
Only used when |
False |
|
Used when |
False |
|
Only used when |
False |
|
Used when |
False |
|
Only used if |
False |
|
Only used if |
False |
tool
> inputs
> param
> sanitizer
¶
See
/tools/filters/grep.xml
for a typical example of how to use this tag set. This tag set is used to
replace the basic parameter sanitization with custom directives. This tag set is
contained within the <param>
tag set - it contains a set of <valid>
and
<mapping>
tags.
Character presets¶
The following presets can be used when specifying the valid characters: the
constants from the string
Python3 module,
plus default
(equal to string.ascii_letters + string.digits + " -=_.()/+*^,:?!"
)
and none
(empty set).
The string.letters
, string.lowercase
and string.uppercase
Python2
constants are accepted for backward compatibility, but are aliased to the
corresponding not locale-dependent constant (i.e. string.ascii_letters
,
string.ascii_lowercase
and string.ascii_uppercase
respectively).
Examples¶
This example specifies to use the empty string as the invalid character (instead
of the default X
, so invalid characters are effectively dropped instead of
replaced with X
) and indicates that the only valid characters for this input
are ASCII letters, digits, and _
.
<param name="mystring" type="text" label="Say something interesting">
<sanitizer invalid_char="">
<valid initial="string.ascii_letters,string.digits">
<add value="_" />
</valid>
</sanitizer>
</param>
This example allows many more valid characters and specifies that &
will just
be dropped from the input.
<sanitizer>
<valid initial="string.printable">
<remove value="&"/>
</valid>
<mapping initial="none">
<add source="&" target=""/>
</mapping>
</sanitizer>
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
This boolean parameter determines if the input is sanitized at all (the default is |
False |
|
The attribute specifies the character used as a replacement for invalid characters (the default is |
False |
tool
> inputs
> param
> sanitizer
> valid
¶
Contained within the
<sanitizer>
tag set, these are used to specify a list of allowed characters.
Contains <add>
and <remove>
tags.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
This describes the initial characters to allow as valid, specified as a character preset (as defined above). The default is the |
False |
tool
> inputs
> param
> sanitizer
> valid
> add
¶
This directive is used to add individual characters or preset lists of characters. Character must not be allowed as a valid input for the mapping to occur.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Add the characters contained in the specified character preset (as defined above) to the list of valid characters. The default is the |
False |
|
Add a character to the list of valid characters. |
False |
tool
> inputs
> param
> sanitizer
> valid
> remove
¶
This directive is used to remove individual characters or preset lists of characters. Character must not be allowed as a valid input for the mapping to occur.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Remove the characters contained in the specified character preset (as defined above) from the list of valid characters. The default is the |
False |
|
A character to remove from the list of valid characters. |
False |
tool
> inputs
> param
> sanitizer
> mapping
¶
Contained within the <sanitizer>
tag set. Used to specify a mapping of disallowed character to replacement string. Contains <add>
and <remove>
tags.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Initial character mapping (default is |
False |
tool
> inputs
> param
> sanitizer
> mapping
> add
¶
Use to add character mapping during sanitization. Character must not be allowed as a valid input for the mapping to occur.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Replace all occurrences of this character with the string of |
False |
|
Replace all occurrences of |
False |
tool
> inputs
> param
> sanitizer
> mapping
> remove
¶
Use to remove character mapping during sanitization.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Character to remove from mapping. |
False |
tool
> request_param_translation
¶
See /tools/data_source/ucsc_tablebrowser.xml for an example of how to use this tag set. This tag set is used only in “data_source” tools (i.e. whose tool_type
attribute is data_source
). This tag set contains a set of request_param elements.
tool
> request_param_translation
> request_param
¶
Contained within the request_param_translation tag set (used only in “data_source” tools). The external data source application may send back parameter names like “GENOME” which must be translated to “dbkey” in Galaxy.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Each of these maps directly to a |
True |
|
The string representing the name of the parameter in the remote data source |
True |
|
The default value to use for |
False |
tool
> request_param_translation
> request_param
> append_param
¶
Optionally contained within the request_param element if galaxy_name="URL"
. Some remote data sources (e.g., Gbrowse, Biomart) send parameters back to Galaxy in the initial response that must be added to the value of “URL” prior to Galaxy sending the secondary request to the remote data source via URL.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
The text to use to join the requested parameters together (example |
True |
|
The text to use to join the |
False |
|
The text to use to join the param name to its value (example |
True |
tool
> request_param_translation
> request_param
> append_param
> value
¶
Contained within the append_param tag set. Allows for appending a param name / value pair to the value of URL.
Example:
<request_param_translation>
<request_param galaxy_name="URL" remote_name="URL" missing="">
<append_param separator="&" first_separator="?" join="=">
<value name="_export" missing="1" />
</append_param>
</request_param>
</request_param_tranlsation>
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Any valid HTTP request parameter name. The name / value pair must be received from the remote data source and will be appended to the value of URL as something like |
True |
|
Must be a valid HTTP request parameter value (e.g. |
True |
tool
> request_param_translation
> request_param
> value_translation
¶
Optionally contained within the request_param tag set. The parameter value received from a remote data source may be named differently in Galaxy, and this tag set allows for the value to be appropriately translated.
tool
> request_param_translation
> request_param
> value_translation
> value
¶
Contained within the value_translation tag set - allows for changing the data type value to something supported by Galaxy.
Example:
<request_param_translation>
<request_param galaxy_name="data_type" remote_name="hgta_outputType" missing="bed" >
<value_translation>
<value galaxy_value="tabular" remote_value="primaryTable" />
</value_translation>
</request_param>
</request_param_tranlsation>
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
The target value (e.g. for setting data format: the list of supported data formats is contained in the /config/datatypes_conf.xml.sample. |
True |
|
The value supplied by the remote data source application |
True |
tool
> outputs
¶
Container tag set for the <data>
and <collection>
tag sets.
The files and collections created by tools as a result of their execution are
named by Galaxy. You specify the number and type of your output files using the
contained <data>
and <collection>
tags. These may be passed to your tool
executable through using line variables just like the parameters described in
the <inputs>
documentation.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Style used for tool provided metadata file (i.e. galaxy.json) - this can be either “legacy” or “default”. The default of tools with a profile of 17.09 or newer are “default”, and “legacy” for older and tools and tools without a specified profile. A discussion of the differences between the styles can be found here. |
False |
|
Path relative to tool’s working directory to load tool provided metadata from. This metadata can describe dynamic datasets to load, dynamic collection contents, as well as simple metadata (e.g. name, dbkey, etc…) and datatype-specific metadata for declared outputs. More information can be found here. The default is |
False |
tool
> outputs
> data
¶
This tag set is contained within the <outputs>
tag set, and it defines the
output data description for the files resulting from the tool’s execution. The
value of the attribute label
can be acquired from input parameters or metadata
in the same way that the command line parameters are (discussed in the
<command>
tag set section above).
Examples¶
The following will create a variable called $out_file1
with data type
pdf
.
<outputs>
<data format="pdf" name="out_file1" />
</outputs>
The valid values for format can be found in /config/datatypes_conf.xml.sample.
The following will create a dataset in the history panel whose data type is the
same as that of the input dataset selected (and named input1
) for the tool.
<outputs>
<data format_source="input1" name="out_file1" metadata_source="input1"/>
</outputs>
The following will create datasets in the history panel, setting the output data
type to be the same as that of an input dataset named by the format_source
attribute. Note that a conditional name is not included, so 2 separate
conditional blocks should not contain parameters with the same name.
<inputs>
<!-- fasta may be an aligned fasta that subclasses Fasta -->
<param name="fasta" type="data" format="fasta" label="fasta - Sequences"/>
<conditional name="qual">
<param name="add" type="select" label="Trim based on a quality file?" help="">
<option value="no">no</option>
<option value="yes">yes</option>
</param>
<when value="no"/>
<when value="yes">
<!-- qual454, qualsolid, qualillumina -->
<param name="qfile" type="data" format="qual" label="qfile - a quality file"/>
</when>
</conditional>
</inputs>
<outputs>
<data format_source="fasta" name="trim_fasta"
label="${tool.name} on ${on_string}: trim.fasta"/>
<data format_source="qfile" name="trim_qual"
label="${tool.name} on ${on_string}: trim.qual">
<filter>qual['add'] == 'yes'</filter>
</data>
</outputs>
Assume that the tool includes an input parameter named database
which is a
select list (as shown below). Also assume that the user selects the first option
in the $database
select list. Then the following will ensure that the tool
produces a tabular data set whose associated history item has the label Blat on Human (hg18)
.
<inputs>
<param format="tabular" name="input" type="data" label="Input stuff"/>
<param type="select" name="database" label="Database">
<option value="hg18">Human (hg18)</option>
<option value="dm3">Fly (dm3)</option>
</param>
</inputs>
<outputs>
<data format="input" name="output" label="Blat on ${database.value_label}" />
</outputs>
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
The short name for the output datatype. The valid values for format can be found in /config/datatypes_conf.xml.sample (e.g. |
False |
|
This sets the data type of the output dataset(s) to be the same format as that of the specified tool input. |
False |
|
This will be the name of the history item for the output data set. The string can include structure like |
False |
|
Name for this output. This |
True |
|
If |
False |
|
Sets the source of element identifier to the specified input. This only applies to collections that are mapped over a non-collection input and that have equivalent structures. If this references input elements in conditionals, this value should be qualified (e.g. ``cond |
input |
|
This copies the metadata information from the tool’s input dataset. This is particularly useful for interval data types where the order of the columns is not set. |
False |
|
Relative path to a file produced by the tool in its working directory. Output’s contents are set to this file’s contents. The behaviour when this file does not exist in the working directory is undefined; the resulting dataset could be empty or the tool execution could fail. |
False |
|
Boolean indicating whether to hide dataset in the history view. (Default is |
False |
tool
> outputs
> data
> filter
¶
The <data>
tag can contain a <filter>
tag which includes a Python code
block to be executed to test whether to include this output in the outputs the
tool ultimately creates. If the code, when executed, returns True
,
the output dataset is retained. In these code blocks the tool parameters appear
as Python variables and are thus referred to without the $ used for the Cheetah
template (used in the <command>
tag). Variables that are part of
conditionals are accessed using a dictionary named after the conditional. Boolean
parameters appear as booleans, not the value of their truevalue
and
falsevalue
attributes. In the example below, options["selection_mode"]
would
appear as $options.selection_mode
in Cheetah. Similarly options["vcf_output"]
would appear as $options.vcf_output
having the values '--vcf'
when true and
''
when false in Cheetah.
Note that also parameters in sections are accessed via a dictionary.
Example¶
<inputs>
<param type="data" format="fasta" name="reference_genome" label="Reference genome" />
<param type="data" format="bam" name="input_bam" label="Aligned reads" />
<conditional name="options">
<param label="Use advanced options" name="selection_mode" type="select">
<option selected="true" value="defaults">Use default options</option>
<option value="advanced">Use advanced options</option>
</param>
<when value="defaults" />
<when value="advanced">
<param name="vcf_output" type="boolean" checked="false" label="VCF output"
truevalue="--vcf" falsevalue="" />
</when>
</conditional>
</inputs>
<outputs>
<data format="txt" label="Alignment report on ${on_string}" name="output_txt" />
<data format="vcf" label="Variant summary on ${on_string}" name="output_vcf">
<filter>options['selection_mode'] == 'advanced' and options['vcf_output']</filter>
</data>
</outputs>
Note that variables that correspond to optional select parameters are None
if nothing is selected.
Therefore a filter for such a variable looks like the following example.
Example¶
<inputs>
<param name="output_type" type="select" optional="true">
<option value="save_phase">Phase Movie</option>
<option value="save_period">Period Movie</option>
</param>
</inputs>
<outputs>
<data name="phase_out" format="tiff">
<filter>output_type and "save_phase" in output_type</filter>
</data>
<data name="period_out" format="tiff" label="${movie.name[:-4]}_period">
<filter>output_type and "save_period" in output_type</filter>
</data>
</outputs>
tool
> outputs
> data
> change_format
¶
See
extract_genomic_dna.xml
or the test tool
output_format.xml
for simple examples of how this tag set is used in a tool. This tag set is
optionally contained within the <data>
tag set and is the container tag set
for the following <when>
tag set.
tool
> outputs
> data
> change_format
> when
¶
If the data type of the output dataset is the specified type, the data type is changed to the desired type.
Examples¶
Assume that your tool config includes the following select list parameter structure:
<param name="out_format" type="select" label="Output data type">
<option value="fasta">FASTA</option>
<option value="interval">Interval</option>
</param>
Then whenever the user selects the interval
option from the select list, the
following structure in your tool config will override the format="fasta"
setting
in the <data>
tag set with format="interval"
.
<outputs>
<data format="fasta" name="out_file1">
<change_format>
<when input="out_format" value="interval" format="interval" />
</change_format>
</data>
</outputs>
See extract_genomic_dna.xml or the test tool output_format.xml for more examples.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
This attribute should be the name of the desired input parameter (e.g. |
False |
|
This must be a possible value of the |
True |
|
This value must be a supported data type (e.g. |
True |
|
Deprecated. |
False |
|
Deprecated. |
False |
tool
> outputs
> data
> actions
¶
The actions
directive allows tools to dynamically take actions related to an
output
either unconditionally or conditionally based on inputs. These
actions currently include setting metadata values and the output’s data format.
The examples below will demonstrate that the actions
tag contains child
conditional
tags. The these conditionals are met, additional action
directives below the conditional are apply to the data
output.
Metadata¶
The <actions>
in the Bowtie 2 wrapper is used in lieu of the deprecated
<code>
tag to set the dbkey
of the output dataset. In
bowtie2_wrapper.xml
(see below), according to the first action block, if the
reference_genome.source
is indexed
(not history
), then it will assign
the dbkey
of the output file to be the same as that of the reference file. It
does this by looking at through the data table and finding the entry that has the
value that’s been selected in the index dropdown box as column 1 of the loc file
entry and using the dbkey, in column 0 (ignoring comment lines (starting with #)
along the way).
If reference_genome.source
is history
, it pulls the dbkey
from the
supplied file.
<data format="bam" name="output" label="${tool.name} on ${on_string}: aligned reads (sorted BAM)">
<filter>analysis_type['analysis_type_selector'] == "simple" or analysis_type['sam_opt'] is False</filter>
<actions>
<conditional name="reference_genome.source">
<when value="indexed">
<action type="metadata" name="dbkey">
<option type="from_data_table" name="bowtie2_indexes" column="1" offset="0">
<filter type="param_value" column="0" value="#" compare="startswith" keep="false"/>
<filter type="param_value" ref="reference_genome.index" column="0"/>
</option>
</action>
</when>
<when value="history">
<action type="metadata" name="dbkey">
<option type="from_param" name="reference_genome.own_file" param_attribute="dbkey" />
</action>
</when>
</conditional>
</actions>
</data>
Format¶
The Bowtie 2 example also demonstrates conditionally setting an output format based on inputs, as shown below:
<data format="fastqsanger" name="output_unaligned_reads_r" label="${tool.name} on ${on_string}: unaligned reads (R)">
<filter>(library['type'] == "paired" or library['type'] == "paired_collection") and library['unaligned_file'] is True</filter>
<actions>
<conditional name="library.type">
<when value="paired">
<action type="format">
<option type="from_param" name="library.input_2" param_attribute="ext" />
</action>
</when>
<when value="paired_collection">
<action type="format">
<option type="from_param" name="library.input_1" param_attribute="reverse.ext" />
</action>
</when>
</conditional>
</actions>
</data>
Note that the value given in when
tags needs to be the python string representation
of the value of the referred parameter, e.g. True
or False
if the referred
parameter is a boolean.
Unconditional Actions and Column Names¶
For a static file that contains a fixed number of columns, it is straight forward:
<outputs>
<data format="tabular" name="table">
<actions>
<action name="column_names" type="metadata" default="Firstname,Lastname,Age" />
</actions>
</data>
</outputs>
It may also be necessary to use column names based on a variable from another input file. This is implemented in the htseq-count and featureCounts wrappers:
<inputs>
<data name="input_file" type="data" multiple="false">
</inputs>
<outputs>
<data format="tabular" name="output_short">
<actions>
<action name="column_names" type="metadata" default="Geneid,${input_file.name}" />
</actions>
</data>
</outputs>
Or in case of multiple files:
<inputs>
<data name="input_files" type="data" multiple="true">
</inputs>
<outputs>
<data format="tabular" name="output_short">
<actions>
<action name="column_names" type="metadata" default="Geneid,${','.join([a.name for a in $input_files])}" />
</actions>
</data>
</outputs>
Unconditional Actions - An Older Example¶
The first approach above to setting dbkey
based on tool data tables is
prefered, but an older example using so called “loc files” directly is found
below.
In addition to demonstrating this lower-level direct access of .loc files, it
demonstrates an unconditional action. The second block would not be needed for
most cases - it was required in this tool to handle the specific case of a small
reference file used for functional testing. It says that if the dbkey has been
set to equCab2chrM
(which is what the <filter type="metadata_value"... column="1" />
tag does), then it should be changed to equCab2
(which is the
<option type="from_param" ... column="0" ...>
tag does).
<actions>
<conditional name="refGenomeSource.genomeSource">
<when value="indexed">
<action type="metadata" name="dbkey">
<option type="from_file" name="bowtie_indices.loc" column="0" offset="0">
<filter type="param_value" column="0" value="#" compare="startswith" keep="false"/>
<filter type="param_value" ref="refGenomeSource.index" column="1"/>
</option>
</action>
</when>
</conditional>
<!-- Special casing equCab2chrM to equCab2 -->
<action type="metadata" name="dbkey">
<option type="from_param" name="refGenomeSource.genomeSource" column="0" offset="0">
<filter type="insert_column" column="0" value="equCab2chrM"/>
<filter type="insert_column" column="0" value="equCab2"/>
<filter type="metadata_value" ref="output" name="dbkey" column="1" />
</option>
</action>
</actions>
tool
> outputs
> data
> actions
> conditional
¶
This directive is contained within an output data
’s actions
directive.
This directive describes the state of the inputs required to apply an action
(specified as children of the child when
directives to this element) to an
output.
See actions documentation for examples of this directive.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Name of the input parameter to base conditional logic on. The value of this parameter will be matched against nested |
True |
tool
> outputs
> data
> actions
> conditional
> when
¶
See actions documentation for examples of this directive.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Value to match conditional input value against. This needs to be the python string representation of the parameter value, e.g. |
False |
|
Datatype to match against (if |
False |
tool
> outputs
> data
> actions
> action
¶
This directive is contained within an output data
’s actions
directive
(either directly or beneath a parent conditional
tag). This directive
describes modifications to either the output’s format or metadata (based on
whether type
is format
or metadata
).
See actions documentation for examples of this directive.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Type of action (either |
True |
|
If |
False |
|
If |
False |
tool
> outputs
> data
> actions
> action
> option
¶
Load options from a data table, a parameter (or its metadata), or a file
Filter the options using all filters defined by the contained
filter
tags.Chose a value in a given line (
offset
) andcolumn
The options can be considered as a table where each line is an option. The values in the columns can be used for filtering.
The different data sources can be loaded as follows:
from_data_table
: load the options from the data table with the givenname
.from_param
: Initialize a single option containing the value of the referred parameter (name
) or its metadata (param_attribute
)from_file
: Load the file the givenname
(in Galaxy’s tool data path), columns are defined by the givenseparator
(default is tab).
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Source of the tabular data |
True |
|
Name of the referred data table, parameter, or file (required). |
False |
|
The column to choose the value from (required) |
False |
|
The row (of the options) to choose the value from (by default -1, ie. last row) |
False |
|
Applies to |
False |
tool
> outputs
> data
> discover_datasets
¶
Describe datasets to dynamically collect after the job complete.
There are many simple tools with examples of this element distributed with Galaxy, including:
More information can be found on Planemo’s documentation for multiple output files.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Indicate that dataset filenames should simply be read from the provided metadata file (e.g. galaxy.json). If this is set - pattern and sort must not be set. |
False |
|
Regular expression used to find filenames and parse dynamic properties. |
False |
|
Directory (relative to working directory) to search for files. |
False |
|
Indicates that the specified directory should be searched recursively for matching files. |
False |
|
Indicates that the entire path of the discovered dataset relative to the specified directory should be available for matching patterns. |
False |
|
Format (or datatype) of discovered datasets (an alias with |
False |
|
Format (or datatype) of discovered datasets (an alias with |
False |
|
A string |
False |
|
Indication if this dataset is visible in output history. This defaults to |
False |
|
Replace the primary dataset described by the parameter |
False |
tool
> outputs
> collection
¶
This tag set is contained within the <outputs>
tag set, and it defines the
output dataset collection description resulting from the tool’s execution. The
value of the attribute label
can be acquired from input parameters or
metadata in the same way that the command line parameters are (discussed in the
command directive).
Creating collections in tools is covered in-depth in Planemo’s documentation.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Collection type for output. Simple collection types are either |
False |
|
This is the name of input collection to derive collection’s type (e.g. |
False |
|
The short name for the output datatype. The valid values for format can be found in /config/datatypes_conf.xml.sample (e.g. |
False |
|
This sets the data type of the output dataset(s) to be the same format as that of the specified tool input. |
False |
|
This will be the name of the history item for the output data set. The string can include structure like |
False |
|
Name for this output. This |
True |
|
This is the name of input collection or dataset to derive “structure” of the output from (output element count and identifiers). For instance, if the referenced input has three ordered items with identifiers |
input |
|
If |
False |
tool
> outputs
> collection
> filter
¶
The <data>
tag can contain a <filter>
tag which includes a Python code
block to be executed to test whether to include this output in the outputs the
tool ultimately creates. If the code, when executed, returns True
,
the output dataset is retained. In these code blocks the tool parameters appear
as Python variables and are thus referred to without the $ used for the Cheetah
template (used in the <command>
tag). Variables that are part of
conditionals are accessed using a dictionary named after the conditional. Boolean
parameters appear as booleans, not the value of their truevalue
and
falsevalue
attributes. In the example below, options["selection_mode"]
would
appear as $options.selection_mode
in Cheetah. Similarly options["vcf_output"]
would appear as $options.vcf_output
having the values '--vcf'
when true and
''
when false in Cheetah.
Note that also parameters in sections are accessed via a dictionary.
Example¶
<inputs>
<param type="data" format="fasta" name="reference_genome" label="Reference genome" />
<param type="data" format="bam" name="input_bam" label="Aligned reads" />
<conditional name="options">
<param label="Use advanced options" name="selection_mode" type="select">
<option selected="true" value="defaults">Use default options</option>
<option value="advanced">Use advanced options</option>
</param>
<when value="defaults" />
<when value="advanced">
<param name="vcf_output" type="boolean" checked="false" label="VCF output"
truevalue="--vcf" falsevalue="" />
</when>
</conditional>
</inputs>
<outputs>
<data format="txt" label="Alignment report on ${on_string}" name="output_txt" />
<data format="vcf" label="Variant summary on ${on_string}" name="output_vcf">
<filter>options['selection_mode'] == 'advanced' and options['vcf_output']</filter>
</data>
</outputs>
Note that variables that correspond to optional select parameters are None
if nothing is selected.
Therefore a filter for such a variable looks like the following example.
Example¶
<inputs>
<param name="output_type" type="select" optional="true">
<option value="save_phase">Phase Movie</option>
<option value="save_period">Period Movie</option>
</param>
</inputs>
<outputs>
<data name="phase_out" format="tiff">
<filter>output_type and "save_phase" in output_type</filter>
</data>
<data name="period_out" format="tiff" label="${movie.name[:-4]}_period">
<filter>output_type and "save_period" in output_type</filter>
</data>
</outputs>
tool
> outputs
> collection
> discover_datasets
¶
This tag allows one to describe the datasets contained within an output collection dynamically, such that the outputs are “discovered” based on regular expressions after the job is complete.
There are many simple tools with examples of this element distributed with Galaxy, including:
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Indicate that dataset filenames should simply be read from the provided metadata file (e.g. galaxy.json). If this is set - pattern and sort_by must not be set. |
False |
|
Regular expression used to find filenames and parse dynamic properties. |
False |
|
Directory (relative to working directory) to search for files. |
False |
|
Indicates that the specified directory should be searched recursively for matching files. |
False |
|
Indicates that the entire path of the discovered dataset relative to the specified directory should be available for matching patterns. |
False |
|
Format (or datatype) of discovered datasets (an alias with |
False |
|
Format (or datatype) of discovered datasets (an alias with |
False |
|
A string |
False |
|
Indication if this dataset is visible in the history. This defaults to |
False |
tool
> tests
¶
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 or the
run_tests.sh
shell script distributed with Galaxy.
The documentation contained here is mostly reference documentation, for tutorials on writing tool tests please check out Planemo’s Test-Driven Development documentation or the much older wiki content for WritingTests.
Best Practices¶
Find the Intergalactic Utilities Commision suggested best practices for this element here.
tool
> tests
> test
¶
This tag set contains the necessary parameter values for executing the tool via the functional test framework.
Example¶
The following two tests will execute the /tools/filters/sorter.xml tool. Notice the way that the tool’s inputs and outputs are defined.
<tests>
<test>
<param name="input" value="1.bed" ftype="bed" />
<param name="column" value="1"/>
<param name="order" value="ASC"/>
<param name="style" value="num"/>
<output name="out_file1" file="sort1_num.bed" ftype="bed" />
</test>
<test>
<param name="input" value="7.bed" ftype="bed" />
<param name="column" value="1"/>
<param name="order" value="ASC"/>
<param name="style" value="alpha"/>
<output name="out_file1" file="sort1_alpha.bed" ftype="bed" />
</test>
</tests>
The following example, tests the execution of the MAF-to-FASTA converter (/tools/maf/maf_to_fasta.xml).
<tests>
<test>
<param name="input1" value="3.maf" ftype="maf"/>
<param name="species" value="canFam1"/>
<param name="fasta_type" value="concatenated"/>
<output name="out_file1" file="cf_maf2fasta_concat.dat" ftype="fasta"/>
</test>
</tests>
This test demonstrates verifying specific properties about a test output instead of directly comparing it to another file. Here the file attribute is not specified and instead a series of assertions is made about the output.
<test>
<param name="input" value="maf_stats_interval_in.dat" />
<param name="lineNum" value="99999"/>
<output name="out_file1">
<assert_contents>
<has_text text="chr7" />
<not_has_text text="chr8" />
<has_text_matching expression="1274\d+53" />
<has_line_matching expression=".*\s+127489808\s+127494553" />
<!-- 	 is XML escape code for tab -->
<has_line line="chr7	127471195	127489808" />
<has_n_columns n="3" />
<has_n_lines n="3" />
</assert_contents>
</output>
</test>
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Describe the job’s expected exit code. |
False |
|
Assert the number of statically defined items (datasets and collections) this test should produce. Each |
False |
|
Setting this to |
False |
|
Setting this to |
False |
|
Maximum amount of time to let test run. |
False |
tool
> tests
> test
> param
¶
This tag set defines the tool’s input parameters for executing the tool via the functional test framework. See test documentation for some simple examples of parameters.
Parameter Types¶
text
, integer
, and float
¶
Values for these parameters are simply given by the desired value.
boolean
¶
The value of the test parameter should be set to true
or false
corresponding
to the cases that the parameter is checked or not. It is also possible, but
discouraged, to use the value specified as truevalue
or falsevalue
.
data
¶
Data input parameters can be given as a file name. The file should exist in the
test-data
folder. Multiple files can be specified as comma separated list.
select
¶
The value of a select parameter should be specified as the value of one of the
legal options. If more than one option is selected (multiple="true"
) they
should be given as comma separated list. For optional selects
(optional="true"
) the case that no option is selected can be specified with
value=""
.
While in general it is preferred to specify the selected cases by their values it
is also possible to specify them by their name (i.e. the content of the
option
tag that is shown to the user). One use case is a dynamic select that is
generated from a data table with two columns: name and value where the value is
a path. Since the path changes with the test environment it can not be used to
select an option for a test.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
This value must match the name of the associated input parameter ( |
True |
|
This value must be one of the legal values that can be assigned to an input parameter. |
False |
|
This variant of the value parameters can be used to load typed parameters. This string will be loaded as JSON and its type will attempt to be preserved through API requests to Galaxy. |
False |
|
This attribute name should be included only with parameters of |
False |
|
Specifies a |
False |
|
Comma separated list of tags to apply to the dataset (only works for elements of collections - e.g. |
False |
|
URL that points to a remote input file that will be downloaded and used as input. Please use this option only when is not possible to include the files in the |
False |
tool
> tests
> test
> param
> metadata
¶
This directive specifies metadata that should be set for a test data parameter.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Name of the metadata element of the data parameter |
True |
|
Value to set |
True |
tool
> tests
> test
> param
> collection
¶
Definition of a collection for test input.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Type of collection to create. |
True |
|
The identifier of the collection. Default is |
False |
|
Comma separated list of tags to apply to the dataset (only works for elements of collections - e.g. |
False |
tool
> tests
> test
> repeat
¶
Specify test parameters below an iteration of a repeat
block with this
element.
param
elements in a test
block can be arranged into nested repeat
,
conditional
, and select
structures to match the inputs. While this might
be overkill for simple tests, it helps prevent ambiguous definitions and keeps
things organized in large test cases. A future profile
version of Galaxy
tools may require repeat
blocks be explicitly defined with this directive.
Examples¶
The test tool disambiguate_repeats.xml demonstrates the use of this directive.
This first test case demonstrates that this block allows different values for
the param
named input
to be tested even though this parameter name
appears in two different <repeat>
elements in the <inputs>
definition.
<!-- Can disambiguate repeats and specify multiple blocks using,
nested structure. -->
<test>
<repeat name="queries">
<param name="input" value="simple_line.txt"/>
</repeat>
<repeat name="more_queries">
<param name="input" value="simple_line_alternative.txt"/>
</repeat>
<output name="out_file1">
<assert_contents>
<has_line line="This is a line of text." />
<has_line line="This is a different line of text." />
</assert_contents>
</output>
</test>
The second definition in that file demonstrates repeated <repeat>
blocks
allowing multiple instances of a single repeat to be specified.
<!-- Multiple such blocks can be specified but only with newer API
driven tests. -->
<test>
<repeat name="queries">
<param name="input" value="simple_line.txt"/>
</repeat>
<repeat name="queries">
<param name="input" value="simple_line_alternative.txt"/>
</repeat>
<repeat name="more_queries">
<param name="input" value="simple_line.txt"/>
</repeat>
<repeat name="more_queries">
<param name="input" value="simple_line_alternative.txt"/>
</repeat>
<output name="out_file1" file="simple_lines_interleaved.txt"/>
</test>
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
This value must match the name of the associated input |
True |
tool
> tests
> test
> section
¶
Specify test parameters below a named of a section
block matching
one in inputs
with this element.
param
elements in a test
block can be arranged into nested repeat
,
conditional
, and select
structures to match the inputs. While this might
be overkill for simple tests, it helps prevent ambiguous definitions and keeps
things organized in large test cases. A future profile
version of Galaxy
tools may require section
blocks be explicitly defined with this
directive.
Examples¶
The test tool demonstrating sections (section.xml) contains a test case demonstrating this block. This test case appears below:
<test>
<section name="int">
<param name="inttest" value="12456" />
</section>
<section name="float">
<param name="floattest" value="6.789" />
</section>
<output name="out_file1">
<assert_contents>
<has_line line="12456" />
<has_line line="6.789" />
</assert_contents>
</output>
</test>
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
This value must match the name of the associated input |
True |
tool
> tests
> test
> conditional
¶
Specify test parameters below a named of a conditional
block matching
one in inputs
with this element.
param
elements in a test
block can be arranged into nested repeat
,
conditional
, and select
structures to match the inputs. While this might
be overkill for simple tests, it helps prevent ambiguous definitions and keeps
things organized in large test cases. A future profile
version of Galaxy
tools may require conditional
blocks be explicitly defined with this
directive.
Examples¶
The following example demonstrates disambiguation of a parameter (named use
)
which appears in multiple param
names in conditional
s in the inputs
definition of the disambiguate_cond.xml
tool.
<!-- Can use nested conditional blocks as shown below to disambiguate
various nested parameters. -->
<test>
<conditional name="p1">
<param name="use" value="False"/>
</conditional>
<conditional name="p2">
<param name="use" value="True"/>
</conditional>
<conditional name="p3">
<param name="use" value="False"/>
</conditional>
<conditional name="files">
<param name="attach_files" value="True" />
<conditional name="p4">
<param name="use" value="True"/>
<param name="file" value="simple_line_alternative.txt" />
</conditional>
</conditional>
<output name="out_file1">
<assert_contents>
<has_line line="7 4 7" />
<has_line line="This is a different line of text." />
</assert_contents>
</output>
</test>
The tophat2
tool demonstrates a real tool that benefits from more structured test cases
using the conditional
test directive. One such test case from that tool is
shown below.
<!-- Test base-space paired-end reads with user-supplied reference fasta and full parameters -->
<test>
<!-- TopHat commands:
tophat2 -o tmp_dir -r 20 -p 1 -a 8 -m 0 -i 70 -I 500000 -g 40 +coverage-search +min-coverage-intron 50 +max-coverage-intro 20000 +segment-mismatches 2 +segment-length 25 +microexon-search +report_discordant_pairs tophat_in1 test-data/tophat_in2.fastqsanger test-data/tophat_in3.fastqsanger
Replace the + with double-dash
Rename the files in tmp_dir appropriately
-->
<conditional name="singlePaired">
<param name="sPaired" value="paired"/>
<param name="input1" ftype="fastqsanger" value="tophat_in2.fastqsanger"/>
<param name="input2" ftype="fastqsanger" value="tophat_in3.fastqsanger"/>
<param name="mate_inner_distance" value="20"/>
<param name="report_discordant_pairs" value="Yes" />
</conditional>
<param name="genomeSource" value="indexed"/>
<param name="index" value="tophat_test"/>
<conditional name="params">
<param name="settingsType" value="full"/>
<param name="library_type" value="FR Unstranded"/>
<param name="read_mismatches" value="5"/>
<!-- Error: the read mismatches (5) and the read gap length (2) should be less than or equal to the read edit dist (2) -->
<param name="read_edit_dist" value="5" />
<param name="bowtie_n" value="Yes"/>
<param name="mate_std_dev" value="20"/>
<param name="anchor_length" value="8"/>
<param name="splice_mismatches" value="0"/>
<param name="min_intron_length" value="70"/>
<param name="max_intron_length" value="500000"/>
<param name="max_multihits" value="40"/>
<param name="min_segment_intron" value="50" />
<param name="max_segment_intron" value="500000" />
<param name="seg_mismatches" value="2"/>
<param name="seg_length" value="25"/>
<conditional name="indel_search">
<param name="allow_indel_search" value="No"/>
</conditional>
<conditional name="own_junctions">
<param name="use_junctions" value="Yes" />
<conditional name="gene_model_ann">
<param name="use_annotations" value="No" />
</conditional>
<conditional name="raw_juncs">
<param name="use_juncs" value="No" />
</conditional>
<conditional name="no_novel_juncs">
<param name="no_novel_juncs" value="No" />
</conditional>
</conditional>
<conditional name="coverage_search">
<param name="use_search" value="No" />
</conditional>
<param name="microexon_search" value="Yes" />
<conditional name="bowtie2_settings">
<param name="b2_settings" value="No" />
</conditional>
<!-- Fusion search params -->
<conditional name="fusion_search">
<param name="do_search" value="Yes" />
<param name="anchor_len" value="21" />
<param name="min_dist" value="10000021" />
<param name="read_mismatches" value="3" />
<param name="multireads" value="4" />
<param name="multipairs" value="5" />
<param name="ignore_chromosomes" value="chrM"/>
</conditional>
</conditional>
<conditional name="readGroup">
<param name="specReadGroup" value="no" />
</conditional>
<output name="junctions" file="tophat2_out4j.bed" />
<output name="accepted_hits" file="tophat_out4h.bam" compare="sim_size" />
</test>
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
This value must match the name of the associated input |
True |
tool
> tests
> test
> output
¶
This tag set defines the variable that names the output dataset for the
functional test framework. The functional test framework will execute the tool
using the parameters defined in the <param>
tag sets and generate a
temporary file, which will either be compared with the file named in the
file
attribute value or checked against assertions made by a child
assert_contents
tag to verify that the tool is functionally correct.
Different methods can be chosen for the comparison with the local file specified
by file
using the compare
attribute:
diff
: uses diff to compare the history data set and the file provided byfile
. Compressed files are decompressed before the compariopm ifdecompress
is set totrue
. BAM files are converted to SAM before the comparision and for pdf some special rules are implemented. The number of allowed differences can be set withlines_diff
. Ifsort="true"
history and local data is sorted before the comparison.re_match
: each line of the history data set is compared to the regular expression specified in the corresponding line of thefile
. The allowed number of non matching lines can be set withlines_diff
and the history dataset is sorted ifsort
is set totrue
.re_match_multiline
: it is checked if the history data sets matches the multi line regular expression given infile
. The history dataset is sorted before the comparison if thesort
atrribute is set totrue
.contains
: check if each line infile
is contained in the history data set. The allowed number of lines that are not contained in the history dataset can be set withlines_diff
.sim_size
: compares the size of the history dataset and thefile
subject to the values of thedelta
anddelta_frac
attributes. Note that ahas_size
content assertion should be preferred, because this avoids storing the test file.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
This value is the same as the value of the |
False |
|
If specified, this value is the name of the output file stored in the target |
False |
|
If specified, this value will be loaded as JSON and compared against the output generated as JSON. This can be useful for testing tool outputs that are not files. |
False |
|
If specified, this value will be checked against the corresponding output’s data type. If these do not match, the test will fail. |
False |
|
Applies only if |
False |
|
An alias for |
False |
|
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. |
False |
|
If specified, the target output’s checksum should match the value specified here. This value should have the form |
False |
|
Type of comparison to use when comparing test generated output files to expected output files. Currently valid value are |
False |
|
Applies only if |
False |
|
If this attribute is true then try to decompress files if needed. This applies to test assertions expressed with |
False |
|
If |
False |
|
If |
False |
|
Number or datasets for this output. Should be used for outputs with |
False |
|
URL that points to a remote output file that will downloaded and used for output comparison. Please use this option only when is not possible to include the files in the |
False |
tool
> tests
> test
> output
> discovered_dataset
¶
This directive specifies a test for an output’s discovered dataset. It acts as an
output
test tag in many ways and can define any tests of that tag (e.g.
assert_contents
, value
, compare
, md5
, checksum
, metadata
, etc…).
Example¶
The functional test tool multi_output_assign_primary.xml provides a demonstration of using this tag.
<outputs>
<data format="tabular" name="sample">
<discover_datasets pattern="(?P<designation>.+)\.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_datasets>
. 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.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
The designation of the discovered dataset. |
False |
tool
> tests
> test
> output
> metadata
¶
This directive specifies a test for an output’s metadata as an expected key-value pair.
Example¶
The functional test tool tool_provided_metadata_1.xml provides a demonstration of using this tag.
<test>
<param name="input1" value="simple_line.txt" />
<output name="out1" file="simple_line.txt" ftype="txt">
<metadata name="name" value="my dynamic name" />
<metadata name="info" value="my dynamic info" />
<metadata name="dbkey" value="cust1" />
</output>
</test>
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Name of the metadata element to check. |
True |
|
Expected value (as a string) of metadata value. |
True |
tool
> tests
> test
> output
> assert_contents
¶
This tag set defines a sequence of checks or assertions to run against the target output. This tag requires no attributes, but child tags should be used to define the assertions to make about the output. The functional test framework makes it easy to extend Galaxy with such tags, the following table summarizes many of the default assertion tags that come with Galaxy and examples of each can be found below.
The implementation of these tags are simply Python functions defined in the /lib/galaxy/tool_util/verify/asserts module.
General assertions¶
has_size
:¶
Asserts the output has a specific size (in bytes) of value
plus minus
delta
, e.g. <has_size value="10000" delta="100" />
.
Alternatively the range of the expected size can be specified by min
and/or
max
.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Desired size of the output (in bytes), can be suffixed by ``(k |
M |
|
Maximum allowed size difference (default is 0). The observed size has to be in the range |
M |
|
Minimum expected size, can be suffixed by ``(k |
M |
|
Maximum expected size, can be suffixed by ``(k |
M |
|
Negate the outcome of the assertion. |
False |
Assertions for text data¶
has_text
:¶
Asserts the specified text
appears in the output (e.g. <has_text text="chr7">
). If the text
is expected to occur a particular number of
times, this value can be specified using n
. Optionally also with a certain
delta
. Alternatively the range of expected occurences can be specified by
min
and/or max
.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Text to check for |
True |
|
Desired number, can be suffixed by ``(k |
M |
|
Allowed difference with respect to n (default: 0), can be suffixed by ``(k |
M |
|
Minimum number (default: -infinity), can be suffixed by ``(k |
M |
|
Maximum number (default: infinity), can be suffixed by ``(k |
M |
|
Negate the outcome of the assertion. |
False |
not_has_text
:¶
Asserts the specified text
does not appear in the output (e.g. <not_has_text text="chr8" />
).
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Text to check for |
True |
has_text_matching
:¶
Asserts text matching the specified regular expression (expression
) appears
in the output (e.g. <has_text_matching expression="1274\d+53" />
). If the
regular expression is expected to match a particular number of times, this value
can be specified using n
. Note only non-overlapping occurences are counted.
Optionally also with a certain delta
. Alternatively the range of expected
occurences can be specified by min
and/or max
.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Regular expression to check for |
True |
|
Desired number, can be suffixed by ``(k |
M |
|
Allowed difference with respect to n (default: 0), can be suffixed by ``(k |
M |
|
Minimum number (default: -infinity), can be suffixed by ``(k |
M |
|
Maximum number (default: infinity), can be suffixed by ``(k |
M |
|
Negate the outcome of the assertion. |
False |
has_line
:¶
Asserts a line matching the specified string (line
) appears in the output
(e.g. <has_line line="A full example line." />
). If the line
is expected
to occur a particular number of times, this value can be specified using n
.
Optionally also with a certain delta
. Alternatively the range of expected
occurences can be specified by min
and/or max
.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
The line to check for |
True |
|
Desired number, can be suffixed by ``(k |
M |
|
Allowed difference with respect to n (default: 0), can be suffixed by ``(k |
M |
|
Minimum number (default: -infinity), can be suffixed by ``(k |
M |
|
Maximum number (default: infinity), can be suffixed by ``(k |
M |
|
Negate the outcome of the assertion. |
False |
has_line_matching
:¶
Asserts a line matching the specified regular expression (expression
)
appears in the output (e.g. <has_line_matching expression=".*\s+127489808\s+127494553" />
).
If a particular number of matching lines is expected, this value can be
specified using n
. Optionally also with delta
. Alternatively the range
of expected occurences can be specified by min
and/or max
.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Regular expression to check for |
True |
|
Desired number, can be suffixed by ``(k |
M |
|
Allowed difference with respect to n (default: 0), can be suffixed by ``(k |
M |
|
Minimum number (default: -infinity), can be suffixed by ``(k |
M |
|
Maximum number (default: infinity), can be suffixed by ``(k |
M |
|
Negate the outcome of the assertion. |
False |
has_n_lines
:¶
Asserts that an output contains n
lines, allowing for a difference of
delta
(default is 0), e.g. <has_n_lines n="3" delta="1"/>
.
Alternatively the range of expected occurences can be specified by min
and/or max
.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Desired number, can be suffixed by ``(k |
M |
|
Allowed difference with respect to n (default: 0), can be suffixed by ``(k |
M |
|
Minimum number (default: -infinity), can be suffixed by ``(k |
M |
|
Maximum number (default: infinity), can be suffixed by ``(k |
M |
|
Negate the outcome of the assertion. |
False |
Assertions for tabular data¶
has_n_columns
:¶
Asserts tabular output (actually only the first line) contains the specified
number (n
) of columns (e.g. <has_n_columns n="3"/>
) optionally also with
delta
. Alternatively the range of expected occurences can be specified by
min
and/or max
. Optionally a column separator (sep
, default is
\t
) `and comment character(s) can be specified (comment
, default is
empty string), then the first non-comment line is used for determining the
number of columns.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Separator defining columns, default: tab |
False |
|
Comment character(s) used to skip comment lines (which should not be used for counting columns) |
False |
|
Desired number, can be suffixed by ``(k |
M |
|
Allowed difference with respect to n (default: 0), can be suffixed by ``(k |
M |
|
Minimum number (default: -infinity), can be suffixed by ``(k |
M |
|
Maximum number (default: infinity), can be suffixed by ``(k |
M |
|
Negate the outcome of the assertion. |
False |
Assertions for archives (zip/tar)¶
has_archive_member
:¶
This tag allows to check if path
is contained in a compressed file. The path
is a regular expression that is matched against the full paths of the objects in
the compressed file (remember that “matching” means it is checked if a prefix of
the full path of an archive member is described by the regular expression).
Valid archive formats include .zip
, .tar
, and .tar.gz
. Note that
depending on the archive creation method:
full paths of the members may be prefixed with
./
directories may be treated as empty files
<has_archive_member path="./path/to/my-file.txt"/>
With n
and delta
(or min
and max
) assertions on the number of
archive members matching path
can be expressed. The following could be used,
e.g., to assert an archive containing n±1 elements out of which at least
4 need to have a txt
extension.
<has_archive_member path=".*" n="10" delta="1"/>
<has_archive_member path=".*\.txt" min="4"/>
In addition the tag can contain additional assertions as child elements about
the first member in the archive matching the regular expression path
. For
instance
<has_archive_member path=".*/my-file.txt">
<not_has_text text="EDK72998.1"/>
</has_archive_member>
If the all
attribute is set to true
then all archive members are subject
to the assertions. Note that, archive members matching the path
are sorted
alphabetically.
The negate
attribute of the has_archive_member
assertion only affects
the asserts on the presence and number of matching archive members, but not any
sub-assertions (which can offer the negate
attribute on their own). The
check if the file is an archive at all, which is also done by the function, is
not affected.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
The regular expression specifying the archive member. |
False |
|
Check the sub-assertions for all paths matching the path. Default: false, i.e. only the first |
False |
|
Desired number, can be suffixed by ``(k |
M |
|
Allowed difference with respect to n (default: 0), can be suffixed by ``(k |
M |
|
Minimum number (default: -infinity), can be suffixed by ``(k |
M |
|
Maximum number (default: infinity), can be suffixed by ``(k |
M |
Assertions for XML data¶
is_valid_xml
:¶
Asserts the output is a valid XML file (e.g. <is_valid_xml />
).
xml_element
:¶
Assert if the XML file contains element(s) or tag(s) with the specified
XPath-like path
. If n
and delta
or min
and max
are given also the number of occurences is checked.
<assert_contents>
<xml_element path="./elem"/>
<xml_element path="./elem/more[2]"/>
<xml_element path=".//more" n="3" delta="1"/>
</assert_contents>
With negate="true"
the outcome of the assertions wrt the precence and number
of path
can be negated. If there are any sub assertions then check them against
the content of the attribute
attribute
the element’s text if no attribute is given
<assert_contents>
<xml_element path="./elem/more[2]" attribute="name">
<has_text_matching expression="foo$"/>
</xml_element>
</assert_contents>
Sub-assertions are not subject to the negate
attribute of xml_element
.
If all
is true
then the sub assertions are checked for all occurences.
Note that all other XML assertions can be expressed by this assertion (Galaxy also implements the other assertions by calling this one).
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Check the sub-assertions for all paths matching the path. Default: false, i.e. only the first |
False |
|
The name of the attribute to apply sub-assertion on. If not given then the element text is used |
False |
|
Path to check for. Valid paths are the simplified subsets of XPath implemented by lxml.etree; https://lxml.de/xpathxslt.html for more information. |
True |
|
Desired number, can be suffixed by ``(k |
M |
|
Allowed difference with respect to n (default: 0), can be suffixed by ``(k |
M |
|
Minimum number (default: -infinity), can be suffixed by ``(k |
M |
|
Maximum number (default: infinity), can be suffixed by ``(k |
M |
|
Negate the outcome of the assertion. |
False |
has_element_with_path
:¶
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" />
With negate
the result of the assertion can be inverted.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Path to check for. Valid paths are the simplified subsets of XPath implemented by lxml.etree; https://lxml.de/xpathxslt.html for more information. |
True |
|
Negate the outcome of the assertion. |
False |
has_n_elements_with_path
:¶
Asserts the XML output contains the specified number (n
, optionally with delta
) 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" />
Alternatively to n
and delta
also the min
and max
attributes
can be used to specify the range of the expected number of occurences.
With negate
the result of the assertion can be inverted.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Path to check for. Valid paths are the simplified subsets of XPath implemented by lxml.etree; https://lxml.de/xpathxslt.html for more information. |
True |
|
Desired number, can be suffixed by ``(k |
M |
|
Allowed difference with respect to n (default: 0), can be suffixed by ``(k |
M |
|
Minimum number (default: -infinity), can be suffixed by ``(k |
M |
|
Maximum number (default: infinity), can be suffixed by ``(k |
M |
|
Negate the outcome of the assertion. |
False |
element_text_matches
:¶
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.*"/>
The assertion implicitly also asserts that an element matching path
exists.
With negate
the result of the assertion (on the matching) can be inverted (the
implicit assertion on the existence of the path is not affected).
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
The regular expression to use. |
True |
|
Path to check for. Valid paths are the simplified subsets of XPath implemented by lxml.etree; https://lxml.de/xpathxslt.html for more information. |
True |
|
Negate the outcome of the assertion. |
False |
element_text_is
:¶
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" />
The assertion implicitly also asserts that an element matching path
exists.
With negate
the result of the assertion (on the equality) can be inverted (the
implicit assertion on the existence of the path is not affected).
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Text to check for. |
True |
|
Path to check for. Valid paths are the simplified subsets of XPath implemented by lxml.etree; https://lxml.de/xpathxslt.html for more information. |
True |
|
Negate the outcome of the assertion. |
False |
attribute_matches
:¶
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+" />
The assertion implicitly also asserts that an element matching path
exists.
With negate
the result of the assertion (on the matching) can be inverted (the
implicit assertion on the existence of the path is not affected).
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
The regular expression to use. |
True |
|
Path to check for. Valid paths are the simplified subsets of XPath implemented by lxml.etree; https://lxml.de/xpathxslt.html for more information. |
True |
|
Negate the outcome of the assertion. |
False |
attribute_is
:¶
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" />
The assertion implicitly also asserts that an element matching path
exists.
With negate
the result of the assertion (on the equality) can be inverted (the
implicit assertion on the existence of the path is not affected).
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Text to check for. |
True |
|
Path to check for. Valid paths are the simplified subsets of XPath implemented by lxml.etree; https://lxml.de/xpathxslt.html for more information. |
True |
|
Negate the outcome of the assertion. |
False |
element_text
:¶
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>
The assertion implicitly also asserts that an element matching path
exists.
With negate
the result of the implicit assertions can be inverted.
The sub-assertions, which have their own negate
attribute, are not affected
by negate
.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Path to check for. Valid paths are the simplified subsets of XPath implemented by lxml.etree; https://lxml.de/xpathxslt.html for more information. |
True |
|
Negate the outcome of the assertion. |
False |
Assertions for JSON data¶
has_json_property_with_value
:¶
Asserts the JSON document contains a property or key with the specified JSON value.
<has_json_property_with_value property="skipped_columns" value="[1, 3, 5]" />
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
JSON-ified value to search for. This will be converted from an XML string to JSON with Python’s json.loads function. |
True |
|
JSON property to search the target for. |
True |
has_json_property_with_text
:¶
Asserts the JSON document contains a property or key with the specified text (i.e. string) value.
<has_json_property_with_text property="color" text="red" />
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Text value to search for. |
True |
|
JSON property to search the target for. |
True |
Assertions for H5 data¶
has_h5_keys
:¶
Asserts HDF5 output has a set of attributes (keys
), specified as a
comma-separated list, e.g.
<has_h5_keys keys="bins,chroms,indexes,pixels,chroms/lengths" />
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Comma-separated list of HDF5 attributes to check for. |
False |
has_h5_attribute
:¶
Asserts HDF5 output contains the specified value
for an attribute (key
), e.g.
<has_h5_attribute key="nchroms" value="15" />
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
HDF5 attribute to check value of. |
False |
|
Expected value of HDF5 attribute to check. |
False |
Examples¶
The following demonstrates a wide variety of text-based and tabular assertion statements.
<output name="out_file1">
<assert_contents>
<has_text text="chr7" />
<not_has_text text="chr8" />
<has_text_matching expression="1274\d+53" />
<has_line_matching expression=".*\s+127489808\s+127494553" />
<!-- 	 is XML escape code for tab -->
<has_line line="chr7	127471195	127489808" />
<has_n_columns n="3" />
</assert_contents>
</output>
The following demonstrates a wide variety of XML assertion statements.
<output name="out_file1">
<assert_contents>
<is_valid_xml />
<has_element_with_path path="BlastOutput_param/Parameters/Parameters_matrix" />
<has_n_elements_with_path n="9" path="BlastOutput_iterations/Iteration/Iteration_hits/Hit/Hit_num" />
<element_text_matches path="BlastOutput_version" expression="BLASTP\s+2\.2.*" />
<element_text_is path="BlastOutput_program" text="blastp" />
<element_text path="BlastOutput_iterations/Iteration/Iteration_hits/Hit/Hit_def">
<not_has_text text="EDK72998.1" />
<has_text_matching expression="ABK[\d\.]+" />
</element_text>
</assert_contents>
</output>
The following demonstrates verifying XML content with XPath-like expressions.
<output name="out_file1">
<assert_contents>
<attribute_is path="outerElement/innerElement1" attribute="foo" text="bar" />
<attribute_matches path="outerElement/innerElement2" attribute="foo2" expression="bar\d+" />
</assert_contents>
</output>
tool
> tests
> test
> output_collection
¶
Define tests for extra datasets and metadata 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.
For tools marked as having profile 20.09 or newer, the order of elements within
an output_collection
declaration are meaningful. The test definition may
omit any number of elements from a collection, but the ones that are specified
will be checked against the actual resulting collection from the tool run and the
order within the collection verified.
Examples¶
The genetrack
tool demonstrates basic usage of an output_collection
test expectation.
<test>
<param name="input" value="genetrack_input2.gff" ftype="gff" />
<param name="input_format" value="gff" />
<param name="sigma" value="5" />
<param name="exclusion" value="20" />
<param name="up_width" value="10" />
<param name="down_width" value="10" />
<param name="filter" value="3" />
<output_collection name="genetrack_output" type="list">
<element name="s5e20u10d10F3_on_data_1" file="genetrack_output2.gff" ftype="gff" />
</output_collection>
</test>
The CWPair2
tool demonstrates that element
s can specify a compare
attribute just
like output.
<test>
<param name="input" value="cwpair2_input1.gff" />
<param name="up_distance" value="25" />
<param name="down_distance" value="100" />
<param name="method" value="all" />
<param name="binsize" value="1" />
<param name="threshold_format" value="relative_threshold" />
<param name="relative_threshold" value="0.0" />
<param name="output_files" value="matched_pair" />
<output name="statistics_output" file="statistics1.tabular" ftype="tabular" />
<output_collection name="MP" type="list">
<element name="data_MP_closest_f0u25d100_on_data_1.gff" file="closest_mp_output1.gff" ftype="gff" compare="contains"/>
<element name="data_MP_largest_f0u25d100_on_data_1.gff" file="largest_mp_output1.gff" ftype="gff" compare="contains"/>
<element name="data_MP_mode_f0u25d100_on_data_1.gff" file="mode_mp_output1.gff" ftype="gff" compare="contains"/>
</output_collection>
</test>
The
collection_creates_dynamic_nested
test tool demonstrates the use of nested element
directives as described
above. Notice also that it tests the output with assert_contents
instead of
supplying a file
attribute. Like hinted at with with compare
attribute
above, the element
tag can specify any of the test attributes that apply to
the output (e.g. md5
, compare
, diff
,
etc…).
<test>
<param name="foo" value="bar" />
<output_collection name="list_output" type="list:list">
<element name="oe1">
<element name="ie1">
<assert_contents>
<has_text_matching expression="^A\n$" />
</assert_contents>
</element>
<element name="ie2">
<assert_contents>
<has_text_matching expression="^B\n$" />
</assert_contents>
</element>
</element>
<element name="oe2">
<element name="ie1">
<assert_contents>
<has_text_matching expression="^C\n$" />
</assert_contents>
</element>
<element name="ie2">
<assert_contents>
<has_text_matching expression="^D\n$" />
</assert_contents>
</element>
</element>
<element name="oe3">
<element name="ie1">
<assert_contents>
<has_text_matching expression="^E\n$" />
</assert_contents>
</element>
<element name="ie2">
<assert_contents>
<has_text_matching expression="^F\n$" />
</assert_contents>
</element>
</element>
</output_collection>
</test>
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
This value is the same as the value of the |
True |
|
Expected collection type ( |
False |
|
Number of elements in output collection. |
False |
tool
> tests
> test
> assert_command
¶
Describe assertions about the job’s generated command-line.
This tag set defines a sequence of checks or assertions to run against the target output. This tag requires no attributes, but child tags should be used to define the assertions to make about the output. The functional test framework makes it easy to extend Galaxy with such tags, the following table summarizes many of the default assertion tags that come with Galaxy and examples of each can be found below.
The implementation of these tags are simply Python functions defined in the /lib/galaxy/tool_util/verify/asserts module.
General assertions¶
has_size
:¶
Asserts the output has a specific size (in bytes) of value
plus minus
delta
, e.g. <has_size value="10000" delta="100" />
.
Alternatively the range of the expected size can be specified by min
and/or
max
.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Desired size of the output (in bytes), can be suffixed by ``(k |
M |
|
Maximum allowed size difference (default is 0). The observed size has to be in the range |
M |
|
Minimum expected size, can be suffixed by ``(k |
M |
|
Maximum expected size, can be suffixed by ``(k |
M |
|
Negate the outcome of the assertion. |
False |
Assertions for text data¶
has_text
:¶
Asserts the specified text
appears in the output (e.g. <has_text text="chr7">
). If the text
is expected to occur a particular number of
times, this value can be specified using n
. Optionally also with a certain
delta
. Alternatively the range of expected occurences can be specified by
min
and/or max
.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Text to check for |
True |
|
Desired number, can be suffixed by ``(k |
M |
|
Allowed difference with respect to n (default: 0), can be suffixed by ``(k |
M |
|
Minimum number (default: -infinity), can be suffixed by ``(k |
M |
|
Maximum number (default: infinity), can be suffixed by ``(k |
M |
|
Negate the outcome of the assertion. |
False |
not_has_text
:¶
Asserts the specified text
does not appear in the output (e.g. <not_has_text text="chr8" />
).
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Text to check for |
True |
has_text_matching
:¶
Asserts text matching the specified regular expression (expression
) appears
in the output (e.g. <has_text_matching expression="1274\d+53" />
). If the
regular expression is expected to match a particular number of times, this value
can be specified using n
. Note only non-overlapping occurences are counted.
Optionally also with a certain delta
. Alternatively the range of expected
occurences can be specified by min
and/or max
.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Regular expression to check for |
True |
|
Desired number, can be suffixed by ``(k |
M |
|
Allowed difference with respect to n (default: 0), can be suffixed by ``(k |
M |
|
Minimum number (default: -infinity), can be suffixed by ``(k |
M |
|
Maximum number (default: infinity), can be suffixed by ``(k |
M |
|
Negate the outcome of the assertion. |
False |
has_line
:¶
Asserts a line matching the specified string (line
) appears in the output
(e.g. <has_line line="A full example line." />
). If the line
is expected
to occur a particular number of times, this value can be specified using n
.
Optionally also with a certain delta
. Alternatively the range of expected
occurences can be specified by min
and/or max
.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
The line to check for |
True |
|
Desired number, can be suffixed by ``(k |
M |
|
Allowed difference with respect to n (default: 0), can be suffixed by ``(k |
M |
|
Minimum number (default: -infinity), can be suffixed by ``(k |
M |
|
Maximum number (default: infinity), can be suffixed by ``(k |
M |
|
Negate the outcome of the assertion. |
False |
has_line_matching
:¶
Asserts a line matching the specified regular expression (expression
)
appears in the output (e.g. <has_line_matching expression=".*\s+127489808\s+127494553" />
).
If a particular number of matching lines is expected, this value can be
specified using n
. Optionally also with delta
. Alternatively the range
of expected occurences can be specified by min
and/or max
.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Regular expression to check for |
True |
|
Desired number, can be suffixed by ``(k |
M |
|
Allowed difference with respect to n (default: 0), can be suffixed by ``(k |
M |
|
Minimum number (default: -infinity), can be suffixed by ``(k |
M |
|
Maximum number (default: infinity), can be suffixed by ``(k |
M |
|
Negate the outcome of the assertion. |
False |
has_n_lines
:¶
Asserts that an output contains n
lines, allowing for a difference of
delta
(default is 0), e.g. <has_n_lines n="3" delta="1"/>
.
Alternatively the range of expected occurences can be specified by min
and/or max
.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Desired number, can be suffixed by ``(k |
M |
|
Allowed difference with respect to n (default: 0), can be suffixed by ``(k |
M |
|
Minimum number (default: -infinity), can be suffixed by ``(k |
M |
|
Maximum number (default: infinity), can be suffixed by ``(k |
M |
|
Negate the outcome of the assertion. |
False |
Assertions for tabular data¶
has_n_columns
:¶
Asserts tabular output (actually only the first line) contains the specified
number (n
) of columns (e.g. <has_n_columns n="3"/>
) optionally also with
delta
. Alternatively the range of expected occurences can be specified by
min
and/or max
. Optionally a column separator (sep
, default is
\t
) `and comment character(s) can be specified (comment
, default is
empty string), then the first non-comment line is used for determining the
number of columns.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Separator defining columns, default: tab |
False |
|
Comment character(s) used to skip comment lines (which should not be used for counting columns) |
False |
|
Desired number, can be suffixed by ``(k |
M |
|
Allowed difference with respect to n (default: 0), can be suffixed by ``(k |
M |
|
Minimum number (default: -infinity), can be suffixed by ``(k |
M |
|
Maximum number (default: infinity), can be suffixed by ``(k |
M |
|
Negate the outcome of the assertion. |
False |
Assertions for archives (zip/tar)¶
has_archive_member
:¶
This tag allows to check if path
is contained in a compressed file. The path
is a regular expression that is matched against the full paths of the objects in
the compressed file (remember that “matching” means it is checked if a prefix of
the full path of an archive member is described by the regular expression).
Valid archive formats include .zip
, .tar
, and .tar.gz
. Note that
depending on the archive creation method:
full paths of the members may be prefixed with
./
directories may be treated as empty files
<has_archive_member path="./path/to/my-file.txt"/>
With n
and delta
(or min
and max
) assertions on the number of
archive members matching path
can be expressed. The following could be used,
e.g., to assert an archive containing n±1 elements out of which at least
4 need to have a txt
extension.
<has_archive_member path=".*" n="10" delta="1"/>
<has_archive_member path=".*\.txt" min="4"/>
In addition the tag can contain additional assertions as child elements about
the first member in the archive matching the regular expression path
. For
instance
<has_archive_member path=".*/my-file.txt">
<not_has_text text="EDK72998.1"/>
</has_archive_member>
If the all
attribute is set to true
then all archive members are subject
to the assertions. Note that, archive members matching the path
are sorted
alphabetically.
The negate
attribute of the has_archive_member
assertion only affects
the asserts on the presence and number of matching archive members, but not any
sub-assertions (which can offer the negate
attribute on their own). The
check if the file is an archive at all, which is also done by the function, is
not affected.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
The regular expression specifying the archive member. |
False |
|
Check the sub-assertions for all paths matching the path. Default: false, i.e. only the first |
False |
|
Desired number, can be suffixed by ``(k |
M |
|
Allowed difference with respect to n (default: 0), can be suffixed by ``(k |
M |
|
Minimum number (default: -infinity), can be suffixed by ``(k |
M |
|
Maximum number (default: infinity), can be suffixed by ``(k |
M |
Assertions for XML data¶
is_valid_xml
:¶
Asserts the output is a valid XML file (e.g. <is_valid_xml />
).
xml_element
:¶
Assert if the XML file contains element(s) or tag(s) with the specified
XPath-like path
. If n
and delta
or min
and max
are given also the number of occurences is checked.
<assert_contents>
<xml_element path="./elem"/>
<xml_element path="./elem/more[2]"/>
<xml_element path=".//more" n="3" delta="1"/>
</assert_contents>
With negate="true"
the outcome of the assertions wrt the precence and number
of path
can be negated. If there are any sub assertions then check them against
the content of the attribute
attribute
the element’s text if no attribute is given
<assert_contents>
<xml_element path="./elem/more[2]" attribute="name">
<has_text_matching expression="foo$"/>
</xml_element>
</assert_contents>
Sub-assertions are not subject to the negate
attribute of xml_element
.
If all
is true
then the sub assertions are checked for all occurences.
Note that all other XML assertions can be expressed by this assertion (Galaxy also implements the other assertions by calling this one).
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Check the sub-assertions for all paths matching the path. Default: false, i.e. only the first |
False |
|
The name of the attribute to apply sub-assertion on. If not given then the element text is used |
False |
|
Path to check for. Valid paths are the simplified subsets of XPath implemented by lxml.etree; https://lxml.de/xpathxslt.html for more information. |
True |
|
Desired number, can be suffixed by ``(k |
M |
|
Allowed difference with respect to n (default: 0), can be suffixed by ``(k |
M |
|
Minimum number (default: -infinity), can be suffixed by ``(k |
M |
|
Maximum number (default: infinity), can be suffixed by ``(k |
M |
|
Negate the outcome of the assertion. |
False |
has_element_with_path
:¶
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" />
With negate
the result of the assertion can be inverted.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Path to check for. Valid paths are the simplified subsets of XPath implemented by lxml.etree; https://lxml.de/xpathxslt.html for more information. |
True |
|
Negate the outcome of the assertion. |
False |
has_n_elements_with_path
:¶
Asserts the XML output contains the specified number (n
, optionally with delta
) 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" />
Alternatively to n
and delta
also the min
and max
attributes
can be used to specify the range of the expected number of occurences.
With negate
the result of the assertion can be inverted.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Path to check for. Valid paths are the simplified subsets of XPath implemented by lxml.etree; https://lxml.de/xpathxslt.html for more information. |
True |
|
Desired number, can be suffixed by ``(k |
M |
|
Allowed difference with respect to n (default: 0), can be suffixed by ``(k |
M |
|
Minimum number (default: -infinity), can be suffixed by ``(k |
M |
|
Maximum number (default: infinity), can be suffixed by ``(k |
M |
|
Negate the outcome of the assertion. |
False |
element_text_matches
:¶
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.*"/>
The assertion implicitly also asserts that an element matching path
exists.
With negate
the result of the assertion (on the matching) can be inverted (the
implicit assertion on the existence of the path is not affected).
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
The regular expression to use. |
True |
|
Path to check for. Valid paths are the simplified subsets of XPath implemented by lxml.etree; https://lxml.de/xpathxslt.html for more information. |
True |
|
Negate the outcome of the assertion. |
False |
element_text_is
:¶
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" />
The assertion implicitly also asserts that an element matching path
exists.
With negate
the result of the assertion (on the equality) can be inverted (the
implicit assertion on the existence of the path is not affected).
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Text to check for. |
True |
|
Path to check for. Valid paths are the simplified subsets of XPath implemented by lxml.etree; https://lxml.de/xpathxslt.html for more information. |
True |
|
Negate the outcome of the assertion. |
False |
attribute_matches
:¶
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+" />
The assertion implicitly also asserts that an element matching path
exists.
With negate
the result of the assertion (on the matching) can be inverted (the
implicit assertion on the existence of the path is not affected).
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
The regular expression to use. |
True |
|
Path to check for. Valid paths are the simplified subsets of XPath implemented by lxml.etree; https://lxml.de/xpathxslt.html for more information. |
True |
|
Negate the outcome of the assertion. |
False |
attribute_is
:¶
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" />
The assertion implicitly also asserts that an element matching path
exists.
With negate
the result of the assertion (on the equality) can be inverted (the
implicit assertion on the existence of the path is not affected).
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Text to check for. |
True |
|
Path to check for. Valid paths are the simplified subsets of XPath implemented by lxml.etree; https://lxml.de/xpathxslt.html for more information. |
True |
|
Negate the outcome of the assertion. |
False |
element_text
:¶
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>
The assertion implicitly also asserts that an element matching path
exists.
With negate
the result of the implicit assertions can be inverted.
The sub-assertions, which have their own negate
attribute, are not affected
by negate
.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Path to check for. Valid paths are the simplified subsets of XPath implemented by lxml.etree; https://lxml.de/xpathxslt.html for more information. |
True |
|
Negate the outcome of the assertion. |
False |
Assertions for JSON data¶
has_json_property_with_value
:¶
Asserts the JSON document contains a property or key with the specified JSON value.
<has_json_property_with_value property="skipped_columns" value="[1, 3, 5]" />
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
JSON-ified value to search for. This will be converted from an XML string to JSON with Python’s json.loads function. |
True |
|
JSON property to search the target for. |
True |
has_json_property_with_text
:¶
Asserts the JSON document contains a property or key with the specified text (i.e. string) value.
<has_json_property_with_text property="color" text="red" />
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Text value to search for. |
True |
|
JSON property to search the target for. |
True |
Assertions for H5 data¶
has_h5_keys
:¶
Asserts HDF5 output has a set of attributes (keys
), specified as a
comma-separated list, e.g.
<has_h5_keys keys="bins,chroms,indexes,pixels,chroms/lengths" />
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Comma-separated list of HDF5 attributes to check for. |
False |
has_h5_attribute
:¶
Asserts HDF5 output contains the specified value
for an attribute (key
), e.g.
<has_h5_attribute key="nchroms" value="15" />
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
HDF5 attribute to check value of. |
False |
|
Expected value of HDF5 attribute to check. |
False |
tool
> tests
> test
> assert_stdout
¶
Describe assertions about the job’s standard output.
This tag set defines a sequence of checks or assertions to run against the target output. This tag requires no attributes, but child tags should be used to define the assertions to make about the output. The functional test framework makes it easy to extend Galaxy with such tags, the following table summarizes many of the default assertion tags that come with Galaxy and examples of each can be found below.
The implementation of these tags are simply Python functions defined in the /lib/galaxy/tool_util/verify/asserts module.
General assertions¶
has_size
:¶
Asserts the output has a specific size (in bytes) of value
plus minus
delta
, e.g. <has_size value="10000" delta="100" />
.
Alternatively the range of the expected size can be specified by min
and/or
max
.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Desired size of the output (in bytes), can be suffixed by ``(k |
M |
|
Maximum allowed size difference (default is 0). The observed size has to be in the range |
M |
|
Minimum expected size, can be suffixed by ``(k |
M |
|
Maximum expected size, can be suffixed by ``(k |
M |
|
Negate the outcome of the assertion. |
False |
Assertions for text data¶
has_text
:¶
Asserts the specified text
appears in the output (e.g. <has_text text="chr7">
). If the text
is expected to occur a particular number of
times, this value can be specified using n
. Optionally also with a certain
delta
. Alternatively the range of expected occurences can be specified by
min
and/or max
.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Text to check for |
True |
|
Desired number, can be suffixed by ``(k |
M |
|
Allowed difference with respect to n (default: 0), can be suffixed by ``(k |
M |
|
Minimum number (default: -infinity), can be suffixed by ``(k |
M |
|
Maximum number (default: infinity), can be suffixed by ``(k |
M |
|
Negate the outcome of the assertion. |
False |
not_has_text
:¶
Asserts the specified text
does not appear in the output (e.g. <not_has_text text="chr8" />
).
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Text to check for |
True |
has_text_matching
:¶
Asserts text matching the specified regular expression (expression
) appears
in the output (e.g. <has_text_matching expression="1274\d+53" />
). If the
regular expression is expected to match a particular number of times, this value
can be specified using n
. Note only non-overlapping occurences are counted.
Optionally also with a certain delta
. Alternatively the range of expected
occurences can be specified by min
and/or max
.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Regular expression to check for |
True |
|
Desired number, can be suffixed by ``(k |
M |
|
Allowed difference with respect to n (default: 0), can be suffixed by ``(k |
M |
|
Minimum number (default: -infinity), can be suffixed by ``(k |
M |
|
Maximum number (default: infinity), can be suffixed by ``(k |
M |
|
Negate the outcome of the assertion. |
False |
has_line
:¶
Asserts a line matching the specified string (line
) appears in the output
(e.g. <has_line line="A full example line." />
). If the line
is expected
to occur a particular number of times, this value can be specified using n
.
Optionally also with a certain delta
. Alternatively the range of expected
occurences can be specified by min
and/or max
.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
The line to check for |
True |
|
Desired number, can be suffixed by ``(k |
M |
|
Allowed difference with respect to n (default: 0), can be suffixed by ``(k |
M |
|
Minimum number (default: -infinity), can be suffixed by ``(k |
M |
|
Maximum number (default: infinity), can be suffixed by ``(k |
M |
|
Negate the outcome of the assertion. |
False |
has_line_matching
:¶
Asserts a line matching the specified regular expression (expression
)
appears in the output (e.g. <has_line_matching expression=".*\s+127489808\s+127494553" />
).
If a particular number of matching lines is expected, this value can be
specified using n
. Optionally also with delta
. Alternatively the range
of expected occurences can be specified by min
and/or max
.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Regular expression to check for |
True |
|
Desired number, can be suffixed by ``(k |
M |
|
Allowed difference with respect to n (default: 0), can be suffixed by ``(k |
M |
|
Minimum number (default: -infinity), can be suffixed by ``(k |
M |
|
Maximum number (default: infinity), can be suffixed by ``(k |
M |
|
Negate the outcome of the assertion. |
False |
has_n_lines
:¶
Asserts that an output contains n
lines, allowing for a difference of
delta
(default is 0), e.g. <has_n_lines n="3" delta="1"/>
.
Alternatively the range of expected occurences can be specified by min
and/or max
.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Desired number, can be suffixed by ``(k |
M |
|
Allowed difference with respect to n (default: 0), can be suffixed by ``(k |
M |
|
Minimum number (default: -infinity), can be suffixed by ``(k |
M |
|
Maximum number (default: infinity), can be suffixed by ``(k |
M |
|
Negate the outcome of the assertion. |
False |
Assertions for tabular data¶
has_n_columns
:¶
Asserts tabular output (actually only the first line) contains the specified
number (n
) of columns (e.g. <has_n_columns n="3"/>
) optionally also with
delta
. Alternatively the range of expected occurences can be specified by
min
and/or max
. Optionally a column separator (sep
, default is
\t
) `and comment character(s) can be specified (comment
, default is
empty string), then the first non-comment line is used for determining the
number of columns.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Separator defining columns, default: tab |
False |
|
Comment character(s) used to skip comment lines (which should not be used for counting columns) |
False |
|
Desired number, can be suffixed by ``(k |
M |
|
Allowed difference with respect to n (default: 0), can be suffixed by ``(k |
M |
|
Minimum number (default: -infinity), can be suffixed by ``(k |
M |
|
Maximum number (default: infinity), can be suffixed by ``(k |
M |
|
Negate the outcome of the assertion. |
False |
Assertions for archives (zip/tar)¶
has_archive_member
:¶
This tag allows to check if path
is contained in a compressed file. The path
is a regular expression that is matched against the full paths of the objects in
the compressed file (remember that “matching” means it is checked if a prefix of
the full path of an archive member is described by the regular expression).
Valid archive formats include .zip
, .tar
, and .tar.gz
. Note that
depending on the archive creation method:
full paths of the members may be prefixed with
./
directories may be treated as empty files
<has_archive_member path="./path/to/my-file.txt"/>
With n
and delta
(or min
and max
) assertions on the number of
archive members matching path
can be expressed. The following could be used,
e.g., to assert an archive containing n±1 elements out of which at least
4 need to have a txt
extension.
<has_archive_member path=".*" n="10" delta="1"/>
<has_archive_member path=".*\.txt" min="4"/>
In addition the tag can contain additional assertions as child elements about
the first member in the archive matching the regular expression path
. For
instance
<has_archive_member path=".*/my-file.txt">
<not_has_text text="EDK72998.1"/>
</has_archive_member>
If the all
attribute is set to true
then all archive members are subject
to the assertions. Note that, archive members matching the path
are sorted
alphabetically.
The negate
attribute of the has_archive_member
assertion only affects
the asserts on the presence and number of matching archive members, but not any
sub-assertions (which can offer the negate
attribute on their own). The
check if the file is an archive at all, which is also done by the function, is
not affected.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
The regular expression specifying the archive member. |
False |
|
Check the sub-assertions for all paths matching the path. Default: false, i.e. only the first |
False |
|
Desired number, can be suffixed by ``(k |
M |
|
Allowed difference with respect to n (default: 0), can be suffixed by ``(k |
M |
|
Minimum number (default: -infinity), can be suffixed by ``(k |
M |
|
Maximum number (default: infinity), can be suffixed by ``(k |
M |
Assertions for XML data¶
is_valid_xml
:¶
Asserts the output is a valid XML file (e.g. <is_valid_xml />
).
xml_element
:¶
Assert if the XML file contains element(s) or tag(s) with the specified
XPath-like path
. If n
and delta
or min
and max
are given also the number of occurences is checked.
<assert_contents>
<xml_element path="./elem"/>
<xml_element path="./elem/more[2]"/>
<xml_element path=".//more" n="3" delta="1"/>
</assert_contents>
With negate="true"
the outcome of the assertions wrt the precence and number
of path
can be negated. If there are any sub assertions then check them against
the content of the attribute
attribute
the element’s text if no attribute is given
<assert_contents>
<xml_element path="./elem/more[2]" attribute="name">
<has_text_matching expression="foo$"/>
</xml_element>
</assert_contents>
Sub-assertions are not subject to the negate
attribute of xml_element
.
If all
is true
then the sub assertions are checked for all occurences.
Note that all other XML assertions can be expressed by this assertion (Galaxy also implements the other assertions by calling this one).
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Check the sub-assertions for all paths matching the path. Default: false, i.e. only the first |
False |
|
The name of the attribute to apply sub-assertion on. If not given then the element text is used |
False |
|
Path to check for. Valid paths are the simplified subsets of XPath implemented by lxml.etree; https://lxml.de/xpathxslt.html for more information. |
True |
|
Desired number, can be suffixed by ``(k |
M |
|
Allowed difference with respect to n (default: 0), can be suffixed by ``(k |
M |
|
Minimum number (default: -infinity), can be suffixed by ``(k |
M |
|
Maximum number (default: infinity), can be suffixed by ``(k |
M |
|
Negate the outcome of the assertion. |
False |
has_element_with_path
:¶
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" />
With negate
the result of the assertion can be inverted.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Path to check for. Valid paths are the simplified subsets of XPath implemented by lxml.etree; https://lxml.de/xpathxslt.html for more information. |
True |
|
Negate the outcome of the assertion. |
False |
has_n_elements_with_path
:¶
Asserts the XML output contains the specified number (n
, optionally with delta
) 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" />
Alternatively to n
and delta
also the min
and max
attributes
can be used to specify the range of the expected number of occurences.
With negate
the result of the assertion can be inverted.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Path to check for. Valid paths are the simplified subsets of XPath implemented by lxml.etree; https://lxml.de/xpathxslt.html for more information. |
True |
|
Desired number, can be suffixed by ``(k |
M |
|
Allowed difference with respect to n (default: 0), can be suffixed by ``(k |
M |
|
Minimum number (default: -infinity), can be suffixed by ``(k |
M |
|
Maximum number (default: infinity), can be suffixed by ``(k |
M |
|
Negate the outcome of the assertion. |
False |
element_text_matches
:¶
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.*"/>
The assertion implicitly also asserts that an element matching path
exists.
With negate
the result of the assertion (on the matching) can be inverted (the
implicit assertion on the existence of the path is not affected).
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
The regular expression to use. |
True |
|
Path to check for. Valid paths are the simplified subsets of XPath implemented by lxml.etree; https://lxml.de/xpathxslt.html for more information. |
True |
|
Negate the outcome of the assertion. |
False |
element_text_is
:¶
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" />
The assertion implicitly also asserts that an element matching path
exists.
With negate
the result of the assertion (on the equality) can be inverted (the
implicit assertion on the existence of the path is not affected).
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Text to check for. |
True |
|
Path to check for. Valid paths are the simplified subsets of XPath implemented by lxml.etree; https://lxml.de/xpathxslt.html for more information. |
True |
|
Negate the outcome of the assertion. |
False |
attribute_matches
:¶
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+" />
The assertion implicitly also asserts that an element matching path
exists.
With negate
the result of the assertion (on the matching) can be inverted (the
implicit assertion on the existence of the path is not affected).
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
The regular expression to use. |
True |
|
Path to check for. Valid paths are the simplified subsets of XPath implemented by lxml.etree; https://lxml.de/xpathxslt.html for more information. |
True |
|
Negate the outcome of the assertion. |
False |
attribute_is
:¶
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" />
The assertion implicitly also asserts that an element matching path
exists.
With negate
the result of the assertion (on the equality) can be inverted (the
implicit assertion on the existence of the path is not affected).
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Text to check for. |
True |
|
Path to check for. Valid paths are the simplified subsets of XPath implemented by lxml.etree; https://lxml.de/xpathxslt.html for more information. |
True |
|
Negate the outcome of the assertion. |
False |
element_text
:¶
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>
The assertion implicitly also asserts that an element matching path
exists.
With negate
the result of the implicit assertions can be inverted.
The sub-assertions, which have their own negate
attribute, are not affected
by negate
.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Path to check for. Valid paths are the simplified subsets of XPath implemented by lxml.etree; https://lxml.de/xpathxslt.html for more information. |
True |
|
Negate the outcome of the assertion. |
False |
Assertions for JSON data¶
has_json_property_with_value
:¶
Asserts the JSON document contains a property or key with the specified JSON value.
<has_json_property_with_value property="skipped_columns" value="[1, 3, 5]" />
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
JSON-ified value to search for. This will be converted from an XML string to JSON with Python’s json.loads function. |
True |
|
JSON property to search the target for. |
True |
has_json_property_with_text
:¶
Asserts the JSON document contains a property or key with the specified text (i.e. string) value.
<has_json_property_with_text property="color" text="red" />
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Text value to search for. |
True |
|
JSON property to search the target for. |
True |
Assertions for H5 data¶
has_h5_keys
:¶
Asserts HDF5 output has a set of attributes (keys
), specified as a
comma-separated list, e.g.
<has_h5_keys keys="bins,chroms,indexes,pixels,chroms/lengths" />
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Comma-separated list of HDF5 attributes to check for. |
False |
has_h5_attribute
:¶
Asserts HDF5 output contains the specified value
for an attribute (key
), e.g.
<has_h5_attribute key="nchroms" value="15" />
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
HDF5 attribute to check value of. |
False |
|
Expected value of HDF5 attribute to check. |
False |
tool
> tests
> test
> assert_stderr
¶
Describe assertions about the job’s standard error.
This tag set defines a sequence of checks or assertions to run against the target output. This tag requires no attributes, but child tags should be used to define the assertions to make about the output. The functional test framework makes it easy to extend Galaxy with such tags, the following table summarizes many of the default assertion tags that come with Galaxy and examples of each can be found below.
The implementation of these tags are simply Python functions defined in the /lib/galaxy/tool_util/verify/asserts module.
General assertions¶
has_size
:¶
Asserts the output has a specific size (in bytes) of value
plus minus
delta
, e.g. <has_size value="10000" delta="100" />
.
Alternatively the range of the expected size can be specified by min
and/or
max
.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Desired size of the output (in bytes), can be suffixed by ``(k |
M |
|
Maximum allowed size difference (default is 0). The observed size has to be in the range |
M |
|
Minimum expected size, can be suffixed by ``(k |
M |
|
Maximum expected size, can be suffixed by ``(k |
M |
|
Negate the outcome of the assertion. |
False |
Assertions for text data¶
has_text
:¶
Asserts the specified text
appears in the output (e.g. <has_text text="chr7">
). If the text
is expected to occur a particular number of
times, this value can be specified using n
. Optionally also with a certain
delta
. Alternatively the range of expected occurences can be specified by
min
and/or max
.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Text to check for |
True |
|
Desired number, can be suffixed by ``(k |
M |
|
Allowed difference with respect to n (default: 0), can be suffixed by ``(k |
M |
|
Minimum number (default: -infinity), can be suffixed by ``(k |
M |
|
Maximum number (default: infinity), can be suffixed by ``(k |
M |
|
Negate the outcome of the assertion. |
False |
not_has_text
:¶
Asserts the specified text
does not appear in the output (e.g. <not_has_text text="chr8" />
).
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Text to check for |
True |
has_text_matching
:¶
Asserts text matching the specified regular expression (expression
) appears
in the output (e.g. <has_text_matching expression="1274\d+53" />
). If the
regular expression is expected to match a particular number of times, this value
can be specified using n
. Note only non-overlapping occurences are counted.
Optionally also with a certain delta
. Alternatively the range of expected
occurences can be specified by min
and/or max
.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Regular expression to check for |
True |
|
Desired number, can be suffixed by ``(k |
M |
|
Allowed difference with respect to n (default: 0), can be suffixed by ``(k |
M |
|
Minimum number (default: -infinity), can be suffixed by ``(k |
M |
|
Maximum number (default: infinity), can be suffixed by ``(k |
M |
|
Negate the outcome of the assertion. |
False |
has_line
:¶
Asserts a line matching the specified string (line
) appears in the output
(e.g. <has_line line="A full example line." />
). If the line
is expected
to occur a particular number of times, this value can be specified using n
.
Optionally also with a certain delta
. Alternatively the range of expected
occurences can be specified by min
and/or max
.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
The line to check for |
True |
|
Desired number, can be suffixed by ``(k |
M |
|
Allowed difference with respect to n (default: 0), can be suffixed by ``(k |
M |
|
Minimum number (default: -infinity), can be suffixed by ``(k |
M |
|
Maximum number (default: infinity), can be suffixed by ``(k |
M |
|
Negate the outcome of the assertion. |
False |
has_line_matching
:¶
Asserts a line matching the specified regular expression (expression
)
appears in the output (e.g. <has_line_matching expression=".*\s+127489808\s+127494553" />
).
If a particular number of matching lines is expected, this value can be
specified using n
. Optionally also with delta
. Alternatively the range
of expected occurences can be specified by min
and/or max
.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Regular expression to check for |
True |
|
Desired number, can be suffixed by ``(k |
M |
|
Allowed difference with respect to n (default: 0), can be suffixed by ``(k |
M |
|
Minimum number (default: -infinity), can be suffixed by ``(k |
M |
|
Maximum number (default: infinity), can be suffixed by ``(k |
M |
|
Negate the outcome of the assertion. |
False |
has_n_lines
:¶
Asserts that an output contains n
lines, allowing for a difference of
delta
(default is 0), e.g. <has_n_lines n="3" delta="1"/>
.
Alternatively the range of expected occurences can be specified by min
and/or max
.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Desired number, can be suffixed by ``(k |
M |
|
Allowed difference with respect to n (default: 0), can be suffixed by ``(k |
M |
|
Minimum number (default: -infinity), can be suffixed by ``(k |
M |
|
Maximum number (default: infinity), can be suffixed by ``(k |
M |
|
Negate the outcome of the assertion. |
False |
Assertions for tabular data¶
has_n_columns
:¶
Asserts tabular output (actually only the first line) contains the specified
number (n
) of columns (e.g. <has_n_columns n="3"/>
) optionally also with
delta
. Alternatively the range of expected occurences can be specified by
min
and/or max
. Optionally a column separator (sep
, default is
\t
) `and comment character(s) can be specified (comment
, default is
empty string), then the first non-comment line is used for determining the
number of columns.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Separator defining columns, default: tab |
False |
|
Comment character(s) used to skip comment lines (which should not be used for counting columns) |
False |
|
Desired number, can be suffixed by ``(k |
M |
|
Allowed difference with respect to n (default: 0), can be suffixed by ``(k |
M |
|
Minimum number (default: -infinity), can be suffixed by ``(k |
M |
|
Maximum number (default: infinity), can be suffixed by ``(k |
M |
|
Negate the outcome of the assertion. |
False |
Assertions for archives (zip/tar)¶
has_archive_member
:¶
This tag allows to check if path
is contained in a compressed file. The path
is a regular expression that is matched against the full paths of the objects in
the compressed file (remember that “matching” means it is checked if a prefix of
the full path of an archive member is described by the regular expression).
Valid archive formats include .zip
, .tar
, and .tar.gz
. Note that
depending on the archive creation method:
full paths of the members may be prefixed with
./
directories may be treated as empty files
<has_archive_member path="./path/to/my-file.txt"/>
With n
and delta
(or min
and max
) assertions on the number of
archive members matching path
can be expressed. The following could be used,
e.g., to assert an archive containing n±1 elements out of which at least
4 need to have a txt
extension.
<has_archive_member path=".*" n="10" delta="1"/>
<has_archive_member path=".*\.txt" min="4"/>
In addition the tag can contain additional assertions as child elements about
the first member in the archive matching the regular expression path
. For
instance
<has_archive_member path=".*/my-file.txt">
<not_has_text text="EDK72998.1"/>
</has_archive_member>
If the all
attribute is set to true
then all archive members are subject
to the assertions. Note that, archive members matching the path
are sorted
alphabetically.
The negate
attribute of the has_archive_member
assertion only affects
the asserts on the presence and number of matching archive members, but not any
sub-assertions (which can offer the negate
attribute on their own). The
check if the file is an archive at all, which is also done by the function, is
not affected.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
The regular expression specifying the archive member. |
False |
|
Check the sub-assertions for all paths matching the path. Default: false, i.e. only the first |
False |
|
Desired number, can be suffixed by ``(k |
M |
|
Allowed difference with respect to n (default: 0), can be suffixed by ``(k |
M |
|
Minimum number (default: -infinity), can be suffixed by ``(k |
M |
|
Maximum number (default: infinity), can be suffixed by ``(k |
M |
Assertions for XML data¶
is_valid_xml
:¶
Asserts the output is a valid XML file (e.g. <is_valid_xml />
).
xml_element
:¶
Assert if the XML file contains element(s) or tag(s) with the specified
XPath-like path
. If n
and delta
or min
and max
are given also the number of occurences is checked.
<assert_contents>
<xml_element path="./elem"/>
<xml_element path="./elem/more[2]"/>
<xml_element path=".//more" n="3" delta="1"/>
</assert_contents>
With negate="true"
the outcome of the assertions wrt the precence and number
of path
can be negated. If there are any sub assertions then check them against
the content of the attribute
attribute
the element’s text if no attribute is given
<assert_contents>
<xml_element path="./elem/more[2]" attribute="name">
<has_text_matching expression="foo$"/>
</xml_element>
</assert_contents>
Sub-assertions are not subject to the negate
attribute of xml_element
.
If all
is true
then the sub assertions are checked for all occurences.
Note that all other XML assertions can be expressed by this assertion (Galaxy also implements the other assertions by calling this one).
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Check the sub-assertions for all paths matching the path. Default: false, i.e. only the first |
False |
|
The name of the attribute to apply sub-assertion on. If not given then the element text is used |
False |
|
Path to check for. Valid paths are the simplified subsets of XPath implemented by lxml.etree; https://lxml.de/xpathxslt.html for more information. |
True |
|
Desired number, can be suffixed by ``(k |
M |
|
Allowed difference with respect to n (default: 0), can be suffixed by ``(k |
M |
|
Minimum number (default: -infinity), can be suffixed by ``(k |
M |
|
Maximum number (default: infinity), can be suffixed by ``(k |
M |
|
Negate the outcome of the assertion. |
False |
has_element_with_path
:¶
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" />
With negate
the result of the assertion can be inverted.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Path to check for. Valid paths are the simplified subsets of XPath implemented by lxml.etree; https://lxml.de/xpathxslt.html for more information. |
True |
|
Negate the outcome of the assertion. |
False |
has_n_elements_with_path
:¶
Asserts the XML output contains the specified number (n
, optionally with delta
) 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" />
Alternatively to n
and delta
also the min
and max
attributes
can be used to specify the range of the expected number of occurences.
With negate
the result of the assertion can be inverted.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Path to check for. Valid paths are the simplified subsets of XPath implemented by lxml.etree; https://lxml.de/xpathxslt.html for more information. |
True |
|
Desired number, can be suffixed by ``(k |
M |
|
Allowed difference with respect to n (default: 0), can be suffixed by ``(k |
M |
|
Minimum number (default: -infinity), can be suffixed by ``(k |
M |
|
Maximum number (default: infinity), can be suffixed by ``(k |
M |
|
Negate the outcome of the assertion. |
False |
element_text_matches
:¶
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.*"/>
The assertion implicitly also asserts that an element matching path
exists.
With negate
the result of the assertion (on the matching) can be inverted (the
implicit assertion on the existence of the path is not affected).
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
The regular expression to use. |
True |
|
Path to check for. Valid paths are the simplified subsets of XPath implemented by lxml.etree; https://lxml.de/xpathxslt.html for more information. |
True |
|
Negate the outcome of the assertion. |
False |
element_text_is
:¶
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" />
The assertion implicitly also asserts that an element matching path
exists.
With negate
the result of the assertion (on the equality) can be inverted (the
implicit assertion on the existence of the path is not affected).
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Text to check for. |
True |
|
Path to check for. Valid paths are the simplified subsets of XPath implemented by lxml.etree; https://lxml.de/xpathxslt.html for more information. |
True |
|
Negate the outcome of the assertion. |
False |
attribute_matches
:¶
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+" />
The assertion implicitly also asserts that an element matching path
exists.
With negate
the result of the assertion (on the matching) can be inverted (the
implicit assertion on the existence of the path is not affected).
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
The regular expression to use. |
True |
|
Path to check for. Valid paths are the simplified subsets of XPath implemented by lxml.etree; https://lxml.de/xpathxslt.html for more information. |
True |
|
Negate the outcome of the assertion. |
False |
attribute_is
:¶
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" />
The assertion implicitly also asserts that an element matching path
exists.
With negate
the result of the assertion (on the equality) can be inverted (the
implicit assertion on the existence of the path is not affected).
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Text to check for. |
True |
|
Path to check for. Valid paths are the simplified subsets of XPath implemented by lxml.etree; https://lxml.de/xpathxslt.html for more information. |
True |
|
Negate the outcome of the assertion. |
False |
element_text
:¶
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>
The assertion implicitly also asserts that an element matching path
exists.
With negate
the result of the implicit assertions can be inverted.
The sub-assertions, which have their own negate
attribute, are not affected
by negate
.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Path to check for. Valid paths are the simplified subsets of XPath implemented by lxml.etree; https://lxml.de/xpathxslt.html for more information. |
True |
|
Negate the outcome of the assertion. |
False |
Assertions for JSON data¶
has_json_property_with_value
:¶
Asserts the JSON document contains a property or key with the specified JSON value.
<has_json_property_with_value property="skipped_columns" value="[1, 3, 5]" />
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
JSON-ified value to search for. This will be converted from an XML string to JSON with Python’s json.loads function. |
True |
|
JSON property to search the target for. |
True |
has_json_property_with_text
:¶
Asserts the JSON document contains a property or key with the specified text (i.e. string) value.
<has_json_property_with_text property="color" text="red" />
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Text value to search for. |
True |
|
JSON property to search the target for. |
True |
Assertions for H5 data¶
has_h5_keys
:¶
Asserts HDF5 output has a set of attributes (keys
), specified as a
comma-separated list, e.g.
<has_h5_keys keys="bins,chroms,indexes,pixels,chroms/lengths" />
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Comma-separated list of HDF5 attributes to check for. |
False |
has_h5_attribute
:¶
Asserts HDF5 output contains the specified value
for an attribute (key
), e.g.
<has_h5_attribute key="nchroms" value="15" />
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
HDF5 attribute to check value of. |
False |
|
Expected value of HDF5 attribute to check. |
False |
tool
> help
¶
This tag set includes all of the necessary details of how to use the tool. This tag set should be included as the next to the last tag set, before citations, in the tool config. Tool help is written in reStructuredText. Included here is only an overview of a subset of features. For more information see here.
tag |
details |
---|---|
|
a yellow warning symbol |
|
a blue information symbol |
|
insert a png file of height 500 and width 600 at this position |
|
bold |
|
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.
<help>
.. class:: warningmark
'''TIP''' This tool requires *fasta* format.
----
'''Example'''
Query sequence::
>seq1
ATCG...
.. image:: my_figure.png
:height: 500
:width: 600
</help>
Best Practices¶
Find the Intergalactic Utilities Commision suggested best practices for this element here.
tool
> citations
¶
Tool files may declare one citations element. Each citations element can contain one or more citation tag elements - each of which specifies tool citation information using either a DOI or a BibTeX entry.
These citations will appear at the bottom of the tool form in a formatted way but the user will have to option to select RAW BibTeX for copying and pasting as well. Likewise, the history menu includes an option allowing users to aggregate all such citations across an analysis in a list of citations.
BibTeX entries for citations annotated with DOIs will be fetched by Galaxy from https://doi.org/ and cached.
<citations>
<!-- Example of annotating a citation using a DOI. -->
<citation type="doi">10.1093/bioinformatics/btq281</citation>
<!-- Example of annotating a citation using a BibTex entry. -->
<citation type="bibtex">@ARTICLE{Kim07aninterior-point,
author = {Seung-jean Kim and Kwangmoo Koh and Michael Lustig and Stephen Boyd and Dimitry Gorinevsky},
title = {An interior-point method for large-scale l1-regularized logistic regression},
journal = {Journal of Machine Learning Research},
year = {2007},
volume = {8},
pages = {1519-1555}
}</citation>
</citations>
For more implementation information see the pull request adding this feature. For more examples of how to add this to tools checkout the following commits adding this to the NCBI BLAST+ suite, phenotype association tools, MAF suite, and MACS2 suite.
This feature was added to the August 2014 release of Galaxy, tools annotated with citations will work in older releases of Galaxy but no citation information will be available to the end user.
tool
> citations
> citation
¶
Each citations element can contain one or
more citation
tag elements - each of which specifies tool citation
information using either a DOI or a BibTeX entry.
Attributes¶
Attribute |
Details |
Required |
---|---|---|
|
Type of citation - currently |
True |