cellgpsr

cellgpsr is the R companion package for CellGPS spatial topology analysis in spatial transcriptomics data. It provides lightweight R implementations for computing cluster-level cophenetic structure matrices, generating StructureMap-style heatmaps, and analyzing transcript-to-cell spatial relationships.

This repository is maintained as a reviewer-friendly code companion for the associated manuscript.

Implementation availability

Moldia/CellGPS is the primary, full Python implementation. It contains all CellGPS functions and the complete code needed to reproduce the analyses in the associated bioRxiv preprint. The Moldia/cellgpsr R package and the Windows files archived at Zenodo record 19482685 provide only the core CellGPS functionality.

Main features

• Compute nearest-neighbor distance summaries between spatial clusters.
• Derive row-wise and column-wise cophenetic distance matrices from coordinate tables.
• Generate publication-style heatmaps for StructureMap and related outputs.
• Run transcript-by-cell analysis from cell metadata and transcript coordinates.
• Provide repository-level example scripts under inst/example/ for manuscript-oriented analyses. These examples require user-supplied public or local dataset paths and are not installed as part of the R package build.
• Launch an interactive Shiny application for exploratory use.

Repository layout

• R/: package source code.
• man/: package manual pages.
• inst/example/: example analysis scripts.
• DESCRIPTION: package metadata and dependencies.

Installation

Install from GitHub with remotes:

install.packages("remotes")
remotes::install_github("Moldia/cellgpsr")

Or install from a local clone:

install.packages("devtools")
devtools::install("path/to/cellgpsr")

The package targets R 4.3 or later.

Minimal example

library(cellgpsr)

df <- data.frame(
  x = c(0, 1, 5, 6),
  y = c(0, 1, 5, 6),
  Cluster = c("A", "A", "B", "B")
)

result <- compute_cophenetic_distances_from_df(
  df = df,
  cluster_col = "Cluster",
  x_col = "x",
  y_col = "y"
)

plot_cophenetic_heatmap(
  matrix = result$row_cophenetic_df,
  matrix_name = "row_coph",
  sample = "Example",
  output_dir = "output"
)

Core exported functions

• compute_cluster_average_nn_distance_matrix
• compute_cluster_nn_distance_df
• compute_cophenetic_distances_from_df
• plot_cophenetic_heatmap
• transcript_by_cell_analysis

Notes for reviewers

• The main reviewer-facing code is in R/.
• Example scripts used during analysis development are available under inst/example/.
• Large local database artifacts are not part of the repository history and are intentionally ignored.
• A short repository walkthrough is available in REVIEWER_GUIDE.md.

Citation

If you use this repository, please cite 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. https://doi.org/10.64898/2026.05.26.727847. bioRxiv preprint v1.

License

This project is distributed under the MIT License.