Skip to main content

Tool XML file

The next step is to create an XML file for the tool. You can see examples in our repo or refer to Galaxy documentation for all tool file options.

A tool file consists of five main parts - header, requirements, command, inputs and outputs.

Let us look at the GPSANS tool and dive into some more details.

Tool file header​

Important is to set tool id (we prefix our tool ids with neutrons), and update version number every time you change anything in the sections below.

<tool id="neutrons_gpsans" name="GPSANS"  profile="22.05" version="0.1.0">

Requirements section​

In this section, you just provide a link to the image that should be used for the tool (see previous step on how to build an image)

<requirements>
    <container type="docker">savannah.ornl.gov/ndip/tool-sources/sans-data-reduction/gpsans-reduction:0.1.0</container>
</requirements>

Command section​

Here you provide an actual command to be executed inside the Docker container (including the part which might be in the image ENTRYPOINT, Galaxy ignores entry point when it starts the container). 

    <command detect_errors="exit_code"><![CDATA[
        mkdir reduced &&
        . /app/activate_env.sh &&
        ln -s $user_input /app/user_input.py &&
        ln -s $staff_input /app/staff_input.py &&
        python /app/gpsans.py -i $ipts_number -o reduced >$output 2>&1 ;
    ]]>
    </command>

In our case, we create a folder for output data and make sure input files that were provided as user input ($user_input and $staff_input, see the section below) are located where the software expect them, execute the Python script and redirect stdout and stderr to a Galaxy dataset defined by $output parameter.

tip

see Galaxy docs for more details

Inputs section​

This section defines input parameters that can be used as a command line parameter in commands section. Input can be a file (use data or data_collection_type) or a value (use _boolean, integer, float or text data type)

    <inputs>
        <param name="ipts_number" type="integer" optional="false" value="0" label="IPTS Number"/>
        <param name="user_input" type="data" format="py,txt" optional="false" label="User input"/>
        <param name="staff_input" type="data" format="py,txt" optional="false" label="Staff input"/>
    </inputs>

One can build a quite sophisticated set of input parameters, including conditional inputs, arrays, etc., but try to keep it simple. Otherwise, a tool will be difficult to use. As an alternative, you can make a tool to accept a file with input parameters which a user would then edit manually directly in Galaxy or in an external editor (this is actually what happens in the example above).

tip

see Galaxy docs for more details

Outputs section​

The outputs section defines the outputs of your code that should be captured by Galaxy. As with inputs, outputs will be used as part of the command in commands section.

There are two types of output: data for a single file and collection for a set of files. If your software produces several files with fixed names, you can use data type and capture these single files. If your software produces many files with dynamical names, the best way is to capture the whole folder as a Galaxy dataset collection. You can then pass this collection as input to another tool, download the whole collection, extract a specific dataset, and browse the collection in Galaxy web application.

note

It is important that the type of each file within a collection is known to Galaxy. So, if your folder contains only files with standard extentions (txt, pdf, jpeg, ...), you can use pattern="__designation_and_ext__" as in the example below for output_collection2. Otherwise, you can use pattern="__designation__" with extra parameter format= "binary" (you will not be able to preview the files in this case, though).

    <outputs>
        <collection type="list" name="output_collection1" label="GPSANS output">
            <discover_datasets format= "binary" pattern="__designation__" directory="reduced" />
        </collection>
        <collection type="list" name="output_collection2" label="GPSANS 1D ouptut">
            <discover_datasets pattern="__designation_and_ext__" directory="reduced/1D" />
        </collection>
        <data format="txt" name="output" label="GPSANS console output">
        </data>
    </outputs>

tip

see Galaxy docs for more details and Planemo docs for more advanced cases.