Upgraded-SoupX
Ambient RNA contamination removal for droplet-based single-cell RNA-seq
Developed by Israt Jahan Khan — LinkedIn · Google Scholar · isratjahankhanijk@gmail.com
Upgraded-SoupX is a full Python port and extension of the original SoupX R package (Young & Behjati, 2020). It removes ambient RNA contamination from droplet-based scRNA-seq count matrices - no R dependency required.
Why ambient RNA matters
Every 10X Chromium droplet contains a small amount of soup - free RNA from lysed cells that accumulated in the cell suspension before capture. This contamination:
- Inflates counts for highly expressed extracellular genes (e.g. haemoglobin in non-erythroid cells)
- Creates spurious cell-type differences across clusters
- Reduces differential expression signal-to-noise
Upgraded-SoupX estimates and removes this contamination by:
- Modelling the soup expression profile from empty droplets
- Estimating the per-cell or per-cluster contamination fraction rho
- Subtracting expected soup counts from each cell
What this Python version adds
| Feature | R Baseline | Python Version |
|---|---|---|
| Core SoupX workflow | Yes | Yes (full parity) |
| DecontX per-cell decontamination | - | Yes run_decontx |
| Per-cell rho refinement | - | Yes estimate_cell_rho |
| Doublet-aware estimation | - | Yes estimate_doublet_scores |
| Gene-heterogeneity correction | - | Yes compute_gene_enrichment |
| Iterative contamination refinement | - | Yes iterative_auto_est_cont |
| Downstream analysis | - | Yes PCA / UMAP / Leiden / DE |
| 8 quantitative benchmark metrics | - | Yes |
| HDF5 input | - | Yes load_10x_h5 |
| Python ecosystem (scipy.sparse) | - | Yes native |
Quick navigation
- Installation - requirements and install commands
- Quick Start - four-line example
- Automatic Workflow - the recommended starting point
- DecontX - per-cell decontamination with LDA topics
- Benchmark Results - plots and findings across 5 datasets
- API Reference - full function documentation
Citation
If you use Upgraded-SoupX, please 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. https://github.com/IsratIJK/Upgraded-soupX
Also cite the original algorithms this work builds on:
Young, M.D. & Behjati, S. (2020). SoupX removes ambient RNA contamination from droplet-based single-cell RNA sequencing data. GigaScience, 9(12), giaa151.
If you use the DecontX module:
Yang, S. et al. (2020). Decontamination of ambient RNA in single-cell RNA-seq with DecontX. Genome Biology, 21, 57.