cycombinepy

cycombinepy is an AnnData-based implementation inspired by cyCombine for batch correction of single-cell cytometry data. It uses established Python packages for the main numerical steps:

Component	Library
ComBat correction	inmoose.pycombat
SOM clustering	FlowSOM
FCS I/O	pytometry
Batch-effect metrics	scib-metrics

Scope and provenance

cyCombinePy implements the core AnnData workflow inspired by the R cyCombine package: normalization for clustering, FlowSOM clustering, and per-cluster ComBat correction.

1. Batch-wise normalize each marker (cycombinepy.normalize)

2. Self-organizing map clustering of cells (cycombinepy.create_som)

3. Per-cluster ComBat correction with optional covariates (cycombinepy.correct_data)

Step 1 operates on a normalized view so that downstream clusters are less driven by technical variation. Step 3 is applied to the unnormalized data per cluster so rare populations are not over-corrected.

The API also validates requested marker names, missing observation metadata, finite marker matrices, and requested layers before numerical routines run. Correction functions write an H5AD-safe report to adata.uns["cycombinepy_correction"], and strict defaults fail closed for ComBat errors or fully confounded covariate/anchor designs.

Out of scope for cyCombinePy are Seurat / SingleCellExperiment wrappers, panel merging, ComBat_seq, alternative clustering backends, and run_analysis.

Main entry points

• cycombinepy.batch_correct(): run normalization, FlowSOM clustering, and per-cluster ComBat in one call.

• cycombinepy.correct_data(): run audited per-cluster ComBat when SOM labels already exist.

• cycombinepy.detect_batch_effect_express() and cycombinepy.detect_batch_effect(): inspect marker-level and embedding batch effects before correction.

• Main cyCombine workflow (Python port): source-only vignette for the correction workflow, including return_report=True, strict policies, and the layer-based modular API.

• Detecting batch effects (Python port): source-only vignette for diagnostic plots and validation behavior.

• CITE-seq ADT batch correction benchmark: rendered CITE-seq ADT benchmark comparing cyCombinePy with Harmony and totalVI.

Getting started

• Installation
  • Requirements
  • Install from PyPI
  • Install from source (development)
  • Building the documentation
  • Verifying the installation
  • Installing the agent skill
• Usage guide
  • Data conventions
  • The pipeline in one call
  • Loading data
  • Preprocessing
  • Normalization
  • Clustering
  • Per-cluster ComBat correction
  • Evaluating a correction
  • Detecting batch effects
  • Plotting helpers
• Citation
  • cyCombinePy
  • Original cyCombine method

Tutorials

• Main cyCombine workflow (Python port)
  • Setup
  • Download the data
  • Load FCS files into AnnData
  • Prepare data: arcsinh transform
  • Inspect the batch effect
  • Batch correction: one-call API
  • Batch correction: modular API
  • Evaluate: EMD reduction
  • Visualize: before and after correction
  • Persisting results
  • What next?
• Detecting batch effects (Python port)
  • Cofactor guidance
  • Setup
  • Load the Nuñez PBMC dataset
  • detect_batch_effect_express: three-panel summary
  • detect_batch_effect: extended diagnostic
  • Interpreting the diagnostics
• CITE-seq ADT batch correction benchmark
  • Setup
  • Load the PBMC CITE-seq ADT modality
  • Subsample and keep the MuData aligned
  • Uncorrected ADT embedding
  • cyCombinePy ADT correction
  • Harmony on ADT PCA
  • totalVI latent space and denoised proteins
  • Expression and embedding metrics
  • UMAP panels colored by batch
  • Interpreting the table

Reference

• API reference
  • Preprocessing
  • Clustering
  • Correction
  • Correction reports and constants
  • Evaluation
  • Detection
  • Utilities
  • I/O
  • Plotting
  • Advanced evaluation

Indices

• Index

• Module Index

• Search Page