SoupX Usage Documentation

Author: SeekGene

Time: 4 min

Words: 744 words

Updated: 2026-10-13

Reads: 0 times

Module Overview

SoupX is an analysis module for removing ambient RNA contamination from single-cell transcriptome data.

In droplet-based single-cell sequencing, some cells rupture during dissociation and library preparation, releasing free mRNA. This free mRNA floats in the cell suspension and is captured by all droplets together, causing some genes to show false-positive high expression in almost all cells and interfering with downstream cell clustering, annotation, and differential analysis.

SoupX uses the free-RNA information from empty droplets, combined with clustering results, to estimate the proportion of ambient RNA mixed into each cell and corrects the expression matrix, producing a cleaner count matrix and thereby improving the accuracy of downstream analysis.

---

Analysis Principles

1. Estimate the ambient background profile: Count the proportion of each gene from empty droplets (nUMI < 10) to obtain the gene fingerprint of ambient RNA.
2. Estimate the contamination rate rho: Use the clustering results to find cluster-specific marker genes, and regress the observed counts of these markers in cells of other clusters to estimate the global contamination proportion.
3. Correct the expression matrix: For each cell and gene, subtract the ambient counts corresponding to "contamination rate × total cell UMI × the gene's proportion in the environment", and round to obtain the clean matrix.

---

Applicable Scenarios

• Droplet-based single-cell transcriptome sequencing data.
• Samples with difficult tissue dissociation and a large number of easily lysed cells (neutrophils, red blood cells, macrophages, etc.).
• FFPE (paraffin-embedded) samples, where ambient RNA contamination is often more pronounced due to degradation and fragmentation.
• Scenarios that require background noise removal before downstream clustering, annotation, and differential analysis.
• Supports ordinary single-cell, spatial transcriptome, and ATAC + RNA multi-omics data simultaneously.

---

Cloud Platform Parameter Description

Parameter Overview

Parameter	Required	Meaning
Analysis workflow	Required	Fixed as SoupX
Task name	Required	Corresponds to the task name in the task list.
Sample information	Required	Input the sample name; the remaining information (analysis batch number, file OSS path) is filled automatically; a sample may have multiple analysis batches, so verify carefully.
Rho	Optional	Ambient RNA contamination rate; when manually specified, automatic estimation is skipped.
Description	Optional	Task description or notes.

Key Parameter Details

Rho (contamination rate)

• The theoretical range is [0, 1], representing the proportion of each cell's measured UMIs that comes from ambient free RNA.
• Recommended to leave empty: when left empty, the module estimates it automatically, and the estimate is clipped to [0.01, 0.8].
• If automatic estimation fails, it falls back to the default value 0.2.
• When manually filled in, the user-specified value is used directly and automatic estimation is skipped.

---

How to Use the Results

1. Check whether the contamination rate is reasonable: Look at the rho values in soupx_rho_info.tsv; in normal data they are typically between 0.02 and 0.2.
2. Assess the decontamination effect: Look at soupx_qc_delta.tsv to confirm that the decrease in nCount and nFeature after cleaning is reasonable and that percent.mt has decreased.
3. Verify the source of contamination: Look at <sample_name>_soupx_ambient_top.tsv; if the top genes are dominated by high-contamination genes such as mitochondrial, hemoglobin, and ribosomal genes, the decontamination direction is correct.
4. Use the corrected RDS directly for downstream analysis: The completed data is under "Cloud Platform — Resource Overview — My Data"; after verifying the results, you can directly create a workflow for analysis.

---

Notes

1. It is recommended to leave rho empty: leaving it empty runs automatic estimation that better fits the data itself; specify it manually only with caution — an overly large rho will over-subtract expression signal.
2. A single task supports only one data type: spatial, multi-omics, and ordinary single-cell data cannot be mixed in the same task.
3. SoupX only corrects counts and does not remove cells: the number of cells before and after correction is the same; if low-quality cells need to be removed, that should be handled separately in a subsequent QC step.
4. The automatically estimated rho is limited to [0.01, 0.8]: if automatic estimation fails, it falls back to 0.2, and the result table's "fallback to default 0.2" column will be marked "Yes" — data quality should then be reviewed.
5. FFPE samples typically have higher contamination: FFPE data contains more ambient RNA, so a higher estimated rho is normal, but the correction should be judged as reasonable in combination with the QC change table.