stereo-seq-project-orchestration

name: stereo-seq-project-orchestration description: Use when a Stereo-seq or STOmics project has multiple samples, serial sections, batches, time points, conditions, donors, replicates, or mixed h5ad/RDS/GEM outputs and needs sample-sheet validation, project metadata design, multi-sample QC summaries, batch/integration handoff, or cross-sample workflow orchestration before downstream Stereo-seq skills.

Stereo-seq Project Orchestration

Use This For

• Designing or auditing a Stereo-seq project sample sheet before QC, integration, 3D reconstruction, annotation, or statistical testing.
• Checking that sample, section, batch, donor, condition, time point, replicate, bin size, and spatial-unit metadata are explicit and non-confounded.
• Summarizing multiple h5ad objects into a project-level QC table and handoff plan.
• Choosing whether to keep per-sample analysis, merge, integrate, align serial sections, or run replicate-aware inference.

For raw GEM/GEF/SAW conversion, use stereo-seq-quality-control-preprocessing. For serial-section geometry registration, use stereo-seq-3d-reconstruction. For biological condition inference, use stereo-seq-statistical-design.

Default Requirements

• Read source_code.md before writing project-level code. The project patterns come from public Stereo-seq article repositories and method repositories, not generic workflow guesses.
• If no curated source fits, search code_candidates.tsv and stereo-seq-publication-story/references/github_code_registry.tsv before external search.
• Keep biological replicate, technical section, spatial slice, batch, donor, and condition as separate columns. Do not encode them only inside sample names.
• Do not integrate or batch-correct until per-sample QC and metadata confounding have been checked.
• Preserve a per-sample file path for each analysis object and report whether the object is raw, filtered, normalized, integrated, aligned, or annotation-ready.
• In the final response, state the reused paper, DOI, repository/source file, and dataset-specific edits.

Workflow

1. Identify the project unit: sample, section, slice, donor, time point, treatment, condition, cellbin/bin size, and desired downstream module.
2. Validate the sample sheet with scripts/stereo_project_sample_sheet_qc.py.
3. For h5ad projects, run scripts/multi_h5ad_project_qc_summary.py to summarize dimensions, count/gene QC, coordinate bounds, and sample-level covariates.
4. Decide the handoff:
   • per-sample QC or raw count export: stereo-seq-quality-control-preprocessing;
   • multi-section integration or batch evaluation: Spatialign/BatchEval-inspired workflow, then domain/mapping skills;
   • serial-section coordinate reconstruction: stereo-seq-3d-reconstruction;
   • condition or replicate inference: stereo-seq-statistical-design.
5. Write an analysis manifest with inputs, sample metadata, selected downstream skill, and integration/statistical assumptions.

Reusable Article Code

• scripts/stereo_project_sample_sheet_qc.py: sample-sheet validator inspired by Endo.R directory/sample organization, ascidian Seurat integration, ZebrafishHeartRegeneration multi-slice scripts, and BatchEval metadata-driven multi-dataset evaluation.
• scripts/multi_h5ad_project_qc_summary.py: multi-h5ad QC summary and project handoff table adapted from BatchEval QC plot logic and multi-sample Stereo-seq h5ad workflows.

When using any bundled script, report the paper and original source file from source_code.md.

Output Expectations

• Validated sample sheet or clear blockers.
• Project-level QC table with per-sample dimensions, count/gene summaries, coordinate bounds, and missing metadata.
• Confounding checks for condition, batch, donor, and replicate where metadata is available.
• Integration/handoff recommendation and which local Stereo-seq skill should run next.
• Reused article code source, DOI, repository, original file name, and dataset-specific edits.