Advanced Inputs

Overview

Teaching: 10 min
Exercises: 0 min
Questions
  • How do I describe dependent and exclusive parameters?

Objectives
  • Learn how to use records to describe the relationships between inputs.

Sometimes an underlying tool has several arguments that must be provided together (they are dependent) or several arguments that cannot be provided together (they are exclusive). You can use records and type unions to group parameters together to describe these two conditions.

record.cwl

#!/usr/bin/env cwl-runner

cwlVersion: v1.0
class: CommandLineTool
inputs:
  dependent_parameters:
    type:
      type: record
      name: dependent_parameters
      fields:
        itemA:
          type: string
          inputBinding:
            prefix: -A
        itemB:
          type: string
          inputBinding:
            prefix: -B
  exclusive_parameters:
    type:
      - type: record
        name: itemC
        fields:
          itemC:
            type: string
            inputBinding:
              prefix: -C
      - type: record
        name: itemD
        fields:
          itemD:
            type: string
            inputBinding:
              prefix: -D
outputs:
  example_out:
    type: stdout
stdout: output.txt
baseCommand: echo

record-job1.yml

dependent_parameters:
  itemA: one
exclusive_parameters:
  itemC: three

$ cwl-runner record.cwl record-job1.yml
Workflow error, try again with --debug for more information:
Invalid job input record:
record-job1.yml:1:1: the `dependent_parameters` field is not valid because
                       missing required field `itemB`

In the first example, you can’t provide itemA without also providing itemB.

record-job2.yml

dependent_parameters:
  itemA: one
  itemB: two
exclusive_parameters:
  itemC: three
  itemD: four

$ cwl-runner record.cwl record-job2.yml
record-job2.yml:6:3: invalid field `itemD`, expected one of: 'itemC'
[job record.cwl] /home/example$ echo \
    -A \
    one \
    -B \
    two \
    -C \
    three > /home/example/output.txt
[job record.cwl] completed success
{
    "example_out": {
        "location": "file:///home/example/11-records/output.txt",
        "basename": "output.txt",
        "class": "File",
        "checksum": "sha1$329fe3b598fed0dfd40f511522eaf386edb2d077",
        "size": 23,
        "path": "/home/example/output.txt"
    }
}
Final process status is success
$ cat output.txt
-A one -B two -C three

In the second example, itemC and itemD are exclusive, so only itemC is added to the command line and itemD is ignored.

record-job3.yml

dependent_parameters:
  itemA: one
  itemB: two
exclusive_parameters:
  itemD: four

$ cwl-runner record.cwl record-job3.yml
[job record.cwl] /home/example$ echo \
    -A \
    one \
    -B \
    two \
    -D \
    four > /home/example/output.txt
[job record.cwl] completed success
{
    "example_out": {
        "location": "file:///home/example/output.txt",
        "basename": "output.txt",
        "class": "File",
        "checksum": "sha1$77f572b28e441240a5e30eb14f1d300bcc13a3b4",
        "size": 22,
        "path": "/home/example/output.txt"
    }
}
Final process status is success
$ cat output.txt
-A one -B two -D four

In the third example, only itemD is provided, so it appears on the command line.

Key Points

  • Use the record field to group parameters together.

  • Multiple records within the same parameter description are treated as exclusive.