User guide

User guide#

This page summarizes the usual campmc workflow and what each CAMP method does. For full signatures, see the API reference.

Typical workflow#

  1. Prepare embeddings — either use an object that already has obsm['X_pca'] (e.g. Scanpy’s reduced PBMC datasets), or run campmc.preprocess() on raw counts.

  2. Partition — call campmc.partition() with a method and compression factor gamma (target cells per metacell).

  3. Evaluate — use campmc.mt.quality() (and optionally campmc.mt.recovery_scores()) against reference labels.

See Partition PBMC 68k (reduced) for a runnable walkthrough, or the API pages for executable examples on each function.

import campmc as cp
import scanpy as sc
adata = sc.datasets.pbmc68k_reduced()
cp.partition(adata, method="camp3", gamma=25, random_state=0)
cp.mt.quality(adata, partition_key="camp", label_key="louvain")[["metacell_id", "size", "purity"]].head()
metacell_id size purity
0 seed0-25-__all__ 57 1.000000
1 seed1-25-__all__ 34 0.911765
2 seed10-25-__all__ 2 1.000000
3 seed11-25-__all__ 42 0.857143
4 seed12-25-__all__ 25 0.840000

Choosing gamma#

gamma is the target number of cells per metacell. The coreset size is m ≈ n / gamma:

gamma

Effect

Smaller (e.g. 10–25)

More metacells, finer resolution

Larger (e.g. 50–100)

Fewer metacells, stronger compression

Pass gammas=[10, 25, 50] instead of gamma to store several partitions on the same object (columns camp_10, camp_25, …).

CAMP methods#

All methods share the same coreset seed sampling; they differ in how cells are assigned to seeds:

Method

Assignment idea

Notes

camp1

Short k-means initialized at seeds

Fast baseline

camp2

Cosine nearest seed + one centroid update

Good default for speed

camp3

Adaptive RBF weights over seed distances

Often a strong default

camp4

SEACells kernel graph from seeds

Slower; needs SEACells

Use method="camp3" unless you have a reason to compare variants.

AnnData keys#

After a single-gamma run with default key_added="camp":

Location

Contents

adata.obs['camp']

Metacell label per cell

adata.obs['camp_is_seed']

Whether the cell was a coreset seed

adata.uns['camp']

Run metadata (method, gamma, …)

With batch_key, partitioning is performed independently inside each batch and labels include the batch annotation.