Singularity / Apptainer

Overview

Apptainer (formerly Singularity) is a container runtime designed for HPC clusters and multi-user systems. With a single SIF file (Singularity Image Format), you can run the full OpenSWATH workflow—including OpenMS tools, PyProphet, TRIC (feature_alignment.py), DIAlignR, EasyPQP, SAGE, ARYCAL, mapDIA, and Percolator—without installing any dependencies.

This page shows three easy ways to obtain the OpenSWATH image:

Option A (recommended): Download a prebuilt .sif from the GitHub Release assets.
Option B: Pull directly from the OpenSWATH Docker image on GHCR and let Apptainer convert it to SIF locally.
Option C: Pull the prebuilt SIF as an OCI artifact from GHCR using ORAS transport (Apptainer ≥ 1.3).

Installing Apptainer

Follow the instructions for your platform: Install Apptainer. On HPC systems, Apptainer is often already installed (e.g., as a module). Ask your system administrator if unsure.

Obtaining the Image

Option A — Download from Release assets

Go to the OpenSWATH **GitHub Docker Releases** page and download the SIF artifact (e.g., openswath-v0.3.0.sif or openswath-latest.sif).
Put it somewhere convenient, e.g. your home directory.

Option B — Convert the Docker image to SIF locally

Apptainer can convert a public Docker/OCI image to a SIF locally (no root/admin needed):

# Pull & convert latest image from GitHub Container Registry (GHCR)

apptainer pull openswath-latest.sif
docker://ghcr.io/openswath/openswath:latest

# Or pull a specific release tag

apptainer pull openswath-v0.3.0.sif
docker://ghcr.io/openswath/openswath:v0.3.0

Option C — Pull a prebuilt SIF via ORAS (OCI artifact on GHCR)

If you’re using Apptainer ≥ 1.3, you can pull a prebuilt SIF directly via ORAS transport:

# From GHCR SIF repository (public)
apptainer pull openswath-v0.3.0.sif \
    oras://ghcr.io/openswath/openswath-sif:v0.3.0

# Or the "latest" alias (if provided)
apptainer pull openswath-latest.sif \
    oras://ghcr.io/openswath/openswath-sif:latest

Running OpenSWATH with Apptainer

Open a terminal (or your HPC login shell) and bind a host directory (e.g. ~/Desktop) into the container as /data:

# Start an interactive shell inside the container
apptainer shell --bind ~/Desktop:/data openswath-latest.sif

Inside the shell, all tools are available on $PATH:

# OpenMS
OpenSwathWorkflow --help

# PyProphet
pyprophet --help

# TRIC
feature_alignment.py --help

# DIAlignR
alignTargetedRuns --help

# ARYCAL
arycal --help

# EasyPQP
easypqp --help

# SAGE
sage --help

# Percolator
percolator --help

You can also run single commands without entering a shell:

apptainer exec --bind ~/Desktop:/data openswath-latest.sif \
    OpenSwathWorkflow --help

Processing Example

Assuming your input files are in ~/Desktop and you want outputs written there as well:

apptainer exec --bind ~/Desktop:/data openswath-latest.sif \
  OpenSwathWorkflow \
    -in /data/data.mzML \
    -tr /data/library.pqp \
    -tr_irt /data/iRT_assays.TraML \
    -swath_windows_file /data/SWATHwindows_analysis.tsv \
    -sort_swath_maps -batchSize 1000 \
    -readOptions cacheWorkingInMemory -tempDirectory /tmp/ \
    -enable_ms1 true \
    -mz_extraction_window 50 -ppm \
    -mz_correction_function quadratic_regression_delta_ppm \
    -TransitionGroupPicker:background_subtraction original \
    -RTNormalization:alignmentMethod linear \
    -Scoring:stop_report_after_feature 5 \
    -out_features /data/osw_output.osw

Note

Replace paths under /data/ with your actual filenames on the host.
You can bind multiple directories using -B /host/dir1:/container/dir1,/host/dir2:/container/dir2.
The SIF is read-only; write outputs to a bound host directory like /data.

Updating the Image

If you used Option A: Download the new SIF from the latest Release assets and replace your local file.
If you used Option B: Re-run apptainer pull with the desired tag (e.g., latest or a specific version).
If you used Option C: Re-run the oras:// pull for the updated tag.

Troubleshooting

Command not found: Make sure you’re using apptainer exec <sif> <command> or have started apptainer shell.
Permission issues on HPC: Apptainer is unprivileged, but some clusters require module loading (e.g., module load apptainer). Check with your admin.
Cannot write files: Ensure you used --bind <hostdir>:/data and write results to /data in the container.

Software version information

For image contents and version pins, see the OpenSWATH Docker/Apptainer repository. The **GitHub Docker Releases** page lists the corresponding SIF assets.