campmc 0.1.0__tar.gz

campmc-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,62 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+  workflow_call:
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  pre-commit:
+    name: pre-commit / ${{ matrix.hook }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        hook:
+          - trailing-whitespace
+          - end-of-file-fixer
+          - check-yaml
+          - check-toml
+          - check-added-large-files
+          - ruff-check
+          - ruff-format
+          - complexipy
+          - ty
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Run ${{ matrix.hook }}
+        run: uvx pre-commit run ${{ matrix.hook }} --all-files --show-diff-on-failure
+
+  test:
+    name: pytest
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Run tests
+        run: uv run pytest -q

campmc-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,37 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  ci:
+    uses: ./.github/workflows/ci.yml
+
+  publish:
+    name: Publish to PyPI
+    needs: ci
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/campmc
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Build
+        run: uv build
+
+      - name: Publish
+        run: uv publish

campmc-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Sphinx
+docs/_build/
+docs/generated/

campmc-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,42 @@
+default_install_hook_types:
+  - pre-commit
+  - commit-msg
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.21
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: complexipy
+        name: complexipy
+        entry: uv run complexipy
+        language: system
+        types: [python]
+        args: [--max-complexity-allowed=15]
+        require_serial: true
+
+  - repo: https://github.com/astral-sh/ty-pre-commit
+    rev: v0.0.58
+    hooks:
+      - id: ty
+        args: [--isolated]
+
+  - repo: https://github.com/compilerla/conventional-pre-commit
+    rev: v4.4.0
+    hooks:
+      - id: conventional-pre-commit
+        stages: [commit-msg]

campmc-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

campmc-0.1.0/.readthedocs.yml

@@ -0,0 +1,17 @@
+# version: 2
+# Scanpy-style Read the Docs config (uv + sphinx-build)
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+  jobs:
+    create_environment:
+      - asdf plugin add uv
+      - asdf install uv latest
+      - asdf global uv latest
+    install:
+      - uv sync --group doc
+    build:
+      html:
+        - uv run sphinx-build -M html docs $READTHEDOCS_OUTPUT

campmc-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 danrongLi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

campmc-0.1.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: campmc
+Version: 0.1.0
+Summary: Third-party portable Python package for CAMP metacell partitioning (not the official paper repo)
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: anndata>=0.11
+Requires-Dist: celltypist
+Requires-Dist: matplotlib
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: scanpy>=1.10
+Requires-Dist: scikit-learn
+Requires-Dist: scipy
+Requires-Dist: seaborn
+Requires-Dist: seacells
+Description-Content-Type: text/markdown
+
+# CAMP (Coreset Accelerated Metacell Partitioning)
+
+Third-party, installable Python reimplementation of the CAMP metacell methods for use with [AnnData](https://anndata.readthedocs.io/) and [Scanpy](https://scanpy.readthedocs.io/).
+
+## About this project
+
+**This repository is not maintained by the authors of the CAMP paper.** It is an independent packaging effort that ports the research code from the upstream [CAMP](https://github.com/danrongLi/CAMP) repository into a reusable library (`import campmc as cp`, PyPI name **campmc**).
+
+Goals of this project:
+
+- Make CAMP1–4 and related helpers **portable** (no hardcoded cluster paths, scanpy-style API).
+- Provide tests, documentation, and a normal Python package layout.
+
+For the **official reference implementation**, paper benchmarks, and experiment scripts, use the upstream CAMP repository. Behavior here should match the published algorithms in spirit, but this package is maintained separately.
+
+If you use the CAMP method, please cite the [bioRxiv preprint](https://www.biorxiv.org/content/10.64898/2025.12.11.693725v1) (Li, Ko & Canzar, 2025; [doi:10.64898/2025.12.11.693725](https://doi.org/10.64898/2025.12.11.693725)) — see [Citation](#citation) below.
+
+## Install
+
+```bash
+cd mycamp
+uv sync --group dev
+```
+
+## Usage (scanpy-style)
+
+```python
+import campmc as cp
+import scanpy as sc
+
+adata = sc.datasets.pbmc68k_reduced()
+cp.tl.partition(adata, method="camp3", gamma=25, random_state=0)
+cp.metrics.quality(adata, partition_key="camp", label_key="louvain")
+```
+
+## Documentation
+
+Build HTML docs locally (same stack as [Scanpy](https://scanpy.readthedocs.io/): Sphinx, MyST, `scanpydoc` theme):
+
+```bash
+uv sync --group doc
+uv run sphinx-build -M html docs docs/_build
+```
+
+## Citation
+
+If you use the CAMP method, please cite the preprint:
+
+> Li, D., Ko, Y. K., & Canzar, S. (2025). CAMP: Coreset Accelerated Metacell Partitioning enables scalable analysis of single-cell data. *bioRxiv*. [https://doi.org/10.64898/2025.12.11.693725](https://doi.org/10.64898/2025.12.11.693725)
+
+Preprint: [bioRxiv](https://www.biorxiv.org/content/10.64898/2025.12.11.693725v1)
+
+```bibtex
+@article{li2025camp,
+  title   = {CAMP: Coreset Accelerated Metacell Partitioning enables scalable analysis of single-cell data},
+  author  = {Li, Danrong and Ko, Young Kun and Canzar, Stefan},
+  journal = {bioRxiv},
+  year    = {2025},
+  doi     = {10.64898/2025.12.11.693725},
+  url     = {https://www.biorxiv.org/content/10.64898/2025.12.11.693725v1}
+}
+```
+
+This **campmc** package is a third-party implementation; citing the preprint refers to the CAMP method, not this repository.
+
+## Tests
+
+```bash
+uv run pytest -q
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE). Algorithm code is adapted from the upstream [CAMP](https://github.com/danrongLi/CAMP) repository (MIT, © danrongLi). This **campmc** package is a separate third-party distribution; it is not affiliated with or endorsed by the original CAMP authors unless they state otherwise.

campmc-0.1.0/README.md

@@ -0,0 +1,74 @@
+# CAMP (Coreset Accelerated Metacell Partitioning)
+
+Third-party, installable Python reimplementation of the CAMP metacell methods for use with [AnnData](https://anndata.readthedocs.io/) and [Scanpy](https://scanpy.readthedocs.io/).
+
+## About this project
+
+**This repository is not maintained by the authors of the CAMP paper.** It is an independent packaging effort that ports the research code from the upstream [CAMP](https://github.com/danrongLi/CAMP) repository into a reusable library (`import campmc as cp`, PyPI name **campmc**).
+
+Goals of this project:
+
+- Make CAMP1–4 and related helpers **portable** (no hardcoded cluster paths, scanpy-style API).
+- Provide tests, documentation, and a normal Python package layout.
+
+For the **official reference implementation**, paper benchmarks, and experiment scripts, use the upstream CAMP repository. Behavior here should match the published algorithms in spirit, but this package is maintained separately.
+
+If you use the CAMP method, please cite the [bioRxiv preprint](https://www.biorxiv.org/content/10.64898/2025.12.11.693725v1) (Li, Ko & Canzar, 2025; [doi:10.64898/2025.12.11.693725](https://doi.org/10.64898/2025.12.11.693725)) — see [Citation](#citation) below.
+
+## Install
+
+```bash
+cd mycamp
+uv sync --group dev
+```
+
+## Usage (scanpy-style)
+
+```python
+import campmc as cp
+import scanpy as sc
+
+adata = sc.datasets.pbmc68k_reduced()
+cp.tl.partition(adata, method="camp3", gamma=25, random_state=0)
+cp.metrics.quality(adata, partition_key="camp", label_key="louvain")
+```
+
+## Documentation
+
+Build HTML docs locally (same stack as [Scanpy](https://scanpy.readthedocs.io/): Sphinx, MyST, `scanpydoc` theme):
+
+```bash
+uv sync --group doc
+uv run sphinx-build -M html docs docs/_build
+```
+
+## Citation
+
+If you use the CAMP method, please cite the preprint:
+
+> Li, D., Ko, Y. K., & Canzar, S. (2025). CAMP: Coreset Accelerated Metacell Partitioning enables scalable analysis of single-cell data. *bioRxiv*. [https://doi.org/10.64898/2025.12.11.693725](https://doi.org/10.64898/2025.12.11.693725)
+
+Preprint: [bioRxiv](https://www.biorxiv.org/content/10.64898/2025.12.11.693725v1)
+
+```bibtex
+@article{li2025camp,
+  title   = {CAMP: Coreset Accelerated Metacell Partitioning enables scalable analysis of single-cell data},
+  author  = {Li, Danrong and Ko, Young Kun and Canzar, Stefan},
+  journal = {bioRxiv},
+  year    = {2025},
+  doi     = {10.64898/2025.12.11.693725},
+  url     = {https://www.biorxiv.org/content/10.64898/2025.12.11.693725v1}
+}
+```
+
+This **campmc** package is a third-party implementation; citing the preprint refers to the CAMP method, not this repository.
+
+## Tests
+
+```bash
+uv run pytest -q
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE). Algorithm code is adapted from the upstream [CAMP](https://github.com/danrongLi/CAMP) repository (MIT, © danrongLi). This **campmc** package is a separate third-party distribution; it is not affiliated with or endorsed by the original CAMP authors unless they state otherwise.

campmc-0.1.0/docs/_static/custom.css

@@ -0,0 +1,5 @@
+/* CAMP docs — small tweaks on top of scanpydoc / sphinx-book-theme */
+
+.bd-main .bd-content {
+  max-width: 60rem;
+}

campmc-0.1.0/docs/api/coreset.md

@@ -0,0 +1,16 @@
+# Coreset
+
+```{eval-rst}
+.. module:: campmc.coreset
+.. currentmodule:: campmc
+```
+
+```{eval-rst}
+.. autosummary::
+   :nosignatures:
+   :toctree: ../generated/
+
+   coreset.compute_q
+   coreset.sample_coreset
+   coreset.gammas_to_m
+```

campmc-0.1.0/docs/api/index.md

@@ -0,0 +1,32 @@
+# API
+
+Import CAMP as:
+
+```
+import campmc as cp
+```
+
+The API mirrors Scanpy’s module layout:
+
+| Module | Role |
+|--------|------|
+| {mod}`campmc.pp` | Preprocessing (filter, normalize, HVG, PCA) |
+| {mod}`campmc.tl` | Metacell partitioning (CAMP1–4) |
+| {mod}`campmc.metrics` | Quality metrics on partitions |
+| {mod}`campmc.rare` | Rare-cell recovery scores |
+| {mod}`campmc.robustness` | HVG/PCA cache helpers for sweeps |
+| {mod}`campmc.pl` | Plotting helpers |
+
+```{toctree}
+:maxdepth: 2
+:hidden:
+
+pp
+tl
+coreset
+io
+metrics
+rare
+robustness
+pl
+```

campmc-0.1.0/docs/api/io.md

@@ -0,0 +1,17 @@
+# I/O
+
+```{eval-rst}
+.. module:: campmc.io
+.. currentmodule:: campmc
+```
+
+Membership CSV read/write (compatible with upstream CAMP partition exports).
+
+```{eval-rst}
+.. autosummary::
+   :nosignatures:
+   :toctree: ../generated/
+
+   io.write_membership
+   io.read_membership
+```

campmc-0.1.0/docs/api/metrics.md

@@ -0,0 +1,14 @@
+# Metrics
+
+```{eval-rst}
+.. module:: campmc.metrics
+.. currentmodule:: campmc
+```
+
+```{eval-rst}
+.. autosummary::
+   :nosignatures:
+   :toctree: ../generated/
+
+   metrics.quality
+```

campmc-0.1.0/docs/api/pl.md

@@ -0,0 +1,15 @@
+# Plotting: `pl`
+
+```{eval-rst}
+.. module:: campmc.pl
+.. currentmodule:: campmc
+```
+
+```{eval-rst}
+.. autosummary::
+   :nosignatures:
+   :toctree: ../generated/
+
+   pl.metric_ecdf
+   pl.metric_lines
+```

campmc-0.1.0/docs/api/pp.md

@@ -0,0 +1,14 @@
+# Preprocessing: `pp`
+
+```{eval-rst}
+.. module:: campmc.pp
+.. currentmodule:: campmc
+```
+
+```{eval-rst}
+.. autosummary::
+   :nosignatures:
+   :toctree: ../generated/
+
+   pp.preprocess
+```

campmc-0.1.0/docs/api/rare.md

@@ -0,0 +1,15 @@
+# Rare-cell recovery
+
+```{eval-rst}
+.. module:: campmc.rare
+.. currentmodule:: campmc
+```
+
+```{eval-rst}
+.. autosummary::
+   :nosignatures:
+   :toctree: ../generated/
+
+   rare.identify_rare_types
+   rare.recovery_scores
+```

campmc-0.1.0/docs/api/robustness.md

@@ -0,0 +1,18 @@
+# Robustness
+
+```{eval-rst}
+.. module:: campmc.robustness
+.. currentmodule:: campmc
+```
+
+Cached preprocessing for HVG/PCA parameter sweeps.
+
+```{eval-rst}
+.. autosummary::
+   :nosignatures:
+   :toctree: ../generated/
+
+   robustness.build_or_load_base_cache
+   robustness.build_or_load_hvg_pca_cache
+   robustness.run_hvg_pca_sweep
+```

campmc-0.1.0/docs/api/tl.md

@@ -0,0 +1,20 @@
+# Tools: `tl`
+
+```{eval-rst}
+.. module:: campmc.tl
+.. currentmodule:: campmc
+```
+
+Metacell partitioning (CAMP1–4). Writes labels to `adata.obs` and metadata to `adata.uns`.
+
+```{eval-rst}
+.. autosummary::
+   :nosignatures:
+   :toctree: ../generated/
+
+   tl.partition
+```
+
+## Assigners (internal)
+
+Lower-level assignment kernels live in {mod}`campmc.tl.assign` and are called from {func}`campmc.tl.partition`.

campmc-0.1.0/docs/conf.py

@@ -0,0 +1,82 @@
+"""Configuration for CAMP Sphinx documentation (scanpy / scverse style)."""
+
+from __future__ import annotations
+
+import sys
+from importlib.metadata import version as get_version
+from pathlib import Path
+
+HERE = Path(__file__).parent
+sys.path.insert(0, str(HERE.parent / "src"))
+
+project = "campmc"
+author = "CAMP contributors"
+copyright = "2025, CAMP contributors"
+version = get_version("campmc").replace(".dirty", "")
+release = version
+
+master_doc = "index"
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "**.ipynb_checkpoints"]
+
+extensions = [
+    "myst_nb",
+    "sphinx_copybutton",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.autosummary",
+    "sphinx_autodoc_typehints",
+    "sphinx_design",
+    "scanpydoc",
+]
+
+autosummary_generate = True
+autodoc_typehints = "none"
+autodoc_member_order = "bysource"
+autodoc_default_options = {
+    "members": False,
+    "show-inheritance": True,
+}
+
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+napoleon_use_rtype = True
+napoleon_use_param = True
+
+myst_enable_extensions = [
+    "colon_fence",
+    "deflist",
+    "dollarmath",
+    "html_admonition",
+]
+myst_heading_anchors = 3
+nb_output_stderr = "remove"
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "pandas": ("https://pandas.pydata.org/docs/", None),
+    "anndata": ("https://anndata.readthedocs.io/en/stable/", None),
+    "scanpy": ("https://scanpy.readthedocs.io/en/stable/", None),
+}
+
+html_theme = "scanpydoc"
+html_theme_options = {
+    "repository_url": "https://github.com/danrongLi/CAMP",
+    "repository_branch": "master",
+    "use_repository_button": True,
+}
+html_context = {
+    "github_user": "danrongLi",
+    "github_repo": "CAMP",
+    "github_version": "master",
+}
+html_static_path = ["_static"]
+html_css_files = ["custom.css"]
+html_show_sphinx = False
+html_title = "campmc"
+
+
+def setup(app):
+    return {"parallel_read_safe": True, "parallel_write_safe": True}

campmc-0.1.0/docs/index.md

@@ -0,0 +1,48 @@
+```{include} ../README.md
+:end-before: '## Tests'
+```
+
+```{note}
+This documentation describes the **campmc** package — a third-party reimplementation. It is **not** the official site of the CAMP paper authors. See [upstream CAMP](https://github.com/danrongLi/CAMP) for the reference code and benchmarks.
+```
+
+::::{grid} 1 2 3 3
+:gutter: 2
+
+:::{grid-item-card} Installation {octicon}`plug;1em;`
+:link: installation
+:link-type: doc
+
+Install `campmc` with uv and optional dev tools.
+:::
+
+:::{grid-item-card} Tutorials {octicon}`play;1em;`
+:link: tutorials/index
+:link-type: doc
+
+Walk through metacell partitioning on built-in Scanpy datasets.
+:::
+
+:::{grid-item-card} API reference {octicon}`book;1em;`
+:link: api/index
+:link-type: doc
+
+Detailed reference for `campmc.pp`, `campmc.tl`, and related modules.
+:::
+
+:::{grid-item-card} Upstream CAMP (official) {octicon}`mark-github;1em;`
+:link: https://github.com/danrongLi/CAMP
+
+Paper authors’ reference scripts and benchmarks — not this package.
+:::
+::::
+
+```{toctree}
+:hidden:
+:maxdepth: 1
+
+installation
+tutorials/index
+api/index
+references
+```