Parte 3: Configurazione¶
Traduzione assistita da IA - scopri di più e suggerisci miglioramenti
Questa sezione esplorerà come gestire la configurazione di una pipeline Nextflow per personalizzarne il comportamento, adattarla a diversi ambienti e ottimizzare l'uso delle risorse senza modificare una singola riga del codice del workflow stesso.
Ci sono molteplici modi per farlo, che possono essere usati in combinazione e vengono interpretati secondo l'ordine di precedenza descritto qui.
In questa parte del corso, ti mostreremo il meccanismo di file di configurazione più semplice e comune, il file nextflow.config, che hai già incontrato nella sezione sui container nella Parte 2.
Esamineremo i componenti essenziali della configurazione di Nextflow come le direttive dei process, gli executor, i profili e i file di parametri. Imparando a utilizzare efficacemente queste opzioni di configurazione, puoi sfruttare appieno la flessibilità, la scalabilità e le prestazioni delle pipeline Nextflow.
Per esercitare questi elementi di configurazione, eseguiremo una copia fresca del workflow che abbiamo eseguito per ultimo alla fine della Parte 2 di questo corso di formazione, rinominato 3-main.nf.
Se non hai familiarità con la pipeline Hello o potresti aver bisogno di un promemoria, consulta questa pagina informativa.
1. Gestire i parametri di input del workflow¶
Scenario
Hai scaricato una pipeline e vuoi eseguirla ripetutamente con gli stessi file di input e impostazioni, ma non vuoi digitare tutti i parametri ogni volta. O forse stai configurando la pipeline per un collega che non è a suo agio con gli argomenti da riga di comando.
Inizieremo con un aspetto della configurazione che è semplicemente un'estensione di ciò con cui abbiamo lavorato finora: la gestione dei parametri di input.
Attualmente, il nostro workflow è configurato per accettare diversi valori di parametri tramite la riga di comando, dichiarati in un blocco params nello script del workflow stesso.
Uno ha un valore predefinito impostato come parte della sua dichiarazione.
Tuttavia, potresti voler impostare valori predefiniti per tutti loro, o sovrascrivere il valore predefinito esistente senza dover specificare parametri sulla riga di comando o modificare il file di script originale.
Ci sono molteplici modi per farlo; ti mostreremo tre modi base che sono molto comunemente usati.
1.1. Imposta i valori in nextflow.config¶
Questo è l'approccio più semplice, sebbene sia probabilmente il meno flessibile poiché il file nextflow.config principale non è qualcosa che vuoi modificare per ogni esecuzione.
Ma ha il vantaggio di separare le preoccupazioni della dichiarazione dei parametri nel workflow (che decisamente appartiene lì) rispetto alla fornitura dei valori predefiniti, che sono più a loro agio in un file di configurazione.
Facciamolo in due step.
1.1.1. Crea un blocco params nel file di configurazione¶
Fai le seguenti modifiche al codice nel file nextflow.config:
Nota che non abbiamo semplicemente copiato il blocco params dal workflow al file di configurazione.
Per il parametro batch che aveva già un valore predefinito dichiarato, la sintassi è un po' diversa.
Nel file del workflow, quella è una dichiarazione tipizzata.
Nella configurazione, quelle sono assegnazioni di valori.
Tecnicamente, questo è sufficiente per sovrascrivere i valori predefiniti ancora specificati nel file del workflow.
Potresti modificare il valore predefinito per batch ed eseguire il workflow per verificare che il valore impostato nel file di configurazione sovrascrive quello impostato nel file del workflow.
Ma nello spirito di spostare la configurazione completamente al file di configurazione, rimuoviamo quel valore predefinito dal file del workflow completamente.
1.1.2. Rimuovi il valore predefinito per batch nel file del workflow¶
Fai la seguente modifica al codice nel file del workflow 3-main.nf:
Ora il file del workflow stesso non imposta alcun valore predefinito per questi parametri.
1.1.3. Esegui la pipeline¶
Testiamo che funzioni correttamente senza specificare alcun parametro nella riga di comando.
Output del comando
Questo produce ancora lo stesso output di prima.
L'output finale dell'arte ASCII è nella directory results/3-main/, sotto il nome cowpy-COLLECTED-batch-output.txt, come prima.
Contenuto del file
_________
/ HOLà \
| HELLO |
\ BONJOUR /
---------
\ ,+*^^*+___+++_
\ ,*^^^^ )
\ _+* ^**+_
\ +^ _ _++*+_+++_, )
_+^^*+_ ( ,+*^ ^ \+_ )
{ ) ( ,( ,_+--+--, ^) ^\
{ (\@) } f ,( ,+-^ __*_*_ ^^\_ ^\ )
{:;-/ (_+*-+^^^^^+*+*<_ _++_)_ ) ) /
( / ( ( ,___ ^*+_+* ) < < \
U _/ ) *--< ) ^\-----++__) ) ) )
( ) _(^)^^)) ) )\^^^^^))^*+/ / /
( / (_))_^)) ) ) ))^^^^^))^^^)__/ +^^
( ,/ (^))^)) ) ) ))^^^^^^^))^^) _)
*+__+* (_))^) ) ) ))^^^^^^))^^^^^)____*^
\ \_)^)_)) ))^^^^^^^^^^))^^^^)
(_ ^\__^^^^^^^^^^^^))^^^^^^^)
^\___ ^\__^^^^^^))^^^^^^^^)\\
^^^^^\uuu/^^\uuu/^^^^\^\^\^\^\^\^\^\
___) >____) >___ ^\_\_\_\_\_\_\)
^^^//\\_^^//\\_^ ^(\_\_\_\)
^^^ ^^ ^^^ ^
Funzionalmente, questo spostamento non ha cambiato nulla, ma concettualmente è un po' più pulito avere i valori predefiniti impostati nel file di configurazione.
1.2. Usa un file di configurazione specifico per l'esecuzione¶
Scenario
Vuoi sperimentare con diverse impostazioni senza modificare il tuo file di configurazione principale.
Puoi farlo creando un nuovo file nextflow.config in una sottodirectory che userai come directory di lavoro per i tuoi esperimenti.
1.2.1. Crea la directory di lavoro con una configurazione vuota¶
Iniziamo creando una nuova directory e spostandoci al suo interno:
Poi, crea un file di configurazione vuoto in quella directory:
Questo produce un file vuoto.
1.2.2. Imposta la configurazione sperimentale¶
Ora apri il nuovo file e aggiungi i parametri che vuoi personalizzare:
| tux-run/nextflow.config | |
|---|---|
Nota che il percorso del file di input deve riflettere la struttura delle directory.
1.2.3. Esegui la pipeline¶
Ora possiamo eseguire la nostra pipeline dall'interno della nostra nuova directory di lavoro. Assicurati di adattare il percorso di conseguenza!
Output del comando
Questo creerà un nuovo set di directory sotto tux-run/ incluse tux-run/work/ e tux-run/results/.
In questa esecuzione, Nextflow combina il nextflow.config nella nostra directory corrente con il nextflow.config nella directory root della pipeline, e quindi sovrascrive il personaggio predefinito (turkey) con il personaggio tux.
Il file di output finale dovrebbe contenere il personaggio tux che dice i saluti.
Contenuto del file
Ecco fatto; ora hai uno spazio per sperimentare senza modificare la tua configurazione 'normale'.
Avviso
Assicurati di tornare alla directory precedente prima di passare alla prossima sezione!
Ora guardiamo un altro modo utile per impostare i valori dei parametri.
1.3. Usa un file di parametri¶
Scenario
Devi condividere i parametri esatti dell'esecuzione con un collaboratore, o registrarli per una pubblicazione.
L'approccio con la sottodirectory funziona benissimo per sperimentare, ma comporta un po' di setup e richiede che tu adatti i percorsi di conseguenza. C'è un approccio più semplice per quando vuoi eseguire la tua pipeline con un set specifico di valori, o permettere a qualcun altro di farlo con il minimo sforzo.
Nextflow ci permette di specificare parametri tramite un file di parametri in formato YAML o JSON, il che lo rende molto conveniente per gestire e distribuire set alternativi di valori predefiniti, per esempio, così come valori di parametri specifici per l'esecuzione.
1.3.1. Esamina il file di parametri di esempio¶
Per dimostrare questo, forniamo un file di parametri di esempio nella directory corrente, chiamato test-params.yaml:
Questo file di parametri contiene una coppia chiave-valore per ciascuno degli input che vogliamo specificare.
Nota l'uso dei due punti (:) invece dei segni di uguale (=) se confronti la sintassi con il file di configurazione.
Il file config è scritto in Groovy, mentre il file di parametri è scritto in YAML.
Informazione
Forniamo anche una versione JSON del file di parametri come esempio ma non lo eseguiremo qui. Sentiti libero di provare quello da solo.
1.3.2. Esegui la pipeline¶
Per eseguire il workflow con questo file di parametri, aggiungi semplicemente -params-file <nomefile> al comando base.
Output del comando
Il file di output finale dovrebbe contenere il personaggio stegosaurus che dice i saluti.
Contenuto del file
_________
/ HELLO \
| HOLà |
\ BONJOUR /
---------
\ . .
\ / `. .' "
\ .---. < > < > .---.
\ | \ \ - ~ ~ - / / |
_____ ..-~ ~-..-~
| | \~~~\.' `./~~~/
--------- \__/ \__/
.' O \ / / \ "
(_____, `._.' | } \/~~~/
`----. / } | / \__/
`-. | / | / `. ,~~|
~-.__| /_ - ~ ^| /- _ `..-'
| / | / ~-. `-. _ _ _
|_____| |_____| ~ - . _ _ _ _ _>
Usare un file di parametri potrebbe sembrare eccessivo quando hai solo pochi parametri da specificare, ma alcune pipeline si aspettano dozzine di parametri. In quei casi, usare un file di parametri ci permetterà di fornire valori di parametri a runtime senza dover digitare linee di comando massive e senza modificare lo script del workflow.
Rende anche più facile distribuire set di parametri ai collaboratori, o come informazione di supporto per una pubblicazione, per esempio. Questo rende il tuo lavoro più riproducibile da altri.
Riepilogo¶
Sai come sfruttare le opzioni di configurazione chiave per gestire gli input del workflow.
Cosa c'è dopo?¶
Impara come gestire dove e come vengono pubblicati gli output del tuo workflow.
2. Gestire gli output del workflow¶
Scenario
La tua pipeline pubblica gli output in una directory hardcoded, ma vuoi organizzare i risultati per progetto o nome dell'esperimento senza modificare il codice del workflow ogni volta.
Il workflow che abbiamo ereditato usa percorsi per le dichiarazioni di output a livello di workflow, il che non è terribilmente flessibile e comporta molta ripetizione.
Guardiamo alcuni modi comuni in cui potresti configurare questo per essere più flessibile.
2.1. Personalizza il nome della directory outputDir¶
Ogni versione del workflow che abbiamo eseguito finora ha pubblicato i suoi output in una sottodirectory diversa hardcoded nelle definizioni di output.
Cambiamo questo per usare un parametro configurabile dall'utente.
Potremmo creare un parametro completamente nuovo per questo, ma usiamo il parametro batch dato che è già lì.
2.1.1. Imposta un valore per outputDir nel file di configurazione¶
Il percorso che Nextflow usa per pubblicare gli output è controllato dall'opzione outputDir.
Per cambiare il percorso per tutti gli output, puoi impostare un valore per questa opzione nel file di configurazione nextflow.config.
Aggiungi il seguente codice al file nextflow.config:
Questo sostituirà il percorso predefinito integrato, results/, con results/ più il valore del parametro batch come sottodirectory.
Potresti anche cambiare la parte results se volessi.
Per una modifica temporanea, potresti impostare questa opzione dalla riga di comando usando il parametro -output-dir nel tuo comando (ma allora non potresti usare il valore del parametro batch).
2.1.2. Rimuovi la parte ripetuta del percorso hardcoded¶
Abbiamo ancora una sottodirectory hardcoded nelle opzioni di output, quindi togliamola ora.
Fai le seguenti modifiche al codice nel file del workflow:
| 3-main.nf | |
|---|---|
| 3-main.nf | |
|---|---|
Avremmo anche potuto semplicemente aggiungere ${params.batch} a ogni percorso invece di modificare il predefinito di outputDir, ma questo è più conciso.
2.1.3. Esegui la pipeline¶
Testiamo che funzioni correttamente, impostando il nome del batch a outdir dalla riga di comando.
Output del comando
Questo produce ancora lo stesso output di prima, tranne che questa volta troviamo i nostri output sotto results/outdir/.
Contenuti della directory
Puoi combinare questo approccio con definizioni di percorsi personalizzate per costruire qualsiasi gerarchia di directory ti piaccia.
2.2. Organizza gli output per process¶
Un modo popolare per organizzare ulteriormente gli output è farlo per process, cioè creare sottodirectory per ogni process eseguito nella pipeline.
2.2.1. Sostituisci i percorsi di output con un riferimento ai nomi dei process¶
Tutto ciò che devi fare è fare riferimento al nome del process come <task>.name nella dichiarazione del percorso di output.
Fai le seguenti modifiche nel file del workflow:
| 3-main.nf | |
|---|---|
| 3-main.nf | |
|---|---|
Questo rimuove gli elementi hardcoded rimanenti dalla configurazione del percorso di output.
2.2.2. Esegui la pipeline¶
Testiamo che funzioni correttamente, impostando il nome del batch a pnames dalla riga di comando.
Output del comando
Questo produce ancora lo stesso output di prima, tranne che questa volta troviamo i nostri output sotto results/pnames/, e sono raggruppati per process.
Contenuti della directory
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
Nota che qui abbiamo eliminato la distinzione tra intermediates rispetto agli output finali al livello superiore.
Potresti ovviamente mescolare e abbinare questi approcci, per esempio impostando il percorso del primo output come intermediates/${sayHello.name}
2.3. Imposta la modalità di pubblicazione a livello di workflow¶
Infine, nello spirito di ridurre la quantità di codice ripetitivo, possiamo sostituire le dichiarazioni mode per-output con una singola riga nella configurazione.
2.3.1. Aggiungi workflow.output.mode al file di configurazione¶
Aggiungi il seguente codice al file nextflow.config:
Proprio come l'opzione outputDir, dare a workflow.output.mode un valore nel file di configurazione sarebbe sufficiente per sovrascrivere ciò che è impostato nel file del workflow, ma rimuoviamo comunque il codice non necessario.
2.3.2. Rimuovi la modalità di output dal file del workflow¶
Fai le seguenti modifiche nel file del workflow:
| 3-main.nf | |
|---|---|
È più conciso, vero?
2.3.3. Esegui la pipeline¶
Testiamo che funzioni correttamente, impostando il nome del batch a outmode dalla riga di comando.
Output del comando
Questo produce ancora lo stesso output di prima, tranne che questa volta troviamo i nostri output sotto results/outmode/.
Sono ancora tutte copie vere, non symlink.
Contenuti della directory
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
Il motivo principale per cui potresti ancora voler usare il modo per-output di impostare la modalità è se vuoi mescolare e abbinare all'interno dello stesso workflow, cioè avere alcuni output copiati e alcuni linkati simbolicamente.
Ci sono molte altre opzioni che puoi personalizzare in questo modo, ma speriamo che questo ti dia un'idea della gamma di opzioni e di come utilizzarle efficacemente per adattarle alle tue preferenze.
Riepilogo¶
Sai come controllare la denominazione e la struttura delle directory dove vengono pubblicati i tuoi output, così come la modalità di pubblicazione dell'output del workflow.
Cosa c'è dopo?¶
Impara come adattare la configurazione del tuo workflow al tuo ambiente di calcolo, partendo dalla tecnologia di pacchettizzazione software.
3. Seleziona una tecnologia di pacchettizzazione software¶
Finora abbiamo guardato elementi di configurazione che controllano come gli input entrano e dove gli output escono. Ora è il momento di concentrarsi più specificamente sull'adattare la configurazione del tuo workflow al tuo ambiente di calcolo.
Il primo passo su quel percorso è specificare da dove verranno i pacchetti software che verranno eseguiti in ogni step. Sono già installati nell'ambiente di calcolo locale? Dobbiamo recuperare immagini ed eseguirle tramite un sistema container? O dobbiamo recuperare pacchetti Conda e costruire un ambiente Conda locale?
Nella prima parte di questo corso di formazione (Parti 1-4) abbiamo semplicemente usato software installato localmente nel nostro workflow.
Poi nella Parte 5, abbiamo introdotto i container Docker e il file nextflow.config, che abbiamo usato per abilitare l'uso dei container Docker.
Ora vediamo come possiamo configurare un'opzione alternativa di pacchettizzazione software tramite il file nextflow.config.
3.1. Disabilita Docker e abilita Conda nel file di config¶
Scenario
Stai spostando la tua pipeline su un cluster HPC dove Docker non è permesso per motivi di sicurezza. Il cluster supporta Singularity e Conda, quindi devi cambiare la tua configurazione di conseguenza.
Nextflow supporta molteplici tecnologie container incluso Singularity (che è più ampiamente usato su HPC), così come gestori di pacchetti software come Conda.
Possiamo cambiare il nostro file di configurazione per usare Conda invece di Docker.
Per farlo, cambiamo il valore di docker.enabled a false, e aggiungiamo una direttiva che abilita l'uso di Conda:
Questo permetterà a Nextflow di creare e utilizzare ambienti Conda per i process che hanno pacchetti Conda specificati.
Il che significa che ora dobbiamo aggiungerne uno al nostro process cowpy!
3.2. Specifica un pacchetto Conda nella definizione del process¶
Abbiamo già recuperato l'URI per un pacchetto Conda contenente lo strumento cowpy: conda-forge::cowpy==1.1.5
Ora aggiungiamo l'URI alla definizione del process cowpy usando la direttiva conda:
Per essere chiari, non stiamo sostituendo la direttiva docker, stiamo aggiungendo un'opzione alternativa.
Suggerimento
Ci sono alcuni modi diversi per ottenere l'URI per un dato pacchetto conda. Raccomandiamo di usare la query di ricerca di Seqera Containers, che ti darà un URI che puoi copiare e incollare, anche se non stai pianificando di creare un container da esso.
3.3. Esegui il workflow per verificare che possa usare Conda¶
Proviamolo.
Output del comando
Questo dovrebbe funzionare senza problemi e produrre gli stessi output di prima sotto results/conda.
Dietro le quinte, Nextflow ha recuperato i pacchetti Conda e creato l'ambiente, che normalmente richiede un po' di lavoro; quindi è bello che non dobbiamo fare niente di tutto ciò noi stessi!
Informazione
Questo viene eseguito velocemente perché il pacchetto cowpy è abbastanza piccolo, ma se stai lavorando con pacchetti grandi, potrebbe richiedere un po' più di tempo del solito la prima volta, e potresti vedere l'output della console rimanere 'bloccato' per un minuto circa prima di completarsi.
Questo è normale ed è dovuto al lavoro extra che Nextflow fa la prima volta che usi un nuovo pacchetto.
Dal nostro punto di vista, sembra che funzioni esattamente come l'esecuzione con Docker, anche se nel backend la meccanica è un po' diversa.
Questo significa che siamo pronti per eseguire con ambienti Conda se necessario.
Mescolare e abbinare Docker e Conda
Dato che queste direttive sono assegnate per process, è possibile 'mescolare e abbinare', cioè configurare alcuni dei process nel tuo workflow per essere eseguiti con Docker e altri con Conda, per esempio, se l'infrastruttura di calcolo che stai usando supporta entrambi. In quel caso, abiliteresti sia Docker che Conda nel tuo file di configurazione. Se entrambi sono disponibili per un dato process, Nextflow darà priorità ai container.
E come notato prima, Nextflow supporta molteplici altre tecnologie di pacchettizzazione software e container, quindi non sei limitato a solo quelle due.
Riepilogo¶
Sai come configurare quale pacchetto software ogni process dovrebbe usare, e come passare da una tecnologia all'altra.
Cosa c'è dopo?¶
Impara come cambiare la piattaforma di esecuzione usata da Nextflow per fare effettivamente il lavoro.
4. Seleziona una piattaforma di esecuzione¶
Scenario
Hai sviluppato e testato la tua pipeline sul tuo laptop, ma ora devi eseguirla su migliaia di campioni. La tua istituzione ha un cluster HPC con uno scheduler Slurm che vorresti usare invece.
Finora, abbiamo eseguito la nostra pipeline con l'executor locale. Questo esegue ogni attività sulla macchina su cui Nextflow è in esecuzione. Quando Nextflow inizia, guarda le CPU e la memoria disponibili. Se le risorse delle attività pronte per l'esecuzione superano le risorse disponibili, Nextflow tratterrà le ultime attività dall'esecuzione fino a quando una o più delle attività precedenti sono terminate, liberando le risorse necessarie.
L'executor locale è conveniente ed efficiente, ma è limitato a quella singola macchina. Per carichi di lavoro molto grandi, potresti scoprire che la tua macchina locale è un collo di bottiglia, o perché hai una singola attività che richiede più risorse di quelle disponibili, o perché hai così tante attività che aspettare che una singola macchina le esegua richiederebbe troppo tempo.
Nextflow supporta molti backend di esecuzione diversi, inclusi scheduler HPC (Slurm, LSF, SGE, PBS, Moab, OAR, Bridge, HTCondor e altri) così come backend di esecuzione cloud come (AWS Batch, Google Cloud Batch, Azure Batch, Kubernetes e altri).
4.1. Puntare a un backend diverso¶
La scelta dell'executor è impostata da una direttiva del process chiamata executor.
Per impostazione predefinita è impostata su local, quindi la seguente configurazione è implicita:
Per impostare l'executor per puntare a un backend diverso, specificheresti semplicemente l'executor che vuoi usando una sintassi simile a quella descritta sopra per le allocazioni di risorse (vedi documentazione per tutte le opzioni).
Avviso
Non possiamo effettivamente testare questo nell'ambiente di formazione perché non è configurato per connettersi a un HPC.
4.2. Gestire la sintassi specifica del backend per i parametri di esecuzione¶
La maggior parte delle piattaforme di calcolo ad alte prestazioni permettono (e a volte richiedono) di specificare certi parametri come richieste e limitazioni di allocazione delle risorse (per es. numero di CPU e memoria) e nome della coda di job da usare.
Sfortunatamente, ciascuno di questi sistemi usa tecnologie, sintassi e configurazioni diverse per definire come un job dovrebbe essere definito e sottomesso allo scheduler rilevante.
Esempi
Per esempio, lo stesso job che richiede 8 CPU e 4GB di RAM per essere eseguito sulla coda "my-science-work" deve essere espresso in modi diversi a seconda del 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
Fortunatamente, Nextflow semplifica tutto questo.
Fornisce una sintassi standardizzata in modo che tu possa specificare le proprietà rilevanti come cpus, memory e queue (vedi documentazione per altre proprietà) solo una volta.
Poi, a runtime, Nextflow userà quelle impostazioni per generare gli script specifici del backend appropriati basati sull'impostazione dell'executor.
Copriremo quella sintassi standardizzata nella prossima sezione.
Riepilogo¶
Ora sai come cambiare l'executor per usare diversi tipi di infrastruttura di calcolo.
Cosa c'è dopo?¶
Impara come valutare ed esprimere allocazioni e limitazioni delle risorse in Nextflow.
5. Controlla le allocazioni delle risorse di calcolo¶
Scenario
La tua pipeline continua a fallire sul cluster perché le attività vengono terminate per aver superato i limiti di memoria. O forse ti vengono addebitate risorse che non stai usando e vuoi ottimizzare i costi.
La maggior parte delle piattaforme di calcolo ad alte prestazioni permettono (e a volte richiedono) di specificare certi parametri di allocazione delle risorse come il numero di CPU e la memoria.
Per impostazione predefinita, Nextflow userà una singola CPU e 2GB di memoria per ogni process.
Le corrispondenti direttive del process sono chiamate cpus e memory, quindi la seguente configurazione è implicita:
Puoi modificare questi valori, sia per tutti i process che per process specifici nominati, usando direttive di process aggiuntive nel tuo file di configurazione. Nextflow le tradurrà nelle istruzioni appropriate per l'executor scelto.
Ma come sai quali valori usare?
5.1. Esegui il workflow per generare un report di utilizzo delle risorse¶
Scenario
Non sai quanta memoria o CPU i tuoi process hanno bisogno e vuoi evitare di sprecare risorse o avere job terminati.
Se non sai in anticipo quanta CPU e memoria i tuoi process probabilmente avranno bisogno, puoi fare del profiling delle risorse, il che significa eseguire il workflow con alcune allocazioni predefinite, registrare quanto ogni process ha usato, e da lì, stimare come regolare le allocazioni base.
Convenientemente, Nextflow include strumenti integrati per fare questo, e genererà felicemente un report per te su richiesta.
Per farlo, aggiungi -with-report <nomefile>.html alla tua riga di comando.
Il report è un file html, che puoi scaricare e aprire nel tuo browser. Puoi anche fare clic destro su di esso nell'esploratore file a sinistra e cliccare su Show preview per visualizzarlo nell'ambiente di formazione.
Prenditi qualche minuto per guardare il report e vedere se riesci a identificare alcune opportunità per regolare le risorse. Assicurati di cliccare sulle schede che mostrano i risultati di utilizzo come percentuale di ciò che è stato allocato. C'è della documentazione che descrive tutte le funzionalità disponibili.
5.2. Imposta le allocazioni delle risorse per tutti i process¶
Il profiling mostra che i process nel nostro workflow di formazione sono molto leggeri, quindi riduciamo l'allocazione di memoria predefinita a 1GB per process.
Aggiungi quanto segue al tuo file nextflow.config, prima della sezione dei parametri della pipeline:
Questo aiuterà a ridurre la quantità di calcolo che consumiamo.
5.3. Imposta le allocazioni delle risorse per un process specifico¶
Allo stesso tempo, faremo finta che il process cowpy richieda più risorse degli altri, solo per poter dimostrare come regolare le allocazioni per un process individuale.
Con questa configurazione, tutti i process richiederanno 1GB di memoria e una singola CPU (il predefinito implicito), tranne il process cowpy, che richiederà 2GB e 2 CPU.
Informazione
Se hai una macchina con poche CPU e allochi un numero elevato per process, potresti vedere chiamate ai process mettersi in coda l'una dietro l'altra. Questo perché Nextflow assicura che non richiediamo più CPU di quelle disponibili.
5.4. Esegui il workflow con la configurazione aggiornata¶
Proviamolo, fornendo un nome file diverso per il report di profiling così possiamo confrontare le prestazioni prima e dopo i cambiamenti di configurazione.
Probabilmente non noterai alcuna differenza reale dato che questo è un carico di lavoro così piccolo, ma questo è l'approccio che useresti per analizzare le prestazioni e i requisiti di risorse di un workflow del mondo reale.
È molto utile quando i tuoi process hanno requisiti di risorse diversi. Ti permette di dimensionare correttamente le allocazioni delle risorse che imposti per ogni process basandoti su dati reali, non su supposizioni.
Suggerimento
Questo è solo un piccolo assaggio di ciò che puoi fare per ottimizzare il tuo uso delle risorse. Nextflow stesso ha una logica di retry dinamico davvero interessante integrata per ritentare i job che falliscono a causa di limitazioni delle risorse. Inoltre, Seqera Platform offre anche strumenti basati sull'IA per ottimizzare automaticamente le tue allocazioni delle risorse.
5.5. Aggiungi limiti alle risorse¶
A seconda di quale executor di calcolo e infrastruttura di calcolo stai usando, potrebbero esserci alcuni vincoli su ciò che puoi (o devi) allocare. Per esempio, il tuo cluster potrebbe richiedere di rimanere entro certi limiti.
Puoi usare la direttiva resourceLimits per impostare le limitazioni rilevanti. La sintassi appare così quando è da sola in un blocco process:
Nextflow tradurrà questi valori nelle istruzioni appropriate a seconda dell'executor che hai specificato.
Non eseguiremo questo, dato che non abbiamo accesso a un'infrastruttura rilevante nell'ambiente di formazione.
Tuttavia, se provassi a eseguire il workflow con allocazioni di risorse che superano questi limiti, poi cercassi il comando sbatch nel file di script .command.run, vedresti che le richieste che vengono effettivamente inviate all'executor sono limitate ai valori specificati da resourceLimits.
Configurazioni di riferimento istituzionali
Il progetto nf-core ha compilato una collezione di file di configurazione condivisi da varie istituzioni in tutto il mondo, coprendo una vasta gamma di executor HPC e cloud.
Quei config condivisi sono preziosi sia per le persone che lavorano lì e possono quindi semplicemente utilizzare la configurazione della loro istituzione out of the box, sia come modello per le persone che cercano di sviluppare una configurazione per la propria infrastruttura.
Riepilogo¶
Sai come generare un report di profiling per valutare l'utilizzo delle risorse e come modificare le allocazioni delle risorse per tutti i process e/o per process individuali, oltre a impostare limitazioni delle risorse per l'esecuzione su HPC.
Cosa c'è dopo?¶
Impara come impostare profili di configurazione preimpostati e passare da uno all'altro a runtime.
6. Usa i profili per passare da una configurazione preimpostata all'altra¶
Scenario
Passi regolarmente dall'esecuzione di pipeline sul tuo laptop per lo sviluppo all'HPC della tua istituzione per le esecuzioni in produzione. Sei stanco di cambiare manualmente le impostazioni di configurazione ogni volta che cambi ambiente.
Ti abbiamo mostrato diversi modi in cui puoi personalizzare la configurazione della tua pipeline a seconda del progetto su cui stai lavorando o dell'ambiente di calcolo che stai usando.
Potresti voler passare da un'impostazione alternativa all'altra a seconda di quale infrastruttura di calcolo stai usando. Per esempio, potresti voler sviluppare e eseguire test su piccola scala localmente sul tuo laptop, poi eseguire carichi di lavoro su scala completa su HPC o cloud.
Nextflow ti permette di impostare un numero qualsiasi di profili che descrivono diverse configurazioni, che puoi poi selezionare a runtime usando un argomento da riga di comando, piuttosto che dover modificare il file di configurazione stesso.
6.1. Crea profili per passare dallo sviluppo locale all'esecuzione su HPC¶
Impostiamo due profili alternativi; uno per eseguire carichi su piccola scala su un computer normale, dove useremo container Docker, e uno per l'esecuzione su un HPC universitario con uno scheduler Slurm, dove useremo pacchetti Conda.
6.1.1. Imposta i profili¶
Aggiungi quanto segue al tuo file nextflow.config, dopo la sezione dei parametri della pipeline ma prima delle impostazioni di output:
| nextflow.config | |
|---|---|
Vedi che per l'HPC universitario, stiamo anche specificando limitazioni delle risorse.
6.1.2. Esegui il workflow con un profilo¶
Per specificare un profilo nella nostra riga di comando di Nextflow, usiamo l'argomento -profile.
Proviamo a eseguire il workflow con la configurazione my_laptop.
Output del comando
Come puoi vedere, questo ci permette di alternare tra configurazioni molto comodamente a runtime.
Avviso
Il profilo univ_hpc non funzionerà correttamente nell'ambiente di formazione dato che non abbiamo accesso a uno scheduler Slurm.
Se in futuro troviamo altri elementi di configurazione che co-occorrono sempre con questi, possiamo semplicemente aggiungerli al/i profilo/i corrispondente/i. Possiamo anche creare profili aggiuntivi se ci sono altri elementi di configurazione che vogliamo raggruppare insieme.
6.2. Crea un profilo di parametri di test¶
Scenario
Vuoi che altri possano provare rapidamente la tua pipeline senza dover raccogliere i propri dati di input.
I profili non sono solo per la configurazione dell'infrastruttura. Possiamo anche usarli per impostare valori predefiniti per i parametri del workflow, per rendere più facile per gli altri provare il workflow senza dover raccogliere valori di input appropriati loro stessi. Puoi considerare questo un'alternativa all'uso di un file di parametri.
6.2.1. Imposta il profilo¶
La sintassi per esprimere valori predefiniti in questo contesto appare così, per un profilo che chiamiamo test:
Se aggiungiamo un profilo test per il nostro workflow, il blocco profiles diventa:
Proprio come per i profili di configurazione tecnica, puoi impostare molteplici profili diversi che specificano parametri sotto qualsiasi nome arbitrario tu voglia.
6.2.2. Esegui il workflow localmente con il profilo test¶
Convenientemente, i profili non sono mutuamente esclusivi, quindi possiamo specificare profili multipli nella nostra riga di comando usando la seguente sintassi -profile <profilo1>,<profilo2> (per qualsiasi numero di profili).
Se combini profili che impostano valori per gli stessi elementi di configurazione e sono descritti nello stesso file di configurazione, Nextflow risolverà il conflitto usando qualunque valore abbia letto per ultimo (cioè qualunque cosa venga dopo nel file). Se le impostazioni in conflitto sono impostate in diverse fonti di configurazione, si applica l'ordine di precedenza predefinito.
Proviamo ad aggiungere il profilo test al nostro comando precedente:
Output del comando
Questo userà Docker dove possibile e produrrà output sotto results/test, e questa volta il personaggio è il duo comico dragonandcow.
Contenuto del file
_________
/ HOLà \
| HELLO |
\ BONJOUR /
---------
\ ^ /^
\ / \ // \
\ |\___/| / \// .\
\ /O O \__ / // | \ \ *----*
/ / \/_/ // | \ \ \ |
\@___\@` \/_ // | \ \ \/\ \
0/0/| \/_ // | \ \ \ \
0/0/0/0/| \/// | \ \ | |
0/0/0/0/0/_|_ / ( // | \ _\ | /
0/0/0/0/0/0/`/,_ _ _/ ) ; -. | _ _\.-~ / /
,-} _ *-.|.-~-. .~ ~
\ \__/ `/\ / ~-. _ .-~ /
\____(oo) *. } { /
( (--) .----~-.\ \-` .~
//__\\ \__ Ack! ///.----..< \ _ -~
// \\ ///-._ _ _ _ _ _ _{^ - - - - ~
Questo significa che finché distribuiamo tutti i file di dati di test con il codice del workflow, chiunque può provare rapidamente il workflow senza dover fornire i propri input tramite la riga di comando o un file di parametri.
Suggerimento
Possiamo puntare a URL per file più grandi che sono memorizzati esternamente. Nextflow li scaricherà automaticamente finché c'è una connessione aperta.
Per maggiori dettagli, vedi la Side Quest Working with Files
6.3. Usa nextflow config per vedere la configurazione risolta¶
Come notato sopra, a volte lo stesso parametro può essere impostato a valori diversi in profili che vuoi combinare. E più in generale, ci sono numerosi posti dove gli elementi di configurazione possono essere memorizzati, e a volte le stesse proprietà possono essere impostate a valori diversi in posti diversi.
Nextflow applica un ordine di precedenza stabilito per risolvere qualsiasi conflitto, ma può essere difficile determinarlo da solo. E anche se nulla è in conflitto, può essere noioso cercare tutti i possibili posti dove le cose potrebbero essere configurate.
Fortunatamente, Nextflow include un conveniente strumento utility chiamato config che può automatizzare tutto quel processo per te.
Lo strumento config esplorerà tutti i contenuti nella tua directory di lavoro corrente, raccoglierà tutti i file di configurazione, e produrrà la configurazione completamente risolta che Nextflow userebbe per eseguire il workflow.
Questo ti permette di scoprire quali impostazioni verranno usate senza dover lanciare nulla.
6.3.1. Risolvi la configurazione predefinita¶
Esegui questo comando per risolvere la configurazione che verrebbe applicata per impostazione predefinita.
Output del comando
Questo ti mostra la configurazione base che ottieni se non specifichi nulla di extra nella riga di comando.
6.3.2. Risolvi la configurazione con impostazioni specifiche attivate¶
Se fornisci parametri da riga di comando, es. abilitando uno o più profili o caricando un file di parametri, il comando terrà conto anche di quelli.
Output del comando
Questo diventa particolarmente utile per progetti complessi che coinvolgono molteplici livelli di configurazione.
Riepilogo¶
Sai come usare i profili per selezionare una configurazione preimpostata a runtime con il minimo fastidio. Più in generale, sai come configurare le esecuzioni del tuo workflow per adattarle a diverse piattaforme di calcolo e migliorare la riproducibilità delle tue analisi.
Cosa c'è dopo?¶
Impara come eseguire pipeline direttamente da repository remoti come GitHub.
7. Esegui pipeline da repository remoti¶
Scenario
Vuoi eseguire una pipeline ben consolidata come quelle di nf-core senza dover scaricare e gestire il codice tu stesso.
Finora abbiamo eseguito script di workflow situati nella directory corrente. In pratica, vorrai spesso eseguire pipeline memorizzate in repository remoti, come GitHub.
Nextflow rende questo semplice: puoi eseguire qualsiasi pipeline direttamente da un URL di un repository Git senza scaricarlo manualmente prima.
7.1. Esegui una pipeline da GitHub¶
La sintassi base per eseguire una pipeline remota è nextflow run <repository>, dove <repository> può essere un percorso di repository GitHub come nextflow-io/hello, un URL completo, o un percorso a GitLab, Bitbucket, o altri servizi di hosting Git.
Prova a eseguire la pipeline demo ufficiale di Nextflow "hello":
La prima volta che esegui una pipeline remota, Nextflow la scarica e la mette in cache localmente. Le esecuzioni successive usano la versione in cache a meno che tu non richieda esplicitamente un aggiornamento.
7.2. Specifica una versione per la riproducibilità¶
Per impostazione predefinita, Nextflow esegue l'ultima versione dal branch predefinito.
Puoi specificare una particolare versione, branch, o commit usando il flag -r:
Specificare versioni esatte è essenziale per la riproducibilità.
Riepilogo¶
Sai come eseguire pipeline direttamente da GitHub e altri repository remoti, e come specificare versioni per la riproducibilità.
Cosa c'è dopo?¶
Datti una bella pacca sulla spalla! Sai tutto ciò che devi sapere per iniziare a eseguire e gestire pipeline Nextflow.
Questo conclude questo corso, ma se sei desideroso di continuare a imparare, abbiamo due raccomandazioni principali:
- Se vuoi approfondire lo sviluppo delle tue pipeline, dai un'occhiata a Hello Nextflow, un corso per principianti che copre la stessa progressione generale di questo ma va molto più in dettaglio su channel e operatori.
- Se vorresti continuare a imparare come eseguire pipeline Nextflow senza andare più in profondità nel codice, dai un'occhiata alla prima parte di Hello nf-core, che introduce gli strumenti per trovare e eseguire pipeline dall'estremamente popolare progetto nf-core.
Buon divertimento!
Quiz¶
Quando i valori dei parametri sono impostati sia nel file del workflow che in nextflow.config, quale ha la precedenza?
Qual è la differenza di sintassi tra l'impostazione di un valore predefinito di un parametro in un file workflow vs. un file config?
Come specifichi un file di parametri quando esegui un workflow?
Cosa controlla l'opzione di configurazione outputDir?
Come si fa riferimento dinamicamente al nome di un process nella configurazione del percorso di output?
Se sia Docker che Conda sono abilitati e un process ha entrambe le direttive, quale ha la priorità?
Qual è l'executor predefinito in Nextflow?
Quale comando genera un report di utilizzo delle risorse?
Come si impostano i requisiti di risorse per un process specifico chiamato cowpy nel file config?
Cosa fa la direttiva resourceLimits?
Come si specificano profili multipli in un singolo comando?
Quale comando mostra la configurazione completamente risolta che Nextflow userebbe?
Per cosa possono essere usati i profili? (Seleziona tutte le risposte corrette)