truecell 0.9.0__tar.gz

truecell-0.9.0/.claude/skills/README.md

@@ -0,0 +1,69 @@
+# truecell agent skills
+
+Ten skills that teach an LLM agent to use `truecell` correctly — the API contracts
+that break code silently, the decisions each analysis step forces, and the
+places truecell and R Seurat genuinely differ.
+
+They are plain Markdown with YAML frontmatter, so they work as
+[Claude Agent Skills](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview)
+and as context for any other model.
+
+## The set
+
+| Skill | Load it for |
+|---|---|
+| [`truecell`](truecell/SKILL.md) | **Start here.** Install, the six API contracts, the canonical pipeline, routing. Bundles the full [API map](truecell/reference/api-map.md) and [object model](truecell/reference/object-model.md). |
+| [`truecell-workflow`](truecell-workflow/SKILL.md) | A standard scRNA-seq run: QC thresholds, LogNormalize vs SCTransform, how many PCs, resolution, annotation. |
+| [`truecell-differential-expression`](truecell-differential-expression/SKILL.md) | Marker genes, the eight `test_use` options, pseudobulk, conserved markers. |
+| [`truecell-integration`](truecell-integration/SKILL.md) | Batch correction (Harmony/CCA/RPCA), label transfer, reference mapping, and scoring whether it worked. |
+| [`truecell-multimodal`](truecell-multimodal/SKILL.md) | CITE-seq + WNN, cell hashing, pooled CRISPR (Mixscape). Includes the CLR `margin` rule. |
+| [`truecell-spatial`](truecell-spatial/SKILL.md) | Xenium / Visium / CosMx / MERSCOPE, niches, spatially variable features, spatial plots. |
+| [`truecell-at-scale`](truecell-at-scale/SKILL.md) | Leverage sketching and on-disk `LazyMatrix`, for data that doesn't fit in RAM. |
+| [`truecell-plotting`](truecell-plotting/SKILL.md) | All 17 plotting functions, their Seurat equivalents, and headless saving. |
+| [`truecell-from-seurat`](truecell-from-seurat/SKILL.md) | Porting R Seurat code, and comparing the two tools' numbers honestly. |
+| [`truecell-dev`](truecell-dev/SKILL.md) | Contributing to truecell itself: tests, lint, docs, the fidelity apparatus, release conventions. |
+
+Each `SKILL.md` stands alone. The router skill points at the others but does not
+depend on them being loaded.
+
+## Using them
+
+### Claude Code
+
+`.claude/skills` in this repo is a symlink to this directory, so the skills are
+discovered automatically when Claude Code runs here. To use them from another
+project:
+
+```bash
+ln -s /path/to/truecell/skills ~/.claude/skills/truecell
+```
+
+Or copy individual skill directories into `.claude/skills/`.
+
+### Claude.ai / Projects
+
+Upload the `SKILL.md` files (and `truecell/reference/*.md`) as project knowledge.
+Names and descriptions in the frontmatter are what make the right one surface.
+
+### Any other model
+
+Concatenate what the task needs — the router plus one domain skill is usually
+enough, and the whole set is small:
+
+```bash
+cat skills/truecell/SKILL.md skills/truecell-workflow/SKILL.md
+cat skills/truecell/reference/api-map.md          # when parameter names matter
+```
+
+## Keeping them true
+
+Every signature, default and measured number in these files came from the
+package or from a recorded R comparison, not from memory. When the API changes,
+the places to re-derive are:
+
+```bash
+python -c "import truecell, inspect; print([n for n in truecell.__all__])"
+python -c "import truecell, inspect; print(inspect.signature(truecell.find_markers))"
+```
+
+and, for the fidelity claims, <https://genomicai.github.io/truecell/fidelity/>.

truecell-0.9.0/.claude/skills/truecell/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: truecell
+description: Use when writing, reading, debugging or reviewing Python single-cell analysis code that uses the truecell package (a port of R Seurat) — creating Truecell objects, the QC → normalize → HVG → scale → PCA → neighbours → clusters → UMAP → markers pipeline, or translating Seurat code to Python. Start here; it carries the API contracts that break code silently and routes to the task-specific truecell skills.
+---
+
+# truecell
+
+`truecell` is a Python port of [Seurat](https://satijalab.org/seurat/) v5 — the same
+data structures and the same algorithms, checked against R Seurat 5.5.1 test by
+test. Version **0.9.0**, Python **3.12+**, MIT.
+
+- Docs: <https://genomicai.github.io/truecell/> · Repo: <https://github.com/GenomicAI/truecell>
+- 105 public names, all exported from the package root **except the generics**
+  (see contract 6 below).
+
+```bash
+pip install truecell                 # core: objects, preprocessing, PCA, markers
+pip install "truecell[analysis]"     # + clustering, UMAP, plotting  ← the usual one
+pip install "truecell[anndata]"      # + AnnData interop
+pip install "truecell[integration]"  # + Harmony (harmonypy)
+pip install "truecell[deseq2]"       # + pseudobulk DESeq2
+pip install "truecell[all]"          # everything, incl. dev + docs tooling
+```
+
+## The six contracts
+
+Almost every mistake made against this API is one of these. Check them before
+writing anything.
+
+**1. Analysis functions mutate in place and return `None`.**
+
+```python
+truecell.normalize_data(pbmc)          # correct — call for effect
+pbmc = truecell.normalize_data(pbmc)   # WRONG — pbmc is now None
+```
+
+Applies to `normalize_data`, `find_variable_features`, `scale_data`,
+`percentage_feature_set`, `run_pca` / `run_ica` / `run_spca` / `run_tsne` /
+`glm_pca`, `find_neighbors`, `find_multi_modal_neighbors`, `find_clusters`,
+`run_umap`, `run_harmony`, `integrate_layers`.
+
+Rebind **only** for the functions that build a new object:
+`subset`, `merge`, `sketch_data`, `integrate_data`.
+
+A third group mutates in place *and* returns the same object it mutated
+(`sctransform`, `add_module_score`, `cell_cycle_scoring`, `hto_demux`,
+`multiseq_demux`, `calc_perturb_sig`, `run_mixscape`, `mixscape_lda`). Rebinding
+is harmless there but is not the idiom — call for effect everywhere except the
+four above.
+
+Functions that compute a *result* rather than mutating return it: `find_markers`,
+`find_all_markers`, `find_conserved_markers`, `aggregate_expression`,
+`transfer_data`, `find_spatially_variable_features`, `composition_test`,
+`leverage_score`, and every plotting function (→ `matplotlib.figure.Figure`).
+
+**2. `dims` is 0-based.** `range(10)` here is `1:10` in R. This is the one
+indexing difference in the API and it follows Python on purpose.
+
+**3. Matrices are features × cells** — genes as rows, same as Seurat, transposed
+relative to AnnData/scanpy. `create_truecell_object(counts, ...)` expects
+genes × cells.
+
+**4. Expression lives in named layers**, not attributes: `counts` (raw),
+`data` (log-normalized), `scale.data` (z-scored). Read them with
+`obj.get_assay().layer_data("data")`.
+
+**5. Names are snake_case ports of Seurat's**: `FindMarkers` → `find_markers`,
+`RunPCA` → `run_pca`, `nn.method` → `nn_method`. Parameters that collide with
+Python keywords get a trailing underscore (`lambda_`, `type_`).
+
+**6. The generics are not top-level.** `cells`, `features`, `idents`,
+`fetch_data`, `layer_data`, `layers`, `split_layers`, `join_layers`,
+`embeddings`, `loadings`, `stdev`, `variable_features`, `which_cells`,
+`rename_idents` and the rest live in `truecell.generics`:
+
+```python
+import truecell
+truecell.generics.features(pbmc)     # correct
+truecell.features(pbmc)              # AttributeError
+```
+
+Same for the loaders: `from truecell.io import read_10x`,
+`from truecell.datasets import pbmc3k`, `from truecell.compat.anndata import as_anndata`.
+(The published API reference says everything is top-level; for the generics page
+that is not true.)
+
+## The canonical pipeline
+
+```python
+import truecell
+from truecell.datasets import pbmc3k
+
+counts, genes, cells = pbmc3k()            # caches to ~/.truecell_data/ (~24 MB)
+pbmc = truecell.create_truecell_object(
+    counts=counts, feature_names=genes, cell_names=cells,
+    project="pbmc3k", min_cells=3, min_features=200,
+)
+
+# QC
+truecell.percentage_feature_set(pbmc, pattern=r"^MT-", col_name="percent.mt")
+md = pbmc.meta_data
+keep = (md["nFeature_RNA"] > 200) & (md["nFeature_RNA"] < 2500) & (md["percent.mt"] < 5)
+pbmc = pbmc.subset(cells=list(md.index[keep]))     # subset RETURNS a new object
+
+# Normalize → select → scale
+truecell.normalize_data(pbmc, normalization_method="LogNormalize", scale_factor=10000)
+truecell.find_variable_features(pbmc, selection_method="vst", nfeatures=2000)
+truecell.scale_data(pbmc)                    # defaults to the variable features
+
+# Reduce → graph → cluster → embed
+truecell.run_pca(pbmc, n_pcs=50)
+truecell.find_neighbors(pbmc, dims=range(10), k_param=20)   # writes RNA_nn, RNA_snn
+truecell.find_clusters(pbmc, resolution=0.5)                # writes seurat_clusters + idents
+truecell.run_umap(pbmc, dims=range(10), seed=42)
+
+# Markers
+markers = truecell.find_all_markers(pbmc, only_pos=True, min_pct=0.25, logfc_threshold=0.25)
+
+fig = truecell.dim_plot(pbmc, reduction="umap", label=True)
+fig.savefig("umap.png", dpi=150, bbox_inches="tight")
+```
+
+Where results land: `pbmc.meta_data` (per-cell columns), `pbmc.reductions`
+(`"pca"`, `"umap"`), `pbmc.graphs` (`"RNA_nn"`, `"RNA_snn"`), `pbmc.idents`,
+`pbmc.commands` (the audit log), `pbmc.misc` (stashed fit details).
+
+## Which skill to load
+
+| Task | Skill |
+|---|---|
+| Standard scRNA-seq run, QC thresholds, how many PCs, resolution choice | `truecell-workflow` |
+| Marker genes, the eight DE tests, pseudobulk, conserved markers | `truecell-differential-expression` |
+| Batch correction (Harmony/CCA/RPCA), label transfer, reference mapping | `truecell-integration` |
+| CITE-seq / WNN, cell hashing demultiplexing, pooled CRISPR (Mixscape) | `truecell-multimodal` |
+| Xenium / Visium / CosMx / MERSCOPE, niches, spatially variable features | `truecell-spatial` |
+| Datasets too big for RAM — leverage sketching, on-disk `LazyMatrix` | `truecell-at-scale` |
+| Any figure | `truecell-plotting` |
+| Porting existing R Seurat code, or comparing the two tools' output | `truecell-from-seurat` |
+| Contributing to truecell itself — tests, lint, docs, fidelity method, release | `truecell-dev` |
+
+## Bundled reference
+
+- [`reference/api-map.md`](reference/api-map.md) — every public function with its
+  real signature and its Seurat equivalent. Read this before guessing a parameter name.
+- [`reference/object-model.md`](reference/object-model.md) — the `Truecell` /
+  `Assay5` / `DimReduc` / `Graph` containers, the generics, subsetting, layers,
+  AnnData interop.
+
+## Known, deliberate differences from Seurat
+
+Not bugs; do not "fix" them, and do not report them as regressions.
+
+- **Louvain cluster counts drift by one.** Same algorithm, same resolution,
+  different local optimum. PBMC 3k: 8 clusters to Seurat's 9 at ARI 0.938.
+- **Variable-feature selection jitters at the boundary.** 1,998 of 2,000 genes
+  shared on PBMC 3k; the two that swap sit at ranks ~1916–2016 where
+  standardized variances agree to three decimals.
+- **Anything with an RNG differs by its RNG and only by that.**
+  `add_module_score` draws control genes at random (96.6 % phase concordance,
+  Pearson ≥ 0.998 on the scores); `jack_straw` permutes.
+- **truecell's neighbour search is exact; Seurat's default `annoy` is approximate.**
+  When comparing, pass `nn.method = "rann"` on the R side.
+
+Full evidence, with the numbers: <https://genomicai.github.io/truecell/fidelity/>.

truecell-0.9.0/.claude/skills/truecell/reference/api-map.md

@@ -0,0 +1,304 @@
+# truecell API map
+
+Every public function, with its real signature and its Seurat equivalent.
+Signatures are from `truecell` 0.9.0. `seurat` / `obj` as the first parameter means
+a `Truecell` object.
+
+**Read the return column.** `None` means the function mutates in place — see
+contract 1 in the parent skill.
+
+---
+
+## Objects
+
+| Seurat | truecell |
+|---|---|
+| `CreateSeuratObject` | `create_truecell_object` |
+| `CreateAssayObject` | `create_assay_object` / `create_assay5_object` |
+| `Seurat`, `Assay`, `Assay5`, `DimReduc`, `Graph`, `Neighbor` | same class names |
+
+```python
+create_truecell_object(counts, assay="RNA", min_cells=0, min_features=0,
+                     project="SeuratProject", feature_names=None, cell_names=None,
+                     meta_data=None, use_v5=True) -> Truecell
+create_assay_object(counts=None, data=None, min_cells=0, min_features=0,
+                    feature_names=None, cell_names=None, key="rna_") -> Assay
+create_assay5_object(...same...) -> Assay5
+log_truecell_command(object_, func_name, params=None, assay=None, reduction=None) -> TruecellCommand
+as_graph(x, cell_names=None, assay_used=None, weighted=True) -> Graph
+```
+
+Classes exported: `Truecell`, `Assay`, `Assay5`, `StdAssay`, `DimReduc`, `Graph`,
+`Neighbor`, `JackStrawData`, `LogMap`, `KeyMixin`, `TruecellCommand`.
+
+## Loading data
+
+Not top-level — import from the submodule.
+
+```python
+from truecell.io import read_10x
+read_10x(data_dir, var_names="gene_symbols", make_unique=True) -> (csc_matrix, genes, cells)
+
+from truecell.datasets import pbmc3k, pbmc8k, cbmc_citeseq, pbmc_hashing, thp1_eccite, \
+                            ifnb, panc8, xenium_mouse_brain, visium_mouse_brain
+pbmc3k(data_dir=None, force_download=False) -> (counts, genes, cells)
+cbmc_citeseq(data_dir=None, force_download=False, species_prefix="HUMAN_")
+xenium_mouse_brain(...) -> Path     # loaders that return a directory
+visium_mouse_brain(...) -> Path
+ifnb(data_dir=None); panc8(data_dir=None)   # need `Rscript tutorials/export_seuratdata.R <name>` once
+```
+
+Everything caches to `~/.truecell_data/` (~770 MB for the full set).
+
+```python
+from truecell.compat.anndata import as_anndata, from_anndata
+as_anndata(seurat, assay=None)
+from_anndata(adata, assay="RNA", spatial_key="spatial", fov_key="fov") -> Truecell
+```
+
+## Preprocessing
+
+| Seurat | truecell | Returns |
+|---|---|---|
+| `PercentageFeatureSet` | `percentage_feature_set` | `None` |
+| `NormalizeData` | `normalize_data` | `None` |
+| `FindVariableFeatures` | `find_variable_features` | `None` |
+| `ScaleData` | `scale_data` | `None` |
+| `SCTransform` | `sctransform` | the object |
+
+```python
+percentage_feature_set(seurat, pattern, col_name=None, assay=None, layer="counts") -> None
+normalize_data(seurat, normalization_method="LogNormalize", scale_factor=10000.0,
+               assay=None, margin=1) -> None
+find_variable_features(seurat, selection_method="vst", nfeatures=2000, assay=None,
+                       layer=None, mean_cutoff=(0.1, 8), dispersion_cutoff=(1, inf),
+                       num_bin=20, binning_method="equal_width") -> None
+scale_data(seurat, features=None, vars_to_regress=None, assay=None, do_scale=True,
+           do_center=True, scale_max=10.0, layer="data") -> None
+sctransform(seurat, assay=None, new_assay_name="SCT", n_cells=5000, n_genes=2000,
+            n_features=3000, min_cells=5, vars_to_regress=None, clip_range=None,
+            gene_chunk=500, seed=42, set_default=True, vst_flavor="v2",
+            bw_adjust=3.0, verbose=False)
+```
+
+- `normalization_method`: `"LogNormalize"`, `"CLR"`, `"RC"`. `margin=1` = per
+  feature, `2` = per cell (matters for CLR on protein/HTO assays).
+- `selection_method`: `"vst"` (default; honours `nfeatures`), `"mvp"` /
+  `"dispersion"` (honours `mean_cutoff` / `dispersion_cutoff` instead).
+- `scale_data(features=None)` scales the **variable features**, as Seurat does.
+  Pass `features=truecell.generics.features(obj)` for `ScaleData(features = rownames(obj))`.
+- `vst_flavor="v2"` is Seurat 5's model; `"v1"` is the 2019 one.
+
+## Dimensional reduction
+
+| Seurat | truecell |
+|---|---|
+| `RunPCA` | `run_pca` |
+| `RunICA` | `run_ica` |
+| `RunSPCA` | `run_spca` |
+| `RunTSNE` | `run_tsne` |
+| `RunUMAP` | `run_umap` |
+| `JackStraw` / `ScoreJackStraw` | `jack_straw` / `score_jackstraw` |
+
+```python
+run_pca(seurat, n_pcs=50, features=None, assay=None, reduction_name="pca",
+        reduction_key="PC_", seed=42, layer="scale.data") -> None
+run_ica(seurat, nics=50, ..., reduction_name="ica", reduction_key="ICA_", max_iter=200) -> None
+run_spca(seurat, graph, npcs=50, ..., reduction_name="spca") -> None     # graph is required
+run_tsne(seurat, dims=None, reduction="pca", n_components=2, perplexity=30.0,
+         reduction_name="tsne", seed=42, assay=None) -> None
+run_umap(seurat, dims=None, reduction="pca", graph=None, n_components=2,
+         n_neighbors=30, min_dist=0.3, metric="euclidean", reduction_name="umap",
+         reduction_key="UMAP_", seed=42, assay=None) -> None
+glm_pca(seurat, n_components=10, features=None, assay=None, reduction_name="glmpca",
+        family="poisson", layer="counts", max_iter=100, tol=1e-4, penalty=1.0,
+        learning_rate=0.1, theta=100.0, optimize_theta=True, seed=42) -> None
+jack_straw(seurat, reduction="pca", dims=20, num_replicate=100, prop_freq=0.01,
+           layer="scale.data", seed=42) -> JackStrawData
+score_jackstraw(seurat, reduction="pca", dims=None, score_thresh=1e-5) -> np.ndarray
+```
+
+`run_umap` takes **either** `dims=` on a reduction **or** `graph=` (a graph name),
+matching `RunUMAP`'s two modes. `glm_pca` runs on `counts`, not scaled data.
+
+## Graphs and clustering
+
+```python
+find_neighbors(seurat, dims=None, k_param=20, assay=None, reduction="pca",
+               graph_name=None, nn_name=None, prune_snn=1/15, seed=42) -> None
+find_clusters(seurat, resolution=0.5, algorithm=1, graph_name=None, random_seed=0,
+              n_iterations=-1, group_singletons=True) -> None
+find_multi_modal_neighbors(seurat, reduction_list=("pca", "apca"), dims_list=None,
+                           k_nn=20, l2_norm=True, knn_graph_name="wknn",
+                           snn_graph_name="wsnn", knn_range=200, prune_snn=1/15,
+                           sd_scale=1.0, cross_constant=None, smooth=False, seed=42) -> None
+```
+
+- `find_neighbors` writes `graphs["{assay}_nn"]` and `graphs["{assay}_snn"]`.
+- `find_clusters` reads `{assay}_snn` unless `graph_name=` is given, and writes
+  `meta_data["seurat_clusters"]` plus the active identity.
+- `algorithm`: **1** = Louvain (default), **2** = Louvain multilevel,
+  **4** = Leiden. **3 (SLM) is not implemented.**
+- `group_singletons=True` absorbs size-1 clusters into their best-connected
+  neighbour, as Seurat's `GroupSingletons` does.
+
+## Differential expression → `truecell-differential-expression`
+
+```python
+find_markers(seurat, ident_1, ident_2=None, assay=None, layer=None, test_use="wilcox",
+             only_pos=False, min_pct=0.1, logfc_threshold=0.25, features=None,
+             latent_vars=None, sample_col=None, max_cells_per_ident=None,
+             random_seed=1) -> pd.DataFrame
+find_all_markers(seurat, assay=None, layer=None, test_use="wilcox", only_pos=False,
+                 min_pct=0.1, logfc_threshold=0.25, sample_col=None,
+                 max_cells_per_ident=None, random_seed=1, return_thresh=0.01) -> pd.DataFrame
+find_conserved_markers(seurat, ident_1, grouping_var, ident_2=None, assay=None,
+                       layer=None, test_use="wilcox", only_pos=False, min_pct=0.1,
+                       logfc_threshold=0.25, features=None) -> pd.DataFrame
+aggregate_expression(seurat, group_by="ident", assays=None, features=None,
+                     layer="counts", return_object=False)
+```
+
+`test_use`: `wilcox` · `t` · `bimod` · `LR` · `negbinom` · `mast` · `deseq2` · `roc`.
+
+## Integration and mapping → `truecell-integration`
+
+```python
+run_harmony(seurat, group_by, reduction="pca", dims=None, reduction_name="harmony",
+            reduction_key="harmony_", theta=None, lambda_=None, sigma=0.1,
+            nclust=None, max_iter_harmony=10, assay=None, seed=0) -> None
+integrate_layers(seurat, method="harmony", orig_reduction="pca", new_reduction=None,
+                 group_by=None, assay=None, **kwargs) -> None
+find_integration_anchors(objects, anchor_features=None, reduction="cca", dims=30,
+                         k_anchor=5, k_filter=200, k_score=30, reference=0,
+                         layer="scale.data", seed=42) -> IntegrationAnchors
+integrate_data(anchors, new_assay="integrated", k_weight=100, sd_weight=1.0,
+               add_cell_ids=None, seed=42)            # returns a NEW object
+integrate_embeddings(anchors, reduction, new_reduction="integrated_dr",
+                     dims_to_integrate=None, k_weight=100, sd_weight=1.0) -> DimReduc
+find_transfer_anchors(reference, query, anchor_features=None, reduction="pcaproject",
+                      dims=30, k_anchor=5, k_filter=200, k_score=30,
+                      layer="scale.data", seed=42) -> TransferAnchors
+transfer_data(anchors, refdata, k_weight=50, sd_weight=1.0,
+              refdata_features=None) -> pd.DataFrame
+map_query(anchors, refdata=None, reference_reduction="pca", reduction_model="umap",
+          reduction_name="ref.umap", reduction_key="refUMAP_", k_weight=50,
+          sd_weight=1.0, refdata_features=None, layer="scale.data")
+project_umap(query, reference, reduction="pca", umap_reduction="umap", dims=None,
+             reduction_name="ref.umap", reduction_key="refUMAP_", layer="scale.data") -> DimReduc
+```
+
+`integrate_layers(method=)`: `"harmony"` · `"cca"` · `"rpca"`. `group_by=` is
+required for every method.
+
+## Signature scoring
+
+```python
+add_module_score(seurat, features, pool=None, nbin=24, ctrl=100, name="Cluster",
+                 assay=None, layer="data", seed=1, search=False)
+cell_cycle_scoring(seurat, s_features=None, g2m_features=None, assay=None,
+                   layer="data", set_ident=False, nbin=24, ctrl=100, seed=1)
+CC_GENES     # the Tirosh 2016 human S / G2M sets, used when the args are None
+```
+
+`features` for `add_module_score` is a gene list, a list of gene lists, or a
+`{name: genes}` dict. Columns land as `{name}1`, `{name}2`, … or the dict keys.
+`cell_cycle_scoring` writes `S.Score`, `G2M.Score`, `Phase`.
+
+## Demultiplexing and screens → `truecell-multimodal`
+
+```python
+hto_demux(seurat, assay="HTO", positive_quantile=0.99, init=None, nstarts=10,
+          kfunc="clara", nsamples=100, normalize=True, margin=1, seed=42, verbose=False)
+multiseq_demux(seurat, assay="HTO", quantile=0.7, autothresh=False, maxiter=5,
+               qrange=None, normalize=True, margin=1, verbose=False)
+calc_perturb_sig(seurat, assay="RNA", features=None, layer="data", labels="gene",
+                 nt_class="NT", split_by=None, num_neighbors=20, reduction="pca",
+                 ndims=15, new_assay="PRTB")
+run_mixscape(seurat, assay="PRTB", labels="gene", nt_class="NT", de_assay="RNA",
+             layer="data", min_de_genes=5, min_cells=5, logfc_threshold=0.25,
+             min_pct=0.05, pval_cutoff=0.05, iter_num=10, prtb_type="KO",
+             new_class="mixscape_class", de_test="wilcox", seed=0, verbose=False)
+mixscape_lda(seurat, labels="gene", nt_class="NT", assay="PRTB", de_assay="RNA",
+             layer="data", npcs=10, logfc_threshold=0.25, min_pct=0.1,
+             pval_cutoff=0.05, de_test="wilcox", reduction_name="lda",
+             reduction_key="LDA_", scale_max=10.0, seed=42, verbose=False)
+```
+
+## Spatial → `truecell-spatial`
+
+```python
+load_xenium(path, assay="Xenium", fov_column=None, project="Xenium", keep_controls=False)
+load_visium(path, assay="Spatial", project="Visium", image=True,
+            image_resolution="lowres", filter_by_tissue=True, slice_name="slice1")
+load_cosmx(path, expr_file=None, meta_file=None, assay="Nanostring",
+           fov_column="fov", project="CosMx")
+load_merscope(path, expr_file=None, meta_file=None, assay="Vizgen",
+              fov_column="fov", project="MERSCOPE", keep_controls=False)
+
+create_centroids(coords, nsides=0, radius=None, theta=None, assay="", key="centroids_")
+create_segmentation(coords, assay="", key="segmentation_")
+create_molecules(coords, assay="", key="molecules_")
+create_fov(coords, type_="centroids", nsides=0, radius=None, theta=None, assay="", key="fov_")
+create_fovs(coords, fov=None, assay="", default_name="fov") -> dict[str, FOV]
+
+get_tissue_coordinates(seurat, image=None) -> pd.DataFrame
+spatial_knn(coords, k=10, query=None) -> (distances, indices)
+nearest_neighbor_distance(seurat, group_by, reference, target=None, image=None) -> pd.DataFrame
+local_neighborhood(seurat, group_by, reference=None, k=10, image=None) -> pd.DataFrame
+build_niche_assay(seurat, group_by, image=None, k=20, niches=4, assay_name="niche",
+                  cluster=True, seed=0)
+find_spatially_variable_features(seurat, features=None, method="moransi", k=10,
+                                 weights="inverse_square", assay=None, layer=None,
+                                 image=None, r_metric=5.0, bandwidth=1.0) -> pd.DataFrame
+composition_test(seurat, group_by, split_by, reference=None) -> pd.DataFrame
+```
+
+Spatial classes: `SpatialImage`, `Centroids`, `Segmentation`, `Molecules`, `FOV`,
+`VisiumV2`, `ScaleFactors`.
+
+## Scale → `truecell-at-scale`
+
+```python
+leverage_score(obj, nsketch=5000, ndims=None, features=None, assay=None, layer="data",
+               var_name="leverage.score", eps=0.5, seed=123) -> np.ndarray
+sketch_data(obj, ncells=5000, method="LeverageScore", features=None, assay=None,
+            layer="data", nsketch=5000, sketched_assay="sketch",
+            var_name="leverage.score", seed=123)        # returns a NEW object
+project_data(full, sketch, reduction="pca", full_reduction="pca.full",
+             umap_reduction="umap", full_umap_reduction="ref.umap", refdata=None,
+             project_umap=True, dims=None, k_weight=50, sd_weight=1.0,
+             layer="scale.data")
+write_lazy_matrix(matrix, path, *, overwrite=False) -> LazyMatrix
+open_lazy_matrix(path) -> LazyMatrix
+is_lazy(x) -> bool
+```
+
+## Plotting → `truecell-plotting`
+
+All 17 return a `matplotlib.figure.Figure`.
+
+`vln_plot` · `feature_plot` · `dim_plot` · `elbow_plot` · `feature_scatter` ·
+`variable_feature_plot` · `viz_dim_loadings` · `dim_heatmap` · `do_heatmap` ·
+`ridge_plot` · `dot_plot` · `image_dim_plot` · `image_feature_plot` ·
+`spatial_dim_plot` · `spatial_feature_plot` · `plot_perturb_score` ·
+`mixscape_heatmap`
+
+## Generics (`truecell.generics.*`, not top-level)
+
+`cells` · `features` · `idents` · `set_ident` · `stash_ident` · `rename_idents` ·
+`reorder_ident` · `which_cells` · `fetch_data` · `layer_data` · `set_layer_data` ·
+`layers` · `split_layers` · `join_layers` · `get_assay_data` · `set_assay_data` ·
+`embeddings` · `loadings` · `set_loadings` · `stdev` · `variable_features` ·
+`set_variable_features` · `hvf_info` · `default_assay` · `set_default_assay` ·
+`set_default_layer` · `key` · `set_key` · `keys` · `assay_names` · `assay_class` ·
+`cast_assay` · `add_meta_data` · `rename_cells` · `match_cells` · `calc_n` ·
+`command` · `misc` / `set_misc` · `tool` / `set_tool` · `version` · `as_sparse` ·
+`as_graph` · `as_neighbor` · `as_seurat` · `check_matrix` · `is_matrix_empty` ·
+`simplify` · `stitch_matrix` · `distances` · `indices` ·
+spatial: `boundaries` · `crop` · `overlay` · `radius` · `theta` · `get_image` ·
+`get_molecules` · `get_tissue_coordinates` · `default_boundary` · `default_fov` ·
+`is_global` · `as_centroids` · `as_segmentation` · `create_fov` · `create_centroids` ·
+`create_segmentation`
+
+See [`object-model.md`](object-model.md) for what each dispatches on.