6 Usando o nf-core

6.1 Recuperar o código do pipeline Demo

Depois de determinarmos que o pipeline parece ser adequado para nossos propósitos, vamos experimentá-lo. Felizmente, o Nextflow facilita a recuperação de pipelines de repositórios formatados corretamente sem precisar baixar nada manualmente.

nextflow pull nf-core/demo

Você pode fazer isso com qualquer pipeline Nextflow que esteja configurado adequadamente no GitHub, não apenas pipelines do nf-core. No entanto, o nf-core é a maior coleção de código aberto de pipelines Nextflow.

Para facilitar a navegação pelo código-fonte do pipeline, crie um link simbólico apontando para a cópia do pipeline que foi baixada:

mkdir -p pipelines/nf-core
ln -s "$(echo $NXF_HOME/assets/.repos/nf-core/demo/clones/*/)" pipelines/nf-core/demo

6.2 Estrutura de um pipeline nf-core

Todo pipeline nf-core segue o mesmo layout. Aprender esse mapa uma vez te economiza tempo em qualquer pipeline da coleção.

tree -L 1 pipelines/nf-core/demo

pipelines/nf-core/demo
├── main.nf                # ponto de entrada — quem você chama com `nextflow run`
├── workflows/             # workflows principais (a lógica de alto nível)
├── subworkflows/          # blocos reutilizáveis (locais e nf-core)
├── modules/               # processos individuais
│   ├── local/             #   → escritos pelo pipeline
│   └── nf-core/           #   → instalados do repositório nf-core/modules
├── conf/                  # todos os arquivos de configuração
│   ├── base.config        #   → labels de recurso (process_low/medium/high)
│   ├── modules.config     #   → ext.args e publishDir por processo  ★ AQUI VOCÊ CUSTOMIZA
│   ├── test.config        #   → perfil de teste
│   └── ...
├── assets/                # samplesheets exemplo + schemas de entrada
├── docs/                  # documentação
├── nextflow.config        # config raiz (carrega tudo em conf/)
└── nextflow_schema.json   # schema dos parâmetros (alimenta --help)

Os três lugares onde você mais vai olhar no dia-a-dia:

conf/modules.config — para descobrir quais ext.args já existem e como sobrescrevê-los
nextflow_schema.json — para entender parâmetros aceitos (ou use --help)
assets/schema_input.json — para saber exatamente o que sua samplesheet precisa ter

6.3 Examinar o perfil de teste

É uma boa prática verificar o que o perfil de teste de um pipeline especifica antes de executá-lo. O perfil test para nf-core/demo está no arquivo de configuração conf/test.config. Você pode encontrá-lo localmente dentro do código-fonte do pipeline que o nextflow pull baixou.

code pipelines/nf-core/demo/conf/test.config

6.4 Examinar o workflow do pipeline

code pipelines/nf-core/demo/main.nf

6.5 Executar o pipeline

nextflow run nf-core/demo -profile docker,test --outdir demo-results

7 Configurar a execução do pipeline

O nf-core distingue dois níveis de configuração:

Nível	O que é	Como definir
Parâmetros do pipeline (`params`)	Entradas, flags de análise, comportamento de ferramentas	`--param`, `-params-file file.yml`, bloco `params` no config
Configuração propriamente dita	Como o pipeline é executado — executor, recursos, engine de contêiner	`nextflow.config`, `-c custom.config`, `-profile`

7.1 Parâmetros do pipeline

7.1.1 Listar todos os parâmetros com `--help`

Todo pipeline nf-core expõe seus parâmetros com uma flag --help, alimentada pelo nextflow_schema.json:

nextflow run nf-core/demo --help

A saída agrupa os parâmetros por categoria (Input/output, Reference genome, etc.) com tipo, descrição e valor padrão.

Use nextflow run nf-core/demo --help --show_hidden para ver parâmetros ocultos, como --publish_dir_mode.

7.1.2 Definir valores de parâmetros

Três formas equivalentes:

1. Linha de comando (rápido, um valor por vez):

nextflow run nf-core/demo -profile docker,test --outdir demo-results --skip_trim

2. Arquivo de parâmetros com -params-file (recomendado):

my_params.yml:

skip_trim: true

nextflow run nf-core/demo -profile docker,test --outdir demo-results -params-file my_params.yml

3. Arquivo de configuração personalizado com -c — funciona, mas para params prefira as opções 1 e 2 (precedência é mais previsível).

Booleans na linha de comando: a partir do Nextflow 26.04, valores da CLI são tratados como strings. Passar --skip_trim puro pode falhar validação. Para booleans, use -params-file.

7.2 Validação automática de parâmetros

O nf-schema valida parâmetros contra o nextflow_schema.json antes de executar qualquer processo — falha rápida:

Parâmetro inexistente (só warning, mas alerta typos):

nextflow run nf-core/demo -profile docker,test --outdir demo --outDir demo
# WARN: --outDir: invalid

Valor de tipo errado (falha imediata):

nextflow run nf-core/demo -profile docker,test --outdir demo --skip_trim yes
# ERROR: --skip_trim (yes): Value is [string] but should be [boolean]

Isso economiza horas de execução perdidas por erros de digitação ou tipo.

7.3 Configuração propriamente dita

Os arquivos de config do pipeline ficam em pipelines/nf-core/demo/conf/. Os mais importantes:

base.config: define labels de recurso (process_low, process_medium, process_high) — CPUs/memória/tempo por categoria de processo.
modules.config: define ext.args (argumentos extras por ferramenta) e configurações de publishDir por processo.
test.config: perfil de teste com dataset mínimo (ativado por -profile test).

Regra de ouro: nunca edite esses arquivos diretamente. Crie um custom.config e passe com -c — os valores dele sobrescrevem os padrões.

7.4 Personalizar recursos e argumentos com `-c`

custom.config:

process {
    withName: 'FASTQC' {
        cpus   = 2
        memory = 4.GB
    }
    withName: 'SEQTK_TRIM' {
        ext.args = '-b 5'
    }
}

Primeiro bloco: reduz recursos alocados ao FASTQC.
Segundo bloco: passa a flag extra -b 5 ao seqtk trimfq (corta 5 bases do início de cada read).

Executar:

nextflow run nf-core/demo -profile docker,test --outdir demo-results-custom -c custom.config

Para confirmar que a flag entrou, procure o hash de SEQTK_TRIM na saída e inspecione o comando:

cat work/17/428668*/.command.sh

7.5 `ext.args` — o padrão-chave para customização

Toda ferramenta CLI tem dezenas de flags. Os módulos nf-core não expõem todas como parâmetros; em vez disso, deixam um “gancho” chamado ext.args que é passado direto para a ferramenta.

ext.args substitui o valor padrão do módulo, não adiciona. Se FASTQC já tem ext.args = '--quiet' em conf/modules.config e você define ext.args = '--kmers 8', o --quiet desaparece. Para manter ambos: ext.args = '--quiet --kmers 8'.

Sempre inspecione conf/modules.config antes de sobrescrever:

grep -A5 "withName: FASTQC" pipelines/nf-core/demo/conf/modules.config

7.6 Exercício 1 — Customizar `ext.args`

Enunciado

Modifique o pipeline nf-core/demo para que o FASTQC rode com a flag extra --kmers 8, sem perder o --quiet que já está configurado.

Depois de rodar, prove que a flag entrou inspecionando o .command.sh do processo FASTQC.

Resposta

Crie custom.config:

process {
    withName: 'FASTQC' {
        ext.args = '--quiet --kmers 8'
    }
}

Rode:

nextflow run nf-core/demo -profile docker,test --outdir demo-ex1 -c custom.config

Encontre o hash do FASTQC na saída (ex: [ca/5b0f3e]) e inspecione:

cat work/ca/5b0f3e*/.command.sh

A linha do fastqc deve conter --quiet --kmers 8.

Ponto-chave: se você tivesse escrito só ext.args = '--kmers 8', o --quiet teria sumido — ext.args substitui, não soma.

8 Validação de entradas

Sem validação, você pode esperar horas até um pipeline falhar num arquivo inexistente. O nf-core resolve isso com o plugin nf-schema, que valida antes de qualquer processo rodar.

8.1 Dois níveis de validação

Arquivo	O que valida
`nextflow_schema.json`	Parâmetros do pipeline (`--input`, `--outdir`, `--skip_trim`, …)
`assets/schema_input.json`	Estrutura da samplesheet (colunas, tipos, arquivos existentes)

Ambos usam o padrão JSON Schema.

A validação de samplesheet checa a estrutura (colunas certas, arquivos existem, extensão correta), não o conteúdo dos arquivos (integridade do FASTQ, por exemplo).

8.2 Validação de parâmetros

O nf-core/demo exibe todos os parâmetros e suas restrições via --help. Cada campo do schema define tipo, formato e regras.

Exemplo de erro por tipo errado:

nextflow run nf-core/demo -profile docker,test --outdir demo --skip_trim yes

ERROR ~ Validation of pipeline parameters failed!
* --skip_trim (yes): Value is [string] but should be [boolean]

O pipeline para antes de rodar qualquer processo.

8.3 Validação de samplesheet

O schema assets/schema_input.json define para cada coluna: nome, tipo, obrigatoriedade, padrão (regex), se o arquivo precisa existir e a mensagem de erro amigável.

Exemplo real do nf-core/demo:

{
    "type": "object",
    "properties": {
        "sample": {
            "type": "string",
            "pattern": "^\\S+$",
            "errorMessage": "Sample name must be provided and cannot contain spaces"
        },
        "fastq_1": {
            "type": "string",
            "format": "file-path",
            "exists": true,
            "pattern": "^([\\S\\s]*\\/)?[^\\s\\/]+\\.f(ast)?q\\.gz$",
            "errorMessage": "FastQ file for reads 1 must be provided..."
        },
        "fastq_2": { "...": "..." }
    },
    "required": ["sample", "fastq_1"]
}

fastq_1 é obrigatório; fastq_2 é opcional (suporta single-end).

8.4 Demonstração — samplesheet quebrada

malformed_samplesheet.csv:

sample,fastq_2
SAMPLE1,/not/a/real/file.fastq.gz

Este arquivo tem dois problemas: falta a coluna fastq_1 e o caminho em fastq_2 não existe.

nextflow run nf-core/demo -profile docker,test --outdir demo --input malformed_samplesheet.csv

ERROR ~ Validation of pipeline parameters failed!

* --input (malformed_samplesheet.csv): Validation of file failed:
    -> Entry 1: Error for field 'fastq_2' (/not/a/real/file.fastq.gz): the file
       or directory does not exist
    -> Entry 1: Missing required field(s): fastq_1

O nf-schema reporta todos os erros de uma vez, não só o primeiro. Você corrige tudo em uma iteração.

8.5 Quando algo falha na validação

Fluxo de debug:

Ler a mensagem — quase sempre diz exatamente qual campo/valor está errado.
Se for parâmetro: consultar nextflow run <pipeline> --help para ver tipo/formato esperado.
Se for samplesheet: abrir assets/schema_input.json do pipeline para ver o schema exato.
Corrigir e reexecutar — não precisa -resume, nada foi computado ainda.

8.6 Exercício 2 — Debugando uma samplesheet

Enunciado

Crie uma samplesheet bad_sheet.csv que quebre a validação de três formas diferentes ao mesmo tempo:

Uma coluna obrigatória faltando
Um caminho de arquivo com extensão inválida
Um nome de amostra com espaço em branco

Rode o pipeline e observe que os três erros aparecem numa mesma execução.

Resposta

bad_sheet.csv:

sample,fastq_2
SAMPLE UM,/tmp/reads.txt

Problemas:

Falta a coluna fastq_1 (obrigatória — required: ["sample", "fastq_1"])
.txt não bate com o padrão .f(ast)?q\.gz$
SAMPLE UM tem espaço — falha no padrão ^\S+$

Rode:

nextflow run nf-core/demo -profile docker,test --outdir demo-ex2 --input bad_sheet.csv

O nf-schema reporta os três erros de uma vez — você corrige tudo numa iteração só, sem ter que rodar três vezes.

9 Usando módulos nf-core

Todo pipeline nf-core é composto por módulos — processos que envolvem uma ferramenta específica (FASTQC, samtools, GATK…). Muitos são compartilhados entre pipelines através do repositório nf-core/modules.

Isso significa que, ao customizar ou construir um pipeline, você raramente precisa escrever um processo do zero: instale o módulo pronto e use.

9.1 Buscar módulos disponíveis

Pelo site: nf-co.re/modules — busca com filtro e página de doc para cada módulo (inputs, outputs, exemplo de uso).

Pela linha de comando (requer nf-core tools instalado):

nf-core modules list remote                        # lista todos
nf-core modules list remote | grep -i samtools     # filtra
nf-core modules info samtools/view                 # detalhes de um módulo

Convenção de nomes: o / na URL vira _ em alguns contextos. samtools/view = pacote samtools, comando view. Módulos com um único comando principal têm nome curto: fastqc, multiqc.

9.2 Instalar um módulo num pipeline

Dentro do diretório raiz de um pipeline nf-core:

nf-core modules install samtools/view

Isso faz três coisas:

Baixa os arquivos do módulo para modules/nf-core/samtools/view/.
Registra o módulo em modules.json (com SHA para reprodutibilidade).
Devolve a linha de include pronta para colar no workflow.

9.3 Estrutura do módulo instalado

modules/nf-core/samtools/view/
├── main.nf              # o processo em si
├── meta.yml             # descrição, inputs, outputs
├── environment.yml      # dependências conda
└── tests/               # testes automatizados

9.4 Importar e usar

include { SAMTOOLS_VIEW } from '../modules/nf-core/samtools/view/main'

Convenção: nomes de módulos importados ficam em MAIÚSCULAS.

9.5 Atualizar e desinstalar

nf-core modules update samtools/view     # atualiza para versão mais recente
nf-core modules uninstall samtools/view  # remove

9.6 Personalização — o padrão `ext.args` de novo

Como todo módulo nf-core respeita ext.args, você quase nunca precisa editar o código do módulo. Basta passar os argumentos extras via custom.config:

process {
    withName: 'SAMTOOLS_VIEW' {
        ext.args = '-b -q 30 -f 2'
    }
}

Se precisar de algo que ext.args não cobre (mudar a lógica do processo, adicionar um output), aí sim vale editar. Mas antes, cheque se o módulo aceita a customização por argumento — quase sempre aceita.

9.7 Exercício 3 — Adicionando um módulo ao pipeline demo

Enunciado

Vamos estender o pipeline nf-core/demo com o módulo seqkit/stats, que gera estatísticas resumidas de arquivos FASTQ (número de reads, tamanho médio, GC%, etc.).

Objetivo: após o SEQTK_TRIM, calcular as estatísticas dos reads trimados e publicá-las em <outdir>/seqkit_stats/.

Passos:

Descubra os inputs/outputs esperados pelo módulo seqkit/stats.
Instale o módulo no pipeline demo.
Importe o módulo no workflow (workflows/demo.nf).
Chame o módulo passando a saída do SEQTK_TRIM.
Execute o pipeline e confirme que o TSV com estatísticas foi gerado.

Trabalhe na cópia local do pipeline (via link simbólico pipelines/nf-core/demo/). O nextflow run pipelines/nf-core/demo executa a versão modificada.

Resposta

a) Consultar o módulo:

nf-core modules info seqkit/stats

O input é tuple val(meta), path(reads) — mesmo formato que o SEQTK_TRIM emite. O output principal é tuple val(meta), path("*.tsv").

b) Instalar (a partir da raiz do pipeline demo):

cd pipelines/nf-core/demo
nf-core modules install seqkit/stats

Cria modules/nf-core/seqkit/stats/ e registra em modules.json.

c) Em workflows/demo.nf, adicionar o include junto com os outros:

include { SEQKIT_STATS } from '../modules/nf-core/seqkit/stats/main'

d) Dentro do bloco if (!params.skip_trim) { ... }, chamar o novo módulo com a saída do trim:

if (!params.skip_trim) {
    SEQTK_TRIM(ch_samplesheet)
    SEQKIT_STATS(SEQTK_TRIM.out.reads)
}

Como as assinaturas batem (tuple val(meta), path(reads) dos dois lados), o encadeamento é direto — sem operadores no meio.

e) Executar:

nextflow run pipelines/nf-core/demo -profile docker,test --outdir demo-seqkit

Verificar o resultado:

cat demo-seqkit/seqkit_stats/*.tsv

Deve mostrar uma linha por arquivo FASTQ com número de reads, comprimento mínimo/máximo/médio e GC%.

Ponto-chave: instalamos e integramos um módulo mantido pela comunidade em ~5 linhas de código, sem escrever nenhum processo do zero. Esse é o padrão de crescimento de qualquer pipeline nf-core.

10 Próximos passos

Você viu tudo com o nf-core/demo, mas o padrão é o mesmo para qualquer pipeline da coleção. O que muda entre eles é o número de parâmetros, o volume de dados e o tempo de execução — mas o mecanismo de customização (-profile, -params-file, -c com ext.args) é idêntico.

Pipelines populares para começar a explorar:

nf-core/rnaseq — quantificação de expressão gênica a partir de RNA-seq
nf-core/sarek — chamada de variantes germinativas e somáticas (WGS/WES)
nf-core/ampliseq — análise de amplicons (16S, ITS)
nf-core/atacseq — ATAC-seq
nf-core/mag — metagenômica assembly

Fluxo recomendado para adotar um pipeline novo:

Ler a aba Introduction e o subway map no site
Ler a aba Parameters e escolher os obrigatórios
Rodar o -profile test para confirmar que o ambiente funciona
Preparar a samplesheet no formato do assets/schema_input.json
Rodar com seus dados reais + custom.config para ajustar recursos/ext.args

Comunidade: nf-core Slack para tirar dúvidas — muito ativa e receptiva.

6.1 Recuperar o código do pipeline Demo

6.2 Estrutura de um pipeline nf-core

6.3 Examinar o perfil de teste

6.4 Examinar o workflow do pipeline

6.5 Executar o pipeline

7 Configurar a execução do pipeline

7.1 Parâmetros do pipeline

7.1.1 Listar todos os parâmetros com --help

7.1.2 Definir valores de parâmetros

7.2 Validação automática de parâmetros

7.3 Configuração propriamente dita

7.4 Personalizar recursos e argumentos com -c

7.5 ext.args — o padrão-chave para customização

7.6 Exercício 1 — Customizar ext.args

8 Validação de entradas

8.1 Dois níveis de validação

8.2 Validação de parâmetros

8.3 Validação de samplesheet

8.4 Demonstração — samplesheet quebrada

8.5 Quando algo falha na validação

8.6 Exercício 2 — Debugando uma samplesheet

9 Usando módulos nf-core

9.1 Buscar módulos disponíveis

9.2 Instalar um módulo num pipeline

9.3 Estrutura do módulo instalado

9.4 Importar e usar

9.5 Atualizar e desinstalar

9.6 Personalização — o padrão ext.args de novo

9.7 Exercício 3 — Adicionando um módulo ao pipeline demo

10 Próximos passos

7.1.1 Listar todos os parâmetros com `--help`

7.4 Personalizar recursos e argumentos com `-c`

7.5 `ext.args` — o padrão-chave para customização

7.6 Exercício 1 — Customizar `ext.args`

9.6 Personalização — o padrão `ext.args` de novo