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: []
baseCommand: echo

record-job1.yml

dependent_parameters:
  itemA: one
exclusive_parameters:
  itemC: three

$ cwl-runner record.cwl record-job1.yml
Workflow error:
  Error validating input record, could not validate field `dependent_parameters` 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
[job 140566927111376] /home/example$ echo -A one -B two -C three
-A one -B two -C three
Final process status is success
{}

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 140606932172880] /home/example$ echo -A one -B two -D four
-A one -B two -D four
Final process status is success
{}

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.