生信自动化流程搭建 07 | 配置文件

配置文件

启动管道脚本时，Nextflow将在当前目录和脚本基本目录（如果与当前目录不同）中查找一个名为nextflow.config的文件。最后，它检查文件 $HOME/.nextflow/config。

当存在多个文件时，它们将被合并，因此第一个文件中的设置将覆盖第二个文件中可能出现的相同设置，依此类推。

如果要忽略任何默认配置文件，而仅使用自定义文件，请使用命令行选项。-C <config file>

值得注意的是，通过这样做，文件nextflow.config和$HOME/.nextflow/config不会被忽略，并且如上所述将它们合并。

配置语法

Nextflow配置文件是一个简单的文本文件，其中包含使用以下语法定义的一组属性：

name = value

字符串值需要用引号引起来，而数字和布尔值（true，false）则不需要。

需要注意，键入的值（例如1）不同于'1'，因为第一个解释为数字，而第一个解释为字符串值。

配置变量

通过使用通常的$propertyName或${expression}语法，配置属性可以用作配置文件本身中的变量。

例如：

propertyOne = 'world'
anotherProp = "Hello $propertyOne"
customPath = "$PATH:/my/app/folder"

包含变量引用的字符串必须用双引号字符而不是单引号字符包装。

配置注释

配置文件使用与Groovy或Java编程语言相同的注释约定。因此，用于//注释单行或/*.. */注释多行中的块。

配置包括

一个配置文件可以使用关键字包含一个或多个配置文件includeConfig。例如：

process.executor = 'sge'
process.queue = 'long'
process.memory = '10G'

includeConfig 'path/foo.config'

使用相对路径时，将根据包含文件的实际位置解析该路径。

配置域

可以通过在属性名称前加一个范围标识符为点名称加上前缀，或使用大括号表示法在同一范围内对属性进行分组，来在不同的范围内组织配置设置。在下面的示例中显示：

alpha.x  = 1
alpha.y  = 'string value..'

beta {
     p = 2
     q = 'another string ..'
}

env

env范围允许将在所述工作流任务将被执行的环境被导出的定义的一个或多个变量。

只需在变量名前加上env范围或用大括号括起来即可，如下所示：

env.ALPHA = 'some value'
env.BETA = "$HOME/some/path"

env {
     DELTA = 'one more'
     GAMMA = "/my/path:$PATH"
}

参数

params范围允许你定义的参数，将在管道脚本访问。只需在参数名称前加params范围或用大括号括起来即可，如下所示：

params.custom_param = 123
params.another_param = 'string value .. '

params {

   alpha_1 = true
   beta_2 = 'another string ..'

}

process

process配置域可以在管道的process中提供的默认配置。

您可以在此处指定process指令和executor部分中描述的任何属性。举些例子：

process {
  executor='sge'
  queue='long'
  clusterOptions = '-pe smp 10 -l virtual_free=64G,h_rt=30:00:00'
}

通过使用此配置，管道中的所有进程将通过SGE集群以指定的设置执行。

Process selectors

withLabel选择器允许与注释的所有进程的配置标签指令如下所示：

process {
    withLabel: big_mem {
        cpus = 16
        memory = 64.GB
        queue = 'long'
    }
}

上面的配置示例将16 cpus，64 Gb内存和long队列分配给所有带有big_mem标签注释的进程。

以相同的方式，withName选择器允许通过名称在管道中配置特定进程。例如：

process {
    withName: hello {
        cpus = 4
        memory = 8.GB
        queue = 'short'
    }
}

并不需要或者标签和进程名称用引号字符括起来，提供的名称不包含特殊字符（例如-，!等），或者它不是一个关键字或内置类型标识符。如有疑问，可以用单引号或双引号将标签名称或过程名称括起来。

选择器表达式

标签和进程名称选择器都允许使用正则表达式，以便将相同的配置应用于与指定模式条件匹配的所有进程。例如：

process {
    withLabel: 'foo|bar' {
        cpus = 2
        memory = 4.GB
    }
}

上面的配置代码片段为进程添加了2 cpus和4 GB的内存，并用标签foo 和bar进行了注释。

可以否定进程选择器，并在其前面加上特殊字符!。例如：

process {
    withLabel: 'foo' { cpus = 2 }
    withLabel: '!foo' { cpus = 4 }
    withName: '!align.*' { queue = 'long' }
}

上面的配置代码段为带有foo标签注释的进程设置2 cpus，为所有未带有该标签注释的进程设置4 cpus 。最后，将使用long队列的所有进程。

选择器优先

在混合通用流程配置和选择器时，将应用以下优先级规则（从低到高）：

处理通用配置。
工作流程脚本中定义的特定于流程的指令。
withLabel 选择器定义。
withName 选择器定义。

例如：

process {
    cpus = 4
    withLabel: foo { cpus = 8 }
    withName: bar { cpus = 32 }
}

使用上面的配置代码段，如果工作流脚本中未另行指定，则所有工作流进程均使用4 cpus。此外，带有foo标签注释的过程使用8 cpus。最后，名为的进程bar 使用32 cpus。

executor 的域

executor配置范围允许您设置可选的执行程序设置，下表中列出。

名称	描述
name	使用执行人的名称，如`local`，`sge`等。
queueSize	执行程序将以并行方式处理的任务数（默认值：）`100`。
pollInterval	确定轮询发生的频率，以检查进程是否终止。
dumpInterval	确定将执行程序状态写入应用程序日志文件的频率（默认值：）`5min`。
queueStatInterval	确定从集群系统获取队列状态的频率。此设置仅由网格执行程序使用（默认值：）`1min`。
exitReadTimeout	确定当进程终止但退出文件不存在或为空时，执行程序在返回错误状态之前等待的时间。此设置仅由网格执行程序使用（默认值：）。`270 sec`
killBatchSize	确定在单个命令执行中可以杀死的作业数（默认值：）`100`。
SubmitRateLimit	确定每个时间单位可以执行的最大作业率，例如每秒最多10个作业（默认值：无限制）。`'10 sec'`
perJobMemLimit	指定平台LSF 每个作业的内存限制模式。参见LSF。
jobName	确定提交给基础集群执行器的作业的名称，例如。`executor.jobName = { "$task.name - $task.hash" }`
cpus	基础系统可用的最大CPU数（仅由`local`执行程序使用）。
memory	基础系统可用的最大内存量（仅由`local`执行程序使用）。

执行器设置可以如下定义：

executor {
    name = 'sge'
    queueSize = 200
    pollInterval = '30 sec'
}

在管道中使用两个（或多个）不同的执行程序时，可以通过在执行程序名称前加上符号$并将其用作特殊作用域标识符来分别指定其设置。例如：

executor {
  $sge {
      queueSize = 100
      pollInterval = '30sec'
  }

  $local {
      cpus = 8
      memory = '32 GB'
  }
}

可以使用如下所示的点符号来重写以上配置示例：

executor.$sge.queueSize = 100
executor.$sge.pollInterval = '30sec'
executor.$local.cpus = 8
executor.$local.memory = '32 GB'

docker 的域

docker配置范围控制如何泊坞容器通过Nextflow执行。

可以使用以下设置：

名称	描述
enabled	将此标志`true`启用以启用Docker执行（默认值：）`false`。
envWhitelist	用逗号分隔的要包含在容器环境中的环境变量名称列表。
legacy	使用从1.10.x版本开始删除的命令行选项（默认值：）`false`。
sudo	以`sudo`（默认值：）执行Docker run命令`false`。
tty	分配一个伪tty（默认值：）`false`。
temp	将选择的路径挂载为`/tmp`容器中的目录。`auto`每次创建容器时，都使用特殊值创建一个临时目录。
remove	执行后清理容器（默认值：）`true`。有关详细信息，请参见：https : //docs.docker.com/engine/reference/run/#clean-up—rm。
runOptions	此属性可用于提供命令支持的任何其他命令行选项。有关详细信息，请参见：https : //docs.docker.com/engine/reference/run/。`docker run`
registry	从中提取Docker映像的注册表。它仅应用于指定私有注册表服务器。它不应包含协议前缀，即`http://`。
fixOwnership	修复由Docker容器创建的文件的所有权。
engineOptions	该属性可用于提供Docker引擎支持的任何选项，即。`docker [OPTIONS]`
mountFlags	将指定的标志添加到卷安装中，例如mountFlags =’ro，Z’

可以通过在docker范围前面加上前缀或用大括号括起来来使用以上选项，如下所示：

process.container = 'nextflow/examples'

docker {
    enabled = true
    temp = 'auto'
}

阅读Docker容器页面以进一步了解如何将Docker容器与Nextflow一起使用。

singularity 的域

的singularity配置范围控制如何奇异容器通过Nextflow执行。

可以使用以下设置：

名称	描述
已启用	将此标志`true`启用以启用奇点执行（默认值：）`false`。
engineOptions	此属性可用于提供奇点引擎支持的任何选项，即。`singularity [OPTIONS]`
envWhitelist	用逗号分隔的要包含在容器环境中的环境变量名称列表。
runOptions	此属性可用于提供.NET支持的任何其他命令行选项。`singularity exec`
noHttps	旋转此标志可`true`使用http协议（默认值：）拉出奇点图像`false`。
自动挂载	当`true`Nextflow自动将主机路径安装在执行的容器中时。它要求您在Singularity安装中启用了用户绑定控制功能（默认值：）`false`。
cacheDir	远程奇点图像的存储目录。使用计算群集时，它必须是所有计算节点均可访问的共享文件夹。
pullTimeout	奇异性拉动可以持续的时间量，超过该时间量将终止该过程（默认值：）。`20 min`

阅读Singularity容器页面以了解如何将Nexting与Singularity容器一起使用。

podman 的域

的podman配置范围控制如何Podman容器通过Nextflow执行。

可以使用以下设置：

名称	描述
已启用	`true`启用此标志以启用Podman执行（默认值：）`false`。
envWhitelist	用逗号分隔的要包含在容器环境中的环境变量名称列表。
温度	将选择的路径挂载为`/tmp`容器中的目录。`auto`每次创建容器时，都使用特殊值创建一个临时目录。
去掉	执行后清理容器（默认值：）`true`。
runOptions	此属性可用于提供命令支持的任何其他命令行选项。`podman run`
注册表	从中提取容器映像的注册表。它仅应用于指定私有注册表服务器。它不应包含协议前缀，即`http://`。
engineOptions	该属性可用于提供Docker引擎支持的任何选项，即。`podman [OPTIONS]`
mountFlags	将指定的标志添加到卷安装中，例如mountFlags =’ro，Z’

可以通过在podman范围前面加上前缀或用大括号括起来来使用以上选项，如下所示：

process.container = 'nextflow/examples'

podman {
    enabled = true
    temp = 'auto'
}

阅读Podman容器页面以了解如何将Podman容器与Nextflow一起使用。

manifest 的域

通过manifest配置作用域，您可以定义在GitHub，BitBucket或GitLab上发布管道项目或运行管道时所需的一些元数据信息。

可以使用以下设置：

名称	描述
作者	项目作者名称（使用逗号分隔多个名称）。
defaultBranch	Git仓库默认分支（默认：）`master`。
描述	描述工作流程项目的自由文本。
土井	与项目相关的出版物DOI标识符。
主页	项目主页URL。
主脚本	项目主脚本（默认值：）`main.nf`。
名称	项目简称。
nextflowVersion	最低要求的Nextflow版本。
版	项目版本号。

可以通过在manifest范围前面加上前缀或用大括号括起来来使用以上选项。例如：

manifest {
    homePage = 'http://foo.com'
    description = 'Pipeline does this and that'
    mainScript = 'foo.nf'
    version = '1.0.0'
}

要了解如何在GitHub，BitBucket或GitLab代码存储库上发布管道，请阅读管道共享文档页面。

Nextflow版本

该nextflowVersion设置允许您指定运行管道所需的最低版本。这对于确保使用特定版本可能很有用：

nextflowVersion = '1.2.3'        // exact match
nextflowVersion = '1.2+'         // 1.2 or later (excluding 2 and later)
nextflowVersion = '>=1.2'        // 1.2 or later
nextflowVersion = '>=1.2, <=1.5' // any version in the 1.2 .. 1.5 range
nextflowVersion = '!>=1.2'       // with ! prefix, stop execution if current version
                                    does not match required version.

范围追踪

该trace范围允许您控制Nextflow生成的执行跟踪文件的布局。

可以使用以下设置：

名称	描述
已启用	当`true`打开执行跟踪报告文件的生成时（默认值：）`false`。
领域	用逗号分隔的要包含在报告中的字段列表。可用字段在此页面列出
文件	跟踪文件名（默认值：）`trace.txt`。
九月	用于分隔每一行中值的字符（默认值：）`\t`。
生的	当`true`打开原始数字报告生成时，即日期和时间以毫秒报告，内存以字节数报告

可以通过在trace范围前面加上前缀或用大括号括起来来使用以上选项。例如：

trace {
    enabled = true
    file = 'pipeline_trace.txt'
    fields = 'task_id,name,status,exit,realtime,%cpu,rss'
}

要了解有关Nextflow可以生成的执行报告的更多信息，请阅读跟踪报告文档页面。

范围aws

该aws范围允许您配置对Amazon S3存储的访问。使用属性accessKey和secretKey 指定存储桶凭证。例如：

aws {
    accessKey = ''
    secretKey = ''
    region = ''
}

单击以下链接以了解有关AWS Security Credentials的更多信息。

可以使用client属性设置高级客户端配置选项。可以使用以下属性：

名称	描述
连接超时	最初建立连接之前放弃和超时之前要等待的时间（以毫秒为单位）。
终点	AWS S3 API入口点，例如s3-us-west-1.amazonaws.com。
maxConnections	允许的最大打开HTTP连接数。
maxErrorRetry	失败的可重试请求的最大重试次数。
协议	连接到AWS时要使用的协议（即HTTP或HTTPS）。
proxyHost	通过代理主机进行连接。
代理端口	代理主机上要连接的端口。
proxyUsername	通过代理连接时使用的用户名。
proxyPassword	通过代理连接时使用的密码。
signerOverride	用于对客户端发出的请求进行签名的签名算法的名称。
socketSendBufferSizeHint	低级TCP发送缓冲区的大小提示（以字节为单位）。
socketRecvBufferSizeHint	低级TCP接收缓冲区的大小提示（以字节为单位）。
socketTimeout	在连接超时之前，等待数据通过已建立的打开的连接传输的时间（以毫秒为单位）。
存储加密	在S3上保存对象时将使用的S3服务器端加密（当前仅支持AES256）
用户代理	与所有HTTP请求一起传递的HTTP用户代理标头。
uploadMaxThreads	用于分段上传的最大线程数。
uploadChunkSize	分段上传中单个部分的大小（默认值：10 MB）。
uploadStorageClass	S3存储类应用于存储的对象，[ STANDARD，STANDARD_IA，ONEZONE_IA，INTELLIGENT_TIERING ]（默认值：STANDARD）之一。
uploadMaxAttempts	分段上传后返回错误的最大尝试上传次数（默认值：5）。
uploadRetrySleep	上载失败尝试重试零件上载后要等待的时间（默认值：100ms）。

例如：

aws {
    client {
        maxConnections = 20
        connectionTimeout = 10000
        uploadStorageClass = 'INTELLIGENT_TIERING'
        storageEncryption = 'AES256'
    }
}

可以使用batch属性设置“高级批处理”配置选项。可以使用以下属性（必需版本19.07.0或更高版本）：

名称	描述
路径	主机AMI中AWS命令行工具的安装路径。
职业角色	需要用于执行批处理作业的AWS Job Role ARN。
卷	一个或多个容器安装架。挂载可以指定为简单格式（例如/ some / path）或规范格式（例如）`/host/path:/mount/path[:ro
delayBetweenAttempts	从S3下载尝试之间的延迟（默认为10秒）。
maxParallelTransfers	每个作业的最大并行上传/下载传输操作（默认值：）`16`。
maxTransferAttempts	从S3下载的最大尝试次数（默认值：1）。

范围云

注意

在cloud配置范围已经退役。

范围康达

该conda范围允许定义配置设置，以控制Conda程序包管理器创建Conda环境。

可以使用以下设置：

名称	描述
cacheDir	定义存储Conda环境的路径。使用计算群集时，请确保提供可从所有计算节点访问的共享文件系统路径。
createTimeout	定义Conda环境创建可以持续的时间。超过超时时间（默认值：）时，创建过程终止。`20 min`

范围k8s

该k8s范围允许定义配置设置，以控制Kubernetes集群中工作流程应用程序的部署和执行。

可以使用以下设置：

名称	描述
autoMountHostPaths	自动将主机路径安装在作业窗格中。仅在使用单节点群集时用于开发目的（默认值：）`false`。
语境	定义要使用的Kubernetes 配置上下文名称。
命名空间	定义要使用的Kubernetes命名空间（默认值：）`default`。
serviceAccount	定义要使用的Kubernetes 服务帐户名。
launchDir	定义启动工作流和存储用户数据的路径。这必须是共享K8s持久卷中的路径（默认值：`<volume-claim-mount-path>/<user-name>`。
工作目录	定义工作流临时数据的存储路径。这必须是共享K8s持久卷中的路径（默认值：）`<user-dir>/work`。
projectDir	定义下载Nextflow项目的路径。这必须是共享K8s持久卷中的路径（默认值：）`<volume-claim-mount-path>/projects`。
荚	允许定义一个或多个pod配置选项，例如环境变量，配置映射，机密等。它允许与pod process指令相同的设置。
pullPolicy	定义用于拉出容器图像的策略，例如。`pullPolicy: 'Always'`
runAsUser	定义用于运行容器的用户标识。
storageClaimName	持久卷声明的名称，用于存储工作流结果数据。
storageMountPath	用于挂载持久卷声明的路径位置（默认值：）`/workspace`。
storageSubPath	要安装的永久卷中的路径（默认值：root）。
volumeClaims	（已弃用）

有关更多详细信息，请参见Kubernetes文档。

范围时间表

该timeline范围使您可以启用/禁用Nextflow生成的流程执行时间表报告。

可以使用以下设置：

名称	描述
已启用	当`true`打开时间轴报告文件的生成时（默认值：）`false`。
文件	时间轴文件名（默认值：）`timeline.html`。

范围邮件

该mail范围允许您定义发送电子邮件所需的邮件服务器配置设置。

名称	描述
从	默认电子邮件发件人地址。
smtp主机	邮件服务器的主机名。
smtp端口	邮件服务器的端口号。
smtp.user	连接到邮件服务器的用户名。
smtp.password	连接到邮件服务器的用户密码。
smtp.proxy.host	HTTP Web代理服务器的主机名，将用于连接到邮件服务器。
smtp.proxy.port	HTTP Web代理服务器的端口号。
smtp。*	Java Mail API支持的任何SMTP配置属性（请参见下面的链接）。
调试	当`true`使Java邮件日志用于调试的目的。

注意

Nextflow依靠Java Mail API发送电子邮件。可以使用Java Mail API支持的任何SMTP配置属性来提供高级邮件配置。请参阅此链接上的可用属性表。

例如，以下代码片段显示了如何配置Nextflow以通过AWS Simple Email Service发送电子邮件：

mail {
    smtp.host = 'email-smtp.us-east-1.amazonaws.com'
    smtp.port = 587
    smtp.user = ''
    smtp.password = ''
    smtp.auth = true
    smtp.starttls.enable = true
    smtp.starttls.required = true
}

范围通知

该notification范围使您可以定义工作流程执行终止时自动发送通知电子邮件。

名称	描述
已启用	当工作流程执行完成时，启用发送通知消息的功能。
至	通知电子邮件的收件人地址。可以指定多个地址，并用逗号分隔。
从	通知电子邮件的发件人地址。
模板	提供通知消息内容的模板文件的路径。
捆绑	对模板文件中的变量进行建模的关联数组。

通知消息是使用配置邮件范围中定义的STMP服务器发送的。

如果未提供邮件配置，它将尝试使用最终由底层系统提供的外部邮件命令（例如sendmail或mail）发送通知消息。

范围报告

该report范围使您可以定义工作流执行报告的配置设置。

名称	描述
已启用	如果`true`创建工作流程执行报告。
文件	创建的执行报告文件的路径（默认值：）`report.html`。

范围网志

的weblog范围允许发送详细的跟踪范围的信息作为HTTP POST请求Web服务器，运作为JSON对象。

有关JSON字段的详细信息可以在Weblog描述中找到。

名称	描述
已启用	如果`true`它将HTTP POST请求发送到给定的URL。
网址	发送HTTP POST请求的网址（默认值：）`http:localhost`。

配置文件

配置文件可以包含一个或多个定义配置文件。配置文件是一组配置属性，在使用-profile命令行选项启动管道执行时可以激活/选择这些配置属性。

通过使用特殊作用域定义配置配置文件，该特殊作用域profiles使用公共前缀将属于同一配置文件的属性进行分组。例如：

profiles {

    standard {
        process.executor = 'local'
    }

    cluster {
        process.executor = 'sge'
        process.queue = 'long'
        process.memory = '10GB'
    }

    cloud {
        process.executor = 'cirrus'
        process.container = 'cbcrg/imagex'
        docker.enabled = true
    }

}

此配置定义了三个不同的配置文件：standard，cluster并且cloud根据目标运行时平台设置了不同的流程配置策略。按照约定，standard当用户未指定其他任何配置文件时，将隐式使用该配置文件。

小费

可以通过使用逗号分隔配置文件名称来指定两个或多个配置配置文件，例如：

nextflow run  -profile standard,cloud

危险

在配置文件中使用配置文件功能时，请勿在profiles上下文的内部和外部在同一范围内设置属性。例如：

process.cpus = 1

profiles {
  foo {
    process.memory = '2 GB'
  }

  bar {
    process.memory = '4 GB'
  }
}

在上面的示例中，process.cpus属性未正确应用，因为process作用域还用于foo和bar配置文件上下文。

以上功能需要0.28.x或更高版本。

环境变量

以下环境变量控制Nextflow运行时的配置以及它使用的Java虚拟机。

名称	描述
NXF_HOME	Nextflow主目录（默认值：）`$HOME/.nextflow`。
NXF_VER	定义要使用的Nextflow版本。
NXF_ORG	查找托管存储库时的默认组织前缀（默认：）`nextflow-io`。
NXF_GRAB	提供从Maven存储库服务下载的额外运行时依赖项。
NXF_OPTS	为Java和Nextflow运行时提供额外的选项。它必须是空白的`-Dkey[=value]`属性列表。
NXF_CLASSPATH	允许使用额外的JAR文件或类文件夹扩展Java运行时类路径。
NXF_ASSETS	定义了下载的管道仓库的存储目录（默认：`$NXF_HOME/assets`）
NXF_PID_FILE	在后台启动Nextflow时，保存过程PID的文件的名称。
NXF_WORK	工作文件的存储目录（通常是您的临时目录）
NXF_TEMP	存放临时文件的目录
NXF_DEBUG	定义脚本调试级别：`1`在任务日志文件中转储任务环境变量；`2`启用命令脚本执行跟踪；`3`启用命令包装程序执行跟踪。
NXF_EXECUTOR	定义默认的流程执行器，例如sge
NXF_CONDA_CACHEDIR	存储Conda环境的目录。使用计算群集时，它必须是一个可从所有计算节点访问的共享文件夹。
NXF_SINGULARITY_CACHEDIR	存储远程奇点图像的目录。使用计算群集时，它必须是一个可从所有计算节点访问的共享文件夹。
NXF_JAVA_HOME	定义用于运行Nextflow的Java VM安装的路径位置。`JAVA_HOME`如果定义，此变量将覆盖该变量。
NXF_OFFLINE	当`true`从远程仓库禁用项目的自动下载和更新（默认：`false`）。
NXF_CLOUD_DRIVER	定义默认的云驱动程序，如果未在配置文件中指定，或者未指定为命令行选项（`aws`或）`google`。
NXF_ANSI_LOG	启用/禁用ANSI控制台输出（`true`检测到ANSI终端时为默认值）。
NXF_ANSI_SUMMARY	启用/禁用ANSI完成摘要：true \| false（默认值：如果执行持续1分钟以上，则显示打印摘要）。
JAVA_HOME	定义用于运行Nextflow的Java VM安装的路径位置。
JAVA_CMD	定义用于启动Nextflow的Java二进制命令的路径位置。
HTTP_PROXY	定义HTTP代理服务器
HTTPS_PROXY	定义HTTPS代理服务器