本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# Nextflow 工作流程定义细节
<a name="workflow-definition-nextflow"></a>

HealthOmics 支持 Next DSL1 flow 和。 DSL2有关更多信息，请参阅 [Nextflow版本支持](workflows-lang-versions.md#workflows-lang-versions-nextflow)。

Nextflow 基 DSL2 于 Groovy 编程语言，因此参数是动态的，并且可以使用与 Groovy 相同的规则进行类型强制。输入 JSON 提供的参数和值可在工作流程的参数 (`params`) 映射中找到。

**Topics**
+ [使用 nf 架构和 nf 验证插件](#schema-and-validation-plugins-nextflow)
+ [指定存储空间 URIs](#storage-uris-nextflow)
+ [下一页流指令](#workflow-nexflow-directives)
+ [导出工作流程级别的内容](#exporting-workflow-content-nextflow)
+ [导出任务内容](#exporting-task-content-nextflow)

## 使用 nf 架构和 nf 验证插件
<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-core-utils`、和 `nf-fgbio` `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`插件的新版本。有关更多信息，请参阅 [Next GitHub flow 存储库中的 nf-schema](https://github.com/nextflow-io/nf-schema)。

## 指定存储空间 URIs
<a name="storage-uris-nextflow"></a>

使用 Amazon S3 或 HealthOmics URI 构建 Nextflow 文件或路径对象时，只要授予读取权限，它就会使匹配的对象可供工作流程使用。Amazon S3 URIs 允许使用前缀或目录。有关示例，请参阅 [亚马逊 S3 输入参数格式](workflows-run-inputs.md#s3-run-input-formats)。

HealthOmics 部分支持在 Amazon S3 URIs 或 HealthOmics 存储 URIs中使用全局模式。在工作流程定义中使用 Glob 模式来创建`path`或`file`频道。有关预期行为和确切情况，请参阅[Nextflow 处理 Amazon S3 输入中的 Glob 模式](workflows-run-inputs.md#wd-nextflow-s3-formats)。

## 下一页流指令
<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 终止整个运行。如果设置为`retry`，则 HealthOmics 尝试`errorStrategy`对失败的任务进行一次重试。要增加重试次数，请参阅[使用任务重试尝试 `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`要增加最大重试次数，请使用该`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 及更高版本，如果任务由于服务错误而失败（5XX HTTP 状态代码），则 HealthOmics 支持任务重试。默认情况下，最多 HealthOmics 会尝试对失败的任务进行两次重试。

您可以配置`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. 任务超时时， 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 存储桶。如以下示例所示，将 p **ublishDir** 值设置为。`/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)。