Array Inputs

Overview

Teaching: 10 min
Exercises: 0 min

Questions

• How do I specify input parameters in arrays?

Objectives

• Learn how to provide parameter arrays as input to a tool.

• Learn how to control the organization of array parameters on the command line.

It is easy to add arrays of input parameters represented to the command line. To specify an array parameter, the array definition is nested under the type field with type: array and items defining the valid data types that may appear in the array.

array-inputs.cwl

#!/usr/bin/env cwl-runner

cwlVersion: v1.0
class: CommandLineTool
inputs:
  filesA:
    type: string[]
    inputBinding:
      prefix: -A
      position: 1

  filesB:
    type:
      type: array
      items: string
      inputBinding:
        prefix: -B=
        separate: false
    inputBinding:
      position: 2

  filesC:
    type: string[]
    inputBinding:
      prefix: -C=
      itemSeparator: ","
      separate: false
      position: 4

outputs: []
baseCommand: echo

array-inputs-job.yml

filesA: [one, two, three]
filesB: [four, five, six]
filesC: [seven, eight, nine]

Now invoke cwl-runner providing the tool wrapper and the input object on the command line:

$ cwl-runner array-inputs.cwl array-inputs-job.yml
[job 140334923640912] /home/example$ echo -A one two three -B=four -B=five -B=six -C=seven,eight,nine
-A one two three -B=four -B=five -B=six -C=seven,eight,nine
Final process status is success
{}

The inputBinding can appear either on the outer array parameter definition or the inner array element definition, and these produce different behavior when constructing the command line, as shown above. In addition, the itemSeperator field, if provided, specifies that array values should be concatenated into a single argument separated by the item separator string.

Note that the arrays of inputs are specified inside square brackets [] in array-inputs-job.yml. Arrays can also be expressed over multiple lines, where array values that are not defined with an associated key is marked by a leading -, as demonstrated in the next lesson. You can specify arrays of arrays, arrays of records, and other complex types.

Key Points

• Array parameter definitions are nested under the type field with type: array.

• The appearance of array parameters on the command line differs depending on with the inputBinding field is provided in the description.

• Use the itemSeperator field to control concatenatation of array parameters.