Snakemake

Snakemake is a workflow manager widely used in bioinformatics. A workflow is described as a set of rules in a Snakefile, and Snakemake runs only the steps whose outputs are missing or out of date.

On the cluster, you can run Snakemake in two ways:

Mode	Best for
Inside one job	Small and medium workflows that fit on one node.
Submitting jobs to PBS	Large workflows, where each rule runs as a separate PBS job.

Everything on this page is installed and configured in your own home or project directory.

Installation

Install Snakemake into its own Conda environment, together with the plugin for submitting jobs to a cluster:

source ${HOME}/miniforge3/etc/profile.d/conda.sh
conda create -n snakemake -c conda-forge -c bioconda \
    snakemake snakemake-executor-plugin-cluster-generic
conda activate snakemake
snakemake --version

Tip

Keep Snakemake in its own environment and let Snakemake create the environments for the individual rules with --use-conda. Mixing the tools of your workflow into the Snakemake environment often leads to dependency conflicts.

Example Workflow

The following Snakefile counts lines in several input files and summarizes the results. Each rule declares the threads, memory and runtime it needs.

SAMPLES = ["a", "b", "c"]

rule all:
    input:
        "results/summary.txt"

rule count:
    input:
        "data/{sample}.txt"
    output:
        "results/{sample}.count"
    threads: 2
    resources:
        mem_mb=2000,
        walltime="00:30:00"
    shell:
        "wc -l < {input} > {output}"

rule summary:
    input:
        expand("results/{sample}.count", sample=SAMPLES)
    output:
        "results/summary.txt"
    shell:
        "cat {input} > {output}"

Always test a workflow with a dry run first, it shows which jobs would be run without running them:

snakemake -n

Running Inside One Job

The simplest way is to run the whole workflow inside a single PBS job. Snakemake then runs as many rules in parallel as fit into the CPUs of the job.

#!/bin/bash
#PBS -N snakemake
#PBS -l select=1:ncpus=32:mem=64gb
#PBS -l walltime=24:00:00
#PBS -j oe

cd ${PBS_O_WORKDIR}

source ${HOME}/miniforge3/etc/profile.d/conda.sh
conda activate snakemake

snakemake --cores ${NCPUS} --resources mem_mb=60000 --use-conda --rerun-incomplete

The --resources mem_mb value limits the total memory used by rules running at the same time. Keep it a little below the memory requested by the job.

Submitting Rules as Jobs

For large workflows, Snakemake can submit every rule as a separate PBS job. Snakemake itself only plans and submits jobs, so it can run on the login node inside Tmux, which keeps it running after you disconnect.

Tip

qsub also works on compute nodes, so instead of tmux you can run Snakemake itself in a small job with 1 CPU and a long walltime.

Store the cluster settings in a profile ~/.config/snakemake/pbs/config.yaml:

executor: cluster-generic
cluster-generic-submit-cmd: >-
  qsub -N smk.{rule}
  -l select=1:ncpus={threads}:mem={resources.mem_mb}mb
  -l walltime={resources.walltime}
  -j oe -o logs/pbs/
cluster-generic-cancel-cmd: qdel
jobs: 50
latency-wait: 60
rerun-incomplete: true
use-conda: true
default-resources:
  - mem_mb=2000
  - walltime="'01:00:00'"

Then run the workflow with this profile:

mkdir -p logs/pbs
tmux new -s smk
conda activate snakemake
snakemake --workflow-profile none --profile pbs

Option	Meaning
jobs	Maximum number of PBS jobs submitted at the same time.
latency-wait	How many seconds to wait for output files to appear on shared storage.
default-resources	Resources of rules that do not set their own.

Warning

Every rule becomes a separate job, which waits in the queue. Do not submit thousands of very short rules this way. Group short rules with the group directive, or run the workflow inside one job instead.

Note

Conda environments of rules are created in .snakemake/conda in the workflow directory. Create them before submitting with snakemake --use-conda --conda-create-envs-only, so the first jobs do not all install the same packages.