AmbiDose Documentation#
What AmbiDose does#
AmbiDose removes ambient RNA from droplet single-cell RNA-seq while keeping the count matrix suitable for ordinary count-based downstream analysis.
raw droplets + filtered cell barcodes
│
▼
classify empty droplets
│
▼
estimate sample soup χ
│
▼
coarse types → per-cell ρ and d
│
▼
subtract (type-constrained):
rank-1 along χ + soupOnly
(soupOnly may exceed d_c)
Empty droplets determine the ambient composition \(\chi_s\) for each sample. Each cell receives an operational scale \(\rho_c\) and \(\chi\)-direction dose \(d_c=\rho_c n_c\) (the rank-1 budget along \(\chi_s\), not a cap on total UMI removal). The standard workflow (denoise()) writes non-negative integer counts to adata.layers["ambidose_denoised"] and, as its last step, also sets them as adata.X – the original input moves to adata.layers["raw_counts"].
AmbiDose estimates ambient RNA and subtracts it. It does not fit a count posterior, correct batch effects, or assign cell-type names. Automatic Leiden groups are an operational identity for dose and subtraction. The usual whitelist is the matching Cell Ranger filtered barcodes, refined against χ. An external barcode list is accepted when that call is missing or unreliable. The CLI default without a whitelist is DIEM. Python callers may request DIEM, EmptyDrops, OrdMag, or a fixed cell count. χ is always estimated from the matching raw droplet matrix.
Where to go#
Goal |
Page |
|---|---|
Install and verify the package |
|
Run one complete analysis |
|
Understand inputs, outputs, and multi-sample behavior |
|
Understand the estimator and its limits |
|
Look up functions and parameters |
|
Diagnose an error |
Default Python call#
import scanpy as sc
import ambidose as amdose
adata = sc.read_10x_mtx("filtered_feature_bc_matrix/")
adata = amdose.denoise(adata, raw="raw_feature_bc_matrix.h5", sample_key=None)
counts = adata.X # denoised; original input is in layers["raw_counts"]
Barcodes on adata are the cell whitelist. raw= is the matching unfiltered matrix. The call returns a new object.
To load the raw matrix yourself and pass cell_barcodes=, see Quickstart.
Default CLI call#
ambidose denoise \
--input /path/to/cellranger/outs \
--output cleaned.h5ad
Pointing --input at a Cell Ranger outs/ directory automatically pairs the raw matrix with filtered barcodes.
Note
The entry point is denoise(). Treat rho as an operational scale; see Method.
Requirements and optional extras.
A first end-to-end run.
Raw Cell Ranger output to analysis-ready counts.
Inputs, labels, outputs, and CLI.
Model, estimator, and limitations.
Public Python interface.
Common decisions and failures.