campmc 0.1.0__py3-none-any.whl

campmc/__init__.py

@@ -0,0 +1,13 @@
+"""CAMP metacell partitioning for AnnData (third-party portable implementation).
+
+This package is not maintained by the authors of the CAMP paper. See the
+upstream repository at https://github.com/danrongLi/CAMP for the reference code.
+"""
+
+from __future__ import annotations
+
+from campmc import metrics, pl, pp, rare, robustness, tl
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__", "metrics", "pl", "pp", "rare", "robustness", "tl"]

campmc/_logging.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+import logging
+
+
+def get_logger(name: str) -> logging.Logger:
+    logger = logging.getLogger(name)
+    if not logger.handlers:
+        handler = logging.StreamHandler()
+        handler.setFormatter(logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s"))
+        logger.addHandler(handler)
+        logger.setLevel(logging.INFO)
+    return logger

campmc/coreset.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import numpy as np
+from anndata import AnnData
+from scipy import sparse
+
+from campmc._logging import get_logger
+
+logger = get_logger(__name__)
+
+
+def compute_q(adata: AnnData, *, rep_key: str = "X_pca") -> np.ndarray:
+    """Importance weights q(x) from distance to mean in representation space."""
+    X = adata.obsm[rep_key]
+    if sparse.issparse(X):
+        x_csr = X.tocsr(copy=False)
+        mu = np.asarray(x_csr.mean(axis=0)).ravel()
+        x_norm_sq = np.asarray(x_csr.power(2).sum(axis=1)).ravel()
+        mu_norm_sq = float(mu @ mu)
+        prod = x_csr @ mu
+        d_sq = x_norm_sq + mu_norm_sq - 2.0 * prod
+    else:
+        x_dense = np.asarray(X, dtype=np.float64)
+        mu = x_dense.mean(axis=0)
+        d_sq = np.sum((x_dense - mu) ** 2, axis=1)
+
+    n = adata.n_obs
+    denom = float(d_sq.sum())
+    if denom == 0.0:
+        logger.warning("All points coincide; returning uniform q.")
+        return np.full(n, 1.0 / n)
+
+    q = 0.5 * (1.0 / n) + 0.5 * (d_sq / denom)
+    q /= q.sum()
+    return q
+
+
+def gammas_to_m(n_obs: int, gammas: Sequence[int]) -> list[int]:
+    return [max(1, int(n_obs / g)) for g in gammas]
+
+
+def sample_coreset(
+    n_obs: int,
+    m: int,
+    q: np.ndarray,
+    *,
+    random_state: int = 0,
+) -> np.ndarray:
+    """Return `m` unique cell indices sampled with probabilities `q`."""
+    rng = np.random.default_rng(random_state)
+    m = min(m, n_obs)
+    return rng.choice(n_obs, size=m, replace=False, p=q)

campmc/io.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import pandas as pd
+from anndata import AnnData
+
+
+def write_membership(adata: AnnData, path: str | Path, *, key_added: str = "camp") -> None:
+    """Write partition labels and seed flags to CSV (CAMP membership schema)."""
+    path = Path(path)
+    label_col = key_added
+    seed_col = f"{key_added}_is_seed"
+    if label_col not in adata.obs:
+        raise KeyError(f"obs missing '{label_col}'")
+    if seed_col not in adata.obs:
+        raise KeyError(f"obs missing '{seed_col}'")
+
+    df = pd.DataFrame(
+        {
+            label_col: adata.obs[label_col].astype(str),
+            seed_col: adata.obs[seed_col].astype(bool),
+        },
+        index=adata.obs_names,
+    )
+    df.to_csv(path)
+
+
+def read_membership(path: str | Path) -> pd.DataFrame:
+    path = Path(path)
+    return pd.read_csv(path, index_col=0)

campmc/metrics/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from campmc.metrics.quality import quality
+
+__all__ = ["quality"]

campmc/metrics/quality.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+import scanpy as sc
+from anndata import AnnData
+from scipy import sparse
+from scipy.stats import entropy as scipy_entropy
+from sklearn.metrics import pairwise_distances
+
+from campmc._logging import get_logger
+
+logger = get_logger(__name__)
+
+
+def _purity(cell_labels: pd.Series) -> float:
+    counts = cell_labels.value_counts(dropna=False)
+    if len(counts) == 0:
+        return np.nan
+    return float(counts.max()) / float(counts.sum())
+
+
+def _label_entropy(cell_labels: pd.Series) -> float:
+    counts = cell_labels.value_counts(dropna=False).values.astype(float)
+    if counts.sum() == 0:
+        return np.nan
+    p = counts / counts.sum()
+    return float(scipy_entropy(p, base=2))
+
+
+def _compactness(diff_coords: np.ndarray) -> float:
+    return float(-np.var(diff_coords, axis=0).mean())
+
+
+def _inv(expr_block) -> float:
+    x = expr_block.toarray() if sparse.issparse(expr_block) else np.asarray(expr_block)
+    gene_var = np.var(x, axis=0)
+    gene_mean = np.mean(x, axis=0)
+    return float(np.percentile(gene_var / (gene_mean + 1e-8), 95))
+
+
+def _ensure_diffmap(adata: AnnData, use_rep: str) -> None:
+    if "X_diffmap" in adata.obsm:
+        return
+    if use_rep not in adata.obsm:
+        raise KeyError(f"Missing obsm['{use_rep}'] for diffusion map computation.")
+    sc.pp.neighbors(adata, use_rep=use_rep)
+    sc.tl.diffmap(adata)
+
+
+def quality(
+    adata: AnnData,
+    *,
+    partition_key: str = "camp",
+    label_key: str | None = None,
+    use_rep: str = "X_pca",
+) -> pd.DataFrame:
+    """Per-metacell quality metrics (compactness, separation, INV, optional purity)."""
+    if partition_key not in adata.obs:
+        raise KeyError(f"obs missing '{partition_key}'")
+
+    work = adata.copy()
+    _ensure_diffmap(work, use_rep)
+    x_diff = work.obsm["X_diffmap"]
+    x_diff_dense = x_diff if not sparse.issparse(x_diff) else x_diff.toarray()
+    work.obs["metacell"] = work.obs[partition_key].astype(str)
+    grouped = work.obs.groupby("metacell", observed=True)
+
+    centroids: dict[str, np.ndarray] = {}
+    for metacell_id, group in grouped:
+        ix = work.obs.index.get_indexer(group.index)
+        centroids[metacell_id] = x_diff_dense[ix].mean(axis=0)
+
+    mc_ids = list(centroids.keys())
+    if not mc_ids:
+        return pd.DataFrame()
+
+    c_mat = np.vstack([centroids[mid] for mid in mc_ids])
+    dist = pairwise_distances(c_mat, c_mat)
+    np.fill_diagonal(dist, np.inf)
+    nearest_sep = np.min(dist, axis=1)
+    sep_map = {mid: float(nearest_sep[j]) for j, mid in enumerate(mc_ids)}
+
+    rows: list[dict] = []
+    for metacell_id, group in grouped:
+        ix = work.obs.index.get_indexer(group.index)
+        diff_coords = x_diff_dense[ix]
+        compact = _compactness(diff_coords)
+        separation = sep_map[metacell_id]
+        row = {
+            "metacell_id": metacell_id,
+            "size": len(group),
+            "compactness": compact,
+            "separation": separation,
+            "sc_ratio": separation / np.sqrt(max(1e-12, -compact)),
+            "INV": _inv(work.X[ix, :]),
+        }
+        if label_key is not None and label_key in work.obs:
+            labels = work.obs.loc[group.index, label_key]
+            row["purity"] = _purity(labels.astype(str))
+            row["label_entropy"] = _label_entropy(labels.astype(str))
+        rows.append(row)
+
+    logger.info("quality metrics for %d metacells", len(rows))
+    return pd.DataFrame(rows)

campmc/pl/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from campmc.pl.plots import metric_ecdf, metric_lines
+
+__all__ = ["metric_ecdf", "metric_lines"]

campmc/pl/plots.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+import seaborn as sns
+
+
+def metric_ecdf(values: np.ndarray, out_png: str | Path, *, title: str = "Metric ECDF") -> None:
+    vals = np.asarray(values, dtype=float)
+    vals = vals[np.isfinite(vals)]
+    if vals.size == 0:
+        raise ValueError("No finite values to plot.")
+    x = np.sort(vals)
+    y = np.arange(1, x.size + 1) / x.size
+    fig, ax = plt.subplots(figsize=(5, 4))
+    ax.plot(x, y, linewidth=2)
+    ax.set_xlabel("value")
+    ax.set_ylabel("ECDF")
+    ax.set_title(title)
+    fig.tight_layout()
+    fig.savefig(out_png, dpi=150)
+    plt.close(fig)
+
+
+def metric_lines(
+    df: pd.DataFrame,
+    out_png: str | Path,
+    *,
+    x_col: str,
+    y_col: str,
+    hue_col: str | None = None,
+    title: str = "Metric",
+) -> None:
+    fig, ax = plt.subplots(figsize=(6, 4))
+    if hue_col:
+        sns.lineplot(data=df, x=x_col, y=y_col, hue=hue_col, ax=ax)
+    else:
+        sns.lineplot(data=df, x=x_col, y=y_col, ax=ax)
+    ax.set_title(title)
+    fig.tight_layout()
+    fig.savefig(out_png, dpi=150)
+    plt.close(fig)

campmc/pp/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from campmc.pp.preprocess import preprocess
+
+__all__ = ["preprocess"]

campmc/pp/preprocess.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import numpy as np
+import scanpy as sc
+from anndata import AnnData
+from scipy import sparse
+from scipy.sparse import csr_matrix
+
+from campmc._logging import get_logger
+
+logger = get_logger(__name__)
+
+
+def preprocess(
+    adata: AnnData,
+    *,
+    min_genes: int = 200,
+    min_cells: int = 3,
+    n_hvg: int = 2000,
+    n_pcs: int = 50,
+    target_sum: float = 1e4,
+    copy: bool = False,
+) -> AnnData | None:
+    if copy:
+        adata = adata.copy()
+
+    sc.pp.filter_cells(adata, min_genes=min_genes)
+    sc.pp.filter_genes(adata, min_cells=min_cells)
+
+    x_dense = adata.X.A if sparse.issparse(adata.X) else adata.X
+    if np.any(x_dense < 0):
+        if sparse.issparse(adata.X):
+            adata.X = csr_matrix(np.maximum(adata.X.toarray(), 0))
+        else:
+            adata.X = np.maximum(adata.X, 0)
+
+    sc.pp.normalize_total(adata, target_sum=target_sum)
+    sc.pp.log1p(adata)
+    if not sparse.issparse(adata.X):
+        adata.X = csr_matrix(adata.X)
+
+    sc.pp.highly_variable_genes(adata, n_top_genes=min(n_hvg, adata.n_vars - 1), flavor="seurat")
+    keep = np.asarray(adata.var["highly_variable"]).ravel()
+    adata._inplace_subset_var(keep)
+
+    sc.pp.scale(adata, max_value=10)
+    sc.tl.pca(adata, n_comps=min(n_pcs, adata.n_vars - 1, adata.n_obs - 1), svd_solver="arpack")
+    logger.info("preprocess done: shape=%s", adata.shape)
+    return adata if copy else None

campmc/rare/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from campmc.rare.recovery import identify_rare_types, recovery_scores
+
+__all__ = ["identify_rare_types", "recovery_scores"]

campmc/rare/recovery.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import pandas as pd
+from anndata import AnnData
+from sklearn.metrics import adjusted_rand_score, normalized_mutual_info_score
+
+
+def identify_rare_types(labels: pd.Series, *, rare_threshold: float = 0.01) -> pd.DataFrame:
+    counts = labels.value_counts(dropna=False)
+    freq = counts / counts.sum()
+    rare = freq[freq <= rare_threshold].sort_values()
+    return pd.DataFrame(
+        {
+            "cell_type": rare.index.astype(str),
+            "n_cells": counts.loc[rare.index].values.astype(int),
+            "fraction": rare.values.astype(float),
+        }
+    )
+
+
+def _balanced_accuracy(true: pd.Series, pred: pd.Series, rare_types: list[str]) -> float:
+    recalls: list[float] = []
+    for ct in rare_types:
+        pos_mask = true == ct
+        n_pos = int(pos_mask.sum())
+        if n_pos == 0:
+            continue
+        tp = int(((pred == ct) & pos_mask).sum())
+        recalls.append(tp / n_pos)
+    if not recalls:
+        return float("nan")
+    return float(sum(recalls) / len(recalls))
+
+
+def recovery_scores(
+    adata: AnnData,
+    *,
+    partition_key: str,
+    label_key: str,
+    rare_threshold: float = 0.01,
+) -> pd.DataFrame:
+    if partition_key not in adata.obs:
+        raise KeyError(partition_key)
+    if label_key not in adata.obs:
+        raise KeyError(label_key)
+
+    labels = adata.obs[label_key].astype(str)
+    assign = adata.obs[partition_key].astype(str)
+    rare_df = identify_rare_types(labels, rare_threshold=rare_threshold)
+    rare_types = rare_df["cell_type"].tolist()
+
+    contingency = pd.crosstab(assign, labels)
+    mc_majority = contingency.idxmax(axis=1)
+    pred = assign.map(mc_majority).astype(str)
+
+    mask = labels.isin(rare_types)
+    ari = float("nan")
+    nmi = float("nan")
+    if mask.sum() > 1:
+        ari = float(adjusted_rand_score(labels.loc[mask], pred.loc[mask]))
+        nmi = float(normalized_mutual_info_score(labels.loc[mask], pred.loc[mask]))
+
+    return pd.DataFrame(
+        [
+            {
+                "balanced_accuracy": _balanced_accuracy(labels, pred, rare_types),
+                "ari": ari,
+                "nmi": nmi,
+                "n_rare_types": len(rare_types),
+            }
+        ]
+    )

campmc/robustness/__init__.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from campmc.robustness.sweeps import (
+    build_or_load_base_cache,
+    build_or_load_hvg_pca_cache,
+    run_hvg_pca_sweep,
+)
+
+__all__ = ["build_or_load_base_cache", "build_or_load_hvg_pca_cache", "run_hvg_pca_sweep"]

campmc/robustness/sweeps.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import numpy as np
+import scanpy as sc
+from anndata import AnnData
+from scipy import sparse
+
+from campmc._logging import get_logger
+
+logger = get_logger(__name__)
+
+
+def _mkdir(path: Path) -> None:
+    path.mkdir(parents=True, exist_ok=True)
+
+
+def build_or_load_base_cache(
+    input_file: str | Path,
+    dataset_name: str,
+    cache_dir: str | Path,
+    *,
+    min_genes: int = 200,
+    min_cells: int = 3,
+    normalize_target_sum: float = 1e4,
+) -> Path:
+    cache_dir = Path(cache_dir)
+    _mkdir(cache_dir)
+    out = cache_dir / f"{dataset_name}_BASE_log1p.h5ad"
+    if out.exists():
+        logger.info("Using base cache %s", out)
+        return out
+
+    adata = sc.read_h5ad(input_file)
+    sc.pp.filter_cells(adata, min_genes=min_genes)
+    sc.pp.filter_genes(adata, min_cells=min_cells)
+    if sparse.issparse(adata.X):
+        adata.X.data = np.maximum(adata.X.data, 0)
+    sc.pp.normalize_total(adata, target_sum=normalize_target_sum)
+    sc.pp.log1p(adata)
+    adata.write_h5ad(out, compression="gzip")
+    meta = cache_dir / f"{dataset_name}_BASE_log1p.meta.json"
+    meta.write_text(
+        json.dumps({"dataset_name": dataset_name, "source": str(input_file)}, indent=2),
+        encoding="utf-8",
+    )
+    return out
+
+
+def build_or_load_hvg_pca_cache(
+    base_h5ad: str | Path,
+    dataset_name: str,
+    cache_dir: str | Path,
+    *,
+    n_hvg: int = 2000,
+    max_pcs: int = 50,
+    random_state: int = 0,
+) -> Path:
+    cache_dir = Path(cache_dir)
+    _mkdir(cache_dir)
+    out = cache_dir / f"{dataset_name}_HVG{n_hvg}_PCA{max_pcs}.h5ad"
+    if out.exists():
+        logger.info("Using HVG/PCA cache %s", out)
+        return out
+
+    adata = sc.read_h5ad(base_h5ad)
+    n_hvg_use = min(n_hvg, adata.n_vars)
+    sc.pp.highly_variable_genes(adata, n_top_genes=n_hvg_use, flavor="seurat")
+    adata = adata[:, adata.var["highly_variable"]].copy()
+    sc.pp.scale(adata, max_value=10)
+    n_pcs = min(max_pcs, max(2, adata.n_vars - 1), adata.n_obs - 1)
+    sc.tl.pca(adata, n_comps=n_pcs, svd_solver="arpack", random_state=random_state)
+    adata.write_h5ad(out, compression="gzip")
+    return out
+
+
+def run_hvg_pca_sweep(
+    input_file: str | Path,
+    dataset_name: str,
+    cache_dir: str | Path,
+    hvg_values: list[int],
+    pca_values: list[int],
+) -> list[AnnData]:
+    """Build cached AnnData objects for each HVG/PCA combination."""
+    base = build_or_load_base_cache(input_file, dataset_name, cache_dir)
+    results: list[AnnData] = []
+    for n_hvg in hvg_values:
+        for n_pcs in pca_values:
+            path = build_or_load_hvg_pca_cache(base, dataset_name, cache_dir, n_hvg=n_hvg, max_pcs=n_pcs)
+            results.append(sc.read_h5ad(path))
+    return results

campmc/tl/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from campmc.tl.partition import partition
+
+__all__ = ["partition"]

campmc/tl/assign/__init__.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from campmc.tl.assign import camp1, camp2, camp3, camp4
+
+Method = Literal["camp1", "camp2", "camp3", "camp4"]
+
+_DISPATCH = {
+    "camp1": camp1,
+    "camp2": camp2,
+    "camp3": camp3,
+    "camp4": camp4,
+}
+
+
+def get_assigner(method: Method):
+    return _DISPATCH[method]

campmc/tl/assign/camp1.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+import numpy as np
+from sklearn.cluster import KMeans
+
+
+def assign_labels(
+    X: np.ndarray,
+    seed_idx: np.ndarray,
+    *,
+    random_state: int = 0,
+) -> np.ndarray:
+    seed_emb = X[seed_idx]
+    m = seed_emb.shape[0]
+    km = KMeans(
+        n_clusters=m,
+        init=seed_emb,
+        n_init=1,
+        max_iter=10,
+        algorithm="lloyd",
+        random_state=random_state,
+    )
+    km.fit(X)
+    return km.labels_.astype(np.int64)

campmc/tl/assign/camp2.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import numpy as np
+
+
+def _unit_rows(X: np.ndarray) -> np.ndarray:
+    norms = np.linalg.norm(X, axis=1, keepdims=True)
+    norms = np.maximum(norms, 1e-12)
+    return X / norms
+
+
+def assign_labels(
+    X: np.ndarray,
+    seed_idx: np.ndarray,
+    *,
+    random_state: int = 0,
+) -> np.ndarray:
+    del random_state
+    x_unit = _unit_rows(np.asarray(X, dtype=np.float64))
+    seeds = _unit_rows(x_unit[seed_idx])
+    m = seeds.shape[0]
+    bs = 100_000
+    parts: list[np.ndarray] = []
+    for s in range(0, x_unit.shape[0], bs):
+        block = x_unit[s : s + bs] @ seeds.T
+        parts.append(np.argmax(block, axis=1))
+    labels_idx = np.concatenate(parts, axis=0)
+
+    new_seeds = np.zeros_like(seeds)
+    for k in range(m):
+        members = labels_idx == k
+        if np.any(members):
+            c = x_unit[members].mean(axis=0)
+            nrm = np.linalg.norm(c)
+            new_seeds[k] = c / nrm if nrm > 0 else seeds[k]
+        else:
+            new_seeds[k] = seeds[k]
+
+    parts = []
+    for s in range(0, x_unit.shape[0], bs):
+        block = x_unit[s : s + bs] @ new_seeds.T
+        parts.append(np.argmax(block, axis=1))
+    return np.concatenate(parts, axis=0).astype(np.int64)

campmc/tl/assign/camp3.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import numpy as np
+from sklearn.metrics import pairwise_distances
+
+
+def assign_labels(
+    X: np.ndarray,
+    seed_idx: np.ndarray,
+    *,
+    random_state: int = 0,
+    k_scale: int = 15,
+    tau: float = 1.0,
+    batch_size: int = 20_000,
+    eps: float = 1e-8,
+) -> np.ndarray:
+    del random_state
+    x_pca = np.asarray(X, dtype=np.float32)
+    xs = x_pca[seed_idx]
+    m = xs.shape[0]
+    k = max(1, min(k_scale, m - 1))
+
+    d_ss = pairwise_distances(xs, xs, metric="euclidean")
+    sigma_seed = np.partition(d_ss, kth=k, axis=1)[:, k].astype(np.float32)
+    sigma_seed = np.maximum(sigma_seed, eps)
+
+    parts: list[np.ndarray] = []
+    for s in range(0, x_pca.shape[0], batch_size):
+        xu = x_pca[s : s + batch_size]
+        d_us = pairwise_distances(xu, xs, metric="euclidean")
+        sigma_cell = np.partition(d_us, kth=k, axis=1)[:, k].astype(np.float32)
+        sigma_cell = np.maximum(sigma_cell, eps)
+        denom = tau * (sigma_cell[:, None] * sigma_seed[None, :]) + eps
+        w = np.exp(-(d_us**2) / denom, dtype=np.float32)
+        parts.append(np.argmax(w, axis=1))
+
+    return np.concatenate(parts, axis=0).astype(np.int64)

campmc/tl/assign/camp4.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import numpy as np
+import SEACells.build_graph as seacell_build_graph
+from anndata import AnnData
+from scipy.sparse import csr_matrix
+from tqdm import std as tqdm_std
+
+# SEACells uses notebook tqdm, which breaks outside Jupyter.
+seacell_build_graph.tqdm = tqdm_std.tqdm
+
+
+def assign_labels(
+    adata: AnnData,
+    seed_names: list[str],
+    *,
+    reduction_key: str = "X_pca",
+    n_neighbors: int = 30,
+    graph_construction: str = "union",
+    chunk_size: int = 20_000,
+) -> np.ndarray:
+    g = seacell_build_graph.SEACellGraph(adata, reduction_key, verbose=False)
+    k_mat = g.rbf(k=n_neighbors, graph_construction=graph_construction)
+
+    k_mat = k_mat.tocsr()
+    n_sub = adata.n_obs
+    m_seeds = len(seed_names)
+    seed_idx = [adata.obs_names.get_loc(s) for s in seed_names]
+
+    data = np.ones(m_seeds, dtype=np.float32)
+    rows = np.array(seed_idx, dtype=int)
+    cols = np.arange(m_seeds, dtype=int)
+    b_mat = csr_matrix((data, (rows, cols)), shape=(n_sub, m_seeds))
+
+    labels = np.empty(n_sub, dtype=int)
+    for start in range(0, n_sub, chunk_size):
+        end = min(start + chunk_size, n_sub)
+        block = k_mat[start:end, :].dot(b_mat).toarray()
+        labels[start:end] = block.argmax(axis=1)
+    return labels.astype(np.int64)

campmc/tl/partition.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Literal
+
+import numpy as np
+from anndata import AnnData
+
+from campmc._logging import get_logger
+from campmc.coreset import compute_q, gammas_to_m, sample_coreset
+from campmc.tl.assign import camp1, camp2, camp3, camp4
+
+logger = get_logger(__name__)
+
+Method = Literal["camp1", "camp2", "camp3", "camp4"]
+
+
+def _partition_one_batch(
+    adata: AnnData,
+    *,
+    method: Method,
+    gamma: int,
+    m: int,
+    batch_key: str | None,
+    reduction_key: str,
+    random_state: int,
+) -> tuple[np.ndarray, np.ndarray]:
+    labels = np.empty(adata.n_obs, dtype=object)
+    is_seed = np.zeros(adata.n_obs, dtype=bool)
+
+    if batch_key is None or batch_key not in adata.obs:
+        batches = [("__all__", np.arange(adata.n_obs))]
+    else:
+        batches = []
+        for anno in adata.obs[batch_key].astype(str).unique():
+            mask = (adata.obs[batch_key].astype(str) == anno).to_numpy()
+            batches.append((anno, np.where(mask)[0]))
+
+    q_global = compute_q(adata, rep_key=reduction_key)
+
+    for anno, idx in batches:
+        if idx.size <= 1:
+            labels[idx] = f"{anno}-metacell-1"
+            continue
+
+        q_sub = q_global[idx]
+        q_sub = q_sub / q_sub.sum()
+        m_here = min(m, idx.size)
+        local_seed = sample_coreset(idx.size, m_here, q_sub, random_state=random_state)
+        global_seed = idx[local_seed]
+        seeds = adata.obs_names[global_seed].tolist()
+
+        x_emb = np.asarray(adata.obsm[reduction_key][idx])
+        if method == "camp1":
+            lab_local = camp1.assign_labels(x_emb, local_seed, random_state=random_state)
+        elif method == "camp2":
+            lab_local = camp2.assign_labels(x_emb, local_seed, random_state=random_state)
+        elif method == "camp3":
+            lab_local = camp3.assign_labels(x_emb, local_seed, random_state=random_state)
+        else:
+            sub = adata[idx].copy()
+            lab_local = camp4.assign_labels(sub, seeds, reduction_key=reduction_key)
+
+        label_str = [f"seed{lab}-{gamma}-{anno}" for lab in lab_local]
+        labels[idx] = label_str
+        is_seed[global_seed] = True
+
+    return labels, is_seed
+
+
+def partition(
+    adata: AnnData,
+    *,
+    method: Method = "camp1",
+    gamma: int | None = None,
+    gammas: Sequence[int] | None = None,
+    key_added: str = "camp",
+    batch_key: str | None = None,
+    reduction_key: str = "X_pca",
+    random_state: int = 0,
+    copy: bool = False,
+) -> AnnData | None:
+    if reduction_key not in adata.obsm:
+        msg = f"Missing obsm['{reduction_key}']; run campmc.pp.preprocess or add PCA first."
+        raise KeyError(msg)
+    if (gamma is None) == (gammas is None):
+        raise ValueError("Provide exactly one of gamma or gammas.")
+
+    target = adata.copy() if copy else adata
+    meta: dict = {"method": method, "reduction_key": reduction_key, "random_state": random_state}
+
+    if gamma is not None:
+        m = gammas_to_m(target.n_obs, [gamma])[0]
+        labels, is_seed = _partition_one_batch(
+            target,
+            method=method,
+            gamma=gamma,
+            m=m,
+            batch_key=batch_key,
+            reduction_key=reduction_key,
+            random_state=random_state,
+        )
+        target.obs[key_added] = labels
+        target.obs[f"{key_added}_is_seed"] = is_seed
+        meta["gamma"] = gamma
+        meta["m"] = m
+    else:
+        assert gammas is not None
+        meta["gammas"] = list(gammas)
+        for g in gammas:
+            m = gammas_to_m(target.n_obs, [g])[0]
+            labels, is_seed = _partition_one_batch(
+                target,
+                method=method,
+                gamma=g,
+                m=m,
+                batch_key=batch_key,
+                reduction_key=reduction_key,
+                random_state=random_state,
+            )
+            target.obs[f"{key_added}_{g}"] = labels
+            target.obs[f"{key_added}_{g}_is_seed"] = is_seed
+
+    target.uns[key_added] = meta
+    logger.info("partition complete: method=%s key=%s", method, key_added)
+    return target if copy else None

campmc-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,25 @@
+campmc/__init__.py,sha256=ni5zlyMT2jNEjrCqBSRWLeDWWHLC9JjLs1RR-o_6Yzg,435
+campmc/_logging.py,sha256=qt8qwtCqsgrnRjDfaXVeFKkWXCt4m5Vjk1tiuqQs4aQ,400
+campmc/coreset.py,sha256=aPAAkf3kgjAOzuhhbOF1IqwW7pduvwOStC038T5cU0E,1530
+campmc/io.py,sha256=efcHvQ9qAIVtbYlLhIw72Gd-dieoXqYo0WXfp4cbqA4,881
+campmc/metrics/__init__.py,sha256=0JArPO_fvx38oBp4uIbUXK3B8YDiHuPjWPTQzS7iX2Y,102
+campmc/metrics/quality.py,sha256=SIZiFaZEghlkxPxV4HmPAeMEB0Z62lNzjTouI4YgGa0,3484
+campmc/pl/__init__.py,sha256=yc_YTdvzJkkDvBQShnlcu-YX1-49_1qK81lcyJQ6lkY,133
+campmc/pl/plots.py,sha256=8vkPXWEzXsoqh4At0dCwtTBuevt5IKo87fvGtdmQPUs,1168
+campmc/pp/__init__.py,sha256=Jk4W9hlfE5AAp0bbEFVCSqpg52kXDVlBOGlaQCC-d5Y,106
+campmc/pp/preprocess.py,sha256=1jniPi4miC3Z0NuWMhHHf5Q7nbjPKOws3UycBynbe0c,1428
+campmc/rare/__init__.py,sha256=3f9kMUVMsJvV-fFhcBQx0-v7278Xg9b9cHmAaKQ_RVg,160
+campmc/rare/recovery.py,sha256=7NE9Q2WJnyteLUvahqaq2LbRsKz5qDCLYH2dyGxSomo,2226
+campmc/robustness/__init__.py,sha256=kQyC00qIQiy_U7ba9rkBohSDP9zBKLk6qLLKiKRAXEA,255
+campmc/robustness/sweeps.py,sha256=6mYOBIYmi9K3WJy9bpstmdVVcbw_S6T9qot0AL5ogPQ,2775
+campmc/tl/__init__.py,sha256=SDkbHdHobQgr6CWEipKMQcbMt8WDXTGNfbxTocu3bpA,103
+campmc/tl/partition.py,sha256=Lj9Y0A19CTnLw0tDOOlDj22eqFHRRFtfN71hozXHUBc,4147
+campmc/tl/assign/__init__.py,sha256=YuVyX_SjQ5PZM8Cxi7SPjuzljSs-qidqc-JaU15t3-E,336
+campmc/tl/assign/camp1.py,sha256=S_QOJbND51g67E451byXrPA_VSLgjR53m27_IRFKzcQ,482
+campmc/tl/assign/camp2.py,sha256=9xRqq6-2pFBZ33cv58-eDx968VNCeW_hiS9_6hVdtBE,1233
+campmc/tl/assign/camp3.py,sha256=Uy_mij7YonLCxuHvVuVSFJ8PksDii53e-6bvWgrrXC4,1189
+campmc/tl/assign/camp4.py,sha256=F73gFJsdoA-_ihW4QzKCkI4VNklXOue176zx9AvgxbA,1294
+campmc-0.1.0.dist-info/METADATA,sha256=Q5JyRj4fiYYcvumGBXUTuL6CjmPk6a_FJlnDocYXtwE,3496
+campmc-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+campmc-0.1.0.dist-info/licenses/LICENSE,sha256=rtg4nzu6kvO55VOPUn0GpuaKmS2zmkEEcLt7ZZcpYUk,1066
+campmc-0.1.0.dist-info/RECORD,,

campmc-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

campmc-0.1.0.dist-info/licenses/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.