gangchen/epiage-skill

表觀遺傳時鐘計算器

從 beta 值檔案計算 DNA 甲基化老化時鐘。提供 25 個時鐘；GrimAge 是其中的重點時鐘。

完全自足。 僅需 pandas + numpy——無需 biolearn、torch、seaborn、scipy 或 network。時鐘係數和參考資料已封裝在 data/ 目錄下（從開源的 biolearn 庫提取，並裁剪至時鐘實際使用的 CpG 位點，總計約 1 MB）。scripts/compute_clocks.py 忠實地再現了 biolearn 的 GrimageModel、LinearMethylationModel 以及 DunedinPACE 的分位數正規化（使用純 numpy 的 rankdata），其對所有 25 個時鐘的輸出與 biolearn 一致（已驗證差異 < 0.005，即僅為四捨五入誤差）。

時鐘列表（執行 --list-clocks 可查看即時清單）

家族	時鐘	單位
GrimAge（第二代，死亡率相關）	grimagev1, grimagev2	年 (需要年齡與性別)
第一代，時間順序年齡	horvath, horvath2, hannum, lin, vidalbralo, weidner, garagnani, bocklandt	年
第二代，生物年齡	phenoage, hrsinchphenoage	年
Ying 2022（因果關係）	yingcausage, yingdamage, yingadaptage	年
隨機性	stoch, stocp, stocz	年
組織特異性	pedbe（兒童頰黏膜）, cortical（大腦）	年
第三代，老化速率	dunedinpace, dunedinpoam	年/年
其他標記	dnamtl（端粒 kb）, zhang（死亡率）, epitoc1（有絲分裂）	因時鐘而異

群組別名（用於 --clocks 參數）：all、grimage、core（預設）、firstgen、secondgen、thirdgen。

dunedinpace 需要約 20k 個背景 CpG 位點 來進行分位數正規化（不僅僅是其 173 個模型 CpG 位點）。對於稀疏輸入，它會從金標準參考資料中自行推算缺失的背景 CpG 位點；如果其報告的覆蓋率遠低於約 90%，則結果將由參考資料主導且不可靠——請務必說明此情況。完整的 EPIC/450K 匯出資料則可良好涵蓋。

關於 GrimAge 的關鍵事實（以便正確解讀）

GrimAge 是第二代、以死亡率為訓練目標的時鐘：它先估計 7 種血漿蛋白質和吸菸包年數（V2 版本增加了 DNAm A1C & CRP）的 DNAm 替代標記，然後結合實際年齡和性別將其納入一個存活模型中。年齡和性別直接輸入公式，因此 grimage* 時鐘都需要這兩個參數。其他時鐘則不需要它們，但傳入 --age 參數可以讓工具報告加速值。

工作流程

1. 檢查輸入檔案

自動偵測的佈局：長格式（兩列：CpG ID + beta 值）或矩陣格式（第一列為 CpG ID，其餘列為樣本）。Beta 值為 [0,1] 之間的浮點數。請注意行數；每個時鐘的 CpG 覆蓋率將按時鐘分別報告。

2. 取得年齡和性別

GrimAge 需要此資訊。如果只知道年齡範圍，請使用範圍中位數並加上 --sensitivity 參數執行，以便使用者了解結果對確切年齡的敏感程度。

3. 檢查依賴項（僅需 pandas + numpy）

python3 -c "import pandas, numpy" 2>/dev/null && echo OK || pip install pandas numpy

無需虛擬環境、biolearn、torch 或網路連線。

4. 執行

python3 <skill-dir>/scripts/compute_clocks.py \
  --input "<betas.csv>" --age <years> --sex <m|f> \
  --clocks all                 # 或：core（預設）、grimage、firstgen、secondgen 或特定鍵值
  # --sensitivity 40 42 47 49  # 可選，當確切年齡不確定時使用
python3 <skill-dir>/scripts/compute_clocks.py --list-clocks   # 查看所有鍵值

該腳本會從附帶的（已裁剪）data/sesame_450k_median.csv 族群參考資料中推算任何缺失的時鐘 CpG 位點，執行每個模型，並輸出一個包含數值、加速值（針對以年為單位的時鐘）和覆蓋率的表格，以及一行供後續使用的 JSON。

5. 報告與解讀

以 GrimAge 為重點，然後進行比較。始終傳達以下警示：

• 這是開源再實作，並非官方計算器。 數值與 Horvath 官方伺服器 / Clock Foundation 接近，但非認證數值。若要引用，請指向 Horvath DNAm Age 計算器或商業供應商。
• 此處的「加速」= 時鐘年齡 − 實際年齡，為簡單的差值。學術上的 AgeAccel（相對於同年齡組群的殘差）需要族群樣本，無法為單一個體計算——因此 +8 表示「表觀遺傳預測年齡比實際年齡大 8 歲」，而非「比同儕老 8 歲」。
• 世代不同。 第一代（Horvath/Hannum/Lin/…）以實際年齡為目標，通常接近真實年齡。第二代（GrimAge/PhenoAge）以健康結果為目標，能更好地預測死亡率和老化——他們本就可以與實際年齡有差異。請勿將 GrimAge 解讀為「看起來 N 歲」；它本質上是一個以年為單位的風險分數。
• 非以年為單位的時鐘（dunedinpoam 速率、dnamtl 端粒 kb、zhang/stocz 死亡率風險、epitoc1 有絲分裂）不是年齡——因此不會顯示加速值。
• 覆蓋率 / 推算：從族群中位數填入少數缺失的時鐘 CpG 是正常現象；請標記覆蓋率低於約 90% 的時鐘。輸出中的 n_lowconf 欄位計算了其血液參考標準差 > 0.08 的推算 CpG 數量（這些是最不可信的填入值）——這是一個比單純覆蓋率更精細的每 CpG 信號。即使某個時鐘「成功執行」，若其 n_lowconf 數量很多，則該樣本的結果不可靠。
• 僅限血液設計。 此技能假設輸入為人類全血。時鐘應用於血液；推算參考資料也源自血液。請勿用於其他組織。
• 缺失 CpG 的推算——預設使用 methyLImp。 缺失的時鐘 CpG（例如，在 MSA/WeGene 匯出檔案中缺失的 EPIC 訓練 CpG）將使用 methyLImp 進行推算：這是一種降階（PCA）回歸方法，利用全血面板中的 CpG 間相關性結構，根據樣本中觀測到的 CpG 來預測每個缺失的 CpG——當組織匹配時，其準確度遠高於直接使用固定中位數（RMSE 降低約 30%）。面板中不存在的 CpG 則會回退到血液中位數；n_lowconf（血液 SD > 0.08）標記不可靠的填入值。使用的方法將在執行開始時印出。
  • 面板資料位於 data/blood_panel.npz 檔案中，已隨技能打包（約 5 MB；預先從 GSE40279（656 個全血 450K 樣本）建立，並縮減至時鐘 CpG + 50 個血液主成分 + 每 CpG 中位數/標準差）。因此，methyLImp 開箱即用——在保留 CpG 的基準測試中，其推算 RMSE 比固定中位數降低了約 10%。若要重建/自訂，請執行 scripts/build_blood_panel.py。如果檔案遺失，工具會優雅地降級為全域中位數並告知使用者。
  • 實際情況：methyLImp 主要改善高度依賴推算的時鐘。覆蓋率高的時鐘（GrimAge/Horvath/PhenoAge）只需要推算少量 CpG，因此其數值無論如何變化都小於 0.2 年——信心標記是其實際應用中更重要的功能。
• 非醫療建議——僅供研究/教育用途使用。

備註

• 矩陣格式輸入 → 每個樣本每個時鐘一行結果。
• 刻意排除（無法在不使用較重運算資源的情況下忠實再現，或非老化時鐘）：
  • PC 時鐘（PCHorvath…）、AltumAge、GPAge——需要 PCA 旋轉/神經網路。
  • 妊娠期時鐘（Knight、Lee、Mayne、Bohlin）——適用於臍帶血/新生兒。
  • 特質和疾病預測器（BMI、膽固醇、吸菸、酒精、阿茲海默症、心血管疾病等）——這些是生物標記模型，而非老化時鐘。 如果使用者特別需要上述任何一項，請告知他們需要完整的 biolearn 安裝。
• 來源。 係數來自 biolearn（MIT 授權），該庫再現了已發表的時鐘。GrimAge 在化妝品和人壽保險用途上有商業使用限制（UCLA TDG / Clock Foundation）。