HealthOmics 工作流程的参数模板文件 - AWS HealthOmics
生成参数模板

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

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 类型都被标记为必填的输入参数。

  • 任何具有默认值的参数都被标记为可选的输入参数。

  • 描述是从main工作流定义的label部分中提取的。如果label未指定，则描述将为空（空字符串）。

下表显示了 CWL 插值示例。对于每个示例，参数名称均为x。如果参数为必填项，则必须为该参数提供一个值。如果参数是可选的，则无需提供值。

下表显示了原始类型的 CWL 插值示例。

输入 输入/输出示例 必需 
x:               
  type: int
 1 或 2 或... 是 
x:               
  type: int
  default: 2
 默认值为 2。有效输入为 1 或 2 或... 否 
x:               
  type: int?
 有效输入为 “无”、“1” 或 “2” 或... 否 
x:               
  type: int?
  default: 2
 默认值为 2。有效输入为 “无”、“1” 或 “2” 或... 否

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

输入 输入/输出示例 必需 
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?

[无] 或 “无” 或 [1,2,3] 或 [无，3] 但不是 []

 否

WDL 的参数检测

在 WDL 工作流引擎中，解析逻辑做出了以下假设：

  • 任何支持为空的类型都被标记为可选的输入参数。

  • 对于支持不可为空的类型：

    • 任何具有字面值或表达式赋值的输入变量都被标记为可选参数。例如：

       Int x = 2 
Float f0 = 1.0 + f1

    • 如果没有为输入参数分配任何值或表达式，则它们将被标记为必填参数。

  • 描述是从main工作流程定义parameter_meta中提取的。如果parameter_meta未指定，则描述将为空（空字符串）。有关更多信息，请参阅参数元数据的 WDL 规范。

下表显示了 WDL 插值示例。对于每个示例，参数名称均为x。如果参数为必填项，则必须为该参数提供一个值。如果参数是可选的，则无需提供值。

下表显示了基元类型的 WDL 插值示例。

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

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

输入 输入/输出示例 必需
数组 [整数] x [1,2,3] 或 [] 是
数组 [整数] + x [1]，但不是 [] 是
数组 [整数]？ x 无或 [] 或 [1,2,3] 否
数组 [整数？] x [] 或 [无、3、无] 是
数组 [整数？] =？ x [无] 或 “无” 或 [1,2,3] 或 [无，3] 但不是 [] 否
结构示例 {字符串 a，整数 y}

稍后在输入中：示例 mySample

 
String a = mySample.a
   Int y = mySample.y
 是
结构示例 {字符串 a，整数 y}

稍后在输入中：样本？ 我的样本

 
if (defined(mySample)) { 
     String a = mySample.a
     Int y = mySample.y
   }
否

Nextflow 参数检测

对于 Nextflow，通过解析文件来 HealthOmics 生成参数模板。nextflow_schema.json如果工作流定义不包括架构文件，则 HealthOmics 解析主工作流定义文件。

解析架构文件

为了使解析正常工作，请确保架构文件满足以下要求：

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 分析在主工作流定义文件和文件中找到的paramsnextflow.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
    }
}

嵌套参数

两者兼nextflow_schema.json而有之，并nextflow.config允许嵌套参数。但是， HealthOmics 参数模板只需要顶级参数。如果您的工作流程使用嵌套参数，则必须提供一个 JSON 对象作为该参数的输入。

架构文件中的嵌套参数

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
}
配置文件中的嵌套参数

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

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

参数 必需
params.input_fil 是
params.input_file = “s3://bucket/data.json” 否
params.nested.input_file 不适用
params.nested.input_file = “s3://bucket/data.json” 不适用

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

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