Skip to contents

U-M4-02b 设计备忘：ms_qc_report() 初版（样本 QC 报告）

Source: vignettes/articles/devlog-2026-10-04-M4-02b-qc-memo.qmd

日期：2026-10-04（夜间窗口第二批）。范围：CAPABILITY-MATRIX L-A M4 行”样本 QC：负荷分布” + L-F 伪迹贡献初版（amber/red 拟合层级 ⏳v1.x 不在本批）。

§1 上游名册（[V] 状态）

COSMIC 官方 Artefact 名单（cancer.sanger.ac.uk SBS 索引页实时核实，2026-10-04）：SBS27、SBS43、SBS45–SBS60、SBS95 共 19 条（SBS27、SBS43、SBS45–SBS60、SBS95；页面文字称 “20 signatures total” 但枚举清单为 19——枚举为准），病因标注 “Artefact”。注意：SBS30/36 是真（NTHL1/MUTYH）、SBS18 是 ROS 损伤真签名——本面不按猜测除名。

FFPE/oxoG 机制标签（research/03 §文献，源码核实于 Excerno/FFPEsig 记录）：FFPE 相关伪迹（脱胺 C>T）与 oxoG（G>T 计数偏斜）是机制级检查，不是 COSMIC 名单签名；本批以启发式通道偏斜统计呈现（见 §3），不以签名拟合冒充。

amber/red（Degasperi 2022, 35949260）：样本级 amber/red 分级来自 GEL 论文的评估流程，逐位阈值未公开索引（论文补充材料级；signature.tools.lib 的 QC 签名目录检索未命中数据文件）。按 D13/[V] 纪律：本批不声称实现 Degasperi amber/red；样本分级用我方初版口径（§4，常数自报 + divergence 声明），Degasperi 忠实复刻记 ⏳v1.x（与 CAPABILITY-MATRIX “amber/red 拟合层级 ⏳v1.x” 行一致）。

§2 estimand 与输入

ms_qc_report(catalog, signatures = NULL, exposures = NULL, ...) → 逐样本 QC 行 data.frame（S7 之后的 v0.3 再对象化；本批 data.frame + print 方法）。

  • catalog：MsCatalog（必选）。负荷轴的估计对象 = 通道计数总和 per sample。
  • signatures/exposures：可选 MsSignature/refit 暴露（k×n）；给了才有伪迹贡献列（§4）。

§3 冻结字段（初版契约）

负荷块（永远有）： - sample、total（突变总数）、log10_total； - burden_class：low(<100)/standard([100,104))/high(≥104)——我方常数，声明 divergence（无上游统一阈值；mSigAct 默认丢 <100 SBS 是拟合下限不是 QC 分级）； - dead：total == 0。

通道偏斜启发式块（永远有；机制级伪迹哨兵）： - gt_share：C>A 通道份额——注册表是嘧啶归一化（C/T 参照、6 类×16 通道），oxoG 的 G>T 在本空间表现为 C>A；字段名保留 gt_share 记损伤视图（oxoG 伪迹 = G>T 偏斜，Costello 2013 23303777）； - c_t_share：C>T 份额——FFPE 哨兵（脱胺 C>T，Guo 2022 36068219）； - strand_bias_p：DpbhC→N 的 T>/C> 分组二项检验（SBS192 需要 TSB 目录；无 192 目录时 NA）——留接口，本批 NA。

伪迹贡献块（给了 signatures/exposures 才有）： - artifact_share：COSMIC Artefact 名单（§1 的 19 条 SBS）暴露份额 = Σ暴露(名单)/Σ暴露(全字典)； - artifact_sigs：份额 >0 的名单签名（逗号连接，标称字符串）。

分级（我方初版，D13 声明）： - qc_flag ∈ {ok, watch, artifact}：artifact_share ≥ 0.05 ∨ g_gt_share ≥ 0.30 ⇒ artifact；c_t_share ≥ 0.40 ∨ burden_class==“low” ⇒ watch；否则 ok。常数为我方初版默认、文档自报；v1.x 的 amber/red 忠实复刻会替换这块。

§4 验收锚

  • 【整数/逐位】：total/log10 逐样本 == colSums；artifact_share 在合成字典上全数字钉测（造 3 签名：SBS1 拷贝 + 一条 COSMIC 名单签名形 + 一条正常形）；
  • 名单 [V]：内部常量与 §1 的 19 条逐一相等（测试字面钉死，防手滑）；
  • 错误路径：exposures 列数 != catalog 样本数 → input 结构化；signatures 不是 SBS96 通道空间 → input（名单只在 SBS96 语义下有效）。

§5 文档联动

CAPABILITY-MATRIX L-A 行注记”初版交付（amber/red 忠实复刻 ⏳v1.x）“；NEWS.md；本备忘 = D13 口径文档。无新 FFI 面（纯 R 数据操作）。