Singularity intro

Uruchamianie oraz katalog cache.

Uruchamianie singularity

Singularity nie jest dostępne na węzłach dostępowych, dlatego żeby móc korzystać z kontenerów trzeba uruchomić tryb interaktywny:

$ srun --pty /bin/bash

albo umieścić polecenia w skrypcie zlecającym zadanie w trybie wsadomwym.

Katalog cache

W katalogu domowym (/mnt/storage_3/home/igrbiom2 albo ~) singularity tworzy katalog .singularity, który potencjalnie może być zbyt duży na partycję katalogu domowego. Dlatego przed pierwszym uruchomieniem należy zastąpić go połączeniem symbolicznym do katalogu w project_data, np.

$ mkdir ~/pl0217-01/singularity_cache
$ ln -s ~/pl0217-01/singularity_cache .singularity

zrobiłem to już wcześniej, ale warto o tym pamiętać na wszelki wypadek. Aktualny połączenie .singularity:

.singularity -> /mnt/storage_3/home/igrbiom2//pl0217-01/project_data/containers_hryc/

Pobieranie gotowych kontenerów.

Gotowe kontenerey

Gotowe kontenery można znaleźć i pobrać, m.in. tutaj:

https://biocontainers.pro/
https://hub.docker.com/
https://depot.galaxyproject.org/singularity/
https://cloud.sylabs.io/library

pull

Pull pozwala zapisać kontener jako plik .sif

  pull        Pull an image from a URI

Przykładowo tutaj pobieram kontener FastQC i zapisuję go jako FASTQC.sif. Uruchomienie kontenera za pomocą singularity run-help wypisuje informacje o kontenerze (jeśli autor je dodał).

$ singularity pull FASTQC.sif library://olivier/rnaseq_qc/fastqc
$ singularity run-help FASTQC.sif 
    This is a Singularity container that includes FastQC, a quality control tool for high throughput sequence data.

run, exec, shell

Możliwe jest pobranie kontenera, zapisanie go w cache’u (.singularity) i natychmiastowe uruchomienie. Przykładowo tutaj pobieram kontener z bwa-mem2 i od razu uruchamiam go w trybie wiersza polecenia:

$ singularity shell https://depot.galaxyproject.org/singularity/bwa-mem2:2.2.1--he70b90d_6
Singularity> bwa-mem2
Looking to launch executable "/usr/local/bin/bwa-mem2.avx512bw", simd = .avx512bw
Launching executable "/usr/local/bin/bwa-mem2.avx512bw"
Usage: bwa-mem2 <command> <arguments>
Commands:
  index         create index
  mem           alignment
  version       print version number

Podobnie można pobrać i uruchomić kontener poleceniem run albo exec.

Jeśli kontener jest zapisany w cache’u nie będzie pobierany przy kolejnym uruchomieniu.

Sposoby uruchomienia konterów.

Do kontenera można przekazać jedno polecenie (exec), albo uruchomić wewnątrz wiersz polecenia i pracować w trybie interaktywnym.

exec

  exec        Run a command within a container

Uruchomienie kontenera w trybie exec wykonuje wewnątrz podane przez użytkownika polecenie. Tutaj wykonuję w kontenerze simseq.sif polecenie fortune, które wypisuje na ekranie losowy cytat:

$ singularity exec simseq.sif fortune
If more of us valued food and cheer and song above hoarded gold, it would
be a merrier world.
                -- J.R.R. Tolkien

shell

  shell       Run a shell within a container

Uruchomienie kontenera w trybie wiersza polecenia (shell) pozwala na wykonanie dowolnej liczby poleceń i pracę w trybie interaktywnym. Tutaj uruchamiam kontener w trybie interaktywnym, wywołuję fortune 3 razy i zamykam kontener wpisując exit (można też użyć skrótu klawiszowego ctrl+d):

$ singularity shell simseq.sif
Singularity> for i in {1..3}; do fortune; done
Its name is Public Opinion.  It is held in reverence.  It settles everything.
Some think it is the voice of God.
                -- Mark Twain
You are magnetic in your bearing.
The better part of valor is discretion.
                -- William Shakespeare, "Henry IV"
Singularity> exit

Niektóre kontenery zawierają predefiniowane skrypty, które można wywołać uruchamiając kontener za pomocą odpowiedniej komendy:

run

  run         Run the user-defined default command within a container

Uruchomienie kontenera w trybie run wykonuje predefiniowane przez autora polecenie (zapisane w pliku .def). Na przykład dla mojego kontenera simseq.sif runscript jest zdefiniowany w taki sposób:

%runscript
    fortune | cowsay | lolcat

A tutaj efekt uruchomienia z run:

$ singularity run simseq.sif 
 ___________________________________
/ Your heart is pure, and your mind \
\ clear, and your soul devout.      /
 -----------------------------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

run-help

  run-help    Show the user-defined help for an image

Uruchomienie kontenera z run-help wypisuje na ekranie informacje o kontenerze (jeśli autor je dodał). Tutaj przykłady obu przypadków:

$ singularity run-help simseq.sif 
Przykładowy kontener Singularity. Zawiera fortune, cowsay, lolcat i skrypt
simseq generujący chromosomy w oparciu o HMM.

Użycie simseq:
  simseq [długość sekwencji] [liczba sekwencji]

Przykładowe skrypty:
  fortune | cowsay | lolcat     Wypisuje na ekranie tęczowy obrazek krowy z
                                losowym cytatem

  simseq 100 10                 Generuje 10 chromosomów długości 100 nt w
                                formacie FASTA

$ singularity run-help lolcow.sif 
No help sections were defined for this image

test

  test        Run the user-defined tests within a container

Uruchomienie kontenera z test wykonuje predefiniowany skrypt testowy (o ile został dodany). Tutaj przykłady obu przypadków:

$ singularity test simseq.sif
'This test does nothing! [test]

$ singularity test lolcow.sif 
INFO:    No test script found in container, exiting

Montowanie katalogów.

Na klastrze eagle katalogi archive, project_data i scratch tak naprawdę są połączeniami symbolicznymi, przez które nie da się przechodzić będąc w kontenerze.

archive -> /mnt/storage_3/archive/pl0217-01
project_data -> /mnt/storage_2/project_data/pl0217-01
scratch -> /mnt/storage_2/scratch/pl0217-01

W praktyce oznacza to, że bez zamontowania katalogów kontener ma dostęp tylko do katalogu domowego.

Poza tym montowanie katalogów pozwala na lepszą organizację ścieżek oraz wykonywanie dużych skryptów za pomocą exec

Katalogi

Przyjmijmy, że w naszych obliczeniach będziemy korzystać z katalogów: (1) ze skryptami, (2) z danymi wejściowymi, (3) z kontenerami:

~/pl0217-01/project_data/skrypty/
~/pl0217-01/scrath/dane/
~/pl0217-01/project_data/kontenery/

Uruchomienie exec z montowaniem

Zamontujemy katalogi (1) i (2) w kontenerze oraz uruchomimy skrypt na naszych danych:

$ singularity exec \
    --bind "~/pl0217-01/project_data/skrypty:/mnt/skrypty" \
    --bind "~/pl0217-01/scratch/dane:/mnt/dane" \
    ~/pl0217-01/project_data/kontenery/kontener.sif \
    bash /mnt/skrypty/skrypt.sh /mnt/dane/dane.fastq

Żeby było bardziej przejrzyście możemy zapisać ścieżki jako zmienne:

SKRYPTY="~/pl0217-01/project_data/skrypty/"
DANE="~/pl0217-01/scrath/dane/"
KONTENER="~/pl0217-01/project_data/kontenery/kontener.sif"

$ singularity exec \
    --bind "$SKRYPTY:/mnt/skrypty" \
    --bind "$DANE:/mnt/dane" \
    $KONTENER bash /mnt/skrypty/skrypt.sh /mnt/dane/dane.fastq

shell

Podobnie możemy uruchomić obliczenia w trybie wiersza polecenia:

SKRYPTY="~/pl0217-01/project_data/skrypty/"
DANE="~/pl0217-01/scrath/dane/"
KONTENER="~/pl0217-01/project_data/kontenery/kontener.sif"

$ singularity shell \
    --bind "$SKRYPTY:/mnt/skrypty" \
    --bind "$DANE:/mnt/dane" \
    $KONTENER
Singularity> cd /mnt/skrypty
Singularity> bash skrypt.sh /mnt/dane/dane.fastq

Uruchamianie kontenera jako daemona.

Polecenie instance pozwala uruchomić kontener w tle, co może być przydatne jeśli mamy zamiar korzystać z niego wielokrotnie.

  instance    Manage containers running as services

Available Commands:
  list        List all running and named Singularity instances
  run         Run a named instance of the given container image
  start       Start a named instance of the given container image
  stats       Get stats for a named instance
  stop        Stop a named instance of a given container image

Przykładowe zastosowanie.

Definiowanie ścieżek

Zastępuję ścieżki zmiennymi. ULR kontenerów pochodzą z biocontainers.pro

FASTQC="https://depot.galaxyproject.org/singularity/fastqc:0.12.1--hdfd78af_0"
FASTP="https://depot.galaxyproject.org/singularity/fastp:0.24.0--heae3180_1"
SKRYPTY="~/pl0217-01/project_data/skrypty/"
DANE="~/pl0217-01/scratch/dane/"

Uruchomienie daemona

Uruchamiam w tle kontener FastQC jako instancję o nazwie fastqc_instance oraz montuję katalogi ze skryptami i z danymi.

singularity instance start \
    --bind "$DANE:/mnt/dane" \
    --bind "$SKRYPTY:/mnt/skrypty" \
    $FASTQC fastqc_instance

FastQC 1

Uruchamiam skrypt wykonujący FastQC na danych:

singularity exec instance://fastqc_instance \
  bash /mnt/skrypty/fastqc.sh /mnt/dane/dane.fastq

Przycinanie odczytów

Ponieważ uruchamiam program do przycinania odczytów (fastp) tylko raz wystarcza jednorazowe uruchomienie exec.

singularity exec \
    --bind "$DANE:/mnt/dane" \
    --bind "$SKRYPTY:/mnt/skrypty" \
    $FASTP bash /mnt/skrypty/fastp.sh /mnt/dane/dane.fastq

FastQC 2

Ponowne wywołanie FastQC z aktywnej instancji:

singularity exec instance://fastqc_instance \
    bash /mnt/skrypty/fastqc_post_fastp.sh /mnt/dane/dane_trim.fastq

Zabicie daemona

Zatrzymanie instancji fastqc_instance (inaczej pozostanie uruchomiona w tle):

singularity instance stop fastqc_instance

Przykładowy pipeline.

https://github.com/MHryc/singularity_streptococcus.git

Opis analizy

pobranie genomu referencyjnego z ncbi
pobranie odczytów z SRA za pomocą prefetch i fasterq-dump z sra-tools
analiza FastQC
przycinanie adapterów oraz zasad niskiej jakości
analiza FastQC po przycinaniu
indeksowanie i mapowanie odczytów do referencji (bwa-mem2)
sortowanie i statystyki mapowania (sam-tools)

Pobranie i uruchomienie

git clone https://github.com/MHryc/singularity_streptococcus.git
cd singularity_streptococcus/ && chmod +x pipeline.sh
./pipeline.sh

Najlepiej uruchomić w trybie interaktywnym (całość zajmuje ok. 5 min).

Struktura repozytorium

.
├── LICENSE
├── pipeline.sh
├── README.md
├── resources
│   ├── adapter.fa
│   └── streptococus_ncbi.txt
├── scripts
│   ├── bwa.sh
│   ├── fastp.sh
│   ├── fastqc_post_fastp.sh
│   ├── fastqc.sh
│   ├── samtools.sh
│   └── sratools.sh
├── simseq.def
├── simseq.py
└── simseq.sif

pipeline.sh — główny skrypt, w nim wywoływane jest singularity
resources/ — zawiera sekwencje adapterów i link do genomu referencyjnego
scripts/ — zawiera skrypty uruchamiane wewnątrz kontenerów
simseq.def — plik def, z którego złożono kontener simseq.sif
simseq.py — skrypt generujący sekwencje DNA w oparciu o HMM
simseq.sif — kontener zawierający simseq.py, fortune, cowsay i lolcat

Na plikach simseq można przetestować samodzielne składanie kontenera (singularity build), definiowanie sekcji %runscript, %test, %help i %labels w pliku def, uruchamianie skryptów w kontenerze run, exec, shell, instance.

Uruchamianie oraz katalog cache.

Uruchamianie singularity

Katalog cache

Pobieranie gotowych kontenerów.

Gotowe kontenerey

pull

run, exec, shell

Sposoby uruchomienia konterów.

exec

shell

run

run-help

test

Montowanie katalogów.

Katalogi

Uruchomienie exec z montowaniem

shell

Uruchamianie kontenera jako daemona.

Definiowanie ścieżek

Uruchomienie daemona

FastQC 1

Przycinanie odczytów

FastQC 2

Zabicie daemona

Przykładowy pipeline.

Opis analizy

Pobranie i uruchomienie

Struktura repozytorium

Linki