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

# Nextflow 워크플로 정의 세부 정보
<a name="workflow-definition-nextflow"></a>

HealthOmics는 Nextflow DSL1 및 DSL2를 지원합니다. 자세한 내용은 [Nextflow 버전 지원](workflows-lang-versions.md#workflows-lang-versions-nextflow)을 참조하세요.

Nextflow DSL2는 Groovy 프로그래밍 언어를 기반으로 하므로 파라미터는 동적이며 Groovy와 동일한 규칙을 사용하여 강제 유형을 지정할 수 있습니다. 입력 JSON에서 제공하는 파라미터와 값은 워크플로의 파라미터(`params`) 맵에서 사용할 수 있습니다.

**Topics**
+ [nf-schema 및 nf-validation 플러그인 사용](#schema-and-validation-plugins-nextflow)
+ [스토리지 URIs 지정](#storage-uris-nextflow)
+ [Nextflow 지시문](#workflow-nexflow-directives)
+ [워크플로 수준 콘텐츠 내보내기](#exporting-workflow-content-nextflow)
+ [작업 콘텐츠 내보내기](#exporting-task-content-nextflow)

## nf-schema 및 nf-validation 플러그인 사용
<a name="schema-and-validation-plugins-nextflow"></a>

**참고**  
플러그인에 대한 HealthOmics 지원 요약:  
v22.04 - 플러그인을 지원하지 않음
v23.10 - `nf-schema` 및 지원 `nf-validation`
v24.10 - 지원 `nf-schema`
v25.10 - `nf-schema`, `nf-fgbio`, 및 `nf-core-utils`지원 `nf-prov`

HealthOmics는 Nextflow 플러그인에 대해 다음과 같은 지원을 제공합니다.
+ Nextflow v23.10의 경우 HealthOmics는 nf-validation@1.1.1 플러그인을 사전 설치합니다.
+ Nextflow v23.10 및 v24.10의 경우 HealthOmics는 nf-schema@2.3.0 플러그인을 사전 설치합니다.
+ Nextflow v25.10의 경우 HealthOmics는 nf-schema@2.6.1, , nf-prov@1.7.0 및 nf-fgbio@1.0.1 플러그인nf-core-utils@0.4.0 사전 설치합니다.
+ 워크플로 실행 중에는 추가 플러그인을 검색할 수 없습니다. HealthOmics는 `nextflow.config` 파일에서 지정한 다른 플러그인 버전을 무시합니다.
+ Nextflow v24 이상의 경우 `nf-schema`는 더 이상 사용되지 않는 `nf-validation` 플러그인의 새 버전입니다. 자세한 내용은 Nextflow GitHub [ 리포지토리의 nf-schema](https://github.com/nextflow-io/nf-schema)를 참조하세요.

## 스토리지 URIs 지정
<a name="storage-uris-nextflow"></a>

Amazon S3 또는 HealthOmics URI를 사용하여 Nextflow 파일 또는 경로 객체를 구성하는 경우 읽기 액세스 권한이 부여되는 한 워크플로에서 일치하는 객체를 사용할 수 있습니다. Amazon S3 URIs. 예시는 [Amazon S3 입력 파라미터 형식](workflows-run-inputs.md#s3-run-input-formats) 섹션을 참조하세요.

HealthOmics는 Amazon S3 URIs 또는 HealthOmics 스토리지 URIs에서 glob 패턴 사용을 부분적으로 지원합니다. 워크플로 정의에서 `path` 또는 `file` 채널 생성에 Glob 패턴을 사용합니다. 예상되는 동작과 정확한 사례는 단원을 참조하십시오[Amazon S3 입력에서 Glob 패턴의 Nextflow 처리](workflows-run-inputs.md#wd-nextflow-s3-formats).

## Nextflow 지시문
<a name="workflow-nexflow-directives"></a>

Nextflow 구성 파일 또는 워크플로 정의에서 Nextflow 명령을 구성합니다. 다음 목록은 HealthOmics가 구성 설정을 적용하는 데 사용하는 우선 순위의 순서를 가장 낮은 우선 순위부터 가장 높은 우선 순위까지 보여줍니다.

1. 구성 파일의 전역 구성입니다.

1. 워크플로 정의의 작업 섹션입니다.

1. 구성 파일의 작업별 선택기입니다.

**Topics**
+ [를 사용한 작업 재시도 전략 `errorStrategy`](#workflow-nextflow-errorStrategy)
+ [를 사용하여 작업 재시도 `maxRetries`](#workflow-nexflow-task-retry)
+ [를 사용하여 작업 재시도 옵트아웃 `omicsRetryOn5xx`](#workflow-nextflow-retry-5xx)
+ [`time` 지시문을 사용한 작업 기간](#time-directive-nextflow)

### 를 사용한 작업 재시도 전략 `errorStrategy`
<a name="workflow-nextflow-errorStrategy"></a>

`errorStrategy` 지시문을 사용하여 작업 오류에 대한 전략을 정의합니다. 기본적으로 작업이 오류 표시(종료 상태가 0이 아님)와 함께 반환되면 작업이 중지되고 HealthOmics가 전체 실행을 종료합니다. 를 `errorStrategy`로 설정하면 `retry` HealthOmics는 실패한 작업을 한 번 재시도합니다. 재시도 횟수를 늘리려면 섹션을 참조하세요[를 사용하여 작업 재시도 `maxRetries`](#workflow-nexflow-task-retry).

```
process {
    label 'my_label'
    errorStrategy 'retry'

    script:
    """
    your-command-here
    """
}
```

HealthOmics가 실행 중에 작업 재시도를 처리하는 방법에 대한 자세한 내용은 섹션을 참조하세요[작업 재시도](monitoring-runs.md#run-status-task-retries).

### 를 사용하여 작업 재시도 `maxRetries`
<a name="workflow-nexflow-task-retry"></a>

기본적으로 HealthOmics는 실패한 작업의 재시도를 시도하지 않거나를 구성한 경우 한 번의 재시도를 시도합니다`errorStrategy`. 최대 재시도 횟수를 늘리려면를 `retry` `errorStrategy`로 설정하고 `maxRetries` 명령을 사용하여 최대 재시도 횟수를 구성합니다.

다음 예제에서는 글로벌 구성에서 최대 재시도 횟수를 3으로 설정합니다.

```
process {
    errorStrategy = 'retry'
    maxRetries = 3
}
```

다음 예제에서는 워크플로 정의`maxRetries`의 작업 섹션에서를 설정하는 방법을 보여줍니다.

```
process myTask {
    label 'my_label'
    errorStrategy 'retry'
    maxRetries 3
    
    script:
    """
    your-command-here
    """
}
```

다음 예제에서는 이름 또는 레이블 선택기를 기반으로 Nextflow 구성 파일에서 작업별 구성을 지정하는 방법을 보여줍니다.

```
process {
    withLabel: 'my_label' {
        errorStrategy = 'retry'
        maxRetries = 3
    }

    withName: 'myTask' {
        errorStrategy = 'retry'
        maxRetries = 3
    }
}
```

### 를 사용하여 작업 재시도 옵트아웃 `omicsRetryOn5xx`
<a name="workflow-nextflow-retry-5xx"></a>

Nextflow v23 이상의 경우 HealthOmics는 서비스 오류(5XX HTTP 상태 코드)로 인해 작업이 실패한 경우 작업 재시도를 지원합니다. 기본적으로 HealthOmics는 실패한 작업을 최대 2회 재시도합니다.

서비스 오류에 대한 작업 재시도를 옵트아웃`omicsRetryOn5xx`하도록를 구성할 수 있습니다. HealthOmics의 작업 재시도에 대한 자세한 내용은 섹션을 참조하세요[작업 재시도](monitoring-runs.md#run-status-task-retries).

다음 예제에서는 작업 재시도를 옵트아웃하도록 전역 구성`omicsRetryOn5xx`에서를 구성합니다.

```
process {
    omicsRetryOn5xx = false
}
```

다음 예제에서는 워크플로 정의`omicsRetryOn5xx`의 작업 섹션에서를 구성하는 방법을 보여줍니다.

```
process myTask {
    label 'my_label'
    omicsRetryOn5xx = false
    
    script:
    """
    your-command-here
    """
}
```

다음 예제에서는 이름 또는 레이블 선택기를 기반으로 Nextflow 구성 파일에서 작업별 구성`omicsRetryOn5xx`으로를 설정하는 방법을 보여줍니다.

```
process {
    withLabel: 'my_label' {
        omicsRetryOn5xx = false
    }

    withName: 'myTask' {
        omicsRetryOn5xx = false
    }
}
```

### `time` 지시문을 사용한 작업 기간
<a name="time-directive-nextflow"></a>

HealthOmics는 조정 가능한 할당량( 참조[HealthOmics 서비스 할당량](service-quotas.md))을 제공하여 실행의 최대 기간을 지정합니다. Nextflow v23 이상 워크플로의 경우 Nextflow `time` 명령을 사용하여 최대 작업 기간을 지정할 수도 있습니다.

새 워크플로 개발 중에 최대 작업 기간을 설정하면 런어웨이 작업과 장기 실행 작업을 포착하는 데 도움이 됩니다.

Nextflow 시간 명령에 대한 자세한 내용은 Nextflow 참조의 [시간 명령을](https://www.nextflow.io/docs/latest/reference/process.html#process-time) 참조하세요.

HealthOmics는 Nextflow 시간 명령에 대해 다음과 같은 지원을 제공합니다.

1. HealthOmics는 시간 명령에 대해 1분 단위를 지원합니다. 60초에서 최대 실행 기간 값 사이의 값을 지정할 수 있습니다.

1. 60 미만의 값을 입력하면 HealthOmics는 값을 60초로 반올림합니다. 60보다 큰 값의 경우 HealthOmics는 가장 가까운 분으로 내림합니다.

1. 워크플로가 작업에 대한 재시도를 지원하는 경우 HealthOmics는 시간 초과 시 작업을 재시도합니다.

1. 작업이 시간 초과(또는 마지막 재시도 시간이 초과)되면 HealthOmics는 작업을 취소합니다. 이 작업의 지속 시간은 1\~2분입니다.

1. 작업 시간 초과 시 HealthOmics는 실행 및 작업 상태를 실패로 설정하고 실행의 다른 작업(시작 중, 보류 중 또는 실행 중 상태의 작업)을 취소합니다. HealthOmics는 제한 시간 이전에 완료한 작업의 출력을 지정된 S3 출력 위치로 내보냅니다.

1. 작업이 보류 중 상태로 소요한 시간은 작업 기간에 포함되지 않습니다.

1. 실행이 실행 그룹의 일부이고 실행 그룹이 작업 타이머보다 빨리 시간 초과되면 실행 및 작업이 실패 상태로 전환됩니다.

`ms`, , 또는 단위 중 하나 이상을 사용하여 제한 시간을 지정합니다`s``m``h``d`.

다음 예제에서는 Nextflow 구성 파일에서 전역 구성을 지정하는 방법을 보여줍니다. 전역 제한 시간을 1시간 30분으로 설정합니다.

```
process {
    time = '1h30m'
}
```

다음 예제에서는 워크플로 정의의 작업 섹션에서 시간 지시문을 지정하는 방법을 보여줍니다. 이 예제에서는 제한 시간을 3일, 5시간 및 4분으로 설정합니다. 이 값은 구성 파일의 전역 값보다 우선하지만 구성 `my_label` 파일의에 대한 작업별 시간 명령보다 우선하지는 않습니다.

```
process myTask {
    label 'my_label'
    time '3d5h4m'
        
    script:
    """
    your-command-here
    """
}
```

다음 예제에서는 이름 또는 레이블 선택기를 기반으로 Nextflow 구성 파일에서 작업별 시간 지시문을 지정하는 방법을 보여줍니다. 이 예제에서는 글로벌 작업 제한 시간 값을 30분으로 설정합니다. 작업의 경우 값을 2시간`myTask`으로 설정하고 레이블이 인 작업의 경우 값을 3시간으로 설정합니다`my_label`. 선택기와 일치하는 작업의 경우 이러한 값이 워크플로 정의의 전역 값 및 값보다 우선합니다.

```
process {
    time = '30m'
    
    withLabel: 'my_label' {
        time = '3h'  
    }

    withName: 'myTask' {
        time = '2h'  
    }
}
```

## 워크플로 수준 콘텐츠 내보내기
<a name="exporting-workflow-content-nextflow"></a>

Nextflow v25.10의 경우 산지 보고서 또는 파이프라인 DAGs. 이러한 파일을 내보내려면에 기록합니다`/mnt/workflow/output/`. HealthOmics는이 디렉터리에 배치된 파일을 실행의 Amazon S3 출력 위치의 `output/` 접두사로 내보냅니다.

다음 예제에서는에 산지 보고서를 작성하도록 `nf-prov` 플러그인을 구성하는 방법을 보여줍니다`/mnt/workflow/output/`.

```
prov {
    formats {
        bco {
            file = "/mnt/workflow/output/pipeline_info/manifest.bco.json"
        }
    }
}
```

실행의 입력 JSON에서이 경로를 파라미터로 전달할 수도 있습니다. 이 접근 방식은를 사용하는 nf-core 워크플로에서 일반적입니다`params.outdir`.

```
{
    "outdir": "/mnt/workflow/output/"
}
```

## 작업 콘텐츠 내보내기
<a name="exporting-task-content-nextflow"></a>

Nextflow에 작성된 워크플로의 경우 **publishDir** 명령을 정의하여 작업 콘텐츠를 출력 Amazon S3 버킷으로 내보냅니다. 다음 예제와 같이 **publishDir** 값을 로 설정합니다`/mnt/workflow/pubdir`. Amazon S3로 파일을 내보내려면 파일이이 디렉터리에 있어야 합니다.

```
 nextflow.enable.dsl=2
              
  workflow {
    CramToBamTask(params.ref_fasta, params.ref_fasta_index, params.ref_dict, params.input_cram, params.sample_name)
    ValidateSamFile(CramToBamTask.out.outputBam)
  }
  
  process CramToBamTask {
    container "<account>.dkr.ecr.us-west-2.amazonaws.com/genomes-in-the-cloud"
  
    publishDir "/mnt/workflow/pubdir"
  
    input:
        path ref_fasta
        path ref_fasta_index
        path ref_dict
        path input_cram
        val sample_name
  
    output:
        path "${sample_name}.bam", emit: outputBam
        path "${sample_name}.bai", emit: outputBai
  
    script:
    """
        set -eo pipefail
  
        samtools view -h -T $ref_fasta $input_cram |
        samtools view -b -o ${sample_name}.bam -
        samtools index -b ${sample_name}.bam
        mv ${sample_name}.bam.bai ${sample_name}.bai
    """
  }
  
  process ValidateSamFile {
    container "<account>.dkr.ecr.us-west-2.amazonaws.com/genomes-in-the-cloud"
  
    publishDir "/mnt/workflow/pubdir"
  
    input:
        file input_bam
  
    output:
        path "validation_report"
  
    script:
    """
        java -Xmx3G -jar /usr/gitc/picard.jar \
        ValidateSamFile \
        INPUT=${input_bam} \
        OUTPUT=validation_report \
        MODE=SUMMARY \
        IS_BISULFITE_SEQUENCED=false
    """
  }
```

Nextflow v25.10의 경우 `publishDir`의 대안으로 워크플로 출력을 사용하여 작업 콘텐츠를 내보낼 수 있습니다. 다음 예제에서는 작업 결과를 Amazon S3로 내보내는 워크플로 `output` 블록을 정의하는 방법을 보여줍니다.

```
process myTask {
    input:
    val data

    output:
    path 'result.txt'

    script:
    """
    echo ${data} > result.txt
    """
}

workflow {
    main:
    output_file = myTask('hello')

    publish:
    results = output_file
}

output {
    results {
        path '.'
    }
}
```

워크플로 출력에 대한 자세한 내용은 Nextflow 설명서의 [워크플로 출력을](https://www.nextflow.io/docs/latest/workflow.html#workflow-output-def) 참조하세요.