12. Configuração do Nextflow¶

Um recurso importante do Nextflow é a capacidade de desacoplar a implementação do fluxo de trabalho e as configurações exigidas pela plataforma onde ele será executado.

Isso permite a portabilidade da aplicação sem a necessidade de modificar seu código quando se faz necessária a execução em diferentes ambientes.

12.1 Arquivo de configuração¶

Quando um script de fluxo de trabalho é executado, o Nextflow procura um arquivo chamado nextflow.config no diretório atual e no diretório base do script (se não for o mesmo que o diretório atual). Caso não encontre, o Nextflow verifica o arquivo: $HOME/.nextflow/config.

Quando existir mais de um dos arquivos acima, eles serão mesclados, de modo que as configurações do primeiro substituam as mesmas configurações que podem aparecer no segundo e assim por diante.

O mecanismo de pesquisa padrão do arquivo de configuração pode ser estendido fornecendo um arquivo de configuração extra usando a opção de linha de comando: -c <arquivo de configuração>.

12.1.1 Sintaxe do arquivo de configuração¶

Um arquivo de configuração do Nextflow é um arquivo de texto simples contendo um conjunto de propriedades definidas usando a sintaxe:

1

nome = valor

12.1.2 Variáveis de configuração¶

As propriedades de configuração podem ser usadas como variáveis no próprio arquivo de configuração, usando a sintaxe usual $nomePropriedade ou ${expressao}.

1
2
3

propriedadeUm = 'mundo'
umaOutraPropriedade = "Olá $propriedadeUm"
caminhoCustomizado = "$PATH:/pasta/da/minha/app"

12.1.3 Comentários no arquivo de configuração¶

Os arquivos de configuração usam as mesmas convenções para comentários usados no script Nextflow:

1
2
3
4
5
6

// comentar uma única linha

/*
    um comentário abrangendo
    várias linhas
  */

12.1.4 Escopos de configuração¶

As definições de configuração podem ser organizadas em diferentes escopos. Pode-se utilizar a notação escopo.propriedade ou agrupar as propriedades no mesmo escopo usando a notação de chaves, como mostrado a seguir:

1
2
3
4
5
6
7

alfa.x = 1
alfa.y = 'valor da string..'

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

12.1.5 Configurar parâmetros¶

O escopo params permite a definição de parâmetros que substituem os valores definidos no script principal do fluxo de trabalho.

Isso é útil para reforçar o uso de um ou mais parâmetros de execução em um arquivo separado.

1
2

params.foo = 'Bonjour'
params.bar = 'le monde!'

1
2
3
4
5

params.foo = 'Olá'
params.bar = 'mundo!'

// imprime ambos os parâmetros
println "$params.foo $params.bar"

nextflow run params.nf

Bonjour le monde!

nextflow run params.nf --foo Olá

Olá le monde!

12.1.6 Configurar ambiente¶

O escopo env permite a definição de uma ou mais variáveis que serão exportadas para o ambiente onde serão executadas as tarefas do fluxo de trabalho.

1
2

env.ALFA = 'algum valor'
env.BETA = "$HOME/algum/caminho"

Salve o trecho acima como um arquivo chamado meu-env.config. Em seguida, salve o trecho abaixo em um arquivo chamado foo.nf:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

process FOO {
    debug true

    script:
    '''
    env | egrep 'ALFA|BETA'
    '''
}

workflow {
    FOO()
}

Por fim, execute o seguinte comando:

nextflow run foo.nf -c meu-env.config

BETA=/home/usuario/algum/caminho
ALFA=algum valor

12.1.7 Configurar processos¶

As diretivas de processos permite a especificação de configurações para a execução de uma tarefa, como cpus, memory, container, além de outros recursos, no script do fluxo de trabalho.

Isso é útil ao criarmos um exemplo-teste ou um protótipo para o nosso fluxo de trabalho.

No entanto, é sempre uma boa prática desassociar a lógica de execução do fluxo de trabalho das configurações que serão utilizadas por ele. Assim, é altamente recomendável definir as configurações do processo no arquivo de configuração do fluxo de trabalho em vez de no script do fluxo de trabalho.

Além disso, quaisquer diretivas do escopo dos processos (process) podem ser usadas no arquivo de configuração.

1
2
3
4
5

process {
    cpus = 10
    memory = 8.GB
    container = 'biocontainers/bamtools:v2.4.0_cv3'
}

O trecho de configuração acima define as diretivas cpus, memory e container para todos os processos em seu fluxo de trabalho.

O seletor de processo pode ser usado para aplicar a configuração a um processo específico ou grupo de processos (discutido posteriormente).

A sintaxe para definir as diretivas de processo no arquivo de configuração requer = (ou seja, operador de atribuição). Esta notação não deve ser usada para definir as diretivas do processo no script do fluxo de trabalho.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

process FOO {
    cpus 4
    memory 2.GB
    time 1.hour
    maxRetries 3

    script:
    """
    seu_comando --cpus $task.cpus --mem $task.memory
    """
}

Isso é especialmente importante quando você deseja criar uma definição de configuração usando uma expressão dinâmica com uma clausura. Por exemplo, em um arquivo de fluxo de trabalho:

1
2
3

process FOO {
    memory { 4.GB * task.cpus }
}

E o equivalente em um arquivo de configuração, se você preferir configurar isso lá:

1
2
3
4
5

process {
    withName: FOO {
        memory = { 4.GB * task.cpus }
    }
}

Diretivas que exigem mais de um valor, como a diretiva pod, precisam ser expressas como um objeto Map no arquivo de configuração.

1
2
3

process {
    pod = [ambiente: 'FOO', valor: '123']
}

Por fim, as diretivas que devem ser repetidas na definição do processo e nos arquivos de configuração precisam ser definidas como um objeto List. Por exemplo:

1
2
3
4

process {
    pod = [[ambiente: 'FOO', valor: '123'],
           [ambiente: 'BAR', valor: '456']]
}

12.1.8 Configurar execução do Docker¶

A imagem do contêiner a ser utilizada para a execução do processo pode ser especificada no arquivo nextflow.config:

1
2

process.container = 'nextflow/rnaseq-nf'
docker.enabled = true

O uso de IDs únicos com "SHA256" para imagens Docker garante que o conteúdo da imagem não mude com o tempo, por exemplo:

1
2

process.container = 'nextflow/rnaseq-nf@sha256:aeacbd7ea1154f263cda972a96920fb228b2033544c2641476350b9317dab266'
docker.enabled = true

12.1.9 Configurar execução do Singularity¶

Para rodar um fluxo de trabalho com Singularity, é necessário fornecer o caminho para o arquivo de imagem do contêiner usando a diretiva de contêiner (container):

1
2

process.container = '/alguma/imagem/singularity/imagem.sif'
singularity.enabled = true

Os seguintes protocolos são suportados:

• library:// baixe a imagem do contêiner do Singularity Library service.
• shub:// baixe a imagem do contêiner do Singularity Hub.
• docker:// baixe a imagem do contêiner do Docker Hub e a converta para o formato Singularity.
• docker-daemon:// extraia a imagem do contêiner de uma instalação local do Docker e a converta em um arquivo de imagem Singularity.

1
2

process.container = 'nextflow/rnaseq-nf'
singularity.enabled = true

nextflow run script7.nf

12.1.10 Configurar execução com ambientes Conda¶

Ambientes Conda também podem ser fornecidos no arquivo de configuração. Basta adicionar a seguinte configuração no arquivo nextflow.config:

1

process.conda = "/home/ubuntu/miniconda2/envs/nf-tutorial"

Você pode especificar o caminho de um ambiente Conda existente como diretório ou o caminho do arquivo YAML do ambiente Conda.