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 보간 예제가 나와 있습니다.

입력	입력/출력 예제	필수
정수 x	1 또는 2 또는 ...	예
정수 x = 2	2	아니요
정수 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 보간 예제가 나와 있습니다. 복합 유형은 기본 유형의 모음입니다.

입력	입력/출력 예제	필수
배열[Int] x	[1,2,3] 또는 []	예
배열[Int]+ x	[1]이지만 []는 아님	예
배열[Int]? x	없음 또는 [] 또는 [1,2,3]	아니요
배열[Int?] x	[] 또는 [없음, 3, 없음]	예
배열[Int?]=? x	[없음] 또는 없음 또는 [1,2,3] 또는 [없음, 3]이지만 []는 아님	아니요
구조 샘플 {문자열 a, 정수 y} 입력의 뒷부분: 샘플 mySample	String a = mySample.a Int y = mySample.y	예
구조 샘플 {문자열 a, 정수 y} 입력의 후반부: 샘플? mySample	if (defined(mySample)) { String a = mySample.a Int y = mySample.y }	아니요

Nextflow에 대한 파라미터 감지

Nextflow의 경우 HealthOmics는 nextflow_schema.json 파일을 구문 분석하여 파라미터 템플릿을 생성합니다. 워크플로 정의에 스키마 파일이 포함되지 않은 경우 HealthOmics는 기본 워크플로 정의 파일을 구문 분석합니다.

주제

• 스키마 파일 구문 분석

• 기본 파일 구문 분석

• 중첩 파라미터

• Nextflow 보간의 예

스키마 파일 구문 분석

구문 분석이 올바르게 작동하려면 스키마 파일이 다음 요구 사항을 충족하는지 확인합니다.

• 스키마 파일의 이름은 이며 기본 워크플로 파일nextflow_schema.json과 동일한 디렉터리에 있습니다.

• 스키마 파일은 다음 스키마 중 하나에 정의된 유효한 JSON입니다.

  • json-schema.org/draft/2020-12/schema.

  • 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