Sc Doublet Detection

sc-doublet-detection

When to use

The user has filtered (or at least QC'd) single-cell counts and wants to flag putative doublet barcodes before clustering / annotation. Five backends share one CLI: scrublet (default, Python), doubletdetection (Python), doubletfinder (R), scdblfinder (R), scds (R). Per-cell scores + binary calls land in obs; this skill annotates, it does not remove cells (filter downstream with obs["predicted_doublet"]).

Use from a step

doublets = load_skill("sc-doublet-detection")
adata = doublets.detect_doublets(read_input("filtered.h5ad"), random_state=0)
write_output(doublets.doublet_calls_table(adata), "tables/doublet_calls.csv")
write_output(doublets.doublet_score_figure(adata), "figures/doublet_scores.png")
write_output(adata, "intermediate/adata_doublets.h5ad")

Detection annotates the input in place; it never removes cells. To remove the calls, pass the result to sc-filter. See examples/example_step.py.

API

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

detect_doublets(adata, *, method: str='scrublet', expected_doublet_rate: float=0.06, threshold: float | None=None, batch_key: str | None=None, n_iters: int=10, standard_scaling: bool=False, scds_mode: str='cxds', random_state: int=0)

Annotate doublets in place using counts from layers['counts'], raw or X.

No observations or features are removed. Pass the result to sc-filter when doublets should be removed. A DoubletFinder failure may fall back to scDblFinder; a failed scds mode may fall back to cxds. run_info records both.

:param adata: AnnData containing a count-like matrix. :param method: scrublet, doubletdetection, doubletfinder, scdblfinder or scds. :param expected_doublet_rate: Expected doublet fraction; default 0.06. :param threshold: Scrublet score cutoff; None keeps its automatic calls. :param batch_key: Scrublet batches in obs; None analyzes all cells together. :param n_iters: DoubletDetection iterations; default 10. :param standard_scaling: DoubletDetection standard scaling; default False. :param scds_mode: cxds, bcds or hybrid; default cxds. :param random_state: Seed passed to the selected backend; default 0. :returns: The same AnnData with doublet_score, predicted_doublet and doublet_classification in obs, plus JSON diagnostics in uns. :raises ValueError: A method, rate, threshold or batch column is invalid. :raises ImportError: A Python backend is missing; use install_skill_deps. :raises RuntimeError: An R method and any documented fallback fail.

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

Read doublet method diagnostics from adata.uns.

:param adata: AnnData annotated by detect_doublets. :param keep: False removes the JSON diagnostics after reading; default True. :returns: Method, counts, matrix source and any fallback details.

doublet_calls_table(adata, *, groupby: str | None=None) -> pd.DataFrame

Return per-cell scores and calls in observation order.

:param adata: AnnData annotated by detect_doublets. :param groupby: Optional obs column to include in the table. :returns: A DataFrame with cell_id, scores, calls and classification.

doublet_summary(adata) -> pd.DataFrame

Return singlet and doublet counts and percentages from obs calls.

:param adata: AnnData with predicted_doublet in obs. :returns: A DataFrame with one row per classification.

group_summary_table(adata, *, groupby: str) -> pd.DataFrame

Summarize doublet counts and scores for an obs grouping column.

:param adata: AnnData annotated by detect_doublets. :param groupby: Existing obs column defining the groups. :returns: A DataFrame with counts, median and mean scores, and rates. :raises ValueError: The grouping column is missing.

doublet_score_figure(adata)

Plot the doublet score distribution and return the Figure.

:param adata: AnnData with doublet_score in obs. :returns: A matplotlib Figure; the caller saves it with write_output.

<!-- api:end -->

Methods and parameters

• method="scrublet" and expected_doublet_rate=0.06 retain the CLI defaults. Set the rate from loading density and the experimental design.
• threshold=None retains Scrublet's automatic calls; a numeric threshold applies only to Scrublet. batch_key runs Scrublet by that obs column; it does not make the other backends batch-aware.
• DoubletDetection retains n_iters=10 and standard_scaling=False.
• R backends use Rscript and temporary gene-by-cell MTX plus CSV metadata; they do not need a Python environment inside R. DoubletFinder requires Seurat, DoubletFinder and Matrix; scDblFinder/scds require their matching package, SingleCellExperiment and Matrix.
• random_state=0 now reaches every backend, including Scrublet and R. Previously the CLI ignored this parameter for Scrublet; scDblFinder used a fixed R seed of 42. Missing Python packages raise an import error.