Tool Output Ports
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.
This page contains information on how to use the fields of the Outputs tab on the Tool Editor.
On this page:
The Outputs tab allows you to describe the output ports of your tool. As described on the Inputs port page, a port is a 'gateway' for data to flow in and out of your tool. You should add one output port per datatype your tool produces as output and per method of processing. For instance, if your tool produces two files, produced in different ways, then you should also enter two ports.
Add an output port to the tool description
To start describing an output port, go to the tab labeled Outputs.
Clicking the + button will bring up a pop-out window in which you can specify an output port.
Basic Information
Required:
The required checkbox for has no function for outputs.
ID: Required
Each port is assigned an ID, which it will be labeled with in the workflow editor.
Type: Required
Specify the data structure that the port outputs: either a file or an array.
Glob: In this field you can enter a pattern, called a 'glob', that the tool outputs should match. This could be a string, such a a file extension, or a more complicated pattern. The globbing (pattern-matching) allows the CGC to categorize the tool outputs appropriately. To read more, see the documentation on globbing. Note that the glob will only match files from the working directory, without recursively searching through any subdirectories.
Additional Information
The fields in this section do not affect the functioning of your tool. Information entered into these fields is just for your own labelling purposes, where the tool appears in graphical interfaces.
Label:
Enter a word or phrase that will be used to label the tool in in the workflow editor.
Description:
Enter a brief description of your tool's behavior. This will also be used to label the tool in in the workflow editor.
File Types:
If your tool outputs files, enter a comma-separated list of file types here that you expect the tool to produce.
Metadata
If your tool outputs files, then in this section you can specify metadata that will annotate the files. Metadata fields and their values are specified as key-value pairs. For example, the key might be quality_scale and the value sanger. For the predefined metadata fields on the CGC, the key needs to be specified in the API format, as shown in the API key column on this page. For example, the library_id API key is used for the field that is labelled Library ID on the CGC.
For information on metadata fields, see the CGC documentation on metadata. For an example of how to annotate output files with metadata dynamically, dependent on the job, see the documentation on dynamic expressions in the tool editor.
Using the field marked Inherit Metadata from Input you can set your tool outputs to inherit metadata from the files inputted to the tool. Do this by selecting an input port of the tool from the dropdown list, as shown:
The rules for assigning metadata from input files to output files are:
- If no input files are provided to the selected port, then no metadata is attached to the output file except for any key-value pairs specified on the Outputs tab.
- If exactly one input file is provided to the selected port, then the output file is assigned all of its metadata. These can then be overridden by the key-value pairs specified.
- If more than one input file is provided to the selected port, then the output file is assigned only the metadata that are identical on all input files. These can then be overridden by the key-value pairs specified.
Load contents
The Load Contents option is a checkbox. When checked, the first 64 KB of the output file produced by the output port will be loaded as the JavaScript object
$self[<index>].contents, where <index> is the index number of the output file whose contents you want to load (e.g. self[0].contents). This allows the initial portion of the file contents to be manipulated in the Output Eval field.
In the context of tool outputs, the Javascript object $self refers to the output object(s), namely a file or an array of files matching the glob. See the documentation on dynamic expressions in tool descriptions for details.
Output Eval
The Output Eval field allows you to enter a JavaScript expression to manipulate the initial 64KB of the file outputted by the tool. This initial portion of the file is loaded as
$self[<index>].contents, where <index> is the index number of the output file whose contents you want to load (e.g. self[0].contents). See the documentation on dynamic expressions in tool descriptions for further details on JavaScript expressions.
Be aware that Output Eval can only be used to manipulate file contents if the Load Contents option is enabled on the same output port. If you haven't checked Load Contents, you will still be able to use JavaScript expressions in Output Eval, but you will not be able to manipulate the content of the tool's output.
Example:
For an example of how Load Contents and Output Eval work, consider the two highlighted tools in the workflow, MixClone RunModel and MixClone PostProcess.
The first tool, MixClone RunModel, has two output ports that are connected to the tool MixClone Postprocess. One of these output ports is #mixclone_model_subclone_number, which outputs a TXT file containing additional information about the files produced by the other output port connected to MixClone Postprocess. We can configure the first output port of MixClone RunModel in order to manipulate the data in the TXT file. In particular, we will extract the necessary information from the TXT file and pass it on to MixClone Postprocess to configure how it handles its input data.
MixClone RunModel assumes five different models of tumor subpopulations by default and determines the suggested model based on its internal criteria. It outputs six files in total:
- An array of five files (one file per model).
- A TXT file containing the string "
Suggested subclone number : <x>", in which<x>is replaced by the number of the suggested model.
The next tool in the workflow, MixClone PostProcess, will only process the output file of MixClone RunModel that was created using the suggested model, even though it receives the array containing all five files. To enable MixClone PostProcess to select only the file produced using the suggested model, MixClone RunModel was configured in the following way:
- An output port for the TXT file was added to MixClone RunModel and the Load Contents option was activated for this output port.
This loads the first 64 KB of the TXT file containing the recommended model number into the $self.contents object, which allows further manipulation of the loaded content.
- The following expression, in terms of
$self.contents, was added to the Output Eval field:
{
if ($self) {
var str = $self[0].contents
var substr = "Suggested subclone number : "
var tmp = str.indexOf(substr)
var solution = str[tmp+substr.length]
return solution
} else {
return ""
}
}
The expression takes $self.contents and evaluates to a string that represents the number of the recommended model (e.g. "4").
When the array of five files is then passed to MixClone PostProcess along with the string that represents the suggested model number, this tool is configured to only use the file whose name contains the number of the suggested model.
Secondary Files
The Secondary Files field is used for tools that output index files as well as data files. For examples and more information on managing index files, see the section on describing index files in Advanced features.
Dynamic expressions in the output port description
In some cases, you'll want to use dynamic expressions to set the values of metadata that annotate the tool's output files. For this, you can enter an expression in the value field using the variable
$self to refer to the path of the file that is caught by the pattern-matching specified in the Glob field. For an example of using dynamic expressions for metadata, see the section on dynamic expressions in tool descriptions.
Updated about 2 years ago