Nextflow configuration
Nextflow的关键能力是将workflow的的实现与底层执行平台所需的配置解耦。这使得workflow具有可移植性,运行其在不同的计算平台上运行,而不需要修改实现。
配置文件
配置文件中的内容是以键值对(name-value
)的形式存储的,其中的value
可以为字符串,布尔类型,或其他变量,还可以为环境变量,例如:$PATH
,$HOME
, $PWD
等。
配置文件可以分为不同的作用域,这些作用域控制不同的行为。例如,workflow参数由params
作用域管理,而process的指令则由process
作用域控制。所有的作用域可以参考作用域。
workflow的配置通常保存在nextflow.config
,配置可以以2种方式写入:第一种使用params.xxx
,第二种使用大括号表示。例如:
// first:
params.input = '' // The workflow parameter "input" is assigned an empty string to use as a default value
params.outdir = './results' // The workflow parameter "outdir" is assigned the value './results' to use by default.
//second:
params {
input = ''
outdir = './results'
}
配置文件还可以分为多个文件,并使用 includeConfig
语句包含到另一个文件中。例如:
// system_resources.config
process {
cpus = 1 // default cpu usage
time = '1h' // default time limit
}
// nextflow.config
params {
input = ''
outdir = './results'
}
includeConfig 'system_resources.config'
配置文件如何导入
配置文件可以分布在不同的文件,这也允许配置文件覆盖其他的。配置文件的优先级从高到低排列如下。
- 命令行指定(
--param_name value
)。 - 使用
-params-file
选项提供参数。 - 使用
-c
指定配置文件。 - 当前目录下的
nextflow.config
文件。 - 项目目录projectDir下的
nextflow.config
文件。($projectDir: 要运行的脚本所在的目录) - 配置文件:
$HOME/.nextflow/config
。 - workflow脚本里面定义的值。
如果有多个配置文件,则使用优先级高的。
以
-
打头的参数是nextflow的配置选项,例如:-c my_config.config
,而以--
打头的参数是定义在params
作用域里面的,例如:--outdir
。
配置process
前面讲到process的指令可以为任务执行指定配置,如cpus
,memory
,conda
等其他资源。这样做在小的脚本里面是可以的,但是这也将配置与workflow绑定了。更好的做法是将process的配置写在另外的文件。
process
作用域可以设置任何process的指令,例如:
// nextflow.config
process {
cpus = 2
memory = 8.GB
time = '1 hour'
publishDir = [ path: params.outdir, mode: 'copy' ]
}
可以使用withName
来指定特定的process:
// process_resources.config
process {
withName: INDEX {
cpus = 4
memory = 8.GB
}
withName: FASTQC {
cpus = 2
memory = 4.GB
}
}
当process很多时,分别为每个process指定指令很不方便,特别是有一些process的指令是重复的。一个好办法是为process增加label
指令(process可以有多个label)。然后在配置中使用withLabel
来指定被该label标记的。例如:
// configuration_process_labels.nf
nextflow.enable.dsl=2
process P1 {
label "big_mem"
script:
"""
echo P1: Using $task.cpus cpus and $task.memory memory.
"""
}
process P2 {
label "big_mem"
script:
"""
echo P2: Using $task.cpus cpus and $task.memory memory.
"""
}
workflow {
P1()
P2()
}
// configuration_process-labels.config
process {
withLabel: big_mem {
cpus = 16
memory = 64.GB
}
}
另一种方法是使用process的选择器表达式。若使用正则表达式,则需要使用引号括起来。
|
匹配或or。例如:withName: 'INDEX|FASTQC'
匹配名为INDEX
或FASTQC
的process。!
可以排除某项。例如:withLabel: '!small_mem'
匹配名称不为small_mem
的process。.*
匹配任意数量的字符串。例如:withName: 'NFCORE_RNASEQ:RNA_SEQ:BAM_SORT:.*'
匹配workflowNFCORE_RNASEQ:RNA_SEQ:BAM_SORT
下的所有process。
当混合使用配置和选择器时,遵循以下优先级(从高到低):
withName
选择器。withLabel
选择器。- 在workflow中定义的指令。
- 通用的
process
配置
动态配置
一个常见的场景是,配置可能取决于正在处理的数据。这样可以使用一个闭包来处理。例如:
// nextflow.config
process {
withName: FASTQC {
cpus = 2
memory = { 2.GB * task.cpus }
publishDir = { "fastqc/$sample" }
}
}
配置运行平台
nextflow支持很多的运行平台,例如:本地执行,或运行在HPC集群或云设备。可以参考这里。
默认的执行器配置在executor
作用域中。例如:
// nextflow.config
executor {
name = 'sge'
queueSize = 10
}
process.executor
指令可以覆盖特定process使用的执行器。这是有用的,当有小任务能直接在本地执行,不适合提交到HPC上面。例如:
//nextflow.config
executor {
name = 'sge'
queueSize = 10
}
process {
withLabel: 'short' {
executor = 'local'
}
}
配置软件
Nextflow 的一个重要特点是能够使用不同技术管理软件。其支持conda包管理系统,还有容器引擎例如:Docker,Singularity,Podman,Charliecloud,和Shifter。软件环境在process作用域中被指定。每种软件还有自己的作用域,可以进一步来配置。
conda
conda是一个软件包和环境管理工具,软件包与特定的conda通道绑定,例如,生信软件包可以从BioConda通道下载安装。
可以按照如下配置cond环境:
- 提供一个现存conda环境的路径。
- 提供一个特定conda环境文件路径(yaml格式的)。
- 指定软件包:
<channel>::<package_name>=<version>
,这样会在process运行时构建conda环境。
process {
conda = "/home/user/miniconda3/envs/my_conda_env"
withName: FASTQC {
conda = "environment.yml"
}
withName: SALMON {
conda = "bioconda::salmon=1.5.2"
}
}
docker
docker 是一种容器技术。容器镜像是轻量级的、独立的、可执行的软件包,包括运行应用程序所需的一切: 代码、运行时环境、系统工具、系统库和配置。容器化软件是不依赖于操作系统的。
可以使用process.container
指令来使用docker,并且提供镜像路径,同时也要开启docker在docker作用域:docker.enabled = true
。容器镜像路径格式为:(protocol://)registry/repository/image:version--build
。通常docker容器使用特权用户运行软件。这可能会导致问题,因此通常使用如下选项:docker.runOptions
。
process.container = 'quay.io/biocontainers/salmon:1.5.2--h84f40af_0'
docker.enabled = true
docker.runOptions = '-u $(id -u):$(id -g)'
singularity
Singularity 也是一种容器技术,通常用于HPC集群。其与docker有些不同。最主要的区别是process以用户身份运行,并且某些目录会自动挂载。Singularity同样支持从docker镜像来构建singularity镜像。
开启singularity使用如下配置:process.container
指定镜像路径,还有singularity.enabled = true
。
process.container = 'https://depot.galaxyproject.org/singularity/salmon:1.5.2--h84f40af_0'
singularity.enabled = true
容器协议
docker://
:从docker hub下载镜像再转换为singularity镜像(默认)。library://
:从singularity库服务下载镜像。shub://
:从singularity hub下载镜像。docker-daemon://
:从本地 Docker 安装中提取容器映像并将其转换为singularity镜像。https://
:从给定URL下载。file://
:使用本地计算存储的镜像。
Configuration profiles
Nextflow 配置最强大的特性之一是可以预定义多个配置或profiles
为不同的执行平台。可以这样来调用:-profile <profile name>
。
//configuration_profiles.config
profiles {
standard {
params.genome = '/local/path/ref.fasta'
process.executor = 'local'
}
cluster {
params.genome = '/data/stared/ref.fasta'
process.executor = 'sge'
process.queue = 'long'
process.memory = '10GB'
process.conda = '/some/path/env.yml'
}
cloud {
params.genome = '/data/stared/ref.fasta'
process.executor = 'awsbatch'
process.container = 'cbcrg/imagex'
docker.enabled = true
}
}
这个配置定义了3个profile:standard
, cluster
和cloud
设置了不同的process配置策略依赖于目标运行平台。使用-profile
来指定特定的profile。
nextflow run <your script> -profile cluster
检查 Nextflow 配置
可以使用命令nextflow config
来打印workflow的配置。
$ nextflow config workflow_02.nf -profile test