RFC 0002: Region auto-annotation from sparse labels

[hutaobo]

Summary

Design-only RFC for the auto-annotation workflow you described:
given sparse expert structure labels on one slide, propagate them
to unannotated regions on the same slide with confidence and
abstain semantics, reusing the trained structure_head plus a
prototype/k-NN sanity path on the region embedding.

Scope

• Phase 1 (this RFC): same-slide propagation, both
  structure_head (temperature-calibrated) and
  prototype_knn paths emitted by default for comparison.
• Phase 2 / 3 (reserved fields only): cross-slide Xenium and
  H&E-only inference. Schema reserves expression_present,
  source_case_id, propagation_kind so the contract does not
  break later.

Key decisions worth your eyes

• Output is region_predictions.parquet with predicted_label,
  predicted_prob, entropy, nearest_seed_*, qc_flag,
  classifier, evidence_id. Probabilities are gated behind
  --write-probabilities to keep the default artifact small.
• Abstain rule combines a probability floor, an entropy ceiling,
  and a distance-to-nearest-seed quantile.
• Seed validation runs k-fold on the seeds themselves; macro-F1
  below 0.6 is a warning, not a fatal error.
• New runtime API stgpt.runtime.annotate_regions plus CLI
  stgpt annotate-regions. embed-regions is invoked
  transparently if missing.
• No code lands in this PR; this is the contract for sign-off.

Test plan

• Confirm the seed CSV contract matches your annotator's
  current workflow (region_id, structure_label, confidence)
• Decide whether Phase 1 should emit path_agreement.csv by
  default or only with --classifier both
• Decide whether low_seed_count (<5 per class) should be a
  warning or a fatal error in your real-data setting
• Approve the abstain defaults (tau_p=0.5, tau_h=log(K)-0.5,
  tau_d=p99(seed-to-seed))
• After sign-off, implement annotate_regions (Python +
  CLI) and the smoke test on the synthetic fixture

---

Generated by Claude Code

Summary by Sourcery

Documentation:

• 添加 RFC 0002，记录计划中的区域自动标注工作流、数据契约、算法路径、质量控制关卡、运行时 API、CLI 接口，以及针对同片传播和未来跨切片传播的分阶段路线图。

Original summary in English

Summary by Sourcery

Documentation:

• Add RFC 0002 documenting the planned region auto-annotation workflow, data contracts, algorithmic paths, QC gates, runtime API, CLI surface, and phased roadmap for same-slide and future cross-slide propagation.

[sourcery-ai]

Reviewer's Guide

仅设计层面的 RFC，引入新的区域自动标注工作流，用于在同一张切片上从稀疏的专家结构标签向其他区域传播标签；在尚未增加可执行代码的前提下，定义数据契约、算法（structure_head 和 prototype/k-NN 路径）、弃权（abstain）标准、运行时/CLI 接口、质控（QC）关卡、溯源机制以及测试计划。

File-Level Changes

Change	Details	Files
为基于稀疏标签的区域自动标注指定数据契约和输出，包括种子（seeds）、区域池、预测结果，以及为未来阶段预留的 schema 字段。	定义种子标签 CSV 格式，并对区域 ID、结构标签以及可选的置信度权重进行校验规则约束。 描述如何选择未标注的区域池，并可通过 include-no-image 和 region-ids 选项进行可选过滤。 定义 region_predictions.parquet 的 schema，包括 predicted_label、probabilities、entropy、nearest-seed 溯源信息、qc_flag、classifier 和 evidence_id。 引入可选的按类别概率输出，以及包含指标、QC 决策和溯源信息的 JSON auto_annotation_report。 为未来的跨切片和仅图像工作流预留额外的 schema 字段：expression_present、source_case_id、propagation_kind。	docs/rfcs/0002-region-auto-annotation.md
使用现有的区域 embedding 与 structure_head，定义核心自动标注算法以及弃权/验证逻辑。	描述路径 A：使用现有的 structure_head logits，并对种子进行温度缩放（temperature scaling），以获得校准后的概率。 描述路径 B：在归一化区域 embedding 上使用 prototype/k-NN，通过类别原型进行推断，当种子数量较少时回退到 k-NN。 定义弃权策略：基于概率下限、熵上限以及与最近种子的距离分位数阈值。 指定种子验证流程：仅在种子上进行 k 折交叉验证，并报告宏平均 F1（macro-F1）和混淆矩阵。 记录触发致命错误与警告的 QC 关卡，包括标签/ID 不匹配、种子数量过少、高弃权率，以及 embedding 质量问题。	docs/rfcs/0002-region-auto-annotation.md
引入用于调用自动标注工作流的运行时 API 和 CLI 接口，并定义可复现性和测试预期。	指定新的 stgpt.runtime.annotate_regions 入口函数签名和行为，包括在需要时自动调用 embed-regions。 定义 stgpt annotate-regions CLI 命令、参数以及典型调用方式。 描述通过指纹（fingerprints）和确定性的 evidence_id 哈希，再加上对随机步骤使用固定种子，以保证溯源与可复现性。 概述一个基于合成数据的单元测试，以及一个 CLI 冒烟测试：在不依赖真实 Atera 数据的前提下验证 schema、行为和可复现性。 记录范围、非目标、分阶段上线计划，以及未来扩展的开放问题（跨切片、仅 H&E、主动学习、染色标准化等）。	docs/rfcs/0002-region-auto-annotation.md

---

Tips and commands

Interacting with Sourcery

• 触发新评审： 在 Pull Request 上评论 @sourcery-ai review。
• 继续讨论： 直接回复 Sourcery 的评审评论。
• 从评审评论生成 GitHub issue： 在某条评审评论下回复，请 Sourcery 从该评论创建 issue。你也可以回复 @sourcery-ai issue 来从该评论创建一个 issue。
• 生成 Pull Request 标题： 在 Pull Request 标题的任意位置写上 @sourcery-ai，即可随时生成标题。你也可以在 Pull Request 中评论 @sourcery-ai title，以在任意时间（重新）生成标题。
• 生成 Pull Request 摘要： 在 Pull Request 正文任意位置写上 @sourcery-ai summary，即可在你希望的位置生成 PR 摘要。你也可以在 Pull Request 中评论 @sourcery-ai summary，以在任意时间（重新）生成摘要。
• 生成评审者指南： 在 Pull Request 中评论 @sourcery-ai guide，即可在任意时间（重新）生成评审者指南。
• 一次性解决所有 Sourcery 评论： 在 Pull Request 中评论 @sourcery-ai resolve，即可将所有 Sourcery 评论标记为已解决。当你已经处理完所有评论且不希望再看到它们时，这非常有用。
• 一次性忽略所有 Sourcery 评审： 在 Pull Request 中评论 @sourcery-ai dismiss，即可忽略所有现有 Sourcery 评审。特别适用于你想从头开始新的评审时——不要忘记随后评论 @sourcery-ai review 来触发新的评审！

Customizing Your Experience

打开你的控制面板 以：

• 启用或停用评审功能，例如 Sourcery 自动生成的 Pull Request 摘要、评审者指南等。
• 更改评审语言。
• 添加、删除或编辑自定义评审说明。
• 调整其他评审设置。

Getting Help

• 如有问题或反馈，请联系支持团队。
• 访问我们的文档以获取详细指南和信息。
• 关注我们在 X/Twitter、LinkedIn 或 GitHub，与 Sourcery 团队保持联系。

Original review guide in English

Reviewer's Guide

Design-only RFC introducing a new region auto-annotation workflow that propagates sparse expert structure labels across regions on the same slide, defining the data contract, algorithms (structure_head and prototype/k-NN paths), abstain criteria, runtime/CLI surface, QC gates, provenance, and testing plan without adding executable code yet.

File-Level Changes

Change	Details	Files
Specify data contracts and outputs for region auto-annotation from sparse labels, including seeds, region pool, predictions, and reserved schema fields for future phases.	Define seed labels CSV format with validation rules on region IDs, structure labels, and optional confidence weights. Describe how the unlabeled region pool is selected and optionally filtered via include-no-image and region-ids options. Define region_predictions.parquet schema with predicted_label, probabilities, entropy, nearest-seed provenance, qc_flag, classifier, and evidence_id. Introduce optional per-class probability output and a JSON auto_annotation_report with metrics, QC decisions, and provenance. Reserve additional schema fields for future cross-slide and image-only workflows: expression_present, source_case_id, propagation_kind.	docs/rfcs/0002-region-auto-annotation.md
Define the core auto-annotation algorithms and abstain/validation logic using the existing region embeddings and structure_head.	Describe Path A using the existing structure_head logits with temperature scaling on seeds for calibrated probabilities. Describe Path B using prototype/k-NN over normalized region embeddings with class prototypes and fallback k-NN for low seed counts. Define an abstain policy based on probability floor, entropy ceiling, and distance-to-nearest-seed quantile thresholds. Specify seed validation via k-fold cross-validation on seeds alone with macro-F1 and confusion matrix reporting. Document QC gates that trigger fatal errors vs warnings, including label/ID mismatches, low seed counts, high abstain rate, and embedding quality issues.	docs/rfcs/0002-region-auto-annotation.md
Introduce the runtime API and CLI surface for invoking the auto-annotation workflow, plus reproducibility and testing expectations.	Specify a new stgpt.runtime.annotate_regions entry point signature and behavior, including automatic embed-regions invocation when needed. Define the stgpt annotate-regions CLI command, arguments, and typical invocation pattern. Describe provenance and reproducibility guarantees via fingerprints and deterministic evidence_id hashes, plus fixed seeds for stochastic steps. Outline a synthetic-data unit test and a smoke CLI test that validate schema, behavior, and reproducibility without relying on real Atera data. Record scope, non-goals, phased rollout plan, and open questions for future extensions (cross-slide, H&E-only, active learning, stain normalization).	docs/rfcs/0002-region-auto-annotation.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.