기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

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


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


| 입력 | 입력/출력 예제 | 필수 | 
| --- | --- | --- | 
| 배열[Int] x | [1,2,3] 또는 [] | 예 | 
| 배열[Int]\$1 x | [1]이지만 []는 아님 | 예 | 
| 배열[Int]? x | 없음 또는 [] 또는 [1,2,3] | 아니요 | 
| 배열[Int?] x | [] 또는 [없음, 3, 없음] | 예 | 
| 배열[Int?]=? 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 입력의 후반부: 샘플? 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입니다.
  + [json-schema.org/draft/2020-12/schema](https://json-schema.org/draft/2020-12/schema).
  + [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 |