Skip to contents

U-M4-02 设计备忘：ms_downsample() + 格式互操作首批

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

日期：2026-10-04（夜间窗口批次，继 U-M4-01 后随批）。状态：范围冻结 + 实现开工。

§0 范围裁决（夜间批收缩，[V] 纪律优先）

U-M4-02 全单元 = ms_qc_report() + ms_downsample() + ms_import/ms_export 首批三格式。本夜间批交付：

  1. ms_downsample()——语义锚定已交付的 M3b sanity 协议（R/calibrate-real.R：counts*_j ~ Multinomial(N, counts_j/total_j)，base R rmultinom 固定种子；同法同口径，包内零分叉）。
  2. ms_import() / ms_export()——COSMIC txt 一种格式：布局锚 = inst/reference/refdb/COSMIC_v3.6/COSMIC_v3.6_SBS_GRCh37.txt 等上游原始字节（Type 首列 + 每签名/样本一列），离线可逐位验证，无网络声明。

推迟（记录原因）：SigProfiler txt（Type+SubType 布局）与 WTSI 长格式——夜间窗口内未能取得上游规范样例文件做 [V] 逐位验证（GitHub 树检索未命中 example matrix；搜索通道被污染）；纪律是”不可验证即不交付”。ms_qc_report() 需报告字段设计裁决，独立小批。三者推日间批。

§1 ms_downsample() 冻结设计 

ms_downsample(catalog, depth = "min", seed = 1)
  • catalog：MsCatalog（channels × samples 计数）。
  • depth：正整数（公共目标深度）或 "min"（活样本最小总量）。
  • 语义（冻结）：逐活样本 total_j > depth ⇒ counts*_j ~ Multinomial(depth, counts_j / total_j)；total_j ≤ depth ⇒ 原样保留（不下采样不上采样）；total_j = 0 ⇒ 死样本保持零列。下采样只减不补——诚实退化语义与 sanity harness 一致。
  • 确定性：单一 set.seed(seed) 后按样本列序顺序 rmultinom——对给定 catalog + seed 逐位可复现（与 sanity harness 的顺序化 RM 约定一致；非 Rust 流——无 FFI 面，纯 R 数据操作，D13 口径：这是数据准备操作而非推断声明）。
  • 返回：新 MsCatalog，channels/labels/samples 原样；provenance 追加 downsample 记录（depth/seed/调用时间戳禁入——可复现性优先）。
  • 多项近似的诚实声明：有放回多项近似”无放回抽子集”（多元超几何）——深覆盖下偏差可忽略；超几何实现记升级臂（memo 一致模式）。

§2 COSMIC txt 互操作冻结设计

布局（锚 = 捆绑上游文件逐字节）：TSV，首列头 Type，行 = 通道标签（规范序），其后每列一个签名/样本；值 = 概率（签名文件）或整数计数（目录）。

  • ms_export(x, format = "cosmic", file = NULL)：x ∈ {MsCatalog（counts 列）, MsSignature（signatures 列）}；标签契约：行标签必须与通道注册表规范序逐一相等（不允许静默重排/子集——互操作的第一守则），失配 → 结构化 input 错误（首个失配 1-based 行号）。file = NULL 返回装配好的 data.frame（管道用）；给了 file → 写出（write.table sep=“ quote=FALSE）并 invisible 返回路径。浮点格式：导出以 17 位有效数字写出（2026-10-04 审计实测上游文件含 16 位字面量，15 位默认会截断至 max rel err 3.98e-15——17 位下概率面逐位往返；整数面本就逐位）。布局/标签逐位声称。
  • ms_import(file, format = "cosmic", kind = c("catalog", "signatures"), channel_table = NULL)：读 TSV；首列头必须为 Type；行标签匹配注册表——channel_table 缺省时按行数+标签集在注册表（SBS96/DBS78/ID83/SBS192/SBS1536）中唯一推断，推断失败 → 错误列举候选。kind="catalog" → MsCatalog（整数化校验：非整数值 → input 错误）；kind="signatures" → MsSignature（provenance 摘要记 file+hash）。
  • 测试：合成目录 export→import 逐位往返（整数计数）；真实 COSMIC v3.6 SBS96 文件 import → 标签集 == 注册表规范序（上游字节锚）+ 值逐位等于 read.delim；导出该签名集 → 重读逐位一致。

§3 验收锚

  • 【逐位/整数】：往返计数恒等；COSMIC 上游文件标签序 == 注册表规范序；rmultinom 固定种子逐位复现。
  • 【工程】：错误路径全结构化（标签失配/未知格式/非整数导入/depth 非法）；provenance 溯源字段齐。
  • 文档：ffi-surface 不动（无新 FFI 面——纯 R 数据操作）；CAPABILITY-MATRIX M4 行注记；NEWS.md。

§4 日间批补录（2026-10-04 23:1x CST：SigProfiler 解禁 + WTSI 维持推迟）

SigProfiler txt [V] 完成、解禁：三重上游锚，全离线可验—— 1. 真实样例：SigProfilerAssignment De_Novo_Solution_Signatures_SBS96.txt（10 签名 de-novo 输出，sha256 6567a77b…916）固化进 tests/testthat/fixtures/，行序与我方 SBS96 注册表逐位一致（R 实证 identical TRUE）。 2. ICAMS ConvertCatalogToSigProfilerFormat（R/other_catalog_formats.R 源码核实）：布局 = MutationType 首列表头 + 括号标签 A[C>A]A；SBS192/384/1536/DBS78/ID 同写法。 3. SigProfilerPlotting reference_formats（tools/channel-reference/，既有锚）：SBS96/384/DBS78 标签方言与我方注册表逐位一致（R 实证 384 identical TRUE）。

SigProfiler 布局冻结：TSV；首列头 MutationType（COSMIC 是 Type——两侧都接受首列任名、导出按 format 定名）；SBS96/384/1536 = 括号标签（= 我方注册表序，逐位）；SBS192 = T:/U: 前缀括号标签（= 我方方言）；DBS78 = AC>CA。值 = 概率或计数；标签契约同 COSMIC 面（== 注册表规范序，失配结构化报错）。

WTSI 长格式维持推迟：MutationType|Trinucleotide|Sample|count 四列定义在 zoo §1.19 有源码核实标记，但本窗口内仍未取得上游实样文件（ICAMS 无 WTSI 面；PCAWG WTSI 矩阵在 ICGC portal 后面需会话；本地 sigminer 的 Nik-lab 矩阵是 COSMIC 方言）。不可验证即不交付——留待拿到 PCAWG 原始 WTSI 矩阵的日间批。

signatures 导入面缺口（前批记录）：MsSignature validator 要求 exposures 有 dimnames，0 列矩阵 colnames() 恒 NULL——本批修 validator（显式放行 ncol==0 的合法空暴露面）后 signatures 导入随批交付。