sc-batchbench

Modular pipeline for benchmarking batch-effect correction methods on single-cell data using scanpy/anndata.

Project layout

• sc_pipeline/qc.py — QC filtering (filter_adata, QCConfig)
• sc_pipeline/normalization.py — normalization and preprocessing
• sc_pipeline/batch_correction.py — integration methods
• sc_pipeline/metrics.py — metric implementations and plots
• sc_pipeline/models.py — dataclass configs/results
• sc_pipeline/pipeline.py — unified run_pipeline(...) entrypoint
• run_sc_pipeline.py — CLI runner for .h5ad datasets
• build_colon_atlas_h5ad.py — utility to assemble colon atlas .h5ad

Installation

With uv (recommended)

uv venv --python 3.11
uv sync
uv sync --extra integration --extra metrics

Run CLI with:

uv run python run_sc_pipeline.py --help

With pip

.venv/bin/python -m pip install scanpy anndata matplotlib scikit-learn
.venv/bin/python -m pip install bbknn harmonypy scanorama scib scib-metrics

Optional packages:

• integration methods: bbknn, harmonypy, scanorama
• metrics: scib, scib-metrics

Quick CLI example

uv run python run_sc_pipeline.py \
  --input-h5ad data/colon_atlas/colon_atlas.h5ad \
  --output-dir results/colon_atlas_run \
  --batch-key batch \
  --methods no_correction,bbknn,harmony,scanorama \
  --metrics ilisi,asw_batch

Useful flags:

• --qc-per-batch / --no-qc-per-batch
• --no-save-intermediate

Main outputs:

• adata_qc.h5ad
• adata_<method>.h5ad (unless disabled)
• metrics_summary.csv
• batch_fraction_<method>.png

Python usage

import scanpy as sc
from sc_pipeline.models import PipelineConfig, QCConfig, NormalizationConfig
from sc_pipeline.pipeline import run_pipeline

adata = sc.read("data/colon_atlas/colon_atlas.h5ad")

result = run_pipeline(
    adata=adata,
    cfg=PipelineConfig(
        batch_key="batch",
        label_key="leiden",
        methods=("no_correction", "harmony"),
        metrics=("ilisi", "asw_batch"),
        run_qc_per_batch=True,
    ),
    qc_cfg=QCConfig(),
    norm_cfg=NormalizationConfig(batch_key="batch"),
)

print(result.metrics_table)

result contains:

• result.adata_qc: post-QC AnnData
• result.corrected: {method_name: AnnData}
• result.metrics_table: metrics table

Built-in methods

• no_correction
• bbknn
• harmony
• scanorama

Built-in metrics

• ilisi
• asw_batch
• asw_label
• kbet
• kbet_pg
• kbet_pg_label
• graph_connectivity
• clisi / cilisi

You can add custom metrics via: run_pipeline(..., custom_metrics={...}).

Metric interpretation

• ilisi: batch mixing in local neighborhoods (higher is better)
• clisi/cilisi: biological structure preservation (higher is better)
• asw_batch: batch mixing within biological labels (higher is better)
• asw_label: label separation quality in embedding (higher is better)
• kbet: local batch-mixing acceptance rate (higher is better)
• kbet_pg / kbet_pg_label: per-label kBET aggregate (higher is better)
• graph_connectivity: within-label graph connectivity (higher is better)

Troubleshooting

If ilisi/clisi fail with Exec format error on knn_graph.o (for example after moving an environment across operating systems), rebuild the scib binary in the current environment:

c++ -O3 -std=c++11 \
  .venv/lib/python3.11/site-packages/scib/knn_graph/knn_graph.cpp \
  -o .venv/lib/python3.11/site-packages/scib/knn_graph/knn_graph.o