翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# HealthOmics ワークフローのパラメータテンプレートファイル
<a name="parameter-templates"></a>

パラメータテンプレートは、ワークフローの入力パラメータを定義します。入力パラメータを定義して、ワークフローの柔軟性と汎用性を高めることができます。たとえば、参照ゲノムファイルの 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
  }
}
```

## パラメータテンプレートの生成
<a name="parameter-parsing"></a>

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

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

**Topics**
+ [CWL のパラメータ検出](#parameter-parsing-cwl)
+ [WDL のパラメータ検出](#parameter-parsing-wdl)
+ [Nextflow のパラメータ検出](#parameter-parsing-nextflow)

### CWL のパラメータ検出
<a name="parameter-parsing-cwl"></a>

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

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

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


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

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


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

### WDL のパラメータ検出
<a name="parameter-parsing-wdl"></a>

WDL ワークフローエンジンでは、解析ロジックは次の前提になります。
+ NULL 対応タイプは、オプションの入力パラメータとしてマークされます。
+ nullable 以外のサポート対象タイプの場合：
  + リテラルまたは式が割り当てられた入力変数は、オプションパラメータとしてマークされます。例:

    ```
     Int x = 2 
    Float f0 = 1.0 + f1
    ```
  + 入力パラメータに値または式が割り当てられていない場合は、必須パラメータとしてマークされます。
+ 説明は、`main`ワークフロー定義`parameter_meta`の から抽出されます。を指定`parameter_meta`しない場合、説明は空白になります (空の文字列）。詳細については、[パラメータメタデータ](https://github.com/openwdl/wdl/blob/wdl-1.2/SPEC.md#metadata-sections)の WDL 仕様を参照してください。

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

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


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

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


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

### Nextflow のパラメータ検出
<a name="parameter-parsing-nextflow"></a>

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

**Topics**
+ [スキーマファイルの解析](#parameter-parsing-nextflow-schema)
+ [メインファイルの解析](#parameter-parsing-nextflow-main)
+ [ネストされたパラメータ](#parameter-parsing-nextflow-nested)
+ [Nextflow 補間の例](#parameter-parsing-nextflow-examples)

#### スキーマファイルの解析
<a name="parameter-parsing-nextflow-schema"></a>

解析を正しく機能させるには、スキーマファイルが次の要件を満たしていることを確認してください。
+ スキーマファイルは という名前`nextflow_schema.json`で、メインワークフローファイルと同じディレクトリにあります。
+ スキーマファイルは、次のいずれかのスキーマで定義されている有効な JSON です。
  + [json-schema.org/draft/2020-12/schema](https://json-schema.org/draft/2020-12/schema)。
  + [json-schema.org/draft-07/schema](https://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
    }
}
```

#### メインファイルの解析
<a name="parameter-parsing-nextflow-main"></a>

ワークフロー定義に `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
    }
}
```

#### ネストされたパラメータ
<a name="parameter-parsing-nextflow-nested"></a>

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

##### スキーマファイルにネストされたパラメータ
<a name="parameter-parsing-schema-nested"></a>

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
}
```

##### 設定ファイルにネストされたパラメータ
<a name="parameter-parsing-config-nested"></a>

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 補間の例
<a name="parameter-parsing-nextflow-examples"></a>

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


| パラメータ | 必須 | 
| --- | --- | 
| params.input\$1file | あり | 
| params.input\$1file = "s3://bucket/data.json" | なし | 
| params.nested.input\$1file | 該当なし | 
| params.nested.input\$1file = "s3://bucket/data.json" | 該当なし | 

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


| パラメータ | 必須 | 
| --- | --- | 
|  <pre>params.input_file = "s3://bucket/data.json"</pre>  | なし | 
|  <pre>params {<br />   input_file = "s3://bucket/data.json"<br />}</pre>  | いいえ | 
|  <pre>params {<br />   nested {<br />     input_file = "s3://bucket/data.json"    <br />   }<br />}</pre>  | 該当なし | 
|  <pre>input_file = params.input_file</pre>  | 該当なし |