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 rajoitu bioinformatiikkaan. Snakemake mahdollistaa skaalautuvat ja toistettavat tieteelliset putket ketjuttamalla joukon sääntöjä täysin määritellyssä ohjelmistoympäristössä. Kuten Nextflow’ssa, Snakemake tukee myös 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 suurteholaskennan ja työnkulkujen sivu.
Saatavuus
CSC:llä saatavilla olevat versiot:
- Roihu-CPU: 7.32.4, 9.14.0 (
bio-apps-moduulin kautta) - Roihu-GPU: 7.32.4, 9.14.0 (
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-konteista. Jos työnkulku sisältää Python-skriptejä, jotka vaativat mukautettuja 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.14.0
snakemake --help # to get information on more options.
Tietyn version lataaminen, esimerkiksi Snakemake 7:
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-kontteina:
- Apptainer-kontti voidaan ladata jostakin repositoriosta tai rakentaa paikallisesti. Mukautettujen Apptainer-konttien rakentamisesta kerrotaan konttien luontisivulla.
- Katso Snakemaken ohjeesta Running jobs in containers, mitä muutoksia Snakemake-tiedostoon ja komentoon tarvitaan.
- Kansioiden liittämiseen tai muiden Apptainer-lippujen käyttöön käytä
snakemake-komennon --apptainer-args-valintaa. - Joskus voi olla tarpeen määritellä komentotulkki kontin sisällä.
# 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 mukautetuilla Python-paketeilla käytä Tykyn konttikääretyökalua conda-ympäristön 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 kanavaluetteloon.
SLURM-integraatiota varten sinun täytyy myös 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 näin: export PATH="/projappl/project_xxxx/$USER/snakemake_tykky/bin:$PATH"
Huom
Huomaa, että koko työnkulkua varten kannattaa tehdä yksi Tykky-asennus, ei erillisiä asennuksia jokaiselle Snakemake-säännölle.
Käyttö
Snakemakea voidaan ajaa supertietokoneilla neljällä eri tavalla:
- Interaktiivisessa tilassa paikallisella suorittajalla, rajallisilla resursseilla. Hyödyllinen lähinnä virheenjäljitykseen tai hyvin pieniin työnkulkuihin.
- Eräajona paikallisella suorittajalla. Resurssien käyttö rajoittuu yhteen kokonaiseen solmuun. Sopii pieniin ja keskikokoisiin työnkulkuihin, on yksinkertaisempi kuin seuraavat vaihtoehdot, joten aloita tästä, jos olet epävarma.
- Eräajona 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 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 monilla syötetiedostoilla (suurteholaskenta).
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ätietoja 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 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 interactive-osiolle. Roihun interactive-osiossa jokainen varattu ydin tarjoaa 1,875 Gt muistia (enintään 32 ydintä / 60 Gt / 36 tuntia).
sinteractive --account <project> --cores 6 # ~11 GB of memory
module load bio-apps/v202603
module load snakemake/9.14.0
cd <to_folder_with_snakefile>
snakemake -s Snakefile --jobs 4
--jobs- rinnakkain ajettavien töiden enimmäismäärä
Snakemake-työnkulun ajaminen paikallisella suorittajalla 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 suorittaja 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.14.0
snakemake -s Snakefile --jobs 4
Lopuksi voit lähettää eräajon kirjautumissolmulta:
Snakemake-työnkulun ajaminen SLURM-suorittajalla
Ensimmäinen eräajotiedosto varaa resurssit vain itse Snakemakelle. Sen jälkeen Snakemake luo 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:
#!/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.14.0
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. Jos haluat kasvattaa niitä (tai muuttaa niitä), määrittele resurssitarpeet jokaiselle säännölle 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ätietoja: 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-suorittajaa.
Snakemaken ajaminen HyperQueue-suorittajalla
Resurssit varataan etukäteen sekä Snakemakelle että työnkululle yhtenä eräajona. On mahdollista käyttää useita solmuja supertietokoneella, 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ä 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.14.0
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. Niistä 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.
Viitteet
Jos käytät Snakemakea työssäsi, viittaa seuraavasti:
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.