{"id":34086293,"url":"https://github.com/quadbio/cellmapper","last_synced_at":"2026-04-10T10:31:41.375Z","repository":{"id":290383828,"uuid":"973714072","full_name":"quadbio/cellmapper","owner":"quadbio","description":"k-NN-based mapping of cells across representations to transfer labels, embeddings, and expression values. ","archived":false,"fork":false,"pushed_at":"2026-04-06T20:34:55.000Z","size":79397,"stargazers_count":13,"open_issues_count":5,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-06T22:21:12.067Z","etag":null,"topics":["data-integration","genomics","k-nn","representation-learning","scrna-seq","single-cell","spatial-biology"],"latest_commit_sha":null,"homepage":"https://cellmapper.readthedocs.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/quadbio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/contributing.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-04-27T15:29:44.000Z","updated_at":"2026-04-01T07:02:51.000Z","dependencies_parsed_at":"2025-05-20T18:25:39.420Z","dependency_job_id":"a7d18f4e-1768-458b-ba0b-691dbb5ccfe5","html_url":"https://github.com/quadbio/cellmapper","commit_stats":null,"previous_names":["quadbio/cellmapper"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/quadbio/cellmapper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quadbio%2Fcellmapper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quadbio%2Fcellmapper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quadbio%2Fcellmapper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quadbio%2Fcellmapper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/quadbio","download_url":"https://codeload.github.com/quadbio/cellmapper/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quadbio%2Fcellmapper/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31638403,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-10T07:40:12.752Z","status":"ssl_error","status_checked_at":"2026-04-10T07:40:11.664Z","response_time":98,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["data-integration","genomics","k-nn","representation-learning","scrna-seq","single-cell","spatial-biology"],"created_at":"2025-12-14T13:25:44.416Z","updated_at":"2026-04-10T10:31:41.353Z","avatar_url":"https://github.com/quadbio.png","language":"Python","readme":"# CellMapper\n\n[![Tests][badge-tests]][tests]\n[![Coverage][badge-coverage]][coverage]\n[![Pre-commit.ci][badge-pre-commit]][pre-commit]\n[![PyPI][badge-pypi]][pypi]\n[![Documentation][badge-docs]][docs]\n[![Downloads][badge-downloads]][downloads]\n[![Zenodo][badge-zenodo]][zenodo]\n\n[badge-tests]: https://github.com/quadbio/cellmapper/actions/workflows/test.yaml/badge.svg\n[badge-coverage]: https://codecov.io/gh/quadbio/cellmapper/branch/main/graph/badge.svg\n[badge-pre-commit]: https://results.pre-commit.ci/badge/github/quadbio/cellmapper/main.svg\n[badge-pypi]: https://img.shields.io/pypi/v/cellmapper.svg\n[badge-docs]: https://img.shields.io/readthedocs/cellmapper\n[badge-downloads]: https://static.pepy.tech/badge/cellmapper\n[badge-zenodo]: https://zenodo.org/badge/973714072.svg\n\nk-NN-based mapping of cells across representations to transfer labels, embeddings and expression values. Works for millions of cells, on CPU and GPU, across molecular modalities, between spatial and non-spatial data, for arbitrary query and reference datasets. Using [faiss][] to compute k-NN graphs, CellMapper takes about 30 seconds to transfer cell type labels from 1.5M cells to 1.5M cells on a single RTX 4090 with 60 GB CPU memory.\n\nInspired by previous tools, including scanpy's [ingest][] and the [HNOCA-tools][] packages. Check out the 📚 [docs][] to learn more, in particular our [tutorials][].\n\n## ✨ Key use cases\n\n- 🧬 Transfer cell type labels and expression values from dissociated to spatial datasets.\n- ↔️ Transfer embeddings between arbitrary query and reference datasets.\n- 📊 Compute presence scores for query datasets in large reference atlasses.\n- 🗺️ Identify niches in spatial datasets by contextualizing latent spaces in spatial coordinates.\n- 📈 Evaluate the results of transferring labels, embeddings and feature spaces using a variety of metrics.\n\nThe core idea of `CellMapper` is to separate the method (k-NN graph with some kernel applied to get a mapping matrix) from the application (mapping across arbitrary representations), to be flexible and fast. The tool currently supports [pynndescent][], [sklearn][], [faiss][] and [rapids][] for neighborhood search, implements a variety of graph kernels, and is closely integrated with `AnnData` objects.\n\n## 📦 Installation\n\nYou need to have 🐍 Python 3.11 or newer installed on your system.\nIf you don't have Python installed, we recommend installing [uv][].\n\nThere are two alternative options to install ``cellmapper``:\n\n- 🚀 Install the latest release from [PyPI][]:\n\n  ```bash\n  pip install cellmapper\n  ```\n\n- 🛠️ Install the latest development version:\n\n  ```bash\n  pip install git+https://github.com/quadbio/cellmapper.git@main\n  ```\n\n## 🏁 Getting started\n\nThis package assumes that you have ``query`` and ``reference`` AnnData objects, with a joint embedding computed and stored in ``.obsm``. While we implement some baseline approaches to compute joint embeddings (PCA and a fast reimplementation of CCA), we typically expect you to provide a pre-computed joint embedding from some task-specific representation learning tools, e.g. [GimVI][] or [ENVI][] for spatial mapping, [GLUE][], [MIDAS][] and [MOFA+][] for modality translation, and [scVI][], [scANVI][] and [scArches][] for query-to-reference mapping - this is just a small selection!\n\nWith a joint embedding in ``.obsm[\"X_joint\"]`` at hand, the simplest way to use ``CellMapper`` is as follows:\n```Python\nfrom cellmapper import CellMapper\n\ncmap = CellMapper(query, reference).map(\n    use_rep=\"X_joint\", obs_keys=\"celltype\", obsm_keys=\"X_umap\", layer_key=\"X\"\n    )\n```\n\nThis will transfer data from the reference to the query dataset, including celltype labels stored in ``reference.obs``, a UMAP embedding stored in ``reference.obsm``, and expression values stored in ``reference.X``.\n\nThere are many ways to customize this, e.g. use different ways to compute k-NN graphs and to turn them into mapping matrices, and we implement a few methods to evaluate whether your k-NN transfer was sucessful. The tool also implements a `self-mapping` mode (only a query object, no reference), which is useful for spatial contextualization and data denoising. Check out the 📚 [docs][] to learn more.\n\n## 📝 Release notes\n\nSee the [changelog][].\n\n## 📬 Contact\n\nIf you found a bug, please use the [issue tracker][].\n\n## 📖 Citation\nPlease use our [zenodo][] entry to cite this software.\n\n[uv]: https://github.com/astral-sh/uv\n[issue tracker]: https://github.com/quadbio/cellmapper/issues\n[tests]: https://github.com/quadbio/cellmapper/actions/workflows/test.yaml\n[changelog]: https://cellmapper.readthedocs.io/en/latest/changelog.html\n[docs]: https://cellmapper.readthedocs.io/\n[tutorials]: https://cellmapper.readthedocs.io/en/latest/notebooks/tutorials/index.html\n[pypi]: https://pypi.org/project/cellmapper\n[coverage]: https://codecov.io/gh/quadbio/cellmapper\n[pre-commit]: https://results.pre-commit.ci/latest/github/quadbio/cellmapper/main\n[pypi]: https://pypi.org/project/cellmapper/\n[downloads]: https://pepy.tech/project/cellmapper\n[zenodo]: https://doi.org/10.5281/zenodo.15683594\n\n[faiss]: https://github.com/facebookresearch/faiss\n[pynndescent]: https://github.com/lmcinnes/pynndescent\n[sklearn]: https://scikit-learn.org/stable/modules/neighbors.html\n[rapids]: https://docs.rapids.ai/api/cuml/stable/api/#nearest-neighbors\n\n[ingest]: https://scanpy.readthedocs.io/en/stable/generated/scanpy.tl.ingest.html\n[HNOCA-tools]: https://devsystemslab.github.io/HNOCA-tools/\n\n[GimVI]: https://docs.scvi-tools.org/en/stable/api/reference/scvi.external.GIMVI.html#\n[ENVI]: https://scenvi.readthedocs.io/en/latest/#\n[GLUE]: https://scglue.readthedocs.io/en/latest/\n[MIDAS]: https://scmidas.readthedocs.io/en/latest/\n[MOFA+]: https://muon.readthedocs.io/en/latest/omics/multi.html\n[scVI]: https://docs.scvi-tools.org/en/stable/api/reference/scvi.model.SCVI.html\n[scANVI]: https://docs.scvi-tools.org/en/stable/api/reference/scvi.model.SCANVI.html\n[scArches]: https://docs.scarches.org/en/latest/\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquadbio%2Fcellmapper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fquadbio%2Fcellmapper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquadbio%2Fcellmapper/lists"}