Skip to content

Getting Started

Installing Sopa

Sopa can be installed on every OS with pip, from python>=3.10 to python<3.13.

Advice (optional)

We advise creating a new environment via a package manager (except if you use Poetry, which will automatically create the environment).

For instance, you can create a new conda environment:

conda create --name sopa python=3.10
conda activate sopa

Choose one of the following, depending on your needs:

pip install sopa

git clone https://github.com/gustaveroussy/sopa.git
cd sopa

# no extra
pip install  -e .

# or, to install extras, among cellpose/baysor/stardist/wsi:
pip install -e '.[cellpose,baysor]'

git clone https://github.com/gustaveroussy/sopa.git
cd sopa

uv sync --all-extras --dev

Extra dependencies

Dependending on the segmentation tool that you use, you'll need extras, as detailed in the next section.

Extra dependencies

By default, sopa only install the minimal dependencies to avoid a heavy installation. Depending on your usage, you can install some extras. The available extras are listed below.

If you need to run Cellpose, you can use the corresponding extra:

pip install 'sopa[cellpose]'

# you can also combine extras: pip install 'sopa[cellpose,baysor,wsi,stardist]'

To use Baysor, you'll first need to install Sopa with the baysor extra:

pip install 'sopa[baysor]'

Important: then, you also have to install the baysor command line as detailed in the official documentation.

Executable path

If the Baysor executable is not at ~/.julia/bin/baysor, please make the baysor command available (e.g., via creating a symlink ~/.local/bin/baysor pointing to the executable), or export the path to the executable via export baysor=/path/to/baysor/executable.

Proseg has to be installed independently, this can be done with cargo:

cargo install proseg

Executable path

If the proseg executable is not at ~/.cargo/bin/proseg, please make the proseg command available (e.g., via creating a symlink ~/.local/bin/proseg pointing to the executable), or export the path to the executable via export proseg=/path/to/proseg/executable.

If you need to run Stardist, you can install the corresponding extra:

pip install 'sopa[stardist]'

If you need to run Comseg, you can install it via pip:

pip install comseg

If you need to work on whole slide images / H&E images, you can install the corresponding extras as below. You can also consider the stardist extra, if you want to run cell segmentation on the H&E image.

pip install 'sopa[wsi]'

Snakemake setup

If you plan to use Snakemake, in addition to the above sopa environment, you'll need to clone the sopa repository containing the Snakemake workflow:

git clone https://github.com/gustaveroussy/sopa.git
cd sopa   # move inside the sopa repository

Also, make sure you have installed snakemake>=8.0.0. This does not necessarily have to be inside the sopa environment — for instance, you can create a new environment specific to snakemake:

# this will create a new environment called "snakemake"
conda create -c conda-forge -c bioconda -n snakemake snakemake
conda activate snakemake

Now, follow our snakemake tutorial to run your first pipeline.

Usage

Sopa comes in three different flavours, each corresponding to a different use case:

  • API: use directly sopa as a Python package for full flexibility and customization (see a tutorial here)
  • Snakemake pipeline: choose a config, and run our pipeline on your spatial data in a few minutes. See our snakemake tutorial.
  • CLI: use our command-line-interface to prototype quickly your own pipeline