decontx-scanpy

Scanpy-native Python port of DecontX (Yang et al., Genome Biology 2020; Bioconductor package campbio/decontX) — estimation and removal of ambient RNA contamination in droplet-based single-cell RNA-seq data. Import name: pydecontx.

• Faithful: the variational-EM kernels are a line-for-line vectorized port of the upstream src/DecontX.cpp, validated against the actual upstream kernels (compiled from source and driven by the original R EM loop) to machine precision — max θ difference ~4e-16 with a shared initialization; Pearson r > 0.99 end-to-end with independent RNGs.
• Complete: automatic broad-cluster estimation (PCA → UMAP → DBSCAN with k-means fallback, as in R), empty-droplet background support incl. per-batch backgrounds and barcode-overlap checks, multi-batch mode, in-place AnnData results following scanpy conventions.
• Fast, no compiler: pure numpy/scipy; nonzeros are grouped by cluster once so each EM pass streams cache-resident columns (~0.5 s/iteration at 20k cells × 12k genes × 22M nonzeros, single core).
• No R required. Only DecontX is ported (not DecontPro).

Install

pip install decontx-scanpy

Usage

import scanpy as sc
from pydecontx import decontx

adata = sc.read_h5ad("filtered_cells.h5ad")   # raw counts, cells x genes

# recommended: use your own annotation / clustering
decontx(adata, z="cell_type", batch="sample")           # modifies in place

# or let DecontX estimate broad clusters (PCA -> UMAP -> DBSCAN)
decontx(adata)

# with empty droplets as the ambient profile
decontx(adata, background=raw_droplets_adata)

adata.layers["decontX_counts"]        # decontaminated counts (non-integer; round if needed)
adata.obs["decontX_contamination"]    # per-cell contamination fraction
adata.obs["decontX_clusters"]         # clusters used
adata.uns["decontX"]["estimates"]     # theta/phi/eta/delta/log-likelihood per batch

A plain cells × genes matrix (numpy or scipy sparse) is also accepted; a result dict is then returned, mirroring the R list return. A simulate_contamination() generator (port of the R one) is included for testing.

Key parameters (same semantics as R): delta=(10, 10) with estimate_delta=True controls the prior on per-cell contamination — set estimate_delta=False with a larger second value for more aggressive removal; max_iter=500, convergence=0.001.

The model

Each cell's observed counts are a two-component multinomial mixture: a native gene distribution phi[:, k] of the cell's population k, and a contamination distribution eta[:, k] aggregating every other population's expression, mixed by a per-cell native proportion theta ~ Beta(delta). Variational EM yields per-transcript native probabilities; the decontaminated matrix is counts × P(native).

Validation

The test suite (tests/, 30 tests) has three layers:

1. R parity: the upstream DecontX.cpp is compiled via Rcpp::sourceCpp and driven by a verbatim copy of the R EM loop on identical inputs. With a shared initial θ and fixed δ the Python kernels match to ~4e-16 (θ), ~5e-13 (decontaminated matrix); with δ re-estimated, ~2e-4; end-to-end r > 0.99. Cached reference outputs ship in the sdist, so pytest needs no R installation.
2. Kernel units: EM step vs a literal dense transcription of the C++ loops; Dirichlet-MLE (Minka fixed point) recovery.
3. Functional: ground-truth recovery on simulations (r = 0.998, MAE 0.004 at ~10% contamination), ~99% removal of marker-gene cross-contamination, background / batch / error paths.

Citation

If you use this package, please cite the DecontX paper:

Yang, S., Corbett, S.E., Koga, Y. et al. Decontamination of ambient RNA in single-cell RNA-seq with DecontX. Genome Biology 21, 57 (2020).

License

MIT. Ported from the MIT-licensed Bioconductor package decontX; see LICENSE for attribution.