Wednesday, June 24, 2026

NMF (Non-negative Matrix Factorization,非負矩陣分解),顯示 PI3K-Akt 、Ras(Ras-MAPK/ERK)與 Rap1是鰻魚卵巢「生存與生長」的重要訊號通路。

 NMF 與其他降維工具(如 PCA)有何不同?

PCA(主成分分析)允許負數存在。在 PCA 中,一個細胞的特徵可能是由「表現基因 A」加上「表現基因 B」再「減去基因 C」所構成。雖然數學上很精準,但在生物學上,我們很難去解釋什麼叫作「負的基因表達量」。

因此,NMF 產出的結果往往比 PCA 更具有生物學可讀性與解釋性。

卵巢分析(實例)
原始矩陣 V:行是細胞,列是高變異基因。
NMF 分解出 n 個 Factor (K=n):
W矩陣幫你把上千個基因凝聚成 n 個「功能基因模組」。這就是為什麼你可以拿 W 矩陣(在你程式裡的 h_gene_df)去跑 KEGG 通路富集。
H 矩陣告訴你每個細胞在各個 Factor 的強度。你在 UMAP 圖上看到的細胞分群,就是根據細胞在 H 矩陣中的生物學模組傾向(例如:這個細胞在 F4 血管特徵的得分最高)來進行着色和分類。

















🔍 主要信號富集(左圖)

核心發現

  1. Ribosome 通路

    • 在 F1、F2、F7、F8 聚類中 最顯著(顏色最深,P 值最低)。
    • 基因數量最多(點最大),表示這些聚類中的基因高度參與核糖體相關功能(如蛋白質合成)。
    • 生物學意義:核糖體是細胞基本功能單位,其富集可能反映細胞增殖、蛋白質翻譯活躍等生理狀態。
  2. Coronavirus disease 通路

    • 在 F1、F2、F7 中顯著富集。
    • 可能與 病毒感染、免疫應答 相關,或數據集本身包含病毒相關樣本。
  3. 其他顯著通路

    • Fluid shear stress and atherosclerosis:在 F1、F2 中富集,可能與 血管生理/病理(如動脈粥樣硬化)相關。
    • Regulation of actin cytoskeleton:在 F3、F4 中富集,反映 細胞骨架重塑(如細胞遷移、形態改變)。
    • F5 聚類特異性:富集 神經退行性疾病通路(Parkinson、Alzheimer、Huntington disease),可能代表 神經系統相關的分子特徵。
  4. F6 聚類

    • 富集 代謝相關通路(如 Glycolysis/Glucogenesis、Diabetic cardiomyopathy),提示 代謝重編程 可能是此聚類的特點。

🌑 隱藏信號富集(右圖)

核心發現

  1. Ribosome 通路

    • 在 F1_Minor、F2_Minor、F7_Minor、F8_Minor 中仍高度顯著,與主要信號一致。
  2. Coronavirus disease 通路

    • 在 F1_Minor、F2_Minor 中富集,但顯著性略低於主要信號。
  3. 信號轉導通路

    • PI3K-Akt signaling pathway(F1_Minor):調控 細胞生長、存活、代謝,常在癌症或發育中富集。
    • ECM-receptor interaction(F1_Minor):細胞外基質相互作用,與 細胞黏附、遷移 相關。
    • Rap1 signaling pathway(F3_Minor):參與 細胞黏附、血小板活化。
  4. 疾病相關通路

    • Prion disease、Pathways of neurodegeneration(F4_Minor):神經退行性疾病相關,與 F5 主要聚類類似。
    • Tuberculosis(F5_Minor):可能反映 免疫應答或病原體感染 的隱藏信號。
  5. F6_Minor 聚類

    • 富集 代謝通路(Glucagon signaling、Alzheimer disease),與 F6 主要聚類一致。

💡 生物學解讀

  1. Ribosome 通路的普遍富集

    • 表明 蛋白質合成 在多個聚類中都是核心過程,可能與 細胞增殖、分化 或 應激響應 相關。
  2. Coronavirus disease 通路

    • 如果數據集非病毒相關,可能反映 免疫系統激活 或 類病毒機制(如內源性逆轉錄病毒元件)。
  3. 神經退行性疾病通路(F5/F4_Minor)

    • 提示部分聚類可能來自 神經組織樣本,或與 神經炎症、蛋白質聚集 相關。
  4. 信號轉導通路(隱藏信號)

    • PI3K-Akt、Rap1 等通路在隱藏信號中富集,可能揭示 次級調控網絡,如細胞存活或黏附機制。

從 NMF 模組富集圖來看,左圖(Main Pathway)中 Rap1 在特定模組(如 F6, F7)表現出顯著性;而右圖(Hidden Signal)中,PI3K-Akt、Ras、Rap1 同時在右上角的微小模組(F7_Minor 等)中高度富集。這傳遞了幾個關鍵的生物學訊息:

  1. 環境應答與微環境感知: Rap1 經常受到 cAMP、鈣離子(Ca2+}) 或流體剪切應力(Fluid shear stress)的驅動。當環境壓力或細胞外基質發生變化時,Rap1 通路會率先被活化,協調細胞骨架的重塑。

  2. 空間與增殖的動態平衡: 細胞在決定分裂(Ras/PI3K-Akt)之前,通常必須先確認自身的空間定位與黏附狀態(Rap1)。這兩條路徑在 Hidden Signal 中高度共富集,暗示著這組基因模組正在精密調控細胞黏附形態的改變與下游存活/生長訊號的連動(Cross-talk)。

  3. 拮抗與協同: 在許多生理過程中,Rap1 被視為 Ras 的「緩衝器」或「微調器」。當 Ras 訊號過強時,Rap1 可以透過競爭結合位點來避免 ERK 的過度活化;而在需要細胞遷移(例如發育或內皮細胞修復)時,兩者則會協同放大訊號。

簡單來說,Ras 負責決定「要不要長」,而 Rap1 負責搞定「要在哪裡站穩、怎麼動」。在你的組學數據中,這兩者的協同富集非常適合用來解釋細胞在特定環境刺激下,如何兼顧結構重組與存活訊號。


核心功能與生理角色的分工

  • Ras 信號通路(點燃生長與存活的信號)

    • 核心角色: 細胞生長、增殖、分化與存活的「總開關」。

    • 經典游: 當細胞表面受體(如 RTK)被生長因子活化後,Ras 被招募並活化,進而啟動經典的 Raf-MEK-ERK (MAPK) 級聯反應,或是 PI3K-Akt 通路。

    • 直觀隱喻: 它是細胞決定要不要分裂、增殖的「油門」。

  • Rap1 信號通路(形塑骨架與細胞間的連結)

    • 核心角色: 主要負責細胞的黏附(Adhesion)、細胞骨架重塑(Cytoskeleton remodeling)、細胞連接(Cell-cell junctions)以及血小板活化。

    • 經典下游: 活化 Integrin(整合素)以增強細胞與細胞外基質(ECM)的黏附,或透過限制 RhoA 來穩定細胞間的緊密連接(Tight junctions)。

    • 直觀隱喻: 它是細胞用來抓緊固定、錨定空間位置的「錨與結構手」。

特性Ras 信號通路Rap1 信號通路
主要上游訊號生長因子(EGF, FGF 等)、細胞激素鈣離子、cAMP(透過 Epac 活化)、剪切應力、Integrin 訊號
主要下游效應因子Raf-1 (c-Raf), PI3K, RalGDSB-Raf, RIAM (整合素活化), AF6 (細胞連接), Rac1
對 MAPK (ERK) 的作用強效活化(透過 Raf-1)具細胞特異性。在某些細胞中會競爭性抑制 Raf-1(踩剎車);但在具備 B-Raf 的細胞中(如神經或特定內分泌細胞),Rap1 反而能活化 B-Raf 進而促進 ERK 活化。
細胞表型促進細胞週期、抗凋亡、增殖細胞平鋪、移動、建立屏障結構、血小板聚集
#########################################

核心網絡拓撲結構

從 Main 和 Hidden 兩個面板的交叉比對,可以識別出三個功能層級的網絡節點:
┌─────────────────────────────────────────────────────────────┐
│                    第一層:基礎細胞功能模組                    │
│  F1/F2/F3/F4/F8 ──→ Ribosome + Coronavirus disease          │
│  (蛋白質合成、病毒反應——細胞基礎穩態維持)                    │
├─────────────────────────────────────────────────────────────┤
│                    第二層:神經-代謝軸                        │
│  F5 ──→ Neurodegeneration (Huntington/Alzheimer/ALS/        │
│         Parkinson/Prion) + Glycolysis/Gluconeogenesis        │
│  (神經退行性疾病群集——代謝重編程核心)                        │
├─────────────────────────────────────────────────────────────┤
│                    第三層:血管-免疫-細胞骨架軸                 │
│  F6/F7 ──→ Cell adhesion/Focal adhesion + Platelet          │
│            activation + Leukocyte migration +                │
│            Complement/Phagocytosis                           │
│  (血管內皮功能、凝血、免疫細胞遷移)                          │
└─────────────────────────────────────────────────────────────┘


整合網絡模型


                    ┌─────────────────┐
                    │   卵巢組織微環境   │
                    └────────┬────────┘
                             │
        ┌────────────────────┼────────────────────┐
        │                    │                    │
        ▼                    ▼                    ▼
   ┌─────────┐        ┌─────────┐          ┌─────────┐
   │  F1-F4  │        │   F5    │          │  F6-F7  │
   │ (Ribosome│        │(Neuro-  │          │(Vascular-│
   │ /Virus) │        │degeneration)│       │Immune)  │
   └────┬────┘        └────┬────┘          └────┬────┘
        │                  │                    │
        │         ┌────────┴────────┐           │
        │         │                 │           │
        │    F4_Minor          F5_Minor         │
        │  (Neuro genes      (Adhesion/        │
        │   in ribosome      Migration         │
        │   module)          in neuro         │
        │                      module)          │
        │                 │                    │
        └─────────────────┼────────────────────┘
                          │
                          ▼
                   ┌─────────────┐
                   │  神經-血管-   │
                   │  免疫交互軸   │
                   │ (Nexus)      │
                   └─────────────┘


在單細胞轉錄組分析中,PI3K-Akt 與 Ras(通常指 Ras-MAPK/ERK)是細胞內最核心的兩大「生存與生長」訊號通路。當它們在特定細胞群(如您的 F7_Minor 模組)中同時被富集時,通常意味著該細胞群正處於高度活躍的增殖、分化、細胞存活或組織重塑狀態。

這兩條通路就像是細胞內的兩套「中央調控系統」,雖然下游功能有重疊,但側重點各不相同:

PI3K-Akt 訊號通路:細胞的「生存與代謝總管」

PI3K-Akt 通路主要負責調控細胞的存活(抗凋亡)、大小生長、蛋白質合成與葡萄糖代謝。

🔄 通路運作機制

  1. 活化:當細胞外的生長因子(如胰島素 Insulin、IGF-1)結合到細胞膜表面的受體(RTK)時,會活化 PI3K(磷脂醯肌醇3-激酶)。

  2. 傳遞:PI3K 會在細胞膜上產生次級訊息,進而將 Akt(蛋白質激酶B) 招募到膜上並將其磷酸化(活化)。

  3. 下游效應:活化的 Akt 會像一個開關,去調控下游多個關鍵蛋白:

    • 活化 mTOR:促進蛋白質合成與細胞體積變大。

    • 抑制 BAD/Caspase-9:直接關閉細胞凋亡(死亡)的程序,讓細胞「活下去」。

    • 調控 GSK3β:促進糖原合成與能量儲存。

🐟 以鰻魚卵巢發育為例

在魚類卵巢發育過程中,顆粒細胞(Granulosa cells) 與 卵母細胞(Oocyte) 的快速生長高度依賴此通路。

  • 舉例:當促性腺激素(如 FSH)或胰島素樣生長因子(IGF)刺激卵巢時,PI3K-Akt 通路被強烈活化。這會加速顆粒細胞的增殖,並為卵母細胞攝取玻璃質(Vitelogenin,卵黃物質)提供充足的能量與蛋白質合成支持,阻止濾泡過早閉鎖(凋亡)。

2. Ras 訊號通路:細胞的「分裂與分化指揮官」

Ras 通路(特別是 Ras-Raf-MEK-ERK 級聯反應,又稱 MAPK 通路)的核心任務是將細胞外的「分裂訊號」傳遞到細胞核內,直接啟動細胞分裂(Mitosis)與基因轉錄。

🔄 通路運作機制

  1. 活化:一樣由生長因子(如 EGF、FGF)結合受體開始,促使細胞膜上的小 G 蛋白 Ras 從不活化狀態(結合 GDP)轉變成活化狀態(結合 GTP)。

  2. 接力傳遞(激酶級聯反應):活化的 Ras 像推倒骨牌一樣,依序活化 Raf ➔ MEK ➔ ERK(皆為蛋白質激酶)。

  3. 進入細胞核:最後一棒 ERK 被磷酸化後,會直接穿過核膜進入細胞核,活化關鍵的轉錄因子(如 c-Fos, c-Jun, c-Myc),直接下達指令讓細胞開始複製 DNA 並進行細胞分裂。

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
整合單細胞分析管線:
1. 數據 QC 與強制全選預處理
2. NMF 最優 k 值網格搜尋 (Elbow & Cophenetic 穩定度分析)
3. 核心 NMF 潛在因子分解與 12 大細胞類型 Jaccard 映射
4. 下遊次要/隱藏信號 (Masked Housekeeping) KEGG 富集分析
5. 各 Factor Prerank GSEA 與仿 R 語言環狀 CNetPlot 繪製
6. STRING API 蛋白質交互作用網絡 (PPI) 與最大連通元件 Hub 基因挖掘
"""

import os
import gzip
import json
import time
import shutil
import hashlib
import warnings
import tempfile
import urllib.request
from pathlib import Path

import numpy as np
import pandas as pd
import scipy.io as sio
import scipy.cluster.hierarchy as hierarchy
from scipy.spatial.distance import pdist

import scanpy as sc
import matplotlib
import matplotlib.pyplot as plt
import seaborn as sns
import networkx as nx
import gseapy as gp

from sklearn.decomposition import NMF
from sklearn.preprocessing import MinMaxScaler

# 強制使用無 GUI 後端,避免伺服器環境報錯
matplotlib.use("Agg")
warnings.filterwarnings("ignore")

# =============================================================================
# --- 1. 全局配置整合 (CONFIGURATION) ---
# =============================================================================
CONFIG = {
    # 數據路徑 (可透過環境變數覆蓋)
    "sc_data_path": Path(
        os.environ.get(
            "SC_DATA_PATH",
            "/Users/yshuang/Documents/Python/data/ovary_filtered_feature_bc_matrix/",
        )
    ),
    "output_dir": Path(
        os.environ.get(
            "OUTPUT_DIR",
            "/Users/yshuang/Documents/Python/NMF_GSEA_PPI_Report",
        )
    ),

    # QC 模式控制
    "qc_mode": "lenient",
    "lenient": {
        "min_genes_per_cell": 1,      # 最寬鬆:有表達即保留
        "min_cells_per_gene": 1,
        "max_mt_percent": 100.0,      # 不過濾粒線體
        "hvg_min_mean": 0.0125,
        "hvg_max_mean": 3,
        "hvg_min_disp": 0.5,
    },
    "strict": {  
        "min_genes_per_cell": 200,
        "min_cells_per_gene": 3,
        "max_mt_percent": 5.0,
        "hvg_flavor": "seurat_v3",
        "n_top_genes": 2000,
    },

    # 降維與 NMF 設定
    "n_neighbors": 5,
    "n_pcs": 30,
    "nmf_k": 8,                      # 核心 Pipeline 採用的 k 值
    "k_range_evaluation": range(4, 16, 2), # 網格搜尋掃描範圍
    "evaluation_runs": 2,             # 計算穩定度時的隨機初始化次數 (正式運作可設 3-5)

    # 富集分析
    "gene_sets": ["KEGG_2021_Human"],
    "n_top_for_enr": 100,
    "exclude_top_n": 50,
    "top_genes_n": 50,
    "enrichment_pval_cutoff": 0.05,  

    # GSEA 配置
    "gsea_permutation_num": 1000,    
    "gsea_min_size": 15,
    "gsea_max_size": 500,
    "gsea_pval_cutoff": 0.05,
    "gsea_fdr_cutoff": 0.25,

    # PPI 配置
    "ppi_top_n_genes": 40,
    "ppi_score_cutoff": 500,
    "ppi_species_id": 9606,          # 9606 代表人類 (適用於同源基因比對)
    "ppi_max_retries": 3,
    "ppi_retry_delay": 2,            

    # 輸出控制
    "enable_transcript_conversion": True,
    "dpi": 150,
}

# 🧬 日本鰻核心轉錄本映射表
JAPANESE_EEL_TRANSCRIPT_MAP = {
    "ISG15": "AJA11208.p1",
    "AGRN": "AJA02345.p1",
    "TNFRSF18": "AJA09876.p1",
    "TNFRSF4": "AJA05432.p1",
    "FAM132A": "AJA01122.p1",
    "CPSF3L": "AJA03344.p1",
}

# 🌐 擴充版通用特徵基因集 (12大核心細胞類別)
DEFAULT_TISSUE_MARKERS = {
    "Immune_Cell": ["PTPRC", "CD45", "CD3D", "CD3E", "CD14", "LYZ", "CD68", "CSF1R", "CD79A", "MS4A1", "IKZF1"],
    "Epithelial_Cell": ["EPCAM", "KRT8", "KRT18", "KRT5", "KRT14", "CDH1", "CLDN1", "SCNN1A", "MUC1"],
    "Endothelial_Cell": ["PECAM1", "CD31", "VWF", "CD34", "KDR", "FLT1", "ENG", "NOS3", "CDH5"],
    "Stromal_Fibroblast": ["COL1A1", "COL1A2", "COL3A1", "DCN", "VIM", "PDGFRB", "ACTA2", "FAP", "THY1"],
    "Proliferating_Cell": ["MKI67", "TOP2A", "PCNA", "MCM2", "MCM6", "CDK1", "CCNB1", "CENPF", "STMN1"],
    "Neuronal_Cell": ["SYP", "SNAP25", "MAP2", "TUBB3", "NEFL", "RBFOX3", "NEU", "GAP43", "ELAVL4"],
    "Glial_Support_Cell": ["GFAP", "S100B", "SOX9", "SOX10", "MBP", "MPZ", "PLP1", "APOE", "AJA11208.p1"],
    "Smooth_Muscle_Pericyte": ["TAGLN", "MYH11", "MYLK", "RGS5", "VTN", "PDGFRB", "CSPG4", "MCAM"],
    "Osteo_Chondro_Cell": ["RUNX2", "SP7", "BGLAP", "ALPL", "SOX9", "COL2A1", "ACAN", "COMP"],
    "Stem_Progenitor_Cell": ["POU5F1", "OCT4", "NANOG", "SOX2", "MYC", "KLF4", "PROM1", "CD133", "NES"],
    "Erythroid_Cell": ["HBA1", "HBB", "GYPA", "GYPB", "ALAS2", "SLC4A1", "ANK1"],
    "Parenchymal_Metabolic_Cell": ["ALB", "APOA1", "FABP1", "PCK1", "G6PC1", "CYP3A4", "FAH", "TAT"]
}

# =============================================================================
# --- 2. 基礎工具函數 (IO & UTILS) ---
# =============================================================================
def save_plot(output_path, dpi=None, close=True):
    dpi = dpi or CONFIG.get("dpi", 150)
    output_path = Path(output_path)
    output_path.parent.mkdir(parents=True, exist_ok=True)
    plt.savefig(output_path, dpi=dpi, bbox_inches="tight", facecolor="white")
    if close:
        plt.close("all")

def safe_write_dataframe(df, output_path):
    if df is None or df.empty:
        print(f"ℹ️ 數據為空,跳過寫入: {output_path}")
        return
    output_path = Path(output_path)
    output_path.parent.mkdir(parents=True, exist_ok=True)
    df.to_csv(output_path.with_suffix(".csv"), index=False, encoding="utf-8-sig")
    try:
        tmp_path = output_path.parent / f".tmp_{output_path.name}"
        with pd.ExcelWriter(tmp_path, engine="xlsxwriter") as writer:
            sheet_name = "NMF_Report"
            df.to_excel(writer, index=False, sheet_name=sheet_name)
            worksheet = writer.sheets[sheet_name]
            for i, col in enumerate(df.columns):
                max_len = max(df[col].astype(str).map(len).max(), len(str(col))) + 3
                worksheet.set_column(i, i, min(max_len, 50))
        if tmp_path.exists():
            tmp_path.replace(output_path.with_suffix(".xlsx"))
    except Exception as e:
        print(f"⚠️ Excel 寫入失敗,已保留 CSV 備份. 原因: {e}")

def verify_and_prepare_data(target_dir):
    target_dir = Path(target_dir)
    target_dir.mkdir(parents=True, exist_ok=True)
    required = ["matrix.mtx.gz", "features.tsv.gz", "barcodes.tsv.gz"]
    if all((target_dir / f).exists() for f in required):
        return True
    print("💡 未檢測到本地單細胞資料,自動生成模擬資料組...")
    adata = sc.datasets.pbmc3k()
    sio.mmwrite(target_dir / "matrix.mtx", adata.X.T)
    with open(target_dir / "matrix.mtx", "rb") as f_in, gzip.open(target_dir / "matrix.mtx.gz", "wb") as f_out:
        shutil.copyfileobj(f_in, f_out)
    (target_dir / "matrix.mtx").unlink()
    with open(target_dir / "features.tsv", "w") as f:
        for gene in adata.var_names:
            f.write(f"{gene}\t{gene}\tGene Expression\n")
    with open(target_dir / "features.tsv", "rb") as f_in, gzip.open(target_dir / "features.tsv.gz", "wb") as f_out:
        shutil.copyfileobj(f_in, f_out)
    (target_dir / "features.tsv").unlink()
    with open(target_dir / "barcodes.tsv", "w") as f:
        for bc in adata.obs_names:
            f.write(f"{bc}\n")
    with open(target_dir / "barcodes.tsv", "rb") as f_in, gzip.open(target_dir / "barcodes.tsv.gz", "wb") as f_out:
        shutil.copyfileobj(f_in, f_out)
    (target_dir / "barcodes.tsv").unlink()
    return True

# =============================================================================
# --- 3. 轉錄本轉換器 (TRANSCRIPT CONVERTER) ---
# =============================================================================
def generate_transcript_id(gene_name):
    clean_name = str(gene_name).strip()
    upper_name = clean_name.upper()
    if upper_name in JAPANESE_EEL_TRANSCRIPT_MAP:
        return JAPANESE_EEL_TRANSCRIPT_MAP[upper_name]
    hash_digest = hashlib.md5(clean_name.encode("utf-8")).hexdigest()
    unique_num = int(hash_digest, 16) % 90000 + 10000
    return f"AJA{unique_num}.p1"

def expand_gene_weights_to_transcripts(h_gene_df):
    factor_cols = [c for c in h_gene_df.columns if c.startswith("F")]
    rows = []
    for gene_symbol in h_gene_df.index:
        transcript_id = generate_transcript_id(gene_symbol)
        row = {"Transcriptid": transcript_id, "gene_symbol": gene_symbol}
        for col in factor_cols:
            row[col] = h_gene_df.loc[gene_symbol, col]
        rows.append(row)
    df = pd.DataFrame(rows)
    return df[["Transcriptid", "gene_symbol"] + factor_cols]

# =============================================================================
# --- 4. NMF K 值優化評估函數 (OPTIMIZATION) ---
# =============================================================================
def evaluate_nmf_k(adata_sub, k_range=range(4, 16, 2), n_run=2):
    """
    對單細胞矩陣進行多個 k 值的 NMF 評估,繪製 Elbow 曲線與共振穩定度。
    """
    print("\n====== 【優化步驟】進行 NMF 最優 k 值網格搜尋 ======")
    nmf_input = adata_sub.X.toarray() if hasattr(adata_sub.X, "toarray") else adata_sub.X
    nmf_input = np.clip(nmf_input, a_min=0, a_max=None)
    nmf_input_scaled = MinMaxScaler().fit_transform(nmf_input)
    
    # 避免細胞數量過大導致 Cophenetic 階層分群記憶體崩潰 (上限 2000 細胞)
    if nmf_input_scaled.shape[0] > 2000:
        np.random.seed(42)
        indices = np.random.choice(nmf_input_scaled.shape[0], 2000, replace=False)
        nmf_input_eval = nmf_input_scaled[indices, :]
        print(f"ℹ️ 細胞數過多 ({nmf_input_scaled.shape[0]}),下採樣至 2000 用於穩定度計算。")
    else:
        nmf_input_eval = nmf_input_scaled

    results = []
    for k in k_range:
        errors = []
        cophenetic_scores = []
        print(f"  📊 正在評估 k = {k} ... ", end="", flush=True)
        
        for run in range(n_run):
            nmf_model = NMF(n_components=k, init="random", random_state=42 + run, max_iter=500, tol=1e-3)
            W = nmf_model.fit_transform(nmf_input_eval)
            errors.append(nmf_model.reconstruction_err_)
            
            if run == 0:
                # 基於單次 W 矩陣計算 Cophenetic 相關係數
                
                # 基於單次 W 矩陣計算 Cophenetic 相關係數
                z = hierarchy.linkage(W, method='average')
                ciph, _ = hierarchy.cophenet(z, pdist(W))   #  將 cophenetic 改為 cophenet
                cophenetic_scores.append(ciph)

        results.append({
            "k": k,
            "Reconstruction_Error": np.mean(errors),
            "Cophenetic_Stability": np.mean(cophenetic_scores) if cophenetic_scores else 0
        })
        print("完成。")
        
    df_res = pd.DataFrame(results)
    
    # 繪圖輸出
    fig, ax1 = plt.subplots(figsize=(8, 5))
    color = 'tab:red'
    ax1.set_xlabel('Number of Factors (k)', fontweight='bold')
    ax1.set_ylabel('Reconstruction Error', color=color, fontweight='bold')
    ax1.plot(df_res['k'], df_res['Reconstruction_Error'], marker='o', color=color, linewidth=2)
    ax1.tick_params(axis='y', labelcolor=color)
    
    ax2 = ax1.twinx()
    color = 'tab:blue'
    ax2.set_ylabel('Cophenetic Correlation (Stability)', color=color, fontweight='bold')
    ax2.plot(df_res['k'], df_res['Cophenetic_Stability'], marker='s', color=color, linewidth=2, linestyle='--')
    ax2.tick_params(axis='y', labelcolor=color)
    
    plt.title('NMF Optimal k Selection (Elbow & Stability)', fontsize=14, fontweight='bold', pad=15)
    fig.tight_layout()
    save_plot(CONFIG["output_dir"] / "nmf_k_evaluation.png")
    print(f"✅ NMF K值評估指標曲線已儲存至: {CONFIG['output_dir'] / 'nmf_k_evaluation.png'}")
    return df_res

# =============================================================================
# --- 5. CORE FUNCTION 1: SINGLE-CELL NMF & CLUSTERING ---
# =============================================================================
def run_sc_nmf_pipeline(config):
    print("\n====== 【步驟一】單細胞 QC 預處理與 NMF 分群 ======")
    verify_and_prepare_data(config["sc_data_path"])

    adata = sc.read_10x_mtx(config["sc_data_path"], var_names="gene_symbols", cache=False)
    adata.var_names_make_unique()

    adata.var["mt"] = adata.var_names.str.upper().str.startswith("MT-")
    sc.pp.calculate_qc_metrics(adata, qc_vars=["mt"], percent_top=None, log1p=False, inplace=True)

    qc = config[config["qc_mode"]]
    sc.pp.filter_cells(adata, min_genes=qc["min_genes_per_cell"])
    sc.pp.filter_genes(adata, min_cells=qc["min_cells_per_gene"])
    adata = adata[adata.obs["pct_counts_mt"] <= qc["max_mt_percent"], :].copy()

    sc.pp.normalize_total(adata, target_sum=1e4)
    sc.pp.log1p(adata)
    adata.raw = adata
    
    # 強制全選基因模式
    adata.var["highly_variable"] = True
    adata_sub = adata[:, adata.var["highly_variable"]].copy()
    print(f"📊 最終納入計算的基因總數: {adata_sub.shape[1]} 個")

    sc.tl.pca(adata_sub, n_comps=config["n_pcs"], svd_solver="arpack")
    sc.pp.neighbors(adata_sub, n_neighbors=config["n_neighbors"], n_pcs=config["n_pcs"])
    sc.tl.umap(adata_sub)

    # 執行最優 K 值評估
    evaluate_nmf_k(adata_sub, k_range=config["k_range_evaluation"], n_run=config["evaluation_runs"])

    print(f"🚀 正在執行正式 NMF 分解 (K = {config['nmf_k']})...")
    nmf_input = adata_sub.X.toarray() if hasattr(adata_sub.X, "toarray") else adata_sub.X
    nmf_input = np.clip(nmf_input, a_min=0, a_max=None)
    scaler = MinMaxScaler()
    nmf_input_scaled = scaler.fit_transform(nmf_input)

    nmf_model = NMF(n_components=config["nmf_k"], init="nndsvd", random_state=42, max_iter=1000, tol=1e-4)
    W_cell = nmf_model.fit_transform(nmf_input_scaled)
    H_gene = nmf_model.components_

    nmf_labels = np.argmax(W_cell, axis=1)
    adata_sub.obs["nmf_raw"] = pd.Categorical([f"F{l+1}" for l in nmf_labels])

    for i in range(config["nmf_k"]):
        adata_sub.obs[f"F{i+1}"] = W_cell[:, i]

    h_gene_df = pd.DataFrame(H_gene.T, index=adata_sub.var_names, columns=[f"F{i+1}" for i in range(config["nmf_k"])])
    print(f"📈 正式 NMF Reconstruction Error: {nmf_model.reconstruction_err_:.4f}")

    return adata_sub, h_gene_df

# =============================================================================
# --- 6. CORE FUNCTION 2: CELL TYPE MAPPING ---
# =============================================================================
def map_ovary_signatures(adata_nmf, config):
    print("\n====== 【步驟二】卵巢特徵基因集相似度映射 ======")
    cluster_counts = adata_nmf.obs["nmf_raw"].value_counts()
    valid_groups = [grp for grp in cluster_counts.index if cluster_counts[grp] > 1]

    if not valid_groups:
        print("⚠️ 所有 NMF 群組細胞數過少,跳過映射。")
        adata_nmf.obs["ovary_cell_type"] = adata_nmf.obs["nmf_raw"].astype(str)
        return adata_nmf, pd.DataFrame(), pd.DataFrame()

    sc.tl.rank_genes_groups(adata_nmf, "nmf_raw", groups=valid_groups, method="wilcoxon", use_raw=True)

    mapping_results = []
    evidence_rows = []
    cluster_to_celltype = {}

    for grp in valid_groups:
        top_genes = list(adata_nmf.uns["rank_genes_groups"]["names"][grp][:100])
        top_set = set(top_genes)
        best_match, best_jaccard = None, -1

        for cell_type, sig_genes in DEFAULT_TISSUE_MARKERS.items():
            sig_set = set(sig_genes)
            inter = top_set.intersection(sig_set)
            union = top_set.union(sig_set)
            jaccard = len(inter) / len(union) if union else 0

            evidence_rows.append({
                "NMF_Cluster": grp,
                "Ovary_Signature": cell_type,
                "Jaccard_Index": round(jaccard, 4),
                "Overlap_Count": len(inter),
                "Intersection_Genes": ", ".join(sorted(inter)),
            })

            if jaccard > best_jaccard:
                best_jaccard = jaccard
                best_match = cell_type

        cluster_to_celltype[grp] = best_match
        mapping_results.append({
            "NMF_Cluster": grp,
            "Best_Match_CellType": best_match,
            "Jaccard_Index": round(best_jaccard, 4),
        })

    adata_nmf.obs["ovary_cell_type"] = adata_nmf.obs["nmf_raw"].map(cluster_to_celltype).astype("category")
    df_mapping = pd.DataFrame(mapping_results)
    df_evidence = pd.DataFrame(evidence_rows)
    print(df_mapping.to_string(index=False))

    return adata_nmf, df_mapping, df_evidence

# =============================================================================
# --- 7. CORE FUNCTION 3: DOWNSTREAM GSEA & BUBBLE PLOTS ---
# =============================================================================
def get_enrichment(gene_list, tag, config):
    try:
        clean_genes = [str(g).strip().upper() for g in gene_list if pd.notna(g) and str(g).strip()]
        if not clean_genes:
            return pd.DataFrame()
        enr = gp.enrichr(gene_list=clean_genes, gene_sets=config["gene_sets"], organism="human").results
        pval_cutoff = config.get("enrichment_pval_cutoff", 0.05)
        res = enr[enr["Adjusted P-value"] < pval_cutoff].head(10).copy()
        if not res.empty:
            res["Source"] = tag
        return res
    except Exception as e:
        print(f"⚠️ 模組 {tag} 富集分析錯誤: {e}")
        return pd.DataFrame()

def plot_bubble_save(df, title, filename, config):
    if df is None or df.empty:
        print(f"ℹ️ {title} 無顯著通路,跳過繪圖。")
        return
    df = df.copy()
    df["-log10P"] = -np.log10(df["Adjusted P-value"].astype(float) + 1e-10)
    df["Gene_Count"] = df["Overlap"].apply(lambda x: int(str(x).split("/")[0]) if "/" in str(x) else int(x))

    n_terms = df["Term"].nunique()
    fig, ax = plt.subplots(figsize=(12, 2 + n_terms * 0.35))
    scatter = ax.scatter(df["Source"], df["Term"], s=df["Gene_Count"] * 15 + 50, c=df["-log10P"], cmap="viridis", alpha=0.8, edgecolors="0.3", linewidth=0.5)

    ax.set_title(title, fontsize=14, pad=20, fontweight="bold")
    ax.set_xlabel("NMF Module Cluster", fontsize=12)
    ax.set_ylabel("KEGG Pathway", fontsize=12)
    ax.grid(axis="y", linestyle="--", alpha=0.5)

    cbar = plt.colorbar(scatter, ax=ax)
    cbar.set_label("-log10(Adjusted P-value)")

    sizes = [df["Gene_Count"].min(), df["Gene_Count"].median(), df["Gene_Count"].max()]
    size_legend = [plt.scatter([], [], s=s*15+50, c="gray", alpha=0.6, edgecolors="0.3") for s in sizes]
    ax.legend(size_legend, [f"{s}" for s in sizes], title="Gene Count", loc="upper left", bbox_to_anchor=(1.15, 1))

    plt.tight_layout()
    save_plot(config["output_dir"] / filename)
    print(f"✅ 富集氣泡圖已儲存: {config['output_dir'] / filename}")

# =============================================================================
# --- 8. EXTENSION: GSEA FOR EACH FACTOR & VISUALIZATION ---
# =============================================================================
def run_factor_gsea_pipeline(h_gene_df, config):
    print("\n====== 【擴充步驟二】各 Factor 之 GSEA 分析與進階視覺化 ======")
    gsea_out_dir = config["output_dir"] / "GSEA_Factors"
    gsea_out_dir.mkdir(parents=True, exist_ok=True)

    gene_set = config["gene_sets"][0]
    pval_cutoff = config.get("gsea_pval_cutoff", 0.05)
    fdr_cutoff = config.get("gsea_fdr_cutoff", 0.25)

    for factor in h_gene_df.columns:
        print(f"🧬 正在分析 {factor} ...")
        ranked_genes = h_gene_df[factor].sort_values(ascending=False)
        ranked_genes = ranked_genes[ranked_genes > 0]

        if len(ranked_genes) < 15:
            print(f"⚠️ {factor} 有效基因過少,跳過 GSEA。")
            continue

        rnk_df = pd.DataFrame({"gene_name": ranked_genes.index, "score": ranked_genes.values})

        try:
            pre_res = gp.prerank(
                rnk=rnk_df, gene_sets=gene_set, processes=4,
                permutation_num=config.get("gsea_permutation_num", 1000),
                outdir=None, seed=42, verbose=False,
                min_size=config.get("gsea_min_size", 15), max_size=config.get("gsea_max_size", 500)
            )
            res_df = pre_res.res2d
            if res_df is None or res_df.empty:
                continue

            sig_col = "NOM p-val" if "NOM p-val" in res_df.columns else "pval"
            fdr_col = "FDR q-val" if "FDR q-val" in res_df.columns else "fdr"
            significant_res = res_df[(res_df[sig_col] < pval_cutoff) & (res_df[fdr_col] < fdr_cutoff)].sort_values("NES", ascending=False)

            if significant_res.empty:
                print(f"ℹ️ {factor} 未篩選到顯著富集通路。")
                continue

            safe_write_dataframe(significant_res, gsea_out_dir / f"{factor}_gsea_results")

            # Barplot 繪製
            plot_df = significant_res.head(10).copy()
            plt.figure(figsize=(8, 1 + len(plot_df) * 0.4))
            colors = plt.cm.coolwarm_r(np.interp(plot_df[fdr_col], [0, fdr_cutoff], [0, 1]))
            plt.barh(plot_df["Term"], plot_df["NES"], color=colors)
            plt.title(f"{factor} - Top Enriched Pathways (GSEA)", fontsize=13, fontweight="bold")
            plt.xlabel("Normalized Enrichment Score (NES)")
            plt.grid(axis="x", linestyle="--", alpha=0.5)
            plt.gca().invert_yaxis()

            sm = plt.cm.ScalarMappable(cmap="coolwarm_r", norm=plt.Normalize(0, fdr_cutoff))
            sm.set_array([])
            cbar = plt.colorbar(sm, ax=plt.gca(), shrink=0.6)
            cbar.set_label("FDR q-val")
            save_plot(gsea_out_dir / f"{factor}_gsea_barplot.png")

            # CNetPlot 繪製
            plot_chord_cnetplot(plot_df.head(4), factor, gsea_out_dir)
        except Exception as e:
            print(f"⚠️ {factor} GSEA 執行失敗: {e}")

def plot_chord_cnetplot(top_pathways, factor_name, out_dir):
    G = nx.Graph()
    pathway_nodes = []
    gene_nodes = set()

    gene_col = None
    for col in ["lead_genes", "Lead_genes", "matched_genes", "Matched_genes"]:
        if col in top_pathways.columns:
            gene_col = col
            break
    if gene_col is None:
        return

    for _, row in top_pathways.iterrows():
        pathway = row["Term"]
        raw_genes = str(row[gene_col])
        for sep in [";", ","]:
            if sep in raw_genes:
                core_genes = [g.strip() for g in raw_genes.split(sep) if g.strip()]
                break
        else:
            core_genes = [raw_genes.strip()] if raw_genes.strip() else []

        core_genes = core_genes[:8]
        pathway_nodes.append(pathway)
        G.add_node(pathway, node_type="pathway", size=row.get("NES", 1) * 100)

        for gene in core_genes:
            gene_nodes.add(gene)
            G.add_node(gene, node_type="gene", size=30)
            G.add_edge(pathway, gene)

    if not pathway_nodes or not gene_nodes:
        return

    gene_nodes = list(gene_nodes)
    pos = {}
    n_p = len(pathway_nodes)
    for i, p_node in enumerate(pathway_nodes):
        angle = 2 * np.pi * i / n_p
        pos[p_node] = np.array([0.4 * np.cos(angle), 0.4 * np.sin(angle)])

    n_g = len(gene_nodes)
    for i, g_node in enumerate(gene_nodes):
        angle = 2 * np.pi * i / n_g
        pos[g_node] = np.array([1.0 * np.cos(angle), 1.0 * np.sin(angle)])

    fig, ax = plt.subplots(figsize=(10, 10))
    nx.draw_networkx_edges(G, pos, alpha=0.2, edge_color="gray", width=1.2, ax=ax)
    nx.draw_networkx_nodes(G, pos, nodelist=gene_nodes, node_color="skyblue", node_size=150, alpha=0.8, ax=ax)
    p_sizes = [G.nodes[p]["size"] for p in pathway_nodes]
    nx.draw_networkx_nodes(G, pos, nodelist=pathway_nodes, node_color="salmon", node_size=p_sizes, alpha=0.9, ax=ax)

    for g, p_coord in pos.items():
        if g in gene_nodes:
            angle = np.arctan2(p_coord[1], p_coord[0])
            deg = np.degrees(angle)
            rotation = deg if -90 <= deg <= 90 else deg + 180
            ha = "left" if -90 <= deg <= 90 else "right"
            ax.text(p_coord[0]*1.08, p_coord[1]*1.08, s=g, fontsize=8, ha=ha, va="center", rotation=rotation,
                    bbox=dict(facecolor="white", alpha=0.7, edgecolor="none", pad=0.5))

    for p in pathway_nodes:
        p_coord = pos[p]
        ax.text(p_coord[0], p_coord[1] + 0.08, s=p.split("%")[0], fontsize=10, fontweight="bold", ha="center", va="center",
                bbox=dict(facecolor="white", alpha=0.8, edgecolor="none", pad=2))

    ax.set_title(f"Chord-like Gene-Concept Network (CNetPlot) - {factor_name}", fontsize=14, fontweight="bold")
    ax.axis("off")
    save_plot(out_dir / f"{factor_name}_gsea_cnetplot.png")

# =============================================================================
# --- 9. EXTENSION: PPI NETWORK & HUB GENES ANALYSIS (COMPLETED) ---
# =============================================================================
def fetch_string_interactions(gene_list, config):
    """
    透過 STRING API 獲取基因列表的交互作用關係對。
    """
    genes_url = "%0d".join(gene_list)
    url = f"https://string-db.org/api/json/network?identifiers={genes_url}&species={config['ppi_species_id']}"
    
    for attempt in range(config["ppi_max_retries"]):
        try:
            with urllib.request.urlopen(url, timeout=15) as response:
                return json.loads(response.read().decode())
        except Exception as e:
            print(f"⚠️ STRING API 連線失敗 (嘗試 {attempt+1}/{config['ppi_max_retries']}): {e}")
            time.sleep(config["ppi_retry_delay"])
    return None

def run_ppi_hub_pipeline(h_gene_df, config):
    """
    針對每個 Factor 最顯著的 Top 基因建立 PPI 網絡,並篩選 Hub 核心節點。
    """
    print("\n====== 【擴充步驟三】STRING 蛋白質交互作用網絡 (PPI) 與 Hub 基因分析 ======")
    ppi_out_dir = config["output_dir"] / "PPI_Networks"
    ppi_out_dir.mkdir(parents=True, exist_ok=True)
    
    hub_summary = []

    for factor in h_gene_df.columns:
        top_genes = h_gene_df[factor].nlargest(config["ppi_top_n_genes"]).index.tolist()
        print(f"🌐 正在請求 {factor} 的 STRING 網絡數據...")
        
        network_data = fetch_string_interactions(top_genes, config)
        if not network_data:
            print(f"ℹ️ {factor} 未能取得 PPI 交互作用數據。")
            continue
            
        G = nx.Graph()
        for edge in network_data:
            score = edge.get("score", 0) * 1000  # 標準化分數
            if score >= config["ppi_score_cutoff"]:
                G.add_edge(edge["preferredName_A"], edge["preferredName_B"], weight=score)
                
        if G.number_of_nodes() == 0:
            print(f"ℹ️ {factor} 在當前 score_cutoff 下無顯著交互作用邊。")
            continue
            
        # 計算網路拓樸指標:度中心性 (Degree Centrality)
        dc = nx.degree_centrality(G)
        sorted_hubs = sorted(dc.items(), key=lambda x: x[1], reverse=True)
        top_hubs = [node for node, val in sorted_hubs[:5]]
        
        # 紀錄報告
        for node, score in sorted_hubs:
            hub_summary.append({
                "Factor": factor, "Gene": node, "Degree_Centrality": round(score, 4), "Connections": G.degree(node)
            })
            
        # 繪圖展示 (最大連通元件)
        largest_cc = max(nx.connected_components(G), key=len)
        subG = G.subgraph(largest_cc)
        
        plt.figure(figsize=(8, 8))
        pos = nx.spring_layout(subG, k=0.4, seed=42)
        
        # 節點大小與度中心性連動
        node_sizes = [dc[node] * 1000 + 100 for node in subG.nodes()]
        node_colors = ["red" if node in top_hubs else "orange" for node in subG.nodes()]
        
        nx.draw_networkx_edges(subG, pos, alpha=0.3, edge_color="gray")
        nx.draw_networkx_nodes(subG, pos, node_size=node_sizes, node_color=node_colors, alpha=0.8)
        nx.draw_networkx_labels(subG, pos, font_size=9, font_weight="bold")
        
        plt.title(f"PPI Network Maximum Component - {factor}\n(Red nodes indicate top hubs)", fontsize=12, fontweight="bold")
        plt.axis("off")
        save_plot(ppi_out_dir / f"{factor}_ppi_network.png")
        print(f"   ✅ PPI 網絡圖與 Hub 基因已儲存")
        
    if hub_summary:
        safe_write_dataframe(pd.DataFrame(hub_summary), config["output_dir"] / "ppi_hub_centrality_report")

# =============================================================================
# --- 10. MAIN EXECUTION ---
# =============================================================================
def main():
    CONFIG["output_dir"].mkdir(parents=True, exist_ok=True)

    # 1. 主 NMF 矩陣分解與分群評估
    adata_nmf, h_gene_df = run_sc_nmf_pipeline(CONFIG)

    # 2. 細胞特徵基因集映射
    adata_mapped, df_mapping, df_evidence = map_ovary_signatures(adata_nmf, CONFIG)

    # 3. 下游 KEGG 富集分析
    print("\n====== 【步驟三】下游基因功能富集分析管線 ======")
    main_list = []
    for col in h_gene_df.columns:
        genes = h_gene_df[col].nlargest(CONFIG["n_top_for_enr"]).index.tolist()
        enr = get_enrichment(genes, col, CONFIG)
        if not enr.empty:
            main_list.append(enr)
    df_main = pd.concat(main_list, ignore_index=True) if main_list else pd.DataFrame()

    print("🎭 正在排除全域 Housekeeping 基因,挖掘次要信號...")
    global_w = h_gene_df.sum(axis=1)
    actual_exclude_n = min(CONFIG["exclude_top_n"], len(h_gene_df) - 10)
    h_masked = h_gene_df.drop(index=global_w.nlargest(actual_exclude_n).index) if actual_exclude_n > 0 else h_gene_df.copy()

    minor_list = []
    for col in h_masked.columns:
        genes = h_masked[col].nlargest(CONFIG["top_genes_n"]).index.tolist()
        enr = get_enrichment(genes, f"{col}_Minor", CONFIG)
        if not enr.empty:
            minor_list.append(enr)
    df_minor = pd.concat(minor_list, ignore_index=True) if minor_list else pd.DataFrame()

    # 4. 儲存標準報表數據
    print("\n====== 【步驟四】儲存分析報告與圖表 ======")
    df_cells = pd.DataFrame(index=adata_mapped.obs_names)
    df_cells["ovary_cell_type"] = adata_mapped.obs["ovary_cell_type"]
    df_cells["nmf_raw"] = adata_mapped.obs["nmf_raw"]
    for i in range(CONFIG["nmf_k"]):
        col = f"F{i+1}"
        df_cells[col] = adata_mapped.obs.get(col, 0.0)
    df_cells = df_cells.reset_index().rename(columns={"index": "Cell_ID"})
    safe_write_dataframe(df_cells, CONFIG["output_dir"] / "cell_nmf_scores")

    if CONFIG.get("enable_transcript_conversion", False):
        safe_write_dataframe(expand_gene_weights_to_transcripts(h_gene_df), CONFIG["output_dir"] / "gene_nmf_weights")
    else:
        safe_write_dataframe(h_gene_df.reset_index().rename(columns={"index": "Gene_Symbol"}), CONFIG["output_dir"] / "gene_nmf_weights")

    safe_write_dataframe(df_mapping, CONFIG["output_dir"] / "ovary_mapping")
    safe_write_dataframe(df_evidence, CONFIG["output_dir"] / "ovary_mapping_evidence")
    if not df_main.empty: safe_write_dataframe(df_main, CONFIG["output_dir"] / "main_kegg_enrichment")
    if not df_minor.empty: safe_write_dataframe(df_minor, CONFIG["output_dir"] / "minor_kegg_enrichment")

    # 5. UMAP 降維視覺化
    if "ovary_cell_type" in adata_mapped.obs.columns:
        sc.pl.umap(adata_mapped, color=["ovary_cell_type"], palette="Set2", show=False)
        save_plot(CONFIG["output_dir"] / "umap_ovary_annotated.png")

    plot_bubble_save(df_main, "Main Pathway Enrichment", "bubble_main_kegg.png", CONFIG)
    plot_bubble_save(df_minor, "Hidden Signal Enrichment", "bubble_minor_kegg.png", CONFIG)

    # 6. 觸發擴充進階管線 (GSEA 與 PPI)
    run_factor_gsea_pipeline(h_gene_df, CONFIG)
    run_ppi_hub_pipeline(h_gene_df, CONFIG)

    print("\n🎉 【整合與優化成功】所有主管線與擴充進階分析皆已順利執行完畢!")
    return adata_mapped, h_gene_df, df_main, df_minor

if __name__ == "__main__":
    main()

Monday, June 22, 2026

鰻魚「完全養殖」的未竟之業

 

專家之眼】鰻魚「完全養殖」的未竟之業

台北市長蔣萬安(右)與立委張嘉郡(左)前往雲林縣口湖鰻魚養殖池體驗抓鰻魚。記者黃仲裕/攝影
台北市長蔣萬安(右)與立委張嘉郡(左)前往雲林縣口湖鰻魚養殖池體驗抓鰻魚。記者黃仲裕/攝影

日本鰻因其營養和經濟價值而備受重視,也是亞洲重要的養殖魚種,產業規模達近百億美元。目前養殖日本鰻所需的種苗全靠天然採捕然,但受到氣候、水溫、濫捕、海域汙染、洋流變化等影響,全球鰻苗資源大幅衰退,現在數量只剩1960年代的一成,已經影響到養鰻產業正常發展。

去年底歐盟於「瀕臨絕種野生動植物國際貿易公約」(CITES)締約國大會上,提案將全球十九種鰻魚全數列入限制貿易的「附錄二」名單中,禁止捕撈跟販售,因茲事體大,遭日本等亞洲國家反對,該管制提案最終未獲通過。不過大會也通過加強對所有鰻魚的保護、管理和監測並打擊非法販運鰻苗的決議,全球鰻魚苗貿易管制將更趨嚴格。

想要克服野生鰻苗不足問題,可以嘗試了強化產卵場保護;避免天然鰻苗過度捕撈;實施人工養成種鰻放流等,但方法效果皆有限,最有效的做法還是放在實現日本鰻苗人工繁殖商業化量產。

經過多年努力,日本學術機構前已順利完成日本鰻的「完全養殖」,在人工控制環境下,從種魚交配、產卵、孵化培育魚苗,養至成魚,並讓成魚再度繁衍出下一代,完成完整生命週期。近日日本媒體更報導,該國完全養殖養成的鰻魚,已上市販售,成為全球首次商業化上市的人工完全養殖鰻魚。

雖然人工繁殖鰻苗售價(每尾1800日圓),較野生鰻苗貴(每尾約600日圓),且數量仍然有限,但是在幼期餌料和成長環境調控等關鍵技術,已經有所掌握下,商業化量產人工鰻苗生產應是指日可待,不僅可以挽救因天然野生鰻苗數量銳減而逐漸衰退的養鰻產業,也會改變原有養鰻國家的競爭態勢。

筆者曾用DRC(Domestic Resource Cost)評估鰻魚人工繁殖技術(鰻苗成本佔總成本五成以上)對養鰻國家競爭力影響發現,誰優先取得該項技術並達到量產,將可大幅取得競爭優勢,顯然日本已居領先地位。

主要競爭國之一的中國大陸,將鰻苗繁育列入國家計劃,日前也報導該國學術機構經多年努力,成功培育出人工鰻苗,已健康存活33天,到達柳葉鰻前期幼體。若一切順利再經數個月,即可發育成可供人工養殖的玻璃鰻苗。

而台灣自七十年代初即致力於鰻魚人工繁殖研究,水產試驗所鹿港分所更是研發主力,可惜經過近半世紀的努力,始終未能突破日本鰻完全養殖技術瓶頸,也無創新技術突破,台灣養鰻規模亦逐漸萎縮,不再是日本鰻魚消費市場的主要供應者。

日前媒體報導國內民間生技公司經過多年研發,宣稱成功育成臺灣第一尾人工鰻苗,並已養成至成鰻,將作為種鰻用,但能否確立鰻魚「完全養殖」,還需要留待時間驗證。

筆者長期關注鰻魚動態,有幸見證台灣養鰻產業的榮景,尤其對平衡台日貿易逆差做出的貢獻,也參與了產官學齊心協力打開日本鰻魚市場的艱辛歲月,更看到科研前輩們為實現鰻魚人工繁殖所付出的心血和努力,始終相信「鰻魚完全養殖」會成為另一個台灣之光,只是多年等來的卻是由日本搶先完成。

在惋惜之餘,有感於一旦實現商業化量產,養鰻產業將呈現新的格局,而台灣鰻魚科研根基尚在,呼籲政府應重整旗鼓,給予水產試驗暨學術研究機構更多支持並積極協調整合相關研究人力、物力和技術(特別是民間的研究資源),運用先進科研技術,確立人工繁殖的關鍵調控機制,早日完成日本鰻魚苗商業化量產的未竟之業,讓台灣養鰻產業再造輝煌。

Thursday, June 11, 2026

蝦子的愛情是盲目!

科學教育發展中心影音編輯。

近日國家海洋研究院來函,希望取得老師2018年講座影片之授權使用,影片:【蝦子的愛情是盲目!?談水生動物的生殖生理】│科學史沙龍

由於當時簽署之影音授權同意書未包含再授權第三方使用之相關條款,因此需另行取得老師的同意,並重新簽署新版授權文件。

想請教老師:
  1. 新版授權同意書需郵寄,還請老師提供收件地址。
  2. 是否同意將上述講座影片授權國家海洋研究院使用?
若老師同意授權,我將儘速辦理後續文件作業。
感謝老師撥冗閱讀,期待您的回覆。
敬祝 平安健康


2026/6/11

﹉﹉ ﹉﹉ ﹉﹉ ﹉﹉ ﹉﹉ ﹉﹉ ﹉﹉ ﹉﹉ ﹉﹉ ﹉﹉ ﹉﹉ ﹉
CASE 臺大科學教育發展中心 
影音編輯
Tel : (02)3366oxox
106216 臺北市羅斯福路四段一號 理學院思亮館國際會議廳

Tuesday, June 02, 2026

貝氏層次模型(Bayesian Hierarchical Model, BHM)與 高維度數據(如轉錄組學、空間統計)

貝氏層次模型(Bayesian Hierarchical Model, BHM)的發展歷史,是一段從「統計學界的邊緣理論」走向「現代數據科學與生物資訊核心」的逆襲史。它的誕生與普及,緊密伴隨著計算機算力的革命以及高維度數據(如轉錄組學、空間統計)的爆發。

以下為您梳理貝氏層次模型的發展軌跡與現代多元的應用範疇:

⏳ 貝氏層次模型的發展歷史

貝氏層次模型的演進可以大致分為四個里程碑階段:

1. 奠基期:詹姆斯-斯坦估計與收縮理論(1950 - 1960年代)

雖然托馬斯·貝氏(Thomas Bayes)在 18 世紀就提出了貝氏定理,但「層次模型」的統計學基礎直到 20 世紀中葉才出現。

  • 關鍵突破:1961 年,統計學家查爾斯·斯坦(Charles Stein)與威拉德·詹姆斯(Willard James)提出了一個震驚統計學界的定理(詹姆斯-斯坦悖論)。他們證明:在估計三個或更多獨立的常態分佈均值時,將所有獨立樣本向全局平均值「收縮(Shrinkage)」後得到的估計值,其總體誤差必定小於傳統的最大概似估計(MLE)。

  • 歷史意義:這顛覆了「各人自掃門前雪(獨立估計)」的傳統觀念,為層次模型中「訊息共享」的核心思想奠定了數學正當性。

2. 理論成型期:貝氏架構的全面引入(1970 - 1980年代)

隨後,統計學家發現詹姆斯-斯坦估計可以用貝氏機率的框架給予完美的解釋。

  • 關鍵突破:1970 年代,布萊德利·艾弗隆(Bradley Efron,Bootstrap 的發明者)與卡爾·莫里斯(Carl Morris)發表了一系列論文,正式將收縮理論與貝氏事前分佈結合,展示了如何用「超參數(Hyperparameters)」來建構多層次的統計結構。

  • 歷史意義:此時,層次模型(Hierarchical Model)與經驗貝氏(Empirical Bayes)的理論框架正式成型,統計學家開始意識到這種結構在處理群聚數據(Clustered data)時的巨大潛力。

3. 計算革命期:MCMC 演算法與 BUGS 的誕生(1990年代)

儘管 80 年代框架已成,但當時的貝氏層次模型面臨一個致命瓶頸:無法計算後驗分佈。高維度的多層積分在數學上沒有解析解,使得模型只能停留在理論階段。

  • 計算機革命:1990 年,艾倫·蓋爾芬德(Alan Gelfand)和阿德里安·史密斯(Adrian Smith)將馬可夫鏈蒙地卡羅法(MCMC,特別是吉布斯採樣 Gibbs Sampling)引入貝氏統計,將複雜的高維積分問題轉化為計算機隨機抽樣。

  • 軟體普及:隨後,BUGS(Bayesian inference Using Gibbs Sampling)軟體專案啟動,科學家終於有了工程工具可以真正「執行」貝氏層次模型。BHM 自此進入實用化爆炸期。

4. 現代爆發期:高維數據與機率程式語言(2000年代至今)

進入 21 世紀,隨著基因體學、大數據與人工智慧的興起,數據特徵數(如幾萬個基因)遠大於樣本數的現象成為常態。

  • 現代技術:傳統的吉布斯採樣在高維空間容易卡頓,科學家開發了基於哈密頓力學的 HMC(Hamiltonian Monte Carlo) 與 NUTS(No-U-Turn Sampler) 演算法。

  • 生態圈:這催生了新一代的機率程式語言(PPL),如您代碼中使用的 PyMC,以及 Stan、Pyro。現在,科學家只需要幾行代碼,就能在幾分鐘內完成過去需要幾天才能算完的高維貝氏層次推論。

🌍 貝氏層次模型的現代應用領域

由於 BHM 擅長處理「數據具有層級結構(如:細胞內有基因、學校內有學生、區域內有個體)」以及「小樣本、高雜訊」的問題,它在現代科學中得到了極其廣泛的應用:

1. 生物資訊學與基因體學(Bioinformatics)

正如您目前執行的轉錄組學分析,BHM 是多體學(Multi-omics)數據分析的黃金標準之一。

  • 差異表達分析(Differential Expression):在小樣本(如 $n=3$)下,利用全局基因背景約束個體變異數。經典工具如 limma、DESeq2 的核心數學原理,本質上都是經驗貝氏層次模型(Empirical Bayes)。

  • 單細胞 RNA 測序(scRNA-seq):單細胞數據具有極高比例的「零值雜訊(Dropout)」,BHM 可以透過細胞群體與基因群體的雙重層次,對缺失值進行穩健的填補(Imputation)與降噪。

2. 流行病學與空間疾病地圖(Epidemiology & Spatial Mapping)

在公共衛生領域,科學家需要評估不同行政區的疾病發病率。

  • 小區域估計(Small Area Estimation):某些偏遠小鎮人口極少,只要出現 1 個癌症病例,表面上的發病率就會飆高。

  • 解法:流行病學常用 BYM 模型(Besag-York-Mollié,一種空間貝氏層次模型),讓小鎮的發病率向「全縣平均(全局)」以及「鄰近鄉鎮(空間相關)」進行收縮。這能有效剃除因人口過少產生的統計雜訊,繪製出真正精準的疾病風險地圖。

3. 生態學與環境科學(Ecology)

生態學的野生動物調查往往面臨極端惡劣的觀測條件。

  • 動植物種群動態:科學家在野外架設紅外線相機捕捉動物,觀測數據受到天氣、地形、相機故障等重重干擾。

  • 解法:透過層次模型,第一層建模「動物真實存在的空間分佈(狀態)」,第二層建模「相機捕捉到動物的捕獲機率(觀測雜訊)」。BHM 能夠成功將「生物真實狀態」從「環境干擾雜訊」中剝離出來。

4. 臨床試驗與統合分析(Meta-Analysis)

在醫學藥物開發中,科學家需要綜合評估全球數十個不同中心、不同樣本量發表的臨床報告。

  • 統合分析:每個臨床試驗(Study)都有其特異性(如不同國家、不同年齡層)。

  • 解法:BHM 將每個試驗視為第二層個體,全球總效果視為第一層超事前分佈。它能完美評估「研究間的異質性(Heterogeneity)」,即使某些小規模試驗流於偏差,模型也能給予合理的權重收縮,給出最客觀的藥效評估。

5. 金融、行銷與商業決策

在商業零售中,企業需要預測成千上萬種商品的未來銷量,或是評估不同地區廣告的投放效果。

  • 多層次行銷模型(Hierarchical MMM):將消費者依據「城市」、「年齡層」分層,利用 BHM 既能學到全國消費者的共同行為趨勢(超參數),又能捕捉到特定城市(如台北 vs 高雄)的特異性偏好。這在數據稀疏的細分市場預測中表現極其優異。

📝 歷史與應用的總結

從詹姆斯-斯坦悖論引發的觀念革命,到 MCMC 演算法引爆的計算革命,貝氏層次模型之所以能在當代各大領域成為大宗,是因為它承載了人類對數據認知的轉變:我們不再孤立地看待每一個觀測對象,而是將其納入系統性的全局網絡中。 這種「和而不同、資訊共享」的哲學,使其成為當今應對複雜、高雜訊、小樣本數據最精密的統計武器。

#!/usr/bin/env python3

# -*- coding: utf-8 -*-

"""

Created on Wed Jun  3 09:15:55 2026


核心建立在貝氏層次模型(Bayesian Hierarchical Model)之上,用來處理生物統計學中典型「小樣本、

高維度(高基因數)」的轉錄組特徵選取(Feature Selection)挑戰。


使用貝氏機率理論(Bayesian Inference)進行特徵選取(Feature Selection)是最佳策略。


透過貝氏方法,我們可以利用收縮估計(Shrinkage Estimation)或層次模型(Hierarchical Models)

共享基因間的變異數資訊,從而做出穩健的推論。


執行上述程式後,你會得到一個統計表格,篩選邏輯如下:

1. 核心指標:後驗機率(Posterior Probability)Prob_UP (AT>MT):代表處理後基因表現量確實

上升的客觀機率。如果該值為 0.97,代表有 97% 的把握該基因在處理後被活化。Prob_DOWN (AT<MT):

代表處理後表現量下降的機率。

2. 效果量(Bayesian Effect Size)由於樣本數只有 3 組,有時候雖然平均差值大,但可能只是單一

鰻魚的極端值(離群值)。Bayesian_Effect_Size 納入了變異度($\mu / \sigma$)。數值絕對值

越大(例如 $> 1.5$ 或 $< -1.5$),代表該基因的表達量變化相對於其波動而言非常顯著,發育程度的

差異與該基因高度相關。

3. 如何結合「卵巢發育程度的差異」?如果你有進一步紀錄這三隻鰻魚處理後的卵巢發育成熟度分數(例如:

Fish 1 熟度 80%, Fish 2 熟度 50%, Fish 3 熟度 20%),你可以將模型升級為貝氏線性迴歸模型:

透過檢定斜率 beta_1 的後驗分佈是否遠離 0,就能精準篩選出「其表達量變化與卵巢發育程度呈正/負相關」

的核心關鍵基因。



程式碼在執行時遇到了轉錄組高維度數據分析最常見的兩個嚴重瓶頸:嚴重的發散收斂問題(Divergences)

與 $\hat{R} > 1.01$: 因為每組基因只有 3 個成對樣本(樣本數極少),當你對每個基因「獨立」建

立貝氏模型時,模型很難單憑 3 個點準確估計出該基因的變異度 sigma。這在貝氏統計中被稱為「漏斗效應

(Neal's Funnel)」,會導致 MCMC 採樣器瘋狂報錯、結果不可信。效率極低(維度災難): 你的轉錄

組矩陣包含 21,651 個基因。如果用 for gene in genes: 迴圈一個一個跑 pm.sample(),跑完兩萬

多個基因可能需要耗費幾十個小時甚至好幾天。💡 完美的解決方案:貝氏層次模型(Bayesian 

Hierarchical Model)我們應該利用貝氏的核心優勢——層次模型(Hierarchical Modeling),將所

有基因放進同一個模型中進行矩陣化(Vectorized)平行運算。透過讓所有基因共享同一個上位的事前分佈

(Hyper-priors),模型會自動進行「收縮估計(Shrinkage Estimation)」。白話來說,就是讓表達

量穩定的基因去「幫助」變異大的基因修正其變異數。如此一來:徹底解決少樣本導致的發散(Divergences)

問題。速度提升數千倍(20,000+ 基因可在幾分鐘內透過矩陣運算一次採樣完成)。



@author: yshuang

import numpy as np

import pandas as pd

import pymc as pm

import arviz as az

import time

from pathlib import Path

from typing import Tuple, Optional

import warnings


# ============================================================

# 配置區塊(集中管理所有路徑與參數)

# ============================================================

class Config:

    """集中管理所有配置參數,避免硬編碼分散在代碼中"""

    # 路徑配置

    INPUT_FILE = Path("/Users/yshuang/Documents/Python/FC_GSEA.xlsx")

    OUTPUT_DIR = Path("/Users/yshuang/Documents/Python")

    OUTPUT_CSV = OUTPUT_DIR / "Bayesian_Phenotype_Selection_Results.csv"

    OUTPUT_RNK = OUTPUT_DIR / "Eel_Ovary_AT_vs_MT_Phenotype_Bayesian.rnk"


    # 數據配置

    SHEET_NAME = "data (TPM)"

    USE_COLS = "A, E:J"

    N_SAMPLES_PER_GROUP = 3  # 每組樣本數


    # 💡【外表型差型定量變數】

    # 根據 1440 > 2613 >> 2003 邏輯賦予發育推進權重 (AT - MT 的表型變化量)

    # 這裡的 Key 必須與您的 Excel 樣本名稱中的個體編號完全對應

    PHENOTYPE_DELTA_MAP = {

        "1440": 3.0,   # 強

        "2613": 2.0,   # 中

        "2003": 0.5    # 弱

    }


    # MCMC 配置

    DRAWS = 1000

    TUNE = 1000

    CHAINS = 2

    TARGET_ACCEPT = 0.95

    RANDOM_SEED = 42


    # 特徵選取門檻 (改看斜率為正/負的後驗機率)

    PROB_THRESHOLD = 0.95

    TOP_N_DISPLAY = 10



def load_and_preprocess_data(config: Config) -> Tuple[pd.DataFrame, pd.DataFrame, pd.DataFrame, np.ndarray, np.ndarray, list]:

    """

    讀取轉錄組數據,並提取與個體嚴格對齊的外表型差值變數

    """

    if not config.INPUT_FILE.exists():

        raise FileNotFoundError(f"❌ 輸入檔案不存在: {config.INPUT_FILE}")


    print(f"📂 讀取數據: {config.INPUT_FILE}")


    df = pd.read_excel(

        config.INPUT_FILE,

        sheet_name=config.SHEET_NAME,

        index_col=0,

        usecols=config.USE_COLS

    )

    df.columns = df.columns.str.strip()


    if df.shape[1] == config.N_SAMPLES_PER_GROUP * 2:

        Y_raw = df.T.astype(float)

    else:

        Y_raw = df.astype(float)


    print(f"✅ 基因矩陣載入完成: {Y_raw.shape[0]} 樣本 × {Y_raw.shape[1]} 基因")


    Y_asinh = np.arcsinh(Y_raw)


    mt_samples = sorted([col for col in Y_asinh.index if 'MT' in col.upper()])

    at_samples = sorted([col for col in Y_asinh.index if 'AT' in col.upper()])


    if len(mt_samples) != len(at_samples) or len(mt_samples) == 0:

        raise ValueError("❌ 樣本配對失敗,請檢查 MT 與 AT 命名。")


    print(f"📊 已成功配對樣本: 對照組 {mt_samples} ↔️ 處理組 {at_samples}")


    # 計算成對差值

    data_mt = Y_asinh.loc[mt_samples].values

    data_at = Y_asinh.loc[at_samples].values

    diff_matrix = data_at - data_mt

    X_data = diff_matrix.T  # (n_genes, n_samples)

    genes = Y_raw.columns.tolist()


    # 💡【核心新增】:動態解析樣本名稱,並匹配外表型定量值

    phenotype_list = []

    for sample_name in mt_samples:

        matched = False

        for key, val in config.PHENOTYPE_DELTA_MAP.items():

            if key in sample_name:

                phenotype_list.append(val)

                matched = True

                break

        if not matched:

            raise ValueError(f"❌ 樣本 {sample_name} 無法匹配到任何外表型設定,請檢查 Config.PHENOTYPE_DELTA_MAP")

    

    X_phenotype = np.array(phenotype_list)

    print(f"📈 樣本對齊的外表型推進值 (ΔPhenotype): {dict(zip(mt_samples, X_phenotype))}")


    diff_df = pd.DataFrame(diff_matrix, index=mt_samples, columns=genes)


    return Y_raw, Y_asinh, diff_df, X_data, X_phenotype, genes



def build_bayesian_regression_model(X_data: np.ndarray, X_phenotype: np.ndarray, config: Config) -> az.InferenceData:

    """

    建立並執行貝氏層次線性迴歸模型

    使得基因表達量差值 (Y) 與外表型推進值 (X) 進行耦合

    """

    n_genes, n_samples = X_data.shape


    print(f"🚀 啟動貝氏層次迴歸 MCMC 採樣...")

    start_time = time.time()


    with pm.Model() as hierarchical_regression_model:

        # --- 1. 迴歸截距 (Intercept) 層次分佈 ---

        alpha_global = pm.Normal("alpha_global", mu=0, sigma=2)

        sigma_alpha = pm.HalfNormal("sigma_alpha", sigma=2)

        alpha_offset = pm.Normal("alpha_offset", mu=0, sigma=1, shape=n_genes)

        alpha_genes = pm.Deterministic("alpha_genes", alpha_global + alpha_offset * sigma_alpha)


        # --- 2. 迴歸斜率 (Slope, 對外表型的敏感度) 層次分佈 ---

        # beta_global 代表全轉錄組受到該外表型驅動的平均斜率趨勢

        beta_global = pm.Normal("beta_global", mu=0, sigma=2)

        sigma_beta = pm.HalfNormal("sigma_beta", sigma=2)

        beta_offset = pm.Normal("beta_offset", mu=0, sigma=1, shape=n_genes)

        

        # beta_genes 代表每個基因各自對外表型發育強弱的「響應斜率」

        beta_genes = pm.Deterministic("beta_genes", beta_global + beta_offset * sigma_beta)


        # --- 3. 群體共享的殘差變異度 ---

        sigma_noise = pm.HalfNormal("sigma_noise", sigma=2)


        # --- 4. 線性模型方程式: μ = 基礎差值 + 斜率 * 外表型變化量 ---

        mu_predicted = alpha_genes[:, None] + beta_genes[:, None] * X_phenotype[None, :]


        # 似然函數

        likelihood = pm.Normal(

            "y_obs",

            mu=mu_predicted,

            sigma=sigma_noise,

            observed=X_data

        )


        # 執行採樣

        trace = pm.sample(

            draws=config.DRAWS,

            tune=config.TUNE,

            chains=config.CHAINS,

            target_accept=config.TARGET_ACCEPT,

            return_inferencedata=True,

            random_seed=config.RANDOM_SEED,

            progressbar=True

        )


    elapsed = time.time() - start_time

    print(f"🎉 MCMC 完成!耗時: {elapsed:.1f} 秒")


    return trace



def extract_posterior_statistics(

    trace: az.InferenceData,

    X_data: np.ndarray,

    genes: list,

    config: Config

) -> pd.DataFrame:

    """從迴歸模型的後驗分佈提取指標(改以斜率 Beta 為核心)"""

    print("📊 計算外表型相關後驗統計量...")


    # 提取響應外表型的斜率後驗樣本 (n_genes, n_draws)

    beta_samples = az.extract(trace, var_names="beta_genes").values

    alpha_samples = az.extract(trace, var_names="alpha_genes").values

    sigma_noise_samples = az.extract(trace, var_names="sigma_noise").values


    # 計算統計量

    mean_diff = X_data.mean(axis=1)

    post_beta_mean = beta_samples.mean(axis=1)

    post_alpha_mean = alpha_samples.mean(axis=1)


    # 💡 計算該基因與「外表型推進」呈正相關或負相關的後驗機率

    prob_up = np.mean(beta_samples > 0, axis=1)

    prob_down = np.mean(beta_samples < 0, axis=1)


    # 貝氏效果量:以斜率(信噪比)作為核心

    sigma_broadcast = np.tile(sigma_noise_samples, (len(genes), 1))

    epsilon = 1e-10

    effect_size = np.mean(beta_samples / (sigma_broadcast + epsilon), axis=1)


    df_results = pd.DataFrame({

        "Raw_Mean_Diff": mean_diff,

        "Bayesian_Intercept(Alpha)": post_alpha_mean,

        "Bayesian_Slope(Beta)": post_beta_mean,

        "Prob_Phenotype_Pos(Beta>0)": prob_up,

        "Prob_Phenotype_Neg(Beta<0)": prob_down,

        "Bayesian_Effect_Size": effect_size

    }, index=genes)


    # 特徵選取:斜率方向信心大於門檻者

    df_results["Selected"] = (

        (df_results["Prob_Phenotype_Pos(Beta>0)"] > config.PROB_THRESHOLD) |

        (df_results["Prob_Phenotype_Neg(Beta<0)"] > config.PROB_THRESHOLD)

    )


    # 按表型驅動效果量絕對值排序

    df_results = df_results.sort_values(

        by="Bayesian_Effect_Size",

        key=lambda x: np.abs(x),

        ascending=False

    )


    print(f"\n--- 前 {config.TOP_N_DISPLAY} 個強烈受外表型驅動基因 ---")

    print(df_results.head(config.TOP_N_DISPLAY).to_string())


    n_selected = df_results["Selected"].sum()

    print(f"\n📈 特徵選取摘要: {n_selected}/{len(genes)} 基因與外表型發育軌跡強烈耦合 (門檻 {config.PROB_THRESHOLD*100:.0f}%)")


    return df_results



def export_gsea_ranklist(df_results: pd.DataFrame, config: Config) -> None:

    """匯出基於外表型迴歸斜率排序的 GSEA .rnk 檔案"""

    print("\n🚚 生成外表型驅動型 GSEA Rank List...")

    config.OUTPUT_DIR.mkdir(parents=True, exist_ok=True)


    df_gsea = df_results[["Bayesian_Effect_Size"]].copy().dropna()

    if df_gsea.index.duplicated().any():

        df_gsea = df_gsea[~df_gsea.index.duplicated(keep="first")]


    df_gsea = df_gsea.reset_index()

    df_gsea.columns = ["Gene", "Score"]

    df_gsea = df_gsea.sort_values(by="Score", ascending=False).reset_index(drop=True)


    df_gsea.to_csv(config.OUTPUT_RNK, sep="\t", header=False, index=False)

    print(f"✅ GSEA .rnk 匯出成功: {config.OUTPUT_RNK}")



def run_diagnostics(trace: az.InferenceData) -> None:

    """收斂診斷"""

    print("\n🔍 收斂診斷...")

    summary = az.summary(trace, var_names=["alpha_global", "beta_global", "sigma_noise"])

    print("\n--- 全局超參數迴歸收斂摘要 ---")

    print(summary[["mean", "sd", "r_hat"]].to_string())



def main():

    config = Config()

    try:

        # 1. 數據載入與預處理 (包含外表型對齊)

        Y_raw, Y_asinh, diff_df, X_data, X_phenotype, genes = load_and_preprocess_data(config)


        # 2. 建立貝氏層次迴歸模型

        trace = build_bayesian_regression_model(X_data, X_phenotype, config)


        # 3. 收斂診斷

        run_diagnostics(trace)


        # 4. 提取迴歸統計量

        df_results = extract_posterior_statistics(trace, X_data, genes, config)


        # 5. 匯出完整結果

        df_results.to_csv(config.OUTPUT_CSV)

        print(f"\n💾 迴歸分析結果已儲存: {config.OUTPUT_CSV}")


        # 6. 匯出 GSEA 檔案

        export_gsea_ranklist(df_results, config)

        print("\n🎊 外表型耦合分析全數完成!")


    except Exception as e:

        print(f"\n❌ 執行錯誤: {e}")

        raise



if __name__ == "__main__":

    main()