# User guide

This page summarizes the usual **campmc** workflow and what each CAMP method does.
For full signatures, see the {doc}`api/index`.

## Typical workflow

1. **Prepare embeddings** — either use an object that already has ``obsm['X_pca']``
   (e.g. Scanpy’s reduced PBMC datasets), or run {func}`campmc.preprocess` on
   raw counts.
2. **Partition** — call {func}`campmc.partition` with a method and compression
   factor ``gamma`` (target cells per metacell).
3. **Evaluate** — use {func}`campmc.mt.quality` (and optionally
   {func}`campmc.mt.recovery_scores`) against reference labels.

See {doc}`tutorials/partition_pbmc68k` for a runnable walkthrough, or the API
pages for executable examples on each function.

```{eval-rst}
.. exec-jupyter::

 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()
```

## 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.

## Related helpers

- {mod}`campmc.pl` — partition assignment and size-distribution plots, plus ECDF / line plots of metric tables