Parte 6: Hello Config¶
Tradução assistida por IA - saiba mais e sugira melhorias
Esta seção explorará como configurar e gerenciar a configuração do seu pipeline Nextflow para que você possa personalizar seu comportamento, adaptá-lo a diferentes ambientes e otimizar o uso de recursos sem alterar uma única linha do código do fluxo de trabalho.
Existem várias maneiras de fazer isso, que podem ser usadas em combinação e são interpretadas de acordo com a ordem de precedência descrita aqui.
Nesta parte do curso, vamos mostrar o mecanismo de arquivo de configuração mais simples e comum, o arquivo nextflow.config, que você já encontrou na Parte 5: Hello Containers.
Vamos abordar componentes essenciais da configuração do Nextflow, como diretivas de processos, executores, perfis e arquivos de parâmetros. Ao aprender a utilizar essas opções de configuração de forma eficaz, você pode melhorar a flexibilidade, escalabilidade e desempenho dos seus pipelines.
Como começar a partir desta seção
Esta seção do curso assume que você completou as Partes 1-5 do curso Hello Nextflow e tem um pipeline completo funcionando.
Se você está começando o curso a partir deste ponto, precisará copiar o diretório modules e o arquivo nextflow.config das soluções:
O arquivo nextflow.config contém a linha docker.enabled = true que habilita o uso de contêineres Docker.
Se você não está familiarizado com o pipeline Hello ou precisa relembrar, veja esta página de informações.
0. Aquecimento: Execute hello-config.nf¶
Vamos usar o script do fluxo de trabalho hello-config.nf como ponto de partida.
Ele é equivalente ao script produzido ao trabalhar na Parte 5 deste curso de treinamento, exceto que mudamos os destinos de saída:
| hello-config.nf | |
|---|---|
Apenas para garantir que tudo está funcionando, execute o script uma vez antes de fazer qualquer alteração:
Saída do comando
Como anteriormente, você encontrará os arquivos de saída no diretório especificado no bloco output (results/hello_config/).
Conteúdo do diretório
A saída final em arte ASCII está no diretório results/hello_config/, com o nome cowpy-COLLECTED-batch-output.txt.
Conteúdo do arquivo
_________
/ HOLà \
| HELLO |
\ BONJOUR /
---------
\ ,+*^^*+___+++_
\ ,*^^^^ )
\ _+* ^**+_
\ +^ _ _++*+_+++_, )
_+^^*+_ ( ,+*^ ^ \+_ )
{ ) ( ,( ,_+--+--, ^) ^\
{ (\@) } f ,( ,+-^ __*_*_ ^^\_ ^\ )
{:;-/ (_+*-+^^^^^+*+*<_ _++_)_ ) ) /
( / ( ( ,___ ^*+_+* ) < < \
U _/ ) *--< ) ^\-----++__) ) ) )
( ) _(^)^^)) ) )\^^^^^))^*+/ / /
( / (_))_^)) ) ) ))^^^^^))^^^)__/ +^^
( ,/ (^))^)) ) ) ))^^^^^^^))^^) _)
*+__+* (_))^) ) ) ))^^^^^^))^^^^^)____*^
\ \_)^)_)) ))^^^^^^^^^^))^^^^)
(_ ^\__^^^^^^^^^^^^))^^^^^^^)
^\___ ^\__^^^^^^))^^^^^^^^)\\
^^^^^\uuu/^^\uuu/^^^^\^\^\^\^\^\^\^\
___) >____) >___ ^\_\_\_\_\_\_\)
^^^//\\_^^//\\_^ ^(\_\_\_\)
^^^ ^^ ^^^ ^
Se isso funcionou para você, está pronto para aprender como configurar seus pipelines.
1. Gerencie parâmetros de entrada do fluxo de trabalho¶
Vamos começar com um aspecto da configuração que é simplesmente uma extensão do que temos trabalhado até agora: o gerenciamento de parâmetros de entrada.
Atualmente, nosso fluxo de trabalho está configurado para aceitar vários valores de parâmetros via linha de comando, com valores padrão definidos em um bloco params no próprio script do fluxo de trabalho.
No entanto, você pode querer substituir esses padrões sem ter que especificar parâmetros na linha de comando ou modificar o arquivo de script original.
Existem várias maneiras de fazer isso; vamos mostrar três formas básicas que são muito comumente usadas.
1.1. Mova os valores padrão para o nextflow.config¶
Esta é a abordagem mais simples, embora seja possivelmente a menos flexível, já que o arquivo nextflow.config principal não é algo que você quer estar editando para cada execução.
Mas tem a vantagem de separar as preocupações de declarar os parâmetros no fluxo de trabalho (que definitivamente pertence lá) versus fornecer valores padrão, que estão mais em casa em um arquivo de configuração.
Vamos fazer isso em dois passos.
1.1.1. Crie um bloco params no arquivo de configuração¶
Faça as seguintes alterações de código no arquivo nextflow.config:
Note que não simplesmente copiamos o bloco params do fluxo de trabalho para o arquivo de configuração.
A sintaxe é um pouco diferente.
No arquivo de fluxo de trabalho, essas são declarações tipadas.
Na configuração, essas são atribuições de valores.
Tecnicamente, isso é suficiente para substituir os valores padrão ainda especificados no arquivo de fluxo de trabalho. Você poderia modificar o caractere, por exemplo, e executar o fluxo de trabalho para se convencer de que o valor definido no arquivo de configuração substitui o definido no arquivo de fluxo de trabalho.
Mas no espírito de mover a configuração completamente para o arquivo de configuração, vamos remover esses valores do arquivo de fluxo de trabalho inteiramente.
1.1.2. Remova os valores do bloco params no arquivo de fluxo de trabalho¶
Faça as seguintes alterações de código no arquivo de fluxo de trabalho hello-config.nf:
Agora o arquivo de fluxo de trabalho em si não define nenhum valor padrão para esses parâmetros.
1.1.3. Execute o pipeline¶
Vamos testar se funciona corretamente.
Saída do comando
Isso ainda produz a mesma saída de antes.
A saída final em arte ASCII está no diretório results/hello_config/, com o nome cowpy-COLLECTED-batch-output.txt, igual a antes.
Conteúdo do arquivo
_________
/ HOLà \
| HELLO |
\ BONJOUR /
---------
\ ,+*^^*+___+++_
\ ,*^^^^ )
\ _+* ^**+_
\ +^ _ _++*+_+++_, )
_+^^*+_ ( ,+*^ ^ \+_ )
{ ) ( ,( ,_+--+--, ^) ^\
{ (\@) } f ,( ,+-^ __*_*_ ^^\_ ^\ )
{:;-/ (_+*-+^^^^^+*+*<_ _++_)_ ) ) /
( / ( ( ,___ ^*+_+* ) < < \
U _/ ) *--< ) ^\-----++__) ) ) )
( ) _(^)^^)) ) )\^^^^^))^*+/ / /
( / (_))_^)) ) ) ))^^^^^))^^^)__/ +^^
( ,/ (^))^)) ) ) ))^^^^^^^))^^) _)
*+__+* (_))^) ) ) ))^^^^^^))^^^^^)____*^
\ \_)^)_)) ))^^^^^^^^^^))^^^^)
(_ ^\__^^^^^^^^^^^^))^^^^^^^)
^\___ ^\__^^^^^^))^^^^^^^^)\\
^^^^^\uuu/^^\uuu/^^^^\^\^\^\^\^\^\^\
___) >____) >___ ^\_\_\_\_\_\_\)
^^^//\\_^^//\\_^ ^(\_\_\_\)
^^^ ^^ ^^^ ^
Funcionalmente, essa mudança não alterou nada, mas conceitualmente é um pouco mais limpo ter os valores padrão definidos no arquivo de configuração.
1.2. Use um arquivo de configuração específico para a execução¶
Isso é ótimo, mas às vezes você pode querer executar alguns experimentos temporários com diferentes valores padrão sem mexer no arquivo de configuração principal.
Você pode fazer isso criando um novo arquivo nextflow.config em um subdiretório que você usará como diretório de trabalho para seus experimentos.
1.2.1. Crie o diretório de trabalho com uma configuração em branco¶
Vamos começar criando um novo diretório e entrando nele:
Em seguida, crie um arquivo de configuração em branco nesse diretório:
Isso produz um arquivo vazio.
1.2.2. Configure a configuração experimental¶
Agora abra o novo arquivo e adicione os parâmetros que você deseja personalizar:
| tux-run/nextflow.config | |
|---|---|
Note que o caminho para o arquivo de entrada deve refletir a estrutura de diretórios.
1.2.3. Execute o pipeline¶
Agora podemos executar nosso pipeline de dentro do nosso novo diretório de trabalho. Certifique-se de adaptar o caminho adequadamente!
Saída do comando
Isso criará um novo conjunto de diretórios em tux-run/ incluindo tux-run/work/ e tux-run/results/.
Nesta execução, o Nextflow combina o nextflow.config no nosso diretório atual com o nextflow.config no diretório raiz do pipeline, e assim substitui o caractere padrão (turkey) pelo caractere tux.
O arquivo de saída final deve conter o caractere tux dizendo as saudações.
Conteúdo do arquivo
É isso; agora você tem um espaço para experimentar sem modificar sua configuração 'normal'.
Agora vamos ver outra maneira útil de definir valores de parâmetros.
1.3. Use um arquivo de parâmetros¶
A abordagem de subdiretório funciona muito bem para experimentar, mas envolve um pouco de configuração e requer que você adapte os caminhos adequadamente. Existe uma abordagem mais simples para quando você quer executar seu pipeline com um conjunto específico de valores, ou permitir que outra pessoa faça isso com o mínimo de esforço.
O Nextflow nos permite especificar parâmetros via um arquivo de parâmetros no formato YAML ou JSON, o que torna muito conveniente gerenciar e distribuir conjuntos alternativos de valores padrão, por exemplo, assim como valores de parâmetros específicos da execução.
1.3.1. Examine o arquivo de parâmetros de exemplo¶
Para demonstrar isso, fornecemos um arquivo de parâmetros de exemplo no diretório atual, chamado test-params.yaml:
Este arquivo de parâmetros contém um par chave-valor para cada uma das entradas que queremos especificar.
Note o uso de dois pontos (:) em vez de sinais de igual (=) se você comparar a sintaxe com o arquivo de configuração.
O arquivo de configuração é escrito em Groovy, enquanto o arquivo de parâmetros é escrito em YAML.
Info
Também fornecemos uma versão JSON do arquivo de parâmetros como exemplo, mas não vamos executar com ela aqui. Sinta-se livre para tentar essa por conta própria.
1.3.2. Execute o pipeline¶
Para executar o fluxo de trabalho com este arquivo de parâmetros, simplesmente adicione -params-file <filename> ao comando base.
Saída do comando
O arquivo de saída final deve conter o caractere stegosaurus dizendo as saudações.
Conteúdo do arquivo
_________
/ HELLO \
| HOLà |
\ BONJOUR /
---------
\ . .
\ / `. .' "
\ .---. < > < > .---.
\ | \ \ - ~ ~ - / / |
_____ ..-~ ~-..-~
| | \~~~\.' `./~~~/
--------- \__/ \__/
.' O \ / / \ "
(_____, `._.' | } \/~~~/
`----. / } | / \__/
`-. | / | / `. ,~~|
~-.__| /_ - ~ ^| /- _ `..-'
| / | / ~-. `-. _ _ _
|_____| |_____| ~ - . _ _ _ _ _>
Usar um arquivo de parâmetros pode parecer exagero quando você tem apenas alguns parâmetros para especificar, mas alguns pipelines esperam dezenas de parâmetros. Nesses casos, usar um arquivo de parâmetros nos permitirá fornecer valores de parâmetros no tempo de execução sem ter que digitar linhas de comando enormes e sem modificar o script do fluxo de trabalho.
Também torna mais fácil distribuir conjuntos de parâmetros para colaboradores, ou como informação de apoio para uma publicação, por exemplo. Isso torna seu trabalho mais reproduzível por outros.
Conclusão¶
Você sabe como aproveitar as principais opções de configuração para gerenciar entradas do fluxo de trabalho.
O que vem a seguir?¶
Aprenda como gerenciar onde e como as saídas do seu fluxo de trabalho são publicadas.
2. Gerencie saídas do fluxo de trabalho¶
Até agora temos codificado todos os caminhos para declarações de saída no nível do fluxo de trabalho, e como notamos quando começamos a adicionar múltiplas saídas, pode haver um pouco de repetição envolvida.
Vamos ver algumas maneiras comuns de configurar isso para ser mais flexível.
2.1. Personalize o nome do diretório outputDir¶
Para cada capítulo deste curso, temos publicado saídas em um subdiretório diferente codificado nas definições de saída.
Vamos mudar isso para usar um parâmetro configurável pelo usuário.
Poderíamos criar um parâmetro totalmente novo para isso, mas vamos usar o parâmetro batch já que está bem ali.
2.1.1. Defina um valor para outputDir no arquivo de configuração¶
O caminho que o Nextflow usa para publicar saídas é controlado pela opção outputDir.
Para mudar o caminho para todas as saídas, você pode definir um valor para esta opção no arquivo de configuração nextflow.config.
Adicione o seguinte código ao arquivo nextflow.config:
Isso substituirá o caminho padrão integrado, results/, por results/ mais o valor do parâmetro batch como subdiretório.
Você também poderia mudar a parte results se quisesse.
Para uma mudança temporária, você poderia definir esta opção da linha de comando usando o parâmetro -output-dir no seu comando (mas então você não poderia usar o valor do parâmetro batch).
2.1.2. Remova a parte repetida do caminho codificado¶
Ainda temos um subdiretório codificado nas opções de saída, então vamos nos livrar disso agora.
Faça as seguintes alterações de código no arquivo de fluxo de trabalho:
| hello-config.nf | |
|---|---|
| hello-config.nf | |
|---|---|
Também poderíamos ter apenas adicionado ${params.batch} a cada caminho em vez de modificar o padrão outputDir, mas isso é mais conciso.
2.1.3. Execute o pipeline¶
Vamos testar se funciona corretamente, definindo o nome do lote como outdir a partir da linha de comando.
Saída do comando
Isso ainda produz a mesma saída de antes, exceto que desta vez encontramos nossas saídas em results/outdir/.
Conteúdo do diretório
Você pode combinar esta abordagem com definições de caminho personalizadas para construir qualquer hierarquia de diretórios que desejar.
2.2. Organize saídas por processo¶
Uma maneira popular de organizar ainda mais as saídas é fazer isso por processo, ou seja, criar subdiretórios para cada processo executado no pipeline.
2.2.1. Substitua os caminhos de saída por uma referência aos nomes dos processos¶
Tudo o que você precisa fazer é referenciar o nome do processo como <task>.name na declaração do caminho de saída.
Faça as seguintes alterações no arquivo de fluxo de trabalho:
| hello-config.nf | |
|---|---|
| hello-config.nf | |
|---|---|
Isso remove os elementos codificados restantes da configuração do caminho de saída.
2.2.2. Execute o pipeline¶
Vamos testar se funciona corretamente, definindo o nome do lote como pnames a partir da linha de comando.
Saída do comando
Isso ainda produz a mesma saída de antes, exceto que desta vez encontramos nossas saídas em results/pnames/, e elas estão agrupadas por processo.
Conteúdo do diretório
results/pnames/
├── collectGreetings
│ ├── COLLECTED-pnames-output.txt
│ └── pnames-report.txt
├── convertToUpper
│ ├── UPPER-Bonjour-output.txt
│ ├── UPPER-Hello-output.txt
│ └── UPPER-Holà-output.txt
├── cowpy
│ └── cowpy-COLLECTED-pnames-output.txt
└── sayHello
├── Bonjour-output.txt
├── Hello-output.txt
└── Holà-output.txt
Note que aqui apagamos a distinção entre intermediates versus saídas finais estando no nível superior.
Você poderia, é claro, misturar e combinar essas abordagens, por exemplo, definindo o caminho da primeira saída como intermediates/${sayHello.process}
2.3. Defina o modo de publicação no nível do fluxo de trabalho¶
Finalmente, no espírito de reduzir a quantidade de código repetitivo, podemos substituir as declarações mode por saída com uma única linha na configuração.
2.3.1. Adicione workflow.output.mode ao arquivo de configuração¶
Adicione o seguinte código ao arquivo nextflow.config:
Assim como a opção outputDir, dar a workflow.output.mode um valor no arquivo de configuração seria suficiente para substituir o que está definido no arquivo de fluxo de trabalho, mas vamos remover o código desnecessário de qualquer forma.
2.3.2. Remova o modo de saída do arquivo de fluxo de trabalho¶
Faça as seguintes alterações no arquivo de fluxo de trabalho:
| hello-config.nf | |
|---|---|
| hello-config.nf | |
|---|---|
Isso é mais conciso, não é?
2.3.3. Execute o pipeline¶
Vamos testar se funciona corretamente, definindo o nome do lote como outmode a partir da linha de comando.
Saída do comando
Isso ainda produz a mesma saída de antes, exceto que desta vez encontramos nossas saídas em results/outmode/.
Todas ainda são cópias adequadas, não symlinks.
Conteúdo do diretório
results/outmode/
├── collectGreetings
│ ├── COLLECTED-outmode-output.txt
│ └── outmode-report.txt
├── convertToUpper
│ ├── UPPER-Bonjour-output.txt
│ ├── UPPER-Hello-output.txt
│ └── UPPER-Holà-output.txt
├── cowpy
│ └── cowpy-COLLECTED-outmode-output.txt
└── sayHello
├── Bonjour-output.txt
├── Hello-output.txt
└── Holà-output.txt
A principal razão pela qual você ainda pode querer usar a maneira por saída de definir o modo é se você quiser misturar e combinar dentro do mesmo fluxo de trabalho, ou seja, ter algumas saídas sendo copiadas e algumas sendo symlinkadas.
Existem muitas outras opções que você pode personalizar dessa maneira, mas esperamos que isso lhe dê uma noção da gama de opções e como utilizá-las efetivamente para atender às suas preferências.
Conclusão¶
Você sabe como controlar a nomenclatura e estrutura dos diretórios onde suas saídas são publicadas, bem como o modo de publicação de saída do fluxo de trabalho.
O que vem a seguir?¶
Aprenda como adaptar a configuração do seu fluxo de trabalho ao seu ambiente de computação, começando com a tecnologia de empacotamento de software.
3. Selecione uma tecnologia de empacotamento de software¶
Até agora temos visto elementos de configuração que controlam como as entradas entram e onde as saídas saem. Agora é hora de focar mais especificamente em adaptar a configuração do seu fluxo de trabalho ao seu ambiente de computação.
O primeiro passo nesse caminho é especificar de onde virão os pacotes de software que serão executados em cada etapa. Eles já estão instalados no ambiente de computação local? Precisamos recuperar imagens e executá-las via um sistema de contêineres? Ou precisamos recuperar pacotes Conda e construir um ambiente Conda local?
Na primeira parte deste curso de treinamento (Partes 1-4) apenas usamos software instalado localmente em nosso fluxo de trabalho.
Então na Parte 5, introduzimos contêineres Docker e o arquivo nextflow.config, que usamos para habilitar o uso de contêineres Docker.
Agora vamos ver como podemos configurar uma opção alternativa de empacotamento de software via o arquivo nextflow.config.
3.1. Desabilite o Docker e habilite o Conda no arquivo de configuração¶
Vamos fingir que estamos trabalhando em um cluster HPC e o administrador não permite o uso do Docker por razões de segurança. Felizmente para nós, o Nextflow suporta múltiplas outras tecnologias de contêineres, incluindo Singularity (que é mais amplamente usado em HPC), e gerenciadores de pacotes de software como Conda.
Podemos mudar nosso arquivo de configuração para usar Conda em vez de Docker.
Para fazer isso, vamos mudar o valor de docker.enabled para false, e adicionar uma diretiva habilitando o uso do Conda:
Isso permitirá que o Nextflow crie e utilize ambientes Conda para processos que têm pacotes Conda especificados.
O que significa que agora precisamos adicionar um desses ao nosso processo cowpy!
3.2. Especifique um pacote Conda na definição do processo¶
Já recuperamos o URI para um pacote Conda contendo a ferramenta cowpy: conda-forge::cowpy==1.1.5
Agora adicionamos o URI à definição do processo cowpy usando a diretiva conda:
Para ser claro, não estamos substituindo a diretiva docker, estamos adicionando uma opção alternativa.
Tip
Existem algumas maneiras diferentes de obter o URI para um determinado pacote conda. Recomendamos usar a consulta de busca Seqera Containers, que lhe dará um URI que você pode copiar e colar, mesmo que você não esteja planejando criar um contêiner a partir dele.
3.3. Execute o fluxo de trabalho para verificar que ele pode usar Conda¶
Vamos experimentar.
Saída do comando
Isso deve funcionar sem problemas e produzir as mesmas saídas de antes em results/conda.
Nos bastidores, o Nextflow recuperou os pacotes Conda e criou o ambiente, o que normalmente requer um pouco de trabalho; então é bom que não tenhamos que fazer nada disso nós mesmos!
Note
Isso executa rapidamente porque o pacote cowpy é bastante pequeno, mas se você estiver trabalhando com pacotes grandes, pode levar um pouco mais de tempo do que o normal na primeira vez, e você pode ver a saída do console ficar 'presa' por um minuto ou mais antes de completar.
Isso é normal e se deve ao trabalho extra que o Nextflow faz na primeira vez que você usa um novo pacote.
Do nosso ponto de vista, parece que funciona exatamente da mesma forma que executar com Docker, embora no backend a mecânica seja um pouco diferente.
Isso significa que estamos todos prontos para executar com ambientes Conda se necessário.
Misturando e combinando Docker e Conda
Como essas diretivas são atribuídas por processo, é possível 'misturar e combinar', ou seja, configurar alguns dos processos em seu fluxo de trabalho para executar com Docker e outros com Conda, por exemplo, se a infraestrutura de computação que você está usando suporta ambos. Nesse caso, você habilitaria tanto Docker quanto Conda no seu arquivo de configuração. Se ambos estiverem disponíveis para um determinado processo, o Nextflow priorizará contêineres.
E como observado anteriormente, o Nextflow suporta múltiplas outras tecnologias de empacotamento de software e contêineres, então você não está limitado a apenas essas duas.
Conclusão¶
Você sabe como configurar qual pacote de software cada processo deve usar, e como alternar entre tecnologias.
O que vem a seguir?¶
Aprenda como mudar a plataforma de execução usada pelo Nextflow para realmente fazer o trabalho.
4. Selecione uma plataforma de execução¶
Até agora, temos executado nosso pipeline com o executor local. Isso executa cada tarefa na máquina em que o Nextflow está sendo executado. Quando o Nextflow começa, ele verifica as CPUs e memória disponíveis. Se os recursos das tarefas prontas para executar excedem os recursos disponíveis, o Nextflow manterá as últimas tarefas de volta da execução até que uma ou mais das tarefas anteriores tenham terminado, liberando os recursos necessários.
O executor local é conveniente e eficiente, mas é limitado àquela única máquina. Para cargas de trabalho muito grandes, você pode descobrir que sua máquina local é um gargalo, seja porque você tem uma única tarefa que requer mais recursos do que você tem disponíveis, ou porque você tem tantas tarefas que esperar por uma única máquina para executá-las levaria muito tempo.
O Nextflow suporta muitos backends de execução diferentes, incluindo agendadores HPC (Slurm, LSF, SGE, PBS, Moab, OAR, Bridge, HTCondor e outros), bem como backends de execução em nuvem (AWS Batch, Google Cloud Batch, Azure Batch, Kubernetes e mais).
4.1. Direcionando um backend diferente¶
A escolha do executor é definida por uma diretiva de processo chamada executor.
Por padrão, é definido como local, então a seguinte configuração está implícita:
Para definir o executor para direcionar um backend diferente, você simplesmente especificaria o executor que deseja usando sintaxe similar à descrita acima para alocações de recursos (veja a documentação para todas as opções).
Warning
Não podemos realmente testar isso no ambiente de treinamento porque não está configurado para se conectar a um HPC.
4.2. Lidando com sintaxe específica do backend para parâmetros de execução¶
A maioria das plataformas de computação de alto desempenho permite (e às vezes exige) que você especifique certos parâmetros, como solicitações e limitações de alocação de recursos (por exemplo, número de CPUs e memória) e nome da fila de trabalhos a ser usada.
Infelizmente, cada um desses sistemas usa tecnologias, sintaxes e configurações diferentes para definir como um trabalho deve ser definido e submetido ao agendador relevante.
Exemplos
Por exemplo, o mesmo trabalho requerendo 8 CPUs e 4GB de RAM para ser executado na fila "my-science-work" precisa ser expresso das seguintes maneiras diferentes dependendo do backend.
#SBATCH -o /path/to/my/task/directory/my-task-1.log
#SBATCH --no-requeue
#SBATCH -c 8
#SBATCH --mem 4096M
#SBATCH -p my-science-work
Felizmente, o Nextflow simplifica tudo isso.
Ele fornece uma sintaxe padronizada para que você possa especificar as propriedades relevantes como cpus, memory e queue (veja a documentação para outras propriedades) apenas uma vez.
Então, no tempo de execução, o Nextflow usará essas configurações para gerar os scripts específicos do backend apropriados com base na configuração do executor.
Vamos cobrir essa sintaxe padronizada na próxima seção.
Conclusão¶
Você agora sabe como mudar o executor para usar diferentes tipos de infraestrutura de computação.
O que vem a seguir?¶
Aprenda como avaliar e expressar alocações e limitações de recursos no Nextflow.
5. Controle alocações de recursos de computação¶
A maioria das plataformas de computação de alto desempenho permite (e às vezes exige) que você especifique certos parâmetros de alocação de recursos, como número de CPUs e memória.
Por padrão, o Nextflow usará uma única CPU e 2GB de memória para cada processo.
As diretivas de processo correspondentes são chamadas cpus e memory, então a seguinte configuração está implícita:
Você pode modificar esses valores, seja para todos os processos ou para processos nomeados específicos, usando diretivas de processo adicionais no seu arquivo de configuração. O Nextflow os traduzirá nas instruções apropriadas para o executor escolhido.
Mas como você sabe quais valores usar?
5.1. Execute o fluxo de trabalho para gerar um relatório de utilização de recursos¶
Se você não sabe de antemão quanta CPU e memória seus processos provavelmente precisarão, você pode fazer algum perfil de recursos, o que significa que você executa o fluxo de trabalho com algumas alocações padrão, registra quanto cada processo usou e, a partir daí, estima como ajustar as alocações base.
Convenientemente, o Nextflow inclui ferramentas integradas para fazer isso, e irá gerar alegremente um relatório para você mediante solicitação.
Para fazer isso, adicione -with-report <filename>.html à sua linha de comando.
O relatório é um arquivo html, que você pode baixar e abrir no seu navegador. Você também pode clicar com o botão direito nele no explorador de arquivos à esquerda e clicar em Show preview para visualizá-lo no ambiente de treinamento.
Reserve alguns minutos para examinar o relatório e ver se você consegue identificar algumas oportunidades para ajustar recursos. Certifique-se de clicar nas abas que mostram os resultados de utilização como uma porcentagem do que foi alocado. Há alguma documentação descrevendo todos os recursos disponíveis.
5.2. Defina alocações de recursos para todos os processos¶
O perfil mostra que os processos em nosso fluxo de trabalho de treinamento são muito leves, então vamos reduzir a alocação de memória padrão para 1GB por processo.
Adicione o seguinte ao seu arquivo nextflow.config, antes da seção de parâmetros do pipeline:
Isso ajudará a reduzir a quantidade de computação que consumimos.
5.3. Defina alocações de recursos para um processo específico¶
Ao mesmo tempo, vamos fingir que o processo cowpy requer mais recursos do que os outros, apenas para que possamos demonstrar como ajustar alocações para um processo individual.
Com esta configuração, todos os processos solicitarão 1GB de memória e uma única CPU (o padrão implícito), exceto o processo cowpy, que solicitará 2GB e 2 CPUs.
Tip
Se você tiver uma máquina com poucas CPUs e alocar um número alto por processo, poderá ver chamadas de processo sendo enfileiradas uma atrás da outra. Isso ocorre porque o Nextflow garante que não solicitemos mais CPUs do que as disponíveis.
5.4. Execute o fluxo de trabalho com a configuração atualizada¶
Vamos experimentar isso, fornecendo um nome de arquivo diferente para o relatório de perfil para que possamos comparar o desempenho antes e depois das mudanças de configuração.
Você provavelmente não notará nenhuma diferença real, pois esta é uma carga de trabalho tão pequena, mas esta é a abordagem que você usaria para analisar o desempenho e os requisitos de recursos de um fluxo de trabalho do mundo real.
É muito útil quando seus processos têm requisitos de recursos diferentes. Ele o capacita a dimensionar corretamente as alocações de recursos que você configura para cada processo com base em dados reais, não em suposições.
Tip
Este é apenas um pequeno aperitivo do que você pode fazer para otimizar seu uso de recursos. O próprio Nextflow tem uma lógica de repetição dinâmica realmente interessante embutida para repetir trabalhos que falham devido a limitações de recursos. Além disso, a Seqera Platform oferece ferramentas orientadas por IA para otimizar suas alocações de recursos automaticamente também.
5.5. Adicione limites de recursos¶
Dependendo de qual executor de computação e infraestrutura de computação você está usando, pode haver algumas restrições sobre o que você pode (ou deve) alocar. Por exemplo, seu cluster pode exigir que você permaneça dentro de certos limites.
Você pode usar a diretiva resourceLimits para definir as limitações relevantes. A sintaxe se parece com isso quando está sozinha em um bloco de processo:
O Nextflow traduzirá esses valores nas instruções apropriadas dependendo do executor que você especificou.
Não vamos executar isso, pois não temos acesso à infraestrutura relevante no ambiente de treinamento.
No entanto, se você tentasse executar o fluxo de trabalho com alocações de recursos que excedem esses limites, então procurasse o comando sbatch no arquivo de script .command.run, você veria que as solicitações que realmente são enviadas ao executor são limitadas aos valores especificados por resourceLimits.
Configurações de referência institucionais
O projeto nf-core compilou uma coleção de arquivos de configuração compartilhados por várias instituições ao redor do mundo, cobrindo uma ampla gama de executores HPC e nuvem.
Essas configurações compartilhadas são valiosas tanto para pessoas que trabalham lá e, portanto, podem simplesmente utilizar a configuração de sua instituição pronta para uso, quanto como modelo para pessoas que estão procurando desenvolver uma configuração para sua própria infraestrutura.
Conclusão¶
Você sabe como gerar um relatório de perfil para avaliar a utilização de recursos e como modificar alocações de recursos para todos os processos e/ou para processos individuais, bem como definir limitações de recursos para executar em HPC.
O que vem a seguir?¶
Aprenda como configurar perfis de configuração predefinidos e alternar entre eles no tempo de execução.
6. Use perfis para alternar entre configurações predefinidas¶
Mostramos a você várias maneiras de personalizar a configuração do seu pipeline dependendo do projeto em que você está trabalhando ou do ambiente de computação que está usando.
Você pode querer alternar entre configurações alternativas dependendo de qual infraestrutura de computação está usando. Por exemplo, você pode querer desenvolver e executar testes em pequena escala localmente no seu laptop, depois executar cargas de trabalho em escala completa em HPC ou nuvem.
O Nextflow permite que você configure qualquer número de perfis que descrevem diferentes configurações, que você pode então selecionar no tempo de execução usando um argumento de linha de comando, em vez de ter que modificar o arquivo de configuração em si.
6.1. Crie perfis para alternar entre desenvolvimento local e execução em HPC¶
Vamos configurar dois perfis alternativos; um para executar cargas em pequena escala em um computador normal, onde usaremos contêineres Docker, e outro para executar em um HPC universitário com um agendador Slurm, onde usaremos pacotes Conda.
6.1.1. Configure os perfis¶
Adicione o seguinte ao seu arquivo nextflow.config, após a seção de parâmetros do pipeline, mas antes das configurações de saída:
| nextflow.config | |
|---|---|
Você vê que para o HPC universitário, também estamos especificando limitações de recursos.
6.1.2. Execute o fluxo de trabalho com um perfil¶
Para especificar um perfil na nossa linha de comando do Nextflow, usamos o argumento -profile.
Vamos tentar executar o fluxo de trabalho com a configuração my_laptop.
Saída do comando
Como você pode ver, isso nos permite alternar entre configurações muito convenientemente no tempo de execução.
Warning
O perfil univ_hpc não será executado corretamente no ambiente de treinamento, pois não temos acesso a um agendador Slurm.
Se no futuro encontrarmos outros elementos de configuração que estão sempre co-ocorrendo com esses, podemos simplesmente adicioná-los ao(s) perfil(is) correspondente(s). Também podemos criar perfis adicionais se houver outros elementos de configuração que queremos agrupar.
6.2. Crie um perfil de parâmetros de teste¶
Perfis não são apenas para configuração de infraestrutura. Também podemos usá-los para definir valores padrão para parâmetros de fluxo de trabalho, para facilitar que outros experimentem o fluxo de trabalho sem ter que reunir valores de entrada apropriados por conta própria. Você pode considerar isso uma alternativa ao uso de um arquivo de parâmetros.
6.2.1. Configure o perfil¶
A sintaxe para expressar valores padrão neste contexto se parece com isso, para um perfil que nomeamos test:
Se adicionarmos um perfil de teste para nosso fluxo de trabalho, o bloco profiles se torna:
Assim como para perfis de configuração técnica, você pode configurar vários perfis diferentes especificando parâmetros sob qualquer