{"_id":"5cbf254aace26900161e449a","project":"55faf11ba62ba1170021a9a7","version":{"_id":"55faf11ba62ba1170021a9aa","project":"55faf11ba62ba1170021a9a7","__v":46,"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","59a555bccdbd85001bfb1442","5a2a81f688574d001e9934f5","5b080c8d7833b20003ddbb6f","5c222bed4bc358002f21459a","5c22412594a2a5005cc9e919","5c41ae1c33592700190a291e","5c8a525e2ba7b2003f9b153c","5cbf14d58c79c700ef2b502e","5db6f03a6e187c006f667fa4"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"category":{"_id":"5cbf14d58c79c700ef2b502e","project":"55faf11ba62ba1170021a9a7","version":"55faf11ba62ba1170021a9aa","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2019-04-23T13:36:21.375Z","from_sync":false,"order":33,"slug":"edit-an-app-1","title":"EDIT AN APP"},"user":"5767bc73bb15f40e00a28777","__v":0,"parentDoc":null,"metadata":{"title":"","description":"","image":[]},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2019-04-23T14:46:34.090Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":7,"body":"[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"This page provides more details on how to use dynamics expressions in version **1.0** of the Common Workflow Language. If you are describing a tool using the **sbg:draft-2** version of CWL, please see [this page](doc:dynamic-expressions-in-tool-descriptions) for details.\"\n}\n[/block]\nThe tool editor allows you to describe the features and behavior of your command line tool. The resulting description is used to create an interface between your tool and other tools that can be run on the CGC.\n\nIf your tool has a certain behavior, controlled by a command line option argument, that you don't want to ever vary with executions, you can 'hard code' this into the tool description. On the other hand, if you want to chose the argument every time you run the tool, you can manually input it with each execution. But, in many cases, a middle way is more appropriate: although the required argument will vary with executions, it should do so in a deterministic way, dependent on other features of the tool execution.\n\nTo achieve this behavior, you can hard code the argument using a dynamic expression in your tool description, rather than a literal. It can be expressed in terms of the inputs, outputs, or other aspects of a tool execution; the object that the expression refers to will then be determined at runtime on the basis of the values of these other objects.\n\n### Using dynamic expressions\nDynamic expressions are given in Javascript. You can enter a dynamic expression anywhere in the tool editor where you find the symbol **</>**. For example, you could enter the Javascript expression `1+2`, or a function body such as `${return 1+2}`.\n\nPlaces where you might want to use dynamic expressions include:\n\n  * Specifying the command options for your tool. Options related to tool inputs are set in the [Input ports](doc:create-a-tool#section-input-ports) section, and others are set in the [Arguments](doc:create-a-tool#section-arguments) section.\n  * Specifying stdin and stdout.\n  * Setting the resources allocated to your tool (memory and CPU number).\n  * Setting up the glob pattern to catch outputs, in the [Output ports](doc:create-a-tool#section-output-ports) section.\n  * Specifying secondary files for inputs and outputs.\n  * Specifying files available in the working directory prior to command execution.\n\n### Predefined Javascript objects\nSome Javascript objects have been defined in the scope of the tool execution, and are available for you to use in dynamic expressions to increase their expressivity. The `inputs`, `self` and `runtime` objects denote properties of the ongoing tool execution (the job), and the tool's inputs or outputs in a given execution. They are described below.\n\n<a name=\"section-inputs-object\"></a>\nThe `inputs` object\n\nThis is an object that denotes the inputs for the tool. Remember that tool inputs [include files and parameters](doc:create-a-tool). The inputs object has the properties `<input_id>` and `<input_value>`. \n\n`<input_id>` is the ID that you have labeled each [input port](doc:create-a-tool#section-input-ports) with in the tool editor. \n\n`<input_value>` refers to the object that is entered into the port named `<input_id>`. It is set according to the following rule, illustrated in the table below: If the object entered into the port named `<input_id>` is any data type other than a file, then `<input_value>` is the object itself. If the object entered into the port `<input_id>` is a file, then `<input_value>` is four objects that describe, and uniquely determine, the file.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Data type input to the port named <input_id>\",\n    \"h-1\": \"<input_value>\",\n    \"0-0\": \"File\",\n    \"1-0\": \"String\",\n    \"2-0\": \"Enum\",\n    \"3-0\": \"Int\",\n    \"4-0\": \"Float\",\n    \"5-0\": \"Boolean\",\n    \"6-0\": \"Array\",\n    \"0-1\": \"The following four objects are the `input_value`:\\n\\n* `class`: this is always 'File'\\n* `secondaryFiles`: this is a list of [secondary files](doc:create-a-tool#section-secondary-files) (index files) attached to the file. It may be empty.\\n* `path`: this is the file path.  \\n* `basename`: this is the file name (e.g. `filename.bam`).  \\n* `nameroot`: this is part of the file name before the last '.' character in the name (e.g. `filename`).  \\n* `nameext`: this is the extension of the file (e.g. `.bam`).  \\n* `size`: this is the file size.\",\n    \"1-1\": \"The string entered to the input port.\",\n    \"2-1\": \"The enumerator of the enumerated type that is entered to the input port labeled by `<input_id>`\",\n    \"3-1\": \"The integer entered to this input port.\",\n    \"4-1\": \"The float entered to this input port.\",\n    \"5-1\": \"The boolean value entered to this input port.\",\n    \"6-1\": \"The array entered to this input port.\"\n  },\n  \"cols\": 2,\n  \"rows\": 7\n}\n[/block]\n### Inspecting the inputs object\nThe objects in `<input_value>` are defined at runtime, depending on which strings, ints, files, and so on are inputted to the tool. \n\nTo see the `inputs` object for your tool description and test values:\n\n1. Click the **...** icon in the top right hand corner\n2. Select **Export (YAML format)**.\n\nA file in YAML format will be downloaded. The file contains the entire CWL code of the app, including the defined input ports within the `inputs` object.\n\nIn order to get a better understanding of what `input_id` and `input_value` denote, let's create a tool description in the editor that has input ports for different selected data types, and then view the inputs.\n\n### Examples of `inputs` usage\nEarlier, we listed fields in which you may want to use the `inputs` object in dynamic expressions. Here are a few examples:\n\n* You may need to set the tool's required memory to be a function of the size of the inputted file. In this case, you can use the object `inputs.<input_id>.size` to pick out the size of the file inputted to the port `<input_id>`.\n* You can use `inputs` to perform linking input files to the current working directory of the job. To do that, you will need to specify: (a) the file name and (b) the file to be copied/linked.\n   * (a) The file name for the file input to the tool is obtained from the `basename` property of the `<input_id>` object for the input port that takes files. The name of the input file is `$(inputs.<input_id>.basename)`.\n   * (b) The file itself is obtained from `<input_id>`, for the input port that takes files. Use: `inputs.<input_id>`.\n\n### The `self` object\nThe `self` object is used to modify the value of the input or output that gets passed to the command line.\n\n* In the command line bindings for the tool inputs, `self` is set to the value of the input. In other words, in this context `self` is just `inputs.<input_id>`.\n* In the command line bindings for the tool outputs, `self` is  an object with the properties `path` and `size` that match the globbed file (see [here](page:glob) for more information on globbing).\n\n### Examples of `self` usage\n\nHere are a few examples of how you can use the self object:\n\n`self` in the **Input ports** section:\n\n* Use `self` for string manipulation. Suppose that your tool takes input files that are entered on the command line, but expects these to be given as filenames, not as file paths. Since `self` refers to the tool input, in the case that files are the input type, `self` will refer to a full file path. By performing string manipulation on this file path, using `self.basename`, you can extract the filename. Then, enter this as the input value to the tool.\n* Another use case for `self` is to manipulate an integer input. Suppose that your tool expects integer inputs in exponent notation, but inputs are given as integers. In this case, `self` will refer to the integer inputted, and you can use an expression in terms of `self` in the Inputs value field to give the integer in its exponent representation.\n\n`self` in the **Outputs ports** section\n\n* In addition to using `self` to refer to a tool's inputs, you can use `self.path` in the **Output Ports** section to specify to the path of the file matching the glob pattern. You might want to annotate output files with the metadata field 'file type', whose value depends on the particular extension of the file being output by the tool. In this case, set the metadata key to `file_type` and set the value to the Javascript expression `self.path.split('.').slice(-1)[0]` to refer to the part of the file path after the dot, i.e. the extension. \n\n### The `runtime` object\n\nIt is an object with properties related to the running environment. More details are explained in the [Common Workflow Language specification](https://www.commonwl.org/v1.0/CommandLineTool.html#Runtime_environment).","excerpt":"","slug":"dynamic-expressions-in-tool-descriptions-1","type":"basic","title":"Dynamic expressions in tool descriptions"}

Dynamic expressions in tool descriptions


[block:callout] { "type": "info", "body": "This page provides more details on how to use dynamics expressions in version **1.0** of the Common Workflow Language. If you are describing a tool using the **sbg:draft-2** version of CWL, please see [this page](doc:dynamic-expressions-in-tool-descriptions) for details." } [/block] The tool editor allows you to describe the features and behavior of your command line tool. The resulting description is used to create an interface between your tool and other tools that can be run on the CGC. If your tool has a certain behavior, controlled by a command line option argument, that you don't want to ever vary with executions, you can 'hard code' this into the tool description. On the other hand, if you want to chose the argument every time you run the tool, you can manually input it with each execution. But, in many cases, a middle way is more appropriate: although the required argument will vary with executions, it should do so in a deterministic way, dependent on other features of the tool execution. To achieve this behavior, you can hard code the argument using a dynamic expression in your tool description, rather than a literal. It can be expressed in terms of the inputs, outputs, or other aspects of a tool execution; the object that the expression refers to will then be determined at runtime on the basis of the values of these other objects. ### Using dynamic expressions Dynamic expressions are given in Javascript. You can enter a dynamic expression anywhere in the tool editor where you find the symbol **</>**. For example, you could enter the Javascript expression `1+2`, or a function body such as `${return 1+2}`. Places where you might want to use dynamic expressions include: * Specifying the command options for your tool. Options related to tool inputs are set in the [Input ports](doc:create-a-tool#section-input-ports) section, and others are set in the [Arguments](doc:create-a-tool#section-arguments) section. * Specifying stdin and stdout. * Setting the resources allocated to your tool (memory and CPU number). * Setting up the glob pattern to catch outputs, in the [Output ports](doc:create-a-tool#section-output-ports) section. * Specifying secondary files for inputs and outputs. * Specifying files available in the working directory prior to command execution. ### Predefined Javascript objects Some Javascript objects have been defined in the scope of the tool execution, and are available for you to use in dynamic expressions to increase their expressivity. The `inputs`, `self` and `runtime` objects denote properties of the ongoing tool execution (the job), and the tool's inputs or outputs in a given execution. They are described below. <a name="section-inputs-object"></a> The `inputs` object This is an object that denotes the inputs for the tool. Remember that tool inputs [include files and parameters](doc:create-a-tool). The inputs object has the properties `<input_id>` and `<input_value>`. `<input_id>` is the ID that you have labeled each [input port](doc:create-a-tool#section-input-ports) with in the tool editor. `<input_value>` refers to the object that is entered into the port named `<input_id>`. It is set according to the following rule, illustrated in the table below: If the object entered into the port named `<input_id>` is any data type other than a file, then `<input_value>` is the object itself. If the object entered into the port `<input_id>` is a file, then `<input_value>` is four objects that describe, and uniquely determine, the file. [block:parameters] { "data": { "h-0": "Data type input to the port named <input_id>", "h-1": "<input_value>", "0-0": "File", "1-0": "String", "2-0": "Enum", "3-0": "Int", "4-0": "Float", "5-0": "Boolean", "6-0": "Array", "0-1": "The following four objects are the `input_value`:\n\n* `class`: this is always 'File'\n* `secondaryFiles`: this is a list of [secondary files](doc:create-a-tool#section-secondary-files) (index files) attached to the file. It may be empty.\n* `path`: this is the file path. \n* `basename`: this is the file name (e.g. `filename.bam`). \n* `nameroot`: this is part of the file name before the last '.' character in the name (e.g. `filename`). \n* `nameext`: this is the extension of the file (e.g. `.bam`). \n* `size`: this is the file size.", "1-1": "The string entered to the input port.", "2-1": "The enumerator of the enumerated type that is entered to the input port labeled by `<input_id>`", "3-1": "The integer entered to this input port.", "4-1": "The float entered to this input port.", "5-1": "The boolean value entered to this input port.", "6-1": "The array entered to this input port." }, "cols": 2, "rows": 7 } [/block] ### Inspecting the inputs object The objects in `<input_value>` are defined at runtime, depending on which strings, ints, files, and so on are inputted to the tool. To see the `inputs` object for your tool description and test values: 1. Click the **...** icon in the top right hand corner 2. Select **Export (YAML format)**. A file in YAML format will be downloaded. The file contains the entire CWL code of the app, including the defined input ports within the `inputs` object. In order to get a better understanding of what `input_id` and `input_value` denote, let's create a tool description in the editor that has input ports for different selected data types, and then view the inputs. ### Examples of `inputs` usage Earlier, we listed fields in which you may want to use the `inputs` object in dynamic expressions. Here are a few examples: * You may need to set the tool's required memory to be a function of the size of the inputted file. In this case, you can use the object `inputs.<input_id>.size` to pick out the size of the file inputted to the port `<input_id>`. * You can use `inputs` to perform linking input files to the current working directory of the job. To do that, you will need to specify: (a) the file name and (b) the file to be copied/linked. * (a) The file name for the file input to the tool is obtained from the `basename` property of the `<input_id>` object for the input port that takes files. The name of the input file is `$(inputs.<input_id>.basename)`. * (b) The file itself is obtained from `<input_id>`, for the input port that takes files. Use: `inputs.<input_id>`. ### The `self` object The `self` object is used to modify the value of the input or output that gets passed to the command line. * In the command line bindings for the tool inputs, `self` is set to the value of the input. In other words, in this context `self` is just `inputs.<input_id>`. * In the command line bindings for the tool outputs, `self` is an object with the properties `path` and `size` that match the globbed file (see [here](page:glob) for more information on globbing). ### Examples of `self` usage Here are a few examples of how you can use the self object: `self` in the **Input ports** section: * Use `self` for string manipulation. Suppose that your tool takes input files that are entered on the command line, but expects these to be given as filenames, not as file paths. Since `self` refers to the tool input, in the case that files are the input type, `self` will refer to a full file path. By performing string manipulation on this file path, using `self.basename`, you can extract the filename. Then, enter this as the input value to the tool. * Another use case for `self` is to manipulate an integer input. Suppose that your tool expects integer inputs in exponent notation, but inputs are given as integers. In this case, `self` will refer to the integer inputted, and you can use an expression in terms of `self` in the Inputs value field to give the integer in its exponent representation. `self` in the **Outputs ports** section * In addition to using `self` to refer to a tool's inputs, you can use `self.path` in the **Output Ports** section to specify to the path of the file matching the glob pattern. You might want to annotate output files with the metadata field 'file type', whose value depends on the particular extension of the file being output by the tool. In this case, set the metadata key to `file_type` and set the value to the Javascript expression `self.path.split('.').slice(-1)[0]` to refer to the part of the file path after the dot, i.e. the extension. ### The `runtime` object It is an object with properties related to the running environment. More details are explained in the [Common Workflow Language specification](https://www.commonwl.org/v1.0/CommandLineTool.html#Runtime_environment).