Snakemake-työvuon ajaminen Puhdissa

Snakemake-työvuo on yksi bioinformatiikan yhteisön suosituista tieteellisistä työnkuluista, vaikka itse työnkulunhallintatyökalua voidaan käyttää myös muilla tieteenaloilla. Snakemake mahdollistaa skaalautuvat ja toistettavat tieteelliset putket ketjuttamalla joukon sääntöjä täysin määritellyssä ohjelmistoympäristössä.

Jos pohdit vielä työnkulkuja yleisemmällä tasolla tai sitä, mitä työnkulkuvälinettä kannattaa käyttää, katso myös Suurteholaskenta ja työnkulut -sivu.

Asennus

Snakemake on saatavilla moduulina Puhti-supertietokoneessa. Tämä vaihtoehto sopii hyvin, jos työnkulku sisältää komentorivityökaluja muista moduuleista tai Apptainer-säiliöitä. Jos työnkulku sisältää Python-skriptejä, jotka vaativat omia Python-paketteja, tee oma Snakemake-asennus Tykyllä.

Snakemake-moduuli

Snakemake-moduuli on helpoin vaihtoehto. Saatavilla olevat versiot on listattu Snakemake-sovellussivulla.

module load snakemake
snakemake --help   #  saadaksesi tietoa useammista vaihtoehdoista.

Huom

Kiinnitä huomiota käyttämääsi Snakemake-versioon. Jos käytät Snakemaken vanhempia versioita (esim. v7.xx.x), syntaksi voi olla erilainen.

Työvuossa käytettävien työkalujen asennus

Työvuossa käytettävät työkalut voidaan asentaa seuraavilla tavoilla:

Työkalut, jotka ovat saatavilla muissa Puhdin moduuleissa tai omassa mukautetussa moduulissa.
- Jos kaikki Snakemake-säännöt käyttävät samoja moduuleja, lataa ne ennen snakemake-komentojen ajamista.
- Jos eri Snakemake-säännöt käyttävät eri moduuleja, sisällytä moduulitiedot Snakefile-tiedostoon.
Omat mukautetut asennukset Apptainer-säiliöinä:
- Apptainer-säiliö voidaan ladata jostakin repositoriosta tai rakentaa paikallisesti. Mukautettujen Apptainer-säiliöiden rakentamisesta kerrotaan Säiliöiden luominen -sivulla.
- Katso Snakemaken ohje Ajetaan töitä säiliöissä, jossa kuvataan Snakemake-tiedostoon ja komentoon tarvittavat muutokset.
- Kansioiden bindaukseen tai muiden Apptainer-lippujen käyttöön käytä snakemake-komennon --apptainer-args-valitsinta.
- Joskus voi olla tarpeen määritellä säiliön sisällä käytettävä shell.

# Jos Apptainer image tutorial.sif on tallennettu paikallisesti Puhdissa kansioon "image":
container: "image/tutorial.sif"
# Jos haluat muuntaa Docker-imagen Apptainer-säiliöimageksi lennossa:
container: "docker://<repository>/<image_name>"

Snakemake Tykky-asennus Pythonia varten

Asentaaksesi Snakemaken omilla Python-paketeilla käytä Tykkyn conda-pohjaista säiliökääretyökalua. Noudata Tykky-sivun ohjeita; conda-ympäristön tulee sisältää paketti snakemake. Jos aiot käyttää Snakemakea SLURM- tai HyperQueue-integraation kanssa (selitetään alla), asenna myös snakemake-executor-plugin-slurm SLURMia varten tai snakemake-executor-plugin-cluster-generic HyperQueuea varten. Nämä paketit ovat osa bioconda-repositoriota, joten lisää se conda-ympäristötiedoston kanavalistaan.

SLURM-integraatiota varten sinun täytyy lisäksi korjata Snakemake-ajotiedoston Python-polku:

Selvitä Tykky-asennuksesi Python-polku. Voit tarkistaa sen komennolla which python sen jälkeen, kun olet antanut Tykyn tulosteessa näkyvän export PATH ... -komennon.
Luo tiedosto post.sh. Vaihda /projappl/project_200xxx/tykky_installation_folder/bin/python oman Tykky-asennuksesi Python-poluksi.

post.sh

sed -i 's@#!.*@#!/projappl/project_200xxx/tykky_installation_folder/bin/python@g' $env_root/bin/snakemake

Päivitä asennus:

conda-containerize update <path to installation> --post-install post.sh

Jos käytät omaa Tykky-asennusta, korvaa alla olevissa esimerkeissä module load snakemake Tykkyn tulostamalla export-komennolla, esimerkiksi: export PATH="/projappl/project_xxxx/$USER/snakemake_tykky/bin:$PATH"

Huom

Huomaa, että koko työvuolle tulee luoda yksi Tykky-asennus, ei erillisiä asennuksia jokaiselle Snakemake-säännölle.

Käyttö

Snakemake voidaan ajaa supertietokoneissa neljällä eri tavalla:

Interaktiivisessa tilassa paikallisella suorittajalla, rajallisilla resursseilla. Hyödyllinen lähinnä virheenjäljitykseen tai hyvin pieniin työnkulkuihin.
Eräajona ja paikallisella suorittajalla. Resurssien käyttö rajoittuu yhteen kokonaiseen solmuun. Hyödyllinen pienille ja keskisuurille työnkuluille, yksinkertaisempi kuin seuraavat vaihtoehdot; aloita tästä, jos et ole varma.
Eräajona ja SLURM-suorittajalla. Voi käyttää useita solmuja ja eri SLURM-osioita (CPU ja GPU), mutta voi aiheuttaa merkittävää ylikuormaa, jos pieniä töitä on paljon. Tätä voi käyttää, jos jokainen työvaihe jokaiselle tiedostolle kestää vähintään 30 minuuttia.
Eräajona ja HyperQueue alityöajastimena. Voi käyttää useita solmuja saman eräajovarauksen sisällä, mutta on asetuksiltaan monimutkaisin. Sopii hyvin tilanteisiin, joissa työnkulku sisältää paljon pieniä työvaiheita ja paljon syötetiedostoja (suurteholaskenta).

Huom

Älä käynnistä raskaita Snakemake-työnkulkuja **kirjautumissolmuilla**.

Seuraava leikkiesimerkki havainnollistaa, miten Snakemake-työvuo voidaan ottaa käyttöön CSC:llä.

Snakefile

Snakefile kuvaa työvuon sisällön. Lisätietoa on saatavilla Snakemaken Snakefile-dokumentaatiosta

Käytetään havainnollistamiseen seuraavaa yksinkertaista Snakemake-skriptiä, Snakefile (isolla S-kirjaimella eikä tiedostopäätettä):

Snakefile

rule all:
        input: "CAPITAL_CASE.txt"

rule say_hello:
        output: "smaller_case.txt"
        shell:
                """
                echo "hello-world greetings from csc to snakemake community !" > smaller_case.txt
                """
rule capitalise:
        input: "smaller_case.txt"
        output: "CAPITAL_CASE.txt"
        shell:
                """
                tr '[:lower:]' '[:upper:]' < {input} > {output}
                """

Monimutkaisemmissa työnkuluissa voit tehdä argumenttien jäsentämistä ja muunnoksia ohjelmallisesti Snakemaken job properties file -ominaisuuden avulla.

Snakemake-työvuon ajaminen paikallisella suorittajalla interaktiivisesti

Resurssit varataan etukäteen sekä Snakemakelle että työnkulun töille yhtenä interaktiivisena istuntona. Interaktiivisessa istunnossa työnkulku voidaan käynnistää useita kertoja virheenjäljitystä varten niin kauan kuin varatut resurssit ovat käytettävissä. Katso resurssirajat interaktiiviselle osiolle.

sinteractive --cores 4 --mem 10000 # käynnistä interaktiivinen istunto 2 CPU-ytimellä ja 10 Gt muistilla
module load snakemake
cd <to_folder_with_snakefile>
snakemake -s Snakefile --jobs 4

--jobs - rinnakkain ajettavien töiden enimmäismäärä

Snakemake-työvuon ajaminen paikallisella suorittajalla eräajona

Resurssit varataan etukäteen sekä Snakemakelle että työnkululle yhtenä eräajona. Työ on käynnissä niin kauan kuin snakemake-komento on käynnissä ja pysähtyy automaattisesti sen valmistuttua. Paikallinen suorittaja on rajoitettu yhteen supertietokoneen solmuun. Ytimien määrää voidaan kasvattaa järjestelmästä riippuen - 40 Puhdissa ja 128 Mahdissa.

snakemake-local-executor.sh

#!/bin/bash
#SBATCH --job-name=myTest
#SBATCH --account=project_xxxxx
#SBATCH --time=00:10:00
#SBATCH --mem-per-cpu=2G
#SBATCH --partition=small
#SBATCH --cpus-per-task=4

module load snakemake
snakemake -s Snakefile --jobs 4

Lopuksi voit lähettää eräajon kirjautumissolmulta:

sbatch snakemake-local-executor.sh

Snakemake-työvuon ajaminen SLURM-suorittajalla

Ensimmäinen eräajotiedosto varaa resurssit vain Snakemakea itseään varten. Snakemake luo sitten lisää SLURM-töitä työnkulun sääntöjä varten. Snakemaken luomat SLURM-työt voidaan jakaa useille supertietokoneen solmuille, ja ne voivat myös käyttää eri osioita eri työnkulun säännöille, esimerkiksi CPU:ta ja GPU:ta. SLURM-suorittajaa tulisi käyttää vain, jos työvaiheet kestävät vähintään 20–30 minuuttia, muuten se voi kuormittaa SLURMia liikaa.

Tässä on bash-skripti yllä olevan leikkiesimerkin ajamiseen SLURM-suorittajalla:

snakemake-slurm-executor.sh

#!/bin/bash
#SBATCH --job-name=snakemake_slurm
#SBATCH --account=project_2008498
#SBATCH --time=00:20:00
#SBATCH --cpus-per-task=1
#SBATCH --mem-per-cpu=2GB
#SBATCH --partition=small
#SBATCH --output=slurm-%j.out
#SBATCH --error=slurm-%j.err

module load snakemake
snakemake --jobs 4  -s Snakefile --executor slurm --default-resources slurm_account=project_xxxx slurm_partition=small

Huom

Varmista, että Snakemaken oma varaus on riittävän pitkä sisältämään myös muiden prosessien käsittelyyn kuluvan odotusajan, mukaan lukien jonotusajan. Käytä mieluummin liian pitkää aikaa Snakemaken omalle eräajolle.

Kunkin SLURM-työn oletusresurssit ovat melko rajalliset. Jos haluat kasvattaa niitä (tai muuttaa niitä), määrittele kunkin säännön resurssitarpeet Snakefile-tiedostossa:

rule say_hello:
        output: "smaller_case.txt"
        resources:
                runtime = 5, # minutes
                cpus_per_task = 1,
                mem_mb = 20000
        shell:
                """
                echo "hello-world greetings from csc to snakemake community !" > smaller_case.txt
                """

Lopuksi voit lähettää eräajon kirjautumissolmulta:

sbatch snakemake-slurm-executor.sh

Lisätietoa: Snakemake SLURM executor

Huom

Töiden skaalaaminen Slurmin avulla tulee tehdä huolellisesti, jotta Slurmin laskutustietokantaa ei kuormiteta tarpeettomasti suurella määrällä pieniä töitä. Harkitse joko ryhmittelyä, localrules -määrityksiä tai HyperQueue-suorittajaa.

Snakemaken ajaminen HyperQueue-suorittajalla

Resurssit varataan etukäteen sekä Snakemakelle että työnkululle yhtenä eräajona. On mahdollista käyttää useita solmuja supertietokoneessa, mutta eri osioita ei voi käyttää eri työnkulun säännöille, esimerkiksi CPU:lle ja GPU:lle. HyperQueue-suorittaja sopii hyvin työnkulkuihin, joissa on paljon lyhyitä työvaiheita, koska se "piilottaa" ne SLURMilta. Työvaiheiden resurssit voidaan määritellä Snakefile-tiedostossa kuten SLURM-työssä.

snakemake-hyperqueue.sh

#!/bin/bash
#SBATCH --job-name=snakemake_hq
#SBATCH --account=project_2008498
#SBATCH --time=00:20:00
#SBATCH --cpus-per-task=4
#SBATCH --mem-per-cpu=40GB
#SBATCH --partition=small
#SBATCH --output=slurm-%j.out
#SBATCH --error=slurm-%j.err

module load hyperqueue
export HQ_SERVER_DIR="$PWD/hq-server/$SLURM_JOB_ID"
mkdir -p "$HQ_SERVER_DIR"
hq server start & until hq job list &> /dev/null ; do sleep 1 ; done

srun --overlap --cpu-bind=none --mpi=none hq worker start \
    --manager slurm \
    --on-server-lost finish-running \
    --cpus="$SLURM_CPUS_PER_TASK" & hq worker wait 1

# snakemake version 8.x.x.x
snakemake --keep-going -s Snakefile --jobs 4 --executor cluster-generic --cluster-generic-submit-cmd "hq submit --cpus 1"

# snakemake version 7.xx.x
# snakemake --cluster "hq submit  ..."

Lopuksi voit lähettää eräajon kirjautumissolmulta:

sbatch snakemake-hyperqueue.sh

Katso CSC:n HyperQueue-sivu, josta löydät lisää vaihtoehtoja ja tarkempia tietoja HyperQueuesta.

Huom

HyperQueue luo tehtäväkohtaisia kansioita (job-<n>) samaan hakemistoon, josta lähetit eräajoskriptin. Näistä on joskus hyötyä virheenjäljityksessä. Jos koodisi kuitenkin toimii hyvin, monien kansioiden luominen voi olla häiritsevää ja lisäksi aiheuttaa kuormaa Lustre-rinnakkaistiedostojärjestelmälle. Voit estää tällaisten tehtäväkohtaisten kansioiden luomisen asettamalla HyperQueuen stdout- ja stderr-liput arvoon none (eli hq submit --stdout=none --stderr=none ...)

Jos sinulla on kysyttävää tai ongelmia Snakemakeen liittyen, ota yhteyttä CSC:n asiakastukeen.