Sc Ambient Removal

sc-ambient-removal

When to use

The user has filtered (or raw + filtered) droplet-based scRNA-seq counts and suspects ambient RNA from cell-free droplets is inflating per-cell expression — typical for 10X data with high droplet density. Three backends share the CLI: simple (a deterministic ambient-profile subtraction, default), cellbender (Python, requires GPU for sensible runtime), and soupx (Rscript; needs raw + filtered matrices). Doublets are a different problem — use sc-doublet-detection for multiplet barcodes.

Use from a step

ambient = load_skill("sc-ambient-removal")
adata = ambient.remove_ambient(read_input("counts.h5ad"), contamination=0.05)
write_output(ambient.correction_summary(adata), "tables/correction_summary.csv")
write_output(ambient.correction_figure(adata), "figures/counts_comparison.png")
write_output(adata, "intermediate/adata_corrected.h5ad")

With raw droplets, use remove_ambient_soupx(filtered, raw=raw_droplets). CellBender remains CLI-only because it uses an external process and files. The simple-method example is in examples/example_step.py.

API

<!-- api:begin generated from _api.py; regenerate with run.py api <skill dir> --write -->

remove_ambient(adata, *, contamination: float=0.05)

Subtract a mean ambient profile from count-like expression in place.

Select layers['counts'], aligned raw or X; retain that matrix in layers['counts'] and replace X with nonnegative corrected values. The mean cell profile is only an approximation when empty droplets are absent.

:param adata: AnnData with a count-like expression matrix. :param contamination: Fraction to subtract before clipping at zero, in [0, 1). Default 0.05, matching the CLI. :returns: The same AnnData; run_info reports the matrix source and reduction. :raises ValueError: No count-like matrix exists or contamination is invalid.

remove_ambient_soupx(adata, *, raw)

Return SoupX-corrected cells, using raw droplet counts to estimate ambient RNA.

Both objects select counts from layers['counts'], aligned raw or X and exchange temporary 10x matrices with R. This backend does not expose a seed through its wrapper; results vary between runs. Errors propagate.

:param adata: AnnData containing the filtered cells. :param raw: AnnData containing raw droplets, with matching feature names. :returns: A new AnnData aligned to SoupX's retained cells and genes, with original counts in layers['counts'] and corrected X. :raises RuntimeError: R, Seurat or SoupX is unavailable, or the method fails. :raises ValueError: Counts are missing or the result cannot be aligned.

run_info(adata, *, keep: bool=True) -> dict

Read JSON correction diagnostics from adata.uns.

:param adata: AnnData returned by a correction function. :param keep: False removes the diagnostics after reading; default True. :returns: Matrix source, method and before/after count summaries.

correction_summary(adata) -> pd.DataFrame

Return the recorded count reduction as a one-row table.

:param adata: AnnData returned by a correction function. :returns: Mean counts, reduction_pct, contamination_estimate and method.

counts_comparison_table(adata) -> pd.DataFrame

Compare per-cell original counts in layers['counts'] with corrected X.

:param adata: AnnData returned by a correction function. :returns: cell_id, counts_before and counts_after in observation order.

ambient_profile_table(adata) -> pd.DataFrame

Return the mean original-count profile used by simple subtraction.

:param adata: Corrected AnnData with original counts in layers['counts']. :returns: gene and fraction columns. This is not SoupX's estimated profile.

correction_figure(adata)

Plot original versus corrected counts per cell and return the Figure.

:param adata: AnnData returned by a correction function. :returns: A matplotlib Figure for write_output.

<!-- api:end -->

Methods and parameters

remove_ambient selects counts from layers["counts"], aligned raw, then X, saves them in layers["counts"] and replaces X in place. The contamination=0.05 default retains the CLI's fixed subtraction fraction; it is not an estimated biological contamination rate. The profile is the mean across input cells, an approximation when no empty droplets exist. This path is deterministic and needs no optional backend.

remove_ambient_soupx requires R, Seurat and SoupX. It exchanges compressed 10x matrices in a temporary directory and returns a new, aligned AnnData. Its wrapper exposes no seed, so results may vary. Unlike the compatibility CLI, the API propagates backend errors; it does not fall back to simple subtraction. run_info records the method, count source and reduction.