CellGPS is the Python package and reference implementation for Cophenetic Spatial Topology Embedding (COSTE), a spatial topology analysis framework for spatial omics data.
This repository is maintained as both the installable Python package and the code companion for the CellGPS/COSTE bioRxiv preprint.
CellGPS is maintained in the Moldia organization. This public repository is the canonical source for development and the scverse ecosystem application. See the migration guide when moving from the historical Cell-GPS distribution or the personal repository.
Moldia/CellGPS is the primary, full Python implementation. It contains all CellGPS functions and the complete reproduction code for the bioRxiv preprint. The Moldia/cellgpsr R package and the Windows files distributed in Zenodo record 19482685 provide only the core functionality; they do not include the full Python function set or the complete preprint reproduction code.
CellGPS/COSTE is described in the associated bioRxiv preprint:
Mengping Long, Taobo Hu, Alexandros Sountoulidis, Christos Samakovlis, and Mats Nilsson (2026). Cophenetic Spatial Topology Embedding reveals multiscale tissue architecture in spatial omics. bioRxiv preprint. doi:10.64898/2026.05.26.727847. Version 1 on bioRxiv.
If you use the Python package, the Windows executable, the R companion package, or the manuscript figure/table code, please cite this preprint.
The code used to generate the preprint figures and supplementary tables is organized in CellGPS manuscript/:
main_figures/: notebooks for main figure analyses.supplementary_figures/: notebooks for supplementary figure analyses.supplementary_tables/: notebooks for supplementary table analyses.
The notebooks are intentionally output-free and preserve the original manuscript data paths where those paths were required for reproduction. A detailed mapping from manuscript results to source code is available in docs/cellgps_science_manuscript_code_inventory.md.
Beyond the main CellGPS/COSTE preprint above, the manuscripts/ directory collects the analysis and figure-generation code for follow-up manuscripts that build on the COSTE method. Each subfolder is a self-contained study with its own README describing the dataset, scripts, and reproduction steps:
manuscripts/atera_urna/: Atera uRNA-COSTE study — segmentation-bias check using unassigned RNA (uRNA, transcripts not assigned to a segmented cell) and uRNA-COSTE concordance analysis.manuscripts/segmentation_free_transcript_domains/: segmentation-free spatial domain discovery from transcript points alone.
For details on any extension manuscript, read the README inside its subfolder.
- Python distribution:
CellGPS - Python import package:
cellgps - R package/repository:
cellgpsr - Windows executable:
cellgps.exe
The Python package is hosted at https://github.com/Moldia/CellGPS. The R package is hosted separately at https://github.com/Moldia/cellgpsr. The Windows files are distributed through https://zenodo.org/records/19482685.
- Computes searcher-findee distance matrices from spatial coordinates and cell labels.
- Builds cophenetic distance matrices and StructureMap heatmaps from
AnnDataobjects or plainpandastables. - Loads 10x Xenium outputs and prepares them for downstream spatial analysis.
- Provides Xenium loaders backed by
pyXenium.io, including standard Xenium folders and table bundles withcells.parquet, official*_cell_groups.csv, andcell_feature_matrix.h5. - Supports transcript-by-cell analysis for locating transcripts relative to cell types.
- Includes memory-optimized workflows for large datasets.
- Provides plotting utilities such as clustered heatmaps, circular dendrograms, and related summary figures.
src/cellgps/: recommended Python import namespace.src/cellgps/pp,src/cellgps/tl,src/cellgps/pl: scverse-style aliases for preprocessing, analysis, and plotting APIs.tests/: package tests and smoke checks.docs/: Sphinx documentation.docs/project/: project notes, changelog, authors, and reviewer guide.CellGPS manuscript/: curated preprint figure and table notebooks for the main CellGPS/COSTE bioRxiv preprint.manuscripts/: analysis code for follow-up COSTE extension manuscripts, one self-contained study per subfolder (see each subfolder's README).examples/: compact usage examples and small example data files.packaging/conda-recipe/: archived local conda recipe retained for reference.packaging/pyinstaller/: Windows executable build scripts and PyInstaller assets.
Install the current source directly from GitHub:
python -m pip install git+https://github.com/Moldia/CellGPS.gitFor local development or reviewer inspection:
git clone https://github.com/Moldia/CellGPS.git
cd CellGPS
python -m pip install -e .The package requires Python 3.9 or later.
The minimal input is a table with spatial coordinates and a cell-type column.
import pandas as pd
from cellgps import compute_cophenetic_distances_from_df, plot_cophenetic_heatmap
df = pd.DataFrame(
{
"x": [0, 1, 5, 6],
"y": [0, 1, 5, 6],
"celltype": ["A", "A", "B", "B"],
}
)
row_coph, col_coph = compute_cophenetic_distances_from_df(
df=df,
x_col="x",
y_col="y",
celltype_col="celltype",
)
plot_cophenetic_heatmap(
row_coph,
matrix_name="row_coph",
output_dir="output",
output_filename="StructureMap_example.pdf",
sample="Example",
)from cellgps import load_xenium_data, load_xenium_table_bundle, compute_cophenetic_distances_from_adata
# Standard Xenium folder through pyXenium.io
adata = load_xenium_data("/path/to/xenium/run", normalize=False)
# Explicit table-bundle route used for the Atera Xenium benchmark
adata = load_xenium_table_bundle("/path/to/xenium/run", normalize=False)
row_coph, col_coph = compute_cophenetic_distances_from_adata(
adata,
cluster_col="Cluster",
output_dir="output",
)load_xenium_data: load and preprocess Xenium data.load_xenium_table_bundle: load Xenium data fromcells.parquet+*_cell_groups.csv+cell_feature_matrix.h5throughpyXenium.io.compute_cophenetic_distances_from_df: compute structure matrices from a coordinate table.compute_weighted_searcher_findee_distance_matrix_from_df: weighted searcher-findee kernel for entity, pathway, or LR analysis.compute_weighted_cophenetic_distances_from_df: weighted StructureMap wrapper over the weighted kernel.compute_cophenetic_distances_from_adata: compute structure matrices fromAnnData.compute_entity_to_cell_topology: generalizet_and_cfrom transcripts to arbitrary weighted entities.compute_entity_structuremap: build StructureMap-style topology among arbitrary weighted entities.plot_cophenetic_heatmap: generate StructureMap and related clustered heatmaps.transcript_by_cell_analysis: analyze transcript-to-cell spatial structure at scale.ligand_receptor_topology_analysis: score sender->receiver ligand-receptor candidates using topology, structure compatibility, and local contact.ligand_receptor_target_consistency: add a NicheNet-style downstream target-consistency layer.compute_pathway_activity_matrix: compute rank-based or weighted pathway activities per cell.pathway_topology_analysis: analyze pathway-to-cell and pathway-to-pathway spatial topology.compute_cophenetic_distances_from_df_memory_opt: memory-aware alternative for large tables.plot_circular_dendrogram_pycirclize: circular dendrogram visualization.
The manuscript-validated scope is the COSTE/SSS workflow and the figure/table analyses mapped in CellGPS manuscript/ and docs/cellgps_science_manuscript_code_inventory.md. Ligand-receptor topology, pathway topology, Visium helpers, GUI entry points and other convenience APIs are included for reuse and development, but should be treated as optional or exploratory unless a manuscript notebook or documentation page explicitly maps them to a reported analysis.
- The curated figure and table notebooks for the bioRxiv preprint are kept in
CellGPS manuscript/. - Raw experimental datasets are not bundled in this repository because of size and distribution constraints. The code expects standard spatial omics outputs such as Xenium folders or tabular coordinate inputs.
- When a
cellgps_tbc_formal_wta/results-style directory is already available, the LR and pathway topology extensions are designed to reuse itst_and_c_result_*.csvandStructureMap_table_*.csvoutputs as the preferred gene-level topology anchors before falling back to recomputation. - Xenium loading depends on
pyXenium>=0.4.3. Visium helpers remain optional through the separateCellGPS[visium]extra. - A short repository walkthrough is available in docs/project/REVIEWER_GUIDE.md.
Sphinx documentation sources are available in docs/. The manuscript-focused pages introduce the bioRxiv preprint, explain how to use the curated figure/table notebooks, and map each figure and supplementary table to its GitHub code location.
If you use CellGPS or reuse the manuscript analysis code, please cite:
Mengping Long, Taobo Hu, Alexandros Sountoulidis, Christos Samakovlis, and Mats Nilsson (2026). Cophenetic Spatial Topology Embedding reveals multiscale tissue architecture in spatial omics. bioRxiv preprint. doi:10.64898/2026.05.26.727847. Version 1 on bioRxiv.
@article{long2026cellgps,
title = {Cophenetic Spatial Topology Embedding reveals multiscale tissue architecture in spatial omics},
author = {Long, Mengping and Hu, Taobo and Sountoulidis, Alexandros and Samakovlis, Christos and Nilsson, Mats},
journal = {bioRxiv},
year = {2026},
doi = {10.64898/2026.05.26.727847},
url = {https://www.biorxiv.org/content/10.64898/2026.05.26.727847v1}
}This project is released under the MIT License. See LICENSE.