prism-oncology /sopa
Technology-invariant pipeline for spatial omics analysis that scales to millions of cells (Xenium / Visium HD / MERSCOPE / CosMx / PhenoCycler / MACSima / etc.)
★ 299⑂ 53👁 9⑃ 134● 319▤ 48
+0
Daily
299
stars
53
forks
9
watchers
134
prs
319
issues
48
releases
README
Spatial omics pipeline and analysis
!Build
Built on top of SpatialData, Sopa enables processing and analyses of spatial omics data with single-cell resolution (spatial transcriptomics or multiplex imaging data) using a standard data structure and output. We currently support the following technologies: Xenium, Visium HD, MERSCOPE, CosMx, PhenoCycler, MACSima, Molecular Cartography, and others. Sopa was designed for generability and low memory consumption on large images (scales to 1TB+ images).
[!NOTE]
You may also be interested in Novae, developed by the same authors, now published in Nature Methods 🎉
Documentation
Check Sopa's documentation to get started. It contains installation explanations, CLI/API details, and tutorials.
Overview
The following illustration describes the main steps of sopa:
Installation
Sopa can be installed from PyPI on all OS, for any Python version =3.12. On a new environment, run the following command:
sh
pip install sopa
[!NOTE]
See this installation section for more details about extras and other installations modes.
Usage modes
Sopa comes in four different flavours, each corresponding to a different use case:
- API: use directly sopa as a Python package for complete flexibility and customization (example below).
- nf-core/sopa: run Sopa with Nextflow (see this repo and the corresponding usage guide).
- Snakemake pipeline: choose a config, and run our pipeline on your spatial data in a couple of minutes (deprecated in favor of nf-core/sopa, see the public archive here).
- CLI: use our command-line-interface for prototyping quickly your own pipeline (advanced users).
API usage
Below is a minimal example of API usage. For a complete API description, please refer to the documentation.
python
import sopa
sdata = sopa.io.xenium("path/to/data") reading Xenium data
sopa.make_image_patches(sdata) creating overlapping patches
sopa.segmentation.cellpose(sdata, "DAPI", diameter=30) running cellpose segmentation
sopa.aggregate(sdata) counting the transcripts inside the cells
Cite us
Our article is published in Nature Communications. You can cite Sopa as below:
txt
Blampey, Q., Mulder, K., Gardet, M. et al. Sopa: a technology-invariant pipeline for analyses of image-based spatial omics.
Nat Commun 15, 4981 (2024). https://doi.org/10.1038/s41467-024-48981-zTop issues
#123[Bug] Isse with running Baysor segmentation on some but not all patches27 comments · 2024-09-12#292[Bug]ComSeg segmentation infinite loop19 comments · 2025-08-14#431Support segger as a segmentation method17 comments · 2026-06-24#256[Bug] Issue with dask segmentation on Windows11 comments · 2025-05-13#299Cell ID mismatch when using proseg10 comments · 2025-08-27#213Reading a slide image while retaining channel data?8 comments · 2025-02-17#117[Bug]"Could not find element with name ['cell_circles']"7 comments · 2024-09-02#440[Proposal / Discussion] Bridging Image Preprocessing (MCMICRO) & TMA Multi-Core Aggregation into SOPA6 comments · 2026-08-03
Discussions
#343Good first issues0 comments · 2025-10-28#298allow in the snakelike implementation tuning multiple cellulose segmentation task and combining them1 comments · 2025-08-25#244Sopa webinar0 comments · 2025-04-23#220Channels for Cellpose1 comments · 2025-03-06#217Xenium explorer ome.tif format1 comments · 2025-02-21#138Migration guide to `sopa>=2.0.0`0 comments · 2024-10-15#36Cell segmentation parallelization4 comments · 2024-03-21#28Questions and answers0 comments · 2024-02-16
Latest release
v2.3.0 v2.3.0 2026-11-04This version includes several deprecations, detailed below. This aligns with the current scope of Sopa, i.e., mainly maintaining (1) the API and (2) the Nextflow pipeline. Added Enable GPU usage for InstanSeg by @quentinblampey in https://github.com/prism-oncology/sopa/pull/461 Changes Deprecate the snakemake pipeline by @quentinblampey in https://github.com/prism-oncology/sopa/pull/458 - we now recommend using nf-core/sopa instead. The snakemake workflow was archived here. Remove support for python 3.11 by @quentinblampey in https://github.com/prism-oncology/sopa/pull/460 in fav