CellSurvey is a Python pipeline for image-based spatial biology/omics analysis built on Sopa. It processes multichannel microscopy images (OME-TIFF) into spatial data objects, segments nuclei with Stardist, detects RNA spots via blob detection, clusters cells with k-means, builds Delaunay networks via scipy, detects Louvain communities via networkx, and exports GeoJSON for QuPath visualization.
- 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).
Full documentation is available at cell-survey.readthedocs.io — installation, a pipeline walkthrough, every parameter, the outputs reference, the visualisation guide, and an FAQ.
CellSurvey uses pixi for environment management targeting Linux (64-bit) with GPU support.
Note
CellSurvey depends on TensorFlow and while TensorFlow will run on all operating systems, support for GPU processing is generally only supported on Linux , see here for more information. Windows and macOS are not supported via pixi.
Pixi manages the full environment including Python, CUDA, cuDNN, and all Python packages in a single command.
First, install pixi if you haven't already:
curl -fsSL https://pixi.sh/install.sh | bashFrom the repository root:
pixi installThat's it , pixi reads pixi.toml and sets up everything. To run:
pixi run python run.py -i <input_tiff> -o <output_zarr> -p <plot_dir>docker build -t cellsurvey .
docker run --gpus all -v /path/to/data:/data cellsurvey -i /data/input.tiff -o /data/output -p /data/plotspixi run python run.py -i <path_to_input_file> -o <path_to_output_zarr> -p <path_to_output_plots_directory>A full reference of every flag, with tuning guidance, is in the Parameters page. The three required arguments are:
-i,--input_file: Path to the input multichannel TIFF image (OME-TIFF recommended).-o,--output_file: Path for the output Zarr (.zarrappended automatically).-p,--plot_dir: Directory where output plots are saved.
pixi run python run.py -i ~/data/sample.tiff -o ~/results/output -p ~/results/plots/To explore how clustering responds to its parameters without re-running the expensive segmentation, use the read-only sweep over an existing segmented Zarr. Results are written to CSVs in the same directory as the Zarr.
Sweep the Louvain resolution (and Delaunay edge distance) for communities:
pixi run python -m cellsurvey.stability \
--zarr <output>_seg.zarr \
--resolutions 0.1,0.05,0.02,0.01 \
--max-edge-distances 1000Or sweep the k-means k (defaults to 5,8,10,12,15,20):
pixi run python -m cellsurvey.stability \
--zarr <output>_seg.zarr \
--mode clustersEach writes per-cell labels (plus a summary CSV with the community count, or the k-means inertia) and leaves the Zarr untouched.
For the full visualisation guide — Odon (recommended), QuPath, TissUUmaps, and napari + napari-spatialdata, with performance notes — see the Visualising results page.

