Hyppää sisältöön

Significant changes to Puhti & Mahti authentication coming in April! Read about the SSH key and multi-factor authentication requirements.

Snakemake-työnkulun suorittaminen Puhtilla

Snakemake-työnkulku on yksi bioinformatiikkayhteisön suosituista tieteellisistä työnkuluista, vaikka työnkulkumanageria voidaan käyttää myös muilla tieteellisillä aloilla. Snakemake mahdollistaa skaalautuvat ja toistettavat tieteelliset putket yhdistämällä sarjan sääntöjä täysin määritellyssä ohjelmistoympäristössä.

Jos olet edelleen epävarma työkulkujen yleisestä käytöstä tai siitä, mitä työkaluja käyttää, katso myös Suorituskykyinen laskenta ja työnkulut -sivu.

Asennus

Snakemake on saatavilla moduulina Puhti-supertietokoneessa. Tämä vaihtoehto sopii hyvin, jos työkulkuihin kuuluu komentorivityökaluja muista moduuleista tai Apptainer-säilöistä. Jos työkulkuun kuuluu Python-skriptejä, jotka vaativat räätälöityjä Python-paketteja, tee oma Snakemake-asennus Tykkyä käyttäen.

Snakemake-moduuli

Snakemake-moduuli on helpoin vaihtoehto. Saatavilla olevat versiot löytyvät Snakemaken sovellussivulta.

module load snakemake
snakemake --help   # lisätietoa valinnoista.

Huomautus

Kiinnitä huomiota käyttämääsi Snakemaken versioon. Jos käytät vanhempia versioita (esim. v7.xx.x), syntaksimuutoksia saattaa olla.

Työkulun työkalujen asennus

Työkulun työkalut voidaan asentaa seuraavilla tavoilla:

  1. Muut Puhti-moduulit tai oma räätälöity moduuli.
    • Jos kaikki Snakemake-säännöt käyttävät samoja moduuleja, lataa ne ennen Snakemake-komentojen suorittamista.
    • Jos eri säännöt käyttävät eri moduuleja, sisällytä moduulitiedot Snakefileen.
  2. Omat räätälöidyt asennukset Apptainer-säilöinä: 
# Jos Apptainer-kuva tutorial.sif on tallennettu paikallisesti Puhtilla kansioon "image":
container: "image/tutorial.sif"
# Jos haluat muuntaa Docker-kuvan Apptainer-säilökuvaksi lennossa:
container: "docker://<repository>/<image_name>"

Snakemake Tykky -asennus Pythonille

Asentaaksesi Snakemaken mukautetuilla Python-paketeilla, käytä Tykky-säilösuojaustyökalua conda kanssa. Noudata Tykky-sivun ohjeita, conda-ympäristön tulee sisältää paketti snakemake. Jos aiot käyttää Snakemakea SLURM- tai HyperQueue-integraation kanssa (selitetty alhaalla), asenna myös snakemake-executor-plugin-slurm SLURMille tai snakemake-executor-plugin-cluster-generic HyperQueuelle. Nämä paketit ovat osa bioconda-arkistoa, joten lisää se kanavien listalle conda-ympäristötiedostossa.

SLURM-integraatiota varten sinun täytyy myös korjata Snakemake-suoritettavan tiedoston Python-polku:

  • Selvitä Tykky-asennuksesi Python-polku. Voit tarkistaa sen which python -komennolla sen jälkeen, kun olet antanut Tykky-tulostuksen export PATH ....
  • Luo tiedosto post.sh. Muuta /projappl/project_200xxx/tykky_installation_folder/bin/python omaan Tykky-asennuksesi Python-polkuun.
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, vaihda alla olevissa esimerkeissä module load snakemake Tykyn tulostamana export-komentoon, esimerkiksi: export PATH="/projappl/project_xxxx/$USER/snakemake_tykky/bin:$PATH"

Huomautus

Huomaa, että luodaksesi yhden Tykky-asennuksen koko työnkululle, älä yksittäisiä asennuksia jokaiselle Snakemake-säännölle.

Käyttö

Snakemaken voi suorittaa neljällä eri tavalla supertietokoneissa:

  1. Interaktiivisessa tilassa paikallisella tehtävä-suorittimella, rajallisilla resursseilla. Hyödyllinen lähinnä debuggingiin tai hyvin pienille työnkuluille.
  2. Erätyönä ja paikallisella tehtävä-suorittimella. Resurssin käyttö rajoittuu yhteen täyteen solmuun. Käytännöllinen pienille ja keskikokoisille työnkuluille, yksinkertaisempi kuin seuraavat vaihtoehdot, aloita tästä, jos olet epävarma.
  3. Erätyönä ja SLURM-tehtävä-suorittimella. Voi käyttää useampaa solmua ja eri SLURM-osastoja (CPU ja GPU), mutta voi aiheuttaa huomattavaa ylimääräistä kuormitusta, jos monta pientä työpaikkaa. Voidaan käyttää, jos kustakin tiedostosta jokainen työvaihe kestää vähintään 30 minuuttia.
  4. Erätyönä ja HyperQueue alityön ajastimena. Voi käyttää useita solmuja samassa erätyön jaossa, monimutkaisin asetus. Sopii hyvin tapauksiin, kun työnkulku sisältää paljon pieniä työvaiheita monilla syöttötiedostoilla (suorituskykyinen laskenta).

Huomautus

Ethän käynnistä raskaita Snakemake-työnkulkuja kirjautumissolmuille.

Seuraava esimerkki havainnollistaa, kuinka Snakemake-työnkulku voidaan ottaa käyttöön CSC:ssä.

Snakefile

Snakefile kuvaa työnkulun sisällön. Lisätietoja löytyy Snakemaken Snakefile-dokumentaatiosta.

Käytämme seuraavaa leikkiesimerkin Snakemake-skriptiä, Snakefile (isolla S), havainnollistuksena:

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}
                """

Monimutkaisempia työnkulkuja varten voit tehdä argumenttien jäsentämistä ja muunnetta ohjelmallisesti käyttäen Snakemaken tehtävän ominaisuustiedostoa.

Snakemake-työnkulun suorittaminen paikallisella tehtävä-suorittimella interaktiivisesti

Resurssit varataan etukäteen, sekä Snakemakelle että työnkulun tehtäväille yksi interaktiivinen istunto. Interaktiivisessa istunnossa työnkulku voidaan käynnistää useita kertoja virheenkorjausta varten niin kauan kuin varatut resurssit ovat käytettävissä. Katso resurssirajoitukset interaktiivisesta osastosta.

sinteractive --cores 4 --mem 10000 # käynnistä interaktiivinen istunto, jossa on 2 CPU ydintä ja 10 Gt muistia
module load snakemake
cd <to_folder_with_snakefile>
snakemake -s Snakefile --jobs 4
  • --jobs - paras rinnakkain ajettavien tehtävien määrä

Snakemake-työnkulun suorittaminen paikallisella tehtävä-suorittimella ja erätyöllä

Resurssit varataan etukäteen, sekä Snakemakelle että työnkululle yhdeksi erätyöksi. Tehtävä jatkuu niin kauan kuin snakemake-komento on käynnissä ja pysähtyy automaattisesti, kun se valmistuu. Paikallinen tehtävä-suoritin on rajoitettu yhteen supertietokoneen solmuun. Käytettävissä olevien ydinten määrä voi vaihdella järjestelmän mukaan - 40 Puhdissa ja 128 Mahtissa.

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ätyön kirjautumissolmusta:

sbatch snakemake-local-executor.sh

Snakemake-työnkulun suorittaminen SLURM-tehtävä-suorittimella

Ensimmäinen erätyötiedosto varaa resursseja vain Snakemakelle itselleen. Snakemake luo sitten lisää SLURM-tehtäviä työnkulun säännöille. Snakemaken luomat SLURM-tehtävät voidaan jakaa useille supertietokoneen solmuille ja käyttää myös eri osastoja eri työnkulku-säännöille, kuten CPU ja GPU. SLURM-tehtävä-suoritinta pitäisi käyttää vain, jos työvaiheet kestävät vähintään 20-30 minuuttia, muuten se saattaisi ylikuormittaa SLURM:ia.

Tässä on bash-skripti, jolla yllä oleva esimerkki suoritetaan SLURM-tehtävä-suorittimella:

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

Huomautus

Varmista, että Snakemaken oma varaus on tarpeeksi pitkä kattamaan myös muiden prosessien käsittelyyn kuluvan odotteluajan, mukaan lukien jonotusaika. Pikeminkin varaa liian pitkä aika Snakemaken omalle erätyölle.

Oletusresurssit jokaiselle SLURM-tehtävälle ovat melko rajalliset, kasvattaaksesi (tai muuttaaksesi) määrittele resurssitarpeet jokaiselle säännölle Snakefileessa: 

rule say_hello:
        output: "smaller_case.txt"
        resources:
                runtime = 5, # minuuttia
                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ätyön kirjautumissolmusta:

sbatch snakemake-slurm-executor.sh

Lisätietoja Snakemake SLURM -tehtävä-suorittimesta

Huomautus

Työtehtävien ajaminen SLURM:lla on tehtävä huolella, jotta vältetään turhaa SLURM:n kirjanpitojärjestelmän kuormitusta suurella määrällä pieniä tehtäviä. Suositellaan joko ryhmittelyä, lokaalisääntöjä tai HyperQueue-tehtävä-suoritinta.

Snakemaken suorittaminen HyperQueue-tehtävä-suorittimella

Resurssit varataan etukäteen, sekä Snakemakelle että työnkululle yhdeksi erätyöksi. On mahdollista käyttää useita solmuja supertietokoneella, mutta ei käyttää eri osastoja eri työnkulkusäännöille, esimerkiksi CPU ja GPU. HyperQueue fits hyvin työnkulkuille, joissa on paljon lyhyitä työvaiheita, koska se "piilottaa" ne SLURM:lta. Työvaiheiden resurssit voidaan määritellä Snakefileessa kuten SLURM-tehtävissä.

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ätyön kirjautumissolmusta:

sbatch snakemake-hyperqueue.sh

Katso CSC HyperQueue -sivulta lisävalintoja ja lisätietoja HyperQueuesta.

Huomautus

HyperQueue luo tehtäväkohtaisia kansioita (job-<n>) samassa hakemistossa, josta lähetit eräskriptin. Nämä ovat joskus hyödyllisiä virheenkorjaukseen. Jos koodi kuitenkin toimii hyvin, useiden kansioiden luonti voi olla ärsyttävää ja aiheuttaa kuormitusta Lustre-paralleellitiedostojärjestelmälle. Voit estää tällaisten tehtäväkohtaisten kansioiden luomisen asettamalla stdout- ja stderr-HyperQueue-vihjeet none (eli hq submit --stdout=none --stderr=none ...).

Jos sinulla on kysyttävää tai ongelmia Snakemaken suhteen, ota yhteyttä CSC:n palvelupisteeseen.