{"_id":"5cbf3231f67741020b0e469a","project":"5773dcfc255e820e00e1cd4d","version":{"_id":"5773dcfc255e820e00e1cd50","__v":26,"project":"5773dcfc255e820e00e1cd4d","createdAt":"2016-06-29T14:36:44.812Z","releaseDate":"2016-06-29T14:36:44.812Z","categories":["5773dcfc255e820e00e1cd51","5773df36904b0c0e00ef05ff","577baf92451b1e0e006075ac","577bb183b7ee4a0e007c4e8d","577ce77a1cf3cb0e0048e5ea","577d11865fd4de0e00cc3dab","578e62792c3c790e00937597","578f4fd98335ca0e006d5c84","578f5e5c3d04570e00976ebb","57bc35f7531e000e0075d118","57f801b3760f3a1700219ebb","5804d55d1642890f00803623","581c8d55c0dc651900aa9350","589dcf8ba8c63b3b00c3704f","594cebadd8a2f7001b0b53b2","59a562f46a5d8c00238e309a","5a2aa096e25025003c582b58","5a2e79566c771d003ca0acd4","5a3a5166142db90026f24007","5a3a52b5bcc254001c4bf152","5a3a574a2be213002675c6d2","5a3a66bb2be213002675cb73","5a3a6e4854faf60030b63159","5c8a68278e883901341de571","5cb9971e57bf020024523c7b","5cbf1683e2a36d01d5012ecd"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"category":{"_id":"5cbf1683e2a36d01d5012ecd","project":"5773dcfc255e820e00e1cd4d","version":"5773dcfc255e820e00e1cd50","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2019-04-23T13:43:31.578Z","from_sync":false,"order":13,"slug":"edit-an-app","title":"EDIT AN APP"},"user":"5767bc73bb15f40e00a28777","__v":0,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2019-04-23T15:41:37.630Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":5,"body":"## Stage input\n\nThe **input staging** functionality allows you to make a tool's input files available in the tool's working directory.\n\nFiles that are named as inputs to a tool are not, by default, in the tool's working directory. In most workflows this access is sufficient, since most tools only need to read their input files, process the data contained in them, and write new output files on the basis of this data to their working directory. However, in some cases a tool might require input files to be in its working directory, and this is where the stage input option is used.\n\n### Staging an input in a CWL v1.0 app\nTo stage an input (make files provided through the input port available directly in the tool's working directory), in a CWL v1.0 app, you need to use the **File requirements** option, as specified below:\n\n1. Open a tool in the tool editor.\n2. Scroll down to the **File Requirements** section.\n3. Click **Add** and select **Expression**. An input field is added to **File Requirements**.\n4. Click **</>** next to the newly-added input field.\n5. Type the following expression: `$(inputs.<input_id>)`, where `<input_id>` is the ID of the input port you want to stage. You can also insert the `inputs.<input_id>` structure within brackets by expanding the **inputs** object on the far right in the expression editor, and double-clicking the desired input port.\n6. Click **Save**. Staging is now configured and input file(s) provided on this input port during execution will be available in the tool's working directory.\n\n### Staging an input in a CWL sbg:draft-2 app\n**Stage Input** allows you to modify the way files appear in a tool's working directory in two ways:\n* **Copy** files that are input to a tool to that tool's working directory. This makes the files directly available in the working directory.\n* **Link** the files input to a tool to that tool's working directory, using a symbolic link (symlink). This option is used in the following circumstances:\n   * To pass the files through' the tool, and report them as the tool's outputs, without actually modifying the files.\n   * To simplify the relative path of the input files to the tool. If you need to include the file paths of a tool's input files as arguments passed to the tool, the path will be simpler if there is a symbolic link from the input files to the tool's working directory.\n\nPlease note that while a tool on Cavatica cannot create output files outside its own working directory, it may write other files – such as config files – outside the working directory. This means that you don't need to modify a tool that is configured to write files to a different directory, as long as you do not wish to treat those files as outputs.\n\nFiles that are copied or linked using the **Stage Input** option will not be produced as the tool's outputs unless output port(s) are created specifically for them.\n\nConsider the following diagram:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/21fb7b3-stage-input-1.png\",\n        \"stage-input-1.png\",\n        580,\n        219,\n        \"#e7f0f0\"\n      ]\n    }\n  ]\n}\n[/block]\nIn this example, files are input to **Tool B** from **Tool A**. If **Tool B** needs the input files to be available in its working directory, you need to use the **Stage Input** setting on the **input_file** input port on **Tool B**.\n\nTo copy the input files from **Tool A** to the working directory of **Tool B**, in order to modify them:\n\n1. Open **Tool B** in the Tool Editor.\n2. On the **Inputs** tab, click the tool description for the inputs port **input_file**.\n3. Click **Stage Input** and select **Copy** from the dropdown menu,\n\nTo create symbolic links for the input files into the working directory of **Tool B**, in order to pass them through, along with other output files but not modify them:\n\n1. Open **Tool B** in the Tool Editor.\n2. On the **Inputs** tab, click the tool description for the inputs port **input_file**.\n3. Click **Stage Input** and select **Link** from the dropdown menu,\n\nSince the **Link** option only results in creation of a symbolic link, it is generally faster than **Copy**. However, **Copy** might be required in certain cases. Besides writing data to files produced by other tools, you also need to select **Copy** when the tool you are configuring needs to add the output files of the previous tool in the workflow to an archive. In order to be able to archive the files, you need actual copies of the files in the tool's working directory.\n\nTo see how the **Stage Input** option is used in an actual workflow on Cavatica:\n**VarScan2 Workflow from BAM** is a public workflow that contains a tool named **SAMtools Index FASTA**. This tool indexes a sequence in FASTA format and outputs a FAI index file. It is also able to output the FASTA file that has been provided as its input.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/8df12dd-stage-input-2.png\",\n        \"stage-input-2.png\",\n        543,\n        523,\n        \"#e7edec\"\n      ]\n    }\n  ]\n}\n[/block]\nTo output the FASTA file that is used as the **SAMTools Index FASTA**'s input file, configure the **input_fasta_file** input port as **Stage Input** > **Link**. This creates a symbolic link to the input FASTA file in the working directory of **SAMtools Index FASTA** and the tool passes the FASTA file as its output, along with the generated index file.\n\n## Load Content\nIn the context of an input port for files, the `$self` object is a JavaScript object referring to the file objects, which can be used in the **Value** field (see the documentation on dynamic expressions in tool descriptions for details).\n\nChecking the box marked **Load Content** on the inputs tab adds an additional property to `$self`, namely contents, which refers to the first 64 KB of the file contents.\n\n## Secondary files\nThis field is present if the input type is **File** or **Array** of files. It allows you to define the extension to be appended to the name of the input file to get the name of the secondary file that is to be loaded automatically along with the input file on this input port. For example, if the input file is `input.bam` and you enter `.bai` in the **Secondary File** field, the resulting file path will be `input.bam.bai`. If you want to remove an extension from the input file name before adding the secondary file extension, add a caret `^` for each extension you want to remove. For example, if the input file is `input.bam` and you enter `^.bai` in the **Secondary File** field, then the secondary file path will be `input.bai`.\n\nIf you are using CWL version sbg:draft-2, a secondary file can be defined for an input port only if the **Include in command line** switch is set to **Yes**. If you do not want to include this input port in the command line, set the **Value** field to return no value by populating it with an expression such as:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    return \\\"\\\";\\n}\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"input-file-options","type":"basic","title":"Input file options"}

Input file options


## Stage input The **input staging** functionality allows you to make a tool's input files available in the tool's working directory. Files that are named as inputs to a tool are not, by default, in the tool's working directory. In most workflows this access is sufficient, since most tools only need to read their input files, process the data contained in them, and write new output files on the basis of this data to their working directory. However, in some cases a tool might require input files to be in its working directory, and this is where the stage input option is used. ### Staging an input in a CWL v1.0 app To stage an input (make files provided through the input port available directly in the tool's working directory), in a CWL v1.0 app, you need to use the **File requirements** option, as specified below: 1. Open a tool in the tool editor. 2. Scroll down to the **File Requirements** section. 3. Click **Add** and select **Expression**. An input field is added to **File Requirements**. 4. Click **</>** next to the newly-added input field. 5. Type the following expression: `$(inputs.<input_id>)`, where `<input_id>` is the ID of the input port you want to stage. You can also insert the `inputs.<input_id>` structure within brackets by expanding the **inputs** object on the far right in the expression editor, and double-clicking the desired input port. 6. Click **Save**. Staging is now configured and input file(s) provided on this input port during execution will be available in the tool's working directory. ### Staging an input in a CWL sbg:draft-2 app **Stage Input** allows you to modify the way files appear in a tool's working directory in two ways: * **Copy** files that are input to a tool to that tool's working directory. This makes the files directly available in the working directory. * **Link** the files input to a tool to that tool's working directory, using a symbolic link (symlink). This option is used in the following circumstances: * To pass the files through' the tool, and report them as the tool's outputs, without actually modifying the files. * To simplify the relative path of the input files to the tool. If you need to include the file paths of a tool's input files as arguments passed to the tool, the path will be simpler if there is a symbolic link from the input files to the tool's working directory. Please note that while a tool on Cavatica cannot create output files outside its own working directory, it may write other files – such as config files – outside the working directory. This means that you don't need to modify a tool that is configured to write files to a different directory, as long as you do not wish to treat those files as outputs. Files that are copied or linked using the **Stage Input** option will not be produced as the tool's outputs unless output port(s) are created specifically for them. Consider the following diagram: [block:image] { "images": [ { "image": [ "https://files.readme.io/21fb7b3-stage-input-1.png", "stage-input-1.png", 580, 219, "#e7f0f0" ] } ] } [/block] In this example, files are input to **Tool B** from **Tool A**. If **Tool B** needs the input files to be available in its working directory, you need to use the **Stage Input** setting on the **input_file** input port on **Tool B**. To copy the input files from **Tool A** to the working directory of **Tool B**, in order to modify them: 1. Open **Tool B** in the Tool Editor. 2. On the **Inputs** tab, click the tool description for the inputs port **input_file**. 3. Click **Stage Input** and select **Copy** from the dropdown menu, To create symbolic links for the input files into the working directory of **Tool B**, in order to pass them through, along with other output files but not modify them: 1. Open **Tool B** in the Tool Editor. 2. On the **Inputs** tab, click the tool description for the inputs port **input_file**. 3. Click **Stage Input** and select **Link** from the dropdown menu, Since the **Link** option only results in creation of a symbolic link, it is generally faster than **Copy**. However, **Copy** might be required in certain cases. Besides writing data to files produced by other tools, you also need to select **Copy** when the tool you are configuring needs to add the output files of the previous tool in the workflow to an archive. In order to be able to archive the files, you need actual copies of the files in the tool's working directory. To see how the **Stage Input** option is used in an actual workflow on Cavatica: **VarScan2 Workflow from BAM** is a public workflow that contains a tool named **SAMtools Index FASTA**. This tool indexes a sequence in FASTA format and outputs a FAI index file. It is also able to output the FASTA file that has been provided as its input. [block:image] { "images": [ { "image": [ "https://files.readme.io/8df12dd-stage-input-2.png", "stage-input-2.png", 543, 523, "#e7edec" ] } ] } [/block] To output the FASTA file that is used as the **SAMTools Index FASTA**'s input file, configure the **input_fasta_file** input port as **Stage Input** > **Link**. This creates a symbolic link to the input FASTA file in the working directory of **SAMtools Index FASTA** and the tool passes the FASTA file as its output, along with the generated index file. ## Load Content In the context of an input port for files, the `$self` object is a JavaScript object referring to the file objects, which can be used in the **Value** field (see the documentation on dynamic expressions in tool descriptions for details). Checking the box marked **Load Content** on the inputs tab adds an additional property to `$self`, namely contents, which refers to the first 64 KB of the file contents. ## Secondary files This field is present if the input type is **File** or **Array** of files. It allows you to define the extension to be appended to the name of the input file to get the name of the secondary file that is to be loaded automatically along with the input file on this input port. For example, if the input file is `input.bam` and you enter `.bai` in the **Secondary File** field, the resulting file path will be `input.bam.bai`. If you want to remove an extension from the input file name before adding the secondary file extension, add a caret `^` for each extension you want to remove. For example, if the input file is `input.bam` and you enter `^.bai` in the **Secondary File** field, then the secondary file path will be `input.bai`. If you are using CWL version sbg:draft-2, a secondary file can be defined for an input port only if the **Include in command line** switch is set to **Yes**. If you do not want to include this input port in the command line, set the **Value** field to return no value by populating it with an expression such as: [block:code] { "codes": [ { "code": "{\n return \"\";\n}", "language": "javascript" } ] } [/block]