xuzhougeng/wisp-science/singlecell-qc

Single-Cell QC

Overview

Use this skill for data-driven, human-centered single-cell QC. The analyst inspects distributions and confirms decisions; code computes metrics and executes only what was agreed.

inspect data → compute metrics → human reviews → confirm thresholds → small action → re-inspect

Not a one-click pipeline. Do not chain calculate → filter → doublet → merge unless the user explicitly requests full execution after reviewing pilot results.

Follow analysis-workflow for module and script layout. Match the user's language.

Read first: references/human-in-the-loop.md

When To Use

• "帮我看看这个样本 QC"
• "算一下 QC 指标，阈值我来定"
• "逐样本诊断，先别过滤"
• "这个 merge-first QC 太粗，怎么改成人工确认"
• "参考 GZL metrics 脚本，但要分步做"

Do not use for integration/Harmony, annotation, or spatial QC unless only expression-matrix QC is needed.

Operating Rules (Human-First)

1. Inspect before acting — matrix type, species, sample metadata, existing checkpoints.
2. Pilot samples first — default 1–3 samples; expand only after user OK.
3. Metrics before filters — run 01-calculate_metrics; stop and report.
4. Propose thresholds, never silently apply — show expected cell loss per sample.
5. Ask at gates — which metrics next? which thresholds? proceed to filter? merge?
6. No silent heavy steps — no full-cohort filter, Scrublet, decontX, or merge without explicit approval.
7. Reversible checkpoints — pre-filter metadata/counts stay intact; filtering writes new files.
8. Scripts = one stage — owner-editable; thresholds visible at top of filter scripts.

Full gate definitions: references/human-in-the-loop.md

First Pass (Always)

find <project_root> -maxdepth 4 -type f \( -name '*.py' -o -name '*.R' -o -name '*.h5ad' -o -name '*.md' \) | head -60
rg -n "filter_cells|calculate_qc|metadata|mito|n_genes" <project_root>/scripts 2>/dev/null | head -30

Report to the user:

• input matrix type (raw / filtered / EmptyDrops / h5ad);
• species; sample count;
• whether per-sample or merge-first QC exists;
• recommended next single step (not full pipeline).

Then ask which samples to pilot and which metrics matter for this tissue.

Staged Workflow (Default)

Each stage ends with human confirmation.

Stages D–G are skipped until the user says proceed.

Metric tiers (choose with user)

Details: references/metrics-catalog.md

Project Layout

Optional scaffold — create only stages the user needs:

scripts/01-qc/
  01-calculate_metrics.py|R   # metrics only
  02-qc_diagnosis.py|R        # figures from metadata
  03-filter_cells.py|R        # runs only after threshold sign-off
result/01-qc/ ...
figure/01-qc/ ...

references/project-layout.md

Bundled Tools (Not a Pipeline)

--run-scrublet on Python script: ask before using.

# Typical pilot — metrics only
python .../calculate_metrics.py \
  --matrix-dir <dir> --sample-id PILOT --species human \
  --output-dir result/01-qc/01-calculate_metrics/PILOT

After Metrics: Report Template

Use the template in references/human-in-the-loop.md:

• observations (numbers);
• flags (sex mismatch, high hbb, depth outlier);
• questions for the user (numbered);
• optional threshold table with estimated loss — label as not yet applied.

Language Choice

Pick one canonical metadata schema across languages (n_genes, n_UMIs, mito_frac, …).

Anti-Patterns

• Running full cohort filter + merge in one agent turn
• Picking thresholds without showing per-sample distributions
• Treating bundled scripts as end-to-end QC
• Hiding cutoffs inside opaque helpers
• Merge-first global QC without per-sample review (legacy atlas reproduction excepted)

Deliverables (Stage-Dependent)

Only produce what the current confirmed stage needs:

External References

• Rich metrics example (R): <project-root>/scripts/calculate_metrics_extended.R
• Legacy contrast (avoid as default): spatial_data/.../run_merging_samples_and_QC.py