gangchen/epiage-skill

エピジェネティック時計計算機

DNAメチル化β値ファイルから老化時計を計算します。25種類の時計が利用可能で、GrimAgeが代表的なものです。

自己完結型。 pandas + numpy のみ必要 — biolearn、torch、seaborn、scipy、networkは不要。時計係数と参照データは data/ にベンダー提供されています（オープンソースのbiolearnライブラリから抽出され、各時計が使用するCpGのみにトリミング、合計約1MB）。scripts/compute_clocks.py はbiolearnの GrimageModel、LinearMethylationModel、およびDunedinPACEの分位正規化（numpyのみの rankdata を使用）を忠実に再実装し、全25時計の出力をbiolearnと一致させています（誤差<0.005、つまり丸め誤差のみ）。

時計一覧（--list-clocks で最新リストを表示）

ファミリ	時計	単位
GrimAge（第2世代、死亡率）	grimagev1、grimagev2	年 (年齢+性別が必要)
第1世代 暦年齢	horvath、horvath2、hannum、lin、vidalbralo、weidner、garagnani、bocklandt	年
第2世代 生物学的年齢	phenoage、hrsinchphenoage	年
Ying 2022（因果性）	yingcausage、yingdamage、yingadaptage	年
確率的	stoch、stocp、stocz	年
組織特異的	pedbe（小児頬粘膜）、cortical（脳）	年
第3世代 老化ペース	dunedinpace、dunedinpoam	年/年
その他のマーカー	dnamtl（テロメア kb）、zhang（死亡率）、epitoc1（有糸分裂）	様々

--clocks のグループエイリアス: all、grimage、core（デフォルト）、firstgen、secondgen、thirdgen。

dunedinpace は分位正規化のために約2万のバックグラウンドCpGが必要（自身の173モデルCpGだけでなく）。スパースな入力の場合、不足するバックグラウンドCpGをゴールドスタンダード参照から自己補完します。報告されるカバレッジが約90%を大きく下回る場合、結果は参照に依存し信頼性が低くなります。完全なEPIC/450Kエクスポートであれば問題なくカバーされます。

GrimAgeに関する重要な事実（正しく解釈するため）

GrimAgeは第2世代、死亡率トレーニング済みです。7つの血漿タンパク質 + 喫煙パック年のDNAmサロゲートを推定し、それらを暦年齢と性別とともに生存モデルで組み合わせます。年齢と性別が直接式に入力されるため、grimage* 時計には両方が必須です。他の時計には不要ですが、--age を渡すと加速化（acceleration）を報告できます。

ワークフロー

1. 入力ファイルの検査

自動検出されるレイアウト: Long（2列: CpG ID + β値）または Matrix（最初の列がCpG ID、残りの列がサンプル）。β値は[0,1]の浮動小数点数です。行数をメモし、各時計のCpGカバレッジは時計ごとに報告されます。

2. 年齢と性別の取得

GrimAgeに必須。年齢範囲のみ判明している場合は中間値を使用し、--sensitivity を実行すると、正確な年齢に応じて結果がどの程度変化するかを確認できます。

3. 依存関係の確認（pandas + numpy のみ）

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

venv、biolearn、torch、ネットワークは不要。

4. 実行

python3 <skill-dir>/scripts/compute_clocks.py \
  --input "<betas.csv>" --age <年齢> --sex <m|f> \
  --clocks all                 # または: core（デフォルト）、grimage、firstgen、secondgen、特定のキー
  # --sensitivity 40 42 47 49  # オプション、正確な年齢が不明な場合
python3 <skill-dir>/scripts/compute_clocks.py --list-clocks   # 全キーを表示

スクリプトは、不足している時計CpGをバンドルされた（トリミング済み）data/sesame_450k_median.csv の集団参照から補完し、各モデルを実行し、値、加速化（年単位時計の場合）、カバレッジの表と、下流処理用のJSON行を出力します。

5. 報告と解釈

GrimAgeを先頭に、比較を行います。以下の注意事項を必ず伝えてください。

• オープンソースの再実装であり、公式計算機ではありません。 値はHorvathの公式サーバー/Clock Foundationに近いですが、認定された数値ではありません。引用可能な値が必要な場合は、Horvath DNAm Age計算機または商用プロバイダーを案内してください。
• ここでの「加速化」 = 時計 − 暦年齢、単純な差です。学術的な AgeAccel（同年齢コホートとの残差）は集団サンプルが必要であり、一人では計算できません。したがって +8 は「エピジェネティック予測年齢が暦年齢より8歳高い」という意味で、「同年代より8歳老けている」ではありません。
• 世代が異なります。 第1世代（Horvath/Hannum/Lin/…）は暦年齢をターゲットとし、実際の年齢付近に収まる傾向があります。第2世代（GrimAge/PhenoAge）は健康アウトカムをターゲットとし、死亡率/老化をよりよく予測します — 設計上、実際の年齢から乖離することがあります。GrimAgeを「N歳に見える」と読まないでください。これは年単位のリスクスコアです。
• 非年単位の時計（dunedinpoam ペース、dnamtl テロメア kb、zhang/stocz 死亡率リスク、epitoc1 有糸分裂）は年齢ではありません — 加速化は表示されません。
• カバレッジ / 補完: いくつかの欠損時計CpGを集団中央値で補完するのは正常です。カバレッジが約90%を下回る時計にはフラグを立ててください。出力の n_lowconf 列は、血液参照SD > 0.08の補完CpGの数をカウントします（信頼できない補完） — カバレッジ単独よりも鋭いシグナルです。多くの n_lowconf 補完がある時計は、たとえ「実行」されてもこのサンプルでは信頼できません。
• 血液のみの設計。 このスキルはヒト全血を想定しています。時計は血液に適用され、補完参照も血液です。他の組織には使用しないでください。
• 欠損CpGの補完 — デフォルトでmethyLImp。 欠損時計CpG（例：MSA/WeGeneエクスポートに存在しないEPICトレーニングCpG）は methyLImp で補完されます：サンプルの観測された CpGから、全血パネルのCpG間相関構造を使用した低ランク（PCA）回帰により、各欠損CpGを予測します — 単純な中央値より正確（組織が一致する場合、RMSEが約30%低い）。パネルにないCpGは血液中央値にフォールバックします。n_lowconf（血液SD>0.08）は信頼できない補完を示します。アクティブなモードは実行開始時に表示されます。
  • パネルは data/blood_panel.npz にありバンドルされています（約5MB；GSE40279（656全血450Kサンプル）から事前構築され、時計CpG + 50血液PC + CpGごとの中央値/SDに削減）。したがってmethyLImpはすぐに使用可能で、保持CpGベンチマークで平坦な中央値と比較して補完RMSEを約10%削減します。再構築/カスタマイズするには scripts/build_blood_panel.py を実行してください。ファイルが欠落している場合、ツールはグローバル中央値にグレースフルにフォールバックし、その旨を表示します。
  • 現実的な確認: methyLImpは主に大量補完が必要な時計を改善します。高カバレッジ時計（GrimAge/Horvath/PhenoAge）はほとんどCpGを補完しないため、値の変動は0.2年未満 — 信頼性フラグの方が実用的に重要です。
• 医療アドバイスではありません — 研究・教育目的専用。

注記

• Matrix入力 → 時計ごとにサンプル1行の結果が出力されます。
• 意図的に除外（より重い機械なしでは忠実に再現できない、または老化時計でないもの）:
  • PC時計（PCHorvath…）、AltumAge、GPAge — PCA回転/ニューラルネットが必要。
  • 妊娠期間時計（Knight、Lee、Mayne、Bohlin） — 臍帯血/新生児用。
  • 特性および疾患予測子（BMI、コレステロール、喫煙、アルコール、アルツハイマー、CVDなど） — これらはバイオマーカーモデルであり、老化時計ではありません。 ユーザーが特にこれらのいずれかを必要とする場合、完全なbiolearnインストールが必要であることを伝えてください。
• 由来。 係数はbiolearn（MIT）のもので、公開された時計を再実装しています。GrimAgeには化粧品および生命保険用途に対する商用利用制限（UCLA TDG / Clock Foundation）があります。