Snakemake¶
Snakemake on Python-pohjainen tieteellinen työnvuonhallintajärjestelmä skaalautuvien, siirrettävien ja toistettavien työnkulkujen luomiseen. Se on yksi bioinformatiikkayhteisön suosituista työnkulunhallintatyökaluista, mutta ei ole erityisesti bioinformatiikkaan sidottu. Snakemake mahdollistaa skaalautuvat ja toistettavat tieteelliset putket ketjuttamalla joukon sääntöjä täysin määritellyssä ohjelmistoympäristössä. Kuten Nextflow’ssa, myös Snakemake tukee muiden kielten, kuten R:n, bashin ja Pythonin, skriptien suorittamista (Snakemake-säännön script/run/shell-direktiivin kautta).
Jos pohdit edelleen työnkulkuja yleisemmällä tasolla tai sitä, mitä työnkulkuvälinettä kannattaa käyttää, katso myös Suurteholaskenta ja työnkulut -sivu.
Saatavuus¶
CSC:llä saatavilla olevat versiot:
- Roihu-CPU: 7.32.4, 9.14.0, 9.16.2, 9.27.1 (
bio-apps-moduulin kautta) - Roihu-GPU: 7.32.4, 9.14.0, 9.16.2, 9.27.1 (
bio-apps-moduulin kautta)
Lisenssi¶
Snakemake on julkaistu MIT-lisenssillä.
Asennus¶
Roihussa Snakemake kuuluu bio-apps -kokoelmaan ja on saatavilla sekä CPU- että GPU-solmuilla. Tämä vaihtoehto sopii hyvin, jos työnkulku sisältää komentorivityökaluja muista moduuleista tai Apptainer-säiliöistä. Jos työnkulku sisältää Python-skriptejä, jotka vaativat omia Python-paketteja, tee oma Snakemake-asennus Tykyllä.
Snakemake-moduuli¶
Snakemake-moduuli on helpoin vaihtoehto. Lataa ensin bio-apps-moduulipuu ja sitten Snakemake-moduuli. Saatavilla olevat versiot on lueteltu yllä.
module load bio-apps/v202603
module load snakemake/9.27.1
snakemake --help # to get information on more options.
Tietyn version lataaminen, esimerkiksi Snakemake 7:
Snakemake-moduulit sisältävät pandasin, joten Snakefile voi käyttää sitä esimerkiksi näytetaulukon lukemiseen.
Huom.
Kiinnitä huomiota käyttämääsi Snakemake-versioon. Jos käytät Snakemaken aiempia versioita (esim. v7.xx.x), syntaksi voi olla erilainen.
Työnkulussa käytettävien työkalujen asennus¶
Työnkulussa käytettävät työkalut voidaan asentaa seuraavilla tavoilla:
- Työkalut, jotka ovat saatavilla muissa moduuleissa tai omassa mukautetussa moduulissa.
- Jos kaikki Snakemake-säännöt käyttävät samoja moduuleja, lataa ne ennen snakemake-komentojen suorittamista.
- Jos eri Snakemake-säännöt käyttävät eri moduuleja, sisällytä moduulitiedot Snakefileen.
- Omat mukautetut asennukset Apptainer-säiliöinä:
- Apptainer-säiliö voidaan ladata jostakin repositoriosta tai rakentaa paikallisesti. Mukautettujen Apptainer-säiliöiden rakentamisesta katso Säiliöiden luominen -sivu.
- Katso Snakemaken Running jobs in containers tarvittavista muutoksista Snakemake-tiedostoon ja komentoon.
- 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äinen shell.
# If your Apptainer tutorial.sif image is stored locally in folder "image":
container: "image/tutorial.sif"
# If you would like to convert a Docker image to Apptainer container image on-the-fly:
container: "docker://<repository>/<image_name>"
Snakemake Tykky -asennus Pythonille¶
Asentaaksesi Snakemaken omilla Python-paketeilla, käytä Tykyn säiliökäärintätyökalua condan kanssa. 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 HyperQueue’ta 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-suoritustiedoston Python-polku:
- Selvitä Tykky-asennuksesi Python-polku. Voit tarkistaa sen komennolla
which pythonsen jälkeen, kun olet antanut Tykyn tulosteessa näkyvänexport PATH ...-komennon. - Luo tiedosto
post.sh. Vaihda/projappl/project_200xxx/tykky_installation_folder/bin/pythonoman Tykky-asennuksesi Python-poluksi.
sed -i 's@#!.*@#!/projappl/project_200xxx/tykky_installation_folder/bin/python@g' $env_root/bin/snakemake
- Päivitä asennus:
Jos käytät omaa Tykky-asennusta, korvaa alla olevissa esimerkeissä module load -komennot Tykyn tulostamalla export-komennolla, esimerkiksi: export PATH="/projappl/project_xxxx/$USER/snakemake_tykky/bin:$PATH"
Huom.
Huomaa, että koko työnkululle tulee luoda yksi Tykky-asennus, ei erillisiä asennuksia jokaiselle Snakemake-säännölle.
Käyttö¶
Snakemakea voidaan ajaa supertietokoneissa neljällä eri tavalla:
- Interaktiivisessa tilassa paikallisella executorilla, rajallisilla resursseilla. Hyödyllinen lähinnä virheenjäljitykseen tai hyvin pieniin työnkulkuihin.
- Eräajona ja paikallisella executorilla. 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-executorilla. Voi käyttää useita solmuja ja eri SLURM-osioita (CPU ja GPU), mutta voi aiheuttaa merkittävää kuormaa, 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 (high-throughput computing).
Huom.
Älä käynnistä raskaita Snakemake-työnkulkuja kirjautumissolmuilla.
Seuraava leikkiesimerkki havainnollistaa, miten Snakemake-työnkulku voidaan ottaa käyttöön CSC:llä.
Snakefile¶
Snakefile kuvaa työnkulun sisällön. Lisätietoa on saatavilla Snakemake Snakefile -dokumentaatiosta
Käytetään havainnollistamiseen seuraavaa yksinkertaista Snakemake-skriptiä, Snakefile (isolla S-kirjaimella ja ilman tiedostopäätettä):
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önkulun ajaminen paikallisella executorilla 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.
Roihun interactive-osiossa saat oletuksena 1 GiB muistia jokaista varattua ydintä kohti, ja voit pyytää lisää --mem-valitsimella (enintään 32 ydintä / 64 GiB / 36 tuntia).
sinteractive --account <project> --cores 4 --mem 12G # 12 GiB of memory
module load bio-apps/v202603
module load snakemake/9.27.1
cd <to_folder_with_snakefile>
snakemake -s Snakefile --jobs 4
--jobs- rinnakkain ajettavien töiden enimmäismäärä
Snakemake-työnkulun ajaminen paikallisella executorilla eräajona¶
Resurssit varataan etukäteen sekä Snakemakelle että työnkululle yhtenä eräajona. Työ suoritetaan niin kauan kuin snakemake-komento on käynnissä ja pysähtyy automaattisesti sen valmistuttua. Paikallinen executor on rajoitettu yhteen supertietokoneen solmuun.
#!/bin/bash
#SBATCH --job-name=myTest
#SBATCH --account=<project>
#SBATCH --time=00:10:00
#SBATCH --partition=small
#SBATCH --cpus-per-task=4
#SBATCH --mem-per-cpu=2G
module load bio-apps/v202603
module load snakemake/9.27.1
snakemake -s Snakefile --jobs 4
Lopuksi voit lähettää eräajon kirjautumissolmulta:
Snakemake-työnkulun ajaminen SLURM-executorilla¶
Ensimmäinen eräajotiedosto varaa resurssit vain Snakemakelle itselleen. 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-executoria 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-executorilla:
#!/bin/bash
#SBATCH --job-name=snakemake_slurm
#SBATCH --account=<project>
#SBATCH --time=00:20:00
#SBATCH --partition=small
#SBATCH --cpus-per-task=1
#SBATCH --mem-per-cpu=2G
#SBATCH --output=slurm-%j.out
#SBATCH --error=slurm-%j.err
module load bio-apps/v202603
module load snakemake/9.27.1
snakemake --jobs 4 -s Snakefile --executor slurm --default-resources slurm_account=<project> slurm_partition=small
Huom.
Varmista, että Snakemaken oma varaus on riittävän pitkä kattamaan 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; kasvattaaksesi niitä (tai muuttaaksesi niitä) määrittele kunkin säännön resurssitarpeet Snakefilessa:
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:
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-sääntöjä tai Hyperqueue-executoria.
Snakemaken ajaminen HyperQueue-executorilla¶
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-executor sopii hyvin työnkulkuihin, joissa on paljon lyhyitä työvaiheita, koska se "piilottaa" ne SLURMilta. Työvaiheiden resurssit voidaan määritellä Snakefilessa kuten SLURM-työssä.
#!/bin/bash
#SBATCH --job-name=snakemake_hq
#SBATCH --account=<project>
#SBATCH --time=00:20:00
#SBATCH --partition=small
#SBATCH --cpus-per-task=4
#SBATCH --mem-per-cpu=4G
#SBATCH --output=slurm-%j.out
#SBATCH --error=slurm-%j.err
module load hyperqueue
module load bio-apps/v202603
module load snakemake/9.27.1
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 and 9.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:
Katso CSC:n HyperQueue-sivu, josta löydät lisää vaihtoehtoja ja yksityiskohtia 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 kysymyksiä tai ongelmia Snakemakeen liittyen, ota yhteyttä CSC:n asiakastukeen.
Viitteet¶
Jos käytät Snakemakea työssäsi, viittaa seuraavaan julkaisuun:
Mölder, F., Jablonski, K.P., Letcher, B., Hall, M.B., Tomkins-Tinch, C.H., Sochat, V., Forster, J., Lee, S., Twardziok, S.O., Kanitz, A., Wilm, A., Holtgrewe, M., Rahmann, S., Nahnsen, S., Köster, J. Sustainable data analysis with Snakemake. F1000Research 2021, https://doi.org/10.12688/f1000research.29032.1.
Lisätietoja¶
- Snakemaken virallinen dokumentaatio
- CSC Snakemake Hackathon 2024
- Antoni Gołośin diplomityö, jossa vertaillaan automatisoituja työnkulkuratkaisuja supertietokoneilla
- Ota yhteyttä CSC Service Deskiin teknistä tukea varten