OSP One-Sample Pipeline: QC → Clustering/DEG → Report → AI Annotation

OSP One-Sample Pipeline: QC → Clustering/DEG → Report → AI Annotation A workflow diagram generated by Archify. 01 / Entry · python -m osp 02 / Quality control · osp.qc 03 / Clustering & DEG · osp.cluster 04 / AI annotation · osp.annotate (optional --annotate) 05 / Output directory · outdir Input H5AD · backed read, one sample · Entry · python -m osp · counts layer over X Input H5AD backed read, one sample counts layer over X QC metrics & flags · hard · MAD · Scrublet · Quality control · osp.qc · low_quality flag QC metrics & flags hard · MAD · Scrublet low_quality flag DecontX estimate · pure-Python port · Quality control · osp.qc · evidence only, no filter DecontX estimate pure-Python port evidence only, no filter Leiden + UMAP · normalize · HVG · PCA · Clustering & DEG · osp.cluster · QC covariates in PCA Leiden + UMAP normalize · HVG · PCA QC covariates in PCA DEG + PAGA · each cluster vs rest · Clustering & DEG · osp.cluster DEG + PAGA each cluster vs rest Annotation agent · agent-harness-bridge · AI annotation · osp.annotate (optional --annotate) · check_genes · subcluster Annotation agent agent-harness-bridge check_genes · subcluster Check submission · schema + cluster coverage · AI annotation · osp.annotate (optional --annotate) Check submission schema + cluster coverage qc_summary.csv · qc_removed.csv ledger · Output directory · outdir qc_summary.csv qc_removed.csv ledger clustered.h5ad · DEG · summary · PAGA · Output directory · outdir · atomic writes clustered.h5ad DEG · summary · PAGA atomic writes report.html · embedded plots, one file · Output directory · outdir report.html embedded plots, one file Proposal JSON · annotation_proposal.json · Output directory · outdir · completion signal Proposal JSON annotation_proposal.json completion signal submit labels PCA covariate write tables keep passing cells ambient all cells + reasons --annotate: read outputs select sample render apply, refresh, publish reject, resubmit Legend HTML report Analysis step Validation gate Output file LLM agent Input data

Design constraints

  • • Strictly one sample per run; no cross-sample batch integration
  • • QC filtering removes cells, with reasons recorded in qc_removed.csv
  • • AI annotation only proposes (_ann_*, _qc_action); it never drops cells or reruns QC

Entry points

  • • python -m osp data.h5ad --sample S --outdir out [--annotate]
  • • python -m osp.qc / osp.report / osp.annotate run the stages separately
  • • Python API: run_one_sample_pipeline + generate_report

Completion and atomicity

  • • H5AD, CSV, JSON, and report writes go through a temp file then replace
  • • annotation_proposal.json is published last and marks completion for outer drivers
  • • Reruns delete the old report and proposal first so stale files never look complete