goatpy — Spatial Glycomics Analysis Toolkit

goatpy is a Python toolkit for spatial glycomics analysis, combining MALDI mass spectrometry imaging with H&E histology. It provides automatic image registration, pseudo-image generation, spatial PCA, and annotation tools built on top of the SpatialData framework.

Features

• Automatic H&E registration — align MALDI ion images to whole-slide H&E images using normalised cross-correlation with full 360° rotation search
• QuPath annotation support — transform GeoJSON annotations from QuPath into the registered coordinate system
• Spatial GraphPCA — dimensionality reduction with optional spatial smoothing via k-nearest-neighbour graphs
• Pseudo-image generation — create spatial images from categorical or continuous obs columns
• Landmark alignment GUI — interactive napari-based landmark alignment tool
• SpatialData native — all outputs are standard SpatialData objects, compatible with the scverse ecosystem

Installation

Recommended: conda environment

Download environment.yml and create the environment:

conda env create -f environment.yml
conda activate maldi
pip install goatpy

PyPI

pip install goatpy

For napari visualisation support:

pip install "goatpy[napari]"

From source

pip install git+https://github.com/agc888/goatpy.git

Quick start

import goatpy as gp

# Load and register MALDI + H&E
sdata = gp.load_and_align(
    imzml_path="my_sample.imzML",
    he_path="my_sample.svs",
    geojson_path="annotations.geojson",  # optional QuPath annotations
)

# Normalise intensities
sdata = gp.normalize_spatialdata(sdata, table_name="maldi_adata", method="TIC")

# Dimensionality reduction
sdata = gp.graphpca_spatialdata(sdata, n_components=30, alpha=0.5)

# Cluster
sdata = gp.get_kmean_clusters(sdata, n_clusters=8)

# Visualise in napari
from napari_spatialdata import Interactive
Interactive([sdata]).run()

Documentation

Full documentation is available at goatpy.readthedocs.io.

Citation

If you use goatpy in your research, please cite:

Causer, A. (2025). goatpy: Spatial Glycomics Analysis Toolkit. https://github.com/agc888/goatpy

License

MIT — see LICENSE for details.