Skip to content

About

GPU-accelerated Python pipeline for image-based spatial omics, built on Sopa and SpatialData

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Documentation Status Python 3.12 Built with Pixi Commit activity GitHub

Overview

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).

cluster hex map cluster profiles

Documentation

Full documentation is available at cell-survey.readthedocs.io — installation, a pipeline walkthrough, every parameter, the outputs reference, the visualisation guide, and an FAQ.

Installation

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 (recommended)

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 | bash

From the repository root:

pixi install

That'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

docker build -t cellsurvey .
docker run --gpus all -v /path/to/data:/data cellsurvey -i /data/input.tiff -o /data/output -p /data/plots

Usage

Basic Usage

pixi run python run.py -i <path_to_input_file> -o <path_to_output_zarr> -p <path_to_output_plots_directory>

Parameters

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 (.zarr appended automatically).
  • -p, --plot_dir: Directory where output plots are saved.

Full Example

pixi run python run.py -i ~/data/sample.tiff -o ~/results/output -p ~/results/plots/

Stability sweep

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 1000

Or sweep the k-means k (defaults to 5,8,10,12,15,20):

pixi run python -m cellsurvey.stability \
  --zarr <output>_seg.zarr \
  --mode clusters

Each writes per-cell labels (plus a summary CSV with the community count, or the k-means inertia) and leaves the Zarr untouched.

Visualising Results

For the full visualisation guide — Odon (recommended), QuPath, TissUUmaps, and napari + napari-spatialdata, with performance notes — see the Visualising results page.

About

GPU-accelerated Python pipeline for image-based spatial omics, built on Sopa and SpatialData

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Used by

Contributors

Languages