General Tool Information

📘

This page contains procedures related to the legacy editor. Try out our new editor that has a more streamlined design and provides a better app editing experience. More info.

🚧

On this page:

[1. Docker container](#docker con)

• [Image ID:](#image id)
• [Docker Repository: Required field](#docker rep)

2. Resources

• CPU:
• Memory:

[3. Create files](#create files)

• [File name:](#file name)
• [File content:](#file con)

4. Command

• Base command: Required field
• Stdin:
• Stdout:
• Success Codes and Temporary Fail Codes:

5. Argument

• Prefix:
• Value:
• [Separate prefix with:](#sep pref)
• Position:

The General information tab contains the following fields.

1. Docker Container

Image ID:

Please leave this blank.

Docker Repository: Required field

The location of the Docker image containing the tool.
If the image is stored in the CGC image registry, the location format is as follows: cgc-images.sbgenomics.com/<username>/<repository_name>[:tag].

Alternatively, if the image is in Docker Hub you can enter its path here as <Docker_repository><:tag>. This means that if you don't enter the prefix cgc-images.sbgenomics.com, the tool editor will search for the image in Docker Hub.

👍

One subcommand = one tool

For the purposes of tool descriptions, each subcommand of an executable is treated as a distinct tool. In other words, tools on the Platform have unique base commands.

For example, sort and view are different subcommands of samtools. So, you would need to create distinct tool descriptions for samtools sort and samtools view. But, each tool description may reference the same Docker image, which contains the tool samtools.

2. Resources

CPU:

Here, you can specify the number of CPUs required for the tool's execution.

Memory:

Here, you can specify the memory resources required for the tool's execution.

Note that the number of CPUs and amount of memory actually allocated to the tool may be greater than the number they strictly require. While the required resources, as stipulated on this tab of the tool editor, are fixed, the resources allocated to the tool will depend on the hardware on which the tool is executed, and may vary during the execution. You can inspect the values for the resources allocated to a tool during a given execution, and can express other aspects of the tool's behavior as a function of these values. This is done using the $job variable.

For more details, see the note on allocatedResources. For information on the $jobvariable, see the page on dynamic expressions in tool descriptions.

3. Create Files

Use this section to specify files that must be created in the working directory of the job before the tool is executed. For example, you might need to have a config file in the tool's working directory.

File name:

This field specifies the name of the file you want to create.

File content:

This field specifies the content that you want written to the file. You can just paste it here.

If using an expression to generate file content, make sure to enter it in the expression input window by clicking </> next to the field. Also, please note that the value returned by the expression must be a string in order to be written as file content.

👍

If you want to run a simple script, you can paste it into the File Content field instead of installing it in a Docker container. For example, to run my-script.py enter my-script.py in the File Name field, and enter the full python script in File Content. Then, you can just enter a base image from Docker Hub into the Docker Repository field that comes with python, such as Ubuntu, rather then an image on which my-script.py has been installed.

👍

How to use dynamic expressions in the Create Files fields

See the section on Describing Index Files in Advanced Features for an example of how to use dynamic expressions in the Create Files field.

4. Command

Base command: Required field

Enter the executable name for the command. If you are describing a tool with multiple subcommands you must also enter the subcommand you are describing.

👍

See the section on terminology on the page The Tool Editor for examples of base commands.

Stdin:

If you want to pipe data into standard input for the tool, enter the name of the file containing the data here.

Stdout:

Here, enter the name of a file to which you want to save any output written by your tool. This allows you to capture, as a file, the output of a tool that would normally be displayed on standard out. For instance, if you were running grep you could save its results in a file named found_string.txt.

Success Codes and Temporary Fail Codes:

If your tool outputs a code after each execution to indicate whether it should be considered a success or failure, then enter these in the respective fields. These codes will be used to determine a displayed status of the tool's execution on the CGC. Typically, the exit status code 0 indicates success and 1 indicates failure. For example, grep will exit with status code 1 if no lines can be found that match the pattern supplied. If you don't enter status codes here, then by default, if your tool gives an exit status of 0, this will be taken to indicate success and any other exit status will be taken to indicate failure.

5. Arguments

Here you can enter the format of your tool's command line options and the option arguments that they take. Clicking the plus button + brings up the following pop-up window. Its fields are described in turn below. Following this is an example of how to use the fields.

Note that this section of the tool editor lets you enter arguments that will be fixed every time you run the tool: their values are 'hard coded' into the tool's description.

On the other hand, if you want to enter the value of an argument whenever you run the tool, you should describe that argument on the Input tab of the tool description. In this case, the value of the argument will be treated as an input to the tool – either supplied as a parameter or as a file.

👍

See the section on terminology for examples of a tool's Value and Prefix.

Prefix:

This parameter typically refers to a command option that the base command can take (for example -l or +x). See the section on terminology for full details.

Value:

This parameter refers to the fixed or dynamic expression passed in as the option argument for the option given in Prefix.

• If the Value field is left empty, you can pass in a value as the option argument for each execution of the tool.
• If the Value field contains a fixed value (such as an integer, string, etc) then it will be passed as the value of the option argument for every execution.
• Alternatively, the Value field can take a dynamic value, which is a JavaScript expression involving variables that refer to features of the execution. This will set the value to be a function of those variable features at runtime. See the page on dynamic expressions in tool descriptions for an example of this in action.

Separate prefix with:

This field allows you to specify the character that separates the prefix from its value: it can be either a space, or the empty string (in the case that no character separates prefix from the value). Note that if your command requires a separator other than space or the empty string, such as '=', you can enter this directly after the prefix and set the separator to the empty string.

Position:

This refers to the position of the prefix and its value on the command line relative to the base command. For example, '1' indicates that the prefix should be entered first, immediately after the base command. If you just want to ensure that a certain prefix comes last on the command, just set this to be some large integer, like 99.

👍

Example of using the Add Arguments field

The command line tool grep, which searches for patterns, can take the option -C. This option takes option arguments which refer to the number of lines of context (text) around the pattern searched for to display along with each search result. For example, to display the 3 lines of text surrounding every found occurrence of our pattern, we would set -C 3 after grep on the command line.

If we were describing grep in the CGC Tool Editor, and wanted to be able to set the number of lines of context at each execution, we would enter the following:
Base command: grep
Arguments:
Value: leave empty
Prefix: -C
Separate prefix with: space
Position: 1