本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 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 类型都被标记为必填的输入参数。
+ 任何具有默认值的参数都被标记为可选的输入参数。
+ 描述是从`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 工作流引擎中，解析逻辑做出了以下假设：
+ 任何支持为空的类型都被标记为可选的输入参数。
+ 对于支持不可为空的类型：
  + 任何具有字面值或表达式赋值的输入变量都被标记为可选参数。例如：

    ```
     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 插值示例。


| 输入 | 输入/输出示例 | 必需 | 
| --- | --- | --- | 
| 整数 x | 1 或 2 或... | 是 | 
| 整数 x = 2 | 2 | 否 | 
| Int x = 1\$12 | 3 | 否 | 
| 整数 x = y\$1z | y\$1z | 否 | 
| 整数？ x | 无、1 或 2 或... | 是 | 
| 整数？ x = 2 | 无或 2 | 否 | 
| 整数？ x = 1\$12 | 无或 3 | 否 | 
| 整数？ x = y\$1z | 无或 y\$1z | 否 | 

下表显示了复杂类型的 WDL 插值示例。复杂类型是原始类型的集合。


| 输入 | 输入/输出示例 | 必需 | 
| --- | --- | --- | 
| 数组 [整数] x | [1,2,3] 或 [] | 是 | 
| 数组 [整数] \$1 x | [1]，但不是 [] | 是 | 
| 数组 [整数]？ x | 无或 [] 或 [1,2,3] | 否 | 
| 数组 [整数？] x | [] 或 [无、3、无] | 是 | 
| 数组 [整数？] =？ x | [无] 或 “无” 或 [1,2,3] 或 [无，3] 但不是 [] | 否 | 
| 结构示例 \$1字符串 a，整数 y\$1 稍后在输入中：示例 mySample  |  <pre>String a = mySample.a<br />   Int y = mySample.y</pre>  | 是 | 
| 结构示例 \$1字符串 a，整数 y\$1 稍后在输入中：样本？ 我的样本 |  <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 架构。 org/draft/2020-12/schema](https://json-schema.org/draft/2020-12/schema)。
  + [json 架构。 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 分析在主工作流定义文件和文件中找到的`params``nextflow.config`表达式。所有`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 解析文件**params**时会跳过嵌套。`nextflow_schema.json`例如，如果您定义了以下`nextflow_schema.json`文件：

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

HealthOmics 忽略`input_file`，`input_num`当它生成参数模板时：

```
{
    "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 不收集嵌套**params**在`nextflow.config`文件中，并在解析过程中跳过它们。例如，如果您定义了以下`nextflow.config`文件：

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

HealthOmics 忽略`params.nested.beta`，`params.group.delta`当它生成参数模板时：

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

#### Nextflow 插值示例
<a name="parameter-parsing-nextflow-examples"></a>

下表显示了主文件中参数的 Nextflow 插值示例。


| 参数 | 必需 | 
| --- | --- | 
| params.input\$1fil | 是 | 
| params.input\$1file = “s3://bucket/data.json” | 否 | 
| params.nested.input\$1file | 不适用 | 
| params.nested.input\$1file = “s3://bucket/data.json” | 不适用 | 

下表显示了文件中参数的 Nextflow 插值示例。`nextflow.config`


| 参数 | 必需 | 
| --- | --- | 
|  <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>  | 不适用 |