翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# 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-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`

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 URI または HealthOmics Storage URI での glob URIs。 URIs HealthOmics `path` または `file`チャネルの作成には、ワークフロー定義で Glob パターンを使用します。予想される動作と正確なケースについては、「」を参照してください[Nextflow Amazon S3 入力での Glob パターンの処理](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` ディレクティブを使用して、タスクエラーの戦略を定義します。デフォルトでは、タスクがエラー表示 (ゼロ以外の終了ステータス) で戻ると、タスクは停止し、HealthOmics は実行全体を終了します。`errorStrategy` を に設定すると`retry`、HealthOmics は失敗したタスクを 1 回再試行します。再試行回数を増やすには、「」を参照してください[を使用したタスクの再試行 `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 は失敗したタスクの再試行を試行しないか、 を設定すると 1 回の再試行を試行します`errorStrategy`。最大再試行回数を増やすには、 を `errorStrategy` に設定`retry`し、 `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 および v24 では、サービスエラー (5XX HTTP ステータスコード) が原因でタスクが失敗した場合、HealthOmics はタスクの再試行をサポートします。デフォルトでは、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 および v24 ワークフローでは、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`、、`m``h`または の 1 `s`つ以上の単位を使用して指定します`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-task-content-nextflow"></a>

Nextflow で記述されたワークフローの場合、タスクコンテンツを出力 Amazon S3 バケットにエクスポートする **publishDir** ディレクティブを定義します。次の例に示すように、**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
    """
  }
```