SoupX: Ambient RNA Contamination Removal

Effective contamination estimation often relies on identifying genes highly specific to a cell type present at low frequency in your data.

Recommended Gene Sets:

• HB genes (Hemoglobin genes) and erythrocytes.
• IG genes (Immunoglobulin genes) and B-cells.
• TPSB2/TPSAB1 and Mast cells.

If standard sets fail, use plotMarkerDistribution (as described in the package vignette) to find inspiration for potential markers. If no markers are found, consider testing a range of manual contamination corrections (e.g., 2-10%) to see the impact on downstream analysis.

autoEstCont automatically estimates the contamination fraction. It relies on the assumption that there is sufficient diversity in the raw data to identify marker genes.

Common Issues:

• Homogenous data or low cell count: If your data is extremely homogenous (e.g., a single cell line) or has very few cells (a few hundred or less), autoEstCont may fail or produce unrealistic estimates. In these cases, manually specify a contamination fraction using setContaminationFraction.
• Unrealistic estimates: A contamination rate of $\le$ 2% is low, 5% is usual, 10% is moderate, and $\ge$ 20% is very high. If estimates fall outside these ranges, consider if your data meets the diversity assumptions.

If you are using 10X data mapped with cellranger, SoupX can automatically load the necessary information. Use load10X to point to your cellranger outs folder, then use autoEstCont to estimate the contamination fraction, and finally adjustCounts to generate the corrected matrix.

autoEstCont requires clustering information. For 10X data loaded via load10X, this is loaded automatically.

sc = load10X('path/to/your/cellranger/outs/folder')
sc = autoEstCont(sc)
out = adjustCounts(sc)

For data formats other than 10X/cellranger, you must manually construct a SoupChannel object and provide clustering information using setClusters before proceeding with estimation and adjustment.

1. Create a SoupChannel using a table of droplets and a table of counts.
2. Provide cluster labels using setClusters.
3. Estimate contamination with autoEstCont.
4. Generate corrected counts with adjustCounts.

The resulting out object contains the corrected matrix for downstream analysis.

sc = SoupChannel(table_of_droplets, table_of_counts)
sc = setClusters(sc, cluster_labels)
sc = autoEstCont(sc)
out = adjustCounts(sc)

You can install the latest stable release of SoupX from CRAN using the standard R installation command. For the latest development version, use devtools to install from GitHub.

If you encounter errors regarding multtest being unavailable, you must install it manually from Bioconductor.

Note: There is a specific branch STAN available for per-cell contamination estimation, though it is generally not required for most users.

# Stable release from CRAN
install.packages('SoupX')

# Latest development version
devtools::install_github("constantAmateur/SoupX", ref='devel')

# Per-cell contamination estimation (STAN branch)
devtools::install_github("constantAmateur/SoupX", ref='STAN')

# Manual installation of dependency if needed
BiocManager::install('multtest')

If SoupX does not appear to remove contamination effectively, check the following:

1. Clustering Information: Ensure you are providing clustering information. Use setClusters manually if not using load10X. Cluster information allows for much more effective identification and removal of contamination.
2. Contamination Rate: Verify if the estimated rate is plausible. If you suspect the estimate is too low, you can manually increase it using setContaminationFraction.
3. Conservative Design: SoupX is designed to err on the side of caution to avoid removing real counts. If you need more aggressive removal, try manually increasing the contamination rate.

When using estimateNonExpressingCells, the default behavior (for 10X data) is to look for cells with strong evidence of endogenous expression of your chosen marker genes, then exclude any cluster containing such a cell. This prevents over-estimation but can fail if all clusters contain at least one 'bad' cell.

Solutions:

1. Recluster: Produce more clusters with fewer cells per cluster (preferred).
2. Relax Criteria: Tweak maximumContamination and/or pCut to make the criteria for declaring a cell as 'genuinely expressing' a gene set less strict.
3. Force Independent Consideration: Set clusters=FALSE to force the function to consider each cell independently. If doing this, decrease maximumContamination to make the exclusion criteria more permissive.