sc-batch-integration

sc-batch-integration

When to use

The user has a merged multi-sample AnnData (post-sc-multi-count or similar) and needs to remove batch effects so downstream clustering / annotation isn't dominated by per-sample technical variation. Seven backends share one CLI: harmony (default), scvi, scanvi (requires labels), bbknn, scanorama, simba, plus R-backed methods (e.g. Seurat integration anchors). Quality is reported as LISI / ASW diagnostics when available.

Inputs & Outputs

Inputs

• Modalities: scrna
• File types: .h5ad
• Requires a preprocessed AnnData (X normalised, PCA/neighbours present)

Outputs

• tables/batch_mixing_matrix.csv
• tables/batch_sizes.csv
• tables/cell_metadata.csv
• tables/cluster_sizes.csv
• tables/embedding.csv
• tables/integration_metrics.csv
• tables/integration_summary.csv
• tables/obs.csv
• tables/umap.csv
• tables/umap_points.csv
• figures/batch_mixing_heatmap.png
• figures/integration_metrics.png
• figures/r_embedding_discrete.png
• analysis_summary.txt
• input.h5ad
• processed.h5ad
• report.md
• result.json
• Processed AnnData (saves_h5ad) — adds obsm: X_<method>, X_pca

Flow

1. Load merged AnnData; resolve --batch-key (default batch).
2. Validate backend prerequisites (e.g. scanvi needs --labels-key).
3. Run the chosen --method; write the integrated embedding to obsm["X_<method>"] (BBKNN is the exception — it adjusts the neighbour graph in-place and leaves the embedding as obsm["X_pca"]).
4. Compute LISI / ASW diagnostics (best-effort; non-fatal if unavailable).
5. Emit summary + batch-composition + diagnostics tables.
6. Save processed.h5ad + report.md + result.json.

Gotchas

• scanvi silently falls back to scvi when labels are missing. sc_integrate.py:189-193 logs "scANVI requires labels; falling back to scVI latent integration" and writes result["requested_method"] = "scanvi", result["executed_method"] = "scvi", result["fallback_used"] = True. After every --method scanvi run, verify result.json["executed_method"] matches the request; --labels-key must be set and contain valid labels to actually get scANVI.
• simba missing → hard fail. sc_integrate.py:242 raises ImportError when --method simba runs without the simba package installed. Install via pip install simba / conda install -c bioconda simba / from-source per the message. scvi-tools failures surface separately with their own ImportError further downstream.
• Scanorama can return zero overlapping cells. sc_integrate.py:349 raises RuntimeError("Scanorama did not produce 'X_scanorama' embeddings") when batches share no genes (typical: gene-namespace mismatch). Pre-run sc-standardize-input on each batch.
• R-backed methods can produce zero-overlap returns too. sc_integrate.py:400 raises RuntimeError(f"R integration method '{method}' returned no overlapping cells") for the same root cause.
• LISI / ASW diagnostics are best-effort. sc_integrate.py:514 and :529 log "LISI diagnostics unavailable" / "ASW diagnostics unavailable" and continue when scIB or its dependencies are missing. Absence of metric rows in tables/integration_metrics.csv does not imply integration quality is bad — it means the diagnostics could not be computed.