Installation#

Requirements#

  • Python 3.11 or later

  • conda (recommended for environment management)

Environment setup#

Create the conda environment from the repository root:

conda env create -f environment.yml
conda activate sc_tools

Core install#

Install sc_tools in editable mode (core dependencies only):

pip install -e .

Optional extras#

sc_tools uses optional dependencies for heavy ML and GPU workflows. Install only what you need:

Extra

Contents

Install command

deconvolution

scvi-tools, tangram-sc

pip install -e ".[deconvolution]"

geneset

gseapy, pyucell

pip install -e ".[geneset]"

integration

harmonypy, bbknn, scanorama

pip install -e ".[integration]"

spatial

utag (spatial-aware clustering)

pip install -e ".[spatial]"

gpu

torch, rapids-singlecell

pip install -e ".[gpu]"

storage

fsspec, s3fs, sshfs, gcsfs, adlfs, zarr, ome-zarr

pip install -e ".[storage]"

storage-box

boxfs (Box storage via OAuth)

pip install -e ".[storage-box]"

registry

SQLAlchemy, Alembic (project/dataset tracking)

pip install -e ".[registry]"

mcp

Model Context Protocol servers

pip install -e ".[mcp]"

benchmark

scikit-image, scib-metrics, plotly, cellpose, stardist

pip install -e ".[benchmark]"

benchmark-extended

All of benchmark + deepcell, torch, transformers, segmentation-models-pytorch

pip install -e ".[benchmark-extended]"

viz

marsilea (publication composite figures)

pip install -e ".[viz]"

decoupler

decoupleR (TF/pathway activity)

pip install -e ".[decoupler]"

dev

pytest, ruff, igraph, leidenalg

pip install -e ".[dev]"

docs

sphinx, pydata-sphinx-theme, myst-nb

pip install -e ".[docs]"

Full pipeline install (deconvolution + geneset + integration):

pip install -e ".[deconvolution,geneset,integration]"

Container usage#

All pipeline runs are containerized. On Linux/HPC use Apptainer (primary); on macOS/Windows use Docker (fallback).

# Run a script inside the container (auto-detects Apptainer vs Docker)
./scripts/run_container.sh projects/visium/ggo_visium python scripts/foo.py

# Interactive shell
./scripts/run_container.sh projects/visium/ggo_visium

# Force Docker on any platform
SC_TOOLS_RUNTIME=docker ./scripts/run_container.sh projects/visium/ggo_visium

Build the Apptainer SIF from the Docker image:

docker build -t sc_tools:latest .
apptainer build containers/sc_tools.sif docker-daemon://sc_tools:latest

Build the documentation#

pip install -e ".[docs]"
make docs           # build HTML
make docs-open      # build and open in browser (macOS)
make docs-clean     # remove build artifacts