{"id":50653381,"url":"https://github.com/hutaobo/cell-gps","last_synced_at":"2026-06-07T22:03:38.522Z","repository":{"id":355433621,"uuid":"912116015","full_name":"hutaobo/Cell-GPS","owner":"hutaobo","description":"Cell-GPS is the Python package and reference implementation for Cophenetic Spatial Topology Embedding (COSTE), a spatial topology analysis framework for spatial omics data.","archived":false,"fork":false,"pushed_at":"2026-06-03T07:41:42.000Z","size":3820,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-03T09:23:03.658Z","etag":null,"topics":["bioinformatics","data-visualization","python","scanpy","single-cell","spatial-analysis","spatial-omics","spatial-transcriptomics","visium","xenium"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/Cell-GPS/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hutaobo.png","metadata":{"files":{"readme":"README.md","changelog":"HISTORY.rst","contributing":"CONTRIBUTING.rst","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.rst","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.rst","dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-01-04T16:42:14.000Z","updated_at":"2026-06-03T07:41:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hutaobo/Cell-GPS","commit_stats":null,"previous_names":["hutaobo/sfplot","hutaobo/cell-gps"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/hutaobo/Cell-GPS","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hutaobo%2FCell-GPS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hutaobo%2FCell-GPS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hutaobo%2FCell-GPS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hutaobo%2FCell-GPS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hutaobo","download_url":"https://codeload.github.com/hutaobo/Cell-GPS/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hutaobo%2FCell-GPS/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34039496,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-07T02:00:07.652Z","response_time":124,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bioinformatics","data-visualization","python","scanpy","single-cell","spatial-analysis","spatial-omics","spatial-transcriptomics","visium","xenium"],"created_at":"2026-06-07T22:03:37.412Z","updated_at":"2026-06-07T22:03:38.515Z","avatar_url":"https://github.com/hutaobo.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cell-GPS\n\n[![PyPI version](https://img.shields.io/pypi/v/Cell-GPS.svg)](https://pypi.org/project/Cell-GPS/)\n[![Documentation Status](https://readthedocs.org/projects/cell-gps/badge/?version=latest)](https://cell-gps.readthedocs.io/en/latest/?badge=latest)\n[![Conda Version](https://img.shields.io/conda/vn/conda-forge/cell-gps.svg)](https://anaconda.org/conda-forge/cell-gps)\n[![Python versions](https://img.shields.io/pypi/pyversions/Cell-GPS.svg)](https://pypi.org/project/Cell-GPS/)\n[![License](https://img.shields.io/pypi/l/Cell-GPS.svg)](LICENSE)\n[![Upload Python Package](https://github.com/hutaobo/Cell-GPS/actions/workflows/python-publish.yml/badge.svg)](https://github.com/hutaobo/Cell-GPS/actions/workflows/python-publish.yml)\n\n`Cell-GPS` is the Python package and reference implementation for Cophenetic Spatial Topology Embedding (COSTE), a spatial topology analysis framework for spatial omics data.\n\nThis repository is maintained as both the installable Python package and the code companion for the Cell-GPS/COSTE bioRxiv preprint.\n\n## Preprint and manuscript code\n\nCell-GPS/COSTE is described in the associated bioRxiv preprint:\n\n\u003e Long M, Hu T, Sountoulidis A, Samakovlis C, Nilsson M. Cophenetic Spatial Topology Embedding reveals multiscale tissue architecture in spatial omics. bioRxiv. 2026. doi: [10.64898/2026.05.26.727847](https://doi.org/10.64898/2026.05.26.727847)\n\nVersioned bioRxiv page: \u003chttps://www.biorxiv.org/content/10.64898/2026.05.26.727847v1\u003e\n\nIf you use the Python package, the Windows executable, the R companion package, or the manuscript figure/table code, please cite this preprint.\n\nThe code used to generate the preprint figures and supplementary tables is organized in [`Cell-GPS manuscript code/`](https://github.com/hutaobo/Cell-GPS/tree/main/Cell-GPS%20manuscript%20code):\n\n- [`main_figures/`](https://github.com/hutaobo/Cell-GPS/tree/main/Cell-GPS%20manuscript%20code/main_figures): notebooks for main figure analyses.\n- [`supplementary_figures/`](https://github.com/hutaobo/Cell-GPS/tree/main/Cell-GPS%20manuscript%20code/supplementary_figures): notebooks for supplementary figure analyses.\n- [`supplementary_tables/`](https://github.com/hutaobo/Cell-GPS/tree/main/Cell-GPS%20manuscript%20code/supplementary_tables): notebooks for supplementary table analyses.\n\nThe 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`](https://github.com/hutaobo/Cell-GPS/blob/main/docs/cellgps_science_manuscript_code_inventory.md).\n\n## Package Names\n\n- Python distribution: `Cell-GPS`\n- Conda-forge distribution: `cell-gps`\n- Python import package: `cellgps`\n- Legacy Python compatibility namespace: `sfplot` (not a separate distribution; retained for existing scripts)\n- R package/repository: `cellgpsr`\n- Windows executable: `cellgps.exe`\n\nThe Python package is hosted at `https://github.com/hutaobo/Cell-GPS`. The R package is hosted separately at `https://github.com/hutaobo/cellgpsr`. The Windows single-file executable is distributed through Zenodo; use the latest open v2 DOI \u003chttps://doi.org/10.5281/zenodo.19482685\u003e or the version-series route \u003chttps://zenodo.org/records/17859173\u003e.\n\n## What Cell-GPS does\n\n- Computes searcher-findee distance matrices from spatial coordinates and cell labels.\n- Builds cophenetic distance matrices and StructureMap heatmaps from `AnnData` objects or plain `pandas` tables.\n- Loads 10x Xenium outputs and prepares them for downstream spatial analysis.\n- Provides Xenium loaders backed by `pyXenium.io`, including standard Xenium folders and table bundles with `cells.parquet`, official `*_cell_groups.csv`, and `cell_feature_matrix.h5`.\n- Supports transcript-by-cell analysis for locating transcripts relative to cell types.\n- Includes memory-optimized workflows for large datasets.\n- Provides plotting utilities such as clustered heatmaps, circular dendrograms, and related summary figures.\n\n## Repository layout\n\n- `src/cellgps/`: recommended Python import namespace.\n- `src/cellgps/pp`, `src/cellgps/tl`, `src/cellgps/pl`: scverse-style aliases for preprocessing, analysis, and plotting APIs.\n- `src/sfplot/`: legacy compatibility namespace that currently hosts implementation modules; new code should import through `cellgps`.\n- `tests/`: package tests and smoke checks.\n- `docs/`: Sphinx documentation.\n- `docs/project/`: project notes, changelog, authors, and reviewer guide.\n- `Cell-GPS manuscript code/`: curated preprint figure and table notebooks.\n- `examples/`: compact usage examples and small example data files.\n- `packaging/conda-recipe/`: legacy local conda recipe retained for reference.\n- `packaging/pyinstaller/`: Windows executable build scripts and PyInstaller assets.\n\n## Installation\n\nInstall from PyPI:\n\n```bash\npip install Cell-GPS\n```\n\nInstall from conda-forge:\n\n```bash\nconda install -c conda-forge cell-gps\n```\n\nInstall directly from GitHub:\n\n```bash\npip install git+https://github.com/hutaobo/Cell-GPS.git\n```\n\nFor local development or reviewer inspection:\n\n```bash\ngit clone https://github.com/hutaobo/Cell-GPS.git\ncd cellgps\npip install -e .\n```\n\nThe package requires Python 3.9 or later.\n\n## Quick start from a coordinate table\n\nThe minimal input is a table with spatial coordinates and a cell-type column.\n\n```python\nimport pandas as pd\nfrom cellgps import compute_cophenetic_distances_from_df, plot_cophenetic_heatmap\n\ndf = pd.DataFrame(\n    {\n        \"x\": [0, 1, 5, 6],\n        \"y\": [0, 1, 5, 6],\n        \"celltype\": [\"A\", \"A\", \"B\", \"B\"],\n    }\n)\n\nrow_coph, col_coph = compute_cophenetic_distances_from_df(\n    df=df,\n    x_col=\"x\",\n    y_col=\"y\",\n    celltype_col=\"celltype\",\n)\n\nplot_cophenetic_heatmap(\n    row_coph,\n    matrix_name=\"row_coph\",\n    output_dir=\"output\",\n    output_filename=\"StructureMap_example.pdf\",\n    sample=\"Example\",\n)\n```\n\n## Quick start from Xenium output\n\n```python\nfrom cellgps import load_xenium_data, load_xenium_table_bundle, compute_cophenetic_distances_from_adata\n\n# Standard Xenium folder through pyXenium.io\nadata = load_xenium_data(\"/path/to/xenium/run\", normalize=False)\n\n# Explicit table-bundle route used for the Atera Xenium benchmark\nadata = load_xenium_table_bundle(\"/path/to/xenium/run\", normalize=False)\n\nrow_coph, col_coph = compute_cophenetic_distances_from_adata(\n    adata,\n    cluster_col=\"Cluster\",\n    output_dir=\"output\",\n)\n```\n\n## Useful public entry points\n\n- `load_xenium_data`: load and preprocess Xenium data.\n- `load_xenium_table_bundle`: load Xenium data from `cells.parquet` + `*_cell_groups.csv` + `cell_feature_matrix.h5` through `pyXenium.io`.\n- `compute_cophenetic_distances_from_df`: compute structure matrices from a coordinate table.\n- `compute_weighted_searcher_findee_distance_matrix_from_df`: weighted searcher-findee kernel for entity, pathway, or LR analysis.\n- `compute_weighted_cophenetic_distances_from_df`: weighted StructureMap wrapper over the weighted kernel.\n- `compute_cophenetic_distances_from_adata`: compute structure matrices from `AnnData`.\n- `compute_entity_to_cell_topology`: generalize `t_and_c` from transcripts to arbitrary weighted entities.\n- `compute_entity_structuremap`: build StructureMap-style topology among arbitrary weighted entities.\n- `plot_cophenetic_heatmap`: generate StructureMap and related clustered heatmaps.\n- `transcript_by_cell_analysis`: analyze transcript-to-cell spatial structure at scale.\n- `ligand_receptor_topology_analysis`: score sender-\u003ereceiver ligand-receptor candidates using topology, structure compatibility, and local contact.\n- `ligand_receptor_target_consistency`: add a NicheNet-style downstream target-consistency layer.\n- `compute_pathway_activity_matrix`: compute rank-based or weighted pathway activities per cell.\n- `pathway_topology_analysis`: analyze pathway-to-cell and pathway-to-pathway spatial topology.\n- `compute_cophenetic_distances_from_df_memory_opt`: memory-aware alternative for large tables.\n- `plot_circular_dendrogram_pycirclize`: circular dendrogram visualization.\n\n## Validation scope\n\nThe manuscript-validated scope is the COSTE/SSS workflow and the figure/table analyses mapped in `Cell-GPS manuscript code/` 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.\n\n## Notes for reviewers\n\n- The curated figure and table notebooks for the bioRxiv preprint are kept in `Cell-GPS manuscript code/`.\n- 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.\n- Conda-forge packages the upstream Python distribution as `cell-gps`. The `sfplot` top-level namespace is bundled only as legacy compatibility inside the same distribution, not as a separate conda or PyPI package.\n- When a `cellgps_tbc_formal_wta/results`-style directory is already available, the LR and pathway topology extensions are designed to reuse its `t_and_c_result_*.csv` and `StructureMap_table_*.csv` outputs as the preferred gene-level topology anchors before falling back to recomputation.\n- Xenium loading depends on `pyXenium\u003e=0.4.3`. Visium helpers remain optional through the separate `Cell-GPS[visium]` extra.\n- A short repository walkthrough is available in [docs/project/REVIEWER_GUIDE.md](docs/project/REVIEWER_GUIDE.md).\n\n## Documentation\n\nRead the Docs documentation is available at \u003chttps://cell-gps.readthedocs.io/en/latest/\u003e.\nThe 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.\n\nSphinx documentation sources are available in `docs/`.\n\n## Citation\n\nIf you use Cell-GPS or reuse the manuscript analysis code, please cite:\n\n\u003e Long M, Hu T, Sountoulidis A, Samakovlis C, Nilsson M. Cophenetic Spatial Topology Embedding reveals multiscale tissue architecture in spatial omics. bioRxiv. 2026. doi: [10.64898/2026.05.26.727847](https://doi.org/10.64898/2026.05.26.727847)\n\n```bibtex\n@article{long2026cellgps,\n  title = {Cophenetic Spatial Topology Embedding reveals multiscale tissue architecture in spatial omics},\n  author = {Long, Mengping and Hu, Taobo and Sountoulidis, Alexandros and Samakovlis, Christos and Nilsson, Mats},\n  journal = {bioRxiv},\n  year = {2026},\n  doi = {10.64898/2026.05.26.727847},\n  url = {https://www.biorxiv.org/content/10.64898/2026.05.26.727847v1}\n}\n```\n\n## License\n\nThis project is released under the MIT License. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhutaobo%2Fcell-gps","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhutaobo%2Fcell-gps","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhutaobo%2Fcell-gps/lists"}