生信自动化流程搭建 06 | 指令

使用指令声明块，可以提供将影响当前进程执行的可选设置。

他们必须在过程的顶部进入人体，在任何其他声明块（即input，output等），并具有以下语法：

name value [, value2 [,..]]

一些指令通常可用于所有进程，另一些则取决于当前定义的执行器。

指令是：

acceleratorse

该accelerator指令允许指定任务执行的硬件加速器要求，例如GPU处理器。例如：

process foo {
    accelerator 4, type: 'nvidia-tesla-k80'

    script:
    """
    your_gpu_enabled --command --line
    """
}

上面的示例将请求4个nvidia-tesla-k80类型的GPU 。

该指令仅受AWS Batch，Google Life Sciences和Kubernetes执行程序支持。

加速器type选项值取决于目标执行平台。有关可用加速器的详细信息，请参阅目标平台文档。AWS Google Kubernetes。

afterScript

afterScript指令允许在主进程运行后立即执行自定义（Bash）代码段。这对于清理暂存区可能很有用。

beforeScript

该beforeScript指令允许在运行主流程脚本之前执行自定义（Bash）代码段。这对于初始化基础群集环境或其他自定义初始化可能很有用。

例如：

process foo {

  beforeScript 'source /cluster/bin/setup'

  """
  echo bar
  """

}

cache

cache指令允许将过程结果存储到本地缓存中。启用高速缓存并使用resume选项启动管道.

随后执行该过程的任何尝试以及相同的输入都会导致该过程的执行被跳过。

默认情况下已启用缓存，可以通过将cache 指令设置为来禁用特定进程的缓存false。例如：

process noCacheThis {
  cache false

  script:
  
}

该cache指令可能值列于下表中：

值	描述
`false`	禁用缓存功能。
`true` （默认）	启用缓存。创建高速缓存键，以索引输入文件的元数据信息（名称，大小和最后更新时间戳记属性）。
`'deep'`	启用缓存。创建高速缓存键，为输入文件的内容建立索引。
`'lenient'`	启用缓存。将创建索引索引输入文件路径和大小属性的缓存键（此策略提供了一种变通方法，用于解决由于文件时间戳不一致而导致在共享文件系统上观察到的不正确的缓存失效；需要版本0.32.x或更高版本）。

conda

conda指令允许使用Conda 包管理器定义流程依赖项。

Nextflow自动为conda指令中列出的给定包名称设置环境。例如：

process foo {
  conda 'bwa=0.7.15'

  '''
  your_command --here
  '''
}

可以指定多个软件包，用空格分隔它们，比如bwa=0.7.15 fastqc=0.11.5。

可以使用通常的Conda表示法指定需要从中下载特定软件包的频道名称，即在软件包前面加上频道名称，比如，bioconda::bwa=0.7.15

该conda目录还允许指定Conda环境文件路径或现有环境目录的路径。有关更多详细信息，请参见Conda环境页面。

container

container指令允许在Docker容器中执行流程脚本。

它要求Docker守护程序必须在执行管道的计算机中运行，即在使用本地执行器的本地计算机或在通过网格执行器部署管道的群集节点中运行。

例如：

process runThisInDocker {

  container 'dockerbox:tag'

  """
  
  """

}

只需在上面的脚本dockerbox:tag中用要使用的Docker映像名称替换即可。

这对于在可复制的独立环境中执行脚本或在云中部署管道非常有用。

对于本地执行的进程，将忽略此伪指令。

containerOptions

containerOptions指令允许指定基础容器引擎支持的任何容器执行选项（即Docker，Singularity等）。这对于仅为特定进程提供容器设置非常有用，例如，安装自定义路径：

process runThisWithDocker {

    container 'busybox:latest'
    containerOptions '--volume /data/db:/db'

    output: file 'output.txt'

    '''
    your_command --data /db > output.txt
    '''
}

AWS Batch和Kubernetes执行程序不支持此功能。

cpus

cpus指令允许定义进程任务所需的（逻辑）CPU数量。例如：

process big_job {

  cpus 8
  executor 'sge'

  """
  blastp -query input_sequence -num_threads ${task.cpus}
  """
}

执行多进程或多线程命令/工具的任务需要此伪指令，并且当通过集群资源管理器执行管道任务时，该伪指令旨在保留足够的CPU。

clusterOptions

clusterOptions指令允许使用群集提交命令接受的任何本机配置选项。可以使用它来请求非标准资源，也可以使用特定于群集且不受Nextflow即时支持的设置。

仅当使用基于网格的执行程序时才考虑此指令： SGE，LSF，SLURM，PBS / Torque，PBS Pro， Moab和HTCondor执行程序。

disk

disk指令允许定义允许该进程使用多少本地磁盘存储。例如：

process big_job {

    disk '2 GB'
    executor 'cirrus'

    """
    your task script here
    """
}

指定磁盘值时，可以使用以下存储单元后缀：

Unit	Description
B	Bytes
KB	Kilobytes
MB	Megabytes
GB	Gigabytes
TB	Terabytes

当前，只有Ignite 和HTCondor执行程序才考虑使用此指令。

echo

默认情况下，将忽略所有进程中执行的命令所产生的标准输出。将echo指令设置为true可以将进程stdout转发到当前运行最频繁的进程stdout文件，并在shell终端中显示该文件。

例如：

process sayHello {
  echo true

  script:
  "echo Hello"
}

Hello

如果不指定echo true，执行以上示例时将看不到打印出的字符串Hello。

errorStrategy

errorStrategy指令允许定义流程如何管理错误条件。

默认情况下，当执行的脚本返回错误状态时，该过程将立即停止。会使整个管道终止。

可用的错误策略表：

名称	Executor
`terminate`	报告错误情况后立即终止执行。待处理的作业被杀死（默认）
`finish`	当出现错误情况时，启动有序的管道关闭，等待任何提交的作业的完成。
`ignore`	忽略进程执行错误。
`retry`	重新提交执行以返回错误条件的进程。

ignore

当将errorStrategy指令设置为ignore进程不会在错误情况下停止，它只会报告一条消息，通知错误事件。

例如：

process ignoreAnyError {
   errorStrategy 'ignore'

   script:
   
}

根据定义，命令脚本以非零退出状态结束时会失败。要更改此行为，请参见validExitStatus。

retry

retry 错误策略，让你重新提交以供执行的过程返回一个错误条件。例如：

process retryIfFail {
   errorStrategy 'retry'

   script:
   
}

重新执行失败进程的次数由maxRetries和maxErrors指令定义。

可以使用动态errorStrategy 指令定义取决于任务退出状态或其他参数值的更复杂的策略。有关详细信息，请参见“ 动态指令”部分。

executor

executor 定义执行 processes 的基础系统。默认情况下，进程使用nextflow.config文件中全局定义的 executor。

executor指令允许配置进程必须使用的执行程序，可以使用以下值：

名称	执行者
`local`	在启动Nextflow的计算机中执行该过程
`sge`	该过程使用Sun Grid Engine / Open Grid Engine执行
`uge`	该过程是使用Univa Grid Engine作业计划程序执行的
`lsf`	该过程是使用Platform LSF作业计划程序执行的
`slurm`	该过程使用SLURM作业调度程序执行
`pbs`	使用PBS / Torque作业计划程序执行该过程
`pbspro`	该过程使用PBS Pro作业计划程序执行
`moab`	该过程是使用Moab作业计划程序执行的
`condor`	使用HTCondor作业计划程序执行该过程
`nqsii`	该过程是使用NQSII作业计划程序执行的
`ignite`	该过程是使用Apache Ignite集群执行的
`k8s`	该过程是使用Kubernetes集群执行的
`awsbatch`	该过程是使用AWS Batch服务执行的
`google-pipelines`	该过程是使用Google Genomics Pipelines服务执行的

以下示例显示如何设置流程的执行程序：

process doSomething {

   executor 'sge'

   script:
   

}

每个 executor 提供一组配置选项，可以在指令声明块中进行设置。请参阅执行程序部分，以了解特定的执行程序指令。

ext

ext是作为一种特殊的指令，用于用户自定义过程指令的名称空间。这对于高级配置选项很有用。例如：

process mapping {
  container "biocontainers/star:${task.ext.version}"

  input:
  file genome from genome_file
  set sampleId, file(reads) from reads_ch

  """
  STAR --genomeDir $genome --readFilesIn $reads
  """
}

在上面的示例中，该过程使用一个容器，其版本由ext.version属性控制。可以在nextflow.config文件中定义它，如下所示：

process.ext.version = '2.5.3'

machineType

machineType可用于指定一个预定义的谷歌计算平台机型。

该指令是可选的，如果指定，它将覆盖cpus和memory指令：

process foo {
  machineType 'n1-highmem-8'

  """
  
  """
}

此功能需要Nextflow 19.07.0或更高版本。

maxErrors

maxErrors指令允许指定使用retry 错误策略时进程失败的最大次数。默认情况下，此指令是禁用的，可以按以下示例所示进行设置：

process retryIfFail {
  errorStrategy 'retry'
  maxErrors 5

  """
  echo 'do this as that .. '
  """
}

此设置考虑所有实例中给定进程累积的总错误。如果要控制流程实例（又称任务）失败的次数，请使用maxRetries。

maxForks

maxForks指令允许定义可以并行执行的最大流程实例数。默认情况下，该值等于可用CPU核心数减去1。

如果要按顺序执行进程，请将此伪指令设置为一个。例如：

process doNotParallelizeIt {

   maxForks 1

   '''
   
   '''

}

maxRetries

maxRetries指令允许定义在发生故障时可以重新提交流程实例的最大次数。仅当使用retry 错误策略时才应用此值。默认情况下，只允许重试一次，可以如下所示增加此值：

process retryIfFail {
    errorStrategy 'retry'
    maxRetries 3

    """
    echo 'do this as that .. '
    """
}

maxRetries和maxErrors指令之间有一个细微但重要的区别。后者定义了流程执行期间允许的错误总数（同一流程可以启动不同的执行实例），而maxRetries定义了在发生错误的情况下可以重试同一流程执行的最大次数。

另请参见：errorStrategy和maxErrors。

memory

memory指令允许定义允许该进程使用多少内存。例如：

process big_job {

    memory '2 GB'
    executor 'sge'

    """
    your task script here
    """
}

指定存储值时，可以使用以下存储单元后缀：

Unit	Description
B	Bytes
KB	Kilobytes
MB	Megabytes
GB	Gigabytes
TB	Terabytes

module

Environment Modules是一个程序包管理器，它使可以动态配置执行环境，并轻松在同一软件工具的多个版本之间切换。

如果系统中可用，则可以将其与Nextflow一起使用，以便在管道中配置流程执行环境。

在流程定义中，可以使用module指令加载要在流程执行环境中使用的特定模块版本。例如：

process basicExample {

  module 'ncbi-blast/2.2.27'

  """
  blastp -query 
  """
}

可以module为需要加载的每个模块重复该指令。或者，可以module通过使用: （冒号）字符分隔所有模块名称，从而在一个指令中指定多个模块，如下所示：

 process manyModules {

   module 'ncbi-blast/2.2.27:t_coffee/10.0:clustalw/2.1'

   """
   blastp -query 
   """
}

penv

该penv指令允许定义将并行任务提交给SGE资源管理器时要使用的并行环境。例如：

process big_job {

  cpus 4
  penv 'smp'
  executor 'sge'

  """
  blastp -query input_sequence -num_threads ${task.cpus}
  """
}

此配置取决于Grid Engine安装程序提供的并行环境。

使用SGE执行程序时，此设置可用。

pod

pod使用Kubernetes执行程序时，该指令允许定义Pod的特定设置。

例如：

process your_task {
  pod env: 'FOO', value: 'bar'

  '''
  echo $FOO
  '''
}

上面的片段定义了名为的环境变量FOO，其值是bar。

该pod指令允许定义以下选项：

`label: <K>, value: <V>`	用key `K`和value 定义一个pod标签`V`。
`annotation: <K>, value: <V>`	用key `K`和value 定义一个pod注解`V`。
`env: <E>, value: <V>`	用名称定义一个环境变量，`E`其值由`V`字符串给定。
`env: <E>, config: <C/K>`	用name定义一个环境变量，`E`其值由与name `K`中的ConfigMap中与name 的键相关联的条目给出`C`。
`env: <E>, secret: <S/K>`	定义一个名称为name的环境变量，`E`其值由与名称`K`为Secret的Secret中具有名称的键关联的条目给出`S`。
`config: <C/K>, mountPath: </absolute/path>`	名称为key 的ConfigMap的内容可用于该路径。当省略关键组件时，该路径将解释为目录，并且所有ConfigMap条目都将在该路径中显示。C``K``/absolute/path
`secret: <S/K>, mountPath: </absolute/path>`	带有名称和密钥的Secret的内容可用于该路径。当省略关键组件时，该路径将解释为目录，并且所有Secret条目都将在该路径中显示。S``K``/absolute/path
`volumeClaim: <V>, mountPath: </absolute/path>`	将名称为Persistent volume的声明挂载`V`到指定的路径位置。使用可选的subPath参数将目录挂载在引用的卷中，而不是其根目录中。
`imagePullPolicy: <V>`	指定用于拉出容器映像的策略，例如。`imagePullPolicy: 'Always'`
`imagePullSecret: <V>`	指定用于访问私有容器映像注册表的秘密名称。有关详细信息，请参见Kubernetes文档。
`runAsUser: <UID>`	指定用于运行容器的用户标识。
`nodeSelector: <V>`	指定进程将在哪个节点上运行。有关详细信息，请参见Kubernetes nodeSelector。

在Nextflow配置文件中定义时，可以使用规范的关联数组语法定义容器设置。例如：

process {
  pod = [env: 'FOO', value: 'bar']
}

当需要提供多个设置时，必须将它们包含在列表定义中，如下所示：

process {
  pod = [ [env: 'FOO', value: 'bar'], [secret: 'my-secret/key1', mountPath: '/etc/file.txt'] ]
}

publishDir

publishDir指令允许将流程输出文件发布到指定的文件夹。例如：

process foo {

    publishDir '/data/chunks'

    output:
    file 'chunk_*' into letters

    '''
    printf 'Hola' | split -b 1 - chunk_
    '''
}

上面的示例将字符串Hola分成单个字节的文件块。完成后，chunk_*输出文件将发布到该/data/chunks文件夹中。

publishDir可以多次指定该指令，以将输出文件发布到不同的目标目录。此功能需要0.29.0或更高版本。

默认情况下，文件会发布到目标文件夹，为每个流程输出创建一个符号链接，该链接将生成的文件链接到流程工作目录中。可以使用mode参数修改此行为。

可以与publishDir伪指令一起使用的可选参数表：

名称	描述
mode	文件发布方法。请参阅下表以获取可能的值。
overwrite	当`true`指定文件夹中的任何现有文件都将被覆盖时（默认值：`true`，在正常管道执行期间。在恢复管道执行时为`false`）。
pattern	指定 glob 文件模式，该模式可从整个输出文件集中选择要发布的文件。
path	指定需要发布文件的目录。注意：语法是的快捷方式。`publishDir '/some/dir'`是`publishDir path: '/some/dir'`的快捷方式
saveAs	一个闭包，给定要发布的文件的名称，它返回实际的文件名或要求存储该文件的完整路径。可以使用自定义策略来动态重命名或更改已发布文件的目标目录。`null`从闭包中返回值以不发布文件。当流程具有多个输出文件，但只希望发布其中一些输出文件时，此功能很有用。
enabled	允许根据指定的布尔值启用或禁用发布规则（默认值：）`true`。

发布方式表：

模式	描述
symlink	在发布的目录中为每个过程输出文件创建一个绝对的符号链接（默认）。
rellink	在发布目录中为每个过程输出文件创建一个相对的符号链接。
link	在发布的目录中为每个过程输出文件创建一个硬链接。
copy	将输出文件复制到发布的目录中。
copyNoFollow	将输出文件复制到发布的目录中，而无需遵循符号链接。复制链接本身。
move	将输出文件移动到发布的目录中。注意：仅应将其用于终止过程，即，其输出未被任何其他下游过程消耗的过程。

需要将模式值指定为字符串文字，即用引号引起来。多个参数需要用冒号分隔。例如：

process foo {

    publishDir '/data/chunks', mode: 'copy', overwrite: false

    output:
    file 'chunk_*' into letters

    '''
    printf 'Hola' | split -b 1 - chunk_
    '''
}

文件以异步方式复制到指定目录中，因此在执行过程结束时，它们可能不会立即在已发布目录中提供。因此，一个进程发布的文件不能被其他下游进程访问。

queue

queue目录使可以设置在管道中使用基于网格的执行程序时调度作业的队列。例如：

process grid_job {

    queue 'long'
    executor 'sge'

    """
    your task script here
    """
}

多个队列可以通过用逗号分隔它们的名称来指定，例如：

process grid_job {

    queue 'short,long,cn-el6'
    executor 'sge'

    """
    your task script here
    """
}

仅以下执行者会考虑此指令：SGE，LSF， SLURM和PBS / Torque执行者。

label

该label指令允许使用选择的助记符标识符注释进程。例如：

process bigTask {

  label 'big_mem'

  '''
  
  '''
}

可以使用同一label指令将同一标签应用于多个进程，并且可以将多个标签应用于同一进程多次。

标签必须由字母数字字符或组成_，必须以字母字符开头并且必须以字母数字字符结尾。

标签对于将工作流程过程组织成单独的组很有用，可以在配置文件中引用这些标签，以选择和配置具有类似计算要求的过程子集。

scratch

scratch指令允许在执行节点本地的临时文件夹中执行流程。

当使用网格执行器启动管道时，这很有用，因为它允许通过在实际执行节点的本地磁盘中的临时目录中运行管道进程来减少NFS开销。仅将在流程定义中声明为输出的文件复制到管道工作区中。

基本形式只需true在指令值处指定即可，如下所示：

process simpleTask {

  scratch true

  output:
  file 'data_out'

  '''
  
  '''
}

通过这样做，它尝试$TMPDIR在执行节点中的变量定义的目录中执行脚本。如果此变量不存在，它将使用Linux命令创建一个新的临时目录mktemp。

$TMPDIR可以通过简单地将其用作暂存值来指定除以外的自定义环境变量，例如：

scratch '$MY_GRID_TMP'

注意，它必须用单引号引起来，否则变量将在管道脚本上下文中求值。

还可以提供特定的文件夹路径作为暂存值，例如：

scratch '/tmp/my/path'

这样，每次执行进程时，都会在指定的路径中创建一个新的临时目录。

最后，当ram-disk字符串作为scratch值提供时，该过程将在节点RAM虚拟磁盘中执行。

允许值的摘要：

刮	描述
false	不要使用临时文件夹。
true	在`$TMPDIR`变量定义的目录中创建一个暂存文件夹；退回至该变量不存在。`mktemp /tmp`
$YOUR_VAR	在`$YOUR_VAR`环境变量定义的目录中创建一个临时文件夹；退回至该变量不存在。`mktemp /tmp`
/my/tmp	在指定目录中创建临时文件夹。
ram-disk	在RAM磁盘中创建临时文件夹`/dev/shm/`（实验性）。

storeDir

该storeDir指令允许定义一个目录，该目录用作过程结果的永久缓存。

更详细地说，它以两种主要方式影响流程执行：

仅当output子句中声明的文件在storeDir指令指定的目录中不存在时，才执行该过程。这些文件存在时，将跳过过程执行，并将这些文件用作实际过程结果。
每当一个过程成功完成时，输出声明块中列出的文件就会移动到该storeDir指令指定的目录中。

以下示例显示如何使用storeDir指令为输入参数指定的每个物种创建一个包含BLAST数据库的目录：

genomes = Channel.fromPath(params.genomes)

process formatBlastDatabases {

  storeDir '/db/genomes'

  input:
  file species from genomes

  output:
  file "${dbName}.*" into blastDb

  script:
  dbName = species.baseName
  """
  makeblastdb -dbtype nucl -in ${species} -out ${dbName}
  """

}

该storeDir指令用于长期的进程缓存，不应用于将进程产生的文件输出到特定文件夹或以语义目录结构组织结果数据。在这些情况下，可以改用publishDir指令。

支持使用AWS S3路径，但是需要在目标计算节点中安装AWS CLI工具（即aws）。

stageInMode

stageInMode指令定义如何将输入文件切入到流程工作目录中。允许以下值：

值	描述
copy	通过创建副本将输入文件暂存到流程工作目录中。
link	通过为每个输入文件创建（硬）链接，将输入文件暂存到流程工作目录中。
symlink	输入文件通过创建带有每个文件的绝对路径的符号链接而在过程工作目录中暂存（默认）。
rellink	通过创建具有每个文件的相对路径的符号链接，将输入文件暂存到流程工作目录中。

stageOutMode

该stageOutMode指令定义如何从头开始目录将输出文件逐步淘汰到流程工作目录。允许以下值：

值	描述
copy	输出文件从临时目录复制到工作目录。
move	输出文件从暂存目录移动到工作目录。
rsync	使用该`rsync`实用程序将输出文件从临时目录复制到工作目录。

tag

tag指令允许将每个流程执行与一个自定义标签相关联，以便在日志文件或跟踪执行报告中更容易识别它们。例如：

process foo {
  tag "$code"

  input:
  val code from 'alpha', 'gamma', 'omega'

  """
  echo $code
  """
}

上面的代码段将打印类似于以下内容的日志，其中进程名称包含标签值：

[6e/28919b] Submitted process > foo (alpha)
[d2/1c6175] Submitted process > foo (gamma)
[1c/3ef220] Submitted process > foo (omega)

time

time指令允许定义一个进程可以运行多长时间。例如：

process big_job {

    time '1h'

    """
    your task script here
    """
}

指定持续时间值时，可以使用以下时间单位后缀：

单元	描述
s	秒
m	分钟
h	小时
d	天

仅在使用以下基于网格的执行程序之一时才考虑此指令： SGE，LSF，SLURM，PBS / Torque， HTCondor和AWS Batch执行程序。

动态指令

可以在流程执行期间动态分配指令，以便可以根据一个或多个流程输入值的值来评估其实际值。

为了以动态方式定义该指令的值，需要使用闭包语句来表示，如以下示例所示：

process foo {

  executor 'sge'
  queue { entries > 100 ? 'long' : 'short' }

  input:
  set entries, file(x) from data

  script:
  """
  < your job here >
  """
}

在上面的示例中，根据输入值动态评估queue指令entries。当它大于100时，作业将被提交到队列long，否则short将使用该作业。

可以将所有指令分配给动态值，但以下各项除外：

executor
maxForks

可以使用隐式变量来检索流程脚本中动态指令的当前值，该隐式变量task 包含当前流程实例中定义的指令值。

例如：

process foo {

   queue { entries > 100 ? 'long' : 'short' }

   input:
   set entries, file(x) from data

   script:
   """
   echo Current queue: ${task.queue}
   """
 }

动态计算资源

在相同的流程的不同实例对计算资源的需求可能非常不同的情况下，这是非常普遍的情况。例如，在这种情况下，请求的内存量太低会导致某些任务失败。相反，使用适合执行中所有任务的更高限制可能会大大降低作业的执行优先级。

动态指令评分功能可被用来修改计算在处理失败的情况下请求的资源的量，并尝试使用更高的限制重新执行。例如：

process foo {

    memory { 2.GB * task.attempt }
    time { 1.hour * task.attempt }

    errorStrategy { task.exitStatus in 137..140 ? 'retry' : 'terminate' }
    maxRetries 3

    script:
    

}

在上面的示例中，内存和执行时间限制是动态定义的。第一次执行该过程时将task.attempt设置为1，因此它将请求2 GB的内存和一小时的最大执行时间。

如果任务执行失败，报告退出状态在137到140之间，退出任务将被重新提交（否则立即终止）。此时的值task.attempt就是2，从而增加了存储器的量至四个GB和时间至2小时，并依此类推。

动态重试

在某些情况下，所需的执行资源可能是暂时不可用的，例如网络拥塞。在这些情况下，立即重新执行任务可能会导致相同的错误。具有延迟的重试可以更好地恢复以下错误情况：

process foo {
  errorStrategy { sleep(Math.pow(2, task.attempt) * 200 as long); return 'retry' }
  maxRetries 5
  script:
  '''
  your_command --here
  '''
}