# SoupX Python
[](https://badge.fury.io/py/soupx-python)
[](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html)
[](https://www.python.org/downloads/release/python-380/)
A Python implementation of SoupX for removing ambient RNA contamination from droplet-based single-cell RNA sequencing data.
## Overview
Droplet-based single-cell RNA sequencing (scRNA-seq) experiments contain ambient RNA contamination from cell-free mRNAs present in the input solution. This "soup" of background contamination can significantly confound biological interpretation, particularly in complex tissues where contamination rates can exceed 20%.
SoupX addresses this by:
1. **Estimating** the ambient RNA expression profile from empty droplets
2. **Quantifying** contamination fraction in each cell using marker genes
3. **Correcting** cell expression profiles by removing estimated background
This Python implementation maintains full compatibility with the original R package interface while integrating seamlessly with the Python scRNA-seq ecosystem (scanpy, anndata).
## Background & Citation
This implementation is based on the method described in:
> **Young, M.D., Behjati, S.** SoupX removes ambient RNA contamination from droplet-based single-cell RNA sequencing data. *GigaScience* 9, giaa151 (2020). [https://doi.org/10.1093/gigascience/giaa151](https://doi.org/10.1093/gigascience/giaa151)
**Please cite the original paper if you use this implementation in your research.**
## Installation
### From PyPI (Recommended)
```bash
pip install soupx-python
```
### From Source
```bash
git clone https://github.com/yourusername/soupx-python.git
cd soupx-python
pip install -e .
```
### Dependencies
- Python ≥3.8
- numpy ≥1.19.0
- pandas ≥1.2.0
- scipy ≥1.6.0
- statsmodels ≥0.12.0
- scanpy ≥1.7.0 (optional, for integration examples)
## Quick Start
### Basic Usage (R-compatible interface)
```python
import soupx
# Load 10X data (cellranger output directory)
sc = soupx.load10X("path/to/cellranger/outs/")
# Automatically estimate contamination
sc = soupx.autoEstCont(sc)
# Generate corrected count matrix
corrected_counts = soupx.adjustCounts(sc)
```
### Integration with scanpy
```python
import scanpy as sc
import soupx
import pandas as pd
# Load raw 10X data with both filtered and raw counts
adata_raw = sc.read_10x_mtx("path/to/raw_feature_bc_matrix/", cache=True)
adata_filtered = sc.read_10x_mtx("path/to/filtered_feature_bc_matrix/", cache=True)
# Create SoupChannel
soup_channel = soupx.SoupChannel(
tod=adata_raw.X.T.tocsr(), # raw counts (genes × droplets)
toc=adata_filtered.X.T.tocsr(), # filtered counts (genes × cells)
metaData=pd.DataFrame(index=adata_filtered.obs_names)
)
# Add clustering information (essential for good results)
sc.tl.leiden(adata_filtered, resolution=0.5)
soup_channel.setClusters(adata_filtered.obs['leiden'].values)
# Estimate and remove contamination
soup_channel = soupx.autoEstCont(soup_channel, verbose=True)
corrected_matrix = soupx.adjustCounts(soup_channel)
# Replace counts in AnnData object
adata_corrected = adata_filtered.copy()
adata_corrected.X = corrected_matrix.T # Convert back to cells × genes
# Continue with standard scanpy workflow
sc.pp.highly_variable_genes(adata_corrected)
sc.tl.pca(adata_corrected)
# ... further analysis
```
## Advanced Usage
### Manual Contamination Estimation
For experiments where automatic estimation fails or when you have prior biological knowledge:
```python
# Manually specify contamination fraction
soup_channel.set_contamination_fraction(0.10) # 10% contamination
# Or use specific marker genes (e.g., hemoglobin genes for tissue samples)
hemoglobin_genes = ['HBA1', 'HBA2', 'HBB', 'HBD', 'HBG1', 'HBG2']
non_expressing = soupx.estimateNonExpressingCells(
soup_channel,
hemoglobin_genes,
clusters=soup_channel.metaData['clusters'].values
)
# Calculate contamination using marker genes
soup_channel = soupx.calculateContaminationFraction(
soup_channel,
{'HB': hemoglobin_genes},
non_expressing
)
```
### Method Selection
```python
# Different correction methods available:
# 1. Subtraction (default, fastest)
corrected = soupx.adjustCounts(soup_channel, method="subtraction")
# 2. Multinomial (most accurate, slower)
corrected = soupx.adjustCounts(soup_channel, method="multinomial")
# 3. SoupOnly (removes only confidently contaminated genes)
corrected = soupx.adjustCounts(soup_channel, method="soupOnly")
# Round to integers (some downstream tools require this)
corrected = soupx.adjustCounts(soup_channel, roundToInt=True)
```
## API Reference
### Core Classes
#### `SoupChannel`
Main container for scRNA-seq data and contamination analysis.
**Parameters:**
- `tod`: Raw count matrix (genes × droplets, sparse)
- `toc`: Filtered count matrix (genes × cells, sparse)
- `metaData`: Cell metadata DataFrame
- `calcSoupProfile`: Whether to estimate soup profile automatically (default: True)
#### Key Methods
##### `autoEstCont(sc, **kwargs)`
Automatically estimate contamination fraction using marker genes.
**Parameters:**
- `tfidfMin`: Minimum tf-idf for marker genes (default: 1.0)
- `soupQuantile`: Quantile threshold for soup genes (default: 0.9)
- `verbose`: Print progress information (default: True)
##### `adjustCounts(sc, **kwargs)`
Remove contamination and return corrected count matrix.
**Parameters:**
- `method`: Correction method ("subtraction", "multinomial", "soupOnly")
- `roundToInt`: Round results to integers (default: False)
- `clusters`: Cluster assignments (improves accuracy)
### Utility Functions
##### `load10X(dataDir)`
Load 10X CellRanger output directory.
##### `quickMarkers(toc, clusters, N=10)`
Identify cluster marker genes using tf-idf.
## Validation & Benchmarking
This implementation has been validated against the original R version using:
- **Species-mixing experiments**: Cross-species contamination quantification
- **PBMC datasets**: Standard benchmark with known marker genes
- **Complex tissue samples**: Kidney tumor and fetal liver data
Key validation results:
- Contamination estimates: R² > 0.95 correlation with R implementation
- Correction accuracy: >90% reduction in cross-species contamination
- Marker gene specificity: Consistent improvement in fold-change ratios
## Performance Considerations
- **Memory usage**: Sparse matrices used throughout to minimize memory footprint
- **Clustering improves results**: Always provide cluster information when possible
- **Method selection**: Use "subtraction" for speed, "multinomial" for accuracy
- **Large datasets**: Consider using `method="soupOnly"` for >100k cells
## Troubleshooting
### Common Issues
**Low marker gene detection:**
```python
# Reduce stringency for marker detection
sc = soupx.autoEstCont(sc, tfidfMin=0.5, soupQuantile=0.8)
```
**High contamination estimates (>50%):**
```python
# Force acceptance of high contamination or manually set
sc.set_contamination_fraction(0.20, forceAccept=True)
```
**No clustering information:**
```python
# SoupX works without clustering but results are less accurate
corrected = soupx.adjustCounts(sc, clusters=False)
```
## Comparison with Other Methods
| Method | Speed | Accuracy | Requires Empty Droplets | Requires Clustering |
|--------|-------|----------|------------------------|-------------------|
| SoupX | Fast | High | Yes | Recommended |
| CellBender | Slow | High | No | No |
| DecontX | Medium | Medium | No | Yes |
## Contributing
We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.
### Development Setup
```bash
git clone https://github.com/yourusername/soupx-python.git
cd soupx-python
pip install -e ".[dev]"
pytest tests/
```
## License
This project is licensed under the GNU General Public License v2.0 - see the [LICENSE](LICENSE) file for details.
## Changelog
### v0.3.0 (Current)
- Full R compatibility
- Automated contamination estimation
- Integration with scanpy ecosystem
- Comprehensive validation suite
### v0.2.0
- Core correction algorithms
- Manual contamination setting
- Basic 10X data loading
### v0.1.0
- Initial implementation
- Basic SoupChannel functionality
## Support
- **Issues**: [GitHub Issues](https://github.com/yourusername/soupx-python/issues)
- **Questions**: [GitHub Discussions](https://github.com/yourusername/soupx-python/discussions)
- **Citation**: Please cite the original SoupX paper (Young & Behjati, 2020)
## Acknowledgments
- Original SoupX developers: Matthew D. Young and Sam Behjati
- R package maintainers and contributors
- Python single-cell community (scanpy, anndata developers)
Raw data
{
"_id": null,
"home_page": null,
"name": "soupx-python",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Nicolas Ruffini <nicolas.ruffini@posteo.de>",
"keywords": "single-cell, RNA-seq, bioinformatics, decontamination, ambient-RNA, soupx",
"author": null,
"author_email": "Nicolas Ruffini <nicolas.ruffini@posteo.de>",
"download_url": "https://files.pythonhosted.org/packages/e1/37/eae4c584d84ec542423d4b3860f535504673524ec0fd4801c89cfbcc488b/soupx_python-0.3.0.tar.gz",
"platform": null,
"description": "# SoupX Python\r\n\r\n[](https://badge.fury.io/py/soupx-python)\r\n[](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html)\r\n[](https://www.python.org/downloads/release/python-380/)\r\n\r\nA Python implementation of SoupX for removing ambient RNA contamination from droplet-based single-cell RNA sequencing data.\r\n\r\n## Overview\r\n\r\nDroplet-based single-cell RNA sequencing (scRNA-seq) experiments contain ambient RNA contamination from cell-free mRNAs present in the input solution. This \"soup\" of background contamination can significantly confound biological interpretation, particularly in complex tissues where contamination rates can exceed 20%.\r\n\r\nSoupX addresses this by:\r\n1. **Estimating** the ambient RNA expression profile from empty droplets\r\n2. **Quantifying** contamination fraction in each cell using marker genes \r\n3. **Correcting** cell expression profiles by removing estimated background\r\n\r\nThis Python implementation maintains full compatibility with the original R package interface while integrating seamlessly with the Python scRNA-seq ecosystem (scanpy, anndata).\r\n\r\n## Background & Citation\r\n\r\nThis implementation is based on the method described in:\r\n\r\n> **Young, M.D., Behjati, S.** SoupX removes ambient RNA contamination from droplet-based single-cell RNA sequencing data. *GigaScience* 9, giaa151 (2020). [https://doi.org/10.1093/gigascience/giaa151](https://doi.org/10.1093/gigascience/giaa151)\r\n\r\n**Please cite the original paper if you use this implementation in your research.**\r\n\r\n## Installation\r\n\r\n### From PyPI (Recommended)\r\n\r\n```bash\r\npip install soupx-python\r\n```\r\n\r\n### From Source\r\n\r\n```bash\r\ngit clone https://github.com/yourusername/soupx-python.git\r\ncd soupx-python\r\npip install -e .\r\n```\r\n\r\n### Dependencies\r\n\r\n- Python \u22653.8\r\n- numpy \u22651.19.0\r\n- pandas \u22651.2.0\r\n- scipy \u22651.6.0\r\n- statsmodels \u22650.12.0\r\n- scanpy \u22651.7.0 (optional, for integration examples)\r\n\r\n## Quick Start\r\n\r\n### Basic Usage (R-compatible interface)\r\n\r\n```python\r\nimport soupx\r\n\r\n# Load 10X data (cellranger output directory)\r\nsc = soupx.load10X(\"path/to/cellranger/outs/\")\r\n\r\n# Automatically estimate contamination\r\nsc = soupx.autoEstCont(sc)\r\n\r\n# Generate corrected count matrix\r\ncorrected_counts = soupx.adjustCounts(sc)\r\n```\r\n\r\n### Integration with scanpy\r\n\r\n```python\r\nimport scanpy as sc\r\nimport soupx\r\nimport pandas as pd\r\n\r\n# Load raw 10X data with both filtered and raw counts\r\nadata_raw = sc.read_10x_mtx(\"path/to/raw_feature_bc_matrix/\", cache=True)\r\nadata_filtered = sc.read_10x_mtx(\"path/to/filtered_feature_bc_matrix/\", cache=True)\r\n\r\n# Create SoupChannel\r\nsoup_channel = soupx.SoupChannel(\r\n tod=adata_raw.X.T.tocsr(), # raw counts (genes \u00d7 droplets)\r\n toc=adata_filtered.X.T.tocsr(), # filtered counts (genes \u00d7 cells)\r\n metaData=pd.DataFrame(index=adata_filtered.obs_names)\r\n)\r\n\r\n# Add clustering information (essential for good results)\r\nsc.tl.leiden(adata_filtered, resolution=0.5)\r\nsoup_channel.setClusters(adata_filtered.obs['leiden'].values)\r\n\r\n# Estimate and remove contamination\r\nsoup_channel = soupx.autoEstCont(soup_channel, verbose=True)\r\ncorrected_matrix = soupx.adjustCounts(soup_channel)\r\n\r\n# Replace counts in AnnData object\r\nadata_corrected = adata_filtered.copy()\r\nadata_corrected.X = corrected_matrix.T # Convert back to cells \u00d7 genes\r\n\r\n# Continue with standard scanpy workflow\r\nsc.pp.highly_variable_genes(adata_corrected)\r\nsc.tl.pca(adata_corrected)\r\n# ... further analysis\r\n```\r\n\r\n## Advanced Usage\r\n\r\n### Manual Contamination Estimation\r\n\r\nFor experiments where automatic estimation fails or when you have prior biological knowledge:\r\n\r\n```python\r\n# Manually specify contamination fraction\r\nsoup_channel.set_contamination_fraction(0.10) # 10% contamination\r\n\r\n# Or use specific marker genes (e.g., hemoglobin genes for tissue samples)\r\nhemoglobin_genes = ['HBA1', 'HBA2', 'HBB', 'HBD', 'HBG1', 'HBG2']\r\nnon_expressing = soupx.estimateNonExpressingCells(\r\n soup_channel, \r\n hemoglobin_genes,\r\n clusters=soup_channel.metaData['clusters'].values\r\n)\r\n\r\n# Calculate contamination using marker genes\r\nsoup_channel = soupx.calculateContaminationFraction(\r\n soup_channel, \r\n {'HB': hemoglobin_genes}, \r\n non_expressing\r\n)\r\n```\r\n\r\n### Method Selection\r\n\r\n```python\r\n# Different correction methods available:\r\n\r\n# 1. Subtraction (default, fastest)\r\ncorrected = soupx.adjustCounts(soup_channel, method=\"subtraction\")\r\n\r\n# 2. Multinomial (most accurate, slower)\r\ncorrected = soupx.adjustCounts(soup_channel, method=\"multinomial\")\r\n\r\n# 3. SoupOnly (removes only confidently contaminated genes)\r\ncorrected = soupx.adjustCounts(soup_channel, method=\"soupOnly\")\r\n\r\n# Round to integers (some downstream tools require this)\r\ncorrected = soupx.adjustCounts(soup_channel, roundToInt=True)\r\n```\r\n\r\n## API Reference\r\n\r\n### Core Classes\r\n\r\n#### `SoupChannel`\r\nMain container for scRNA-seq data and contamination analysis.\r\n\r\n**Parameters:**\r\n- `tod`: Raw count matrix (genes \u00d7 droplets, sparse)\r\n- `toc`: Filtered count matrix (genes \u00d7 cells, sparse) \r\n- `metaData`: Cell metadata DataFrame\r\n- `calcSoupProfile`: Whether to estimate soup profile automatically (default: True)\r\n\r\n#### Key Methods\r\n\r\n##### `autoEstCont(sc, **kwargs)`\r\nAutomatically estimate contamination fraction using marker genes.\r\n\r\n**Parameters:**\r\n- `tfidfMin`: Minimum tf-idf for marker genes (default: 1.0)\r\n- `soupQuantile`: Quantile threshold for soup genes (default: 0.9)\r\n- `verbose`: Print progress information (default: True)\r\n\r\n##### `adjustCounts(sc, **kwargs)`\r\nRemove contamination and return corrected count matrix.\r\n\r\n**Parameters:**\r\n- `method`: Correction method (\"subtraction\", \"multinomial\", \"soupOnly\")\r\n- `roundToInt`: Round results to integers (default: False)\r\n- `clusters`: Cluster assignments (improves accuracy)\r\n\r\n### Utility Functions\r\n\r\n##### `load10X(dataDir)`\r\nLoad 10X CellRanger output directory.\r\n\r\n##### `quickMarkers(toc, clusters, N=10)`\r\nIdentify cluster marker genes using tf-idf.\r\n\r\n## Validation & Benchmarking\r\n\r\nThis implementation has been validated against the original R version using:\r\n\r\n- **Species-mixing experiments**: Cross-species contamination quantification\r\n- **PBMC datasets**: Standard benchmark with known marker genes\r\n- **Complex tissue samples**: Kidney tumor and fetal liver data\r\n\r\nKey validation results:\r\n- Contamination estimates: R\u00b2 > 0.95 correlation with R implementation\r\n- Correction accuracy: >90% reduction in cross-species contamination\r\n- Marker gene specificity: Consistent improvement in fold-change ratios\r\n\r\n## Performance Considerations\r\n\r\n- **Memory usage**: Sparse matrices used throughout to minimize memory footprint\r\n- **Clustering improves results**: Always provide cluster information when possible\r\n- **Method selection**: Use \"subtraction\" for speed, \"multinomial\" for accuracy\r\n- **Large datasets**: Consider using `method=\"soupOnly\"` for >100k cells\r\n\r\n## Troubleshooting\r\n\r\n### Common Issues\r\n\r\n**Low marker gene detection:**\r\n```python\r\n# Reduce stringency for marker detection\r\nsc = soupx.autoEstCont(sc, tfidfMin=0.5, soupQuantile=0.8)\r\n```\r\n\r\n**High contamination estimates (>50%):**\r\n```python\r\n# Force acceptance of high contamination or manually set\r\nsc.set_contamination_fraction(0.20, forceAccept=True)\r\n```\r\n\r\n**No clustering information:**\r\n```python\r\n# SoupX works without clustering but results are less accurate\r\ncorrected = soupx.adjustCounts(sc, clusters=False)\r\n```\r\n\r\n## Comparison with Other Methods\r\n\r\n| Method | Speed | Accuracy | Requires Empty Droplets | Requires Clustering |\r\n|--------|-------|----------|------------------------|-------------------|\r\n| SoupX | Fast | High | Yes | Recommended |\r\n| CellBender | Slow | High | No | No |\r\n| DecontX | Medium | Medium | No | Yes |\r\n\r\n## Contributing\r\n\r\nWe welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.\r\n\r\n### Development Setup\r\n\r\n```bash\r\ngit clone https://github.com/yourusername/soupx-python.git\r\ncd soupx-python\r\npip install -e \".[dev]\"\r\npytest tests/\r\n```\r\n\r\n## License\r\n\r\nThis project is licensed under the GNU General Public License v2.0 - see the [LICENSE](LICENSE) file for details.\r\n\r\n## Changelog\r\n\r\n### v0.3.0 (Current)\r\n- Full R compatibility \r\n- Automated contamination estimation\r\n- Integration with scanpy ecosystem\r\n- Comprehensive validation suite\r\n\r\n### v0.2.0\r\n- Core correction algorithms\r\n- Manual contamination setting\r\n- Basic 10X data loading\r\n\r\n### v0.1.0\r\n- Initial implementation\r\n- Basic SoupChannel functionality\r\n\r\n## Support\r\n\r\n- **Issues**: [GitHub Issues](https://github.com/yourusername/soupx-python/issues)\r\n- **Questions**: [GitHub Discussions](https://github.com/yourusername/soupx-python/discussions)\r\n- **Citation**: Please cite the original SoupX paper (Young & Behjati, 2020)\r\n\r\n## Acknowledgments\r\n\r\n- Original SoupX developers: Matthew D. Young and Sam Behjati\r\n- R package maintainers and contributors\r\n- Python single-cell community (scanpy, anndata developers)\r\n",
"bugtrack_url": null,
"license": "GPL-2.0",
"summary": "Python implementation of SoupX for removing ambient RNA contamination from droplet-based single-cell RNA sequencing data",
"version": "0.3.0",
"project_urls": {
"Bug Tracker": "https://github.com/NiRuff/soupx-python/issues",
"Homepage": "https://github.com/NiRuff/soupx-python",
"Repository": "https://github.com/NiRuff/soupx-python"
},
"split_keywords": [
"single-cell",
" rna-seq",
" bioinformatics",
" decontamination",
" ambient-rna",
" soupx"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3863b21fee05ab88861ea2db29aa539ae516c55ff1773defd830ddf71b8ad22d",
"md5": "a0d0909e7578b01711351ede02471d22",
"sha256": "a936abeec88f7b2605c59c1f32d6728443817faadd667dd6645be1980a65a6f2"
},
"downloads": -1,
"filename": "soupx_python-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a0d0909e7578b01711351ede02471d22",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 21109,
"upload_time": "2025-09-03T13:40:47",
"upload_time_iso_8601": "2025-09-03T13:40:47.588510Z",
"url": "https://files.pythonhosted.org/packages/38/63/b21fee05ab88861ea2db29aa539ae516c55ff1773defd830ddf71b8ad22d/soupx_python-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e137eae4c584d84ec542423d4b3860f535504673524ec0fd4801c89cfbcc488b",
"md5": "a45d22e31e384fabac85e4d2ee06f7e8",
"sha256": "585f263e5b5d53591c00dc1034563f68d1c82d3c47b683b059169f376b56c6e0"
},
"downloads": -1,
"filename": "soupx_python-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "a45d22e31e384fabac85e4d2ee06f7e8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 22699,
"upload_time": "2025-09-03T13:40:48",
"upload_time_iso_8601": "2025-09-03T13:40:48.659331Z",
"url": "https://files.pythonhosted.org/packages/e1/37/eae4c584d84ec542423d4b3860f535504673524ec0fd4801c89cfbcc488b/soupx_python-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-03 13:40:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "NiRuff",
"github_project": "soupx-python",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "soupx-python"
}
JSON
