9 Nextflow configuration

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 usagetime = '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 = 2memory = 8.GBtime = '1 hour'publishDir = [ path: params.outdir, mode: 'copy' ]
}

可以使用withName来指定特定的process：

// process_resources.config
process {withName: INDEX {cpus = 4memory = 8.GB}withName: FASTQC {cpus = 2memory = 4.GB}
}

当process很多时，分别为每个process指定指令很不方便，特别是有一些process的指令是重复的。一个好办法是为process增加label指令（process可以有多个label）。然后在配置中使用withLabel来指定被该label标记的。例如：

// configuration_process_labels.nf
nextflow.enable.dsl=2process 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 = 16memory = 64.GB}
}

另一种方法是使用process的选择器表达式。若使用正则表达式，则需要使用引号括起来。

|匹配或or。例如: withName: 'INDEX|FASTQC'匹配名为INDEX或FASTQC的process。
!可以排除某项。例如：withLabel: '!small_mem'匹配名称不为small_mem的process。
.*匹配任意数量的字符串。例如：withName: 'NFCORE_RNASEQ:RNA_SEQ:BAM_SORT:.*'匹配workflow NFCORE_RNASEQ:RNA_SEQ:BAM_SORT下的所有process。

当混合使用配置和选择器时，遵循以下优先级（从高到低）：

withName选择器。
withLabel选择器。
在workflow中定义的指令。
通用的process配置

动态配置

一个常见的场景是，配置可能取决于正在处理的数据。这样可以使用一个闭包来处理。例如：

// nextflow.config
process {withName: FASTQC {cpus = 2memory = { 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