解釋中心
系統全景 · 第 11 頁 · 給第一次接觸的人

這套系統由哪些部件組成，各自做什麼？

本頁回答四個問題：目標是什麼、有哪些部件、每個部件吃什麼吐什麼、現在哪些真的能跑。 每個部件的細節在各自分冊頁，本頁只給地圖與狀態。

一分鐘版本

這套系統要解決的問題是：從 bulk 長讀長資料建立可審核的局部突變狀態候選結構，並標出哪些證據仍不足以確認細胞譜系。

傳統做法用短讀長測序，只能看到每個位點各自的變異頻率；若只靠 per-locus marginal VAF、且沒有 linkage 或額外模型假設，此逆問題不可識別。 本系統改用 ONT 長讀長：一條 DNA 分子動輒數萬鹼基，可以同時跨過好幾個突變位點， 於是「這兩個突變在不在同一條實驗取樣到的物理分子上」成為直接觀測；它們是否來自同一細胞群、以及譜系關係，仍是受模型與輔助資料限制的推論。

系統由 兩支 C++ 主程式（InterSubMod、LongLineage）＋ 一層上游工具鏈 ＋ 一層 Python 分析與 HTML 呈現組成。 其中只有一部分現在真的跑得動 —— 下面的狀態表會誠實標出來。

本系統最值得注意的設計 它在機器欄位的層級把「技術跑通」和「科學可用」分開：canonical cohort_receipt.json 承載 technical_all_pass = true，而 summary/all7_summary.json 承載 validation_evidence_eligible = false。Frozen cohort receipts 的具名 checks 對其引用的 frozen artifacts 通過；這不是 current-source certification，也不是 production／release gate PASS，因此這批結果還不能當作驗證證據。 這種「不確定就明講不確定」的紀律，貫穿整份設計。

01全景圖 — 資料從哪裡進來，經過誰，變成什麼

由下而上共五層。方框顏色 = 現在的可用狀態： 綠 可跑 黃 有限制 紅 被鎖住。

圖 1 · 五層全景與資料流
五層系統全景圖 由下而上分為原始資料層、上游工具層、read-label representation、兩支 C++ 主程式層、Python producer 與 validator/HTML 呈現層。 原始 ONT BAM 經 Dorado 產生甲基化標記、ClairS 產生體細胞突變清單、LongPhase-S 產生單倍型標籤；InterSubMod 從 BAM aux tags 讀 HP/PS，exact-PS/LongLineage 使用 sidecar，兩者不是直接 runtime interface； InterSubMod 與 LongLineage 兩支程式各自讀取這些輸入；前者可由 exact checkout clean build，後者在 private candidate b9aaa12 可跑 preflight，且 frozen HCC1395 receipt 由 dataset-gate 產生 research artifacts，run/probe 仍 BLOCKED； commit-pinned Python research solver 可作有獨立 receipt 的 science producer；validator/builders 與 HTML 只呈現 validated data，不暗中重算 science。 ① 原始資料 tumor BAM（ONT） HCC1395 = 292 GB normal BAM 配對正常組織 reference FASTA GRCh38 + .fai 必備 ← 這三樣是所有分析的共同起點；BAM 需自帶 MM/ML 甲基化標記 ② 上游工具（都是外部既有軟體，不是本專案寫的） Dorado basecaller 電訊號 → 鹼基 + 甲基化 產出 MM / ML tag ClairS v0.4.0 腫瘤/正常配對比對 產出 somatic SNV VCF LongPhase-S 判斷每條 read 來自哪一套染色體 產出 HP / PS tag SAVANA（cna） 拷貝數變異 目前 NOT_INTEGRATED 前三個是必要輸入的生產者。 SAVANA 的 CN 結果尚未接進主線。 ③ Read-label representations — BAM tags 與 sidecar 平行、非直接 runtime interface HP/PS sidecar TSV（.tsv.gz + .tbi 索引） #CHROM START0 END0 QNAME FLAG MAPQ CIGAR_B2 HP PS exact-PS/LongLineage 用 sidecar；InterSubMod 從 BAM aux tags 讀 HP/PS，不直接讀 sidecar。 為什麼用 sidecar 而不是直接存 tagged BAM： 7 paired_full = 1.674 TiB；sampled-only；NON_FINAL ④ 兩支 C++ 主程式（本專案核心） InterSubMod（inter_sub_mod） 可跑 研究原型。對每個 somatic SNV 開一個視窗，把跨過它的 read 的甲基化狀態排成矩陣 → 算 read-read 距離 → 分群 → 統計檢定。 輸出粒度：per-region（每個位點一包結果） ddd8909a 釘選 census：29 options（branch-scoped）· clean build receipt exit 0 吃：tumor BAM + reference + somatic VCF（必要） 吐：methylation.csv · distance_matrix · tree.nwk · significance_summary.csv LongLineage（longlineage） 部分可跑 PRIVATE research-preview candidate；origin/license/dependency audit pending。 NOT_READY / non-production；P3/P4/P5/P7/P8 BLOCKED。 輸出粒度：per-read（每條 read 一列） b9aaa12 candidate：run/probe 被鎖；HCC1395 frozen dataset-gate 有 artifacts 吃：8 角色 manifest（BAM + VCF + sidecar + reference） 吐：site_reads · methyl_calls · cooccurrence_* · topology_unit ⑤ Python science producer vs validator／HTML presentation Commit-pinned research solver 共現骨幹 · candidate family 獨立 input/command/schema/hash receipt Validator · builder · HTML validated data · 明示分母 缺值拒絕渲染 · 不重算 science Python 是語言，不是 evidence tier：solver 與 presenter 必須分開登錄。 HTML 只能呈現 validated artifact；localStorage 判讀不能取代 producer receipt。 ⚠ 未釘選 producer/receipt 的 Python 結果不得升格 authority
怎麼讀這張圖：由下往上是資料流方向。InterSubMod 從 BAM aux tags 讀 HP/PS； exact-PS／LongLineage 使用 sidecar。兩者是 commit-scoped 平行 provenance contracts， 不是兩支引擎直接串接的執行期介面；tagged-BAM writer 另依 feature/preview commit 判讀。
數字出處：292 GB tumor BAM 與 40,859,727 列 sidecar 皆為具名歷史量測。2026-08-13 另盤點 14 個 PRE-FIX canonical tagged BAM（7 paired_full＋7 paired_pileup）合計 3,709,322,840,333 bytes。7 個 paired_full 的 exact paths/bytes/mtimes 合計 1,840,983,466,353 bytes（1.6743647 TiB），且 2026-08-13 重播 2026-07-11 首／中／尾 1 MiB sampled-identity receipt 為 7/7 MATCH。 但未計算 full-file SHA-256，也未證明與現行 7 sidecar 的 producer revision／內容等價，因此仍是 PARTIAL/NON_FINAL。 exact stat bytes quotient 為 294.2669×，只可稱跨世代 storage-footprint comparison；不是因果壓縮率或 frozen authority，舊 287× 無效。

02兩支程式是什麼關係？（和直覺不同）

最容易誤會的一點：LongLineage 不是 InterSubMod 的新版本，也不是它的分支。

InterSubMod（ISM）LongLineage（LL）
定位研究原型：C++ 核心 ＋ 大量 Python 探索腳本PRIVATE research-preview candidate：truth-isolated、fail-closed；source-origin／license／dependency audit pending
git 起源71ce312e7a8f75e8 — 完全不同的根 commit
血緣—ORIGIN.md 記錄 21 條 source mapping 與 17 條 authority；在 origin/license gate 完成前，不把 clean-room／可公開來源當成已驗證結論
輸出粒度per-region（每個 SNV 位點一包）per-read（每條 read 一列）
單倍型來源直接從 BAM 的 aux tag 讀明文禁止讀 BAM tag，只認 sidecar TSV
對「甲基化能不能參與重建」的立場絕不參與 只做事後關聯描述是必要關卡 甲基化分不出群的位點不會有拓撲解
● 兩系統的科學立場直接衝突 ISM 的既有結論是「甲基化絕不進入重建的 likelihood」，因為會產生循環論證（見下方 §4）。 但 LL 現行程式碼把「甲基化有沒有分出群」當成拓撲單元的前置關卡。 後果：在 LL 裡，甲基化沒分出群的位點永遠不會有拓撲解 —— 這是一個選擇性偏誤來源。 任何跨系統的比較都必須明講這點，否則會得出與 ISM 既有結論矛盾的敘述。

03現在到底哪些能跑？—— 誠實狀態表

這張表是本頁最實用的部分。所有狀態都是本輪實際執行過或讀原始碼確認的結果，不是文件宣稱。

部件狀態實測依據與限制
inter_sub_mod
ISM 主程式		 可跑 build output 不入版控；fresh clone 必須從 exact checkout 在 clean build directory 建置。具名 internal fixture 曾有單次 2.9 秒、exit 0 receipt，僅限該硬體／commit／輸入，不是讀者 runtime promise；含 normal BAM＋LOH BED 的 internal receipt 亦不可替代 clean-clone 驗收。
longlineage preflight 可跑 驗證 8 個角色的 manifest 完整性。
longlineage dataset-gate 限制 在 b9aaa12 candidate 的 frozen HCC1395 receipt 中，這是唯一觀察到能產生 research artifacts 的介面，該次產出 8 個 artifact。 ● 但 樣本名稱硬寫死在原始碼裡 —— 換一個樣本就會失敗，必須改 C++ 重新編譯。
longlineage run / probe 被鎖 run/probe 仍無條件回 KernelBlocked (exit 6)。 release_attestation.json 的 P3/P4/P5 與 phase ledger／public-safety receipt 的 P7/P8 具名 gates 尚未通過，涵蓋 parity／validation、source-origin、license、dependency 與 release-safety。 部分 M1／M2／topology kernels 曾由具名 dataset-gate 執行，不等於全部核心、production entry 或公開資格完成；整體仍為 NOT_READY/non-production。
longlineage 的 topology 產出 目前為 0 b9aaa12 candidate 的 frozen HCC1395 dataset-gate receipt：79,687 個位點 → 通過甲基化關卡的只剩 5 個 → mutation-state candidate topology units 0 個。 134,278 個配對中有 134,276 個被標記為不合格；此單一 receipt 不可外推其他 revision、dataset 或 run。
longlineage-query / export-legacy 未實作 仍是 fail-closed 的空殼。
research exact-PS candidate solver
獨立 Python + C++ 路徑；不是 inter_sub_mod		 可跑 這是產出 frozen exact-PS candidate funnel 的路徑；已覆蓋 7 個 technical datasets／6 個 biological IDs（見下方 §5）。它不把 model-selected candidate shape 升格成細胞譜系。
7 個 technical datasets 的 sidecar 資料 齊全 實測 run_status.tsv 顯示 7/7 全部 PASS，可立即使用。
輸出帶標籤的 BAM 版本相依 InterSubMod 沒有寫 BAM 的能力。LongLineage private baseline/main snapshot 5daf50f 也沒有；private public-preview candidate b9aaa12 已含 longlineage-tag-bam。 這只是 revision-scoped、尚未發布的 NOT_READY 能力；不可寫成公開或 production 可用。
兩支程式串起來跑 無 沒有任何腳本同時執行兩個 binary（雙向搜尋皆無命中）。目前是兩條各自獨立的線。
給教授看的三句重點
  1. 可作本次研究交接重現的主線，是 InterSubMod ＋ 獨立 research solver；LongLineage 仍是 PRIVATE/NOT_READY preview candidate。兩者的數字與 receipt 不可混用。
  2. LongLineage 的 P3/P4/P5/P7/P8 具名 gates 尚未通過：部分 kernels 的具名 dataset-gate receipt 不能取代 parity／validation、source-origin／license／dependency 與 release-safety。
  3. 沒有一條打通兩支程式的路。零件很齊、契約很嚴，但接縫還沒建。

04為什麼甲基化不能拿來重建譜系？

這是整套方法論最核心、也最常被外部讀者質疑的設計決定，值得單獨解釋。

直覺上會想：既然甲基化模式在不同細胞群之間有差異，那用甲基化把 read 分群，不就能找出亞群了嗎？ 不行 —— 因為會產生循環論證。

圖 2 · cis-ASM 循環：為什麼「用甲基化確認亞群」證明不了東西
甲基化循環論證示意 左側顯示一個位點觀察到兩群不同甲基化模式的 read，右側列出四種可能成因： germline 等位特異性甲基化、雜合性缺失導致的解遮蔽、拷貝數增益的劑量效應、以及真正的亞群譜系差異。 在目前 single-bulk 測量集合下，若無 orthogonal data 或額外假設，這四者不可識別；因此不能用甲基化分群獨立確認亞群。 觀察到「兩群甲基化模式不同的 read」時，至少有四種成因，單一 bulk 分不開 觀察 同一位點的 read 分成甲基化高 / 低兩群 甲基化高 甲基化低 ① germline 等位特異性甲基化 天生兩套染色體的甲基化就不同（如印記基因） ② LOH 解遮蔽 腫瘤丟掉一套染色體，原本被平均掉的差異浮現 ③ 拷貝數增益的劑量效應 某段被複製多份，比例被拉偏 ④ 真正的亞群譜系差異 ← 我們想要的 不同細胞群確實帶不同甲基化 循環論證 要用甲基化「確認」某群 read 是亞群， 得先排除 ①②③。 但要排除 ①②③，就得先知道 哪些 read 屬於哪個亞群 —— 這正是待證明的結論。 目前 single-bulk measurements 加現有假設，無法識別四種成因。 ✔ 本系統的解法：改用「同一條分子上的突變共現」當骨幹 一條 read 上同時看到兩個候選 allele = 物理分子連鎖；只在不使用甲基化衍生標籤下非循環。 仍依賴 variant calling、alignment、basecalling 與 haplotag 假設；不是 assumption-free truth。 甲基化被隔離在主線之外：遺傳候選結構先固定，甲基只在事後做關聯描述，改不動邊。
這個設計的代價與收穫：代價是甲基化這個資訊量很大的軸被降級成輔助； 收穫是避免「用甲基定義群、再用甲基驗證群」這一項可預見的循環論證批評；這不代表已通過外部同儕審查。 實際數字上，在 frozen formal family 中，甲基化輔助層共 1,045 個正式單元、811 個可評估、 最終只有 3 個（0.37%）達到該定義下的 robust pattern-conditioned association。這是現行設計不把該 formal family 當骨幹的一個理由，不是所有 methylation signal／backbone design 的總檢定。

05實際跑出來長什麼樣？—— 7 technical datasets／6 biological IDs funnel

這是目前的 canonical 結果（2026-08-01 凍結，7 個 technical datasets／6 個 biological IDs、chr1–22）。 每一層的數字都能在 denominator_registry.tsv 或 all7_summary.json 裡查到。

469,849
sSNV dataset records（7 technical datasets）
66.5219%
170,131／255,752 k=1 strict components；非 dataset-record 比例
71,955
可由 frozen read-AF model 排序的 candidate units
0
confirmed 細胞亞群
圖 3 · 從 469,849 筆 dataset records 到 63,506 筆 model-assigned candidate-shape records
七 technical-dataset candidate funnel 分流圖 從 469,849 筆 dataset records 開始，經 strict read-linked component 建構得到 255,752 個成分；170,131 個 k=1 成分占 strict-component 分母 66.5219%。component census 無法推得 isolated dataset-record percentage； k 大於等於 2 者經有界切分成為 98,955 個分析單元，扣掉無突變者剩 85,941 個帶突變單元； 其中 12.47% 因搜尋資源上限而放棄，75,224 個完成候選家族枚舉；再扣除分母為零與遞迴篩選者， 71,955 個可排序；frozen model 中 39,648 筆有單一最高分 candidate、23,858 筆雖有並列 candidate 但共享 rooted-unlabeled shape signature、8,449 筆 candidate shape 未解。 sSNV dataset records（7 technical datasets · chr1–22） 469,849 嚴格 read-linked 連通成分 255,752 k=1 strict components 170,131 / 255,752 = 66.5219% 不可換成 dataset-record 分母 無 isolated-record 比例；非生物正確率 k≥2 有共現 → 有界切分後的分析單元 85,621 → 98,955 k>12 的大成分被切開， 所以單元數會變多 帶突變的單元 85,941（86.85%） 無活躍 ALT，不推論 13,014（13.15%） 候選結構家族 完整枚舉完成 75,224（87.53%） 算力上限，主動放棄 10,717（12.47%） 非隨機缺失，集中在複雜區 可用 read-AF 排序 71,955（95.65%） 分母為 0 / 遞迴篩選 3,224 + 45 frozen model 單一最高分 candidate 39,648（55.10%） data-record 層級；非生物真值 並列 candidates，共享 shape signature 23,858（33.16%） frozen model/data-record 層級 並列且跨不同樹形 8,449（11.74%） 「定不出來」← 這也是答案 單一 rooted-unlabeled candidate-shape signature = 39,648 + 23,858 63,506 / 71,955 = 88.2579%
算術自洽性已驗證：39,648 + 23,858 = 63,506；+ 8,449 = 71,955；+ 3,224 + 45 = 75,224； + 10,717 = 85,941；+ 13,014 = 98,955。每一層加總都對得起來。
● 最常被誤引的數字就是 88.2579%。它的正確讀法是： 「在已經可排序的 71,955 個 candidate units 中，frozen model 對 63,506 個（88.2579%）指派單一 rooted-unlabeled candidate-shape signature」—— 這是 model-conditional 的圖形統計，不是「腫瘤裡 88% 的演化關係已經解出來了」。 分母不是全部突變。圖中的 170,131 個 k=1 是 170,131 / 255,752 strict read-linked components = 66.5219%；component census 無法推得 isolated dataset-record percentage，不能改除以最上游 469,849 dataset records。後續另有 12.47% 的資源上限放棄。
● 排序器同時也是篩選器 — 一個容易被忽略的細節 read-AF 不只用來「排序」候選樹，它在同分的候選集合裡取最大值並丟掉其餘， 因此它實際上也改變了候選集合本身（實測丟棄 30.03%）。 後果：純 parsimony（不靠 AF）的單一 candidate-shape 比率只能說是一個區間，不能報單一數字。 ⚠ 本輪查證發現：該區間的上界 88.2579% 有 registry 佐證， 但下界 64.89% 在本 repo 內未 grep 到原始出處，僅存在於工作記憶索引 —— 對外引用前必須先補上出處。

06能回答什麼、不能回答什麼

這節直接取自 authority_manifest.json 的 claim_boundary 欄位 —— 是機器可讀的宣稱邊界，不是散文。

✔ 可以主張 permitted

  • 嚴格 read-linked 的局部區域結構
  • 家族完整時，完整的最小 read-相容突變狀態候選家族
  • 允許遞迴的 Hamming-1 父子樹候選
  • 未經 CN/LOH 校正的 deterministic read-AF 排序
  • 全域 AF-best 數學樹的 exact rooted-unlabeled 拓撲普查
  • pattern-conditioned 的區域甲基化關聯（非因果）

✘ 明文禁止主張 forbidden

  • confirmed 細胞層級的 clone / subclone
  • CN/LOH 校正過的 CCF
  • 校準過的 likelihood 或 posterior
  • 把 read cluster 當成 cell clone
  • 用甲基化差異重排拓撲
  • 把 HCC1395 與其 DORADO 重跑當成生物學重複

已測為 negative／blocked 的方向（新假說須重新稽核）

方向為什麼不行
對整棵樹做機率排序 候選樹在 likelihood 下等機率，posterior 只會吐 P=1/N。 換成連續 posterior「只是換個記法，變不出 reads 裡不存在的資訊」。
用甲基化排序拓撲 三個理由全否：cis 構造對稱、四配子最常見成因是拷貝數多重性而非二次突變、 等機率區沒有遺傳真值可校驗（等於拿甲基驗甲基）。
甲基化非監督分群確認亞群 單一位點的四種成因不可拆（見 §4），屬已判 NEGATIVE 的 tumor-only double-dip。
甲基化當變異 TP/FP 過濾器 已測 formulation concluded negative；重開須 materially new hypothesis + pre-decision audit。
用舊的 50 kb 鄰近取代嚴格 read linkage 幾何鄰近不等於同分子連鎖。已被 read-linked 方法取代。
證據等級的天花板 在目前單一 bulk observation／model 且未整合 CN／LOH 的條件下，不能確認 cellular subclone 或 linear ancestry，因此目前封頂 ★3。single-cell、multi-region、orthogonal CN／purity 等額外獨立證據可能提高識別性；不宣稱只有某一種 assay 可行。Steiner 節點會被 誠實標成 inferred。

07接下來看哪一頁

依你的目的挑一頁進去。

ISM 部件與輸入輸出 可跑

ddd8909a 的釘選 29-option census（branch-scoped）、內部 8 個處理階段、每個輸出檔的真實欄位與範例行。

吃 → tumor BAM + reference + somatic VCF
吐 → methylation.csv · distance_matrix · tree.nwk
進入 ISM 分冊 →

LongLineage 部件與契約 部分可跑

Private candidate b9aaa12 的 4 個子命令狀態、frozen HCC1395 M1→M2→candidate-topology 鏈、artifact schema 與 read_id 算法。

吃 → 8 角色 manifest
吐 → site_reads · cooccurrence_* · topology_unit
進入 LL 分冊 →

上游工具鏈與資料 齊全

sSNV / HP-PS / 甲基化 / CN 各自從哪個工具來、7 個 technical datasets（6 biological IDs）的實體資料在哪。

Dorado · ClairS · LongPhase-S · SAVANA · sidecar TSV
進入上游分冊 →

Python 分析層與 HTML 呈現層

主力腳本各自做什麼、工作站 HTML 怎麼生成、這層目前的碎片化問題。

分析腳本 → workstation spec → standalone HTML
進入呈現層分冊 →

怎麼跑 — 操作手冊 可複製指令

從編譯到跑出第一個結果的完整步驟，每條指令都已實際執行驗證過。

build → 最小跑法 → 完整跑法 → 看結果
進入操作手冊 →

科學方法細節 既有頁面

名詞定義、ISM 方法本體、甲基化讀取與篩選、chr2:18M 真實案例逐步拆解。

解釋中心第 01–10 頁
回 INDEX 選頁 →