{"_id":"5640bae32b14f70d0039b8cf","project":"55faf11ba62ba1170021a9a7","category":{"_id":"5637e8b2fbe1c50d008cb078","pages":["5637e95797666c0d008656ba","5637ea64ee0ee60d0024ec0e","5637f110daf0840d0011dcd5","563d423e9799fb0d0004779b","5640ba77b9c4dd0d0097c827","5640bad42b14f70d0039b8cd","5640bae32b14f70d0039b8cf","5640bb0ceaede117005c99d8","565f6b770dc99e1900f24c73","56cc9eab8fa8b01b00b81f5a","56ddcb9ab4ac273200457c82"],"__v":11,"project":"55faf11ba62ba1170021a9a7","version":"55faf11ba62ba1170021a9aa","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-11-02T22:50:26.865Z","from_sync":false,"order":15,"slug":"describe-your-tool","title":"DESCRIBE YOUR TOOL"},"version":{"_id":"55faf11ba62ba1170021a9aa","project":"55faf11ba62ba1170021a9a7","__v":37,"createdAt":"2015-09-17T16:58:03.490Z","releaseDate":"2015-09-17T16:58:03.490Z","categories":["55faf11ca62ba1170021a9ab","55faf8f4d0e22017005b8272","55faf91aa62ba1170021a9b5","55faf929a8a7770d00c2c0bd","55faf932a8a7770d00c2c0bf","55faf94b17b9d00d00969f47","55faf958d0e22017005b8274","55faf95fa8a7770d00c2c0c0","55faf96917b9d00d00969f48","55faf970a8a7770d00c2c0c1","55faf98c825d5f19001fa3a6","55faf99aa62ba1170021a9b8","55faf99fa62ba1170021a9b9","55faf9aa17b9d00d00969f49","55faf9b6a8a7770d00c2c0c3","55faf9bda62ba1170021a9ba","5604570090ee490d00440551","5637e8b2fbe1c50d008cb078","5649bb624fa1460d00780add","5671974d1b6b730d008b4823","5671979d60c8e70d006c9760","568e8eef70ca1f0d0035808e","56d0a2081ecc471500f1795e","56d4a0adde40c70b00823ea3","56d96b03dd90610b00270849","56fbb83d8f21c817002af880","573c811bee2b3b2200422be1","576bc92afb62dd20001cda85","5771811e27a5c20e00030dcd","5785191af3a10c0e009b75b0","57bdf84d5d48411900cd8dc0","57ff5c5dc135231700aed806","5804caf792398f0f00e77521","58458b4fba4f1c0f009692bb","586d3c287c6b5b2300c05055","58ef66d88646742f009a0216","58f5d52d7891630f00fe4e77"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"__v":40,"user":"554340dfb7f4540d00fcef1d","parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-11-09T15:25:23.817Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":4,"body":"This page contains information on how to use the fields of the Outputs tab on the Tool Editor. \n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"On this page:\",\n  \"body\": \"* [Add an output port to the tool description](#add)\\n* [Basic information](#basic)\\n* [Additional information](#additional)\\n* [Metadata](#metadata)\\n* [Load contents](#load)\\n* [Output eval](#output)\\n* [Secondary files](#secondary)\\n* [Dynamic expressions in the output port description](#dynamic)\"\n}\n[/block]\nThe Outputs tab allows you to describe the output ports of your tool. As described on the [Inputs port page](doc:tool-input-ports), 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.\n\n<a name=\"add\"></a><h2>Add an output port to the tool description</h2>\nTo start describing an output port, go to the tab labeled **Outputs**.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/yppTL6hKREWTy9HO0xIa_*.1-2.png\",\n        \"*.1-2.png\",\n        \"3196\",\n        \"624\",\n        \"#324a61\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nClicking the **+** button will bring up a pop-out window in which you can specify an **output** port. \n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/EsGOoAoFRmpq5jVy4nXa_to1.png\",\n        \"to1.png\",\n        \"1786\",\n        \"1610\",\n        \"#d85554\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n<div align=\"right\"><a href=\"#top\">top</a></div>\n\n<a name=\"basic\"></a><h2>Basic Information </h2>\n**ID**: <span style=\"color:red\"><b><i>Required</i></b></span> \nEach port is assigned an **ID**, which it will be labeled with in the workflow editor.\n\n**Type**: <span style=\"color:red\"><b><i>Required</i></b></span> \nSpecify the data structure that the port outputs: either a file or an array.\n\n<a name=\"glob\"></a>**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](page:glob). Note that the glob will only match files from the working directory, without recursively searching through any subdirectories.\n\n<div align=\"right\"><a href=\"#top\">top</a></div>\n\n<a name=\"additional\"></a><h2>Additional Information</h2>\nThe 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.\n\n**Label**: \nEnter a word or phrase that will be used to label the tool in in the workflow editor.\n\n**Description**: \nEnter a brief description of your tool's behavior. This will also be used to label the tool in in the workflow editor.\n\n**File Types**: \nIf your tool outputs files, enter a comma-separated list of file types here that you expect the tool to produce.\n\n<div align=\"right\"><a href=\"#top\">top</a></div>\n\n<a name=\"metadata\"></a><h2>Metadata</h2>\nIf 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](doc:metadata-on-the-seven-bridges-platform). For example, the **library_id** API key is used for the field that is labelled **Library ID** on the CGC.\n\nFor information on metadata fields, see the [CGC documentation on metadata](doc:metadata-for-private-data). 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.\nUsing 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:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/9Lv0B6ywRRm9GTjWaEwG_*:1103.png\",\n        \"*:1103.png\",\n        \"1010\",\n        \"230\",\n        \"#be9060\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nThe rules for assigning metadata from input files to output files are:\n  * 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.\n  * 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.\n  * 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.\n\n<div align=\"right\"><a href=\"#top\">top</a></div>\n\n<a name=\"load\"></a><h2>Load contents</h2>\nThe **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.\n\nIn 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](page:glob). See the documentation on [dynamic expressions in tool descriptions](doc:dynamic-expressions-in-tool-descriptions) for details.\n\n<div align=\"right\"><a href=\"#top\">top</a></div>\n\n<a name=\"output\"></a><h2>Output Eval</h2>\nThe **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](doc:dynamic-expressions-in-tool-descriptions) for further details on JavaScript expressions.\n\nBe 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.\n\n**Example:**\nFor an example of how **Load Contents** and **Output Eval** work, consider the two highlighted tools in the workflow, **MixClone RunModel** and **MixClone PostProcess**.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/1bb54a6-load-contents-1.jpeg\",\n        \"load-contents-1.jpeg\",\n        775,\n        554,\n        \"#2e5377\"\n      ]\n    }\n  ]\n}\n[/block]\nThe 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.\n\n**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:\n* An array of five files (one file per model).\n* A TXT file containing the string \"`Suggested subclone number :  <x>`\", in which `<x>` is replaced by the number of the suggested model.\n\nThe 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:\n\n1. An output port for the TXT file was added to **MixClone RunModel** and the **Load Contents** option was activated for this output port.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/34fd55b-load-contents-2.jpeg\",\n        \"load-contents-2.jpeg\",\n        940,\n        583,\n        \"#e5e6e5\"\n      ]\n    }\n  ]\n}\n[/block]\nThis 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.\n\n2. The following expression, in terms of `$self.contents`, was added to the **Output Eval** field:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  if ($self) {\\n  var str = $self[0].contents\\n  var substr = \\\"Suggested subclone number : \\\"\\n  var tmp = str.indexOf(substr)\\n  var solution = str[tmp+substr.length]\\n  return solution\\n  } else {\\n  return \\\"\\\"\\n  }\\n}\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nThe expression takes `$self.contents` and evaluates to a string that represents the number of the recommended model (e.g. \"4\").\n\nWhen 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.\n\n<div align=\"right\"><a href=\"#top\">top</a></div>\n\n<a name=\"secondary\"></a><h2>Secondary Files</h2>\nThe 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](doc:advanced-features-of-the-tool-editor).\n\n<div align=\"right\"><a href=\"#top\">top</a></div>\n\n<a name=\"dynamic\"></a><h2>Dynamic expressions in the output port description</h2>\nIn 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](doc:dynamic-expressions-in-tool-descriptions).\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/Cjl7fopiSASdMmDcoKwy_to2.png\",\n        \"to2.png\",\n        \"1762\",\n        \"1580\",\n        \"#49616f\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n<div align=\"right\"><a href=\"#top\">top</a></div>","excerpt":"<a name=\"top\"></a>This page contains information on how to use the fields of the Outputs tab on the Tool Editor.","slug":"tool-output-ports","type":"basic","title":"Tool Output Ports"}

Tool Output Ports

<a name="top"></a>This page contains information on how to use the fields of the Outputs tab on the Tool Editor.

This page contains information on how to use the fields of the Outputs tab on the Tool Editor. [block:callout] { "type": "warning", "title": "On this page:", "body": "* [Add an output port to the tool description](#add)\n* [Basic information](#basic)\n* [Additional information](#additional)\n* [Metadata](#metadata)\n* [Load contents](#load)\n* [Output eval](#output)\n* [Secondary files](#secondary)\n* [Dynamic expressions in the output port description](#dynamic)" } [/block] The Outputs tab allows you to describe the output ports of your tool. As described on the [Inputs port page](doc:tool-input-ports), 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. <a name="add"></a><h2>Add an output port to the tool description</h2> To start describing an output port, go to the tab labeled **Outputs**. [block:image] { "images": [ { "image": [ "https://files.readme.io/yppTL6hKREWTy9HO0xIa_*.1-2.png", "*.1-2.png", "3196", "624", "#324a61", "" ] } ] } [/block] Clicking the **+** button will bring up a pop-out window in which you can specify an **output** port. [block:image] { "images": [ { "image": [ "https://files.readme.io/EsGOoAoFRmpq5jVy4nXa_to1.png", "to1.png", "1786", "1610", "#d85554", "" ] } ] } [/block] <div align="right"><a href="#top">top</a></div> <a name="basic"></a><h2>Basic Information </h2> **ID**: <span style="color:red"><b><i>Required</i></b></span> Each port is assigned an **ID**, which it will be labeled with in the workflow editor. **Type**: <span style="color:red"><b><i>Required</i></b></span> Specify the data structure that the port outputs: either a file or an array. <a name="glob"></a>**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](page:glob). Note that the glob will only match files from the working directory, without recursively searching through any subdirectories. <div align="right"><a href="#top">top</a></div> <a name="additional"></a><h2>Additional Information</h2> 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. <div align="right"><a href="#top">top</a></div> <a name="metadata"></a><h2>Metadata</h2> 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](doc:metadata-on-the-seven-bridges-platform). 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](doc:metadata-for-private-data). 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: [block:image] { "images": [ { "image": [ "https://files.readme.io/9Lv0B6ywRRm9GTjWaEwG_*:1103.png", "*:1103.png", "1010", "230", "#be9060", "" ] } ] } [/block] 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. <div align="right"><a href="#top">top</a></div> <a name="load"></a><h2>Load contents</h2> 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](page:glob). See the documentation on [dynamic expressions in tool descriptions](doc:dynamic-expressions-in-tool-descriptions) for details. <div align="right"><a href="#top">top</a></div> <a name="output"></a><h2>Output Eval</h2> 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](doc: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**. [block:image] { "images": [ { "image": [ "https://files.readme.io/1bb54a6-load-contents-1.jpeg", "load-contents-1.jpeg", 775, 554, "#2e5377" ] } ] } [/block] 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: 1. An output port for the TXT file was added to **MixClone RunModel** and the **Load Contents** option was activated for this output port. [block:image] { "images": [ { "image": [ "https://files.readme.io/34fd55b-load-contents-2.jpeg", "load-contents-2.jpeg", 940, 583, "#e5e6e5" ] } ] } [/block] 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. 2. The following expression, in terms of `$self.contents`, was added to the **Output Eval** field: [block:code] { "codes": [ { "code": "{\n if ($self) {\n var str = $self[0].contents\n var substr = \"Suggested subclone number : \"\n var tmp = str.indexOf(substr)\n var solution = str[tmp+substr.length]\n return solution\n } else {\n return \"\"\n }\n}", "language": "javascript" } ] } [/block] 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. <div align="right"><a href="#top">top</a></div> <a name="secondary"></a><h2>Secondary Files</h2> 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](doc:advanced-features-of-the-tool-editor). <div align="right"><a href="#top">top</a></div> <a name="dynamic"></a><h2>Dynamic expressions in the output port description</h2> 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](doc:dynamic-expressions-in-tool-descriptions). [block:image] { "images": [ { "image": [ "https://files.readme.io/Cjl7fopiSASdMmDcoKwy_to2.png", "to2.png", "1762", "1580", "#49616f", "" ] } ] } [/block] <div align="right"><a href="#top">top</a></div>