sc-ambient-removal

name	sc-ambient-removal
description	Remove ambient RNA contamination from droplet-based single-cell RNA-seq using a simple subtraction path, CellBender, or SoupX. The wrapper exposes only the parameters that are actually wired into the current implementation.
version	0.6.0
author	OmicsClaw
license	MIT
tags	["singlecell","ambient","cellbender","soupx","qc"]
metadata	{"omicsclaw":{"domain":"singlecell","allowed_extra_flags":["--contamination","--expected-cells","--filtered-matrix-dir","--method","--raw-h5","--raw-matrix-dir","--r-enhanced"],"param_hints":{"simple":"[Truncated]","cellbender":"[Truncated]","soupx":"[Truncated]"},"saves_h5ad":true,"requires_preprocessed":false,"requires":{"bins":"[Truncated]","env":"[Truncated]","config":"[Truncated]"},"emoji":"S","homepage":"https://github.com/OmicsClaw/OmicsClaw","os":["macos","linux"],"install":["[Truncated]"],"trigger_keywords":["ambient RNA","ambient removal","cellbender","contamination","background RNA"]}}

Single-Cell Ambient RNA Removal

Why This Exists

• Without it: ambient transcripts from lysed cells bias downstream expression profiles.
• With it: corrected counts are easier to use for annotation, marker discovery, and DE.
• Why OmicsClaw: one wrapper exposes a fast Python fallback and two common method-specific entry paths.

Core Capabilities

1. Three entry paths: lightweight subtraction, CellBender, and SoupX.
2. Method-aware input contract: raw .h5 for CellBender, paired 10x directories for SoupX, AnnData for the simple path.
3. Method-aware diagnostics: shared-barcode comparison, count-distribution, and CellBender barcode-rank diagnostics when applicable.
4. Dual output contract for CellBender: preserves native CellBender matrix/log artifacts and also writes processed.h5ad for downstream OmicsClaw skills.
5. Honest fallback behavior: when SoupX prerequisites are absent, the current wrapper can fall back to the simple method instead of pretending full SoupX execution happened.

Scope Boundary

Implemented methods in the current wrapper:

1. simple - default Python subtraction path
2. cellbender - deep generative correction when --raw-h5 is provided
3. soupx - R-backed 10x matrix correction when raw and filtered directories are provided

The wrapper does not currently expose the full upstream CellBender or SoupX parameter surface.

Input Formats

Format	Extension / form	Current wrapper support	Notes
AnnData	.h5ad	yes	preferred input for simple; also usable as filtered reference for other paths
10x raw HDF5	.h5	yes	required by cellbender; can also be loaded directly when --input is omitted
10x raw matrix directory	directory	yes	used with --raw-matrix-dir for soupx
10x filtered matrix directory