comparison env/lib/python3.9/site-packages/galaxy/tool_util/xsd/galaxy.xsd @ 0:4f3585e2f14b draft default tip

"planemo upload commit 60cee0fc7c0cda8592644e1aad72851dec82c959"
author shellac
date Mon, 22 Mar 2021 18:12:50 +0000
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:4f3585e2f14b
1 <?xml version="1.0" encoding="UTF-8"?>
2 <xs:schema
3 xmlns:xs="http://www.w3.org/2001/XMLSchema"
4 xmlns:gxdocs="http://galaxyproject.org/xml/1.0"
5 elementFormDefault="qualified"
6 attributeFormDefault="unqualified"
7 >
8 <xs:annotation>
9 <xs:appinfo>Galaxy Schema</xs:appinfo>
10 <xs:documentation xml:lang="en">A Galaxy XML tool wrapper</xs:documentation>
11 </xs:annotation>
12
13 <xs:element name="tool">
14 <xs:annotation gxdocs:best_practices="tools">
15 <xs:documentation xml:lang="en"><![CDATA[
16 The outer-most tag set of tool XML files. Attributes on this tag apply to the
17 tool as a whole.
18
19 ### Examples
20
21 A normal tool:
22
23 ```xml
24 <tool id="seqtk_seq"
25 name="Convert FASTQ to FASTA"
26 version="1.0.0"
27 profile="16.04"
28 >
29 ```
30
31 A ``data_source`` tool contains a few more relevant attributes.
32
33 ```xml
34 <tool id="ucsc_table_direct1"
35 name="UCSC Main"
36 version="1.0.0"
37 hidden="false"
38 profile="16.01"
39 tool_type="data_source"
40 URL_method="post">
41 ```
42 ]]></xs:documentation>
43 </xs:annotation>
44 <xs:complexType>
45 <xs:all>
46 <!-- TODO: Move the anyType further into macros def... -->
47 <xs:element name="macros" type="Macros" minOccurs="0"/>
48 <xs:element name="edam_topics" type="EdamTopics" minOccurs="0"/>
49 <xs:element name="edam_operations" type="EdamOperations" minOccurs="0"/>
50 <xs:element name="xrefs" type="xrefs" minOccurs="0" />
51 <xs:element name="creator" type="Creator" minOccurs="0" />
52 <xs:element name="requirements" type="Requirements" minOccurs="0"/>
53 <xs:element name="entry_points" type="EntryPoints" minOccurs="0" maxOccurs="1" />
54 <xs:element name="description" type="xs:string" minOccurs="0">
55 <xs:annotation gxdocs:best_practices="tool-descriptions">
56 <xs:documentation xml:lang="en"><![CDATA[The value is displayed in
57 the tool menu immediately following the hyperlink for the tool (based on the
58 ``name`` attribute of the ``<tool>`` tag set described above).
59
60 ### Example
61
62 ```xml
63 <description>table browser</description>
64 ```
65 ]]></xs:documentation>
66 </xs:annotation>
67 </xs:element>
68 <xs:element name="parallelism" type="Parallelism" minOccurs="0"/>
69 <xs:element name="version_command" type="VersionCommand" minOccurs="0">
70 </xs:element>
71 <xs:element name="action" type="ToolAction" minOccurs="0" maxOccurs="1" />
72 <xs:element name="environment_variables" type="EnvironmentVariables" minOccurs="0" maxOccurs="1"/>
73 <xs:element name="command" type="Command" minOccurs="0" maxOccurs="1"/>
74 <xs:element name="expression" type="Expression" minOccurs="0" maxOccurs="1"/>
75 <xs:element name="request_param_translation" type="RequestParameterTranslation" minOccurs="0"/>
76 <xs:element name="configfiles" type="ConfigFiles" minOccurs="0"/>
77 <xs:element name="outputs" type="Outputs" minOccurs="0"/>
78 <xs:element name="inputs" type="Inputs" minOccurs="0"/>
79 <xs:element name="tests" type="Tests" minOccurs="0"/>
80 <xs:element name="stdio" type="Stdio" minOccurs="0"/>
81 <xs:element name="help" type="xs:string" minOccurs="0">
82 <xs:annotation gxdocs:best_practices="help-tag">
83 <xs:documentation xml:lang="en"><![CDATA[This tag set includes all of the necessary details of how to use the tool. This tag set should be included as the next to the last tag set, before citations, in the tool config. Tool help is written in reStructuredText. Included here is only an overview of a subset of features. For more information see [here](https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html).
84
85 tag | details
86 --- | -------
87 ``.. class:: warningmark`` | a yellow warning symbol
88 ``.. class:: infomark`` | a blue information symbol
89 ``.. image:: path-of-the-file.png :height: 500 :width: 600`` | insert a png file of height 500 and width 600 at this position |
90 ``**bold**`` | bold
91 ``*italic*`` | italic
92 ``*`` | list
93 ``-`` | list
94 ``::`` | paragraph
95 ``-----`` | a horizontal line
96
97 ### Examples
98
99 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.
100
101 ```xml
102 <help>
103
104 .. class:: warningmark
105
106 '''TIP''' This tool requires *fasta* format.
107
108 ----
109
110 '''Example'''
111
112 Query sequence::
113 >seq1
114 ATCG...
115
116 .. image:: my_figure.png
117 :height: 500
118 :width: 600
119
120 </help>
121 ```
122
123 ]]></xs:documentation>
124 </xs:annotation>
125 </xs:element>
126 <xs:element name="code" type="Code" minOccurs="0"/>
127 <xs:element name="uihints" type="UIhints" minOccurs="0"/>
128 <xs:element name="options" type="Options" minOccurs="0"/>
129 <xs:element name="trackster_conf" type="TracksterConf" minOccurs="0"/>
130 <xs:element name="citations" type="Citations" minOccurs="0"/>
131 </xs:all>
132 <xs:attribute name="id" type="xs:string" use="required">
133 <xs:annotation gxdocs:best_practices="tool-ids">
134 <xs:documentation xml:lang="en">Must be unique across all tools;
135 should be lowercase and contain only letters, numbers, and underscores.
136 It allows for tool versioning and metrics of the number of times a tool is used,
137 among other things.</xs:documentation>
138 </xs:annotation>
139 </xs:attribute>
140 <xs:attribute name="name" type="xs:string" use="required">
141 <xs:annotation gxdocs:best_practices="tool-names">
142 <xs:documentation xml:lang="en">This string is what is displayed as a
143 hyperlink in the tool menu.</xs:documentation>
144 </xs:annotation>
145 </xs:attribute>
146 <xs:attribute name="version" type="xs:string" default="1.0.0">
147 <xs:annotation gxdocs:best_practices="tool-versions">
148 <xs:documentation xml:lang="en">This string allows for tool versioning
149 and should be increased with each new version of the tool. The value should
150 follow the [PEP 440](https://www.python.org/dev/peps/pep-0440/) specification.
151 It defaults to ``1.0.0`` if it is not included in the tag.</xs:documentation>
152 </xs:annotation>
153 </xs:attribute>
154 <xs:attribute name="hidden" type="PermissiveBoolean" default="false">
155 <xs:annotation>
156 <xs:documentation xml:lang="en">Allows for tools to be loaded upon
157 server startup, but not displayed in the tool menu. This attribute should be
158 applied in the toolbox configuration instead and so should be considered
159 deprecated.
160 </xs:documentation>
161 </xs:annotation>
162 </xs:attribute>
163 <xs:attribute name="display_interface" type="PermissiveBoolean">
164 <xs:annotation>
165 <xs:documentation xml:lang="en">Disable the display the tool's
166 graphical tool form by setting this to ``false``.</xs:documentation>
167 </xs:annotation>
168 </xs:attribute>
169 <xs:attribute name="tool_type" type="ToolTypeType">
170 <xs:annotation>
171 <xs:documentation xml:lang="en">Allows for certain framework
172 functionality to be performed on certain types of tools. Normal tools that execute
173 typical command-line jobs do not need to specify this, special kinds of tools such
174 as [Data Source](https://galaxyproject.org/admin/internals/data-sources/) and
175 [Data Manager](https://galaxyproject.org/admin/tools/data-managers/) tools should
176 set this to have values such as ``data_source`` or ``manage_data``.</xs:documentation>
177 </xs:annotation>
178 </xs:attribute>
179 <xs:attribute name="profile" type="xs:string">
180 <xs:annotation>
181 <xs:documentation xml:lang="en">This string specifies the minimum Galaxy
182 version that should be required to run this tool. Certain legacy behaviors such
183 as using standard error content to detect errors instead of exit code are disabled
184 automatically if profile is set to any version newer than ``16.01``, such as
185 ``16.04``.
186
187 16.04
188
189 - Disable implicit extra file collection. All dynamic extra file collection requires a `discover_datasets` tag.
190 - Disable `format="input"` and require explicit metadata targets (`metadata_source`, `format_source`).
191 - Disable `interpreter` use `$__tool_directory__`.
192 - Disable `$param_file` use `configfile`
193 - Disable default tool version of 1.0.0.
194 - Use non zero exit code as default stdio error condition (before non-empty stderr).
195
196 18.01
197
198 - Use a separate home directory for each job.
199 - Introduce `provided_metadata_style` with default `"default"` before `"legacy"`.
200
201 18.09
202
203 - References to other inputs need to be fully qualified by using `|`.
204 - Do not allow provided but illegal default values.
205 - Do not use Galaxy python environment for `manage_data` tools.
206
207 19.05
208
209 - Change default Python version from 2.7 to 3.5
210
211 20.05
212
213 - json config files:
214 - unselected optional `select` and `data_column` parameters get `None` instead of `"None"`
215 - multiple `select` and `data_column` parameters are lists (before comma separated string)
216
217 20.09
218
219 - Exit immediately if a command exits with a non-zero status (`set -e`)
220 - Assume sort order for collection elements
221 </xs:documentation>
222 </xs:annotation>
223 </xs:attribute>
224 <xs:attribute name="license" type="xs:string">
225 <xs:annotation>
226 <xs:documentation xml:lang="en">This string specifies any full URI or a
227 a short SPDX (https://spdx.org/licenses/) identifier for a license for this tool
228 wrapper. The tool wrapper version can be indepedent of the underlying tool. This
229 license covers the tool XML and associated scripts shipped with the tool.
230
231 This is interpreted as a schema.org license attribute (see also https://schema.org/license).
232 </xs:documentation>
233 </xs:annotation>
234 </xs:attribute>
235 <xs:attribute name="python_template_version" type="xs:float">
236 <xs:annotation>
237 <xs:documentation xml:lang="en">This string specifies the minimum Python
238 version that is able to fill the Cheetah sections of the tool. If unset defaults
239 to 2.7 if the profile is older than 19.05, otherwise defaults to 3.5. Galaxy will
240 attempt to convert Python statements in Cheetah sections using [future](http://python-future.org/)
241 if Galaxy is run on Python 3 and ``python_template_version`` is below 3.</xs:documentation>
242 </xs:annotation>
243 </xs:attribute>
244 <xs:attribute name="workflow_compatible" type="xs:boolean" default="true">
245 <xs:annotation>
246 <xs:documentation xml:lang="en">This attribute indicates if
247 this tool is usable within a workflow (defaults to ``true`` for normal tools and
248 ``false`` for data sources).</xs:documentation>
249 </xs:annotation>
250 </xs:attribute>
251 <xs:attribute name="URL_method" type="URLmethodType">
252 <xs:annotation>
253 <xs:documentation xml:lang="en">Only used if ``tool_type`` attribute value
254 is ``data_source`` - this attribute defines the HTTP request method to use when
255 communicating with an external data source application (the default is ``get``).</xs:documentation>
256 </xs:annotation>
257 </xs:attribute>
258 </xs:complexType>
259 </xs:element>
260
261 <xs:complexType name="Macros">
262 <xs:annotation>
263 <xs:documentation xml:lang="en">Frequently, tools may require the same XML
264 fragments be repeated in a file (for instance similar conditional branches,
265 repeated options, etc...) or among tools in the same repository. Galaxy tools
266 have a macro system to address this problem.
267
268 For more information, see [planemo documentation](https://planemo.readthedocs.io/en/latest/writing_advanced.html#macros-reusable-elements)</xs:documentation>
269 </xs:annotation>
270 <xs:sequence>
271 <xs:element name="import" type="MacroImportType" minOccurs="0" maxOccurs="unbounded">
272 <xs:annotation>
273 <xs:documentation xml:lang="en"><![CDATA[
274 The ``import`` element allows specifying an XML file containing shared macro definitions that can then
275 be reused by all the tools contained in the same directory/repository.
276
277 Example:
278 ````
279 <macros>
280 <import>macros.xml</import>
281 </macros>
282 ````]]>
283 </xs:documentation>
284 </xs:annotation>
285 </xs:element>
286 <xs:element name="token" type="xs:anyType" minOccurs="0" maxOccurs="unbounded">
287 <xs:annotation>
288 <xs:documentation xml:lang="en"><![CDATA[
289 The ``token`` element defines a value, like a constant, that can then be replaced anywhere in any tool importing the token.
290
291 Definition example:
292 ````
293 <macros>
294 <token name="@TOOL_VERSION@">1.0.0</token>
295 </macros>
296 ````
297
298 Usage example:
299 ````
300 <requirements>
301 <requirement type="package" version="@TOOL_VERSION@">mypackage</requirement>
302 </requirements>
303 ````]]>
304 </xs:documentation>
305 </xs:annotation>
306 </xs:element>
307 <xs:element name="xml" type="xs:anyType" minOccurs="0" maxOccurs="unbounded">
308 <xs:annotation>
309 <xs:documentation xml:lang="en">
310 <![CDATA[
311 The ``xml`` element, inside macros, allows defining a named XML fragment that can be reused (expanded) anywhere in the tool or tools that use the macro.
312
313 Definition example:
314 ````
315 <macros>
316 <xml name="citations">
317 <citations>
318 ....
319 </citations>
320 </xml>
321 </macros>
322 ````
323
324 Usage example:
325 ````
326 <expand macro="citations" />
327 ````
328 ]]></xs:documentation>
329 </xs:annotation>
330 </xs:element>
331 </xs:sequence>
332 </xs:complexType>
333
334 <xs:complexType name="EntryPoints">
335 <xs:annotation>
336 <xs:documentation xml:lang="en"><![CDATA[
337
338 This is a container tag set for the ``entry_point`` tag that contains ``port`` and ``url`` tags
339 described in greater detail below. ``entry_point``s describe InteractiveTool entry points
340 to a tool.
341
342 ]]></xs:documentation>
343 </xs:annotation>
344 <xs:sequence>
345 <xs:element name="entry_point" type="EntryPoint" minOccurs="0" maxOccurs="unbounded"/>
346 </xs:sequence>
347 </xs:complexType>
348
349 <xs:complexType name="EntryPoint" mixed="true">
350 <xs:annotation>
351 <xs:documentation xml:lang="en"><![CDATA[
352
353 This tag set is contained within the ``<entry_point>`` tag set. Access to entry point
354 ports and urls are included in this tag set. These are used by InteractiveTools
355 to provide access to graphical tools in real-time.
356
357 ```xml
358 <entry_points>
359 <entry_point name="Example name">
360 <port>80</port>
361 <url>landing/${template_enabled}/index.html</url>
362 </entry_point>
363 </entry_points>
364 ```
365
366 ]]></xs:documentation>
367 </xs:annotation>
368 <xs:sequence>
369 <xs:element name="port" type="EntryPointPort" minOccurs="1" maxOccurs="1"/>
370 <xs:element name="url" type="EntryPointURL" minOccurs="0" maxOccurs="1"/>
371 </xs:sequence>
372 <xs:attribute name="name" type="xs:string" use="required">
373 <xs:annotation>
374 <xs:documentation xml:lang="en">This value defines the name of the entry point.</xs:documentation>
375 </xs:annotation>
376 </xs:attribute>
377 <xs:attribute name="requires_domain" type="PermissiveBoolean" default="false">
378 <xs:annotation>
379 <xs:documentation xml:lang="en">This value declares if domain-based proxying is required. Default is False. Currently only works when True.</xs:documentation>
380 </xs:annotation>
381 </xs:attribute>
382 </xs:complexType>
383 <xs:complexType name="EntryPointPort" mixed="true">
384 <xs:annotation>
385 <xs:documentation xml:lang="en"><![CDATA[
386
387 This tag set is contained within the ``<entry_point>`` tag set. It contains the entry port.
388
389 ]]></xs:documentation>
390 </xs:annotation>
391 </xs:complexType>
392 <xs:complexType name="EntryPointURL" mixed="true">
393 <xs:annotation>
394 <xs:documentation xml:lang="en"><![CDATA[
395
396 This tag set is contained within the ``<entry_point>`` tag set. It contains the entry URL.
397
398 ]]></xs:documentation>
399 </xs:annotation>
400 </xs:complexType>
401
402 <xs:complexType name="ToolAction">
403 <xs:annotation>
404 <xs:documentation xml:lang="en">Describe the backend Python action to execute for this Galaxy tool.</xs:documentation>
405 </xs:annotation>
406 <xs:sequence>
407 </xs:sequence>
408 <xs:attribute name="module" type="xs:string" use="required">
409 </xs:attribute>
410 <xs:attribute name="class" type="xs:string" use="required">
411 </xs:attribute>
412 </xs:complexType>
413
414 <xs:attributeGroup name="Thing">
415 <xs:attribute name="name" type="xs:string" use="optional">
416 <xs:annotation>
417 <xs:documentation>https://schema.org/name</xs:documentation>
418 </xs:annotation>
419 </xs:attribute>
420 <xs:attribute name="url" type="xs:string" use="optional">
421 <xs:annotation>
422 <xs:documentation>https://schema.org/url</xs:documentation>
423 </xs:annotation>
424 </xs:attribute>
425 <xs:attribute name="identifier" type="xs:string" use="optional">
426 <xs:annotation>
427 <xs:documentation>https://schema.org/identifier</xs:documentation>
428 </xs:annotation>
429 </xs:attribute>
430 <xs:attribute name="image" type="xs:string" use="optional">
431 <xs:annotation>
432 <xs:documentation>https://schema.org/image</xs:documentation>
433 </xs:annotation>
434 </xs:attribute>
435 <xs:attribute name="address" type="xs:string" use="optional">
436 <xs:annotation>
437 <xs:documentation>https://schema.org/address</xs:documentation>
438 </xs:annotation>
439 </xs:attribute>
440 <xs:attribute name="email" type="xs:string" use="optional">
441 <xs:annotation>
442 <xs:documentation>https://schema.org/email</xs:documentation>
443 </xs:annotation>
444 </xs:attribute>
445 <xs:attribute name="telephone" type="xs:string" use="optional">
446 <xs:annotation>
447 <xs:documentation>https://schema.org/telephone</xs:documentation>
448 </xs:annotation>
449 </xs:attribute>
450 <xs:attribute name="faxNumber" type="xs:string" use="optional">
451 <xs:annotation>
452 <xs:documentation>https://schema.org/faxNumber</xs:documentation>
453 </xs:annotation>
454 </xs:attribute>
455 <xs:attribute name="alternateName" type="xs:string" use="optional">
456 <xs:annotation>
457 <xs:documentation>https://schema.org/alternateName</xs:documentation>
458 </xs:annotation>
459 </xs:attribute>
460 </xs:attributeGroup>
461
462 <xs:complexType name="Person">
463 <xs:annotation>
464 <xs:documentation xml:lang="en"><![CDATA[
465 Describes a person. Tries to stay close to schema.org data model - see https://schema.org/Person.
466 ]]></xs:documentation>
467 </xs:annotation>
468 <xs:attributeGroup ref="Thing"/>
469 <xs:attribute name="givenName" type="xs:string" use="optional">
470 <xs:annotation>
471 <xs:documentation>https://schema.org/givenName</xs:documentation>
472 </xs:annotation>
473 </xs:attribute>
474 <xs:attribute name="familyName" type="xs:string" use="optional">
475 <xs:annotation>
476 <xs:documentation>https://schema.org/familyName</xs:documentation>
477 </xs:annotation>
478 </xs:attribute>
479 <xs:attribute name="honorificPrefix" type="xs:string" use="optional">
480 <xs:annotation>
481 <xs:documentation>https://schema.org/honorificPrefix</xs:documentation>
482 </xs:annotation>
483 </xs:attribute>
484 <xs:attribute name="honorificSuffix" type="xs:string" use="optional">
485 <xs:annotation>
486 <xs:documentation>https://schema.org/honorificSuffix</xs:documentation>
487 </xs:annotation>
488 </xs:attribute>
489 <xs:attribute name="jobTitle" type="xs:string" use="optional">
490 <xs:annotation>
491 <xs:documentation>https://schema.org/jobTitle</xs:documentation>
492 </xs:annotation>
493 </xs:attribute>
494 </xs:complexType>
495
496 <xs:complexType name="Organization">
497 <xs:annotation>
498 <xs:documentation xml:lang="en"><![CDATA[
499 Describes an organization. Tries to stay close to schema.org data model - see https://schema.org/Organization.
500 ]]></xs:documentation>
501 </xs:annotation>
502 <xs:attributeGroup ref="Thing"/>
503 </xs:complexType>
504
505 <xs:group name="PersonOrOrganization">
506 <xs:choice>
507 <xs:element name="person" type="Person" />
508 <xs:element name="organization" type="Organization" />
509 </xs:choice>
510 </xs:group>
511
512 <xs:complexType name="Creator">
513 <xs:annotation>
514 <xs:documentation xml:lang="en">The creator(s) of this work. See https://schema.org/creator.</xs:documentation>
515 </xs:annotation>
516 <xs:sequence>
517 <xs:group ref="PersonOrOrganization" minOccurs="0" maxOccurs="unbounded"/>
518 </xs:sequence>
519 </xs:complexType>
520
521 <xs:complexType name="Requirements">
522 <xs:annotation>
523 <xs:documentation xml:lang="en"><![CDATA[
524
525 This is a container tag set for the ``requirement`` and ``container`` tags
526 described in greater detail below. ``requirement``s describe software packages
527 and other individual computing requirements required to execute a tool, while
528 ``container``s describe Docker or Singularity containers that should be able to
529 serve as complete descriptions of the runtime of a tool.
530
531 ]]></xs:documentation>
532 </xs:annotation>
533 <xs:sequence>
534 <xs:element name="requirement" type="Requirement" minOccurs="0" maxOccurs="unbounded"/>
535 <xs:element name="container" type="Container" minOccurs="0" maxOccurs="unbounded"/>
536 </xs:sequence>
537 </xs:complexType>
538
539 <xs:complexType name="Requirement">
540 <xs:annotation>
541 <xs:documentation xml:lang="en"><![CDATA[
542
543 This tag set is contained within the ``<requirements>`` tag set. Third party
544 programs or modules that the tool depends upon are included in this tag set.
545
546 When a tool runs, Galaxy attempts to *resolve* these requirements (also called
547 dependencies). ``requirement``s are meant to be abstract and resolvable by
548 multiple different systems (e.g. [conda](https://conda.io/), the
549 [Galaxy Tool Shed dependency management system](https://galaxyproject.org/toolshed/tool-features/#Automatic_third-party_tool_dependency_installation_and_compilation_with_installed_repositories),
550 or [environment modules](http://modules.sourceforge.net/)).
551
552 Read more about dependency resolvers in Galaxy on
553 [docs.galaxyproject.org](https://docs.galaxyproject.org/en/master/admin/dependency_resolvers.html).
554 The current best practice for tool dependencies is to target Conda, this is
555 discussed in greater detail
556 [here](https://docs.galaxyproject.org/en/master/admin/conda_faq.html).
557
558 ### Examples
559
560 This example shows a tool that requires the samtools 0.0.18 package.
561
562 This package is available via the Tool Shed (see
563 [Tool Shed dependency management](https://galaxyproject.org/toolshed/tool-features/#Automatic_third-party_tool_dependency_installation_and_compilation_with_installed_repositories)
564 ) as well as [Conda](https://docs.galaxyproject.org/en/master/admin/conda_faq.html)
565 and can be configured locally to adapt to any other package management system.
566
567 ```xml
568 <requirements>
569 <requirement type="package" version="0.1.18">samtools</requirement>
570 </requirements>
571 ```
572
573 This older example shows a tool that requires R version 2.15.1. The
574 ``tool_dependencies.xml`` should contain matching declarations for Galaxy to
575 actually install the R runtime. The ``set_envirornment`` type is only respected
576 by the tool shed and is ignored by the newer and preferred conda dependency
577 resolver.
578
579 ```xml
580 <requirements>
581 <requirement type="set_environment">R_SCRIPT_PATH</requirement>
582 <requirement type="package" version="2.15.1">R</requirement>
583 </requirements>
584 ```
585
586 ]]></xs:documentation>
587 </xs:annotation>
588 <xs:simpleContent>
589 <xs:extension base="xs:string">
590 <xs:attribute name="type" type="RequirementType" use="required">
591 <xs:annotation>
592 <xs:documentation xml:lang="en">This value defines the type of the 3rd party module required by this tool.</xs:documentation>
593 </xs:annotation>
594 </xs:attribute>
595 <xs:attribute name="version" type="xs:string">
596 <xs:annotation>
597 <xs:documentation xml:lang="en">For requirements of type ``package`` this value defines a specific version of the tool dependency.</xs:documentation>
598 </xs:annotation>
599 </xs:attribute>
600 </xs:extension>
601 </xs:simpleContent>
602 </xs:complexType>
603 <xs:complexType name="Container">
604 <xs:annotation>
605 <xs:documentation xml:lang="en"><![CDATA[
606 This tag set is contained within the 'requirements' tag set. Galaxy can be
607 configured to run tools within [Docker](https://www.docker.com/) or [Singularity](https://www.sylabs.io/singularity/)
608 containers - this tag allows the tool to suggest possible valid containers for this tool. The contents of the tag should
609 be a container image identifier appropriate for the particular container runtime being used, e.g.
610 ``quay.io/biocontainers/fastqc:0.11.2--1`` for Docker or ``docker://quay.io/biocontainers/fastqc:0.11.2--1``
611 (or alternatively ``/opt/containers/fastqc.simg`` if your Galaxy installation will be loading the image from a filesystem path)
612 for Singularity. The ``requirements`` tag can contain multiple ``container`` tags describing suitable container options, in
613 which case the first container that is found by the Galaxy container resolver at runtime will be used.
614
615 Example:
616
617 ```xml
618 <requirements>
619 <container type="docker">quay.io/biocontainers/fastqc:0.11.2--1</container>
620 <requirements>
621 ```
622
623 Read more about configuring Galaxy to run Docker jobs
624 [here](https://galaxyproject.org/admin/tools/docker/).
625 ]]></xs:documentation>
626 </xs:annotation>
627 <xs:simpleContent>
628 <xs:extension base="xs:string">
629 <xs:attribute name="type" type="ContainerType" use="required">
630 <xs:annotation>
631 <xs:documentation xml:lang="en">This value describes the type of container that the tool may be executed in and currently may be ``docker`` or ``singularity``.</xs:documentation>
632 </xs:annotation>
633 </xs:attribute>
634 </xs:extension>
635 </xs:simpleContent>
636 </xs:complexType>
637
638 <xs:complexType name="Parallelism">
639 <xs:annotation>
640 <xs:documentation xml:lang="en">Documentation for Parallelism</xs:documentation>
641 </xs:annotation>
642 <xs:attribute name="method" type="MethodType">
643 <xs:annotation>
644 <xs:documentation xml:lang="en">Documentation for method</xs:documentation>
645 </xs:annotation>
646 </xs:attribute>
647 <xs:attribute name="merge_outputs" type="xs:string">
648 <xs:annotation>
649 <xs:documentation xml:lang="en">Documentation for merge_outputs</xs:documentation>
650 </xs:annotation>
651 </xs:attribute>
652 <xs:attribute name="split_inputs" type="xs:string">
653 <xs:annotation>
654 <xs:documentation xml:lang="en">A comma-separated list of data inputs to split for job parallelization.</xs:documentation>
655 </xs:annotation>
656 </xs:attribute>
657 <xs:attribute name="split_size" type="xs:string">
658 <xs:annotation>
659 <xs:documentation xml:lang="en">Documentation for split_size</xs:documentation>
660 </xs:annotation>
661 </xs:attribute>
662 <xs:attribute name="split_mode" type="xs:string">
663 <xs:annotation>
664 <xs:documentation xml:lang="en">Documentation for split_mode</xs:documentation>
665 </xs:annotation>
666 </xs:attribute>
667 <xs:attribute name="shared_inputs" type="xs:string">
668 <xs:annotation>
669 <xs:documentation xml:lang="en">A comma-separated list of data inputs that should not be split for this tool, Galaxy will infer this if not present and so this potentially never needs to be set.</xs:documentation>
670 </xs:annotation>
671 </xs:attribute>
672 </xs:complexType>
673 <xs:complexType name="Code">
674 <xs:annotation>
675 <xs:documentation xml:lang="en"><![CDATA[
676 *Deprecated*. Do not use this unless absolutely necessary.
677
678 The extensions described here can cause problems using your tool with certain components
679 of Galaxy (like the workflow system). It is highly recommended to avoid these constructs
680 unless absolutely necessary.
681
682 This tag set provides detailed control of the way the tool is executed. This
683 (optional) code can be deployed in a separate file in the same directory as the
684 tool's config file. These hooks are being replaced by new tool config features
685 and methods in the [/lib/galaxy/tools/\__init__.py](https://github.com/galaxyproject/galaxy/blob/dev/lib/galaxy/tools/__init__.py) code file.
686
687 ### Examples
688
689 #### Dynamic Options
690
691 Use associated dynamic select lists where selecting an option in the first
692 select list dynamically re-renders the options in the second select list. In
693 this example, we are populating both dynamic select lists from metadata elements
694 associated with a tool's single input dataset. The 2 metadata elements we're
695 using look like this.
696
697 ```python
698 MetadataElement(name="field_names", default=[], desc="Field names", readonly=True, optional=True, visible=True, no_value=[])
699 # The keys in the field_components map to the list of field_names in the above element
700 # which ensures order for select list options that are built from it.
701 MetadataElement(name="field_components", default={}, desc="Field names and components", readonly=True, optional=True, visible=True, no_value={})
702 ```
703
704 Our tool config includes a code file tag like this.
705
706 ```xml
707 <code file="tool_form_utils.py" />
708 ```
709
710 Here are the relevant input parameters in our tool config. The first parameter
711 is the input dataset that includes the above metadata elements.
712
713 ```xml
714 <param name="input" type="data" format="vtkascii,vtkbinary" label="Shape with uncolored surface field">
715 <validator type="expression" message="Shape must have an uncolored surface field.">value is not None and len(value.metadata.field_names) > 0</validator>
716 </param>
717 ```
718
719 The following parameter dynamically renders a select list consisting of the
720 elements in the ``field_names`` metadata element associated with the selected
721 input dataset.
722
723 ```xml
724 <param name="field_name" type="select" label="Field name" refresh_on_change="true">
725 <options>
726 <filter type="data_meta" ref="input" key="field_names"/>
727 <validator type="no_options" message="The selected shape has no uncolored surface fields." />
728 </options>
729 </param>
730 ```
731
732 The following parameter calls the ``get_field_components_options()`` function in
733 the ``tool_form_utils.py`` code file discussed above. This function returns the
734 value of the input dataset's ``field_components`` metadata element dictionary
735 whose key is the currently selected ``field_name`` from the select list parameter
736 above.
737
738 ```xml
739 <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." />
740 ```
741
742 Changing the selected option in the ``field_name`` select list will dynamically
743 re-render the options available in the associated ``field_component_index`` select
744 list, which is the behavior we want.
745
746 The ``get_field_components_options()`` method looks like this.
747
748 ```python
749 def get_field_components_options(dataset, field_name):
750 options = []
751 if dataset.metadata is None:
752 return options
753 if not hasattr(dataset.metadata, 'field_names'):
754 return options
755 if dataset.metadata.field_names is None:
756 return options
757 if field_name is None:
758 # The expression validator that helps populate the select list of input
759 # datsets in the icqsol_color_surface_field tool does not filter out
760 # datasets with no field field_names, so we need this check.
761 if len(dataset.metadata.field_names) == 0:
762 return options
763 field_name = dataset.metadata.field_names[0]
764 field_components = dataset.metadata.field_components.get(field_name, [])
765 for i, field_component in enumerate(field_components):
766 options.append((field_component, field_component, i == 0))
767 return options
768 ```
769
770 #### Parameter Validation
771
772 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:
773
774 ```python
775 def validate(incoming):
776 """Validator for the plotting program"""
777
778
779 bins = incoming.get("bins","")
780 col = incoming.get("col","")
781
782
783 if not bins or not col:
784 raise Exception, "You need to specify a number for bins and columns"
785
786
787 try:
788 bins = int(bins)
789 col = int(col)
790 except:
791 raise Exception, "Parameters are not integers, columns:%s, bins:%s" % (col, bins)
792
793
794 if not 1<bins<100:
795 raise Exception, "The number of bins %s must be a number between 1 and 100" % bins
796 ```
797
798 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.
799
800 #### Pre-job and pre-process code
801
802 The signature of both of these is the same:
803
804 ```python
805 def exec_before_job(inp_data, out_data, param_dict, tool):
806 def exec_before_process(inp_data, out_data, param_dict, tool):
807 ```
808
809 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.
810
811 Example:
812
813 ```python
814 def exec_before_process(inp_data, out_data, param_dict, tool):
815 for name, data in out_data.items():
816 data.name = 'New name'
817 ```
818
819 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.
820
821 #### Post-process code
822
823 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``:
824
825 ```python
826 from galaxy import datatypes
827 def exec_after_process(app, inp_data, out_data, param_dict, tool, stdout, stderr):
828 ext = param_dict.get('extension', 'text')
829 items = out_data.items()
830 for name, data in items:
831 newdata = datatypes.factory(ext)(id=data.id)
832 for key, value in data. __dict__.items():
833 setattr(newdata, key, value)
834 newdata.ext = ext
835 out_data[name] = newdata
836 ```
837
838 The content of ``stdout`` and ``stderr`` are strings containing the output of the process.
839
840 ]]></xs:documentation>
841
842 </xs:annotation>
843 <xs:sequence>
844 <xs:element name="hook" type="CodeHook" minOccurs="0" maxOccurs="unbounded"/>
845 </xs:sequence>
846 <xs:attribute name="file" type="xs:string" use="required">
847 <xs:annotation>
848 <xs:documentation xml:lang="en">This value is the name of the executable code file, and is called in the ``exec_before_process()``, ``exec_before_job()``, ``exec_after_process()`` and ``exec_after_job()`` methods.</xs:documentation>
849 </xs:annotation>
850 </xs:attribute>
851 </xs:complexType>
852 <xs:complexType name="CodeHook">
853 <xs:annotation>
854 <xs:documentation xml:lang="en">*Deprecated*. Map a hook to a function defined in the code file.</xs:documentation>
855 </xs:annotation>
856 <xs:attribute name="exec_after_process" type="xs:string">
857 <xs:annotation>
858 <xs:documentation xml:lang="en">Function defined in the code file to which the ``exec_after_process`` hook should be mapped</xs:documentation>
859 </xs:annotation>
860 </xs:attribute>
861 </xs:complexType>
862 <xs:complexType name="UIhints">
863 <xs:annotation>
864 <xs:documentation xml:lang="en">Used only for data source tools, this directive contains UI options (currently only ``minwidth`` is valid).</xs:documentation>
865 </xs:annotation>
866 <xs:attribute name="minwidth" type="xs:integer">
867 <xs:annotation>
868 <xs:documentation xml:lang="en">Documentation for minwidth</xs:documentation>
869 </xs:annotation>
870 </xs:attribute>
871 </xs:complexType>
872
873 <xs:complexType name="Options">
874 <xs:annotation>
875 <xs:documentation xml:lang="en">This directive is used to specify some rarely modified options.</xs:documentation>
876 </xs:annotation>
877 <xs:attribute name="refresh" type="PermissiveBoolean" gxdocs:deprecated="true">
878 <xs:annotation>
879 <xs:documentation xml:lang="en">*Deprecated*. Unused attribute.</xs:documentation>
880 </xs:annotation>
881 </xs:attribute>
882 <xs:attribute name="sanitize" type="PermissiveBoolean" default="true">
883 <xs:annotation>
884 <xs:documentation xml:lang="en">This attribute can be used to turn off all input sanitization for a tool.</xs:documentation>
885 </xs:annotation>
886 </xs:attribute>
887 </xs:complexType>
888
889 <xs:complexType name="TracksterConf">
890 <xs:annotation>
891 <xs:documentation xml:lang="en">This directive is used to specify some rarely modified trackster options.</xs:documentation>
892 </xs:annotation>
893 <xs:sequence>
894 <xs:element name="action" type="TracksterAction" minOccurs="0" maxOccurs="unbounded" />
895 </xs:sequence>
896 </xs:complexType>
897
898 <xs:complexType name="TracksterAction">
899 <xs:annotation>
900 <xs:documentation xml:lang="en"></xs:documentation>
901 </xs:annotation>
902 <xs:attribute name="name" type="xs:string">
903 <xs:annotation>
904 <xs:documentation xml:lang="en"></xs:documentation>
905 </xs:annotation>
906 </xs:attribute>
907 <xs:attribute name="output_name" type="xs:string">
908 <xs:annotation>
909 <xs:documentation xml:lang="en"></xs:documentation>
910 </xs:annotation>
911 </xs:attribute>
912 </xs:complexType>
913
914 <xs:complexType name="Tests">
915 <xs:annotation gxdocs:best_practices="tests">
916 <xs:documentation xml:lang="en"><![CDATA[
917
918 Container tag set to specify tests via the ``<test>`` tag sets. Any number of tests can be included,
919 and each test is wrapped within separate ``<test>`` tag sets. Functional tests are
920 executed via [Planemo](https://planemo.readthedocs.io/) or the
921 [run_tests.sh](https://github.com/galaxyproject/galaxy/blob/dev/run_tests.sh)
922 shell script distributed with Galaxy.
923
924 The documentation contained here is mostly reference documentation, for
925 tutorials on writing tool tests please check out Planemo's
926 [Test-Driven Development](https://planemo.readthedocs.io/en/latest/writing_advanced.html#test-driven-development)
927 documentation or the much older wiki content for
928 [WritingTests](https://galaxyproject.org/admin/tools/writing-tests/).
929
930 ]]></xs:documentation>
931 </xs:annotation>
932 <xs:sequence>
933 <xs:element name="test" type="Test" minOccurs="0" maxOccurs="unbounded"/>
934 </xs:sequence>
935 </xs:complexType>
936
937 <xs:complexType name="Test">
938 <xs:annotation>
939 <xs:documentation xml:lang="en"><![CDATA[
940
941 This tag set contains the necessary parameter values for executing the tool via
942 the functional test framework.
943
944 ### Example
945
946 The following two tests will execute the
947 [/tools/filters/sorter.xml](https://github.com/galaxyproject/galaxy/blob/dev/tools/filters/sorter.xml)
948 tool. Notice the way that the tool's inputs and outputs are defined.
949
950 ```xml
951 <tests>
952 <test>
953 <param name="input" value="1.bed" ftype="bed" />
954 <param name="column" value="1"/>
955 <param name="order" value="ASC"/>
956 <param name="style" value="num"/>
957 <output name="out_file1" file="sort1_num.bed" ftype="bed" />
958 </test>
959 <test>
960 <param name="input" value="7.bed" ftype="bed" />
961 <param name="column" value="1"/>
962 <param name="order" value="ASC"/>
963 <param name="style" value="alpha"/>
964 <output name="out_file1" file="sort1_alpha.bed" ftype="bed" />
965 </test>
966 </tests>
967 ```
968
969 The following example, tests the execution of the MAF-to-FASTA converter
970 ([/tools/maf/maf_to_fasta.xml](https://github.com/galaxyproject/galaxy/blob/master/tools/maf/maf_to_fasta.xml)).
971
972 ```xml
973 <tests>
974 <test>
975 <param name="input1" value="3.maf" ftype="maf"/>
976 <param name="species" value="canFam1"/>
977 <param name="fasta_type" value="concatenated"/>
978 <output name="out_file1" file="cf_maf2fasta_concat.dat" ftype="fasta"/>
979 </test>
980 </tests>
981 ```
982
983 This test demonstrates verifying specific properties about a test output instead
984 of directly comparing it to another file. Here the file attribute is not
985 specified and instead a series of assertions is made about the output.
986
987 ```xml
988 <test>
989 <param name="input" value="maf_stats_interval_in.dat" />
990 <param name="lineNum" value="99999"/>
991 <output name="out_file1">
992 <assert_contents>
993 <has_text text="chr7" />
994 <not_has_text text="chr8" />
995 <has_text_matching expression="1274\d+53" />
996 <has_line_matching expression=".*\s+127489808\s+127494553" />
997 <!-- &#009; is XML escape code for tab -->
998 <has_line line="chr7&#009;127471195&#009;127489808" />
999 <has_n_columns n="3" />
1000 <has_n_lines n="3" />
1001 </assert_contents>
1002 </output>
1003 </test>
1004 ```
1005
1006 ]]></xs:documentation>
1007 </xs:annotation>
1008 <xs:sequence>
1009 <xs:group ref="TestParamElement" minOccurs="0" maxOccurs="unbounded"/>
1010 </xs:sequence>
1011 <xs:attribute name="expect_exit_code" type="xs:integer">
1012 <xs:annotation>
1013 <xs:documentation xml:lang="en">Describe the job's expected exit code.</xs:documentation>
1014 </xs:annotation>
1015 </xs:attribute>
1016 <xs:attribute name="expect_num_outputs" type="xs:integer">
1017 <xs:annotation>
1018 <xs:documentation xml:lang="en">Assert the number of outputs this test
1019 should produce, this is useful to ensure ``filter`` directives are implemented correctly.</xs:documentation>
1020 </xs:annotation>
1021 </xs:attribute>
1022 <xs:attribute name="expect_failure" type="PermissiveBoolean" default="false">
1023 <xs:annotation>
1024 <xs:documentation xml:lang="en">Setting this to ``true`` indicates
1025 the expectation is for the job fail. If set to ``true`` no job output checks may
1026 be present in ``test`` definition.</xs:documentation>
1027 </xs:annotation>
1028 </xs:attribute>
1029 <xs:attribute name="maxseconds" type="xs:integer">
1030 <xs:annotation>
1031 <xs:documentation xml:lang="en">Maximum amount of time to let test run.</xs:documentation>
1032 </xs:annotation>
1033 </xs:attribute>
1034 </xs:complexType>
1035 <xs:group name="TestParamElement">
1036 <xs:choice>
1037 <xs:element name="param" type="TestParam" />
1038 <xs:element name="repeat" type="TestRepeat" />
1039 <xs:element name="conditional" type="TestConditional" />
1040 <xs:element name="section" type="TestSection" />
1041 <xs:element name="output" type="TestOutput" minOccurs="0" maxOccurs="unbounded"/>
1042 <xs:element name="output_collection" type="TestOutputCollection"/>
1043 <xs:element name="assert_command" type="TestAssertions">
1044 <xs:annotation>
1045 <xs:documentation xml:lang="en">Describe assertions about the job's
1046 generated command-line.
1047
1048 $assertions
1049 </xs:documentation>
1050 </xs:annotation>
1051 </xs:element>
1052 <xs:element name="assert_stdout" type="TestAssertions">
1053 <xs:annotation>
1054 <xs:documentation xml:lang="en">Describe assertions about the job's
1055 standard output.
1056
1057 $assertions
1058 </xs:documentation>
1059 </xs:annotation>
1060 </xs:element>
1061 <xs:element name="assert_stderr" type="TestAssertions">
1062 <xs:annotation>
1063 <xs:documentation xml:lang="en">Describe assertions about the job's
1064 standard error.
1065
1066 $assertions
1067 </xs:documentation>
1068 </xs:annotation>
1069 </xs:element>
1070 <xs:element name="assert_command_version" type="TestAssertions">
1071 <xs:annotation>
1072 <xs:documentation xml:lang="en">Describe assertions about the job's
1073 command version.
1074
1075 $assertions
1076 </xs:documentation>
1077 </xs:annotation>
1078 </xs:element>
1079 </xs:choice>
1080 </xs:group>
1081 <xs:complexType name="TestSection">
1082 <xs:annotation>
1083 <xs:documentation xml:lang="en"><![CDATA[
1084
1085 Specify test parameters below a named of a ``section`` block matching
1086 one in ``inputs`` with this element.
1087
1088 ``param`` elements in a ``test`` block can be arranged into nested ``repeat``,
1089 ``conditional``, and ``select`` structures to match the inputs. While this might
1090 be overkill for simple tests, it helps prevent ambiguous definitions and keeps
1091 things organized in large test cases. A future ``profile`` version of Galaxy
1092 tools may require ``section`` blocks be explicitly defined with this
1093 directive.
1094
1095 ### Examples
1096
1097 The test tool demonstrating sections
1098 ([section.xml](https://github.com/galaxyproject/galaxy/blob/dev/test/functional/tools/section.xml))
1099 contains a test case demonstrating this block. This test case appears below:
1100
1101 ```xml
1102 <test>
1103 <section name="int">
1104 <param name="inttest" value="12456" />
1105 </section>
1106 <section name="float">
1107 <param name="floattest" value="6.789" />
1108 </section>
1109 <output name="out_file1">
1110 <assert_contents>
1111 <has_line line="12456" />
1112 <has_line line="6.789" />
1113 </assert_contents>
1114 </output>
1115 </test>
1116 ```
1117
1118 ]]>
1119 </xs:documentation>
1120 </xs:annotation>
1121 <xs:sequence>
1122 <xs:group ref="TestParamElement" minOccurs="0" maxOccurs="unbounded" />
1123 </xs:sequence>
1124 <xs:attribute name="name" type="xs:string" use="required">
1125 <xs:annotation>
1126 <xs:documentation xml:lang="en">This value must match the name of the
1127 associated input ``section``.</xs:documentation>
1128 </xs:annotation>
1129 </xs:attribute>
1130 </xs:complexType>
1131 <xs:complexType name="TestConditional">
1132 <xs:annotation>
1133 <xs:documentation xml:lang="en"><![CDATA[
1134
1135 Specify test parameters below a named of a ``conditional`` block matching
1136 one in ``inputs`` with this element.
1137
1138 ``param`` elements in a ``test`` block can be arranged into nested ``repeat``,
1139 ``conditional``, and ``select`` structures to match the inputs. While this might
1140 be overkill for simple tests, it helps prevent ambiguous definitions and keeps
1141 things organized in large test cases. A future ``profile`` version of Galaxy
1142 tools may require ``conditional`` blocks be explicitly defined with this
1143 directive.
1144
1145 ### Examples
1146
1147 The following example demonstrates disambiguation of a parameter (named ``use``)
1148 which appears in multiple ``param`` names in ``conditional``s in the ``inputs``
1149 definition of the [disambiguate_cond.xml](https://github.com/galaxyproject/galaxy/blob/dev/test/functional/tools/disambiguate_cond.xml)
1150 tool.
1151
1152 ```xml
1153 <!-- Can use nested conditional blocks as shown below to disambiguate
1154 various nested parameters. -->
1155 <test>
1156 <conditional name="p1">
1157 <param name="use" value="False"/>
1158 </conditional>
1159 <conditional name="p2">
1160 <param name="use" value="True"/>
1161 </conditional>
1162 <conditional name="p3">
1163 <param name="use" value="False"/>
1164 </conditional>
1165 <conditional name="files">
1166 <param name="attach_files" value="True" />
1167 <conditional name="p4">
1168 <param name="use" value="True"/>
1169 <param name="file" value="simple_line_alternative.txt" />
1170 </conditional>
1171 </conditional>
1172 <output name="out_file1">
1173 <assert_contents>
1174 <has_line line="7 4 7" />
1175 <has_line line="This is a different line of text." />
1176 </assert_contents>
1177 </output>
1178 </test>
1179 ```
1180
1181 The [tophat2](https://github.com/galaxyproject/tools-devteam/blob/master/tools/tophat2/tophat2_wrapper.xml)
1182 tool demonstrates a real tool that benefits from more structured test cases
1183 using the ``conditional`` test directive. One such test case from that tool is
1184 shown below.
1185
1186 ```xml
1187 <!-- Test base-space paired-end reads with user-supplied reference fasta and full parameters -->
1188 <test>
1189 <!-- TopHat commands:
1190 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
1191 Replace the + with double-dash
1192 Rename the files in tmp_dir appropriately
1193 -->
1194 <conditional name="singlePaired">
1195 <param name="sPaired" value="paired"/>
1196 <param name="input1" ftype="fastqsanger" value="tophat_in2.fastqsanger"/>
1197 <param name="input2" ftype="fastqsanger" value="tophat_in3.fastqsanger"/>
1198 <param name="mate_inner_distance" value="20"/>
1199 <param name="report_discordant_pairs" value="Yes" />
1200 </conditional>
1201 <param name="genomeSource" value="indexed"/>
1202 <param name="index" value="tophat_test"/>
1203 <conditional name="params">
1204 <param name="settingsType" value="full"/>
1205 <param name="library_type" value="FR Unstranded"/>
1206 <param name="read_mismatches" value="5"/>
1207 <!-- Error: the read mismatches (5) and the read gap length (2) should be less than or equal to the read edit dist (2) -->
1208 <param name="read_edit_dist" value="5" />
1209 <param name="bowtie_n" value="Yes"/>
1210 <param name="mate_std_dev" value="20"/>
1211 <param name="anchor_length" value="8"/>
1212 <param name="splice_mismatches" value="0"/>
1213 <param name="min_intron_length" value="70"/>
1214 <param name="max_intron_length" value="500000"/>
1215 <param name="max_multihits" value="40"/>
1216 <param name="min_segment_intron" value="50" />
1217 <param name="max_segment_intron" value="500000" />
1218 <param name="seg_mismatches" value="2"/>
1219 <param name="seg_length" value="25"/>
1220 <conditional name="indel_search">
1221 <param name="allow_indel_search" value="No"/>
1222 </conditional>
1223 <conditional name="own_junctions">
1224 <param name="use_junctions" value="Yes" />
1225 <conditional name="gene_model_ann">
1226 <param name="use_annotations" value="No" />
1227 </conditional>
1228 <conditional name="raw_juncs">
1229 <param name="use_juncs" value="No" />
1230 </conditional>
1231 <conditional name="no_novel_juncs">
1232 <param name="no_novel_juncs" value="No" />
1233 </conditional>
1234 </conditional>
1235 <conditional name="coverage_search">
1236 <param name="use_search" value="No" />
1237 </conditional>
1238 <param name="microexon_search" value="Yes" />
1239 <conditional name="bowtie2_settings">
1240 <param name="b2_settings" value="No" />
1241 </conditional>
1242 <!-- Fusion search params -->
1243 <conditional name="fusion_search">
1244 <param name="do_search" value="Yes" />
1245 <param name="anchor_len" value="21" />
1246 <param name="min_dist" value="10000021" />
1247 <param name="read_mismatches" value="3" />
1248 <param name="multireads" value="4" />
1249 <param name="multipairs" value="5" />
1250 <param name="ignore_chromosomes" value="chrM"/>
1251 </conditional>
1252 </conditional>
1253 <conditional name="readGroup">
1254 <param name="specReadGroup" value="no" />
1255 </conditional>
1256 <output name="junctions" file="tophat2_out4j.bed" />
1257 <output name="accepted_hits" file="tophat_out4h.bam" compare="sim_size" />
1258 </test>
1259 ```
1260
1261 ]]></xs:documentation>
1262 </xs:annotation>
1263 <xs:sequence>
1264 <xs:group ref="TestParamElement" minOccurs="0" maxOccurs="unbounded" />
1265 </xs:sequence>
1266 <xs:attribute name="name" type="xs:string" use="required">
1267 <xs:annotation>
1268 <xs:documentation xml:lang="en">This value must match the name of the
1269 associated input ``conditional``.</xs:documentation>
1270 </xs:annotation>
1271 </xs:attribute>
1272 </xs:complexType>
1273 <xs:complexType name="TestRepeat">
1274 <xs:annotation>
1275 <xs:documentation xml:lang="en"><![CDATA[
1276
1277 Specify test parameters below an iteration of a ``repeat`` block with this
1278 element.
1279
1280 ``param`` elements in a ``test`` block can be arranged into nested ``repeat``,
1281 ``conditional``, and ``select`` structures to match the inputs. While this might
1282 be overkill for simple tests, it helps prevent ambiguous definitions and keeps
1283 things organized in large test cases. A future ``profile`` version of Galaxy
1284 tools may require ``repeat`` blocks be explicitly defined with this directive.
1285
1286 ### Examples
1287
1288 The test tool [disambiguate_repeats.xml](https://github.com/galaxyproject/galaxy/blob/dev/test/functional/tools/disambiguate_repeats.xml)
1289 demonstrates the use of this directive.
1290
1291 This first test case demonstrates that this block allows different values for
1292 the ``param`` named ``input`` to be tested even though this parameter name
1293 appears in two different ``<repeat>`` elements in the ``<inputs>`` definition.
1294
1295 ```xml
1296 <!-- Can disambiguate repeats and specify multiple blocks using,
1297 nested structure. -->
1298 <test>
1299 <repeat name="queries">
1300 <param name="input" value="simple_line.txt"/>
1301 </repeat>
1302 <repeat name="more_queries">
1303 <param name="input" value="simple_line_alternative.txt"/>
1304 </repeat>
1305 <output name="out_file1">
1306 <assert_contents>
1307 <has_line line="This is a line of text." />
1308 <has_line line="This is a different line of text." />
1309 </assert_contents>
1310 </output>
1311 </test>
1312 ```
1313
1314 The second definition in that file demonstrates repeated ``<repeat>`` blocks
1315 allowing multiple instances of a single repeat to be specified.
1316
1317 ```xml
1318 <!-- Multiple such blocks can be specified but only with newer API
1319 driven tests. -->
1320 <test>
1321 <repeat name="queries">
1322 <param name="input" value="simple_line.txt"/>
1323 </repeat>
1324 <repeat name="queries">
1325 <param name="input" value="simple_line_alternative.txt"/>
1326 </repeat>
1327 <repeat name="more_queries">
1328 <param name="input" value="simple_line.txt"/>
1329 </repeat>
1330 <repeat name="more_queries">
1331 <param name="input" value="simple_line_alternative.txt"/>
1332 </repeat>
1333 <output name="out_file1" file="simple_lines_interleaved.txt"/>
1334 </test>
1335 ```
1336
1337 ]]></xs:documentation>
1338 </xs:annotation>
1339 <xs:sequence>
1340 <xs:group ref="TestParamElement" minOccurs="0" maxOccurs="unbounded" />
1341 </xs:sequence>
1342 <xs:attribute name="name" type="xs:string" use="required">
1343 <xs:annotation>
1344 <xs:documentation xml:lang="en">This value must match the name of the
1345 associated input ``repeat``.</xs:documentation>
1346 </xs:annotation>
1347 </xs:attribute>
1348 </xs:complexType>
1349 <xs:complexType name="TestParam">
1350 <xs:annotation>
1351 <xs:documentation xml:lang="en"><![CDATA[
1352
1353 This tag set defines the tool's input parameters for executing the tool via the
1354 functional test framework. See [test](#tool-tests-test) documentation for
1355 some simple examples of parameters.
1356
1357 ### Parameter Types
1358
1359 #### ``text``, ``integer``, and ``float``
1360
1361 Values for these parameters are simply given by the desired value.
1362
1363 #### ``boolean``
1364
1365 The value of the test parameter should be set to `true` or `false` corresponding
1366 to the cases that the parameter is checked or not. Alternatively the value
1367 specified as `truevalue` or `falsevalue` can be given.
1368
1369 #### ``data``
1370
1371 Data input parameters can be given as a file name. The file should exist in the
1372 `test-data` folder. Multiple files can be specified as comma separated list.
1373
1374 #### ``select``
1375
1376 The value of a select parameter should be specified as the value of one of the
1377 legal options. If more than one option is selected (`multiple="true"`) they
1378 should be given as comma separated list. For optional selects
1379 (`optional="true"`) the case that no option is selected can be specified with
1380 `value=""`.
1381
1382 While in general it is preferred to specify the selected cases by their values it
1383 is also possible to specify them by their name (i.e. the content of the
1384 `option` tag that is shown to the user). One use case is a dynamic select that is
1385 generated from a data table with two columns: name and value where the value is
1386 a path. Since the path changes with the test environment it can not be used to
1387 select an option for a test.
1388
1389 ]]></xs:documentation>
1390 </xs:annotation>
1391 <xs:sequence>
1392 <xs:element name="collection" type="TestCollection" minOccurs="0" maxOccurs="1" />
1393 <xs:element name="composite_data" type="TestCompositeData" minOccurs="0" maxOccurs="unbounded" />
1394 <xs:element name="metadata" type="TestParamMetadata" minOccurs="0" maxOccurs="unbounded" />
1395 </xs:sequence>
1396 <xs:attribute name="name" type="xs:string" use="required">
1397 <xs:annotation>
1398 <xs:documentation xml:lang="en">This value must match the name of the
1399 associated input parameter (``param``).</xs:documentation>
1400 </xs:annotation>
1401 </xs:attribute>
1402 <xs:attribute name="value" type="xs:string">
1403 <xs:annotation>
1404 <xs:documentation xml:lang="en">This value must be one of the legal
1405 values that can be assigned to an input parameter.</xs:documentation>
1406 </xs:annotation>
1407 </xs:attribute>
1408 <xs:attribute name="value_json" type="xs:string">
1409 <xs:annotation>
1410 <xs:documentation xml:lang="en">This variant of the value parameters can be
1411 used to load typed parameters. This string will be loaded as JSON and its type will
1412 attempt to be preserved through API requests to Galaxy.</xs:documentation>
1413 </xs:annotation>
1414 </xs:attribute>
1415 <xs:attribute name="ftype" type="xs:string">
1416 <xs:annotation>
1417 <xs:documentation xml:lang="en">This attribute name should be included
1418 only with parameters of ``type`` ``data`` for the tool. If this
1419 attribute name is not included, the functional test framework will attempt to
1420 determine the data type for the input dataset using the data type sniffers.</xs:documentation>
1421 </xs:annotation>
1422 </xs:attribute>
1423 <xs:attribute name="dbkey" type="xs:string">
1424 <xs:annotation>
1425 <xs:documentation xml:lang="en">Specifies a ``dbkey`` value for the
1426 referenced input dataset. This is only valid if the corresponding parameter is
1427 of ``type`` ``data``.</xs:documentation>
1428 </xs:annotation>
1429 </xs:attribute>
1430 <xs:attribute name="tags" type="xs:string">
1431 <xs:annotation>
1432 <xs:documentation xml:lang="en">Comma separated list of tags to apply to the dataset (only works for elements of collections - e.g. ``element`` XML tags).</xs:documentation>
1433 </xs:annotation>
1434 </xs:attribute>
1435 </xs:complexType>
1436 <xs:complexType name="TestCompositeData">
1437 <xs:annotation>
1438 <xs:documentation xml:lang="en">Define extra composite input files for test
1439 input. The specified ``ftype`` on the parent ``param`` should specify a composite
1440 datatype with defined static composite files. The order of the defined composite
1441 files on the datatype must match the order specified with these elements and All
1442 non-optional composite inputs must be specified as part of the ``param``.
1443 </xs:documentation>
1444 </xs:annotation>
1445 <xs:attribute name="value" type="xs:string" use="required">
1446 <xs:annotation>
1447 <xs:documentation xml:lang="en">Path relative to test-data of composite file.</xs:documentation>
1448 </xs:annotation>
1449 </xs:attribute>
1450 </xs:complexType>
1451 <xs:complexType name="TestCollection">
1452 <xs:annotation>
1453 <xs:documentation xml:lang="en">Definition of a collection for test input.</xs:documentation>
1454 </xs:annotation>
1455 <xs:sequence>
1456 <xs:element name="element" type="TestParam" minOccurs="0" maxOccurs="unbounded"/>
1457 </xs:sequence>
1458 <xs:attribute name="type" type="xs:string" use="required">
1459 <xs:annotation>
1460 <xs:documentation xml:lang="en">Type of collection to create.</xs:documentation>
1461 </xs:annotation>
1462 </xs:attribute>
1463 <xs:attribute name="tags" type="xs:string">
1464 <xs:annotation>
1465 <xs:documentation xml:lang="en">Comma separated list of tags to apply to the dataset (only works for elements of collections - e.g. ``element`` XML tags).</xs:documentation>
1466 </xs:annotation>
1467 </xs:attribute>
1468 </xs:complexType>
1469 <xs:complexType name="TestOutput">
1470 <xs:annotation>
1471 <xs:documentation xml:lang="en"><![CDATA[
1472
1473 This tag set defines the variable that names the output dataset for the
1474 functional test framework. The functional test framework will execute the tool
1475 using the parameters defined in the ``<param>`` tag sets and generate a
1476 temporary file, which will either be compared with the file named in the
1477 ``file`` attribute value or checked against assertions made by a child
1478 ``assert_contents`` tag to verify that the tool is functionally correct.
1479
1480 ]]></xs:documentation>
1481 </xs:annotation>
1482 <xs:sequence>
1483 <xs:group ref="TestOutputElement" minOccurs="0" maxOccurs="unbounded" />
1484 </xs:sequence>
1485 <!-- TODO: This would be more percise if this was required if at the top-level. -->
1486 <xs:attribute name="name" type="xs:string">
1487 <xs:annotation>
1488 <xs:documentation xml:lang="en"><![CDATA[
1489
1490 This value is the same as the value of the ``name`` attribute of the ``<data>``
1491 tag set contained within the tool's ``<outputs>`` tag set.
1492
1493 ]]></xs:documentation>
1494 </xs:annotation>
1495 </xs:attribute>
1496 <xs:attribute name="file" type="xs:string">
1497 <xs:annotation>
1498 <xs:documentation xml:lang="en"><![CDATA[
1499
1500 If specified, this value is the name of the output file stored in the target
1501 ``test-data`` directory which will be used to compare the results of executing
1502 the tool via the functional test framework.
1503
1504 ]]></xs:documentation>
1505 </xs:annotation>
1506 </xs:attribute>
1507 <xs:attribute name="value_json" type="xs:string">
1508 <xs:annotation>
1509 <xs:documentation xml:lang="en"><![CDATA[
1510
1511 If specified, this value will be loaded as JSON and compared against the output
1512 generated as JSON. This can be useful for testing tool outputs that are not files.
1513
1514 ]]></xs:documentation>
1515 </xs:annotation>
1516 </xs:attribute>
1517 <xs:attribute name="ftype" type="xs:string">
1518 <xs:annotation>
1519 <xs:documentation xml:lang="en"><![CDATA[
1520
1521 If specified, this value will be checked against the corresponding output's
1522 data type. If these do not match, the test will fail.
1523
1524 ]]></xs:documentation>
1525 </xs:annotation>
1526 </xs:attribute>
1527 <xs:attribute name="sort" type="PermissiveBoolean">
1528 <xs:annotation>
1529 <xs:documentation xml:lang="en">This flag causes the lines of the output
1530 to be sorted before they are compared to the expected output. This could be
1531 useful for non-deterministic output.</xs:documentation>
1532 </xs:annotation>
1533 </xs:attribute>
1534 <xs:attribute name="value" type="xs:string">
1535 <xs:annotation>
1536 <xs:documentation xml:lang="en">An alias for ``file``.</xs:documentation>
1537 </xs:annotation>
1538 </xs:attribute>
1539 <xs:attribute name="md5" type="xs:string">
1540 <xs:annotation>
1541 <xs:documentation xml:lang="en"><![CDATA[
1542
1543 If specified, the target output's MD5 hash should match the value specified
1544 here. For large static files it may be inconvenient to upload the entiry file
1545 and this can be used instead.
1546
1547 ]]></xs:documentation>
1548 </xs:annotation>
1549 </xs:attribute>
1550 <xs:attribute name="checksum" type="xs:string">
1551 <xs:annotation>
1552 <xs:documentation xml:lang="en"><![CDATA[
1553
1554 If specified, the target output's checksum should match the value specified
1555 here. This value should have the form ``hash_type$hash_value``
1556 (e.g. ``sha1$8156d7ca0f46ed7abac98f82e36cfaddb2aca041``). For large static files
1557 it may be inconvenient to upload the entiry file and this can be used instead.
1558
1559 ]]></xs:documentation>
1560 </xs:annotation>
1561 </xs:attribute>
1562 <xs:attribute name="compare" type="TestOutputCompareType">
1563 </xs:attribute>
1564 <xs:attribute name="lines_diff" type="xs:integer">
1565 <xs:annotation>
1566 <xs:documentation xml:lang="en">If ``compare`` is set to ``diff``, the number of lines of difference to allow (each line with a modification is a line added and a line removed so this counts as two lines).</xs:documentation>
1567 </xs:annotation>
1568 </xs:attribute>
1569 <xs:attribute name="decompress" type="PermissiveBoolean">
1570 <xs:annotation>
1571 <xs:documentation xml:lang="en"><![CDATA[
1572 When this attribute is true and ``compare`` is set to ``diff``, try to decompress files if needed. This flag is useful for testing compressed outputs that are non-deterministic despite having deterministic decompressed contents. By default, only files compressed with bz2, gzip and zip will be automatically decompressed. This is available in Galaxy since release 17.05 and was introduced in [pull request #3550](https://github.com/galaxyproject/galaxy/pull/3550).
1573 ]]></xs:documentation>
1574 </xs:annotation>
1575 </xs:attribute>
1576 <xs:attribute name="delta" type="xs:integer" default="10000">
1577 <xs:annotation>
1578 <xs:documentation xml:lang="en">If ``compare`` is set to ``sim_size``, this is the maximum allowed absolute size difference (in bytes) between the data set that is generated in the test and the file in ``test-data/`` that is referenced by the ``file`` attribute. Default value is 10000 bytes. Can be combined with ``delta_frac``.</xs:documentation>
1579 </xs:annotation>
1580 </xs:attribute>
1581 <xs:attribute name="delta_frac" type="xs:float">
1582 <xs:annotation>
1583 <xs:documentation xml:lang="en">If ``compare`` is set to ``sim_size``, this is the maximum allowed relative size difference between the data set that is generated in the test and the file in ``test-data/`` that is referenced by the ``file`` attribute. A value of 0.1 means that the file that is generated in the test can differ by at most 10% of the file in ``test-data``. The default is not to check for relative size difference. Can be combined with ``delta``.</xs:documentation>
1584 </xs:annotation>
1585 </xs:attribute>
1586 </xs:complexType>
1587 <xs:group name="TestOutputElement">
1588 <xs:choice>
1589 <xs:element name="element" type="TestOutput"/>
1590 <!-- TODO: This would be more percise if this was only allowed at the top-level. -->
1591 <xs:element name="discovered_dataset" type="TestDiscoveredDataset"/>
1592 <!-- TODO: To be more percise only one assert_contents is allowed - this should not be in here. -->
1593 <xs:element name="assert_contents" type="TestAssertions">
1594 <xs:annotation>
1595 <xs:documentation><![CDATA[
1596 $assertions
1597
1598 ### Examples
1599
1600 The following demonstrates a wide variety of text-based and tabular
1601 assertion statements.
1602
1603 ```xml
1604 <output name="out_file1">
1605 <assert_contents>
1606 <has_text text="chr7" />
1607 <not_has_text text="chr8" />
1608 <has_text_matching expression="1274\d+53" />
1609 <has_line_matching expression=".*\s+127489808\s+127494553" />
1610 <!-- &#009; is XML escape code for tab -->
1611 <has_line line="chr7&#009;127471195&#009;127489808" />
1612 <has_n_columns n="3" />
1613 </assert_contents>
1614 </output>
1615 ```
1616
1617 The following demonstrates a wide variety of XML assertion statements.
1618
1619 ```xml
1620 <output name="out_file1">
1621 <assert_contents>
1622 <is_valid_xml />
1623 <has_element_with_path path="BlastOutput_param/Parameters/Parameters_matrix" />
1624 <has_n_elements_with_path n="9" path="BlastOutput_iterations/Iteration/Iteration_hits/Hit/Hit_num" />
1625 <element_text_matches path="BlastOutput_version" expression="BLASTP\s+2\.2.*" />
1626 <element_text_is path="BlastOutput_program" text="blastp" />
1627 <element_text path="BlastOutput_iterations/Iteration/Iteration_hits/Hit/Hit_def">
1628 <not_has_text text="EDK72998.1" />
1629 <has_text_matching expression="ABK[\d\.]+" />
1630 </element_text>
1631 </assert_contents>
1632 </output>
1633 ```
1634
1635 The following demonstrates verifying XML content with XPath-like expressions.
1636
1637 ```xml
1638 <output name="out_file1">
1639 <assert_contents>
1640 <attribute_is path="outerElement/innerElement1" attribute="foo" text="bar" />
1641 <attribute_matches path="outerElement/innerElement2" attribute="foo2" expression="bar\d+" />
1642 </assert_contents>
1643 </output>
1644 ```
1645
1646 ]]></xs:documentation>
1647 </xs:annotation>
1648 </xs:element>
1649 <!-- TODO: This would be more percise if this was only allowed at the top-level. -->
1650 <xs:element name="extra_files" type="TestExtraFile" />
1651 <xs:element name="metadata" type="TestOutputMetadata"/>
1652 </xs:choice>
1653 </xs:group>
1654 <xs:complexType name="TestParamMetadata">
1655 <xs:attribute name="name" type="xs:string" use="required">
1656 <xs:annotation>
1657 <xs:documentation xml:lang="en">Documentation for name</xs:documentation>
1658 </xs:annotation>
1659 </xs:attribute>
1660 <xs:attribute name="value" type="xs:string" use="required">
1661 <xs:annotation>
1662 <xs:documentation xml:lang="en">Documentation for value</xs:documentation>
1663 </xs:annotation>
1664 </xs:attribute>
1665 </xs:complexType>
1666 <xs:complexType name="TestOutputMetadata">
1667 <xs:annotation>
1668 <xs:documentation xml:lang="en"><![CDATA[
1669
1670 This directive specifies a test for an output's metadata as an expected key-value pair.
1671
1672 ### Example
1673
1674 The functional test tool
1675 [tool_provided_metadata_1.xml](https://github.com/galaxyproject/galaxy/blob/dev/test/functional/tools/tool_provided_metadata_1.xml)
1676 provides a demonstration of using this tag.
1677
1678 ```xml
1679 <test>
1680 <param name="input1" value="simple_line.txt" />
1681 <output name="out1" file="simple_line.txt" ftype="txt">
1682 <metadata name="name" value="my dynamic name" />
1683 <metadata name="info" value="my dynamic info" />
1684 <metadata name="dbkey" value="cust1" />
1685 </output>
1686 </test>
1687 ```
1688
1689 ]]></xs:documentation>
1690 </xs:annotation>
1691 <xs:attribute name="name" type="xs:string" use="required">
1692 <xs:annotation>
1693 <xs:documentation xml:lang="en">Name of the metadata element to check.</xs:documentation>
1694 </xs:annotation>
1695 </xs:attribute>
1696 <xs:attribute name="value" type="xs:string" use="required">
1697 <xs:annotation>
1698 <xs:documentation xml:lang="en">Expected value (as a string) of metadata value.</xs:documentation>
1699 </xs:annotation>
1700 </xs:attribute>
1701 </xs:complexType>
1702 <xs:complexType name="TestDiscoveredDataset">
1703 <xs:annotation>
1704 <xs:documentation><![CDATA[
1705
1706 This directive specifies a test for an output's discovered dataset. It acts as an
1707 ``output`` test tag in many ways and can define any tests of that tag (e.g.
1708 ``assert_contents``, ``value``, ``compare``, ``md5``, ``checksum``, ``metadata``, etc...).
1709
1710 ### Example
1711
1712 The functional test tool
1713 [multi_output_assign_primary.xml](https://github.com/galaxyproject/galaxy/blob/dev/test/functional/tools/multi_output_assign_primary.xml)
1714 provides a demonstration of using this tag.
1715
1716 ```xml
1717 <outputs>
1718 <data format="tabular" name="sample">
1719 <discover_datasets pattern="(?P&lt;designation&gt;.+)\.report\.tsv" ext="tabular" visible="true" assign_primary_output="true" />
1720 </data>
1721 </outputs>
1722 <test>
1723 <param name="num_param" value="7" />
1724 <param name="input" ftype="txt" value="simple_line.txt"/>
1725 <output name="sample">
1726 <assert_contents>
1727 <has_line line="1" />
1728 </assert_contents>
1729 <!-- no sample1 it was consumed by named output "sample" -->
1730 <discovered_dataset designation="sample2" ftype="tabular">
1731 <assert_contents><has_line line="2" /></assert_contents>
1732 </discovered_dataset>
1733 <discovered_dataset designation="sample3" ftype="tabular">
1734 <assert_contents><has_line line="3" /></assert_contents>
1735 </discovered_dataset>
1736 </output>
1737 </test>
1738 ```
1739
1740 Note that this tool uses ``assign_primary_output="true"`` for ``<discover_data_sets>``. Hence, the content of the first discovered dataset (which is the first in the alphabetically sorted list of discovered designations) is checked directly in the ``<output>`` tag of the test.
1741 ]]></xs:documentation>
1742 </xs:annotation>
1743 <xs:complexContent>
1744 <xs:extension base="TestOutput">
1745 <xs:attribute type="xs:string" name="designation">
1746 <xs:annotation>
1747 <xs:documentation xml:lang="en">The designation of the discovered dataset.</xs:documentation>
1748 </xs:annotation>
1749 </xs:attribute>
1750 </xs:extension>
1751 </xs:complexContent>
1752 </xs:complexType>
1753 <xs:complexType name="TestExtraFile">
1754 <xs:annotation>
1755 <xs:documentation xml:lang="en">Define test for extra files on corresponding output.</xs:documentation>
1756 </xs:annotation>
1757 <xs:complexContent>
1758 <xs:extension base="TestOutput">
1759 <xs:attribute type="xs:string" name="type">
1760 <xs:annotation>
1761 <xs:documentation xml:lang="en">Extra file type (either ``file`` or ``directory``).</xs:documentation>
1762 </xs:annotation>
1763 </xs:attribute>
1764 </xs:extension>
1765 </xs:complexContent>
1766 </xs:complexType>
1767 <xs:complexType name="TestOutputCollection">
1768 <xs:annotation>
1769 <xs:documentation xml:lang="en"><![CDATA[
1770
1771 Define tests for extra datasets and metadata corresponding to an output collection.
1772
1773 ``output_collection`` directives should specify a ``name`` and ``type``
1774 attribute to describe the expected output collection as a whole.
1775
1776 Expectations about collection contents are described using child ``element``
1777 directives. For nested collections, these child ``element`` directives may
1778 themselves contain children.
1779
1780 For tools marked as having profile 20.09 or newer, the order of elements within
1781 an ``output_collection`` declaration are meaningful. The test definition may
1782 omit any number of elements from a collection, but the ones that are specified
1783 will be checked against the actual resulting collection from the tool run and the
1784 order within the collection verified.
1785
1786 ### Examples
1787
1788 The [genetrack](https://github.com/galaxyproject/tools-iuc/blob/master/tools/genetrack/genetrack.xml)
1789 tool demonstrates basic usage of an ``output_collection`` test expectation.
1790
1791 ```xml
1792 <test>
1793 <param name="input" value="genetrack_input2.gff" ftype="gff" />
1794 <param name="input_format" value="gff" />
1795 <param name="sigma" value="5" />
1796 <param name="exclusion" value="20" />
1797 <param name="up_width" value="10" />
1798 <param name="down_width" value="10" />
1799 <param name="filter" value="3" />
1800 <output_collection name="genetrack_output" type="list">
1801 <element name="s5e20u10d10F3_on_data_1" file="genetrack_output2.gff" ftype="gff" />
1802 </output_collection>
1803 </test>
1804 ```
1805
1806 The [CWPair2](https://github.com/galaxyproject/tools-iuc/blob/master/tools/cwpair2/cwpair2.xml)
1807 tool demonstrates that ``element``s can specify a ``compare`` attribute just
1808 like [output](#tool-tests-test-output).
1809
1810 ```xml
1811 <test>
1812 <param name="input" value="cwpair2_input1.gff" />
1813 <param name="up_distance" value="25" />
1814 <param name="down_distance" value="100" />
1815 <param name="method" value="all" />
1816 <param name="binsize" value="1" />
1817 <param name="threshold_format" value="relative_threshold" />
1818 <param name="relative_threshold" value="0.0" />
1819 <param name="output_files" value="matched_pair" />
1820 <output name="statistics_output" file="statistics1.tabular" ftype="tabular" />
1821 <output_collection name="MP" type="list">
1822 <element name="data_MP_closest_f0u25d100_on_data_1.gff" file="closest_mp_output1.gff" ftype="gff" compare="contains"/>
1823 <element name="data_MP_largest_f0u25d100_on_data_1.gff" file="largest_mp_output1.gff" ftype="gff" compare="contains"/>
1824 <element name="data_MP_mode_f0u25d100_on_data_1.gff" file="mode_mp_output1.gff" ftype="gff" compare="contains"/>
1825 </output_collection>
1826 </test>
1827 ```
1828
1829 The
1830 [collection_creates_dynamic_nested](https://github.com/galaxyproject/galaxy/blob/dev/test/functional/tools/collection_creates_dynamic_nested.xml)
1831 test tool demonstrates the use of nested ``element`` directives as described
1832 above. Notice also that it tests the output with ``assert_contents`` instead of
1833 supplying a ``file`` attribute. Like hinted at with with ``compare`` attribute
1834 above, the ``element`` tag can specify any of the test attributes that apply to
1835 the [output](#tool-tests-test-output) (e.g. ``md5``, ``compare``, ``diff``,
1836 etc...).
1837
1838 ```xml
1839 <test>
1840 <param name="foo" value="bar" />
1841 <output_collection name="list_output" type="list:list">
1842 <element name="oe1">
1843 <element name="ie1">
1844 <assert_contents>
1845 <has_text_matching expression="^A\n$" />
1846 </assert_contents>
1847 </element>
1848 <element name="ie2">
1849 <assert_contents>
1850 <has_text_matching expression="^B\n$" />
1851 </assert_contents>
1852 </element>
1853 </element>
1854 <element name="oe2">
1855 <element name="ie1">
1856 <assert_contents>
1857 <has_text_matching expression="^C\n$" />
1858 </assert_contents>
1859 </element>
1860 <element name="ie2">
1861 <assert_contents>
1862 <has_text_matching expression="^D\n$" />
1863 </assert_contents>
1864 </element>
1865 </element>
1866 <element name="oe3">
1867 <element name="ie1">
1868 <assert_contents>
1869 <has_text_matching expression="^E\n$" />
1870 </assert_contents>
1871 </element>
1872 <element name="ie2">
1873 <assert_contents>
1874 <has_text_matching expression="^F\n$" />
1875 </assert_contents>
1876 </element>
1877 </element>
1878 </output_collection>
1879 </test>
1880 ```
1881
1882 ]]></xs:documentation>
1883 </xs:annotation>
1884 <xs:sequence>
1885 <xs:element name="element" type="TestOutput" minOccurs="0" maxOccurs="unbounded"/>
1886 </xs:sequence>
1887 <xs:attribute name="name" type="xs:string" use="required">
1888 <xs:annotation>
1889 <xs:documentation xml:lang="en"><![CDATA[
1890
1891 This value is the same as the value of the ``name`` attribute of the
1892 ``<collection>`` tag set contained within the tool's ``<outputs>`` tag set.
1893
1894 ]]></xs:documentation>
1895 </xs:annotation>
1896 </xs:attribute>
1897 <xs:attribute name="type" type="xs:string">
1898 <xs:annotation>
1899 <xs:documentation xml:lang="en">Expected collection type (e.g. ``list``, ``paired``,
1900 or ``list:paired``).</xs:documentation>
1901 </xs:annotation>
1902 </xs:attribute>
1903 <xs:attribute name="count" type="xs:integer">
1904 <xs:annotation>
1905 <xs:documentation xml:lang="en">Number of elements in output collection.</xs:documentation>
1906 </xs:annotation>
1907 </xs:attribute>
1908 </xs:complexType>
1909
1910 <xs:complexType name="TestAssertions">
1911 <xs:annotation>
1912 <xs:documentation><![CDATA[
1913 This tag set defines a sequence of checks or assertions to run against the
1914 target output. This tag requires no attributes, but child tags should be used to
1915 define the assertions to make about the output. The functional test framework
1916 makes it easy to extend Galaxy with such tags, the following table summarizes
1917 many of the default assertion tags that come with Galaxy and examples of each
1918 can be found below.
1919
1920 The implementation of these tags are simply Python functions defined in the
1921 [/lib/galaxy/tool_util/verify/asserts](https://github.com/galaxyproject/galaxy/tree/dev/lib/galaxy/tool_util/verify/asserts)
1922 module.
1923 ]]>
1924 </xs:documentation>
1925 </xs:annotation>
1926 <xs:sequence>
1927 <xs:group ref="TestAssertion" minOccurs="0" maxOccurs="unbounded"/>
1928 </xs:sequence>
1929 </xs:complexType>
1930 <xs:group name="TestAssertion">
1931 <xs:choice>
1932 <xs:element name="has_text" type="xs:anyType">
1933 <xs:annotation>
1934 <xs:documentation><![CDATA[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``.]]>
1935 </xs:documentation>
1936 </xs:annotation>
1937 </xs:element>
1938 <xs:element name="not_has_text" type="xs:anyType">
1939 <xs:annotation>
1940 <xs:documentation><![CDATA[Asserts the specified ``text`` does not appear in the output (e.g. ``<not_has_text text="chr8" />``).]]>
1941 </xs:documentation>
1942 </xs:annotation>
1943 </xs:element>
1944 <xs:element name="has_text_matching" type="xs:anyType">
1945 <xs:annotation>
1946 <xs:documentation><![CDATA[Asserts text matching the specified regular expression (``expression``) appears in the output (e.g. ``<has_text_matching expression="1274\d+53" />`` ).]]>
1947 </xs:documentation>
1948 </xs:annotation>
1949 </xs:element>
1950 <xs:element name="has_line" type="xs:anyType">
1951 <xs:annotation>
1952 <xs:documentation><![CDATA[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``.]]>
1953 </xs:documentation>
1954 </xs:annotation>
1955 </xs:element>
1956 <xs:element name="has_n_lines" type="xs:anyType">
1957 <xs:annotation>
1958 <xs:documentation><![CDATA[Asserts that an output contains ``n`` lines, e.g. ``<has_n_lines n="3" />``.]]>
1959 </xs:documentation>
1960 </xs:annotation>
1961 </xs:element>
1962 <xs:element name="has_line_matching" type="xs:anyType">
1963 <xs:annotation>
1964 <xs:documentation><![CDATA[Asserts a line matching the specified regular expression (``expression``) appears in the output (e.g. ``<has_line_matching expression=".*\s+127489808\s+127494553" />``).]]>
1965 </xs:documentation>
1966 </xs:annotation>
1967 </xs:element>
1968 <xs:element name="has_n_columns" type="xs:anyType">
1969 <xs:annotation>
1970 <xs:documentation><![CDATA[Asserts tabular output contains the specified number (``n``) of columns (e.g. ``<has_n_columns n="3" />``).]]>
1971 </xs:documentation>
1972 </xs:annotation>
1973 </xs:element>
1974 <xs:element name="is_valid_xml" type="xs:anyType">
1975 <xs:annotation>
1976 <xs:documentation><![CDATA[Asserts the output is a valid XML file (e.g. ``<is_valid_xml />``).]]>
1977 </xs:documentation>
1978 </xs:annotation>
1979 </xs:element>
1980 <xs:element name="has_element_with_path" type="xs:anyType">
1981 <xs:annotation>
1982 <xs:documentation><![CDATA[Asserts the XML output contains at least one element (or tag) with the specified XPath-like ``path`` (e.g. ``<has_element_with_path path="BlastOutput_param/Parameters/Parameters_matrix" />``).]]>
1983 </xs:documentation>
1984 </xs:annotation>
1985 </xs:element>
1986 <xs:element name="has_n_elements_with_path" type="xs:anyType">
1987 <xs:annotation>
1988 <xs:documentation><![CDATA[Asserts the XML output contains the specified number (``n``) of elements (or tags) with the specified XPath-like ``path`` (e.g. ``<has_n_elements_with_path n="9" path="BlastOutput_iterations/Iteration/Iteration_hits/Hit/Hit_num" />``).]]>
1989 </xs:documentation>
1990 </xs:annotation>
1991 </xs:element>
1992 <xs:element name="element_text_is" type="xs:anyType">
1993 <xs:annotation>
1994 <xs:documentation><![CDATA[Asserts the text of the XML element with the specified XPath-like ``path`` is the specified ``text`` (e.g. ``<element_text_is path="BlastOutput_program" text="blastp" />``).]]>
1995 </xs:documentation>
1996 </xs:annotation>
1997 </xs:element>
1998 <xs:element name="element_text_matches">
1999 <xs:annotation>
2000 <xs:documentation><![CDATA[Asserts the text of the XML element with the specified XPath-like ``path`` matches the regular expression defined by ``expression`` (e.g. ``<element_text_matches path="BlastOutput_version" expression="BLASTP\s+2\.2.*" />``).]]>
2001 </xs:documentation>
2002 </xs:annotation>
2003 </xs:element>
2004 <xs:element name="attribute_is" type="xs:anyType">
2005 <xs:annotation>
2006 <xs:documentation><![CDATA[Asserts the XML ``attribute`` for the element (or tag) with the specified XPath-like ``path`` is the specified ``text`` (e.g. ``<attribute_is path="outerElement/innerElement1" attribute="foo" text="bar" />`` ).]]>
2007 </xs:documentation>
2008 </xs:annotation>
2009 </xs:element>
2010 <xs:element name="attribute_matches" type="xs:anyType">
2011 <xs:annotation>
2012 <xs:documentation><![CDATA[Asserts the XML ``attribute`` for the element (or tag) with the specified XPath-like ``path`` matches the regular expression specified by ``expression`` (e.g. ``<attribute_matches path="outerElement/innerElement2" attribute="foo2" expression="bar\d+" />``).]]></xs:documentation>
2013 </xs:annotation>
2014 </xs:element>
2015 <xs:element name="element_text" type="xs:anyType">
2016 <xs:annotation>
2017 <xs:documentation><![CDATA[This tag allows the developer to recurisively specify additional assertions as child elements about just the text contained in the element specified by the XPath-like ``path`` (e.g. ``<element_text path="BlastOutput_iterations/Iteration/Iteration_hits/Hit/Hit_def"><not_has_text text="EDK72998.1" /></element_text>``).]]></xs:documentation>
2018 </xs:annotation>
2019 </xs:element>
2020 <xs:element name="has_h5_keys" type="AssertHasH5Keys">
2021 </xs:element>
2022 <xs:element name="has_h5_attribute" type="AssertHasH5Attribute">
2023 </xs:element>
2024 <xs:element name="has_archive_member" type="AssertHasArchiveMember">
2025 </xs:element>
2026 <xs:element name="has_size" type="xs:anyType">
2027 <xs:annotation>
2028 <xs:documentation><![CDATA[Asserts the output has a size (in bytes) of the specified ``value``; if the size is allowed to deviate from this value, the maximum difference can be optionally specified with ``delta`` (e.g. ``<has_size value="10000" delta="100">``).]]>
2029 </xs:documentation>
2030 </xs:annotation>
2031 </xs:element>
2032 </xs:choice>
2033 </xs:group>
2034 <xs:complexType name="AssertHasH5Keys">
2035 <xs:annotation>
2036 <xs:documentation xml:lang="en"><![CDATA[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" />``).]]></xs:documentation>
2037 </xs:annotation>
2038 <xs:attribute name="keys" type="xs:string">
2039 <xs:annotation>
2040 <xs:documentation xml:lang="en">Comma-separated list of HDF5 attributes to check for.</xs:documentation>
2041 </xs:annotation>
2042 </xs:attribute>
2043 </xs:complexType>
2044 <xs:complexType name="AssertHasH5Attribute">
2045 <xs:annotation>
2046 <xs:documentation xml:lang="en"><![CDATA[Asserts HDF5 output contains the specified ``value`` for an attribute (``key``) (e.g. ``<has_attr key="nchroms" value="15" />``).]]></xs:documentation>
2047 </xs:annotation>
2048 <xs:attribute name="key" type="xs:string">
2049 <xs:annotation>
2050 <xs:documentation xml:lang="en">HDF5 attribute to check value of.</xs:documentation>
2051 </xs:annotation>
2052 </xs:attribute>
2053 <xs:attribute name="value" type="xs:string">
2054 <xs:annotation>
2055 <xs:documentation xml:lang="en">Expected value of HDF5 attribute to check.</xs:documentation>
2056 </xs:annotation>
2057 </xs:attribute>
2058 </xs:complexType>
2059 <xs:complexType name="AssertHasArchiveMember">
2060 <xs:annotation>
2061 <xs:documentation xml:lang="en"><![CDATA[This tag allows the developer to recursively specify additional assertions as child elements about just the member contained in the archive specified by the regular expression ``path`` (e.g. ``<has_archive_member path=".*/my-file.txt"><not_has_text text="EDK72998.1" /></has_archive_member>``). Valid archive formats include ``.zip``, ``.tar``, and ``.tar.gz``.]]></xs:documentation>
2062 </xs:annotation>
2063 <xs:sequence>
2064 <xs:group ref="TestAssertion" minOccurs="0" maxOccurs="unbounded"/>
2065 </xs:sequence>
2066 <xs:attribute name="path" type="xs:string">
2067 <xs:annotation>
2068 <xs:documentation xml:lang="en">The regular expression specifying the archive member.</xs:documentation>
2069 </xs:annotation>
2070 </xs:attribute>
2071 </xs:complexType>
2072 <xs:complexType name="Inputs">
2073 <xs:annotation>
2074 <xs:documentation xml:lang="en"><![CDATA[Consists of all elements that define the
2075 tool's input parameters. Each [param](#tool-inputs-param) element contained in this element
2076 can be used as a command line parameter within the [command](#tool-command) text content. Most
2077 tools will not need to specify any attributes on this tag itself.]]>
2078 </xs:documentation>
2079 </xs:annotation>
2080 <xs:sequence>
2081 <xs:group ref="InputElement" minOccurs="0" maxOccurs="unbounded"/>
2082 </xs:sequence>
2083 <xs:attribute name="action" type="xs:string">
2084 <xs:annotation>
2085 <xs:documentation xml:lang="en">URL used by data source tools.</xs:documentation>
2086 </xs:annotation>
2087 </xs:attribute>
2088 <xs:attribute name="check_values" type="PermissiveBoolean" default="true">
2089 <xs:annotation>
2090 <xs:documentation xml:lang="en">Set to ``false`` to disable parameter checking in data source tools.</xs:documentation>
2091 </xs:annotation>
2092 </xs:attribute>
2093 <xs:attribute name="method" type="URLmethodType">
2094 <xs:annotation>
2095 <xs:documentation xml:lang="en">Data source HTTP action (e.g. ``get`` or ``put``) to use.</xs:documentation>
2096 </xs:annotation>
2097 </xs:attribute>
2098 <xs:attribute name="target" type="TargetType">
2099 <xs:annotation>
2100 <xs:documentation xml:lang="en">UI link target to use for data source tools (e.g. ``_top``).</xs:documentation>
2101 </xs:annotation>
2102 </xs:attribute>
2103 <xs:attribute name="nginx_upload" type="PermissiveBoolean" default="false">
2104 <xs:annotation>
2105 <xs:documentation xml:lang="en">This boolean indicates if this is an upload tool or not.</xs:documentation>
2106 </xs:annotation>
2107 </xs:attribute>
2108 </xs:complexType>
2109
2110
2111 <xs:group name="InputElement">
2112 <xs:choice>
2113 <xs:element name="param" type="Param"/>
2114 <xs:element name="repeat" type="Repeat"/>
2115 <xs:element name="conditional" type="Conditional"/>
2116 <xs:element name="section" type="Section"/>
2117 <xs:element name="upload_dataset" type="xs:anyType">
2118 <xs:annotation>
2119 <xs:documentation xml:lang="en">Internal, intentionally undocumented feature.</xs:documentation>
2120 </xs:annotation>
2121 </xs:element>
2122 <xs:element name="display" type="xs:string">
2123 <xs:annotation>
2124 <xs:documentation xml:lang="en">Documentation for display</xs:documentation>
2125 </xs:annotation>
2126 </xs:element>
2127 </xs:choice>
2128 </xs:group>
2129 <xs:complexType name="InputType" abstract="true">
2130 <xs:annotation>
2131 <xs:documentation xml:lang="en">Documentation for InputType</xs:documentation>
2132 </xs:annotation>
2133 <xs:sequence/>
2134 </xs:complexType>
2135
2136
2137 <xs:complexType name="Conditional">
2138 <xs:annotation>
2139 <xs:documentation xml:lang="en"><![CDATA[
2140
2141 This is a container for conditional parameters in the tool (must contain 'when'
2142 tag sets) - the command line (or portions thereof) are then wrapped in an if-else
2143 statement. A good example tool that demonstrates many conditional parameters is
2144 [biom_convert.xml](https://github.com/galaxyproject/tools-iuc/blob/master/tools/biom_format/biom_convert.xml).
2145
2146 ```xml
2147 <conditional name="input_type">
2148 <param name="input_type_selector" type="select" label="Choose the source BIOM format">
2149 <option value="tsv" selected="true">Tabular File</option>
2150 <option value="biom">BIOM File</option>
2151 </param>
2152 <when value="tsv">
2153 <param name="input_table" type="data" format="tabular" label="Tabular File" argument="--input-fp"/>
2154 <param argument="--process-obs-metadata" type="select" label="Process metadata associated with observations when converting">
2155 <option value="" selected="true">Do Not process metadata</option>
2156 <option value="taxonomy">taxonomy</option>
2157 <option value="naive">naive</option>
2158 <option value="sc_separated">sc_separated</option>
2159 </param>
2160 </when>
2161 <when value="biom">
2162 <param name="input_table" type="data" format="biom1" label="Tabular File" argument="--input-fp"/>
2163 </when>
2164 </conditional>
2165 ```
2166
2167 The first directive following the conditional is a [param](#tool-inputs-param),
2168 this param must be of type ``select`` or ``boolean``. Depending on the value a
2169 user selects for this "test" parameter - different UI elements will be shown.
2170 These different paths are described by the following the ``when`` blocks shown
2171 above.
2172
2173 The following Cheetah block demonstrates the use of the ``conditional``
2174 shown above:
2175
2176 ```
2177 biom convert -i "${input_type.input_table}" -o "${output_table}"
2178 #if str($input_type.input_type_selector) == "tsv":
2179 #if $input_type.process_obs_metadata:
2180 --process-obs-metadata "${input_type.process_obs_metadata}"
2181 #end if
2182 #end if
2183 ```
2184
2185 Notice that the parameter ``input_table`` appears down both ``when`` clauses
2186 so ``${input_type.input_table}`` appears unconditionally but we need to
2187 conditionally reference ``${input_type.process_obs_metadata}`` with a Cheetah
2188 ``if`` statement.
2189
2190 A common use of the conditional wrapper is to select between reference data
2191 managed by the Galaxy admins (for instance via
2192 [data managers](https://galaxyproject.org/admin/tools/data-managers/)
2193 ) and
2194 history files. A good example tool that demonstrates this is
2195 the [Bowtie 2](https://github.com/galaxyproject/tools-iuc/blob/master/tools/bowtie2/bowtie2_wrapper.xml) wrapper.
2196
2197 ```xml
2198 <conditional name="reference_genome">
2199 <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">
2200 <option value="indexed">Use a built-in genome index</option>
2201 <option value="history">Use a genome from the history and build index</option>
2202 </param>
2203 <when value="indexed">
2204 <param name="index" type="select" label="Select reference genome" help="If your genome of interest is not listed, contact the Galaxy team">
2205 <options from_data_table="bowtie2_indexes">
2206 <filter type="sort_by" column="2"/>
2207 <validator type="no_options" message="No indexes are available for the selected input dataset"/>
2208 </options>
2209 </param>
2210 </when>
2211 <when value="history">
2212 <param name="own_file" type="data" format="fasta" label="Select reference genome" />
2213 </when>
2214 </conditional>
2215 ```
2216
2217 The Bowtie 2 wrapper also demonstrates other conditional paths - such as choosing
2218 between paired inputs of single stranded inputs.
2219 ]]></xs:documentation>
2220 </xs:annotation>
2221 <xs:complexContent>
2222 <xs:extension base="InputType">
2223 <xs:sequence>
2224 <xs:group ref="InputElement" minOccurs="0" maxOccurs="1" />
2225 <xs:element name="when" type="ConditionalWhen" minOccurs="0" maxOccurs="unbounded"/>
2226 </xs:sequence>
2227 <xs:attribute name="name" type="xs:string">
2228 <xs:annotation>
2229 <xs:documentation xml:lang="en">Name for this element</xs:documentation>
2230 </xs:annotation>
2231 </xs:attribute>
2232 <xs:attribute name="value_from" type="xs:string">
2233 <xs:annotation>
2234 <xs:documentation><![CDATA[Infrequently used option to dynamically access Galaxy internals, this should be avoided.
2235
2236 Galaxy method to execute.]]></xs:documentation>
2237 </xs:annotation>
2238 </xs:attribute>
2239 <xs:attribute name="value_ref" type="xs:string">
2240 <xs:annotation>
2241 <xs:documentation><![CDATA[Infrequently used option to dynamically access Galaxy internals, this should be avoided.
2242
2243 Referenced parameter to pass method.]]></xs:documentation>
2244 </xs:annotation>
2245 </xs:attribute>
2246 <xs:attribute name="value_ref_in_group" type="PermissiveBoolean">
2247 <xs:annotation>
2248 <xs:documentation><![CDATA[Infrequently used option to dynamically access Galaxy internals, this should be avoided.
2249
2250 Is referenced parameter is the same group.]]></xs:documentation>
2251 </xs:annotation>
2252 </xs:attribute>
2253
2254 <xs:attribute name="label" type="xs:string">
2255 <xs:annotation>
2256 <xs:documentation xml:lang="en">Human readable description for the conditional, unused in the Galaxy UI currently.</xs:documentation>
2257 </xs:annotation>
2258 </xs:attribute>
2259
2260 </xs:extension>
2261 </xs:complexContent>
2262 </xs:complexType>
2263
2264
2265
2266 <xs:complexType name="ConditionalWhen">
2267 <xs:annotation>
2268 <xs:documentation xml:lang="en">This directive describes one potential
2269 set of input for the tool at this depth. See documentation for the
2270 [conditional](#tool-inputs-conditional) block for more details and examples (XML
2271 and corresponding Cheetah conditionals).</xs:documentation>
2272 </xs:annotation>
2273 <xs:sequence>
2274 <xs:group ref="InputElement" minOccurs="0" maxOccurs="unbounded"/>
2275 </xs:sequence>
2276 <xs:attribute name="value" type="xs:string" use="required">
2277 <xs:annotation>
2278 <xs:documentation xml:lang="en">Value for the tool form test parameter
2279 corresponding to this ``when`` block.</xs:documentation>
2280 </xs:annotation>
2281 </xs:attribute>
2282 </xs:complexType>
2283
2284
2285
2286 <xs:complexType name="Repeat">
2287 <xs:annotation>
2288 <xs:documentation xml:lang="en"><![CDATA[
2289 See
2290 [xy_plot.xml](https://github.com/galaxyproject/tools-devteam/blob/master/tools/xy_plot/xy_plot.xml)
2291 for an example of how to use this tag set. This is a container for any tag sets
2292 that can be contained within the ``<inputs>`` tag set. When this is used, the
2293 tool will allow the user to add any number of additional sets of the contained
2294 parameters (an option to add new iterations will be displayed on the tool form).
2295 All input parameters contained within the ``<repeat>`` tag can be retrieved by
2296 enumerating over ``$<name_of_repeat_tag_set>`` in the relevant Cheetah code.
2297 This returns the rank and the parameter objects of the repeat container. See the
2298 Cheetah code below.
2299
2300 ### Example
2301
2302 This part is contained in the ``<inputs>`` tag set.
2303
2304 ```xml
2305 <repeat name="series" title="Series">
2306 <param name="input" type="data" format="tabular" label="Dataset"/>
2307 <param name="xcol" type="data_column" data_ref="input" label="Column for x axis"/>
2308 <param name="ycol" type="data_column" data_ref="input" label="Column for y axis"/>
2309 </repeat>
2310 ```
2311
2312 This Cheetah code can be used in the ``<command>`` tag set or the
2313 ``<configfile>`` tag set.
2314
2315 ```
2316 #for $i, $s in enumerate($series)
2317 rank_of_series=$i
2318 input_path='${s.input}'
2319 x_colom=${s.xcol}
2320 y_colom=${s.ycol}
2321 #end for
2322 ```
2323
2324 ### Testing
2325
2326 This is an example test case with multiple repeat elements for the example above.
2327
2328 ```xml
2329 <test>
2330 <repeat name="series">
2331 <param name="input" value="tabular1.tsv" ftype="tabular"/>
2332 <param name="xcol" value="1"/>
2333 <param name="ycol" value="2"/>
2334 </repeat>
2335 <repeat name="series">
2336 <param name="input" value="tabular2.tsv" ftype="tabular"/>
2337 <param name="xcol" value="4"/>
2338 <param name="ycol" value="2"/>
2339 </repeat>
2340 <output name="out_file1" file="cool.pdf" ftype="pdf" />
2341 </test>
2342 ```
2343
2344 See the documentation on the [repeat test directive](#tool-tests-test-repeat).
2345
2346 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>``
2347
2348 ```xml
2349 <test>
2350 <param name="series_0|input" value="tabular1.tsv" ftype="tabular"/>
2351 <param name="series_0|xcol" value="1"/>
2352 <param name="series_0|ycol" value="2"/>
2353 <param name="series_1|input" value="tabular2.tsv" ftype="tabular"/>
2354 <param name="series_1|xcol" value="4"/>
2355 <param name="series_1|ycol" value="2"/>
2356 <output name="out_file1" file="cool.pdf" ftype="pdf" />
2357 </test>
2358 ```
2359
2360 The test tool [disambiguate_repeats.xml](https://github.com/galaxyproject/galaxy/blob/dev/test/functional/tools/disambiguate_repeats.xml)
2361 demonstrates both testing strategies.
2362
2363 ]]></xs:documentation>
2364 </xs:annotation>
2365 <xs:complexContent>
2366 <xs:extension base="InputType">
2367 <xs:sequence>
2368 <xs:group ref="InputElement" minOccurs="0" maxOccurs="unbounded"/>
2369 </xs:sequence>
2370 <xs:attribute name="name" type="xs:string">
2371 <xs:annotation>
2372 <xs:documentation xml:lang="en">Name for this element</xs:documentation>
2373 </xs:annotation>
2374 </xs:attribute>
2375 <xs:attribute name="title" type="xs:string" use="required">
2376 <xs:annotation>
2377 <xs:documentation xml:lang="en">The title of the repeat section, which will be displayed on the tool form.</xs:documentation>
2378 </xs:annotation>
2379 </xs:attribute>
2380 <xs:attribute name="min" type="xs:integer">
2381 <xs:annotation>
2382 <xs:documentation xml:lang="en">The minimum number of repeat units.</xs:documentation>
2383 </xs:annotation>
2384 </xs:attribute>
2385 <xs:attribute name="max" type="xs:integer">
2386 <xs:annotation>
2387 <xs:documentation xml:lang="en">The maximum number of repeat units.</xs:documentation>
2388 </xs:annotation>
2389 </xs:attribute>
2390 <xs:attribute name="default" type="xs:integer" default="1">
2391 <xs:annotation>
2392 <xs:documentation xml:lang="en">The default number of repeat units.</xs:documentation>
2393 </xs:annotation>
2394 </xs:attribute>
2395 <xs:attribute name="help" type="xs:string">
2396 <xs:annotation>
2397 <xs:documentation xml:lang="en">Short help description for repeat element.</xs:documentation>
2398 </xs:annotation>
2399 </xs:attribute>
2400 </xs:extension>
2401 </xs:complexContent>
2402 </xs:complexType>
2403
2404 <xs:complexType name="Section">
2405 <xs:annotation>
2406 <xs:documentation xml:lang="en"><![CDATA[
2407 This tag is used to group parameters into sections of the interface. Sections
2408 are implemented to replace the commonly used tactic of hiding advanced options
2409 behind a conditional, with sections you can easily visually group a related set
2410 of options.
2411
2412 ### Example
2413
2414 The XML configuration is relatively trivial for sections:
2415
2416 ```xml
2417 <inputs>
2418 <section name="section_name" title="Section Title" >
2419 <param name="parameter_name" type="text" label="A parameter label" />
2420 </section>
2421 </inputs>
2422 ```
2423
2424 In your command template, you'll need to include the section name to access the
2425 variable:
2426
2427 ```
2428 $section_name.parameter_name
2429 ```
2430
2431 In output filters sections are represented as dictionary with the same name as the section:
2432
2433 ```
2434 <filter>section_name['parameter_name']</filter>
2435 ```
2436
2437 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:
2438
2439 ```
2440 <data name="output" format_source="section_name|parameter_name" metadata_source="section_name|parameter_name"/>
2441 ```
2442
2443 Until profile 21.01 `parameter_name` was sufficient (https://github.com/galaxyproject/galaxy/pull/9493/files).
2444
2445 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.
2446
2447 ```
2448 <param name="foo" type="data" format="tabular"/>
2449 <param name="bar" type="data_column" data_ref="foo"/>
2450 <section>
2451 <param name="qux" type="data_column" data_ref="foo"/>
2452 <param name="foo" type="data" format="tabular"/>
2453 <param name="baz" type="data_column" data_ref="foo"/>
2454 </section>
2455 ```
2456
2457 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.
2458
2459 The following will not work:
2460
2461 ```
2462 <section>
2463 <param name="foo" type="data" format="tabular"/>
2464 </section>
2465 <param name="bar" type="data_column" data_ref="foo"/>
2466 ```
2467
2468 Further examples can be found in the [test case](https://github.com/galaxyproject/galaxy/blob/master/test/functional/tools/section.xml) from [pull request #35](https://github.com/galaxyproject/galaxy/pull/35).
2469 ]]></xs:documentation>
2470 </xs:annotation>
2471 <xs:sequence>
2472 <xs:group ref="InputElement" minOccurs="0" maxOccurs="unbounded"/>
2473 </xs:sequence>
2474 <xs:attribute name="name" type="xs:string" use="required">
2475 <xs:annotation>
2476 <xs:documentation xml:lang="en">The internal key used for the section.</xs:documentation>
2477 </xs:annotation>
2478 </xs:attribute>
2479 <xs:attribute name="title" type="xs:string" use="required">
2480 <xs:annotation>
2481 <xs:documentation xml:lang="en">Human readable label for the section.</xs:documentation>
2482 </xs:annotation>
2483 </xs:attribute>
2484 <xs:attribute name="expanded" type="PermissiveBoolean" default="false">
2485 <xs:annotation>
2486 <xs:documentation xml:lang="en">Whether the section should be expanded by default or not. If not, the default set values are used.</xs:documentation>
2487 </xs:annotation>
2488 </xs:attribute>
2489 <xs:attribute name="help" type="xs:string">
2490 <xs:annotation>
2491 <xs:documentation xml:lang="en">Short help description for section, rendered just below the section.</xs:documentation>
2492 </xs:annotation>
2493 </xs:attribute>
2494 </xs:complexType>
2495
2496 <xs:complexType name="Param">
2497 <xs:annotation>
2498 <xs:documentation xml:lang="en"><![CDATA[
2499
2500 Contained within the ``<inputs>`` tag set - each of these specifies a field that
2501 will be displayed on the tool form. Ultimately, the values of these form fields
2502 will be passed as the command line parameters to the tool's executable.
2503
2504 ### Common Attributes
2505
2506 The attributes valid for this tag vary wildly based on the ``type`` of the
2507 parameter being described. All the attributes for the ``param`` element are
2508 documented below for completeness, but here are the common ones for each
2509 type are as follows:
2510
2511 $attribute_list:name,type,optional,label,help,argument,load_contents,refresh_on_change:4
2512
2513 ### Parameter Types
2514
2515 #### ``text``
2516
2517 When ``type="text"``, the parameter is free form text and appears as a text box
2518 in the tool form.
2519
2520 ##### Examples
2521
2522 Sometimes you need labels for data or graph axes, chart titles, etc. This can be
2523 done using a text field. The following will create a text box with the default
2524 value of "V1".
2525
2526 ```xml
2527 <param name="xlab" type="text" value="V1" label="Label for x axis" />
2528 ```
2529
2530 The ``area`` boolean attribute can be used to change the ``text`` parameter to a
2531 two-dimensional text area instead of a single line text box.
2532
2533 ```xml
2534 <param name="foo" type="text" area="true" />
2535 ```
2536
2537 Since release 17.01, ``text`` parameters can also supply a static list of preset
2538 defaults options. The user **may** be presented with the option to select one of
2539 these but will be allowed to supply an arbitrary text value.
2540
2541 ```xml
2542 <param name="foo" type="text" value="foo 1">
2543 <option value="foo 1">Foo 1 Display</option>
2544 <option value="foo 2">Foo 2 Display</option>
2545 </param>
2546 ```
2547
2548 See [param_text_option.xml](https://github.com/galaxyproject/galaxy/blob/dev/test/functional/tools/param_text_option.xml)
2549 for a demonstration of this.
2550
2551 $attribute_list:value,size,area:5
2552
2553 #### ``integer`` and ``float``
2554
2555 These parameters represent whole number and real numbers, respectively.
2556
2557 ##### Example
2558
2559 ```xml
2560 <param name="region_size" type="integer" value="1" label="Size of the flanking regions" />
2561 ```
2562
2563 $attribute_list:value,min,max:5
2564
2565 #### ``boolean``
2566
2567 This represents a binary true or false value.
2568
2569 $attribute_list:checked,truevalue,falsevalue:5
2570
2571 #### ``data``
2572
2573 A dataset from the current history. Multiple types might be used for the param form.
2574
2575 ##### Examples
2576
2577 The following will find all "coordinate interval files" contained within the
2578 current history and dynamically populate a select list with them. If they are
2579 selected, their destination and internal file name will be passed to the
2580 appropriate command line variable.
2581
2582 ```xml
2583 <param name="interval_file" type="data" format="interval" label="near intervals in"/>
2584 ```
2585
2586 The following demonstrates a ``param`` which may accept multiple files and
2587 multiple formats.
2588
2589 ```xml
2590 <param format="sam,bam" multiple="true" name="bamOrSamFile" type="data"
2591 label="Alignments in BAM or SAM format"
2592 help="The set of aligned reads." />
2593 ```
2594
2595 Perhaps counter-intuitively, a ``multiple="true"`` data parameter requires at least one
2596 data input. If ``optional="true"`` is specified, this condition is relaxed and the user
2597 is allowed to select 0 datasets. Unfortunately, if 0 datasets are selected the resulting
2598 value for the parameter during Cheetah templating (such as in a ``command`` block) will
2599 effectively be a list with one ``None``-like entity in it.
2600
2601 The following idiom can be used to iterate over such a list and build a hypothetical ``-B``
2602 parameter for each file - the ``if`` block is used to handle the case where a ``None``-like
2603 entity appears in the list because no files were selected:
2604
2605 ```
2606 #for $input in $input1
2607 #if $input
2608 -B "$input"
2609 #end if
2610 #end for
2611 ```
2612
2613 Some example tools using ``multiple="true"`` data parameters include:
2614
2615 - [multi_data_param.xml](https://github.com/galaxyproject/galaxy/blob/dev/test/functional/tools/multi_data_param.xml)
2616 - [multi_data_optional.xml](https://github.com/galaxyproject/galaxy/blob/dev/test/functional/tools/multi_data_optional.xml)
2617
2618 Additionally, a detailed discussion of handling multiple homogenous files can be found in the
2619 the [Planemo Documentation](https://planemo.readthedocs.io/en/latest/writing_advanced.html#consuming-collections)
2620 on this topic.
2621
2622 $attribute_list:format,multiple,optional,min,max:5
2623
2624 #### ``group_tag``
2625
2626 $attribute_list:multiple,date_ref:5
2627
2628 #### ``select``
2629
2630 The following will create a select list containing the options "Downstream" and
2631 "Upstream". Depending on the selection, a ``d`` or ``u`` value will be passed to
2632 the ``$upstream_or_down`` variable on the command line.
2633
2634 ```xml
2635 <param name="upstream_or_down" type="select" label="Get">
2636 <option value="u">Upstream</option>
2637 <option value="d">Downstream</option>
2638 </param>
2639 ```
2640
2641 The following will create a checkbox list allowing the user to select
2642 "Downstream", "Upstream", both, or neither. Depending on the selection, the
2643 value of ``$upstream_or_down`` will be ``d``, ``u``, ``u,d``, or "".
2644
2645 ```xml
2646 <param name="upstream_or_down" type="select" label="Get" multiple="true" display="checkboxes">
2647 <option value="u">Upstream</option>
2648 <option value="d">Downstream</option>
2649 </param>
2650 ```
2651
2652 $attribute_list:data_ref,dynamic_options,display,multiple:5
2653
2654 #### ``data_column``
2655
2656 This parameter type is used to select columns from a parameter.
2657
2658 $attribute_list:force_select,numerical,use_header_name:5
2659
2660 #### ``drill_down``
2661
2662 $attribute_list:hierarchy:5
2663
2664 #### ``data_collection``
2665
2666 The following will create a parameter that only accepts paired FASTQ files grouped into a collection.
2667
2668 ##### Examples
2669
2670 ```xml
2671 <param name="inputs" type="data_collection" collection_type="paired" label="Input FASTQs" format="fastq">
2672 </param>
2673 ```
2674
2675 More detailed information on writing tools that consume collections can be found
2676 in the [planemo documentation](https://planemo.readthedocs.io/en/latest/writing_advanced.html#collections).
2677
2678 $attribute_list:format,collection_type:5
2679
2680 #### ``color``
2681
2682 ##### Examples
2683
2684 The following example will create a color selector parameter.
2685
2686 ```xml
2687 <param name="feature_color" type="color" label="Default feature color" value="#ff00ff">
2688 </param>
2689 ```
2690
2691 Given that the output includes a pound sign, it is often convenient to use a
2692 sanitizer to prevent Galaxy from escaping the result.
2693
2694 ```xml
2695 <param name="feature_color" type="color" label="Default feature color" value="#ff00ff">
2696 <sanitizer>
2697 <valid initial="string.ascii_letters,string.digits">
2698 <add value="#" />
2699 </valid>
2700 </sanitizer>
2701 </param>
2702 ```
2703
2704 #### ``directory_uri``
2705
2706 This is used to tie into galaxy.files URI infrastructure. This should only be used by
2707 core Galaxy tools until the interface around files has stabilized.
2708
2709 Currently ``directory_uri`` parameters provide user's the option of selecting a writable
2710 directory destination for unstructured outputs of tools (e.g. history exports).
2711
2712 $attribute_list:value,rgb:5
2713
2714 This covers examples of the most common parameter types, the remaining parameter
2715 types are more obsecure and less likely to be useful for most tool authors.
2716
2717 ]]></xs:documentation>
2718 </xs:annotation>
2719 <xs:complexContent>
2720 <xs:extension base="InputType">
2721 <xs:sequence>
2722 <xs:group ref="ParamElement" minOccurs="0" maxOccurs="unbounded" />
2723 </xs:sequence>
2724 <xs:attribute name="type" type="ParamType" use="required">
2725 <xs:annotation>
2726 <xs:documentation xml:lang="en"><![CDATA[
2727
2728 Describes the parameter type - each different type as different semantics and
2729 the tool form widget is different. Currently valid parameter types are:
2730 ``text``, ``integer``, ``float``, ``boolean``, ``genomebuild``, ``select``,
2731 ``color``, ``data_column``, ``hidden``, ``hidden_data``, ``baseurl``,
2732 ``file``, ``ftpfile``, ``data``, ``data_collection``, ``library_data``,
2733 ``drill_down``. The definition of supported parameter types as defined in the
2734 ``parameter_types`` dictionary in
2735 [/lib/galaxy/tools/parameters/basic.py](https://github.com/galaxyproject/galaxy/blob/master/lib/galaxy/tools/parameters/basic.py).
2736
2737 ]]></xs:documentation>
2738 </xs:annotation>
2739 </xs:attribute>
2740 <xs:attribute name="name" type="xs:string">
2741 <xs:annotation>
2742 <xs:documentation xml:lang="en"><![CDATA[Name for this element. This ``name``
2743 is used as the Cheetah variable containing the user-supplied parameter name in
2744 ``command`` and ``configfile`` elements. The name should not contain pipes or
2745 periods (e.g. ``.``). Some "reserved" names are ``REDIRECT_URL``,
2746 ``DATA_URL``, ``GALAXY_URL``.]]></xs:documentation>
2747 </xs:annotation>
2748 </xs:attribute>
2749 <!-- TODO: add unique constraints... -->
2750 <xs:attribute name="area" type="PermissiveBoolean">
2751 <xs:annotation>
2752 <xs:documentation xml:lang="en">Boolean indicating if this should be
2753 rendered as a one line text box (if ``false``, the default) or a multi-line text
2754 area (if ``true``).</xs:documentation>
2755 </xs:annotation>
2756 </xs:attribute>
2757 <xs:attribute name="argument" type="xs:string">
2758 <xs:annotation>
2759 <xs:documentation xml:lang="en"><![CDATA[
2760
2761 If the parameter reflects just one command line argument of a certain tool, this
2762 tag should be set to that particular argument. It is rendered in parenthesis
2763 after the help section, and it will create the name attribute (if not given explicitly)
2764 from the argument attribute by stripping leading dashes and replacing all remaining
2765 dashes by underscores (e.g. if ``argument="--long-parameter"`` then
2766 ``name="long_parameter"`` is implicit).
2767
2768 ]]></xs:documentation>
2769 </xs:annotation>
2770 </xs:attribute>
2771 <xs:attribute name="label" type="xs:string">
2772 <xs:annotation>
2773 <xs:documentation xml:lang="en">The attribute value will be
2774 displayed on the tool page as the label of the form field
2775 (``label="Sort Query"``).</xs:documentation>
2776 </xs:annotation>
2777 </xs:attribute>
2778 <xs:attribute name="help" type="xs:string">
2779 <xs:annotation gxdocs:best_practices="parameter-help">
2780 <xs:documentation xml:lang="en">Short bit of text, rendered on the
2781 tool form just below the associated field to provide information about the
2782 field.</xs:documentation>
2783 </xs:annotation>
2784 </xs:attribute>
2785 <xs:attribute name="load_contents" type="xs:integer">
2786 <xs:annotation>
2787 <xs:documentation xml:lang="en">Number of bytes that should be
2788 loaded into the `contents` attribute of the jobs dictionary provided to Expression
2789 Tools. Applies only to type="data" inputs.</xs:documentation>
2790 </xs:annotation>
2791 </xs:attribute>
2792 <xs:attribute name="value" type="xs:string">
2793 <xs:annotation>
2794 <xs:documentation xml:lang="en">The default value for this
2795 parameter.</xs:documentation>
2796 </xs:annotation>
2797 </xs:attribute>
2798 <xs:attribute name="default_value" type="xs:string" gxdocs:deprecated="true">
2799 <xs:annotation>
2800 <xs:documentation xml:lang="en">*Deprecated*. Specify default value for column parameters (use ``value`` instead).</xs:documentation>
2801 </xs:annotation>
2802 </xs:attribute>
2803 <xs:attribute name="optional" type="xs:string" default="false">
2804 <xs:annotation>
2805 <xs:documentation xml:lang="en">If ``false``, parameter must have a
2806 value. Defaults to "false".</xs:documentation>
2807 </xs:annotation>
2808 </xs:attribute>
2809 <xs:attribute name="rgb" type="xs:string" default="false">
2810 <xs:annotation>
2811 <xs:documentation xml:lang="en">If ``false``, the returned value will be in Hex color code. If ``true``
2812 it will be a RGB value e.g. 0,0,255. This attribute is only valid when ``type`` is ``color``.</xs:documentation>
2813 </xs:annotation>
2814 </xs:attribute>
2815 <xs:attribute name="min" type="xs:float">
2816 <xs:annotation>
2817 <xs:documentation xml:lang="en">Minimum valid parameter value - only
2818 valid when ``type`` is ``integer``, ``float``, or ``data``.</xs:documentation>
2819 </xs:annotation>
2820 </xs:attribute>
2821 <xs:attribute name="max" type="xs:float">
2822 <xs:annotation>
2823 <xs:documentation xml:lang="en">Maximum valid parameter value - only
2824 valid when ``type`` is ``integer``, ``float``, or ``data``.</xs:documentation>
2825 </xs:annotation>
2826 </xs:attribute>
2827 <xs:attribute name="format" type="xs:string">
2828 <xs:annotation>
2829 <xs:documentation xml:lang="en">Only if ``type`` attribute value is
2830 ``data`` or ``data_collection`` - the list of supported data formats is
2831 contained in the
2832 [/config/datatypes_conf.xml.sample](https://github.com/galaxyproject/galaxy/blob/dev/config/datatypes_conf.xml.sample)
2833 file. Use the file extension.</xs:documentation>
2834 </xs:annotation>
2835 </xs:attribute>
2836 <xs:attribute name="collection_type" type="xs:string">
2837 <xs:annotation>
2838 <xs:documentation xml:lang="en"><![CDATA[
2839
2840 This is only valid if ``type`` is ``data_collection``. Restrict the kind of
2841 collection that can be consumed by this parameter (e.g. ``paired``,
2842 ``list:paired``, ``list``). Multiple such collection types can be specified here
2843 as a comma-separated list.
2844
2845 ]]></xs:documentation>
2846 </xs:annotation>
2847 </xs:attribute>
2848 <xs:attribute name="data_ref" type="xs:string">
2849 <xs:annotation>
2850 <xs:documentation xml:lang="en"><![CDATA[
2851
2852 Only valid if ``type`` attribute value is ``select``, ``data_column``, or
2853 ``group_tag``. Used with select lists whose options are dynamically generated
2854 based on certain metadata attributes of the dataset or collection upon which
2855 this parameter depends (usually but not always the tool's input dataset).
2856
2857 ]]></xs:documentation>
2858 </xs:annotation>
2859 </xs:attribute>
2860 <xs:attribute name="accept_default" type="PermissiveBoolean">
2861 <xs:annotation>
2862 <xs:documentation xml:lang="en"></xs:documentation>
2863 </xs:annotation>
2864 </xs:attribute>
2865 <xs:attribute name="refresh_on_change" type="PermissiveBoolean">
2866 <xs:annotation>
2867 <xs:documentation xml:lang="en">Force a reload of the tool panel when the value of this parameter changes to allow ``code`` file processing. See deprecation-like notice for ``code`` blocks.</xs:documentation>
2868 </xs:annotation>
2869 </xs:attribute>
2870 <xs:attribute name="force_select" type="PermissiveBoolean" gxdocs:deprecated="true">
2871 <xs:annotation>
2872 <xs:documentation xml:lang="en">*Deprecated*. Used only if the ``type`` attribute
2873 value is ``data_column``, this is deprecated and the inverse of ``optional``.
2874 Set to ``false`` to not force user to select an option in the list.</xs:documentation>
2875 </xs:annotation>
2876 </xs:attribute>
2877 <xs:attribute name="use_header_names" type="PermissiveBoolean">
2878 <xs:annotation>
2879 <xs:documentation xml:lang="en">Used only if the ``type`` attribute
2880 value is ``data_column``. If ``true``, Galaxy assumes the first row of ``data_ref``
2881 is a header and builds the select list with these values rather than the more
2882 generic ``c1`` ... ``cN`` (i.e. it will be ``c1: head1`` ... ``cN: headN``).
2883 Note that the content of the Cheetah variable is still
2884 the column index.
2885 </xs:documentation>
2886 </xs:annotation>
2887 </xs:attribute>
2888 <xs:attribute name="display" type="DisplayType">
2889 <xs:annotation>
2890 <xs:documentation xml:lang="en">This attribute is used only if
2891 ``type`` attribute value is ``select`` - render a select list as a set of check
2892 boxes or radio buttons. Defaults to a drop-down menu select list.</xs:documentation>
2893 </xs:annotation>
2894 </xs:attribute>
2895 <xs:attribute name="multiple" type="PermissiveBoolean">
2896 <xs:annotation>
2897 <xs:documentation xml:lang="en">Allow multiple valus to be selected.
2898 Valid with ``data`` and ``select`` parameters. ``select`` parameters with ``multiple="true"`` are optional by default.</xs:documentation>
2899 </xs:annotation>
2900 </xs:attribute>
2901 <xs:attribute name="numerical" type="PermissiveBoolean">
2902 <xs:annotation>
2903 <xs:documentation xml:lang="en">Used only if the ``type`` attribute
2904 value is ``data_column``, if ``true`` the column will be treated as numerical
2905 when filtering columns based on metadata.</xs:documentation>
2906 </xs:annotation>
2907 </xs:attribute>
2908 <xs:attribute name="hierarchy" type="HierarchyType">
2909 <xs:annotation>
2910 <xs:documentation xml:lang="en">Used only if the ``type`` attribute
2911 value is ``drill_down``, this attribute determines the drill down is
2912 ``recursive`` or ``exact``.</xs:documentation>
2913 </xs:annotation>
2914 </xs:attribute>
2915 <xs:attribute name="checked" type="PermissiveBoolean" default="false">
2916 <xs:annotation>
2917 <xs:documentation xml:lang="en">Set to ``true`` if the ``boolean``
2918 parameter should be checked (or ``true``) by default.</xs:documentation>
2919 </xs:annotation>
2920 </xs:attribute>
2921 <xs:attribute name="truevalue" type="xs:string">
2922 <xs:annotation>
2923 <xs:documentation xml:lang="en">The parameter value in the Cheetah
2924 template if the parameter is ``true`` or checked by the user. Only valid if
2925 ``type`` is ``boolean``.</xs:documentation>
2926 </xs:annotation>
2927 </xs:attribute>
2928 <xs:attribute name="falsevalue" type="xs:string">
2929 <xs:annotation>
2930 <xs:documentation xml:lang="en">The parameter value in the Cheetah
2931 template if the parameter is ``false`` or not checked by the user. Only valid if
2932 ``type`` is ``boolean``.</xs:documentation>
2933 </xs:annotation>
2934 </xs:attribute>
2935 <xs:attribute name="size" type="xs:string" gxdocs:deprecated="true">
2936 <!-- TODO: can be integer or integerxinteger -->
2937 <xs:annotation>
2938 <xs:documentation xml:lang="en">*Deprecated*. Used only if ``type`` attribute
2939 value is ``text``. Completely ignored since release 16.10.</xs:documentation>
2940 </xs:annotation>
2941 </xs:attribute>
2942 <!-- metadata_name appears in some wrappers but I think this is a copy
2943 and paste problem and doesn't reflect something actually used by
2944 Galaxy.
2945 -->
2946 <!--
2947 <xs:attribute name="metadata_name" type="xs:string">
2948 <xs:annotation>
2949 <xs:documentation xml:lang="en">Documentation for metadata_name</xs:documentation>
2950 </xs:annotation>
2951 </xs:attribute>
2952 -->
2953 <xs:attribute name="dynamic_options" type="xs:string">
2954 <xs:annotation>
2955 <xs:documentation xml:lang="en">Deprecated/discouraged method to
2956 allow access to Python code to generate options for a select list. See
2957 ``code``'s documentation for an example.
2958 </xs:documentation>
2959 </xs:annotation>
2960 </xs:attribute>
2961 </xs:extension>
2962 </xs:complexContent>
2963 </xs:complexType>
2964
2965 <xs:group name="ParamElement">
2966 <xs:choice>
2967 <xs:element name="label" type="xs:string">
2968 <xs:annotation>
2969 <xs:documentation xml:lang="en">Documentation for label</xs:documentation>
2970 </xs:annotation>
2971 </xs:element>
2972 <xs:element name="conversion" type="ParamConversion" />
2973 <xs:element name="option" type="ParamOption" />
2974 <xs:element name="options" type="ParamOptions"/>
2975 <xs:element name="validator" type="Validator" />
2976 <xs:element name="sanitizer" type="Sanitizer"/>
2977 <xs:element name="help" type="xs:string">
2978 <xs:annotation>
2979 <xs:documentation xml:lang="en">Documentation for help</xs:documentation>
2980 </xs:annotation>
2981 </xs:element>
2982 </xs:choice>
2983 </xs:group>
2984
2985 <xs:simpleType name="ParamType">
2986 <xs:annotation>
2987 <xs:documentation xml:lang="en">Documentation for ParamType</xs:documentation>
2988 </xs:annotation>
2989 <xs:restriction base="xs:string">
2990 <xs:enumeration value="text"/>
2991 <xs:enumeration value="integer"/>
2992 <xs:enumeration value="float"/>
2993 <xs:enumeration value="color"/>
2994 <xs:enumeration value="boolean"/>
2995 <xs:enumeration value="genomebuild"/>
2996 <xs:enumeration value="library_data"/>
2997 <xs:enumeration value="select"/>
2998 <xs:enumeration value="data_column"/>
2999 <xs:enumeration value="hidden"/>
3000 <xs:enumeration value="hidden_data"/>
3001 <xs:enumeration value="baseurl"/>
3002 <xs:enumeration value="file"/>
3003 <xs:enumeration value="data"/>
3004 <xs:enumeration value="drill_down"/>
3005 <xs:enumeration value="group_tag"/>
3006 <xs:enumeration value="data_collection"/>
3007 <xs:enumeration value="directory_uri" />
3008 </xs:restriction>
3009 </xs:simpleType>
3010
3011
3012 <xs:complexType name="Command">
3013 <xs:annotation gxdocs:best_practices="command-tag">
3014 <xs:documentation xml:lang="en"><![CDATA[
3015 This tag specifies how Galaxy should invoke the tool's executable, passing its
3016 required input parameter values (the command line specification links the
3017 parameters supplied in the form with the actual tool executable). Any word
3018 inside it starting with a dollar sign (``$``) will be treated as a variable whose
3019 values can be acquired from one of three sources: parameters, metadata, or
3020 output files. After the substitution of variables with their values, the content
3021 is interpreted with [Cheetah](https://pythonhosted.org/Cheetah/) and finally given
3022 to the interpreter specified in the corresponding attribute (if any).
3023
3024 ### Examples
3025
3026 The following uses a compiled executable ([bedtools](https://bedtools.readthedocs.io/en/latest/)).
3027
3028 ```xml
3029 <command><![CDATA[
3030 bed12ToBed6 -i '$input' > '$output'
3031 ]]]]><![CDATA[></command>
3032 ```
3033
3034 A few things to note about even this simple example:
3035
3036 * Input and output variables (boringly named ``input`` and ``output``)
3037 are expanded into paths using the ``$`` Cheetah directive.
3038 * Paths should be quoted so that the Galaxy database files may contain spaces.
3039 * We are building up a shell script - so special characters like ``>`` can be used
3040 (in this case the standard output of the bedtools call is written to the path
3041 specified by ``'$output'``).
3042
3043 The bed12ToBed6 tool can be found [here](https://github.com/galaxyproject/tools-iuc/blob/master/tools/bedtools/bed12ToBed6.xml).
3044
3045 A more sophisticated bedtools example demonstrates the use of loops, conditionals,
3046 and uses whitespace to make a complex command very readable can be found in
3047 [annotateBed](https://github.com/galaxyproject/tools-iuc/blob/master/tools/bedtools/annotateBed.xml)
3048 tool.
3049
3050 ```xml
3051 <command><![CDATA[
3052 bedtools annotate
3053 -i '${inputA}'
3054 #if $names.names_select == 'yes':
3055 -files
3056 #for $bed in $names.beds:
3057 '${bed.input}'
3058 #end for
3059 -names
3060 #for $bed in $names.beds:
3061 '${bed.inputName}'
3062 #end for
3063 #else:
3064 #set files = '" "'.join([str($file) for $file in $names.beds])
3065 -files '${files}'
3066 #set names = '" "'.join([str($name.display_name) for $name in $names.beds])
3067 -names '${names}'
3068 #end if
3069 $strand
3070 $counts
3071 $both
3072 > '${output}'
3073 ]]]]><![CDATA[></command>
3074 ```
3075
3076 The following example (taken from [xpath](https://github.com/galaxyproject/tools-iuc/blob/master/tools/xpath/xpath.xml) tool)
3077 uses an interpreted executable. In this case a Perl script is shipped with the
3078 tool and the directory of the tool itself is referenced with ``$__tool_directory__``.
3079
3080 ```xml
3081 <command><![CDATA[
3082 perl '$__tool_directory__/xpath' -q -e '$expression' '$input' > '$output'
3083 ]]]]><![CDATA[></command>
3084 ```
3085
3086 The following example demonstrates accessing metadata from datasets. Metadata values
3087 (e.g., ``${input.metadata.chromCol}``) are acquired from the ``Metadata`` model associated
3088 with the objects selected as the values of each of the relative form field
3089 parameters in the tool form. Accessing this information is generally enabled using
3090 the following feature components.
3091
3092 A set of "metadata information" is defined for each supported data type (see the
3093 ``MetadataElement`` objects in the various data types classes in
3094 [/lib/galaxy/datatypes](https://github.com/galaxyproject/galaxy/tree/dev/lib/galaxy/datatypes).
3095 The ``DatasetFilenameWrapper`` class in the
3096 [/lib/galaxy/tools/wrappers.py](https://github.com/galaxyproject/galaxy/blob/dev/lib/galaxy/tools/wrappers.py)
3097 code file wraps a metadata collection to return metadata parameters wrapped
3098 according to the Metadata spec.
3099
3100 ```xml
3101 <command><![CDATA[
3102 #set genome = $input.metadata.dbkey
3103 #set datatype = $input.datatype
3104 mkdir -p output_dir &&
3105 python '$__tool_directory__/extract_genomic_dna.py'
3106 --input '$input'
3107 --genome '$genome'
3108 #if $input.is_of_type("gff"):
3109 --input_format "gff"
3110 --columns "1,4,5,7"
3111 --interpret_features $interpret_features
3112 #else:
3113 --input_format "interval"
3114 --columns "${input.metadata.chromCol},${input.metadata.startCol},${input.metadata.endCol},${input.metadata.strandCol},${input.metadata.nameCol}"
3115 #end if
3116 --reference_genome_source $reference_genome_cond.reference_genome_source
3117 #if str($reference_genome_cond.reference_genome_source) == "cached"
3118 --reference_genome $reference_genome_cond.reference_genome.fields.path
3119 #else:
3120 --reference_genome $reference_genome_cond.reference_genome
3121 #end if
3122 --output_format $output_format_cond.output_format
3123 #if str($output_format_cond.output_format) == "fasta":
3124 --fasta_header_type $output_format_cond.fasta_header_type_cond.fasta_header_type
3125 #if str($output_format_cond.fasta_header_type_cond.fasta_header_type) == "char_delimited":
3126 --fasta_header_delimiter $output_format_cond.fasta_header_type_cond.fasta_header_delimiter
3127 #end if
3128 #end if
3129 --output '$output'
3130 ]]]]><![CDATA[></command>
3131 ```
3132
3133 In additon to demonstrating accessing metadata, this example demonstrates:
3134
3135 * ``$input.is_of_type("gff")`` which can be used to check if an input is of a
3136 given datatype.
3137 * ``#set datatype = $input.datatype`` which is the syntax for defining variables
3138 in Cheetah.
3139
3140 ### Reserved Variables
3141
3142 Galaxy provides a few pre-defined variables which can be used in your command line,
3143 even though they don't appear in your tool's parameters.
3144
3145 Name | Description
3146 ---- | -----------
3147 ``$__tool_directory__`` | The directory the tool description (XML file) currently resides in (new in 15.03)
3148 ``$__new_file_path__`` | ``config/galaxy.ini``'s ``new_file_path`` value
3149 ``$__tool_data_path__`` | ``config/galaxy.ini``'s tool_data_path value
3150 ``$__root_dir__`` | Top-level Galaxy source directory made absolute via ``os.path.abspath()``
3151 ``$__datatypes_config__`` | ``config/galaxy.ini``'s datatypes_config value
3152 ``$__user_id__`` | Email's numeric ID (id column of ``galaxy_user`` table in the database)
3153 ``$__user_email__`` | User's email address
3154 ``$__app__`` | The ``galaxy.app.UniverseApplication`` instance, gives access to all other configuration file variables (e.g. $__app__.config.output_size_limit). Should be used as a last resort, may go away in future releases.
3155
3156 Additional runtime properties are available as environment variables. Since these
3157 are not Cheetah variables (the values aren't available until runtime) these should likely
3158 be escaped with a backslash (``\``) when appearing in ``command`` or ``configfile`` elements.
3159
3160 Name | Description
3161 ---- | -----------
3162 ``\${GALAXY_SLOTS:-4}`` | Number of cores/threads allocated by the job runner or resource manager to the tool for the given job (here 4 is the default number of threads to use if running via custom runner that does not configure GALAXY_SLOTS or in an older Galaxy runtime).
3163 ``\$GALAXY_MEMORY_MB`` | Total amount of memory in megabytes (1024^2 bytes) allocated by the administrator (via the resource manager) to the tool for the given job. If unset, tools should not attempt to limit memory usage.
3164 ``\$GALAXY_MEMORY_MB_PER_SLOT`` | Amount of memory per slot in megabytes (1024^2 bytes) allocated by the administrator (via the resource manager) to the tool for the given job. If unset, tools should not attempt to limit memory usage.
3165 ``\$_GALAXY_JOB_TMP_DIR`` | Path to an empty directory in the job's working directory that can be used as a temporary directory.
3166
3167 See the [Planemo docs](https://planemo.readthedocs.io/en/latest/writing_advanced.html#cluster-usage)
3168 on the topic of ``GALAXY_SLOTS`` for more information and examples.
3169
3170 ### Error detection
3171
3172 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:
3173
3174 * ``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.
3175 * ``exit_code``: adds checks for non zero exit codes (The @jmchilton recommendation). The ``oom_exit_code`` parameter can be used to add an additional out of memory indicating exit code.
3176 * ``aggressive``: adds checks for non zero exit codes, and checks for ``Exception:``, ``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).
3177
3178 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.
3179 ]]></xs:documentation>
3180 </xs:annotation>
3181 <xs:simpleContent>
3182 <xs:extension base="xs:string">
3183 <xs:attribute name="detect_errors" type="DetectErrorType">
3184 <xs:annotation>
3185 <xs:documentation xml:lang="en"><![CDATA[
3186 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:
3187
3188 * ``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.
3189 * ``exit_code``: adds checks for non zero exit codes. The ``oom_exit_code`` parameter can be used to add an additional out of memory indicating exit code. This is the default when a tool specifies a ``profile`` >= 16.04.
3190 * ``aggressive``: adds checks for non zero exit codes, and checks for ``Exception:``, ``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``).
3191 ]]>
3192 </xs:documentation>
3193 </xs:annotation>
3194 </xs:attribute>
3195 <xs:attribute name="oom_exit_code" type="xs:integer">
3196 <xs:annotation>
3197 <xs:documentation>Only used if ``detect_errors="exit_code"``, tells Galaxy the specified exit code indicates an out of memory error. Galaxy instances may be configured to retry such jobs on resources with more memory.</xs:documentation>
3198 </xs:annotation>
3199 </xs:attribute>
3200 <xs:attribute name="use_shared_home" type="xs:string">
3201 <xs:annotation>
3202 <xs:documentation>When running a job for this tool, do not isolate its ``$HOME`` directory within the job's directory - use either the ``shared_home_dir`` setting in Galaxy or the default ``$HOME`` specified in the job's default environment.</xs:documentation>
3203 </xs:annotation>
3204 </xs:attribute>
3205 <xs:attribute name="interpreter" type="xs:string" gxdocs:deprecated="true">
3206 <xs:annotation>
3207 <xs:documentation xml:lang="en"><![CDATA[*Deprecated*. This will prefix the command with the value of this attribute (e.g. ``python`` or ``perl``) and the tool directory, in order to run an executable file shipped with the tool. It is recommended to instead use ``<interpreter> '$__tool_directory__/<executable_name>'`` in the tag content. If this attribute is not specified, the tag should contain a Bash command calling executable(s) available in the ``$PATH``, as modified after loading the requirements.]]></xs:documentation>
3208 </xs:annotation>
3209 </xs:attribute>
3210 <xs:attribute name="strict" type="xs:boolean">
3211 <xs:annotation>
3212 <xs:documentation xml:lang="en">This boolean forces the ``#set -e`` directive on in shell scripts - so that in a multi-part command if any part fails the job exits with a non-zero exit code. This is enabled by default for tools with ``profile>=20.09`` and disabled on legacy tools.</xs:documentation>
3213 </xs:annotation>
3214 </xs:attribute>
3215 </xs:extension>
3216 </xs:simpleContent>
3217 </xs:complexType>
3218
3219 <xs:complexType name="Expression">
3220 <xs:annotation>
3221 <xs:documentation xml:lang="en"><![CDATA[
3222 For "Expression Tools" (tools with ``tool_type="expression``) this block describes the expression
3223 used to evaluate inputs and produce outputs. The semantics are going to vary based on the value
3224 of "type" specified for this expression block.
3225 ]]></xs:documentation>
3226 </xs:annotation>
3227 <xs:simpleContent>
3228 <xs:extension base="xs:string">
3229 <xs:attribute name="type" type="ExpressionType">
3230 <xs:annotation>
3231 <xs:documentation>Type of expression defined by this expression block. The only current valid option is ecma5.1 - which will evaluate the expression in a sandbox using node. The option still must be specified to allow a different default in the future.</xs:documentation>
3232 </xs:annotation>
3233 </xs:attribute>
3234 </xs:extension>
3235 </xs:simpleContent>
3236 </xs:complexType>
3237
3238 <xs:simpleType name="ExpressionType">
3239 <xs:annotation>
3240 <xs:documentation xml:lang="en"></xs:documentation>
3241 </xs:annotation>
3242 <xs:restriction base="xs:string">
3243 <xs:enumeration value="ecma5.1" />
3244 </xs:restriction>
3245 </xs:simpleType>
3246
3247 <xs:complexType name="ParamOption">
3248 <xs:annotation>
3249 <xs:documentation xml:lang="en"><![CDATA[
3250
3251 See [/tools/filters/sorter.xml](https://github.com/galaxyproject/galaxy/blob/master/tools/filters/sorter.xml)
3252 for typical examples of how to use this tag set. This directive is used to described
3253 static lists of options and is contained
3254 within the [param](#tool-inputs-param) directive when the ``type`` attribute
3255 value is ``select`` (i.e. ``<param type="select" ...>``).
3256
3257 ### Example
3258
3259 ```xml
3260 <param name="style" type="select" label="with flavor">
3261 <option value="num">Numerical sort</option>
3262 <option value="gennum">General numeric sort</option>
3263 <option value="alpha">Alphabetical sort</option>
3264 </param>
3265 ```
3266
3267 An option can also be annotated with ``selected="true"`` to specify a
3268 default option.
3269
3270 ```xml
3271 <param name="col" type="select" label="From">
3272 <option value="0" selected="true">Column 1 / Sequence name</option>
3273 <option value="1">Column 2 / Source</option>
3274 <option value="2">Column 3 / Feature</option>
3275 <option value="6">Column 7 / Strand</option>
3276 <option value="7">Column 8 / Frame</option>
3277 </param>
3278 ```
3279 ]]>
3280 </xs:documentation>
3281 </xs:annotation>
3282 <xs:simpleContent>
3283 <xs:extension base="xs:string">
3284 <xs:attribute name="value" type="xs:string">
3285 <xs:annotation>
3286 <xs:documentation xml:lang="en"><![CDATA[The value of the
3287 corresponding variable when used the Cheetah template. Also the value that
3288 should be used in building test cases and used when building requests for the
3289 API.]]></xs:documentation>
3290 </xs:annotation>
3291 </xs:attribute>
3292 <xs:attribute name="selected" type="PermissiveBoolean" default="false">
3293 <xs:annotation>
3294 <xs:documentation xml:lang="en">A boolean parameter indicating
3295 if the corresponding option is selected by default (the default is ``false``).
3296 </xs:documentation>
3297 </xs:annotation>
3298 </xs:attribute>
3299 </xs:extension>
3300 </xs:simpleContent>
3301 </xs:complexType>
3302
3303 <xs:complexType name="ParamConversion">
3304 <xs:annotation>
3305 <xs:documentation xml:lang="en"><![CDATA[
3306
3307 A contrived example of a tool that uses this is the test tool
3308 [explicit_conversion.xml](https://github.com/galaxyproject/galaxy/blob/dev/test/functional/tools/explicit_conversion.xml).
3309
3310 This directive is optionally contained within the ``<param>`` tag when the
3311 ``type`` attribute value is ``data`` and is used to dynamically generated a converted
3312 dataset for the contained input of the type specified using the ``type`` tag.
3313
3314 ]]>
3315 </xs:documentation>
3316 </xs:annotation>
3317 <xs:attribute name="name" type="xs:string" use="required">
3318 <xs:annotation>
3319 <xs:documentation xml:lang="en">Name of Cheetah variable to create for converted dataset.</xs:documentation>
3320 </xs:annotation>
3321 </xs:attribute>
3322 <xs:attribute name="type" type="xs:string" use="required">
3323 <xs:annotation>
3324 <xs:documentation xml:lang="en">The short extension describing the datatype to convert to - Galaxy must have a datatype converter from the parent input's type to this.</xs:documentation>
3325 </xs:annotation>
3326 </xs:attribute>
3327 </xs:complexType>
3328
3329
3330 <xs:complexType name="ParamOptions">
3331 <xs:annotation>
3332 <xs:documentation xml:lang="en"><![CDATA[
3333
3334 See [/tools/extract/liftOver_wrapper.xml](https://github.com/galaxyproject/galaxy/blob/master/tools/extract/liftOver_wrapper.xml)
3335 for an example of how to use this tag set. This tag set is optionally contained
3336 within the ``<param>`` tag when the ``type`` attribute value is ``select`` or
3337 ``data`` and used to dynamically generated lists of options. This tag set
3338 dynamically creates a list of options whose values can be
3339 obtained from a predefined file stored locally or a dataset selected from the
3340 current history.
3341
3342 There are at least five basic ways to use this tag - four of these correspond to
3343 a ``from_XXX`` attribute on the ``options`` directive and the other is to
3344 exclusively use ``filter``s to populate options.
3345
3346 * ``from_data_table`` - The options for the select list are dynamically obtained
3347 from a file specified in the Galaxy configuration file
3348 ``tool_data_table_conf.xml`` or from a Tool Shed installed data manager.
3349 * ``from_dataset`` - The options for the select list are dynamically obtained
3350 from input dataset selected for the tool from the current history.
3351 * ``from_file`` - The options for the select list are dynamically obtained from
3352 a file. This mechanis is discourage in favor of the more generic
3353 ``from_data_table``.
3354 * ``from_parameter`` - The options for the select list are dynamically obtained
3355 from a parameter.
3356 * Using ``filter``s - various filters can be used to populate options, see
3357 examples in the [filter](#tool-inputs-param-options-filter) documentation.
3358
3359 ### ``from_data_table``
3360
3361 See Galaxy's
3362 [data tables documentation](https://galaxyproject.org/admin/tools/data-tables)
3363 for information on setting up data tables.
3364
3365 Once a data table has been configured and populated, these can be easily
3366 leveraged via tools.
3367
3368 This ``conditional`` block in the
3369 [bowtie2](https://github.com/galaxyproject/tools-devteam/blob/master/tools/bowtie2/bowtie2_wrapper.xml)
3370 wrapper demonstrates using ``from_data_table`` options as an
3371 alternative to local reference data.
3372
3373 ```xml
3374 <conditional name="reference_genome">
3375 <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">
3376 <option value="indexed">Use a built-in genome index</option>
3377 <option value="history">Use a genome from the history and build index</option>
3378 </param>
3379 <when value="indexed">
3380 <param name="index" type="select" label="Select reference genome" help="If your genome of interest is not listed, contact the Galaxy team">
3381 <options from_data_table="bowtie2_indexes">
3382 <filter type="sort_by" column="2"/>
3383 <validator type="no_options" message="No indexes are available for the selected input dataset"/>
3384 </options>
3385 </param>
3386 </when>
3387 <when value="history">
3388 <param name="own_file" type="data" format="fasta" label="Select reference genome" />
3389 </when>
3390 </conditional>
3391 ```
3392
3393 A minimal example wouldn't even need the ``filter`` or ``validator`` above, but
3394 they are frequently nice features to add to your wrapper and can improve the user
3395 experience of a tool.
3396
3397 ### ``from_dataset``
3398
3399 The following example is taken from the Mothur tool
3400 [remove.lineage.xml](https://github.com/galaxyproject/tools-iuc/blob/master/tools/mothur/remove.lineage.xml)
3401 and demonstrates generating options from a dataset directly.
3402
3403 ```xml
3404 <param name="taxonomy" type="data" format="mothur.seq.taxonomy" label="taxonomy - Taxonomy" help="please make sure your file has no quotation marks in it"/>
3405 <param name="taxons" type="select" optional="true" multiple="true" label="Browse Taxons from Taxonomy">
3406 <options from_dataset="taxonomy">
3407 <column name="name" index="1"/>
3408 <column name="value" index="1"/>
3409 <filter type="unique_value" name="unique_taxon" column="1"/>
3410 <filter type="sort_by" name="sorted_taxon" column="1"/>
3411 </options>
3412 <sanitizer>
3413 <valid initial="default">
3414 <add preset="string.printable"/>
3415 <add value=";"/>
3416 <remove value="&quot;"/>
3417 <remove value="&apos;"/>
3418 </valid>
3419 </sanitizer>
3420 </param>
3421 ```
3422
3423 Filters can be used to generate options from dataset directly also as the
3424 example below demonstrates (many more examples are present in the
3425 [filter](#tool-inputs-param-options-filter) documentation).
3426
3427 ```xml
3428 <param name="species1" type="select" label="When Species" multiple="false">
3429 <options>
3430 <filter type="data_meta" ref="input1" key="species" />
3431 </options>
3432 </param>
3433 ```
3434
3435 ### ``from_file``
3436
3437 The following example is for Blast databases. In this example users maybe select
3438 a database that is pre-formatted and cached in Galaxy clusters. When a new
3439 dataset is available, admins must add the database to the local file named
3440 "blastdb.loc". All such databases in that file are included in the options of
3441 the select list. For a local instance, the file (e.g. ``blastdb.loc`` or
3442 ``alignseq.loc``) must be stored in the configured
3443 [tool_data_path](https://github.com/galaxyproject/galaxy/tree/master/tool-data)
3444 directory. In this example, the option names and values are taken from column 0
3445 of the file.
3446
3447 ```xml
3448 <param name="source_select" type="select" display="radio" label="Choose target database">
3449 <options from_file="blastdb.loc">
3450 <column name="name" index="0"/>
3451 <column name="value" index="0"/>
3452 </options>
3453 </param>
3454 ```
3455
3456 In general, ``from_file`` should be considered deprecated and ``from_data_table``
3457 should be prefered.
3458
3459 ### ``from_parameter``
3460
3461 This variant of the ``options`` directive is discouraged because it exposes
3462 internal Galaxy structures. See the older
3463 [bowtie](https://github.com/galaxyproject/tools-devteam/blob/master/tools/bowtie_wrappers/bowtie_wrapper.xml)
3464 wrappers for an example of these.
3465
3466 ### Other Ways to Dynamically Generate Options
3467
3468 Though deprecated and discouraged, [code](#tool-code) blocks can also be
3469 used to generate dynamic options.
3470
3471 ]]>
3472 </xs:documentation>
3473 </xs:annotation>
3474 <xs:sequence>
3475 <xs:group ref="OptionsElement" minOccurs="0" maxOccurs="unbounded"/>
3476 </xs:sequence>
3477 <xs:attribute name="from_dataset" type="xs:string">
3478 <xs:annotation>
3479 <xs:documentation xml:lang="en">Documentation for from_dataset</xs:documentation>
3480 </xs:annotation>
3481 </xs:attribute>
3482 <xs:attribute name="from_file" type="xs:string">
3483 <xs:annotation>
3484 <xs:documentation xml:lang="en">Documentation for from_file</xs:documentation>
3485 </xs:annotation>
3486 </xs:attribute>
3487 <xs:attribute name="from_data_table" type="xs:string">
3488 <xs:annotation>
3489 <xs:documentation xml:lang="en">Documentation for from_data_table</xs:documentation>
3490 </xs:annotation>
3491 </xs:attribute>
3492 <xs:attribute name="from_parameter" type="xs:string">
3493 <xs:annotation>
3494 <xs:documentation xml:lang="en">Documentation for from_parameter</xs:documentation>
3495 </xs:annotation>
3496 </xs:attribute>
3497 <xs:attribute name="options_filter_attribute" type="xs:string">
3498 <xs:annotation>
3499 <xs:documentation xml:lang="en">Documentation for options_filter_attribute</xs:documentation>
3500 </xs:annotation>
3501 </xs:attribute>
3502 <xs:attribute name="transform_lines" type="xs:string">
3503 <xs:annotation>
3504 <xs:documentation xml:lang="en">Documentation for transform_lines</xs:documentation>
3505 </xs:annotation>
3506 </xs:attribute>
3507 <xs:attribute name="startswith" type="xs:string">
3508 <xs:annotation>
3509 <xs:documentation xml:lang="en">Documentation for startswith</xs:documentation>
3510 </xs:annotation>
3511 </xs:attribute>
3512 </xs:complexType>
3513 <xs:group name="OptionsElement">
3514 <xs:choice>
3515 <xs:element name="filter" type="Filter" minOccurs="0" maxOccurs="unbounded"/>
3516 <xs:element name="column" type="Column" minOccurs="0" maxOccurs="unbounded"/>
3517 <xs:element name="validator" type="Validator" minOccurs="0" maxOccurs="1"/>
3518 <xs:element name="file" type="xs:string" minOccurs="0" maxOccurs="unbounded">
3519 <xs:annotation>
3520 <xs:documentation xml:lang="en">Documentation for file</xs:documentation>
3521 </xs:annotation>
3522 </xs:element>
3523 </xs:choice>
3524 </xs:group>
3525 <xs:complexType name="Column">
3526 <xs:annotation>
3527 <xs:documentation xml:lang="en"><![CDATA[Optionally contained within an
3528 ``<options>`` tag set - specifies columns used in building select options from a
3529 file stored locally (i.e. index or tool data) or a dataset in the
3530 current history.
3531
3532 Any number of columns may be described, but at least one must be given the name
3533 ``value`` and it will serve as the value of this parameter in the Cheetah
3534 template and elsewhwere (e.g. in API for instance).
3535
3536 If a column named ``name`` is defined, this too has special meaning and it will
3537 be the value the tool form user sees for each option. If no ``name`` column
3538 appears, ``value`` will serve as the name.
3539
3540 ### Examples
3541
3542 The following fragment shows options from the dataset in the current history
3543 that has been selected as the value of the parameter named ``input1``.
3544
3545 ```xml
3546 <options from_dataset="input1">
3547 <column name="name" index="0"/>
3548 <column name="value" index="0"/>
3549 </options>
3550 ```
3551
3552 The [interval2maf](https://github.com/galaxyproject/galaxy/blob/dev/tools/maf/interval2maf.xml)
3553 tool makes use of this tag with files from a history, and the
3554 [star_fusion](https://github.com/galaxyproject/tools-iuc/blob/master/tools/star_fusion/star_fusion.xml)
3555 tool makes use of this to reference a data table.
3556 ]]></xs:documentation>
3557 </xs:annotation>
3558 <xs:attribute name="name" type="xs:string" use="required">
3559 <xs:annotation>
3560 <xs:documentation xml:lang="en">Name given to the column with index
3561 ``index``, the names ``name`` and ``value`` have special meaning as described
3562 above.</xs:documentation>
3563 </xs:annotation>
3564 </xs:attribute>
3565 <xs:attribute name="index" type="xs:decimal" use="required">
3566 <xs:annotation>
3567 <xs:documentation xml:lang="en">0-based index of the column in the
3568 target file.</xs:documentation>
3569 </xs:annotation>
3570 </xs:attribute>
3571 </xs:complexType>
3572 <xs:complexType name="Validator">
3573 <xs:annotation>
3574
3575 <xs:documentation xml:lang="en"><![CDATA[
3576
3577 This tag set is contained within the ``<param>`` tag set - it applies a
3578 validator to the containing parameter. Tool submission will fail if a
3579 single validator fails. See the
3580 [annotation_profiler](https://github.com/galaxyproject/tools-devteam/blob/master/tools/annotation_profiler/annotation_profiler.xml)
3581 tool for an example of how to use this tag set.
3582
3583 Note that validators for parameters with ``optional="true"`` are not
3584 executed if no value is given.
3585
3586 ### Generic validators
3587
3588 - ``expression``: Check if a one line python expression given expression
3589 evaluates to True. The expression is given is the content of the validator tag.
3590
3591 ### Validators for ``data`` and ``data_collection`` parameters
3592
3593 In case of ``data_collection`` parameters and
3594 ``data`` parameters with ``multiple="true"`` these validators are executed
3595 separately for each of the contained data sets. Note that, for ``data``
3596 parameters a ``metadata`` validator is added automatically.
3597
3598 - ``metadata``: Check for missing metadata.
3599 - ``unspecified_build``: Check of a build is defined.
3600 - ``dataset_ok_validator``: Check if the data set is in state OK.
3601 - ``dataset_metadata_in_range``: Check if a numeric metadata value is within
3602 a given range.
3603 - ``dataset_metadata_in_file``: Check if a metadata value is contained in a
3604 specific column of another data set.
3605 - ``dataset_metadata_in_data_table`` (``dataset_metadata_not_in_data_table``):
3606 Check if a metadata value is contained in a column of a data table.
3607
3608 ### Validators for textual inputs (``text``, ``select``, ...)
3609
3610 ``regex``: Check if a regular expression **matches** the value, i.e. appears
3611 at the beginning of the value. To enforce a match of the complete value use
3612 ``$`` at the end of the expression. The expression is given is the content
3613 of the validator tag. Note that for ``selects`` each option is checked
3614 separately.
3615
3616 For selects (in particular with dynamically defined options) the following
3617 validator is useful:
3618
3619 ``no_options``: Check if options are available for a ``select`` parameter.
3620 Useful for parameters with dynamically defined options.
3621
3622 For ``text`` inputs the following validators are useful:
3623
3624 ``length``: Check if the length of the value is within a range.
3625 ``empty_field``: Check if the sting is not empty
3626 ``value_in_data_table`` (``value_not_in_data_table``): Check if the value is
3627 contained in a column of a given data table.
3628
3629 ### Validators for numeric inputs (``integer``, ``float``)
3630
3631 ``in_range``: Check if the value is in a given range.
3632
3633 ### Examples
3634
3635 The following demonstrates a simple validator ``unspecified_build`` ensuring
3636 that a dbkey is present on the selected dataset. This example is taken from the
3637 [extract_genomic_dna](https://github.com/galaxyproject/tools-iuc/blob/master/tools/extract_genomic_dna/extract_genomic_dna.xml#L42)
3638 tool.
3639
3640 ```xml
3641 <param name="input" type="data" format="gff,interval" label="Fetch sequences for intervals in">
3642 <validator type="unspecified_build" />
3643 </param>
3644 ```
3645
3646 Along the same line, the following example taken from
3647 [samtools_mpileup](https://github.com/galaxyproject/tools-devteam/blob/master/tool_collections/samtools/samtools_mpileup/samtools_mpileup.xml)
3648 ensures that a dbkey is present and that FASTA indices in the ``fasta_indexes``
3649 tool data table are present.
3650
3651 ```xml
3652 <param format="bam" label="BAM file(s)" name="input_bam" type="data" min="1" multiple="true">
3653 <validator type="unspecified_build" />
3654 <validator type="dataset_metadata_in_data_table" metadata_name="dbkey" table_name="fasta_indexes" metadata_column="1"
3655 message="Sequences are not currently available for the specified build." />
3656 </param>
3657 ```
3658
3659 In this older, somewhat deprecated example - a genome build of the dataset must
3660 be stored in Galaxy clusters and the name of the genome (``dbkey``) must be one
3661 of the values in the first column of file ``alignseq.loc`` - that could be
3662 expressed with the validator. In general, ``dataset_metadata_in_file`` should be
3663 considered deprecated in favor of
3664
3665 ```xml
3666 <validator type="dataset_metadata_in_data_table"
3667 metadata_name="dbkey"
3668 metadata_column="1"
3669 message="Sequences are not currently available for the specified build." />
3670 ```
3671
3672 A very common validator is simply ensure a Python expression is valid for a
3673 specified value. In the following example - paths/names that downstream tools
3674 use in filenames may not contain ``..``.
3675
3676 ```xml
3677 <validator type="expression" message="No two dots (..) allowed">'..' not in value</validator>
3678 ```
3679 ]]></xs:documentation>
3680 </xs:annotation>
3681 <xs:simpleContent>
3682 <xs:extension base="xs:string">
3683 <xs:attribute name="type" type="ValidatorType" use="required">
3684 <xs:annotation>
3685 <xs:documentation xml:lang="en"><![CDATA[The list of supported
3686 validators is in the ``validator_types`` dictionary in
3687 [/lib/galaxy/tools/parameters/validation.py](https://github.com/galaxyproject/galaxy/blob/dev/lib/galaxy/tools/parameters/validation.py).
3688 Valid values include: ``expression``, ``regex``, ``in_range``, ``length``,
3689 ``metadata``, ``unspecified_build``, ``no_options``, ``empty_field``,
3690 ``dataset_metadata_in_file``,
3691 ``dataset_metadata_in_data_table``, ``dataset_metadata_not_in_data_table``,
3692 ``value_in_data_table``, ``value_not_in_data_table``,
3693 ``dataset_ok_validator``, ``dataset_metadata_in_range``]]></xs:documentation>
3694 </xs:annotation>
3695 </xs:attribute>
3696 <xs:attribute name="message" type="xs:string">
3697 <xs:annotation>
3698 <xs:documentation xml:lang="en">
3699 The error message displayed on the tool form if validation fails.</xs:documentation>
3700 </xs:annotation>
3701 </xs:attribute>
3702 <xs:attribute name="check" type="xs:string">
3703 <xs:annotation>
3704 <xs:documentation xml:lang="en">Comma-seperated list of metadata
3705 fields to check for if type is ``metadata``. If not specified, all non-optional
3706 metadata fields will be checked unless they appear in the list of fields
3707 specified by the ``skip`` attribute.</xs:documentation>
3708 </xs:annotation>
3709 </xs:attribute>
3710 <xs:attribute name="table_name" type="xs:string">
3711 <xs:annotation>
3712 <xs:documentation xml:lang="en">Tool data table name to check against
3713 if ``type`` is ``dataset_metadata_in_tool_data``, ``dataset_metadata_not_in_tool_data``, ``value_in_tool_data``, or ``value_not_in_tool_data``. See the documentation for
3714 [tool data tables](https://galaxyproject.org/admin/tools/data-tables)
3715 and [data managers](https://galaxyproject.org/admin/tools/data-managers/) for
3716 more information.</xs:documentation>
3717 </xs:annotation>
3718 </xs:attribute>
3719 <xs:attribute name="filename" type="xs:string">
3720 <xs:annotation>
3721 <xs:documentation xml:lang="en">Tool data filename to check against
3722 if ``type`` is ``dataset_metadata_in_file``. File should be present Galaxy's
3723 ``tool-data`` directory.</xs:documentation>
3724 </xs:annotation>
3725 </xs:attribute>
3726 <xs:attribute name="metadata_name" type="xs:string">
3727 <xs:annotation>
3728 <xs:documentation xml:lang="en">Target metadata attribute name for
3729 ``dataset_metadata_in_data_table``, ``dataset_metadata_not_in_data_table`` and ``dataset_metadata_in_file`` options.</xs:documentation>
3730 </xs:annotation>
3731 </xs:attribute>
3732 <xs:attribute name="metadata_column" type="xs:string">
3733 <xs:annotation>
3734 <xs:documentation xml:lang="en">Target column for metadata attribute
3735 in ``dataset_metadata_in_data_table``, ``dataset_metadata_not_in_data_table``, ``value_in_data_table``, ``value__not_in_data_table``, and ``dataset_metadata_in_file`` options.
3736 This can be an integer index to the column or a column name.</xs:documentation>
3737 </xs:annotation>
3738 </xs:attribute>
3739 <xs:attribute name="line_startswith" type="xs:string">
3740 <xs:annotation>
3741 <xs:documentation xml:lang="en">Used to indicate lines in the file
3742 being used for validation start with a this attribute value.</xs:documentation>
3743 </xs:annotation>
3744 </xs:attribute>
3745 <xs:attribute name="min" type="xs:decimal">
3746 <xs:annotation>
3747 <xs:documentation xml:lang="en">When the ``type`` attribute value is
3748 ``in_range`` - this is the minimum number allowed.</xs:documentation>
3749 </xs:annotation>
3750 </xs:attribute>
3751 <xs:attribute name="max" type="xs:decimal">
3752 <xs:annotation>
3753 <xs:documentation xml:lang="en">When the ``type`` attribute value is
3754 ``in_range`` - this is the maximum number allowed.</xs:documentation>
3755 </xs:annotation>
3756 </xs:attribute>
3757 <xs:attribute name="exclude_min" type="xs:boolean" default="false">
3758 <xs:annotation>
3759 <xs:documentation xml:lang="en">When the ``type`` attribute value is
3760 ``in_range`` - this boolean indicates if the ``min`` value is allowed.</xs:documentation>
3761 </xs:annotation>
3762 </xs:attribute>
3763 <xs:attribute name="exclude_max" type="xs:boolean" default="false">
3764 <xs:annotation>
3765 <xs:documentation xml:lang="en">When the ``type`` attribute value is
3766 ``in_range`` - this boolean indicates if the ``max`` value is allowed.</xs:documentation>
3767 </xs:annotation>
3768 </xs:attribute>
3769 <xs:attribute name="split" type="xs:string">
3770 <xs:annotation>
3771 <xs:documentation xml:lang="en">If ``type`` is `dataset_metadata_in_file``,
3772 this attribute is the column separator to use for values in the specified file.
3773 This default is ``\t`` and due to a bug in older versions of Galaxy, should
3774 not be modified.</xs:documentation>
3775 </xs:annotation>
3776 </xs:attribute>
3777 <xs:attribute name="skip" type="xs:string">
3778 <xs:annotation>
3779 <xs:documentation xml:lang="en">Comma-seperated list of metadata
3780 fields to skip if type is ``metadata``. If not specified, all non-optional
3781 metadata fields will be checked unless ``check`` attribute is specified.</xs:documentation>
3782 </xs:annotation>
3783 </xs:attribute>
3784 </xs:extension>
3785 </xs:simpleContent>
3786 </xs:complexType>
3787 <xs:complexType name="Sanitizer">
3788 <xs:annotation>
3789 <xs:documentation xml:lang="en"><![CDATA[
3790
3791 See
3792 [/tools/filters/grep.xml](https://github.com/galaxyproject/galaxy/blob/dev/tools/filters/grep.xml)
3793 for a typical example of how to use this tag set. This tag set is used to
3794 replace the basic parameter sanitization with custom directives. This tag set is
3795 contained within the ``<param>`` tag set - it contains a set of ``<valid>`` and
3796 ``<mapping>`` tags.
3797
3798 ### Character presets
3799
3800 The following presets can be used when specifying the valid characters: the
3801 [constants](https://docs.python.org/3/library/string.html#string-constants) from the ``string`` Python3 module,
3802 plus ``default`` (equal to ``string.ascii_letters + string.digits + " -=_.()/+*^,:?!"``)
3803 and ``none`` (empty set).
3804 The ``string.letters``, ``string.lowercase`` and ``string.uppercase`` Python2
3805 constants are accepted for backward compatibility, but are aliased to the
3806 corresponding not locale-dependent constant (i.e. ``string.ascii_letters``,
3807 ``string.ascii_lowercase`` and ``string.ascii_uppercase`` respectively).
3808
3809 ### Examples
3810
3811 This example specifies to use the empty string as the invalid character (instead
3812 of the default ``X``, so invalid characters are effectively dropped instead of
3813 replaced with ``X``) and indicates that the only valid characters for this input
3814 are ASCII letters, digits, and ``_``.
3815
3816 ```xml
3817 <param name="mystring" type="text" label="Say something interesting">
3818 <sanitizer invalid_char="">
3819 <valid initial="string.ascii_letters,string.digits">
3820 <add value="_" />
3821 </valid>
3822 </sanitizer>
3823 </param>
3824 ```
3825
3826 This example allows many more valid characters and specifies that ``&`` will just
3827 be dropped from the input.
3828
3829 ```xml
3830 <sanitizer>
3831 <valid initial="string.printable">
3832 <remove value="&amp;"/>
3833 </valid>
3834 <mapping initial="none">
3835 <add source="&amp;" target=""/>
3836 </mapping>
3837 </sanitizer>
3838 ```
3839 ]]></xs:documentation>
3840 </xs:annotation>
3841 <xs:sequence>
3842 <xs:group ref="SanitizerElement" minOccurs="0" maxOccurs="unbounded"/>
3843 </xs:sequence>
3844 <xs:attribute name="sanitize" type="PermissiveBoolean" default="true">
3845 <xs:annotation>
3846 <xs:documentation xml:lang="en">This boolean parameter determines if the
3847 input is sanitized at all (the default is ``true``).</xs:documentation>
3848 </xs:annotation>
3849 </xs:attribute>
3850 <xs:attribute name="invalid_char" type="xs:string" default="X">
3851 <xs:annotation>
3852 <xs:documentation xml:lang="en">The attribute specifies the character
3853 used as a replacement for invalid characters (the default is ``X``).</xs:documentation>
3854 </xs:annotation>
3855 </xs:attribute>
3856 </xs:complexType>
3857 <xs:group name="SanitizerElement">
3858 <xs:choice>
3859 <xs:element name="valid" type="SanitizerValid"/>
3860 <xs:element name="mapping" type="SanitizerMapping"/>
3861 </xs:choice>
3862 </xs:group>
3863 <xs:complexType name="SanitizerValid">
3864 <xs:annotation>
3865 <xs:documentation xml:lang="en"><![CDATA[Contained within the
3866 ``<sanitizer>`` tag set, these are used to specify a list of allowed characters.
3867 Contains ``<add>`` and ``<remove>`` tags.]]></xs:documentation>
3868 </xs:annotation>
3869 <xs:sequence>
3870 <xs:group ref="SanitizerValidElement" minOccurs="0" maxOccurs="unbounded"/>
3871 </xs:sequence>
3872 <xs:attribute name="initial" type="xs:string">
3873 <xs:annotation>
3874 <xs:documentation xml:lang="en">This describes the initial characters to
3875 allow as valid, specified as a character preset (as defined above). The default
3876 is the ``default`` preset.</xs:documentation>
3877 </xs:annotation>
3878 </xs:attribute>
3879 </xs:complexType>
3880 <xs:complexType name="SanitizerValidAdd">
3881 <xs:annotation>
3882 <xs:documentation xml:lang="en">This directive is used to add individual
3883 characters or preset lists of characters. Character must not be allowed as a
3884 valid input for the mapping to occur.</xs:documentation>
3885 </xs:annotation>
3886 <xs:attribute name="preset" type="xs:string">
3887 <xs:annotation>
3888 <xs:documentation xml:lang="en">Add the characters contained in the specified character preset (as defined above) to the list of valid characters. The default
3889 is the ``none`` preset.</xs:documentation>
3890 </xs:annotation>
3891 </xs:attribute>
3892 <xs:attribute name="value" type="xs:string">
3893 <xs:annotation>
3894 <xs:documentation xml:lang="en">Add a character to the list of valid characters.</xs:documentation>
3895 </xs:annotation>
3896 </xs:attribute>
3897 </xs:complexType>
3898 <xs:complexType name="SanitizerValidRemove">
3899 <xs:annotation>
3900 <xs:documentation xml:lang="en">This directive is used to remove
3901 individual characters or preset lists of characters.
3902 Character must not be allowed as a valid input for the mapping to occur.</xs:documentation>
3903 </xs:annotation>
3904 <xs:attribute name="preset" type="xs:string">
3905 <xs:annotation>
3906 <xs:documentation xml:lang="en">Remove the characters contained in the specified character preset (as defined above) from the list of valid characters. The default
3907 is the ``none`` preset.</xs:documentation>
3908 </xs:annotation>
3909 </xs:attribute>
3910 <xs:attribute name="value" type="xs:string">
3911 <xs:annotation>
3912 <xs:documentation xml:lang="en">A character to remove from the list of valid characters.</xs:documentation>
3913 </xs:annotation>
3914 </xs:attribute>
3915 </xs:complexType>
3916 <xs:group name="SanitizerValidElement">
3917 <xs:choice>
3918 <xs:element name="add" type="SanitizerValidAdd"/>
3919 <xs:element name="remove" type="SanitizerValidRemove"/>
3920 </xs:choice>
3921 </xs:group>
3922 <xs:complexType name="SanitizerMapping">
3923 <xs:annotation>
3924 <xs:documentation xml:lang="en"><![CDATA[Contained within the ``<sanitizer>`` tag set. Used to specify a mapping of disallowed character to replacement string. Contains ``<add>`` and ``<remove>`` tags.]]></xs:documentation>
3925 </xs:annotation>
3926 <xs:sequence>
3927 <xs:group ref="SanitizerMappingElement" minOccurs="0" maxOccurs="unbounded"/>
3928 </xs:sequence>
3929 <xs:attribute name="initial" type="xs:string">
3930 <xs:annotation>
3931 <xs:documentation xml:lang="en">Initial character mapping (default is ``galaxy.util.mapped_chars``)</xs:documentation>
3932 </xs:annotation>
3933 </xs:attribute>
3934 </xs:complexType>
3935 <xs:complexType name="SanitizerMappingAdd">
3936 <xs:annotation>
3937 <xs:documentation xml:lang="en"><![CDATA[Use to add character mapping during sanitization. Character must not be allowed as a valid input for the mapping to occur.]]></xs:documentation>
3938 </xs:annotation>
3939 <xs:attribute name="source" type="xs:string">
3940 <xs:annotation>
3941 <xs:documentation xml:lang="en">Replace all occurrences of this character with the string of ``target``.</xs:documentation>
3942 </xs:annotation>
3943 </xs:attribute>
3944 <xs:attribute name="target" type="xs:string">
3945 <xs:annotation>
3946 <xs:documentation xml:lang="en">Replace all occurrences of ``source`` with this string</xs:documentation>
3947 </xs:annotation>
3948 </xs:attribute>
3949 </xs:complexType>
3950 <xs:complexType name="SanitizerMappingRemove">
3951 <xs:annotation>
3952 <xs:documentation xml:lang="en"><![CDATA[Use to remove character mapping during sanitization.]]></xs:documentation>
3953 </xs:annotation>
3954 <xs:attribute name="source" type="xs:string">
3955 <xs:annotation>
3956 <xs:documentation xml:lang="en">Character to remove from mapping.</xs:documentation>
3957 </xs:annotation>
3958 </xs:attribute>
3959 </xs:complexType>
3960 <xs:group name="SanitizerMappingElement">
3961 <xs:choice>
3962 <xs:element name="add" type="SanitizerMappingAdd" minOccurs="0" maxOccurs="unbounded"/>
3963 <xs:element name="remove" type="SanitizerMappingRemove" minOccurs="0" maxOccurs="unbounded"/>
3964 </xs:choice>
3965 </xs:group>
3966 <xs:complexType name="Filter">
3967 <xs:annotation>
3968 <xs:documentation xml:lang="en"><![CDATA[Optionally contained within an
3969 ``<options>`` tag set - modify (e.g. remove, add, sort, ...) the list of values obtained from a locally stored file (e.g.
3970 a tool data table) or a dataset in the current history.
3971
3972 Currently the following filters are defined:
3973
3974 * ``static_value`` filter options for which the entry in a given ``column`` of the referenced file based on equality to the ``value`` attribute of the filter.
3975 * ``regexp`` similar to the ``static_value`` filter, but checks if the regular expression given by ``value`` matches the entry.
3976 * ``param_value`` filter options for which the entry in a given ``column`` of the referenced file based on properties of another input parameter specified by ``ref``. 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.
3977 * ``data_meta`` populate or filter options based on the metadata of another input parameter specified by ``ref``. If a ``column`` is given options are filtered for which the entry in this column ``column`` is equal to metadata of the input parameter specified by ``ref``.
3978 If no ``column`` is given the metadata value of the referenced input is added to the options list (in this case the corresponding ``options`` tag must not have the ``from_data_table`` or ``from_dataset`` attributes).
3979 In both cases the desired metadata is selected by ``key``.
3980
3981 The ``static_value`` and ``regexp`` filters can be inverted by setting ``keep`` to true.
3982
3983 * ``add_value``: add an option with a given ``name`` and ``value`` to the options. By default the new option is appended, with ``index`` the insertion position can be specified.
3984 * ``remove_value``: remove a value from the options. Either specified explicitly with ``value``, the value of another input specifified with ``ref``, or the metatdata ``key`` of another input ``meta_ref``.
3985 * ``unique_value``: remove options that have duplicate entries in the given ``column``.
3986 * ``sort_by``: sort options by the entries of a given ``column``.
3987 * ``multiple_splitter``: split the entries of the specified ``column``(s) in the referenced file using a ``separator``. Thereby the number of columns is increased.
3988
3989 ### Examples
3990
3991 The following example from Mothur's
3992 [remove.groups.xml](https://github.com/galaxyproject/tools-iuc/blob/master/tools/mothur/remove.groups.xml)
3993 tool demonstrates filtering a select list based on the metadata of an input to
3994 to the tool.
3995
3996 ```xml
3997 <param name="group_in" type="data" format="mothur.groups,mothur.count_table" label="group or count table - Groups"/>
3998 <param name="groups" type="select" label="groups - Pick groups to remove" multiple="true" optional="false">
3999 <options>
4000 <filter type="data_meta" ref="group_in" key="groups"/>
4001 </options>
4002 </param>
4003 ```
4004
4005 This more advanced example, taken from Mothur's
4006 [remove.lineage.xml](https://github.com/galaxyproject/tools-iuc/blob/master/tools/mothur/remove.lineage.xml)
4007 tool demonstrates using filters to sort a list and remove duplicate entries.
4008
4009 ```xml
4010 <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"/>
4011 <param name="taxons" type="select" optional="true" multiple="true" label="Browse Taxons from Taxonomy">
4012 <options from_dataset="taxonomy">
4013 <column name="name" index="2"/>
4014 <column name="value" index="2"/>
4015 <filter type="unique_value" name="unique_taxon" column="2"/>
4016 <filter type="sort_by" name="sorted_taxon" column="2"/>
4017 </options>
4018 <sanitizer>
4019 <valid initial="default">
4020 <add preset="string.printable"/>
4021 <add value=";"/>
4022 <remove value="&quot;"/>
4023 <remove value="&apos;"/>
4024 </valid>
4025 </sanitizer>
4026 </param>
4027 ```
4028
4029 This example taken from the
4030 [hisat2](https://github.com/galaxyproject/tools-iuc/blob/master/tools/hisat2/hisat2.xml)
4031 tool demonstrates filtering values from a tool data table.
4032
4033 ```xml
4034 <param help="If your genome of interest is not listed, contact the Galaxy team" label="Select a reference genome" name="index" type="select">
4035 <options from_data_table="hisat2_indexes">
4036 <filter column="2" type="sort_by" />
4037 <validator message="No genomes are available for the selected input dataset" type="no_options" />
4038 </options>
4039 </param>
4040 ```
4041
4042 The
4043 [gemini_load.xml](https://github.com/galaxyproject/tools-iuc/blob/master/tools/gemini/gemini_load.xml)
4044 tool demonstrates adding values to an option list using ``filter``s.
4045
4046 ```xml
4047 <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.">
4048 <options>
4049 <filter type="add_value" value="hg19" />
4050 <filter type="add_value" value="Homo_sapiens_nuHg19_mtrCRS" />
4051 <filter type="add_value" value="hg_g1k_v37" />
4052 </options>
4053 </param>
4054 ```
4055
4056 While this fragment from [maf_to_interval.xml](https://github.com/galaxyproject/galaxy/blob/dev/tools/maf/maf_to_interval.xml) demonstrates removing items.
4057
4058 ```xml
4059 <param name="species" type="select" label="Select additional species"
4060 display="checkboxes" multiple="true"
4061 help="The species matching the dbkey of the alignment is always included.
4062 A separate history item will be created for each species.">
4063 <options>
4064 <filter type="data_meta" ref="input1" key="species" />
4065 <filter type="remove_value" meta_ref="input1" key="dbkey" />
4066 </options>
4067 </param>
4068 ```
4069
4070 This example taken from
4071 [snpSift_dbnsfp.xml](https://github.com/galaxyproject/tools-iuc/blob/master/tool_collections/snpsift/snpsift_dbnsfp/snpSift_dbnsfp.xml)
4072 demonstrates splitting up strings into multiple values.
4073
4074 ```xml
4075 <param name="annotations" type="select" multiple="true" display="checkboxes" label="Annotate with">
4076 <options from_data_table="snpsift_dbnsfps">
4077 <column name="name" index="4"/>
4078 <column name="value" index="4"/>
4079 <filter type="param_value" ref="dbnsfp" column="3" />
4080 <filter type="multiple_splitter" column="4" separator=","/>
4081 </options>
4082 </param>
4083 ```
4084 ]]></xs:documentation>
4085 </xs:annotation>
4086 <xs:attribute name="type" type="FilterType" use="required">
4087 <xs:annotation>
4088 <xs:documentation xml:lang="en"><![CDATA[
4089 Currently the filters in the ``filter_types`` dictionary in the module
4090 [/lib/galaxy/tools/parameters/dynamic_options.py](https://github.com/galaxyproject/galaxy/blob/master/lib/galaxy/tools/parameters/dynamic_options.py) are defined.
4091
4092 Deprecated filter types:
4093
4094 * ``attribute_value_splitter``
4095 ]]></xs:documentation>
4096 </xs:annotation>
4097 </xs:attribute>
4098 <xs:attribute name="column" type="xs:string">
4099 <xs:annotation>
4100 <xs:documentation xml:lang="en">Column targeted by this filter given as column index or a column name. Invalid if ``type`` is ``add_value`` or ``remove_value``.
4101 </xs:documentation>
4102 </xs:annotation>
4103 </xs:attribute>
4104 <xs:attribute name="name" type="xs:string">
4105 <xs:annotation>
4106 <xs:documentation xml:lang="en">Name displayed for value to add (only
4107 used with ``type`` of ``add_value``).</xs:documentation>
4108 </xs:annotation>
4109 </xs:attribute>
4110 <xs:attribute name="ref" type="xs:string">
4111 <xs:annotation>
4112 <xs:documentation xml:lang="en">The attribute name of the reference file
4113 (tool data) or input dataset. Only used when ``type`` is
4114 ``data_meta`` (required), ``param_value`` (required), or ``remove_value``
4115 (optional).</xs:documentation>
4116 </xs:annotation>
4117 </xs:attribute>
4118 <xs:attribute name="key" type="xs:string">
4119 <xs:annotation>
4120 <xs:documentation xml:lang="en">When ``type`` is ``data_meta``, ``param_value``,
4121 or ``remove_value`` - this is the name of the metadata key to filter by.</xs:documentation>
4122 </xs:annotation>
4123 </xs:attribute>
4124 <xs:attribute name="multiple" type="PermissiveBoolean" default="false">
4125 <xs:annotation>
4126 <xs:documentation xml:lang="en"><![CDATA[For types ``data_meta`` and
4127 ``remove_value``, whether option values are multiple. Columns will be split by
4128 separator. Defaults to ``false``.]]></xs:documentation>
4129 </xs:annotation>
4130 </xs:attribute>
4131 <xs:attribute name="separator" type="xs:string">
4132 <xs:annotation>
4133 <xs:documentation xml:lang="en"><![CDATA[When ``type`` is ``data_meta``,
4134 ``multiple_splitter``, or ``remove_value`` - this is used to split one value
4135 into multiple parts. When ``type`` is ``data_meta`` or ``remove_value`` this is
4136 only used if ``multiple`` is set to ``true``.]]></xs:documentation>
4137 </xs:annotation>
4138 </xs:attribute>
4139 <xs:attribute name="keep" type="PermissiveBoolean" default="true">
4140 <xs:annotation>
4141 <xs:documentation xml:lang="en">If ``true``, keep columns matching the
4142 value, if ``false`` discard columns matching the value. Used when ``type`` is
4143 either ``static_value``, ``regexp`` or ``param_value``.</xs:documentation>
4144 </xs:annotation>
4145 </xs:attribute>
4146 <xs:attribute name="value" type="xs:string">
4147 <xs:annotation>
4148 <xs:documentation xml:lang="en">Target value of the operations - has
4149 slightly different meanings depending on ``type``. For instance when ``type`` is
4150 ``add_value`` it is the value to add to the list and when ``type`` is
4151 ``static_value`` or ``regexp`` it is the value compared against.</xs:documentation>
4152 </xs:annotation>
4153 </xs:attribute>
4154 <xs:attribute name="ref_attribute" type="xs:string">
4155 <xs:annotation>
4156 <xs:documentation xml:lang="en">Only used when ``type`` is
4157 ``param_value``. Period (``.``) separated attribute chain of input (``ref``)
4158 attributes to use as value for filter.</xs:documentation>
4159 </xs:annotation>
4160 </xs:attribute>
4161 <xs:attribute name="index" type="xs:integer">
4162 <xs:annotation>
4163 <xs:documentation xml:lang="en">Used when ``type`` is ``add_value``, it
4164 is the index into the list to add the option to. If not set, the option will be
4165 added to the end of the list.</xs:documentation>
4166 </xs:annotation>
4167 </xs:attribute>
4168 <xs:attribute name="meta_ref" type="xs:string">
4169 <xs:annotation>
4170 <xs:documentation xml:lang="en">Only used when ``type`` is
4171 ``remove_value``. Dataset to look for the value of metadata ``key`` to remove
4172 from the list.</xs:documentation>
4173 </xs:annotation>
4174 </xs:attribute>
4175 </xs:complexType>
4176 <xs:complexType name="Outputs">
4177 <xs:annotation>
4178 <xs:documentation xml:lang="en"><![CDATA[
4179 Container tag set for the ``<data>`` and ``<collection>`` tag sets.
4180 The files and collections created by tools as a result of their execution are
4181 named by Galaxy. You specify the number and type of your output files using the
4182 contained ``<data>`` and ``<collection>`` tags. These may be passed to your tool
4183 executable through using line variables just like the parameters described in
4184 the ``<inputs>`` documentation.
4185 ]]></xs:documentation>
4186 </xs:annotation>
4187 <xs:sequence>
4188 <xs:group ref="OutputsElement" minOccurs="0" maxOccurs="unbounded"/>
4189 </xs:sequence>
4190 <xs:attribute name="provided_metadata_style" type="xs:string">
4191 <xs:annotation>
4192 <xs:documentation xml:lang="en"><![CDATA[
4193 Style used for tool provided metadata file (i.e.
4194 [galaxy.json](https://planemo.readthedocs.io/en/latest/writing_advanced.html#tool-provided-metadata))
4195 - this can be either "legacy" or "default". The default of tools with a profile
4196 of 17.09 or newer are "default", and "legacy" for older and tools and tools
4197 without a specified profile. A discussion of the differences between the styles
4198 can be found [here](https://github.com/galaxyproject/galaxy/pull/4437).
4199 ]]></xs:documentation>
4200 </xs:annotation>
4201 </xs:attribute>
4202 <xs:attribute name="provided_metadata_file" type="xs:string" default="galaxy.json">
4203 <xs:annotation>
4204 <xs:documentation xml:lang="en"><![CDATA[
4205 Path relative to tool's working directory to load tool provided metadata from.
4206 This metadata can describe dynamic datasets to load, dynamic collection
4207 contents, as well as simple metadata (e.g. name, dbkey, etc...) and
4208 datatype-specific metadata for declared outputs. More information can be found
4209 [here](https://planemo.readthedocs.io/en/latest/writing_advanced.html#tool-provided-metadata).
4210 The default is ``galaxy.json``.
4211 ]]></xs:documentation>
4212 </xs:annotation>
4213 </xs:attribute>
4214 </xs:complexType>
4215 <xs:group name="OutputsElement">
4216 <xs:choice>
4217 <xs:element name="output" type="Output" />
4218 <xs:element name="data" type="OutputData"/>
4219 <xs:element name="collection" type="OutputCollection" />
4220 </xs:choice>
4221 </xs:group>
4222 <xs:group name="OutputDataElement">
4223 <xs:choice>
4224 <xs:element name="change_format" type="ChangeFormat"/>
4225 <xs:element name="filter" type="OutputFilter" />
4226 <xs:element name="discover_datasets" type="OutputDiscoverDatasets" />
4227 <xs:element name="actions" type="Actions"/>
4228 </xs:choice>
4229 </xs:group>
4230
4231 <xs:attributeGroup name="OutputCommon">
4232 <xs:attribute name="format" type="xs:string">
4233 <xs:annotation>
4234 <xs:documentation xml:lang="en">The short name for the output datatype.
4235 The valid values for format can be found in
4236 [/config/datatypes_conf.xml.sample](https://github.com/galaxyproject/galaxy/blob/dev/config/datatypes_conf.xml.sample)
4237 (e.g. ``format="pdf"`` or ``format="fastqsanger"``). For collections this is the default format for all included
4238 elements. Note that the format specified here is ignored for discovered data sets.</xs:documentation>
4239 </xs:annotation>
4240 </xs:attribute>
4241 <xs:attribute name="format_source" type="xs:string">
4242 <xs:annotation>
4243 <xs:documentation xml:lang="en">This sets the data type of the output dataset(s) to be the same format as that of the specified tool input.</xs:documentation>
4244 </xs:annotation>
4245 </xs:attribute>
4246 <xs:attribute name="label" type="xs:string">
4247 <xs:annotation>
4248 <xs:documentation xml:lang="en"><![CDATA[
4249
4250 This will be the name of the history item for the output data set. The string
4251 can include structure like ``${<some param name>.<some attribute>}``, as
4252 discussed for command line parameters in the ``<command>`` tag set section
4253 above. The default label is ``${tool.name} on ${on_string}``.
4254
4255 ]]></xs:documentation>
4256 </xs:annotation>
4257 </xs:attribute>
4258 <xs:attribute name="name" type="xs:string" use="required">
4259 <xs:annotation>
4260 <xs:documentation xml:lang="en"><![CDATA[Name for this output. This
4261 ``name`` is used as the Cheetah variable containing the Galaxy assigned output
4262 path in ``command`` and ``configfile`` elements. The name should not contain
4263 pipes or periods (e.g. ``.``).]]></xs:documentation>
4264 </xs:annotation>
4265 </xs:attribute>
4266 </xs:attributeGroup>
4267
4268 <xs:attributeGroup name="OutputDataAttributes">
4269 <xs:attribute name="auto_format" type="PermissiveBoolean">
4270 <xs:annotation>
4271 <xs:documentation xml:lang="en"><![CDATA[
4272
4273 If ``true``, this output will sniffed and its format determined automatically by Galaxy.
4274
4275 ]]></xs:documentation>
4276 </xs:annotation>
4277 </xs:attribute>
4278 <xs:attribute name="default_identifier_source" type="xs:string">
4279 <xs:annotation>
4280 <xs:documentation xml:lang="en">Sets the source of element identifier to the specified input.
4281 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`` instead of ``input`` if ``input`` is in a conditional with ``name="cond"``).</xs:documentation>
4282 </xs:annotation>
4283 </xs:attribute>
4284 <xs:attribute name="metadata_source" type="xs:string">
4285 <xs:annotation>
4286 <xs:documentation xml:lang="en">This copies the metadata information
4287 from the tool's input dataset. This is particularly useful for interval data
4288 types where the order of the columns is not set.</xs:documentation>
4289 </xs:annotation>
4290 </xs:attribute>
4291 <xs:attribute name="from_work_dir" type="xs:string">
4292 <xs:annotation>
4293 <xs:documentation xml:lang="en">Relative path to a file produced by the
4294 tool in its working directory. Output's contents are set to this file's
4295 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.</xs:documentation>
4296 </xs:annotation>
4297 </xs:attribute>
4298 <xs:attribute name="hidden" type="xs:boolean" default="false">
4299 <xs:annotation>
4300 <xs:documentation xml:lang="en">Boolean indicating whether to hide
4301 dataset in the history view. (Default is ``false``.)</xs:documentation>
4302 </xs:annotation>
4303 </xs:attribute>
4304 </xs:attributeGroup>
4305
4306 <xs:attributeGroup name="OutputCollectionAttributes">
4307 <xs:attribute name="structured_like" type="xs:string">
4308 <xs:annotation>
4309 <xs:documentation xml:lang="en">This is the name of input collection or
4310 dataset to derive "structure" of the output from (output element count and
4311 identifiers). For instance, if the referenced input has three ordered items with
4312 identifiers ``sample1``, ``sample2``, and ``sample3``. If this references input
4313 elements in conditionals, this value should be qualified (e.g. ``cond|input`` instead
4314 of ``input`` if ``input`` is in a conditional with ``name="cond"``).</xs:documentation>
4315 </xs:annotation>
4316 </xs:attribute>
4317 <xs:attribute name="inherit_format" type="xs:boolean">
4318 <xs:annotation>
4319 <xs:documentation xml:lang="en">If ``structured_like`` is set, inherit
4320 format of outputs from format of corresponding input.</xs:documentation>
4321 </xs:annotation>
4322 </xs:attribute>
4323 </xs:attributeGroup>
4324
4325 <xs:complexType name="OutputData">
4326 <xs:annotation>
4327 <xs:documentation xml:lang="en"><![CDATA[
4328
4329 This tag set is contained within the ``<outputs>`` tag set, and it defines the
4330 output data description for the files resulting from the tool's execution. The
4331 value of the attribute ``label`` can be acquired from input parameters or metadata
4332 in the same way that the command line parameters are (discussed in the
4333 ``<command>`` tag set section above).
4334
4335 ### Examples
4336
4337 The following will create a variable called ``$out_file1`` with data type
4338 ``pdf``.
4339
4340 ```xml
4341 <outputs>
4342 <data format="pdf" name="out_file1" />
4343 </outputs>
4344 ```
4345
4346 The valid values for format can be found in
4347 [/config/datatypes_conf.xml.sample](https://github.com/galaxyproject/galaxy/blob/dev/config/datatypes_conf.xml.sample).
4348
4349 The following will create a dataset in the history panel whose data type is the
4350 same as that of the input dataset selected (and named ``input1``) for the tool.
4351
4352 ```xml
4353 <outputs>
4354 <data format_source="input1" name="out_file1" metadata_source="input1"/>
4355 </outputs>
4356 ```
4357
4358 The following will create datasets in the history panel, setting the output data
4359 type to be the same as that of an input dataset named by the ``format_source``
4360 attribute. Note that a conditional name is not included, so 2 separate
4361 conditional blocks should not contain parameters with the same name.
4362
4363 ```xml
4364 <inputs>
4365 <!-- fasta may be an aligned fasta that subclasses Fasta -->
4366 <param name="fasta" type="data" format="fasta" label="fasta - Sequences"/>
4367 <conditional name="qual">
4368 <param name="add" type="select" label="Trim based on a quality file?" help="">
4369 <option value="no">no</option>
4370 <option value="yes">yes</option>
4371 </param>
4372 <when value="no"/>
4373 <when value="yes">
4374 <!-- qual454, qualsolid, qualillumina -->
4375 <param name="qfile" type="data" format="qual" label="qfile - a quality file"/>
4376 </when>
4377 </conditional>
4378 </inputs>
4379 <outputs>
4380 <data format_source="fasta" name="trim_fasta"
4381 label="${tool.name} on ${on_string}: trim.fasta"/>
4382 <data format_source="qfile" name="trim_qual"
4383 label="${tool.name} on ${on_string}: trim.qual">
4384 <filter>qual['add'] == 'yes'</filter>
4385 </data>
4386 </outputs>
4387 ```
4388
4389 Assume that the tool includes an input parameter named ``database`` which is a
4390 select list (as shown below). Also assume that the user selects the first option
4391 in the ``$database`` select list. Then the following will ensure that the tool
4392 produces a tabular data set whose associated history item has the label ``Blat
4393 on Human (hg18)``.
4394
4395 ```xml
4396 <inputs>
4397 <param format="tabular" name="input" type="data" label="Input stuff"/>
4398 <param type="select" name="database" label="Database">
4399 <option value="hg18">Human (hg18)</option>
4400 <option value="dm3">Fly (dm3)</option>
4401 </param>
4402 </inputs>
4403 <outputs>
4404 <data format="input" name="output" label="Blat on ${database.value_label}" />
4405 </outputs>
4406 ```
4407
4408 ]]></xs:documentation>
4409 </xs:annotation>
4410 <xs:sequence>
4411 <xs:group ref="OutputDataElement" minOccurs="0" maxOccurs="unbounded" />
4412 </xs:sequence>
4413 <!-- TODO: add a unique constraint for action. -->
4414 <xs:attributeGroup ref="OutputCommon"/>
4415 <xs:attributeGroup ref="OutputDataAttributes"/>
4416 </xs:complexType>
4417
4418 <xs:group name="OutputCollectionElement">
4419 <xs:choice>
4420 <xs:element name="data" type="OutputData" />
4421 <xs:element name="discover_datasets" type="OutputCollectionDiscoverDatasets" />
4422 <xs:element name="filter" type="OutputFilter" />
4423 </xs:choice>
4424 </xs:group>
4425
4426 <xs:complexType name="OutputCollection">
4427 <xs:annotation>
4428 <xs:documentation xml:lang="en"><![CDATA[
4429
4430 This tag set is contained within the ``<outputs>`` tag set, and it defines the
4431 output dataset collection description resulting from the tool's execution. The
4432 value of the attribute ``label`` can be acquired from input parameters or
4433 metadata in the same way that the command line parameters are (discussed in the
4434 [command](#tool-command) directive).
4435
4436 Creating collections in tools is covered in-depth in
4437 [Planemo's documentation](https://planemo.readthedocs.io/en/latest/writing_advanced.html#creating-collections).
4438
4439 ]]></xs:documentation>
4440 </xs:annotation>
4441 <xs:sequence>
4442 <xs:group ref="OutputCollectionElement" minOccurs="0" maxOccurs="unbounded" />
4443 </xs:sequence>
4444 <xs:attributeGroup ref="OutputCommon"/>
4445 <xs:attributeGroup ref="OutputCollectionAttributes"/>
4446 <xs:attribute name="type" type="xs:string">
4447 <xs:annotation>
4448 <xs:documentation xml:lang="en">Collection type for output (e.g. ``paired``, ``list``, or ``list:list``).</xs:documentation>
4449 </xs:annotation>
4450 </xs:attribute>
4451 <xs:attribute name="type_source" type="xs:string">
4452 <xs:annotation>
4453 <xs:documentation xml:lang="en">This is the name of input collection to
4454 derive collection's type (e.g. ``collection_type``) from.</xs:documentation>
4455 </xs:annotation>
4456 </xs:attribute>
4457 </xs:complexType>
4458
4459 <xs:complexType name="Output">
4460 <xs:annotation>
4461 <xs:documentation xml:lang="en"><![CDATA[
4462
4463 This tag describes an output to the tool.
4464 ]]></xs:documentation>
4465 </xs:annotation>
4466 <xs:sequence>
4467 <xs:group ref="OutputDataElement" minOccurs="0" maxOccurs="unbounded" />
4468 <xs:group ref="OutputCollectionElement" minOccurs="0" maxOccurs="unbounded" />
4469 </xs:sequence>
4470 <xs:attributeGroup ref="OutputCommon"/>
4471 <xs:attributeGroup ref="OutputCollectionAttributes"/>
4472 <xs:attribute name="type" type="xs:string">
4473 <xs:annotation>
4474 <xs:documentation xml:lang="en">Output type. This could be older more established Galaxy types (e.g. data and collection) - in which case the semantics of this largely reflect the corresponding ``data`` and ``collection`` tags. This could also be newer non-data types such as ``integer`` or ``boolean``.</xs:documentation>
4475 </xs:annotation>
4476 </xs:attribute>
4477 <xs:attribute name="from" type="xs:string">
4478 <xs:annotation>
4479 <xs:documentation xml:lang="en">In expression tools, use this to specify a dictionary value to populate this output from. The semantics may change for other expression types in the future.</xs:documentation>
4480 </xs:annotation>
4481 </xs:attribute>
4482 <xs:attribute name="collection_type" type="xs:string">
4483 <xs:annotation>
4484 <xs:documentation xml:lang="en">Collection type for output (e.g. ``paired``, ``list``, or ``list:list``).</xs:documentation>
4485 </xs:annotation>
4486 </xs:attribute>
4487 <xs:attribute name="collection_type_source" type="xs:string">
4488 <xs:annotation>
4489 <xs:documentation xml:lang="en">This is the name of input collection to
4490 derive collection's type (e.g. ``collection_type``) from.</xs:documentation>
4491 </xs:annotation>
4492 </xs:attribute>
4493
4494 </xs:complexType>
4495 <xs:complexType name="OutputFilter">
4496 <xs:annotation>
4497 <xs:documentation xml:lang="en"><![CDATA[
4498 The ``<data>`` tag can contain a ``<filter>`` tag which includes a Python code
4499 block to be executed to test whether to include this output in the outputs the
4500 tool ultimately creates. If the code, when executed, returns ``True``,
4501 the output dataset is retained. In these code blocks the tool parameters appear
4502 as Python variables and are thus referred to without the $ used for the Cheetah
4503 template (used in the ``<command>`` tag). Variables that are part of
4504 conditionals are accessed using a dictionary named after the conditional. Boolean
4505 parameters appear as booleans, not the value of their ``truevalue`` and
4506 ``falsevalue`` attributes. In the example below, ``options["selection_mode"]`` would
4507 appear as ``$options.selection_mode`` in Cheetah. Similarly ``options["vcf_output"]``
4508 would appear as ``$options.vcf_output`` having the values ``'--vcf'`` when true and
4509 ``''`` when false in Cheetah.
4510 Note that also parameters in sections are accessed via a dictionary.
4511
4512 ### Example
4513
4514 ```xml
4515 <inputs>
4516 <param type="data" format="fasta" name="reference_genome" label="Reference genome" />
4517 <param type="data" format="bam" name="input_bam" label="Aligned reads" />
4518 <conditional name="options">
4519 <param label="Use advanced options" name="selection_mode" type="select">
4520 <option selected="true" value="defaults">Use default options</option>
4521 <option value="advanced">Use advanced options</option>
4522 </param>
4523 <when value="defaults" />
4524 <when value="advanced">
4525 <param name="vcf_output" type="boolean" checked="false" label="VCF output"
4526 truevalue="--vcf" falsevalue="" />
4527 </when>
4528 </conditional>
4529 </inputs>
4530 <outputs>
4531 <data format="txt" label="Alignment report on ${on_string}" name="output_txt" />
4532 <data format="vcf" label="Variant summary on ${on_string}" name="output_vcf">
4533 <filter>options['selection_mode'] == 'advanced' and options['vcf_output']</filter>
4534 </data>
4535 </outputs>
4536 ```
4537
4538 Note that variables that correspond to optional select parameters are `None` if nothing is selected.
4539 Therefore a filter for such a variable looks like the following example.
4540
4541 ### Example
4542
4543 ```xml
4544 <inputs>
4545 <param name="output_type" type="select" optional="true">
4546 <option value="save_phase">Phase Movie</option>
4547 <option value="save_period">Period Movie</option>
4548 </param>
4549 </inputs>
4550
4551 <outputs>
4552 <data name="phase_out" format="tiff">
4553 <filter>output_type and "save_phase" in output_type</filter>
4554 </data>
4555 <data name="period_out" format="tiff" label="${movie.name[:-4]}_period">
4556 <filter>output_type and "save_period" in output_type</filter>
4557 </data>
4558 </outputs>
4559 ```
4560
4561 ]]></xs:documentation>
4562 </xs:annotation>
4563 <xs:simpleContent>
4564 <xs:extension base="xs:string">
4565 </xs:extension>
4566 </xs:simpleContent>
4567 </xs:complexType>
4568
4569 <xs:complexType name="OutputDiscoverDatasets">
4570 <xs:annotation>
4571 <xs:documentation xml:lang="en"><![CDATA[
4572
4573 Describe datasets to dynamically collect after the job complete.
4574
4575 There are many simple tools with examples of this element distributed with
4576 Galaxy, including:
4577
4578 * [multi_output.xml](https://github.com/galaxyproject/galaxy/tree/master/test/functional/tools/multi_output.xml)
4579 * [multi_output_assign_primary.xml](https://github.com/galaxyproject/galaxy/tree/master/test/functional/tools/multi_output_assign_primary.xml)
4580 * [multi_output_configured.xml](https://github.com/galaxyproject/galaxy/tree/master/test/functional/tools/multi_output_configured.xml)
4581
4582 More information can be found on Planemo's documentation for
4583 [multiple output files](https://planemo.readthedocs.io/en/latest/writing_advanced.html#multiple-output-files).
4584 ]]></xs:documentation>
4585 </xs:annotation>
4586 <xs:attribute name="from_provided_metadata" type="xs:boolean" use="optional">
4587 <xs:annotation>
4588 <xs:documentation xml:lang="en">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.</xs:documentation>
4589 </xs:annotation>
4590 </xs:attribute>
4591 <xs:attribute name="pattern" type="xs:string" use="optional">
4592 <xs:annotation>
4593 <xs:documentation xml:lang="en">Regular expression used to find filenames and parse dynamic properties.</xs:documentation>
4594 </xs:annotation>
4595 </xs:attribute>
4596 <xs:attribute name="directory" type="xs:string" use="optional">
4597 <xs:annotation>
4598 <xs:documentation xml:lang="en">Directory (relative to working directory) to search for files.</xs:documentation>
4599 </xs:annotation>
4600 </xs:attribute>
4601 <xs:attribute name="recurse" type="xs:boolean" use="optional">
4602 <xs:annotation>
4603 <xs:documentation xml:lang="en">Indicates that the specified directory should be searched recursively for matching files.</xs:documentation>
4604 </xs:annotation>
4605 </xs:attribute>
4606 <xs:attribute name="format" type="xs:string" use="optional">
4607 <xs:annotation>
4608 <xs:documentation xml:lang="en">Format (or datatype) of discovered datasets (an alias with ``ext``).</xs:documentation>
4609 </xs:annotation>
4610 </xs:attribute>
4611 <xs:attribute name="ext" type="xs:string" use="optional">
4612 <xs:annotation>
4613 <xs:documentation xml:lang="en">Format (or datatype) of discovered datasets (an alias with ``format``).</xs:documentation>
4614 </xs:annotation>
4615 </xs:attribute>
4616 <xs:attribute name="sort_by" type="xs:string" use="optional">
4617 <xs:annotation>
4618 <xs:documentation xml:lang="en">A string `[reverse_][SORT_COMP_]SORTBY` describing the desired sort order of the collection elements. `SORTBY` can be `filename`, `name`, `designation`, `dbkey` and the optional `SORT_COMP` can be either `lexical` or `numeric`. Default is lexical sorting by filename.</xs:documentation>
4619 </xs:annotation>
4620 </xs:attribute>
4621 <xs:attribute name="visible" type="xs:boolean" use="optional">
4622 <xs:annotation>
4623 <xs:documentation xml:lang="en">Indication if this dataset is visible in output history. This defaults to ``false``, but probably shouldn't - be sure to set to ``true`` if that is your intention.</xs:documentation>
4624 </xs:annotation>
4625 </xs:attribute>
4626 <xs:attribute name="assign_primary_output" type="xs:boolean" use="optional">
4627 <xs:annotation>
4628 <xs:documentation xml:lang="en">Replace the primary dataset described by the parameter ``data`` parameter with the first output discovered.</xs:documentation>
4629 </xs:annotation>
4630 </xs:attribute>
4631 </xs:complexType>
4632 <xs:complexType name="OutputCollectionDiscoverDatasets">
4633 <xs:annotation>
4634 <xs:documentation xml:lang="en"><![CDATA[
4635
4636 This tag allows one to describe the datasets contained within an output
4637 collection dynamically, such that the outputs are "discovered" based on regular
4638 expressions after the job is complete.
4639
4640 There are many simple tools with examples of this element distributed with
4641 Galaxy, including:
4642
4643 * [collection_split_on_column.xml](https://github.com/galaxyproject/galaxy/blob/master/test/functional/tools/collection_split_on_column.xml)
4644 * [collection_creates_dynamic_list_of_pairs.xml](https://github.com/galaxyproject/galaxy/blob/master/test/functional/tools/collection_creates_dynamic_list_of_pairs.xml)
4645 * [collection_creates_dynamic_nested.xml](https://github.com/galaxyproject/galaxy/blob/master/test/functional/tools/collection_creates_dynamic_nested.xml)
4646
4647 ]]></xs:documentation>
4648 </xs:annotation>
4649 <xs:attribute name="from_provided_metadata" type="xs:boolean" use="optional">
4650 <xs:annotation>
4651 <xs:documentation xml:lang="en">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.</xs:documentation>
4652 </xs:annotation>
4653 </xs:attribute>
4654 <xs:attribute name="pattern" type="xs:string" use="optional">
4655 <xs:annotation>
4656 <xs:documentation xml:lang="en">Regular expression used to find filenames and parse dynamic properties.</xs:documentation>
4657 </xs:annotation>
4658 </xs:attribute>
4659 <xs:attribute name="directory" type="xs:string" use="optional">
4660 <xs:annotation>
4661 <xs:documentation xml:lang="en">Directory (relative to working directory) to search for files.</xs:documentation>
4662 </xs:annotation>
4663 </xs:attribute>
4664 <xs:attribute name="recurse" type="xs:boolean" use="optional">
4665 <xs:annotation>
4666 <xs:documentation xml:lang="en">Indicates that the specified directory should be searched recursively for matching files.</xs:documentation>
4667 </xs:annotation>
4668 </xs:attribute>
4669 <xs:attribute name="format" type="xs:string" use="optional">
4670 <xs:annotation>
4671 <xs:documentation xml:lang="en">Format (or datatype) of discovered datasets (an alias with ``ext``).</xs:documentation>
4672 </xs:annotation>
4673 </xs:attribute>
4674 <xs:attribute name="ext" type="xs:string" use="optional">
4675 <xs:annotation>
4676 <xs:documentation xml:lang="en">Format (or datatype) of discovered datasets (an alias with ``format``).</xs:documentation>
4677 </xs:annotation>
4678 </xs:attribute>
4679 <xs:attribute name="sort_by" type="xs:string" use="optional">
4680 <xs:annotation>
4681 <xs:documentation xml:lang="en">A string `[reverse_][SORT_COMP_]SORTBY` describing the desired sort order of the collection elements. `SORTBY` can be `filename`, `name`, `designation`, `dbkey` and the optional `SORT_COMP` can be either `lexical` or `numeric`. Default is lexical sorting by filename.</xs:documentation>
4682 </xs:annotation>
4683 </xs:attribute>
4684 <xs:attribute name="visible" type="xs:boolean" use="optional">
4685 <xs:annotation>
4686 <xs:documentation xml:lang="en">Indication if this dataset is visible in the history. This defaults to ``false``, but probably shouldn't - be sure to set to ``true`` if that is your intention.</xs:documentation>
4687 </xs:annotation>
4688 </xs:attribute>
4689 </xs:complexType>
4690 <xs:complexType name="Actions">
4691 <xs:annotation>
4692 <xs:documentation xml:lang="en"><![CDATA[
4693
4694 The ``actions`` directive allows tools to dynamically take actions related to an
4695 ``output`` either unconditionally or conditionally based on inputs. These
4696 actions currently include setting metadata values and the output's data format.
4697
4698 The examples below will demonstrate that the ``actions`` tag contains child
4699 ``conditional`` tags. The these conditionals are met, additional ``action``
4700 directives below the conditional are apply to the ``data`` output.
4701
4702 ### Metadata
4703
4704 The ``<actions>`` in the Bowtie 2 wrapper is used in lieu of the deprecated
4705 ``<code>`` tag to set the ``dbkey`` of the output dataset. In
4706 [bowtie2_wrapper.xml](https://github.com/galaxyproject/tools-devteam/blob/master/tools/bowtie2/bowtie2_wrapper.xml)
4707 (see below), according to the first action block, if the
4708 ``reference_genome.source`` is ``indexed`` (not ``history``), then it will assign
4709 the ``dbkey`` of the output file to be the same as that of the reference file. It
4710 does this by looking at through the data table and finding the entry that has the
4711 value that's been selected in the index dropdown box as column 1 of the loc file
4712 entry and using the dbkey, in column 0 (ignoring comment lines (starting with #)
4713 along the way).
4714
4715 If ``reference_genome.source`` is ``history``, it pulls the ``dbkey`` from the
4716 supplied file.
4717
4718 ```xml
4719 <data format="bam" name="output" label="${tool.name} on ${on_string}: aligned reads (sorted BAM)">
4720 <filter>analysis_type['analysis_type_selector'] == "simple" or analysis_type['sam_opt'] is False</filter>
4721 <actions>
4722 <conditional name="reference_genome.source">
4723 <when value="indexed">
4724 <action type="metadata" name="dbkey">
4725 <option type="from_data_table" name="bowtie2_indexes" column="1" offset="0">
4726 <filter type="param_value" column="0" value="#" compare="startswith" keep="false"/>
4727 <filter type="param_value" ref="reference_genome.index" column="0"/>
4728 </option>
4729 </action>
4730 </when>
4731 <when value="history">
4732 <action type="metadata" name="dbkey">
4733 <option type="from_param" name="reference_genome.own_file" param_attribute="dbkey" />
4734 </action>
4735 </when>
4736 </conditional>
4737 </actions>
4738 </data>
4739 ```
4740
4741 ### Format
4742
4743 The Bowtie 2 example also demonstrates conditionally setting an output format
4744 based on inputs, as shown below:
4745
4746 ```xml
4747 <data format="fastqsanger" name="output_unaligned_reads_r" label="${tool.name} on ${on_string}: unaligned reads (R)">
4748 <filter>(library['type'] == "paired" or library['type'] == "paired_collection") and library['unaligned_file'] is True</filter>
4749 <actions>
4750 <conditional name="library.type">
4751 <when value="paired">
4752 <action type="format">
4753 <option type="from_param" name="library.input_2" param_attribute="ext" />
4754 </action>
4755 </when>
4756 <when value="paired_collection">
4757 <action type="format">
4758 <option type="from_param" name="library.input_1" param_attribute="reverse.ext" />
4759 </action>
4760 </when>
4761 </conditional>
4762 </actions>
4763 </data>
4764 ```
4765
4766 ### Unconditional Actions and Column Names
4767
4768 For a static file that contains a fixed number of columns, it is straight forward:
4769
4770 ```xml
4771 <outputs>
4772 <data format="tabular" name="table">
4773 <actions>
4774 <action name="column_names" type="metadata" default="Firstname,Lastname,Age" />
4775 </actions>
4776 </data>
4777 </outputs>
4778 ```
4779
4780 It may also be necessary to use column names based on a variable from another
4781 input file. This is implemented in the
4782 [htseq-count](https://github.com/galaxyproject/tools-iuc/blob/master/tools/htseq_count/htseq-count.xml)
4783 and
4784 [featureCounts](https://github.com/galaxyproject/tools-iuc/blob/master/tools/featurecounts/featurecounts.xml)
4785 wrappers:
4786
4787 ```xml
4788 <inputs>
4789 <data name="input_file" type="data" multiple="false">
4790 </inputs>
4791 <outputs>
4792 <data format="tabular" name="output_short">
4793 <actions>
4794 <action name="column_names" type="metadata" default="Geneid,${input_file.name}" />
4795 </actions>
4796 </data>
4797 </outputs>
4798 ```
4799
4800 Or in case of multiple files:
4801
4802 ```xml
4803 <inputs>
4804 <data name="input_files" type="data" multiple="true">
4805 </inputs>
4806 <outputs>
4807 <data format="tabular" name="output_short">
4808 <actions>
4809 <action name="column_names" type="metadata" default="Geneid,${','.join([a.name for a in $input_files])}" />
4810 </actions>
4811 </data>
4812 </outputs>
4813 ```
4814
4815 ### Unconditional Actions - An Older Example
4816
4817 The first approach above to setting ``dbkey`` based on tool data tables is
4818 prefered, but an older example using so called "loc files" directly is found
4819 below.
4820
4821 In addition to demonstrating this lower-level direct access of .loc files, it
4822 demonstrates an unconditional action. The second block would not be needed for
4823 most cases - it was required in this tool to handle the specific case of a small
4824 reference file used for functional testing. It says that if the dbkey has been
4825 set to ``equCab2chrM`` (which is what the ``<filter type="metadata_value"...
4826 column="1" />`` tag does), then it should be changed to ``equCab2`` (which is the
4827 ``<option type="from_param" ... column="0" ...>`` tag does).
4828
4829 ```xml
4830 <actions>
4831 <conditional name="refGenomeSource.genomeSource">
4832 <when value="indexed">
4833 <action type="metadata" name="dbkey">
4834 <option type="from_file" name="bowtie_indices.loc" column="0" offset="0">
4835 <filter type="param_value" column="0" value="#" compare="startswith" keep="false"/>
4836 <filter type="param_value" ref="refGenomeSource.index" column="1"/>
4837 </option>
4838 </action>
4839 </when>
4840 </conditional>
4841 <!-- Special casing equCab2chrM to equCab2 -->
4842 <action type="metadata" name="dbkey">
4843 <option type="from_param" name="refGenomeSource.genomeSource" column="0" offset="0">
4844 <filter type="insert_column" column="0" value="equCab2chrM"/>
4845 <filter type="insert_column" column="0" value="equCab2"/>
4846 <filter type="metadata_value" ref="output" name="dbkey" column="1" />
4847 </option>
4848 </action>
4849 </actions>
4850 ```
4851 ]]>
4852 </xs:documentation>
4853 </xs:annotation>
4854 <xs:sequence>
4855 <xs:group ref="ActionsElement" minOccurs="0" maxOccurs="unbounded"/>
4856 </xs:sequence>
4857 </xs:complexType>
4858 <xs:group name="ActionsElement">
4859 <xs:choice>
4860 <xs:element name="action" type="Action"/>
4861 <xs:element name="conditional" type="ActionsConditional"/>
4862 </xs:choice>
4863 </xs:group>
4864 <xs:complexType name="Action">
4865 <xs:annotation>
4866 <xs:documentation xml:lang="en"><![CDATA[
4867
4868 This directive is contained within an output ``data``'s ``actions`` directive
4869 (either directly or beneath a parent ``conditional`` tag). This directive
4870 describes modifications to either the output's format or metadata (based on
4871 whether ``type`` is ``format`` or ``metadata``).
4872
4873 See [actions](#tool-outputs-data-actions) documentation for examples
4874 of this directive.
4875
4876 ]]></xs:documentation>
4877 </xs:annotation>
4878 <xs:sequence>
4879 <xs:element name="option" type="ActionsOption" minOccurs="0" maxOccurs="unbounded"/>
4880 </xs:sequence>
4881 <xs:attribute name="type" type="ActionType" use="required">
4882 <xs:annotation>
4883 <xs:documentation xml:lang="en">Type of action (either ``format`` or
4884 ``metadata`` currently).</xs:documentation>
4885 </xs:annotation>
4886 </xs:attribute>
4887 <xs:attribute name="name" type="xs:string">
4888 <xs:annotation>
4889 <xs:documentation xml:lang="en">If ``type="metadata"``, the name of the
4890 metadata element.</xs:documentation>
4891 </xs:annotation>
4892 </xs:attribute>
4893 <xs:attribute name="default" type="xs:string">
4894 <xs:annotation>
4895 <xs:documentation xml:lang="en">If ``type="format"``, the default format
4896 if none of the nested options apply.</xs:documentation>
4897 </xs:annotation>
4898 </xs:attribute>
4899 </xs:complexType>
4900 <xs:complexType name="ActionsOption">
4901 <xs:annotation>
4902 <xs:documentation xml:lang="en"></xs:documentation>
4903 </xs:annotation>
4904 <xs:sequence>
4905 <xs:element name="filter" type="ActionsConditionalFilter" minOccurs="0" maxOccurs="unbounded"/>
4906 </xs:sequence>
4907 <xs:attribute name="type" type="ActionsOptionType">
4908 <xs:annotation>
4909 <xs:documentation xml:lang="en"></xs:documentation>
4910 </xs:annotation>
4911 </xs:attribute>
4912 <xs:attribute name="name" type="xs:string">
4913 <xs:annotation>
4914 <xs:documentation xml:lang="en"></xs:documentation>
4915 </xs:annotation>
4916 </xs:attribute>
4917 <xs:attribute name="column" type="xs:integer">
4918 <xs:annotation>
4919 <xs:documentation xml:lang="en"></xs:documentation>
4920 </xs:annotation>
4921 </xs:attribute>
4922 <xs:attribute name="offset" type="xs:integer">
4923 <xs:annotation>
4924 <xs:documentation xml:lang="en"></xs:documentation>
4925 </xs:annotation>
4926 </xs:attribute>
4927 <xs:attribute name="param_attribute" type="xs:string">
4928 <xs:annotation>
4929 <xs:documentation xml:lang="en"></xs:documentation>
4930 </xs:annotation>
4931 </xs:attribute>
4932 </xs:complexType>
4933 <xs:complexType name="ActionsConditional">
4934 <xs:annotation>
4935 <xs:documentation xml:lang="en"><![CDATA[
4936
4937 This directive is contained within an output ``data``'s ``actions`` directive.
4938 This directive describes the state of the inputs required to apply an ``action``
4939 (specified as children of the child ``when`` directives to this element) to an
4940 output.
4941
4942 See [actions](#tool-outputs-data-actions) documentation for examples
4943 of this directive.
4944
4945 ]]></xs:documentation>
4946 </xs:annotation>
4947 <xs:sequence>
4948 <xs:element name="when" type="ActionsConditionalWhen" minOccurs="0" maxOccurs="unbounded"/>
4949 </xs:sequence>
4950 <xs:attribute name="name" type="xs:string" use="required">
4951 <xs:annotation>
4952 <xs:documentation xml:lang="en">Name of the input parameter to base
4953 conditional logic on. The value of this parameter will be matched against nested
4954 ``when`` directives.</xs:documentation>
4955 </xs:annotation>
4956 </xs:attribute>
4957 </xs:complexType>
4958 <xs:complexType name="ActionsConditionalWhen">
4959 <xs:annotation>
4960 <xs:documentation xml:lang="en"><![CDATA[
4961
4962 See [actions](#tool-outputs-data-actions) documentation for examples
4963 of this directive.
4964
4965 ]]></xs:documentation>
4966 </xs:annotation>
4967 <xs:sequence>
4968 <xs:element name="action" type="Action" minOccurs="1" maxOccurs="unbounded"/>
4969 </xs:sequence>
4970 <xs:attribute name="value" type="xs:string" use="optional">
4971 <xs:annotation>
4972 <xs:documentation xml:lang="en">Value to match conditional input value
4973 against.</xs:documentation>
4974 </xs:annotation>
4975 </xs:attribute>
4976 <xs:attribute name="datatype_isinstance" type="xs:string" use="optional">
4977 <xs:annotation>
4978 <xs:documentation xml:lang="en">Datatype to match against (if ``value`` is unspecified). This should be the short string describing the format (e.g. ``interval``).</xs:documentation>
4979 </xs:annotation>
4980 </xs:attribute>
4981 </xs:complexType>
4982 <xs:complexType name="ActionsConditionalFilter">
4983 <xs:annotation>
4984 <xs:documentation xml:lang="en"></xs:documentation>
4985 </xs:annotation>
4986 <xs:attribute name="type" type="ActionsConditionalFilterType" use="required">
4987 <xs:annotation>
4988 <xs:documentation xml:lang="en"><![CDATA[]]></xs:documentation>
4989 </xs:annotation>
4990 </xs:attribute>
4991 <xs:attribute name="compare" type="CompareType">
4992 <xs:annotation>
4993 <xs:documentation xml:lang="en"></xs:documentation>
4994 </xs:annotation>
4995 </xs:attribute>
4996 <xs:attribute name="ref" type="xs:string">
4997 <xs:annotation>
4998 <xs:documentation xml:lang="en"></xs:documentation>
4999 </xs:annotation>
5000 </xs:attribute>
5001 <xs:attribute name="value" type="xs:string">
5002 <xs:annotation>
5003 <xs:documentation xml:lang="en"></xs:documentation>
5004 </xs:annotation>
5005 </xs:attribute>
5006 <xs:attribute name="column" type="xs:integer">
5007 <xs:annotation>
5008 <xs:documentation xml:lang="en"></xs:documentation>
5009 </xs:annotation>
5010 </xs:attribute>
5011 <xs:attribute name="keep" type="PermissiveBoolean">
5012 <xs:annotation>
5013 <xs:documentation xml:lang="en"></xs:documentation>
5014 </xs:annotation>
5015 </xs:attribute>
5016 <xs:attribute name="cast" type="xs:string">
5017 <xs:annotation>
5018 <xs:documentation xml:lang="en"></xs:documentation>
5019 </xs:annotation>
5020 </xs:attribute>
5021 <xs:attribute name="param_attribute" type="xs:string">
5022 <xs:annotation>
5023 <xs:documentation xml:lang="en"></xs:documentation>
5024 </xs:annotation>
5025 </xs:attribute>
5026 <xs:attribute name="separator" type="xs:string">
5027 <xs:annotation>
5028 <xs:documentation xml:lang="en"></xs:documentation>
5029 </xs:annotation>
5030 </xs:attribute>
5031 <xs:attribute name="strip" type="PermissiveBoolean">
5032 <xs:annotation>
5033 <xs:documentation xml:lang="en"></xs:documentation>
5034 </xs:annotation>
5035 </xs:attribute>
5036 <xs:attribute name="old_column" type="xs:string">
5037 <xs:annotation>
5038 <xs:documentation xml:lang="en"></xs:documentation>
5039 </xs:annotation>
5040 </xs:attribute>
5041 <xs:attribute name="old_value" type="xs:string">
5042 <xs:annotation>
5043 <xs:documentation xml:lang="en"></xs:documentation>
5044 </xs:annotation>
5045 </xs:attribute>
5046 <xs:attribute name="new_column" type="xs:string">
5047 <xs:annotation>
5048 <xs:documentation xml:lang="en"></xs:documentation>
5049 </xs:annotation>
5050 </xs:attribute>
5051 <xs:attribute name="new_value" type="xs:string">
5052 <xs:annotation>
5053 <xs:documentation xml:lang="en"></xs:documentation>
5054 </xs:annotation>
5055 </xs:attribute>
5056 </xs:complexType>
5057 <xs:complexType name="EnvironmentVariables">
5058 <xs:annotation>
5059 <xs:documentation xml:lang="en">
5060 This directive should contain one or more ``environment_variable`` definition.
5061 </xs:documentation>
5062 </xs:annotation>
5063 <xs:sequence>
5064 <xs:element name="environment_variable" type="EnvironmentVariable" minOccurs="0" maxOccurs="unbounded" />
5065 </xs:sequence>
5066 </xs:complexType>
5067
5068 <xs:complexType name="EnvironmentVariable">
5069 <xs:annotation>
5070 <xs:documentation xml:lang="en"><![CDATA[
5071
5072 This directive defines an environment variable that will be available when the
5073 tool executes. The body should be a Cheetah template block that may reference
5074 the tool's inputs as demonstrated below.
5075
5076 ### Example
5077
5078 The following demonstrates a couple ``environment_variable`` definitions.
5079
5080 ```xml
5081 <environment_variables>
5082 <environment_variable name="INTVAR">$inttest</environment_variable>
5083 <environment_variable name="IFTEST">#if int($inttest) == 3
5084 ISTHREE
5085 #else#
5086 NOTTHREE
5087 #end if#</environment_variable>
5088 </environment_variables>
5089 </environment_variables>
5090 ```
5091
5092 If these environment variables are used in another Cheetah context, such as in
5093 the ``command`` block, the ``$`` used indicate shell expansion of a variable
5094 should be escaped with a ``\`` so prevent it from being evaluated as a Cheetah
5095 variable instead of shell variable.
5096
5097 ```xml
5098 <command>
5099 echo "\$INTVAR" > $out_file1;
5100 echo "\$IFTEST" >> $out_file1;
5101 </command>
5102 ```
5103
5104 ### inject
5105
5106 The Galaxy user's API key can be injected into an environment variable by setting ``inject``
5107 attribute to ``api_key`` (e.g. ``inject="api_key"``).
5108
5109 ```xml
5110 <environment_variables>
5111 <environment_variable name="GALAXY_API_KEY" inject="api_key" />
5112 </environment_variables>
5113 ```
5114
5115 The framework allows setting this via environment variable and not via templating variables
5116 in order to discourage setting the actual values of these keys as command line arguments.
5117 On shared systems this provides some security by preventing a simple process listing command
5118 from exposing keys.
5119 ]]></xs:documentation>
5120 </xs:annotation>
5121 <xs:simpleContent>
5122 <xs:extension base="xs:string">
5123 <xs:attribute name="name" type="xs:string">
5124 <xs:annotation>
5125 <xs:documentation xml:lang="en">Name of the environment variable to
5126 define.</xs:documentation>
5127 </xs:annotation>
5128 </xs:attribute>
5129 <xs:attribute name="inject" type="EnvironmentVariableInject" gxdocs:added="19.09">
5130 <xs:annotation>
5131 <xs:documentation xml:lang="en">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.</xs:documentation>
5132 </xs:annotation>
5133 </xs:attribute>
5134 <xs:attribute name="strip" type="PermissiveBoolean" default="false">
5135 <xs:annotation>
5136 <xs:documentation xml:lang="en">Whether to strip leading and trailing whitespace from the calculated value before exporting the environment variable.</xs:documentation>
5137 </xs:annotation>
5138 </xs:attribute>
5139 </xs:extension>
5140 </xs:simpleContent>
5141 </xs:complexType>
5142 <xs:simpleType name="EnvironmentVariableInject">
5143 <xs:annotation>
5144 <xs:documentation xml:lang="en"></xs:documentation>
5145 </xs:annotation>
5146 <xs:restriction base="xs:string">
5147 <xs:enumeration value="api_key" />
5148 </xs:restriction>
5149 </xs:simpleType>
5150 <xs:complexType name="ConfigFiles">
5151 <xs:annotation>
5152 <xs:documentation xml:lang="en"><![CDATA[See
5153 [xy_plot.xml](https://github.com/galaxyproject/tools-devteam/blob/master/tools/xy_plot/xy_plot.xml)
5154 for an example of how this tag set is used in a tool. This tag set is a
5155 container for ``<configfile>`` and ``<inputs>`` tag sets - which can be used
5156 to setup configuration files for use by tools.]]></xs:documentation>
5157 </xs:annotation>
5158 <xs:sequence>
5159 <xs:group ref="ConfigFilesElement" minOccurs="0" maxOccurs="unbounded" />
5160 </xs:sequence>
5161 </xs:complexType>
5162
5163 <xs:group name="ConfigFilesElement">
5164 <xs:choice>
5165 <xs:element name="inputs" type="ConfigInputs"/>
5166 <xs:element name="file_sources" type="ConfigFileSources"/>
5167 <xs:element name="configfile" type="ConfigFile"/>
5168 </xs:choice>
5169 </xs:group>
5170
5171 <xs:complexType name="ConfigFile">
5172 <xs:annotation>
5173 <xs:documentation xml:lang="en"><![CDATA[
5174
5175 This tag set is contained within the ``<configfiles>`` tag set. It allows for
5176 the creation of a temporary file for file-based parameter transfer.
5177
5178 *Example*
5179
5180 The following is taken from the [xy_plot.xml](https://github.com/galaxyproject/tools-devteam/blob/master/tools/xy_plot/xy_plot.xml)
5181 tool config.
5182
5183 ```xml
5184 <configfiles>
5185 <configfile name="script_file">
5186 ## Setup R error handling to go to stderr
5187 options(show.error.messages=F, error = function () { cat(geterrmessage(), file=stderr()); q("no", 1, F) })
5188 ## Determine range of all series in the plot
5189 xrange = c(NULL, NULL)
5190 yrange = c(NULL, NULL)
5191 #for $i, $s in enumerate($series)
5192 s${i} = read.table("${s.input.file_name}")
5193 x${i} = s${i}[,${s.xcol}]
5194 y${i} = s${i}[,${s.ycol}]
5195 xrange = range(x${i}, xrange)
5196 yrange = range(y${i}, yrange)
5197 #end for
5198 ## Open output PDF file
5199 pdf("${out_file1}")
5200 ## Dummy plot for axis / labels
5201 plot(NULL, type="n", xlim=xrange, ylim=yrange, main="${main}", xlab="${xlab}", ylab="${ylab}")
5202 ## Plot each series
5203 #for $i, $s in enumerate($series)
5204 #if $s.series_type['type'] == "line"
5205 lines(x${i}, y${i}, lty=${s.series_type.lty}, lwd=${s.series_type.lwd}, col=${s.series_type.col})
5206 #elif $s.series_type.type == "points"
5207 points(x${i}, y${i}, pch=${s.series_type.pch}, cex=${s.series_type.cex}, col=${s.series_type.col})
5208 #end if
5209 #end for
5210 ## Close the PDF file
5211 devname = dev.off()
5212 </configfile>
5213 </configfiles>
5214 ```
5215
5216 This file is then used in the ``command`` block of the tool as follows:
5217
5218 ```xml
5219 <command>bash '$__tool_directory__/r_wrapper.sh' '$script_file'</command>
5220 ```
5221
5222 ]]></xs:documentation>
5223 </xs:annotation>
5224 <xs:simpleContent>
5225 <xs:extension base="xs:string">
5226 <xs:attribute name="name" type="xs:string">
5227 <xs:annotation>
5228 <xs:documentation xml:lang="en">Cheetah variable used to reference
5229 the path to the file created with this directive.</xs:documentation>
5230 </xs:annotation>
5231 </xs:attribute>
5232 <xs:attribute name="filename" type="xs:string">
5233 <xs:annotation>
5234 <xs:documentation xml:lang="en">Path relative to the working directory of the tool for the configfile created in response to this directive.</xs:documentation>
5235 </xs:annotation>
5236 </xs:attribute>
5237 </xs:extension>
5238 </xs:simpleContent>
5239 </xs:complexType>
5240
5241 <xs:complexType name="ConfigInputs">
5242 <xs:annotation>
5243 <xs:documentation xml:lang="en"><![CDATA[
5244
5245 This tag set is contained within the ``<configfiles>`` tag set. It tells Galaxy to
5246 write out a JSON representation of the tool parameters.
5247
5248 *Example*
5249
5250 The following will create a Cheetah variable that can be evaluated as ``$inputs`` that
5251 will contain the tool parameter inputs.
5252
5253 ```xml
5254 <configfiles>
5255 <inputs name="inputs" />
5256 <configfiles>
5257 ```
5258
5259 The following will instead write the inputs to the tool's working directory with
5260 the specified name (i.e. ``inputs.json``).
5261
5262 ```xml
5263 <configfiles>
5264 <inputs name="inputs" filename="inputs.json" />
5265 <configfiles>
5266 ```
5267
5268 A contrived example of a tool that uses this is the test tool
5269 [inputs_as_json.xml](https://github.com/galaxyproject/galaxy/blob/dev/test/functional/tools/inputs_as_json.xml).
5270
5271 By default this file will not contain paths for data or collection inputs. To include simple
5272 paths for data parameters set the ``data_style`` attribute to ``paths`` (see [inputs_as_json_with_paths.xml](https://github.com/galaxyproject/galaxy/blob/dev/test/functional/tools/inputs_as_json_with_paths.xml) for an example).
5273
5274 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.
5275 ]]></xs:documentation>
5276 </xs:annotation>
5277 <xs:simpleContent>
5278 <xs:extension base="xs:string">
5279 <xs:attribute name="name" type="xs:string">
5280 <xs:annotation>
5281 <xs:documentation xml:lang="en"><![CDATA[
5282 Cheetah variable to populate the path to the inputs JSON file created in
5283 response to this directive.
5284 ]]></xs:documentation>
5285 </xs:annotation>
5286 </xs:attribute>
5287 <xs:attribute name="filename" type="xs:string">
5288 <xs:annotation>
5289 <xs:documentation xml:lang="en">Path relative to the working directory of the tool for the inputs JSON file created in response to this directive.</xs:documentation>
5290 </xs:annotation>
5291 </xs:attribute>
5292 <xs:attribute name="data_style" type="xs:string">
5293 <xs:annotation>
5294 <xs:documentation xml:lang="en">Set to 'paths' to include dataset paths in the resulting file.</xs:documentation>
5295 </xs:annotation>
5296 </xs:attribute>
5297 </xs:extension>
5298 </xs:simpleContent>
5299 </xs:complexType>
5300
5301 <xs:complexType name="ConfigFileSources">
5302 <xs:annotation>
5303 <xs:documentation xml:lang="en"><![CDATA[
5304 ]]></xs:documentation>
5305 </xs:annotation>
5306 <xs:simpleContent>
5307 <xs:extension base="xs:string">
5308 <xs:attribute name="name" type="xs:string">
5309 <xs:annotation>
5310 <xs:documentation xml:lang="en"><![CDATA[
5311 Cheetah variable to populate the path to the inputs JSON file created in
5312 response to this directive.
5313 ]]></xs:documentation>
5314 </xs:annotation>
5315 </xs:attribute>
5316 <xs:attribute name="filename" type="xs:string">
5317 <xs:annotation>
5318 <xs:documentation xml:lang="en">Path relative to the working directory of the tool for the file sources JSON configuration file created in response to this directive.</xs:documentation>
5319 </xs:annotation>
5320 </xs:attribute>
5321 </xs:extension>
5322 </xs:simpleContent>
5323 </xs:complexType>
5324
5325 <xs:complexType name="VersionCommand">
5326 <xs:annotation>
5327 <xs:documentation xml:lang="en"><![CDATA[Specifies the command to be run in
5328 order to get the tool's version string. The resulting value will be found in the
5329 "Info" field of the history dataset.
5330
5331 Unlike the [command](#tool-command) tag, with the exception of the string
5332 ``$__tool_directory__`` this value is taken as a literal and so there is no
5333 need to escape values like ``$`` and command inputs are not available for variable
5334 substitution.
5335
5336 ### Examples
5337
5338 A simple example for a [TopHat](https://ccb.jhu.edu/software/tophat/index.shtml)
5339 tool definition might just be:
5340
5341 ```xml
5342 <version_command>tophat -version</version_command>
5343 ```
5344
5345 An example that leverages a Python script (e.g. ``count_reads.py``) shipped with
5346 the tool might be:
5347
5348 ```xml
5349 <version_command>python '$__tool_directory__/count_reads.py'</version_command>
5350 ```
5351
5352 Examples are included in the test tools directory including:
5353
5354 - [version_command_plain.xml](https://github.com/galaxyproject/galaxy/blob/dev/test/functional/tools/version_command_plain.xml)
5355 - [version_command_tool_dir.xml](https://github.com/galaxyproject/galaxy/blob/dev/test/functional/tools/version_command_tool_dir.xml)
5356 - [version_command_interpreter.xml](https://github.com/galaxyproject/galaxy/blob/dev/test/functional/tools/version_command_interpreter.xml) (*deprecated*)
5357
5358 ]]></xs:documentation>
5359 </xs:annotation>
5360 <xs:simpleContent>
5361 <xs:extension base="xs:string">
5362 <xs:attribute name="interpreter" type="xs:string">
5363 <xs:annotation>
5364 <xs:documentation xml:lang="en"><![CDATA[*Deprecated*. This will prefix the version command with the value of this attribute (e.g. ``python`` or ``perl``) and the tool directory, in order to to run an executable file shipped with the tool. It is recommended to instead use ``<interpreter> '$__tool_directory__/<executable_name>'`` in the tag content. If this attribute is not specified, the tag should contain a Bash command calling executable(s) available in the ``$PATH``, as modified after loading the requirements.]]></xs:documentation>
5365 </xs:annotation>
5366 </xs:attribute>
5367 </xs:extension>
5368 </xs:simpleContent>
5369 </xs:complexType>
5370
5371 <xs:complexType name="RequestParameterTranslation">
5372 <xs:annotation>
5373 <xs:documentation xml:lang="en"><![CDATA[See [/tools/data_source/ucsc_tablebrowser.xml](https://github.com/galaxyproject/galaxy/blob/dev/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](#tool-request-param-translation-request-param) elements.]]></xs:documentation>
5374 </xs:annotation>
5375 <xs:sequence>
5376 <xs:element name="request_param" minOccurs="0" maxOccurs="unbounded" type="RequestParameter"/>
5377 </xs:sequence>
5378 </xs:complexType>
5379
5380 <xs:complexType name="RequestParameter">
5381 <xs:annotation>
5382 <xs:documentation xml:lang="en"><![CDATA[Contained within the [request_param_translation](#tool-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.]]></xs:documentation>
5383 </xs:annotation>
5384 <xs:sequence>
5385 <xs:group ref="RequestParameterElement" minOccurs="0" maxOccurs="unbounded"/>
5386 </xs:sequence>
5387 <xs:attribute name="galaxy_name" type="RequestParameterGalaxyNameType" use="required">
5388 <xs:annotation>
5389 <xs:documentation xml:lang="en">
5390 Each of these maps directly to a ``remote_name`` value
5391 </xs:documentation>
5392 </xs:annotation>
5393 </xs:attribute>
5394 <xs:attribute name="remote_name" type="xs:string" use="required">
5395 <xs:annotation>
5396 <xs:documentation xml:lang="en">
5397 The string representing the name of the parameter in the remote data source
5398 </xs:documentation>
5399 </xs:annotation>
5400 </xs:attribute>
5401 <xs:attribute name="missing" type="xs:string">
5402 <xs:annotation>
5403 <xs:documentation xml:lang="en">
5404 The default value to use for ``galaxy_name`` if the ``remote_name`` parameter is not included in the request
5405 </xs:documentation>
5406 </xs:annotation>
5407 </xs:attribute>
5408 </xs:complexType>
5409
5410 <xs:simpleType name="RequestParameterGalaxyNameType">
5411 <xs:annotation>
5412 <xs:documentation xml:lang="en"></xs:documentation>
5413 </xs:annotation>
5414 <xs:restriction base="xs:string">
5415 <xs:enumeration value="URL" />
5416 <xs:enumeration value="URL_method" />
5417 <xs:enumeration value="dbkey" />
5418 <xs:enumeration value="organism" />
5419 <xs:enumeration value="table" />
5420 <xs:enumeration value="description" />
5421 <xs:enumeration value="name" />
5422 <xs:enumeration value="info" />
5423 <xs:enumeration value="data_type" />
5424 </xs:restriction>
5425 </xs:simpleType>
5426
5427 <xs:group name="RequestParameterElement">
5428 <xs:choice>
5429 <xs:element name="append_param" type="RequestParameterAppend" />
5430 <xs:element name="value_translation" type="RequestParameterValueTranslation" />
5431 </xs:choice>
5432 </xs:group>
5433
5434 <xs:complexType name="RequestParameterAppend">
5435 <xs:annotation>
5436 <xs:documentation xml:lang="en"><![CDATA[Optionally contained within the [request_param](#tool-request-param-translation-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.]]></xs:documentation>
5437 </xs:annotation>
5438 <xs:sequence>
5439 <xs:element name="value" minOccurs="0" maxOccurs="unbounded" type="RequestParameterAppendValue"/>
5440 </xs:sequence>
5441 <xs:attribute name="separator" type="xs:string" use="required">
5442 <xs:annotation>
5443 <xs:documentation xml:lang="en"><![CDATA[
5444 The text to use to join the requested parameters together (example ``separator="&amp;"``).
5445 ]]></xs:documentation>
5446 </xs:annotation>
5447 </xs:attribute>
5448 <xs:attribute name="first_separator" type="xs:string">
5449 <xs:annotation>
5450 <xs:documentation xml:lang="en"><![CDATA[
5451 The text to use to join the ``request_param`` parameters to the first requested parameter (example ``first_separator="?"``).
5452 ]]></xs:documentation>
5453 </xs:annotation>
5454 </xs:attribute>
5455 <xs:attribute name="join" type="xs:string" use="required">
5456 <xs:annotation>
5457 <xs:documentation xml:lang="en"><![CDATA[
5458 The text to use to join the param name to its value (example ``join="="``).
5459 ]]></xs:documentation>
5460 </xs:annotation>
5461 </xs:attribute>
5462 </xs:complexType>
5463
5464 <xs:complexType name="RequestParameterAppendValue">
5465 <xs:annotation>
5466 <xs:documentation xml:lang="en"><![CDATA[Contained within the [append_param](#tool-request-param-translation-request-param-append-param) tag set. Allows for appending a param name / value pair to the value of URL.
5467
5468 Example:
5469
5470 ```xml
5471 <request_param_translation>
5472 <request_param galaxy_name="URL" remote_name="URL" missing="">
5473 <append_param separator="&amp;" first_separator="?" join="=">
5474 <value name="_export" missing="1" />
5475 </append_param>
5476 </request_param>
5477 </request_param_tranlsation>
5478 ```
5479 ]]></xs:documentation>
5480 </xs:annotation>
5481 <xs:attribute name="name" type="xs:string" use="required">
5482 <xs:annotation>
5483 <xs:documentation xml:lang="en"><![CDATA[
5484 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 ``"&_export=1"`` (e.g. ``name="_export"``).
5485 ]]></xs:documentation>
5486 </xs:annotation>
5487 </xs:attribute>
5488 <xs:attribute name="missing" type="xs:string" use="required">
5489 <xs:annotation>
5490 <xs:documentation xml:lang="en"><![CDATA[Must be a valid HTTP request parameter value (e.g. ``missing="1"``).]]></xs:documentation>
5491 </xs:annotation>
5492 </xs:attribute>
5493 </xs:complexType>
5494
5495 <xs:complexType name="RequestParameterValueTranslation">
5496 <xs:annotation>
5497 <xs:documentation xml:lang="en"><![CDATA[Optionally contained within the [request_param](#tool-request-param-translation-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.]]></xs:documentation>
5498 </xs:annotation>
5499 <xs:sequence>
5500 <xs:element name="value" minOccurs="0" maxOccurs="unbounded" type="RequestParameterValueTranslationValue"/>
5501 </xs:sequence>
5502 </xs:complexType>
5503
5504 <xs:complexType name="RequestParameterValueTranslationValue">
5505 <xs:annotation>
5506 <xs:documentation xml:lang="en"><![CDATA[Contained within the [value_translation](#tool-request-param-translation-request-param-value-translation) tag set - allows for changing the data type value to something supported by Galaxy.
5507
5508 Example:
5509
5510 ```xml
5511 <request_param_translation>
5512 <request_param galaxy_name="data_type" remote_name="hgta_outputType" missing="bed" >
5513 <value_translation>
5514 <value galaxy_value="tabular" remote_value="primaryTable" />
5515 </value_translation>
5516 </request_param>
5517 </request_param_tranlsation>
5518 ```
5519 ]]></xs:documentation>
5520 </xs:annotation>
5521 <xs:attribute name="galaxy_value" type="xs:string" use="required">
5522 <xs:annotation>
5523 <xs:documentation xml:lang="en"><![CDATA[
5524 The target value (e.g. for setting data format: the list of supported data formats is contained in the
5525 [/config/datatypes_conf.xml.sample](https://github.com/galaxyproject/galaxy/blob/dev/config/datatypes_conf.xml.sample).
5526 ]]></xs:documentation>
5527 </xs:annotation>
5528 </xs:attribute>
5529 <xs:attribute name="remote_value" type="xs:string" use="required">
5530 <xs:annotation>
5531 <xs:documentation xml:lang="en"><![CDATA[The value supplied by the remote data source application]]></xs:documentation>
5532 </xs:annotation>
5533 </xs:attribute>
5534 </xs:complexType>
5535
5536 <xs:complexType name="Stdio">
5537 <xs:annotation>
5538 <xs:documentation xml:lang="en"><![CDATA[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.
5539
5540 Legacy tools (ones with ``profile`` unspecified or a ``profile`` of less than
5541 16.04) will default to checking stderr for errors as described above. Newer
5542 tools will instead treat an exit code other than 0 as an error. The
5543 ``detect_errors`` on ``command`` can swap between these behaviors but the
5544 ``stdio`` directive allows more options in defining error conditions (though
5545 these aren't always intuitive).
5546
5547 With ``stdio`` directive, Galaxy can use regular expressions to scan stdout and
5548 stderr, and it also allows exit codes to be scanned for ranges. The ``<stdio>``
5549 tag has two subtags, ``<regex>`` and ``<exit_code>``, to define regular
5550 expressions and exit code processing, respectively. They are defined below. If a
5551 tool does not have any valid ``<regex>`` or ``<exit_code>`` tags, then Galaxy
5552 will use the previous technique for finding errors.
5553
5554 A note should be made on the order in which exit codes and regular expressions
5555 are applied and how the processing stops. Exit code rules are applied before
5556 regular expression rules. The rationale is that exit codes are more clearly
5557 defined and are easier to check computationally, so they are applied first. Exit
5558 code rules are applied in the order in which they appear in the tool's
5559 configuration file, and regular expressions are also applied in the order in
5560 which they appear in the tool's configuration file. However, once a rule is
5561 triggered that causes a fatal error, no further rules are
5562 checked.]]></xs:documentation>
5563
5564 </xs:annotation>
5565 <xs:sequence>
5566 <xs:group ref="StdioElement" minOccurs="0" maxOccurs="unbounded" />
5567 </xs:sequence>
5568 </xs:complexType>
5569
5570 <xs:group name="StdioElement">
5571 <xs:choice>
5572 <xs:element name="regex" type="Regex"/>
5573 <xs:element name="exit_code" type="ExitCode"/>
5574 </xs:choice>
5575 </xs:group>
5576
5577 <xs:complexType name="ExitCode">
5578 <xs:annotation>
5579 <xs:documentation xml:lang="en"><![CDATA[
5580 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.
5581
5582 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.
5583
5584 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](https://en.wikipedia.org/wiki/Signal_(IPC)) as well as on the man page for "signal" (``man 7 signal``).
5585
5586 The ``<exit_code>`` tag's supported attributes are as follows:
5587
5588 * ``range``: This indicates the range of exit codes to check. The range can be one of the following:
5589 * ``n``: the exit code will only be compared to n;
5590 * ``[m:n]``: the exit code must be greater than or equal to m and less than or equal to n;
5591 * ``[m:]``: the exit code must be greater than or equal to m;
5592 * ``[:n]``: the exit code must be less than or equal to n.
5593 * ``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:
5594 * ``log`` and ``warning``: 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 'Log:' or 'Warning:'. A log-level/warning-level error will not cause the tool to fail.
5595 * ``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.
5596 * ``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.
5597 * ``description``: This is an optional description of the error that corresponds to the exit code.
5598
5599 The following is an example of the ``<exit_code>`` tag:
5600
5601 ```xml
5602 <stdio>
5603 <exit_code range="3:5" level="warning" description="Low disk space" />
5604 <exit_code range="6:" level="fatal" description="Bad input dataset" />
5605 <!-- Catching fatal_oom allows the job runner to potentially resubmit to a resource with more
5606 memory if Galaxy is configured to do this. -->
5607 <exit_code range="2" level="fatal_oom" description="Out of Memory" />
5608 </stdio>
5609 ```
5610
5611 If the tool returns 0 or 1, then the tool will not be marked as having an error.
5612 If the exit code is 2, then the tool will fail with the description ``Out of
5613 Memory`` added to stderr. If the tool returns 3, 4, or 5, then the tool will not
5614 be marked as having failed, but ``Low disk space`` will be added to stderr.
5615 Finally, if the tool returns any number greater than or equal to 6, then the
5616 description ``Bad input dataset`` will be added to stderr and the tool will be
5617 marked as having failed.
5618
5619 ]]></xs:documentation>
5620 </xs:annotation>
5621 <xs:attribute name="range" type="RangeType">
5622 <xs:annotation>
5623 <xs:documentation xml:lang="en"></xs:documentation>
5624 </xs:annotation>
5625 </xs:attribute>
5626 <xs:attribute name="level" type="LevelType">
5627 <xs:annotation>
5628 <xs:documentation xml:lang="en"></xs:documentation>
5629 </xs:annotation>
5630 </xs:attribute>
5631 <xs:attribute name="description" type="xs:string">
5632 <xs:annotation>
5633 <xs:documentation xml:lang="en"></xs:documentation>
5634 </xs:annotation>
5635 </xs:attribute>
5636 </xs:complexType>
5637
5638
5639 <xs:complexType name="Regex">
5640 <xs:annotation>
5641 <xs:documentation xml:lang="en"><![CDATA[
5642 A regular expression defines a pattern of characters. The patterns include the following:
5643
5644 * ``GCTA``, which matches on the fixed string "GCTA";
5645 * ``[abcd]``, which matches on the characters a, b, c, or d;
5646 * ``[CG]{12}``, which matches on 12 consecutive characters that are C or G;
5647 * ``a.*z``, which matches on the character "a", followed by 0 or more characters of any type, followed by a "z";
5648 * ``^X``, which matches the letter X at the beginning of a string;
5649 * ``Y$``, which matches the letter Y at the end of a string.
5650
5651 There are many more possible regular expressions. A reference to all supported
5652 regular expressions can be found under
5653 [Python Regular Expression Syntax](https://docs.python.org/3/library/re.html#regular-expression-syntax).
5654
5655 A regular expression includes the following attributes:
5656
5657 * ``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:
5658 * ``stdout``: the regular expression will be applied to stdout;
5659 * ``stderr``: the regular expression will be applied to stderr;
5660 * ``both``: the regular expression will be applied to both stderr and stdout (which is the default case).
5661 * ``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.
5662 * ``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:
5663 * ``log`` and ``warning``: If the regular expression matches against its source input (i.e., stdout and/or stderr), then a description of the error will be added to the beginning of the source, prepended with either 'Log:' or 'Warning:'. A log-level/warning-level error will not cause the tool to fail.
5664 * ``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.
5665 * ``fatal_oom``: In contrast to fatal the job might be resubmitted if possible according to the job configuration.
5666 * ``description``: Just like its ``exit_code`` counterpart, this is an optional description of the regular expression that has matched.
5667
5668 The following is an example of regular expressions that may be used:
5669
5670 ```xml
5671 <stdio>
5672 <regex match="low space"
5673 source="both"
5674 level="warning"
5675 description="Low space on device" />
5676 <regex match="error"
5677 source="stdout"
5678 level="fatal"
5679 description="Unknown error encountered" />
5680 <!-- Catching fatal_oom allows the job runner to potentially resubmit to a resource with more
5681 memory if Galaxy is configured to do this. -->
5682 <regex match="out of memory"
5683 source="stdout"
5684 level="fatal_oom"
5685 description="Out of memory error occurred" />
5686 <regex match="[CG]{12}"
5687 description="Fatal error - CG island 12 nts long found" />
5688 <regex match="^Branch A"
5689 level="warning"
5690 description="Branch A was taken in execution" />
5691 </stdio>
5692 ```
5693
5694 The regular expression matching proceeds as follows. First, if either stdout or
5695 stderr match on ``low space``, then a warning is registered. If stdout contained
5696 the string ``---LOW SPACE---``, then stdout has the string ``Warning: Low space
5697 on device`` added to its beginning. The same goes for if stderr had contained the
5698 string ``low space``. Since only a warning could have occurred, the processing
5699 continues.
5700
5701 Next, the regular expression ``error`` is matched only against stdout. If stdout
5702 contains the string ``error`` regardless of its capitalization, then a fatal
5703 error has occurred and the processing stops. In that case, stdout would be
5704 prepended with the string ``Fatal: Unknown error encountered``. Note that, if
5705 stderr contained ``error``, ``ERROR``, or ``ErRor`` then it would not matter -
5706 stderr was not being scanned.
5707
5708 If the second regular expression does not match, the regular expression "out of memory"
5709 is checked on stdout. If found, Galaxy tries to resubmit the job with more memory
5710 if configured correctly, otherwise the job fails.
5711
5712 If the previous regular expressions does not match, then the fourth regular
5713 expression is checked. The fourth regular expression does not contain an error
5714 level, so an error level of ``fatal`` is assumed. The fourth regular expression
5715 also does not contain a source, so both stdout and stderr are checked. The fourth
5716 regular expression looks for 12 consecutive "C"s or "G"s in any order and in
5717 uppercase or lowercase. If stdout contained ``cgccGGCCcGGcG`` or stderr
5718 contained ``CCCCCCgggGGG``, then the regular expression would match, the tool
5719 would be marked with a fatal error, and the stream that contained the
5720 12-nucleotide CG island would be prepended with ``Fatal: Fatal error - CG island
5721 12 nts long found``.
5722
5723 Finally, if the tool did not match any of the fatal errors, then the fifth
5724 regular expression is checked. Since no source is specified, both stdout and
5725 stderr are checked. If ``Branch A`` is at the beginning of stdout or stderr, then
5726 a warning will be registered and the source that contained ``Branch A`` will be
5727 prepended with the warning ``Warning: Branch A was taken in execution``.
5728
5729 ]]></xs:documentation>
5730 </xs:annotation>
5731 <xs:attribute name="source" type="SourceType">
5732 <xs:annotation>
5733 <xs:documentation xml:lang="en">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:</xs:documentation>
5734 </xs:annotation>
5735 </xs:attribute>
5736 <xs:attribute name="match" type="xs:string">
5737 <xs:annotation>
5738 <xs:documentation xml:lang="en">This is the regular expression that will be used to match against stdout and/or stderr.</xs:documentation>
5739 </xs:annotation>
5740 </xs:attribute>
5741 <xs:attribute name="level" type="LevelType">
5742 <xs:annotation>
5743 <xs:documentation xml:lang="en">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.</xs:documentation>
5744 </xs:annotation>
5745 </xs:attribute>
5746 <xs:attribute name="description" type="xs:string">
5747 <xs:annotation>
5748 <xs:documentation xml:lang="en">an optional description of the regular expression that has matched.</xs:documentation>
5749 </xs:annotation>
5750 </xs:attribute>
5751 </xs:complexType>
5752
5753 <xs:complexType name="ChangeFormat">
5754 <xs:annotation>
5755 <xs:documentation xml:lang="en"><![CDATA[See
5756 [extract_genomic_dna.xml](https://github.com/galaxyproject/tools-iuc/blob/master/tools/extract_genomic_dna/extract_genomic_dna.xml)
5757 or the test tool
5758 [output_format.xml](https://github.com/galaxyproject/galaxy/blob/dev/test/functional/tools/output_format.xml)
5759 for simple examples of how this tag set is used in a tool. This tag set is
5760 optionally contained within the ``<data>`` tag set and is the container tag set
5761 for the following ``<when>`` tag set.]]></xs:documentation>
5762 </xs:annotation>
5763 <xs:sequence>
5764 <xs:element name="when" type="ChangeFormatWhen" maxOccurs="unbounded"/>
5765 </xs:sequence>
5766 </xs:complexType>
5767 <xs:complexType name="ChangeFormatWhen">
5768 <xs:annotation>
5769 <xs:documentation xml:lang="en"><![CDATA[
5770
5771 If the data type of the output dataset is the specified type, the data type is
5772 changed to the desired type.
5773
5774 ### Examples
5775
5776 Assume that your tool config includes the following select list parameter
5777 structure:
5778
5779 ```xml
5780 <param name="out_format" type="select" label="Output data type">
5781 <option value="fasta">FASTA</option>
5782 <option value="interval">Interval</option>
5783 </param>
5784 ```
5785
5786 Then whenever the user selects the ``interval`` option from the select list, the
5787 following structure in your tool config will override the ``format="fasta"`` setting
5788 in the ``<data>`` tag set with ``format="interval"``.
5789
5790 ```xml
5791 <outputs>
5792 <data format="fasta" name="out_file1">
5793 <change_format>
5794 <when input="out_format" value="interval" format="interval" />
5795 </change_format>
5796 </data>
5797 </outputs>
5798 ```
5799
5800 See
5801 [extract_genomic_dna.xml](https://github.com/galaxyproject/tools-iuc/blob/master/tools/extract_genomic_dna/extract_genomic_dna.xml)
5802 or the test tool
5803 [output_format.xml](https://github.com/galaxyproject/galaxy/blob/dev/test/functional/tools/output_format.xml)
5804 for more examples.
5805
5806 ]]></xs:documentation>
5807 </xs:annotation>
5808 <xs:sequence/>
5809 <xs:attribute name="input" type="xs:string">
5810 <xs:annotation>
5811 <xs:documentation xml:lang="en">This attribute should be the name of
5812 the desired input parameter (e.g. ``input="out_format"`` above).</xs:documentation>
5813 </xs:annotation>
5814 </xs:attribute>
5815 <xs:attribute name="value" type="xs:string" use="required">
5816 <xs:annotation>
5817 <xs:documentation xml:lang="en">This must be a possible value of the ``input``
5818 parameter (e.g. ``value="interval"`` above), or of the deprecated ``input_dataset``'s
5819 attribute.</xs:documentation>
5820 </xs:annotation>
5821 </xs:attribute>
5822 <xs:attribute name="format" type="xs:string" use="required">
5823 <xs:annotation>
5824 <xs:documentation xml:lang="en">This value must be a supported data type
5825 (e.g. ``format="interval"``). See
5826 [/config/datatypes_conf.xml.sample](https://github.com/galaxyproject/galaxy/blob/dev/config/datatypes_conf.xml.sample)
5827 for a list of supported formats.</xs:documentation>
5828 </xs:annotation>
5829 </xs:attribute>
5830 <xs:attribute name="input_dataset" type="xs:string" gxdocs:deprecated="true">
5831 <xs:annotation>
5832 <xs:documentation xml:lang="en">*Deprecated*.</xs:documentation>
5833 </xs:annotation>
5834 </xs:attribute>
5835 <xs:attribute name="attribute" type="xs:string" gxdocs:deprecated="true">
5836 <xs:annotation>
5837 <xs:documentation xml:lang="en">*Deprecated*.</xs:documentation>
5838 </xs:annotation>
5839 </xs:attribute>
5840 </xs:complexType>
5841
5842 <xs:complexType name="Citations">
5843 <xs:annotation>
5844 <xs:documentation xml:lang="en"><![CDATA[Tool files may declare one
5845 citations element. Each citations element can contain one or more citation tag
5846 elements - each of which specifies tool citation information using either a DOI
5847 or a BibTeX entry.
5848
5849 These citations will appear at the bottom of the tool form in a formatted way
5850 but the user will have to option to select RAW BibTeX for copying and pasting as
5851 well. Likewise, the history menu includes an option allowing users to aggregate
5852 all such citations across an analysis in a list of citations.
5853
5854 BibTeX entries for citations annotated with DOIs will be fetched by Galaxy from
5855 https://doi.org/ and cached.
5856
5857 ```xml
5858 <citations>
5859 <!-- Example of annotating a citation using a DOI. -->
5860 <citation type="doi">10.1093/bioinformatics/btq281</citation>
5861
5862 <!-- Example of annotating a citation using a BibTex entry. -->
5863 <citation type="bibtex">@ARTICLE{Kim07aninterior-point,
5864 author = {Seung-jean Kim and Kwangmoo Koh and Michael Lustig and Stephen Boyd and Dimitry Gorinevsky},
5865 title = {An interior-point method for large-scale l1-regularized logistic regression},
5866 journal = {Journal of Machine Learning Research},
5867 year = {2007},
5868 volume = {8},
5869 pages = {1519-1555}
5870 }</citation>
5871 </citations>
5872 ```
5873
5874 For more implementation information see the
5875 [pull request](https://bitbucket.org/galaxy/galaxy-central/pull-requests/440/initial-bibtex-doi-citation-support-in/diff)
5876 adding this feature. For more examples of how to add this to tools checkout the
5877 following commits adding this to the
5878 [NCBI BLAST+ suite](https://github.com/peterjc/galaxy_blast/commit/9d2e3906915895765ecc3f48421b91fabf2ccd8b),
5879 [phenotype association tools](https://bitbucket.org/galaxy/galaxy-central/commits/39c983151fe328ff5d415f6da81ce5b21a7e18a4),
5880 [MAF suite](https://bitbucket.org/galaxy/galaxy-central/commits/60f63d6d4cb7b73286f3c747e8acaa475e4b6fa8),
5881 and [MACS2 suite](https://github.com/jmchilton/galaxytools/commit/184971dea73e236f11e82b77adb5cab615b8391b).
5882
5883 This feature was added to the August 2014 release of Galaxy, tools annotated
5884 with citations will work in older releases of Galaxy but no citation information
5885 will be available to the end user.
5886 ]]></xs:documentation>
5887 </xs:annotation>
5888 <xs:sequence>
5889 <xs:element name="citation" type="Citation" minOccurs="0" maxOccurs="unbounded"/>
5890 </xs:sequence>
5891 </xs:complexType>
5892
5893 <xs:complexType name="Citation">
5894 <xs:annotation>
5895 <xs:documentation xml:lang="en">Each citations element can contain one or
5896 more ``citation`` tag elements - each of which specifies tool citation
5897 information using either a DOI or a BibTeX entry.</xs:documentation>
5898 </xs:annotation>
5899 <xs:simpleContent>
5900 <xs:extension base="xs:string">
5901 <xs:attribute name="type" type="CitationType" use="required">
5902 <xs:annotation>
5903 <xs:documentation xml:lang="en">Type of citation - currently ``doi``
5904 and ``bibtex`` are the only supported options.</xs:documentation>
5905 </xs:annotation>
5906 </xs:attribute>
5907 </xs:extension>
5908 </xs:simpleContent>
5909 </xs:complexType>
5910
5911 <xs:simpleType name="CitationType">
5912 <xs:annotation>
5913 <xs:documentation xml:lang="en">Type of citation represented.</xs:documentation>
5914 </xs:annotation>
5915 <xs:restriction base="xs:string">
5916 <xs:enumeration value="bibtex"/>
5917 <xs:enumeration value="doi"/>
5918 </xs:restriction>
5919 </xs:simpleType>
5920
5921 <xs:simpleType name="RequirementType">
5922 <xs:annotation>
5923 <xs:documentation xml:lang="en">Documentation for RequirementType</xs:documentation>
5924 </xs:annotation>
5925 <xs:restriction base="xs:string">
5926 <xs:enumeration value="python-module"/>
5927 <xs:enumeration value="binary"/>
5928 <xs:enumeration value="package"/>
5929 <xs:enumeration value="set_environment"/>
5930 </xs:restriction>
5931 </xs:simpleType>
5932 <xs:simpleType name="ContainerType">
5933 <xs:annotation>
5934 <xs:documentation xml:lang="en">Type of container for tool execution.</xs:documentation>
5935 </xs:annotation>
5936 <xs:restriction base="xs:string">
5937 <xs:enumeration value="docker"/>
5938 <xs:enumeration value="singularity"/>
5939 </xs:restriction>
5940 </xs:simpleType>
5941 <xs:simpleType name="ToolTypeType">
5942 <xs:annotation>
5943 <xs:documentation xml:lang="en">Documentation for ToolTypeType</xs:documentation>
5944 </xs:annotation>
5945 <xs:restriction base="xs:string">
5946 <xs:enumeration value="data_source"/>
5947 <xs:enumeration value="manage_data"/>
5948 <xs:enumeration value="interactive"/>
5949 <xs:enumeration value="expression"/>
5950 </xs:restriction>
5951 </xs:simpleType>
5952 <xs:simpleType name="URLmethodType">
5953 <xs:annotation>
5954 <xs:documentation xml:lang="en">Documentation for URLmethodType</xs:documentation>
5955 </xs:annotation>
5956 <xs:restriction base="xs:string">
5957 <xs:enumeration value="get"/>
5958 <xs:enumeration value="post"/>
5959 </xs:restriction>
5960 </xs:simpleType>
5961 <xs:simpleType name="TargetType">
5962 <xs:annotation>
5963 <xs:documentation xml:lang="en">Documentation for TargetType</xs:documentation>
5964 </xs:annotation>
5965 <xs:restriction base="xs:string">
5966 <xs:enumeration value="_top"/>
5967 <xs:enumeration value="_parent"/>
5968 </xs:restriction>
5969 </xs:simpleType>
5970 <xs:simpleType name="MethodType">
5971 <xs:annotation>
5972 <xs:documentation xml:lang="en">Documentation for MethodType</xs:documentation>
5973 </xs:annotation>
5974 <xs:restriction base="xs:string">
5975 <xs:enumeration value="basic"/>
5976 <xs:enumeration value="multi"/>
5977 </xs:restriction>
5978 </xs:simpleType>
5979 <xs:simpleType name="DisplayType">
5980 <xs:annotation>
5981 <xs:documentation xml:lang="en">Documentation for DisplayType</xs:documentation>
5982 </xs:annotation>
5983 <xs:restriction base="xs:string">
5984 <xs:enumeration value="checkboxes"/>
5985 <xs:enumeration value="radio"/>
5986 </xs:restriction>
5987 </xs:simpleType>
5988 <xs:simpleType name="HierarchyType">
5989 <xs:annotation>
5990 <xs:documentation xml:lang="en">Documentation for HierarchyType</xs:documentation>
5991 </xs:annotation>
5992 <xs:restriction base="xs:string">
5993 <xs:enumeration value="exact"/>
5994 <xs:enumeration value="recurse"/>
5995 </xs:restriction>
5996 </xs:simpleType>
5997 <xs:simpleType name="ValidatorType">
5998 <xs:annotation>
5999 <xs:documentation xml:lang="en">Documentation for ValidatorType</xs:documentation>
6000 </xs:annotation>
6001 <xs:restriction base="xs:string">
6002 <xs:enumeration value="empty_dataset"/>
6003 <xs:enumeration value="empty_extra_files_path"/>
6004 <xs:enumeration value="expression"/>
6005 <xs:enumeration value="regex"/>
6006 <xs:enumeration value="in_range"/>
6007 <xs:enumeration value="length"/>
6008 <xs:enumeration value="metadata"/>
6009 <xs:enumeration value="unspecified_build"/>
6010 <xs:enumeration value="no_options"/>
6011 <xs:enumeration value="empty_field"/>
6012 <xs:enumeration value="dataset_metadata_in_file"/>
6013 <xs:enumeration value="dataset_metadata_in_data_table"/>
6014 <xs:enumeration value="dataset_metadata_not_in_data_table"/>
6015 <xs:enumeration value="value_in_data_table"/>
6016 <xs:enumeration value="value_not_in_data_table"/>
6017 <xs:enumeration value="dataset_metadata_in_range"/>
6018 <xs:enumeration value="dataset_ok_validator"/>
6019 </xs:restriction>
6020 </xs:simpleType>
6021 <xs:simpleType name="FilterType">
6022 <xs:annotation>
6023 <xs:documentation xml:lang="en"></xs:documentation>
6024 </xs:annotation>
6025 <xs:restriction base="xs:string">
6026 <xs:enumeration value="data_meta"/>
6027 <xs:enumeration value="param_value"/>
6028 <xs:enumeration value="static_value"/>
6029 <xs:enumeration value="regexp"/>
6030 <xs:enumeration value="unique_value"/>
6031 <xs:enumeration value="multiple_splitter"/>
6032 <xs:enumeration value="add_value"/>
6033 <xs:enumeration value="remove_value"/>
6034 <xs:enumeration value="sort_by"/>
6035 </xs:restriction>
6036 </xs:simpleType>
6037 <xs:simpleType name="ActionsConditionalFilterType">
6038 <xs:annotation>
6039 <xs:documentation xml:lang="en"></xs:documentation>
6040 </xs:annotation>
6041 <xs:restriction base="xs:string">
6042 <xs:enumeration value="param_value"/>
6043 <xs:enumeration value="insert_column"/>
6044 <xs:enumeration value="column_strip"/>
6045 <xs:enumeration value="multiple_splitter"/>
6046 <xs:enumeration value="column_replace"/>
6047 <xs:enumeration value="metadata_value"/>
6048 <xs:enumeration value="boolean"/>
6049 <xs:enumeration value="string_function"/>
6050 </xs:restriction>
6051 </xs:simpleType>
6052 <xs:simpleType name="ActionType">
6053 <xs:annotation>
6054 <xs:documentation xml:lang="en">Documentation for ActionType</xs:documentation>
6055 </xs:annotation>
6056 <xs:restriction base="xs:string">
6057 <xs:enumeration value="format"/>
6058 <xs:enumeration value="metadata"/>
6059 </xs:restriction>
6060 </xs:simpleType>
6061 <xs:simpleType name="ActionsOptionType">
6062 <xs:annotation>
6063 <xs:documentation xml:lang="en">Documentation for ActionsOptionType</xs:documentation>
6064 </xs:annotation>
6065 <xs:restriction base="xs:string">
6066 <xs:enumeration value="from_data_table"/>
6067 <xs:enumeration value="from_param"/>
6068 <xs:enumeration value="from_file"/>
6069 </xs:restriction>
6070 </xs:simpleType>
6071 <xs:simpleType name="CompareType">
6072 <xs:annotation>
6073 <xs:documentation xml:lang="en">Documentation for CompareType</xs:documentation>
6074 </xs:annotation>
6075 <xs:restriction base="xs:string">
6076 <xs:enumeration value="startswith"/>
6077 <xs:enumeration value="re_search"/>
6078 </xs:restriction>
6079 </xs:simpleType>
6080 <xs:simpleType name="LevelType">
6081 <xs:annotation>
6082 <xs:documentation xml:lang="en">Documentation for LevelType</xs:documentation>
6083 </xs:annotation>
6084 <xs:restriction base="xs:string">
6085 <xs:enumeration value="fatal_oom"/>
6086 <xs:enumeration value="fatal"/>
6087 <xs:enumeration value="warning"/>
6088 <xs:enumeration value="log"/>
6089 <xs:enumeration value="qc"/>
6090 </xs:restriction>
6091 </xs:simpleType>
6092 <xs:simpleType name="RangeType">
6093 <xs:annotation>
6094 <xs:documentation xml:lang="en">Documentation for RangeType</xs:documentation>
6095 </xs:annotation>
6096 <xs:restriction base="xs:string">
6097 <xs:pattern value="\-?(\d)*:?\-?(\d)*"/>
6098 </xs:restriction>
6099 </xs:simpleType>
6100 <xs:simpleType name="SourceType">
6101 <xs:annotation>
6102 <xs:documentation xml:lang="en">Documentation for SourceType</xs:documentation>
6103 </xs:annotation>
6104 <xs:restriction base="xs:string">
6105 <xs:enumeration value="stdout"/>
6106 <xs:enumeration value="stderr"/>
6107 <xs:enumeration value="both"/>
6108 </xs:restriction>
6109 </xs:simpleType>
6110 <xs:simpleType name="TestOutputCompareType">
6111 <xs:annotation>
6112 <xs:documentation xml:lang="en">Type of comparison to use when comparing
6113 test generated output files to expected output files. Currently valid value are
6114 ``diff`` (the default), ``re_match``, ``sim_size``, ``re_match_multiline``,
6115 and ``contains``.</xs:documentation>
6116 </xs:annotation>
6117 <xs:restriction base="xs:string">
6118 <xs:enumeration value="diff"/>
6119 <xs:enumeration value="re_match"/>
6120 <xs:enumeration value="sim_size"/>
6121 <xs:enumeration value="re_match_multiline"/>
6122 <xs:enumeration value="contains"/>
6123 </xs:restriction>
6124 </xs:simpleType>
6125 <xs:simpleType name="PermissiveBoolean">
6126 <xs:annotation>
6127 <xs:documentation xml:lang="en">Documentation for PermissiveBoolean</xs:documentation>
6128 </xs:annotation>
6129 <xs:restriction base="xs:string">
6130 <xs:enumeration value="0"/>
6131 <xs:enumeration value="1"/>
6132 <xs:enumeration value="true"/>
6133 <xs:enumeration value="false"/>
6134 <xs:enumeration value="True"/>
6135 <xs:enumeration value="False"/>
6136 <xs:enumeration value="yes"/>
6137 <xs:enumeration value="no"/>
6138 </xs:restriction>
6139 </xs:simpleType>
6140 <xs:complexType name="EdamTopics">
6141 <xs:annotation>
6142 <xs:documentation xml:lang="en"><![CDATA[
6143 Container tag set for the ``<edam_topic>`` tags.
6144 A tool can have any number of EDAM topic references.
6145
6146 ```xml
6147 <!-- Example: this tool is about 'Statistics and probability' (http://edamontology.org/topic_2269) -->
6148 <edam_topics>
6149 <edam_topic>topic_2269</edam_topic>
6150 </edam_topics>
6151 ```
6152 ]]></xs:documentation>
6153 </xs:annotation>
6154 <xs:sequence>
6155 <xs:element name="edam_topic" minOccurs="0" maxOccurs="unbounded">
6156 <xs:simpleType>
6157 <xs:restriction base="xs:string">
6158 <xs:pattern value="topic_[0-9]{4}"></xs:pattern>
6159 </xs:restriction>
6160 </xs:simpleType>
6161 </xs:element>
6162 </xs:sequence>
6163 </xs:complexType>
6164 <xs:complexType name="EdamOperations">
6165 <xs:annotation>
6166 <xs:documentation xml:lang="en"><![CDATA[
6167 Container tag set for the ``<edam_operation>`` tags.
6168 A tool can have any number of EDAM operation references.
6169
6170 ```xml
6171 <!-- Example: this tool performs a 'Conversion' operation (http://edamontology.org/operation_3434) -->
6172 <edam_operations>
6173 <edam_operation>operation_3434</edam_operation>
6174 </edam_operations>
6175 ```
6176
6177 ]]></xs:documentation>
6178 </xs:annotation>
6179 <xs:sequence>
6180 <xs:element name="edam_operation" minOccurs="0" maxOccurs="unbounded">
6181 <xs:simpleType>
6182 <xs:restriction base="xs:string">
6183 <xs:pattern value="operation_[0-9]{4}"></xs:pattern>
6184 </xs:restriction>
6185 </xs:simpleType>
6186 </xs:element>
6187 </xs:sequence>
6188 </xs:complexType>
6189 <xs:complexType name="xrefs">
6190 <xs:annotation>
6191 <xs:documentation xml:lang="en"><![CDATA[
6192 Container tag set for the ``<xref>`` tags.
6193 A tool can refer multiple reference IDs.
6194
6195 ```xml
6196 <!-- Example: this tool is seqtk -->
6197 <xrefs>
6198 <xref type="bio.tools">seqtk</xref>
6199 </xrefs>
6200 <!-- https://bio.tools/seqtk -->
6201 ```
6202
6203 ]]></xs:documentation>
6204 </xs:annotation>
6205 <xs:sequence>
6206 <xs:element name="xref" type="xref" minOccurs="0" maxOccurs="unbounded">
6207 </xs:element>
6208 </xs:sequence>
6209 </xs:complexType>
6210 <xs:complexType name="xref">
6211 <xs:annotation>
6212 <xs:documentation xml:lang="en">The ``xref`` element specifies reference
6213 information according to a catalog.</xs:documentation>
6214 </xs:annotation>
6215 <xs:simpleContent>
6216 <xs:extension base="xs:string">
6217 <xs:attribute name="type" type="xrefType" use="required">
6218 <xs:annotation>
6219 <xs:documentation xml:lang="en">Type of reference - currently ``bio.tools``
6220 is the only supported options.</xs:documentation>
6221 </xs:annotation>
6222 </xs:attribute>
6223 </xs:extension>
6224 </xs:simpleContent>
6225 </xs:complexType>
6226 <xs:simpleType name="xrefType">
6227 <xs:annotation>
6228 <xs:documentation xml:lang="en">Type of Reference.</xs:documentation>
6229 </xs:annotation>
6230 <xs:restriction base="xs:string">
6231 <xs:enumeration value="bio.tools"/>
6232 <!--xs:enumeration value="whatelse"/-->
6233 </xs:restriction>
6234 </xs:simpleType>
6235
6236 <xs:simpleType name="MacroImportType">
6237 <xs:restriction base="xs:string">
6238 <xs:pattern value="[a-zA-Z0-9_\-\.]+.xml"/>
6239 </xs:restriction>
6240 </xs:simpleType>
6241
6242 <xs:simpleType name="DetectErrorType">
6243 <xs:restriction base="xs:string">
6244 <xs:enumeration value="default"/>
6245 <xs:enumeration value="exit_code"/>
6246 <xs:enumeration value="aggressive"/>
6247 </xs:restriction>
6248 </xs:simpleType>
6249
6250 </xs:schema>