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

# 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 이상에서는 HealthOmics가 nf-schema@2.3.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 패턴 사용을 부분적으로 지원합니다. 워크플로 정의에서 Glob 패턴을 사용하여 `path` 또는 `file` 채널을 생성합니다. 예상되는 동작과 정확한 사례는 단원을 참조하십시오[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\$12분입니다.

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) 참조하세요.