Beyond the R Baseline
Everything the original SoupX R package provides, plus six new decontamination modes and a full benchmark framework.
Full Python Port
Complete reimplementation of the R SoupX package. No R dependency - runs natively in the Python / scipy.sparse ecosystem.
DecontX Per-Cell Decontamination
Two-component Dirichlet-Multinomial EM with LDA topics. Estimates per-cell contamination theta instead of a single global rho.
Doublet-Aware Estimation
Scrublet-style doublet scoring masks contaminated doublets before rho estimation, producing cleaner per-cluster contamination rates.
Iterative Refinement
Runs auto_est_cont - adjust_counts - soup profile update until convergence. Achieves the best cluster preservation across all datasets.
Gene Heterogeneity Correction
Reweights the soup profile to amplify truly ambient genes. Reduces spurious DE genes by up to 98% on barnyard data.
8 Quantitative Metrics
Cross-species reduction, marker fold change, cluster ARI, batch entropy, HBB analysis, silhouette, spurious DE, marker enrichment.
30-second example
Load CellRanger output, add cluster labels, estimate contamination automatically, and correct counts - all in four function calls.
Works with v2 and v3 CellRanger layouts, MEX and HDF5 formats, and integrates with any clustering tool (Seurat, Scanpy, etc.).
from SoupX import load_10x, set_clusters, auto_est_cont, adjust_counts
# Load CellRanger output (v2 or v3, auto-detected)
sc = load_10x('path/to/cellranger/outs/')
# Attach cluster labels from Seurat / Scanpy
sc = set_clusters(sc, cluster_labels)
# Estimate contamination fraction rho automatically
sc = auto_est_cont(sc)
print(f"Contamination: {sc.meta_data['rho'].mean():.1%}")
# Produce corrected count matrix
corrected = adjust_counts(sc)
Pipeline Comparison
Choose the pipeline that best fits your data and biological question.
| Pipeline | Rho Type | Best For | Cluster Preservation | Speed |
|---|---|---|---|---|
auto_est_cont | Global / per-cluster | Most datasets | Good | Fast |
iterative_auto_est_cont | Global / per-cluster | Overlapping soup + cells | Best (highest ARI) | Moderate |
run_decontx | Per-cell | Barnyard, heterogeneous tissues | Good | Slow |
run_decontx_genehet | Per-cell | Blood contamination, high spurious DE | Moderate | Slow |
auto_est_cont_doublet_aware | Global / per-cluster | High doublet rate experiments | Good | Fast |
Installation
# Core package
pip install -e .
# With downstream analysis (PCA, UMAP, Leiden):
pip install -e ".[downstream]"
Requires Python ≥ 3.9.
Full installation guide ->Citation
Cite this software:
Khan, I.J. (2026). Upgraded-SoupX: A Python port and extension of SoupX for ambient RNA decontamination in single-cell RNA-seq. GitHub. github.com/IsratIJK/Upgraded-soupX
Also cite the original algorithms:
Young, M.D. & Behjati, S. (2020). SoupX removes ambient RNA contamination from droplet-based single-cell RNA sequencing data. GigaScience, 9(12), giaa151.
Yang, S. et al. (2020). Decontamination of ambient RNA in single-cell RNA-seq with DecontX. Genome Biology, 21, 57.