HealthOmics ワークフローのパラメータテンプレートファイル

パラメータテンプレートは、ワークフローの入力パラメータを定義します。入力パラメータを定義して、ワークフローの柔軟性と汎用性を高めることができます。たとえば、参照ゲノムファイルの Amazon S3 の場所のパラメータを定義できます。パラメータテンプレートは、Git ベースのリポジトリサービスまたはローカルドライブを通じて提供できます。その後、ユーザーはさまざまなデータセットを使用してワークフローを実行できます。

ワークフローのパラメータテンプレートを作成するか、HealthOmics がパラメータテンプレートを自動的に生成できます。

パラメータテンプレートは JSON ファイルです。ファイルでは、各入力パラメータは、ワークフロー入力の名前と一致する名前付きオブジェクトです。実行を開始するときに、すべての必須パラメータの値を指定しない場合、実行は失敗します。

入力パラメータオブジェクトには、次の属性が含まれます。

description – この必須属性は、コンソールが実行開始ページに表示する文字列です。この説明は実行メタデータとしても保持されます。
optional – このオプション属性は、入力パラメータがオプションかどうかを示します。optional フィールドを指定しない場合、入力パラメータは必須です。

次のパラメータテンプレートの例は、入力パラメータを指定する方法を示しています。


{
  "myRequiredParameter1": {
     "description": "this parameter is required",
  },
  "myRequiredParameter2": {
     "description": "this parameter is also required",
     "optional": false
  },
  "myOptionalParameter": {
     "description": "this parameter is optional",
     "optional": true
  }
}

パラメータテンプレートの生成

HealthOmics は、ワークフロー定義を解析して入力パラメータを検出することでパラメータテンプレートを生成します。ワークフローのパラメータテンプレートファイルを指定すると、ファイルのパラメータによって、ワークフロー定義で検出されたパラメータが上書きされます。

以下のセクションで説明するように、CWL、WDL、Nextflow エンジンの解析ロジックには若干の違いがあります。

CWL のパラメータ検出

CWL ワークフローエンジンでは、解析ロジックは次の仮定を行います。

NULL 対応タイプは、オプションの入力パラメータとしてマークされます。
NULL でサポートされていないタイプは、必須の入力パラメータとしてマークされます。
デフォルト値を持つパラメータは、オプションの入力パラメータとしてマークされます。
説明は、mainワークフロー定義の labelセクションから抽出されます。を指定labelしない場合、説明は空白になります (空の文字列）。

次の表は、CWL 補間の例を示しています。各例のパラメータ名はですx。パラメータが必要な場合は、パラメータの値を指定する必要があります。パラメータがオプションの場合、値を指定する必要はありません。

この表は、プリミティブ型の CWL 補間の例を示しています。

Input	入出力の例	必須
`x: type: int`	1 または 2 または ...	あり
`x: type: int default: 2`	デフォルト値は 2 です。有効な入力は 1 または 2 または ...	なし
`x: type: int?`	有効な入力は None または 1 または 2 または ... です。	なし
`x: type: int? default: 2`	デフォルト値は 2 です。有効な入力は None または 1 または 2 または ... です。	なし

次の表は、複雑なタイプの CWL 補間の例を示しています。複合型はプリミティブ型のコレクションです。

Input	入出力の例	必須
`x: type: array items: int`	[] または [1,2,3]	あり
`x: type: array? items: int`	なしまたは [] または [1,2,3]	なし
`x: type: array items: int?`	[] または [なし、3、なし〕	あり
`x: type: array? items: int?`	[None] または None または [1,2,3] または [None, 3] ですが [] ではありません	なし

WDL のパラメータ検出

WDL ワークフローエンジンでは、解析ロジックは次の前提になります。

NULL 対応タイプは、オプションの入力パラメータとしてマークされます。
nullable 以外のサポート対象タイプの場合：
- リテラルまたは式が割り当てられた入力変数は、オプションパラメータとしてマークされます。例:
```
 Int x = 2 
Float f0 = 1.0 + f1
```
- 入力パラメータに値または式が割り当てられていない場合は、必須パラメータとしてマークされます。
説明は、mainワークフロー定義parameter_metaのから抽出されます。を指定parameter_metaしない場合、説明は空白になります (空の文字列）。詳細については、パラメータメタデータの WDL 仕様を参照してください。

次の表は、WDL 補間の例を示しています。各例のパラメータ名はですx。パラメータが必要な場合は、パラメータの値を指定する必要があります。パラメータがオプションの場合、値を指定する必要はありません。

この表は、プリミティブ型の WDL 補間の例を示しています。

Input	入出力の例	必須
Int x	1 または 2 または ...	あり
Int x = 2	2	なし
Int x = 1+2	3	なし
Int x = y+z	y+z	なし
Int? x	なし、1 または 2 または ...	あり
Int? x = 2	なしまたは 2	なし
Int? x = 1+2	なしまたは 3	なし
Int? x = y+z	なしまたは y+z	なし

次の表は、複雑なタイプの WDL 補間の例を示しています。複合型はプリミティブ型のコレクションです。

Input	入出力の例	必須
配列[Int] x	[1,2,3] または []	あり
配列[Int]+ x	[1]、ただし [] ではない	あり
Array[Int]? x	なしまたは [] または [1,2,3]	なし
配列[Int?] x	[] または [なし、3、なし〕	あり
Array[Int?]=? x	[None] または None または [1,2,3] または [None, 3] ですが [] ではありません	なし
構造体サンプル {文字列 a、Int y} 後続の入力: サンプル mySample	`String a = mySample.a Int y = mySample.y`	あり
構造体サンプル {文字列 a、Int y} 後の入力: Sample? mySample	`if (defined(mySample)) { String a = mySample.a Int y = mySample.y }`	なし

Nextflow のパラメータ検出

Nextflow の場合、HealthOmics はnextflow_schema.jsonファイルを解析してパラメータテンプレートを生成します。ワークフロー定義にスキーマファイルが含まれていない場合、HealthOmics はメインワークフロー定義ファイルを解析します。

トピック

スキーマファイルの解析
メインファイルの解析
ネストされたパラメータ
Nextflow 補間の例

スキーマファイルの解析

解析を正しく機能させるには、スキーマファイルが次の要件を満たしていることを確認してください。

スキーマファイルはという名前nextflow_schema.jsonで、メインワークフローファイルと同じディレクトリにあります。
スキーマファイルは、次のいずれかのスキーマで定義されている有効な JSON です。
- json-schema.org/draft/2020-12/schema。
- json-schema.org/draft-07/schema。

HealthOmics はnextflow_schema.jsonファイルを解析してパラメータテンプレートを生成します。

スキーマで定義されているすべての properties を抽出します。
プロパティで使用可能なdescription場合は、プロパティを含めます。
プロパティの requiredフィールドに基づいて、各パラメータがオプションか必須かを識別します。

次の例は、定義ファイルと生成されたパラメータファイルを示しています。


{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "$defs": {
        "input_options": {
            "title": "Input options",
            "type": "object",
            "required": ["input_file"],
            "properties": {
                "input_file": {
                    "type": "string",
                    "format": "file-path",
                    "pattern": "^s3://[a-z0-9.-]{3,63}(?:/\\S*)?$",
                    "description": "description for input_file"
                },
                "input_num": {
                    "type": "integer",
                    "default": 42,
                    "description": "description for input_num"
                }
            }
        },
        "output_options": {
            "title": "Output options",
            "type": "object",
            "required": ["output_dir"],
            "properties": {
                "output_dir": {
                    "type": "string",
                    "format": "file-path",
                    "description": "description for output_dir",
                }
            }
        }
    },
    "properties": {
        "ungrouped_input_bool": {
            "type": "boolean",
            "default": true
        }
    },
    "required": ["ungrouped_input_bool"],
    "allOf": [
        { "$ref": "#/$defs/input_options" },
        { "$ref": "#/$defs/output_options" }
    ]
}

生成されたパラメータテンプレート：


{
    "input_file": {
        "description": "description for input_file",
        "optional": False
    },
    "input_num": {
        "description": "description for input_num",
        "optional": True
    },
    "output_dir": {
        "description": "description for output_dir",
        "optional": False
    },
    "ungrouped_input_bool": {
        "description": None,
        "optional": False
    }
}

メインファイルの解析

ワークフロー定義に nextflow_schema.json ファイルが含まれていない場合、HealthOmics はメインワークフロー定義ファイルを解析します。

HealthOmics は、メインワークフロー定義ファイルと nextflow.config ファイルにあるparams式を分析します。デフォルト値paramsを持つすべてのはオプションとしてマークされます。

解析を正しく機能させるには、次の要件に注意してください。

HealthOmics は、メインワークフロー定義ファイルのみを解析します。すべてのパラメータを確実にキャプチャするには、すべてのサブモジュールとインポートされたワークフローにparamsワイヤスルーすることをお勧めします。
設定ファイルはオプションです。定義する場合は、名前を付けnextflow.config、メインワークフロー定義ファイルと同じディレクトリに配置します。

次の例は、定義ファイルと生成されたパラメータテンプレートを示しています。


params.input_file = "default.txt"
params.threads = 4
params.memory = "8GB"

workflow {
    if (params.version) {
        println "Using version: ${params.version}"
    }
}

生成されたパラメータテンプレート：


{
    "input_file": {
        "description": None,
        "optional": True
    },
    "threads": {
        "description": None,
        "optional": True
    },
    "memory": {
        "description": None,
        "optional": True
    },
    "version": {
        "description": None,
        "optional": False
    }
}

nextflow.config で定義されているデフォルト値の場合、HealthOmics は、次の例に示すようにparams {}、内で宣言されたparams割り当てとパラメータを収集します。割り当てステートメントでは、はステートメントの左側に表示されるparams必要があります。


params.alpha = "alpha"
params.beta = "beta"

params {
    gamma = "gamma"
    delta = "delta"
}

env {
   // ignored, as this assignment isn't in the params block
   VERSION = "TEST"  
}

// ignored, as params is not on the left side
interpolated_image = "${params.cli_image}"

生成されたパラメータテンプレート：


{
    // other params in your main workflow defintion
    "alpha": {
        "description": None,
        "optional": True
    },
    "beta": {
        "description": None,
        "optional": True
    },
    "gamma": {
        "description": None,
        "optional": True
    },
    "delta": {
        "description": None,
        "optional": True
    }
}

ネストされたパラメータ

nextflow_schema.json との両方がネストされたパラメータnextflow.configを許可します。ただし、HealthOmics パラメータテンプレートでは、最上位のパラメータのみが必要です。ワークフローでネストされたパラメータを使用する場合は、そのパラメータの入力として JSON オブジェクトを指定する必要があります。

スキーマファイルにネストされたパラメータ

HealthOmics は、nextflow_schema.jsonファイルの解析params時にネストされたをスキップします。たとえば、次のnextflow_schema.jsonファイルを定義します。


{
    "properties": {
        "input": {
            "properties": {
                "input_file": { ... },
                "input_num": { ... }
            }
        },
        "input_bool": { ... }
    }
}

HealthOmics は、パラメータテンプレートを生成するinput_numときに input_fileとを無視します。


{
    "input": {
        "description": None,
        "optional": True
    },
    "input_bool": {
        "description": None,
        "optional": True
    }
}

このワークフローを実行すると、HealthOmics は次のような input.json ファイルを想定します。


{
   "input": {
       "input_file": "s3://bucket/obj",
       "input_num": 2
   },
   "input_bool": false
}

設定ファイルにネストされたパラメータ

HealthOmics は、nextflow.configファイルにネストされた params を収集せず、解析中にスキップします。たとえば、次のnextflow.configファイルを定義します。


params.alpha = "alpha"
  params.nested.beta = "beta"
  
  params {
      gamma = "gamma"
      group {
          delta = "delta"
      }
  }

HealthOmics は、パラメータテンプレートを生成するparams.group.deltaときに params.nested.betaとを無視します。


{
    "alpha": {
        "description": None,
        "optional": True
    },
    "gamma": {
        "description": None,
        "optional": True
    }
}

Nextflow 補間の例

次の表は、メインファイル内のパラメータの Nextflow 補間の例を示しています。

パラメータ	必須
params.input_file	あり
params.input_file = "s3://bucket/data.json"	なし
params.nested.input_file	該当なし
params.nested.input_file = "s3://bucket/data.json"	該当なし

次の表は、 nextflow.config ファイル内のパラメータの Nextflow 補間の例を示しています。

パラメータ	必須
`params.input_file = "s3://bucket/data.json"`	なし
`params { input_file = "s3://bucket/data.json" }`	いいえ
`params { nested { input_file = "s3://bucket/data.json" } }`	該当なし
`input_file = params.input_file`	該当なし

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

HealthOmics ワークフローのワークフロー定義の記述

Amazon ECR イメージ