{"__v":6,"_id":"56cc9eab8fa8b01b00b81f5a","category":{"__v":11,"_id":"5637e8b2fbe1c50d008cb078","pages":["5637e95797666c0d008656ba","5637ea64ee0ee60d0024ec0e","5637f110daf0840d0011dcd5","563d423e9799fb0d0004779b","5640ba77b9c4dd0d0097c827","5640bad42b14f70d0039b8cd","5640bae32b14f70d0039b8cf","5640bb0ceaede117005c99d8","565f6b770dc99e1900f24c73","56cc9eab8fa8b01b00b81f5a","56ddcb9ab4ac273200457c82"],"project":"55faf11ba62ba1170021a9a7","version":"55faf11ba62ba1170021a9aa","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-11-02T22:50:26.865Z","from_sync":false,"order":14,"slug":"describe-your-tool","title":"DESCRIBE YOUR TOOL"},"parentDoc":null,"project":"55faf11ba62ba1170021a9a7","user":"5613e4f8fdd08f2b00437620","version":{"__v":35,"_id":"55faf11ba62ba1170021a9aa","project":"55faf11ba62ba1170021a9a7","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"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-02-23T18:02:19.280Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"On this page:\",\n  \"body\": \"[1. Docker container](#docker con)\\n   * [Image ID:](#image id)\\n   * [Docker Repository: Required field](#docker rep)\\n\\n[2. Resources](#resources)\\n   * [CPU:](#cpu)\\n   * [Memory:](#memory)\\n\\n[3. Create files](#create files)\\n   * [File name:](#file name)\\n   * [File content:](#file con)\\n\\n[4. Command](#command)\\n   * [Base command: Required field](#base)\\n   * [Stdin:](#stdin)\\n   * [Stdout:](#stdout)\\n   * [Success Codes and Temporary Fail Codes:](#success)\\n\\n[5. Argument](#arg)\\n   * [Prefix:](#prefix)\\n   * [Value:](#value)\\n   * [Separate prefix with:](#sep pref)\\n   * [Position:](#pos)\"\n}\n[/block]\nThe **General** information tab contains the following fields.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/TlHdzWz7RDyycb8b68Ta_--700-10.jpeg\",\n        \"--700-10.jpeg\",\n        \"1629\",\n        \"796\",\n        \"#4ba0d1\",\n        \"\"\n      ],\n      \"caption\": \"The General tab on the Tool Editor\"\n    }\n  ]\n}\n[/block]\n<h2><a name=\"docker con\"></a> 1. Docker Container</h2>\n \n<h3><a name=\"image id\"></a>Image ID:</h3>\nPlease leave this blank.\n\n<h3><a name=\"docker rep\"></a>Docker Repository: <span style=\"color:red\"><b>Required field</b></span></h3>\n\nHere, enter the location of the image.\nIf the image is stored in the CGC image registry, the format for locations is <code>cgc-images.sbgenomics.com/<repository><:tag></code>.\nAlternatively, if the image is in <a href=\"https://hub.docker.com/\" target=\"blank\">Docker Hub</a> you can enter its path here as <code><Docker_repository><:tag></code>. 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.\n[block:callout]\n{\n  \"type\": \"success\",\n  \"body\": \"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](doc:the-tool-editor#section-terminology).\\n\\nFor 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`.\",\n  \"title\": \"One subcommand = one tool\"\n}\n[/block]\n<div align=\"right\"><a href=\"#top\">top</a></div>\n\n<a name=\"resources\"></a><h2>2. Resources</h2>\n<a name=\"cpu\"></a><h3>CPU: </h3>\nHere, you can specify the number of CPUs required for the tool's execution.\n\n<a name=\"memory\"></a><h3>Memory: </h3>\nHere, you can specify the memory resources required for the tool's execution.\n\nNote 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.\n\nFor more details, see the [note on `allocatedResources`](doc:dynamic-expressions-in-tool-descriptions#allocated). For information on the $jobvariable, see the [page on dynamic expressions in tool descriptions](doc:dynamic-expressions-in-tool-descriptions#section-the-job-object).\n\n<div align=\"right\"><a href=\"#top\">top</a></div>\n\n<a name=\"create files\"></a><h2>3. Create Files</h2>\nUse 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.\n\n<a name=\"file name\"></a><h3>File name:</h3>\nThis field specifies the name of the file you want to create.\n\n<a name=\"file con\"></a><h3>File content:</h3>\nThis field specifies the content that you want written to the file. You can just paste it here.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/8mOYjcUATfS7IqICF7No_--1001.jpeg\",\n        \"--1001.jpeg\",\n        \"1662\",\n        \"436\",\n        \"#83a4c4\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"success\",\n  \"body\": \"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.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"success\",\n  \"body\": \"See the section on Describing Index Files in [Advanced Features](doc:advanced-features-of-the-tool-editor#section-describing-index-files) for an example of how to use dynamic expressions in the Create Files field.\",\n  \"title\": \"How to use dynamic expressions in the Create Files fields\"\n}\n[/block]\n<div align=\"right\"><a href=\"#top\">top</a></div>\n\n<a name=\"command\"></a><h2>4. Command</h2>\n<h3><a name=\"base\"></a>Base command: <span style=\"color:red\"><b>Required field</b></span></h3>\nEnter the executable name for the command. If you are describing a tool with multiple subcommands you must also enter the subcommand you are describing.\n[block:callout]\n{\n  \"type\": \"success\",\n  \"body\": \"See the [section on terminology](doc:the-tool-editor#section-terminology) on the page The Tool Editor for examples of base commands.\"\n}\n[/block]\n<a name=\"stdin\"></a><h3>Stdin: </h3>\nIf you want to pipe data into standard input for the tool, enter the name of the file containing the data here.\n\n<a name=\"stdout\"></a><h3>Stdout: </h3>\nHere, 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`.\n\n<a name=\"success\"></a><h3>Success Codes and Temporary Fail Codes: </h3>\nIf 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.\n\n<div align=\"right\"><a href=\"#top\">top</a></div>\n\n<a name=\"arg\"></a><h2>5. Arguments</h2>\nHere 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.\n\nNote 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.\n\nOn 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](doc:tool-input-ports) 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.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/kBtPHPwtQmq9n6Oa0RdU_--700-11.jpeg\",\n        \"--700-11.jpeg\",\n        \"1832\",\n        \"464\",\n        \"#4f6f8d\",\n        \"\"\n      ],\n      \"caption\": \"The Add Argument field\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"success\",\n  \"body\": \"See the [section on terminology](doc:the-tool-editor#section-terminology) for examples of a tool's **Value** and **Prefix**.\"\n}\n[/block]\n<a name=\"prefix\"></a><h3>Prefix: </h3>\nThis parameter typically refers to a command option that the base command can take (for example -l or +x). See the [section on terminology](doc:the-tool-editor#section-terminology) for full details.\n\n<a name=\"value\"></a><h3>Value: </h3>\nThis parameter refers to the fixed or dynamic expression passed in as the option argument for the option given in **Prefix**.\n  * If the **Value** field is left empty, you can pass in a value as the option argument for each execution of the tool. \n  * 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.\n  * 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](doc:dynamic-expressions-in-tool-descriptions)  for an example of this in action. \n\n<a name=\"sep pref\"></a><h3>Separate prefix with: </h3>\nThis 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.\n\n<a name=\"pos\"></a><h3>Position: </h3>\nThis 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.\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Example of using the Add Arguments field\",\n  \"body\": \"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.\\n\\nIf 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:\\n**Base command:** `grep`\\n**Arguments:**\\n**Value**: leave empty\\n**Prefix:** `-C`\\n**Separate prefix with:** space\\n**Position:** `1`\"\n}\n[/block]\n<div align=\"right\"><a href=\"#top\">top</a></div>","excerpt":"<a name=\"top\"></a>Details of the fields on the General tab of the Tool Editor","slug":"general-tool-information","type":"basic","title":"General Tool Information"}

General Tool Information

<a name="top"></a>Details of the fields on the General tab of the Tool Editor

[block:callout] { "type": "warning", "title": "On this page:", "body": "[1. Docker container](#docker con)\n * [Image ID:](#image id)\n * [Docker Repository: Required field](#docker rep)\n\n[2. Resources](#resources)\n * [CPU:](#cpu)\n * [Memory:](#memory)\n\n[3. Create files](#create files)\n * [File name:](#file name)\n * [File content:](#file con)\n\n[4. Command](#command)\n * [Base command: Required field](#base)\n * [Stdin:](#stdin)\n * [Stdout:](#stdout)\n * [Success Codes and Temporary Fail Codes:](#success)\n\n[5. Argument](#arg)\n * [Prefix:](#prefix)\n * [Value:](#value)\n * [Separate prefix with:](#sep pref)\n * [Position:](#pos)" } [/block] The **General** information tab contains the following fields. [block:image] { "images": [ { "image": [ "https://files.readme.io/TlHdzWz7RDyycb8b68Ta_--700-10.jpeg", "--700-10.jpeg", "1629", "796", "#4ba0d1", "" ], "caption": "The General tab on the Tool Editor" } ] } [/block] <h2><a name="docker con"></a> 1. Docker Container</h2> <h3><a name="image id"></a>Image ID:</h3> Please leave this blank. <h3><a name="docker rep"></a>Docker Repository: <span style="color:red"><b>Required field</b></span></h3> Here, enter the location of the image. If the image is stored in the CGC image registry, the format for locations is <code>cgc-images.sbgenomics.com/<repository><:tag></code>. Alternatively, if the image is in <a href="https://hub.docker.com/" target="blank">Docker Hub</a> you can enter its path here as <code><Docker_repository><:tag></code>. 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. [block:callout] { "type": "success", "body": "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](doc:the-tool-editor#section-terminology).\n\nFor 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`.", "title": "One subcommand = one tool" } [/block] <div align="right"><a href="#top">top</a></div> <a name="resources"></a><h2>2. Resources</h2> <a name="cpu"></a><h3>CPU: </h3> Here, you can specify the number of CPUs required for the tool's execution. <a name="memory"></a><h3>Memory: </h3> 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`](doc:dynamic-expressions-in-tool-descriptions#allocated). For information on the $jobvariable, see the [page on dynamic expressions in tool descriptions](doc:dynamic-expressions-in-tool-descriptions#section-the-job-object). <div align="right"><a href="#top">top</a></div> <a name="create files"></a><h2>3. Create Files</h2> 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. <a name="file name"></a><h3>File name:</h3> This field specifies the name of the file you want to create. <a name="file con"></a><h3>File content:</h3> This field specifies the content that you want written to the file. You can just paste it here. [block:image] { "images": [ { "image": [ "https://files.readme.io/8mOYjcUATfS7IqICF7No_--1001.jpeg", "--1001.jpeg", "1662", "436", "#83a4c4", "" ] } ] } [/block] [block:callout] { "type": "success", "body": "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." } [/block] [block:callout] { "type": "success", "body": "See the section on Describing Index Files in [Advanced Features](doc:advanced-features-of-the-tool-editor#section-describing-index-files) for an example of how to use dynamic expressions in the Create Files field.", "title": "How to use dynamic expressions in the Create Files fields" } [/block] <div align="right"><a href="#top">top</a></div> <a name="command"></a><h2>4. Command</h2> <h3><a name="base"></a>Base command: <span style="color:red"><b>Required field</b></span></h3> 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. [block:callout] { "type": "success", "body": "See the [section on terminology](doc:the-tool-editor#section-terminology) on the page The Tool Editor for examples of base commands." } [/block] <a name="stdin"></a><h3>Stdin: </h3> If you want to pipe data into standard input for the tool, enter the name of the file containing the data here. <a name="stdout"></a><h3>Stdout: </h3> 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`. <a name="success"></a><h3>Success Codes and Temporary Fail Codes: </h3> 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. <div align="right"><a href="#top">top</a></div> <a name="arg"></a><h2>5. Arguments</h2> 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](doc:tool-input-ports) 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. [block:image] { "images": [ { "image": [ "https://files.readme.io/kBtPHPwtQmq9n6Oa0RdU_--700-11.jpeg", "--700-11.jpeg", "1832", "464", "#4f6f8d", "" ], "caption": "The Add Argument field" } ] } [/block] [block:callout] { "type": "success", "body": "See the [section on terminology](doc:the-tool-editor#section-terminology) for examples of a tool's **Value** and **Prefix**." } [/block] <a name="prefix"></a><h3>Prefix: </h3> This parameter typically refers to a command option that the base command can take (for example -l or +x). See the [section on terminology](doc:the-tool-editor#section-terminology) for full details. <a name="value"></a><h3>Value: </h3> 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](doc:dynamic-expressions-in-tool-descriptions) for an example of this in action. <a name="sep pref"></a><h3>Separate prefix with: </h3> 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. <a name="pos"></a><h3>Position: </h3> 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. [block:callout] { "type": "success", "title": "Example of using the Add Arguments field", "body": "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.\n\nIf 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:\n**Base command:** `grep`\n**Arguments:**\n**Value**: leave empty\n**Prefix:** `-C`\n**Separate prefix with:** space\n**Position:** `1`" } [/block] <div align="right"><a href="#top">top</a></div>