本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 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 插補範例。


| 輸入 | 輸入/輸出範例 | 必要 | 
| --- | --- | --- | 
|  <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>  | 有效輸入為無或 1 或 2 或 ... | 否 | 
|  <pre>x:               <br />  type: int?<br />  default: 2</pre>  | 預設值為 2。有效輸入為無或 1 或 2 或 ... | 否 | 

下表顯示複雜類型的 CWL 插補範例。複雜類型是基本類型的集合。


| 輸入 | 輸入/輸出範例 | 必要 | 
| --- | --- | --- | 
|  <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>  |  【無】 或 無 或 【1，2，3】 或 【無，3】 但 【】  | 否 | 

### WDL 的參數偵測
<a name="parameter-parsing-wdl"></a>

在 WDL 工作流程引擎中，剖析邏輯會做出下列假設：
+ 任何 null 支援的類型都會標示為選用的輸入參數。
+ 對於非 Null 支援的類型：
  + 任何指派常值或表達式的輸入變數都會標示為選用參數。例如：

    ```
     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 插補範例。


| 輸入 | 輸入/輸出範例 | 必要 | 
| --- | --- | --- | 
| 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 插補範例。複雜類型是基本類型的集合。


| 輸入 | 輸入/輸出範例 | 必要 | 
| --- | --- | --- | 
| Array【Int】 x | 【1，2，3】 或 【】 | 是 | 
| Array【Int】\$1 x | 【1】，但不是 【】 | 是 | 
| Array【Int】？ x | 無 或 【】 或 【1，2，3】 | 否 | 
| Array【Int？】 x | 【】 或 【無、3、無】 | 是 | 
| Array【Int？】=？ x | 【無】 或 無 或 【1，2，3】 或 【無，3】 但 【】 | 否 | 
| 結構範例 \$1String a， Int y\$1 稍後在輸入中：mySample 範例  |  <pre>String a = mySample.a<br />   Int y = mySample.y</pre>  | 是 | 
| 結構範例 \$1String 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，如下列任一結構描述所定義：
  + https：//[json-schema.org/draft/2020-12/schema](https://json-schema.org/draft/2020-12/schema)。
  + https：//[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 | N/A | 
| params.nested.input\$1file = "s3：//bucket/data.json" | N/A | 

下表顯示 `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>  | N/A | 
|  <pre>input_file = params.input_file</pre>  | N/A |