launchcontainers

launchcontainers is an open-source Python framework for running neuroimaging analysis pipelines on high-performance computing (HPC) clusters in a reproducible, BIDS-compliant way. It was developed at the Basque Center on Cognition, Brain and Language (BCBL) - LMC Group to address the practical challenges of managing large multi-subject, multi-session neuroimaging datasets across heterogeneous computing environments.

The framework wraps complex container-based and Python-based pipelines — from DWI preprocessing and tractography to fMRI first-level GLM and population receptive field (PRF) analysis — behind a single, consistent command-line interface. Rather than requiring researchers to manually track config files, input paths, and job scripts for dozens of subjects, launchcontainers handles all of that automatically: it validates inputs before any job is submitted, freezes a snapshot of every config used, and generates ready-to-submit HPC scripts tailored to your cluster’s scheduler.

A key design principle is that the analysis directory produced at the prepare stage is fully self-contained. Every run is fully traceable — you can always inspect exactly which config, which software version, and which subject list was used to produce a given result. Quality control is built into the workflow as a first-class step, generating per-subject pass/fail reports and a failed_subseslist.tsv that feeds directly back into the next prepare cycle with no manual editing required.

---

Key features

🔁	Three-phase workflow — prepare → run → qc keeps validation, execution, and quality control cleanly separated; each phase reads only from the self-contained analysis directory, never from your original config files.
📦	Container and analysis pipelines — supports six DWI/structural Apptainer containers (anatrois, freesurferator, rtppreproc, rtp-pipeline, rtp2-preproc, rtp2-pipeline, fMRIPrep) and fMRI analysis types (glm, prf) through an extensible registry.
🖥️	Multi-cluster support — works with SLURM (DIPC), SGE (BCBL), and local execution out of the box; adding a new host requires only one config block.
🔒	Reproducibility by design — configs, subject lists, and software versions are frozen into the analysis directory at prepare time, making every result fully auditable.
✅	Built-in QC — outputs are validated after every run; failures are reported and exported as a ready-to-resubmit subject list.
🧩	Extensible — adding a new analysis type requires only a subclass and one line in the registry; no existing code needs to change.

---

Installation

For users — install the latest release from PyPI:

pip install launchcontainers

For developers — clone the repo and install with Poetry:

pip install pipx && pipx install poetry
git clone https://github.com/garikoitz/launchcontainers.git
cd launchcontainers
poetry env use python3 && poetry install
poetry shell

See the Installation page for full requirements, verification steps, and instructions for building the documentation locally.

---

How to cite

If you use launchcontainers in your research, please cite:

Lerma-Usabiaga, G., Lei, Y., Liu, M., Lecca, L., Linhardt, D.,
Tellaetxe, I., & others (2023). launchcontainers: a Python framework
for reproducible neuroimaging pipeline execution on HPC clusters.
[Software]. https://github.com/garikoitz/launchcontainers

---