L05 — Multi-Sample Integration

Where this lecture fits

Goals of this lecture

  • Recognize when integration is needed by inspecting the unintegrated UMAP / cluster mix
  • Compare integration tools (Harmony, Seurat anchors, scVI, fastMNN) by what they assume
  • Read the Harmony 4-step iterative algorithm; read the Seurat anchor + L2 + MNN scoring algorithm
  • Diagnose over-correction vs under-correction with three complementary checks
  • Defend the choice of integration method in a methods section

Note

Mental model.

  • Multiple samples / batches / donors of the same biology should produce overlapping clusters of the same cell types.
  • If they don’t — if every sample becomes its own island on the UMAP — the technical axis is dominating PC space.
  • Integration warps the embedding to move shared cell types together while leaving genuine biological differences in place.

When to integrate

  • Multiple samples / batches / donors → the same cell type can split into per-sample clusters
  • Integration aligns shared cell types while preserving real biological differences
  • Diagnostic: color a UMAP by sample. If cell types co-cluster across samples, you don’t need integration. If each sample forms its own island, you do.

Tools to integrate

Tool Ecosystem Approach
Harmony R / Py Iterative soft-clustering in PC space
Seurat CCA / RPCA R Anchor-based cross-sample matching
scVI / scANVI Python Variational autoencoder
BBKNN Python Batch-balanced k-NN graph
MNN / fastMNN R / Py Mutual nearest neighbors

Tip

Rule of thumb:

  • try a simple method (Harmony) first; move to scVI/scANVI for very large or heterogeneous atlases.
  • The workshop’s Tutorial 05 walks Harmony and Seurat anchors on the ifnb dataset (CTRL vs IFN-β-stimulated PBMCs) — the canonical small two-sample integration case.
  • For a complementary, notebook-driven walkthrough see also the scNotebooks integration chapter.

Warning

Over-integration is real.

  • If you push integration too hard, real biological differences (e.g. tumor vs. normal) get squashed away with the batch effect.
  • Always plot both batch and a known biological covariate after integration to confirm only the unwanted axis was removed.

Integration strategies — visual guide

Integration overview — raster reference

Seurat CCA integration

  • Project both samples by canonical correlation analysis (CCA) + L2 normalization into a shared low-rank space
  • Find pairs of cells that are mutual nearest neighbours across the two samples — these are the anchors
  • Score each anchor by how well its local neighbourhoods agree across the two samples
  • Apply the anchor-derived correction to bring matching cell types into register

Harmony integration

  • Operates in PC space after a normal RunPCA() — no extra tooling above the standard workflow
  • Iterates four steps until convergence: (a) soft-cluster cells with a batch-diversity penalty, (b) compute a global centroid and per-batch centroids per cluster, (c) compute correction factors that pull each per-batch centroid toward the global one, (d) shift each cell using its soft-cluster-weighted correction
  • Output is a harmony reduction that drops in for pca in FindNeighbors and RunUMAP

What integration looks like — before vs after

What integration looks like — before vs after

  • Left: raw PCA — the biggest axis is which sample the cell came from, not what cell type it is. Each sample looks like its own island.
  • Right: after integration (Harmony / FastMNN / scVI / …) — cell types align across samples, and the four populations are now distinguishable on PC1/PC2.
  • Diagnostic check: colour the post-integration UMAP by batch. If batches mix within each cluster you’re done. If a cluster is still single-batch, either there’s residual batch effect (push integration harder) or that population truly only exists in one sample (don’t push, you’ll erase real biology).

Warning

The “after” panel above is a cartoon. Real integration warps the embedding non-rigidly — that’s what makes it powerful and what makes over-integration dangerous. Always sanity-check with both batch and a known biological covariate.

Diagnosing over- and under-correction

Three diagnostics, all of which appear in Tutorial 05:

  1. Color the post-integration UMAP by sample. Cells from each sample should interleave within every cluster. Clusters that remain mostly one sample are either (a) under-corrected or (b) genuinely sample-specific biology (e.g. an activated state present only after stimulation).
  2. Color it by a biological covariate. Cell-type labels (or reference-mapped predictions) should occupy single regions. If a cell type fragments into multiple clusters, integration is leaving residual sample structure.
  3. Score a known biological signal at the cell level and check it survives. For ifnb, score each cell on a panel of interferon-stimulated genes (ISG15, IFI6, MX1, …) and confirm STIM cells still score higher than CTRL cells within the same cluster. If integration has flattened that gap, you’ve over-corrected.

These three checks generalize to any batch-integrated dataset. The third is particularly important and easy to forget.

Quantifying integration: mixing metrics

The three checks above are qualitative. Two common numerical scores:

  • iLISI / LISI (Local Inverse Simpson’s Index)
    • within each cell’s neighbourhood, how many batches are represented.
    • High iLISI = batches well mixed. Pair it with cLISI (cell-type LISI), which should stay low (each neighbourhood is one cell type).
    • Good integration = high iLISI and low cLISI.
  • kBET — tests whether the batch composition of local neighbourhoods matches the global composition (a rejection rate; lower = better mixed).

Warning

A mixing metric alone can be gamed by over-correction

  • blend distinct cell types and iLISI looks great.
  • Always read a mixing score together with a biology-preservation check (cLISI, or the ISG-score gap on the next slides), never one alone.

ISG score gap survives integration — the over-correction check

The integration moved cells spatially (the bottom panels of the previous figure) without erasing the IFN-β biology (ISG score still STIM > CTRL within every cluster). That’s the right outcome.

Tip

This is the most important diagnostic and the one most often skipped. Always run a known biological signal through the post-integration object and confirm the signal survives. Pretty UMAPs are not the same as preserved biology.

Recap & what’s next

What to remember from Lecture 05

  • Integration is always an editorial choice — pick the simplest method that works, then check you didn’t over-correct
  • Harmony corrects in PC space iteratively; Seurat anchors finds mutual nearest neighbours after CCA
  • The over-correction check that matters: a known biological signal (e.g. ISG score) should still differ between conditions within the same cluster after integration
  • Always plot the post-integration UMAP coloured by batch AND by biology — both dimensions