Snakemake

Snakemake on Python-pohjainen tieteellinen työnvuonhallintajärjestelmä skaalautuvien, siirrettävien ja toistettavien työnkulkujen luomiseen. Se on yksi bioinformatiikkayhteisön suosituista työnvuonhallintatyökaluista, mutta ei ole rajattu vain bioinformatiikkaan. Snakemake mahdollistaa skaalautuvat ja toistettavat tieteelliset putket ketjuttamalla sarjan sääntöjä täysin määritellyssä ohjelmistoympäristössä. Kuten Nextflow'ssa, myös Snakemake tukee skriptien suorittamista (Snakemake-säännön script/run/shell-direktiivin kautta) muilla kielillä, kuten R:llä, bashilla ja Pythonilla.

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.

Snakemake

Saatavuus

CSC:llä saatavilla olevat versiot:

Roihu-CPU: 9.11.6, 7.17.1
Roihu-GPU: ei saatavilla
Puhti: 7.15.2, 7.17.1, 8.4.6

Lisenssi

Snakemake on julkaistu MIT-lisenssillä.

Asennus

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

Snakemake-moduuli

Snakemake-moduuli on helpoin vaihtoehto. Saatavilla olevat versiot on lueteltu yllä.

module load snakemake
snakemake --help   #  to get information on more options.

Esimerkki snakemake-moduulin lataamisesta tietyllä versiolla:

module load snakemake/8.4.6

Snakemaken uusin versio (v8.4.6) asennettiin Puhtiin virtuaaliympäristöön pip3:n avulla. Katso luettelo tässä moduulissa käytetyistä Python-paketeista.

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önvuossa käytettävien työkalujen asennus

Työnvuossa 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 samaa moduulia tai samoja moduuleita, lataa ne ennen snakemake-komentojen suorittamista.
- Jos eri Snakemake-säännöt käyttävät eri moduuleita, 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 luonti -sivulla.
- Katso Snakemaken töiden suorittaminen 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-valintaa.
- Joskus voi olla tarpeen määritellä säiliön sisällä käytettävä shell.

# If your Apptainer tutorial.sif image is stored locally in Puhti 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>"

Snakemaken Tykky-asennus Pythonille

Asentaaksesi Snakemaken mukautetuilla Python-paketeilla käytä Tykkyn conda-pohjaista säiliökäärintätyö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 kanavaluetteloon.

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

Selvitä Tykky-asennuksesi Python-polku. Voit tarkistaa sen komennolla which python sen jälkeen, kun olet antanut Tykkyn 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 näin: export PATH="/projappl/project_xxxx/$USER/snakemake_tykky/bin:$PATH"

Huom

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

Käyttö

Snakemake voidaan suorittaa supertietokoneissa neljällä eri tavalla:

Interaktiivisessa tilassa paikallisella suorittajalla ja rajallisilla resursseilla. Hyödyllinen lähinnä virheenjäljitykseen tai hyvin pieniin työnkulkuihin.
Eräajona paikallisella suorittajalla. Resurssien käyttö on rajattu yhteen kokonaiseen solmuun. Hyödyllinen pienille ja keskisuurille työnkuluille, yksinkertaisempi kuin seuraavat vaihtoehdot; aloita tästä, jos et ole varma.
Eräajona SLURM-suorittajalla. 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 siten, että HyperQueue toimii alityöajastimena. Voi käyttää useita solmuja saman eräajovarauksen sisällä, mutta on asetuksiltaan monimutkaisin. Sopii hyvin tilanteisiin, joissa työnvuo 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önvuo voidaan ottaa käyttöön CSC:llä.

Snakefile

Snakefile kuvaa työnvuon sisällön. Lisätietoja on saatavilla Snakemaken Snakefile-dokumentaatiosta

Käytetään havainnollistamiseen seuraavaa yksinkertaista Snakemake-skriptiä, Snakefile (isolla S-kirjaimella ja ilman 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önvuon suorittaminen paikallisella suorittajalla interaktiivisesti

Resurssit varataan etukäteen sekä Snakemakelle että työnvuon töille yhtenä interaktiivisena istuntona. Interaktiivisessa istunnossa työnvuo 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 # start an interactive session with 2 CPU cores and 10 Gb of memory
module load snakemake
cd <to_folder_with_snakefile>
snakemake -s Snakefile --jobs 4

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

Snakemake-työnvuon suorittaminen paikallisella suorittajalla eräajona

Resurssit varataan etukäteen sekä Snakemakelle että työnvuolle 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. Ydinten määrää voidaan kasvattaa järjestelmästä riippuen – 40 Puhtissa 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önvuon suorittaminen SLURM-suorittajalla

Ensimmäinen eräajotiedosto varaa resurssit vain Snakemakelle itselleen. Sen jälkeen Snakemake luo lisää SLURM-töitä työnvuon 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önvuon 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 suorittamiseen 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ä kattamaan myös muiden prosessien käsittelyyn kuluvan odotusajan, mukaan lukien jonotusajan. On parempi varata Snakemaken omaan eräajoon liian paljon kuin liian vähän aikaa.

Kunkin SLURM-työn oletusresurssit ovat melko rajalliset. Jos haluat kasvattaa niitä (tai muuttaa niitä), määrittele resurssitarpeet jokaiselle säännölle 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ätietoja: Snakemaken SLURM-suorittaja

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 suorittaminen HyperQueue-suorittajalla

Resurssit varataan etukäteen sekä Snakemakelle että työnvuolle yhtenä eräajona. On mahdollista käyttää useita solmuja supertietokoneessa, mutta eri osioita ei voi käyttää eri työnvuon 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-ajoissa.

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 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 kysymyksiä 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.