Installation

spatiomic only supports Python versions greater than or equal to 3.10. Currently, not all optional dependencies are available for Python 3.13. For the best experience, please use Python 3.10, 3.11 or 3.12 (recommended).

Recommendation

For the best GPU-accelerated experience (optional), a CUDA-compatible GPU and installation of the cupy, cuml, cugraph and cucim packages is necessary. Please consult the RAPIDS.AI installation guide for further information.

Installation Options

Choose an option to install this package.

Install spatiomic package using pip:

python3 -m pip install spatiomic

# optionally, for GPU acceleration with CUDA 12
python3 -m pip install cupy-cuda12x
python3 -m pip install \
    --extra-index-url=https://pypi.nvidia.com \
    "cuml-cu12==25.2.*" "cugraph-cu12==25.2.*" "nx-cugraph-cu12==25.2.*" \
    "cucim-cu12==25.2.*"

# optionally, for GPU acceleration with CUDA 11
python3 -m pip install cupy-cuda11x
python3 -m pip install \
    --extra-index-url=https://pypi.nvidia.com \
    "cuml-cu11==25.2.*" "cugraph-cu11==25.2.*" "nx-cugraph-cu11==25.2.*" \
    "cucim-cu11==25.2.*"

Install spatiomic from GitHub using pip:

python3 -m pip install [email protected]:complextissue/spatiomic.git

Install spatiomic from source:

# Clone repo
git clone --depth 1 https://github.com/complextissue/spatiomic.git
cd spatiomic
make install
Additional packages for GPU support

These packages are not required for spatiomic to work but may speed certain operations up significantly.

  • cupy for faster pre-/postprocessing and faster SOM calculations on the GPU.

  • cuml for GPU-based AgglomerativeClustering, KMeans, UMAP, TSNE and PCA calculation.

  • cucim for GPU-based phase_cross_correlation.

spatiomic will always try to perform heavy calculations on the GPU. However, for this to work, a CUDA-enabled system with cupy and the RAPIDS package cuml is required and have to be installed beforehand. If these packages are not available, spatiomic will default to CPU-based packages such as numpy and sklearn.

Note that cupy and cucim can be installed with the [gpu] flag when installing via pip. cuml however is not available as a PyPi package and thus has to be installed by the user of this package, for example with the provided Dockerfile.