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

輸入	輸入/輸出範例	必要
`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 工作流程引擎中，剖析邏輯會做出下列假設：

任何 null 支援的類型都會標示為選用的輸入參數。
對於非 Null 支援的類型：
- 任何指派常值或表達式的輸入變數都會標示為選用參數。例如：
```
 Int x = 2 
Float f0 = 1.0 + f1
```
- 如果未將值或表達式指派給輸入參數，則會將其標記為必要參數。
描述是從main工作流程定義parameter_meta中的擷取。如果parameter_meta未指定，則描述將為空白（空字串）。如需詳細資訊，請參閱參數中繼資料的 WDL 規格。

下表顯示 WDL 插補範例。對於每個範例，參數名稱為 x。如果需要參數，您必須提供參數的值。如果參數是選用的，則不需要提供值。

此資料表顯示基本類型的 WDL 插補範例。

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

輸入	輸入/輸出範例	必要
Array【Int】 x	【1，2，3】或【】	是
Array【Int】+ x	【1】，但不是【】	是
Array【Int】？ x	無或【】或【1，2，3】	否
Array【Int？】 x	【】或【無、3、無】	是
Array【Int？】=？ x	【無】或無或【1，2，3】或【無，3】但【】	否
結構範例 {String a， Int y} 稍後在輸入中：mySample 範例	`String a = mySample.a Int y = mySample.y`	是
結構範例 {String 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，如下列任一結構描述所定義：
- https：//json-schema.org/draft/2020-12/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
    }
}

剖析主要檔案

如果工作流程定義不包含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	N/A
params.nested.input_file = "s3：//bucket/data.json"	N/A

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

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

撰寫 HealthOmics 工作流程的工作流程定義

Amazon ECR 映像