Ctrl+K

2.4. Inputs#

2.4.1. 必須入力パラメータ#

ツールのinputs は、ツールの実行に関わる入力パラメーターのリストです。 各パラメーターには、パラメーター名を示すid と、そのパラメーターに有効な値の種類を示すtype があります。

利用可能なプリミティブ型はstring,int,long,float,double, null; 複合型はarrayとrecord; さらに特殊型File,Directory ,Any があります。

次の例では、異なる型の入力パラメーターが、異なる方法でコマンドライン上に表示されることを示します。

まず、以下の内容を含むinp.cwl というファイルを作成します：

inp.cwl#
#!/usr/bin/env cwl-runner
cwlVersion: v1.2
class: CommandLineTool
baseCommand: echo
inputs:
  example_flag:
    type: boolean
    inputBinding:
      position: 1
      prefix: -f
  example_string:
    type: string
    inputBinding:
      position: 3
      prefix: --example-string
  example_int:
    type: int
    inputBinding:
      position: 2
      prefix: -i
      separate: false
  example_file:
    type: File?
    inputBinding:
      prefix: --file=
      separate: false
      position: 4

outputs: []

inp-job.yml というファイルを作成します：

inp-job.yml#
example_flag: true
example_string: hello
example_int: 42
example_file:
  class: File
  path: whale.txt

注釈

cwltool を使って、テンプレートとなる入力オブジェクトを作成できます。これにより、入力オブジェクトファイルにすべての入力パラメータを入力する手間を省くことができます：

$ cwltool --make-template inp.cwl
INFO /opt/hostedtoolcache/Python/3.9.19/x64/bin/cwltool 3.1.20240508115724
INFO Resolved 'inp.cwl' to 'file:///home/runner/work/user_guide/user_guide/src/_includes/cwl/inputs/inp.cwl'
example_string: a_string  # type 'string'
example_int: 0  # type 'int'
example_flag: false  # type 'boolean'
example_file:  # type 'File' (optional)
    class: File
    path: a/file/path

cwltool --make-template inp.cwl > inp-job.yml のように、出力をファイルにリダイレクトします。その後デフォルト値を希望の入力値で修正できます。

"example_file" は File 型として、フィールド class： File と path フィールドを持つオブジェクトとして提供されなければなりません。

次に、コマンドラインでtouch whale.txt と入力し、touchをコマンドを使用して whale.txt を作成します。

$ touch whale.txt

次に、cwltool inp.cwl inp-job.yml というコマンドを使い、コマンドラインにツール定義と入力オブジェクトを指定してcwltool を起動します。次のボックステキストは、これら2つのコマンドと、コマンドラインから期待される出力について説明しています：

$ cwltool inp.cwl inp-job.yml
INFO /opt/hostedtoolcache/Python/3.9.19/x64/bin/cwltool 3.1.20240508115724
INFO Resolved 'inp.cwl' to 'file:///home/runner/work/user_guide/user_guide/src/_includes/cwl/inputs/inp.cwl'
INFO [job inp.cwl] /tmp/cmrl71jp$ echo \
    -f \
    -i42 \
    --example-string \
    hello \
    --file=/tmp/rhvc8wvv/stg7c7273be-ecd7-4297-bbc4-479641fabf95/whale.txt
-f -i42 --example-string hello --file=/tmp/rhvc8wvv/stg7c7273be-ecd7-4297-bbc4-479641fabf95/whale.txt
INFO [job inp.cwl] completed success
{}INFO Final process status is success

Tip

Where did those `/tmp` paths come from?

CWL reference runner（cwltool）と他のランナーは、ツールが明示的に指定されていないファイルに誤ってアクセスしないように、入力ファイルへの（"ソフト"）シンボリックリンクを持つ一時ディレクトリを作成します

inputBindingフィールドはオプションであり、入力パラメータをツールのコマンドラインに含めるかどうか、またどのように含めるかを指定します。inputBindingがない場合、パラメータはコマンドラインに含まれません。 それぞれの例を詳しく見てみましょう。

example_flag:
  type: boolean
  inputBinding:
    position: 1
    prefix: -f

ブール型はフラグとして扱われます。 入力パラメータ "example_flag "が "true "の場合、コマンドラインにprefix が追加されます。 falseの場合、フラグは付加されません。

example_string:
  type: string
  inputBinding:
    position: 3
    prefix: --example-string

文字列型は、コマンドライン上ではリテラル値として与えられます。 prefix はオプションです。与えられた場合、コマンドライン上のパラメータの前に別の引数として与えられます。 上の例では、--example-string hello と与えられます。

example_int:
  type: int
  inputBinding:
    position: 2
    prefix: -i
    separate: false

整数型（および浮動小数点型）はコマンドラインに10進数のテキスト表現で表示されます。 separateオプションがfalseの場合（デフォルト値はtrue）、prefixと値は1つの引数になるようにまとめられます。 上の例では -i42 として表示されます。

example_file:
  type: File?
  inputBinding:
    prefix: --file=
    separate: false
    position: 4

ファイル型は、コマンドライン上にファイルへのパスとして表示されます。 パラメータの型の末尾にクエスチョンマーク?がある場合、これは、パラメータがオプショナルであることを表します。 上記の例では、--file=/tmp/random/path/whale.txt と表示されます。 ただし、入力パラメータに "example_file" パラメータを指定しなかった場合、コマンドラインには何も表示されません。

入力ファイルは読み取り専用です。 入力ファイルを更新したい場合は、まず出力ディレクトリにコピーする必要があります。

position の値は、パラメータがコマンドライン上のどこに表示されるかを決定するために使用されます。 Positionは、絶対的なものではなく、互いに相対的なものです。 そのため、位置は連続である必要はなく、1、3、5の位置にある3つのパラメータは、1、2、3と同じコマンドラインになります。 複数のパラメータが同じ位置を持つことも可能です（パラメータ名で紐付けを行います）。また、位置フィールドは任意です。 デフォルトの位置は0です。

baseCommand フィールドは、常にパラメータの前の最終コマンド行に表示されます。

2.4.2. 配列入力#

コマンドラインに含まれる入力パラメータの配列は簡単に追加できます。配列パラメータを指定するには、2つの方法があります。1つ目の方法は、type にtype: array とitems を指定して、配列に現れる可能性のある有効なデータ型を定義する方法です。2つ目の方法は、入力パラメータがその型の配列であることを示すために、型名の後に[] という括弧を付けることもできます。

array-inputs.cwl#
#!/usr/bin/env cwl-runner
cwlVersion: v1.2
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:
  example_out:
    type: stdout
stdout: output.txt
baseCommand: echo
array-inputs-job.yml#
filesA: [one, two, three]
filesB: [four, five, six]
filesC: [seven, eight, nine]

ここで、コマンドラインにツール定義と入力オブジェクトを指定し cwltool を起動します：

$ cwltool array-inputs.cwl array-inputs-job.yml
INFO /opt/hostedtoolcache/Python/3.9.19/x64/bin/cwltool 3.1.20240508115724
INFO Resolved 'array-inputs.cwl' to 'file:///home/runner/work/user_guide/user_guide/src/_includes/cwl/inputs/array-inputs.cwl'
INFO [job array-inputs.cwl] /tmp/3ugxks63$ echo \
    -A \
    one \
    two \
    three \
    -B=four \
    -B=five \
    -B=six \
    -C=seven,eight,nine > /tmp/3ugxks63/output.txt
INFO [job array-inputs.cwl] completed success
{
    "example_out": {
        "location": "file:///home/runner/work/user_guide/user_guide/src/_includes/cwl/inputs/output.txt",
        "basename": "output.txt",
        "class": "File",
        "checksum": "sha1$91038e29452bc77dcd21edef90a15075f3071540",
        "size": 60,
        "path": "/home/runner/work/user_guide/user_guide/src/_includes/cwl/inputs/output.txt"
    }
}INFO Final process status is success

$ cat output.txt
-A one two three -B=four -B=five -B=six -C=seven,eight,nine

inputBinding は、外側の配列パラメータ定義と内側の配列要素定義のいずれかに記述でき、上図のようにコマンドラインを構築する際に異なる挙動を示します。また、itemSeparator フィールドがあれば、配列の値を項目区切り文字列で区切って1つの引数に連結することを指定できます。

なお、入力の配列は大括弧の中で指定します array-inputs-job.ymlの[]です.配列は複数行に渡って表現することも可能で、関連するキーで定義されていない配列の値は、先頭の- でマークされます。これは次のレッスンで実際に確認し、YAML Guide でより詳細に説明されています。配列の配列、レコードの配列、その他の複雑な型を指定できます。

2.4.3. 包括的入力と排他的入力#

基本的なツールには、一緒に提供しなければならない複数の引数（依存関係あり）や、一緒に提供できない複数の引数（排他関係あり）があることがあります。 recordとユニオン型を使ってパラメータをグループ化し、この2つの条件を定義できます。

record.cwl#
#!/usr/bin/env cwl-runner
cwlVersion: v1.2
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

$ cwltool record.cwl record-job1.yml
INFO /opt/hostedtoolcache/Python/3.9.19/x64/bin/cwltool 3.1.20240508115724
INFO Resolved 'record.cwl' to 'file:///home/runner/work/user_guide/user_guide/src/_includes/cwl/inputs/record.cwl'
ERROR 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'

最初の例では、itemB も与えずに、itemA を与えることはできません。

record-job2.yml#
dependent_parameters:
  itemA: one
  itemB: two
exclusive_parameters:
  itemC: three
  itemD: four

$ cwltool record.cwl record-job2.yml
INFO /opt/hostedtoolcache/Python/3.9.19/x64/bin/cwltool 3.1.20240508115724
INFO Resolved 'record.cwl' to 'file:///home/runner/work/user_guide/user_guide/src/_includes/cwl/inputs/record.cwl'
record-job2.yml:6:3: Warning: invalid field 'itemD', expected one of: 'itemC'
WARNING record-job2.yml:6:3: Warning: invalid field 'itemD', expected one of: 'itemC'
INFO [job record.cwl] /tmp/xj7vn7c6$ echo \
    -A \
    one \
    -B \
    two \
    -C \
    three > /tmp/xj7vn7c6/output.txt
INFO [job record.cwl] completed success
{
    "example_out": {
        "location": "file:///home/runner/work/user_guide/user_guide/src/_includes/cwl/inputs/output.txt",
        "basename": "output.txt",
        "class": "File",
        "checksum": "sha1$329fe3b598fed0dfd40f511522eaf386edb2d077",
        "size": 23,
        "path": "/home/runner/work/user_guide/user_guide/src/_includes/cwl/inputs/output.txt"
    }
}INFO Final process status is success

$ cat output.txt
-A one -B two -C three

2番目の例では、itemC とitemD が排他的であるため、最初に一致した項目 (itemC) のみがコマンドラインに追加され、残りの項目 (itemD) は無視されます。

record-job3.yml#
dependent_parameters:
  itemA: one
  itemB: two
exclusive_parameters:
  itemD: four

$ cwltool record.cwl record-job3.yml
INFO /opt/hostedtoolcache/Python/3.9.19/x64/bin/cwltool 3.1.20240508115724
INFO Resolved 'record.cwl' to 'file:///home/runner/work/user_guide/user_guide/src/_includes/cwl/inputs/record.cwl'
INFO [job record.cwl] /tmp/j05qne7w$ echo \
    -A \
    one \
    -B \
    two \
    -D \
    four > /tmp/j05qne7w/output.txt
INFO [job record.cwl] completed success
{
    "example_out": {
        "location": "file:///home/runner/work/user_guide/user_guide/src/_includes/cwl/inputs/output.txt",
        "basename": "output.txt",
        "class": "File",
        "checksum": "sha1$77f572b28e441240a5e30eb14f1d300bcc13a3b4",
        "size": 22,
        "path": "/home/runner/work/user_guide/user_guide/src/_includes/cwl/inputs/output.txt"
    }
}INFO Final process status is success

$ cat output.txt
-A one -B two -D four

3番目の例では、itemD のみが提供されているので、コマンドラインに表示されます。

2.4.3.1. 式で入力パラメータを排他的に指定する#

排他的入力パラメータを式と組み合わせて使用する場合、JavaScript オブジェクトのinputs に排他的入力値のいずれかが含まれることを意識する必要があります。つまり、これらの排他的な値の型は異なる可能性があるので、input オブジェクトのプロパティを参照するときに、どの型が使用されているかを確認する必要があるかもしれません。

file_format 入力パラメータに、null (つまり、値がない)、または enum の任意の値を受け入れる排他的なものを含む例を使ってみましょう。

exclusive-parameter-expressions.cwl#
cwlVersion: v1.2
class: CommandLineTool

inputs:
  file_format:
    type:
      - 'null'
      - name: format_choices
        type: enum
        symbols:
          - auto
          - fasta
          - fastq
          - fasta.gz
          - fastq.gz
        inputBinding:
          position: 0
          prefix: '--format'
outputs:
  text_output:
    type: string
    outputBinding:
      outputEval: $(inputs.file_format)

baseCommand: 'true'

JavaScriptの式では、null の値を考慮せずに、排他的入力パラメータの値を使用していることに注意してください。fasta（enumの値の1つ）のような有効な値を指定すると、コマンドは正常に実行されるはずです：

$ cwltool exclusive-parameter-expressions.cwl --file_format fasta
INFO /opt/hostedtoolcache/Python/3.9.19/x64/bin/cwltool 3.1.20240508115724
INFO Resolved 'exclusive-parameter-expressions.cwl' to 'file:///home/runner/work/user_guide/user_guide/src/_includes/cwl/inputs/exclusive-parameter-expressions.cwl'
INFO [job exclusive-parameter-expressions.cwl] /tmp/2rza2x99$ true \
    --format \
    fasta
INFO [job exclusive-parameter-expressions.cwl] completed success
{
    "text_output": "fasta"
}INFO Final process status is success

しかし、入力値を提供しない場合、file_format は、null の値として評価されます。これは、出力フィールドが期待する型（string ）と一致しないため、ワークフロー実行時に失敗することになります。

$ cwltool exclusive-parameter-expressions.cwl
INFO /opt/hostedtoolcache/Python/3.9.19/x64/bin/cwltool 3.1.20240508115724
INFO Resolved 'exclusive-parameter-expressions.cwl' to 'file:///home/runner/work/user_guide/user_guide/src/_includes/cwl/inputs/exclusive-parameter-expressions.cwl'
INFO [job exclusive-parameter-expressions.cwl] /tmp/hjn0vbj_$ true
ERROR [job exclusive-parameter-expressions.cwl] Job error:
Error validating output record. the 'text_output' field is not valid because
  the value is not string
 in {
    "text_output": null
}
WARNING [job exclusive-parameter-expressions.cwl] completed permanentFail
{}WARNING Final process status is permanentFail

これを修正するには、排他的パラメータ、またはnull を許可するパラメータを使用する場合、JavaScript 式で or 演算子を使用することを忘れてはなりません。たとえば、式を$(inputs.file_format || 'auto') に変更すると、コマンドラインやジョブ入力ファイルで何も指定されていない場合にデフォルト値"auto"を持つようになります。

ここでは、JavaScriptのブール値 "or"、 演算子 || は、その short-circuiting プロパティに使用されます。inputs.file_formatがブール値の "true"である場合（例えば、列挙された有効な空でない文字列）、式の評価は ||の最初のオペランド"short-circuits"で停止します。しかし、 inputs.file_formatがnullの場合、式全体の値は2番目のオペランドの値になります。これにより合理的なデフォルト値を提供します。

On this page
Edit on GitHub
ソースコードを表示