/singlecell-qc

name: singlecell-qc
description: Use when designing, reviewing, or implementing single-cell RNA-seq QC in Python or R with a human-in-the-loop, data-driven approach. Trigger for scRNA QC metrics, per-sample diagnosis, threshold discussion, mitochondrial/ambient/doublet assessment, MAD vs fixed cutoffs, or refactoring automated merge-first QC. The analyst confirms key decisions at each step—agents must inspect data, propose options, and wait for approval before filtering, doublet removal, or merging. Not a turnkey pipeline skill.

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.

| Stage | Script / action | Agent stops until user confirms | |-------|-----------------|--------------------------------| | A | Input inspection | sample list, matrix, species | | B | `01-calculate_metrics` (pilot) | metric scope (core / hbb / doublet / …) | | C | `02-qc_diagnosis` figures | figures match expectations | | D | Threshold proposal (table + loss estimate) | per-sample cutoffs | | E | `03-filter_cells` | filter summary acceptable | | F | optional doublet / ambient | method and aggressiveness | | G | `04-merge_qc_passed` | all samples signed off |

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

Metric tiers (choose with user)

| Tier | Metrics | Ask when | |------|---------|----------| | Core | `n_genes`, `n_UMIs`, `mito_frac`, `pct_counts_rb` | always unless h5ad already has them | | Recommended | `hbb_score`, `doublet_score`, cell cycle | tissue-dependent | | Extended | `chrY_frac`, `ambient_frac`, `nuclear_frac` | metadata / STARsolo available |

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)

| Tool | Role | |------|------| | `scripts/calculate_metrics.py` | core metrics → `metadata.tsv` | | `scripts/calculate_metrics.R` | same, R/Matrix | | `scripts/inspect_qc_metadata.py` | read-only cohort summary | | `assets/gene_sets/*` | hbb / chrY gene lists | | `assets/qc_thresholds.example.yaml` | template for **user-edited** thresholds |

`--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

| Context | Reference | |---------|-----------| | scanpy / h5ad | `references/python-scanpy.md` | | Seurat | `references/r-seurat.md` | | threshold methods | `references/filtering-strategies.md` |

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:

| After stage | Deliverable | |-------------|-------------| | B | `metadata.tsv`, `metrics_summary.json` | | C | diagnosis PDFs/PNGs | | D | threshold proposal table (no filte