usher-exploring/README.md

Usher Cilia Candidate Gene Discovery Pipeline

English version (README.en.md)

一套可重現的生物資訊分析管線，用於系統性篩選與 Usher 症候群及纖毛病變（ciliopathies）相關的候選基因。

本管線對人類約 22,600 個蛋白質編碼基因，透過六個獨立的證據層面進行評分與排序，最終產出分層候選基因清單，供後續實驗驗證參考。

---

目錄

• 研究背景
• 管線總覽
• 安裝與環境設定
• 執行管線
• 六大證據層面詳解
  • 1. gnomAD 約束性分析
  • 2. 基因功能註釋
  • 3. 組織表達特異性
  • 4. 亞細胞定位
  • 5. 動物模型表型
  • 6. 文獻探勘
• 綜合評分與分層
• 驗證機制
• 產出檔案說明
• 設定檔調整
• 已知限制
• 引用資料庫

---

研究背景

Usher 症候群是最常見的遺傳性聾盲症候群，患者同時出現感音神經性聽力損失與視網膜色素變性。目前已知的致病基因（如 MYO7A、USH2A、CDH23 等）約 10 個，但臨床上仍有部分患者無法找到已知基因的致病變異，暗示可能存在尚未被發現的致病或修飾基因。

Usher 蛋白在纖毛（cilia）與纖毛相關結構中扮演關鍵角色，特別是視網膜光受器細胞的連接纖毛（connecting cilium）及內耳毛細胞的靜纖毛（stereocilia）。因此，本管線以纖毛生物學為核心，整合多面向的基因體與功能體學資料，系統性地搜尋可能被忽略的候選基因。

核心設計理念

• 缺失資料 ≠ 零分：若某基因在特定證據層無資料（NULL），不會被扣分，僅以有資料的層面計算加權平均。這避免了對研究不足基因的系統性懲罰。
• 多面向正交驗證：六個證據層面分別從不同角度衡量基因與纖毛/Usher 的關聯性，降低單一資料來源偏差的影響。
• 可重現性：所有資料版本、參數設定、分析步驟均有完整記錄。

---

管線總覽

┌─────────────────────────────────────────────────────┐
│  Step 1: 建立基因宇宙 (Gene Universe)                  │
│  透過 mygene API 取得 ~22,600 個人類蛋白質編碼基因          │
└────────────────────────┬────────────────────────────┘
                         ▼
┌─────────────────────────────────────────────────────┐
│  Step 2: 六大證據層面 (並行可獨立執行)                     │
│                                                     │
│  ┌───────────┐ ┌───────────┐ ┌────────────────┐    │
│  │ gnomAD    │ │ 功能註釋   │ │ 組織表達特異性   │    │
│  │ 約束性    │ │           │ │                │    │
│  └───────────┘ └───────────┘ └────────────────┘    │
│  ┌───────────┐ ┌───────────┐ ┌────────────────┐    │
│  │ 亞細胞定位 │ │ 動物模型   │ │ 文獻探勘       │    │
│  │           │ │ 表型      │ │                │    │
│  └───────────┘ └───────────┘ └────────────────┘    │
└────────────────────────┬────────────────────────────┘
                         ▼
┌─────────────────────────────────────────────────────┐
│  Step 3: 綜合加權評分 + 信心分層                         │
│  NULL-aware weighted average → HIGH/MEDIUM/LOW       │
└────────────────────────┬────────────────────────────┘
                         ▼
┌─────────────────────────────────────────────────────┐
│  Step 4: 驗證 + 報告產出                                │
│  已知 Usher/cilia 基因排名驗證 → TSV + Parquet + 圖表   │
└─────────────────────────────────────────────────────┘

---

安裝與環境設定

系統需求

• Python 3.11 以上
• 約 5 GB 磁碟空間（用於快取下載的資料庫檔案）
• 網路連線（首次執行需下載外部資料）

安裝步驟

打開終端機（Terminal），進入專案資料夾後執行：

# 1. 建立虛擬環境（建議）
python -m venv .venv
source .venv/bin/activate    # macOS / Linux
# .venv\Scripts\activate     # Windows

# 2. 安裝管線
pip install -e ".[dev]"

安裝完成後，可以用以下指令確認是否成功：

usher-pipeline info

如果看到版本號與設定摘要，表示安裝成功。

NCBI API Key（文獻探勘層需要）

文獻探勘層使用 NCBI PubMed E-utilities API。此 API 需要提供電子郵件，並建議申請 API Key 以提高查詢速度（3 次/秒 → 10 次/秒）。

申請方式：前往 https://www.ncbi.nlm.nih.gov/account/ 註冊 NCBI 帳號，在帳號設定中產生 API Key。

---

執行管線

以下是完整的執行流程。每一步都是獨立的指令，按順序執行即可。

提示：每個指令執行完畢後會顯示摘要統計。如果中途失敗，修正問題後重新執行同一步即可（所有步驟皆為冪等操作，重複執行不會產生重複資料）。

Step 1：建立基因宇宙

usher-pipeline setup

這一步會：

• 透過 mygene API 查詢所有人類蛋白質編碼基因（約 22,600 個）
• 建立 Ensembl Gene ID ↔ HGNC Symbol ↔ UniProt Accession 的對應關係
• 結果儲存至本地 DuckDB 資料庫（data/pipeline.duckdb）

Step 2：執行六大證據層面

六個層面可以按任意順序執行，彼此之間互相獨立。但請逐一執行，不要同時開兩個（DuckDB 僅支援單一寫入者）。

# 2a. gnomAD 約束性指標
usher-pipeline evidence gnomad

# 2b. 基因功能註釋
usher-pipeline evidence annotation

# 2c. 組織表達特異性
usher-pipeline evidence expression

# 2d. 亞細胞定位
usher-pipeline evidence localization

# 2e. 動物模型表型
usher-pipeline evidence animal-models

# 2f. 文獻探勘（需要 email，建議提供 API key）
usher-pipeline evidence literature --email your@email.com --api-key YOUR_KEY

注意：文獻探勘層需要查詢 22,600 個基因的 PubMed 記錄，速度較慢（約 8 基因/分鐘），完整執行可能需要較長時間。此層支援中斷後續跑（checkpoint-restart），如果中途斷線，重新執行同一指令即可從上次進度繼續。

Step 3：綜合評分

usher-pipeline score

此步驟會：

• 以 LEFT JOIN 合併六個證據層的分數
• 計算 NULL-aware 加權綜合分數
• 對已知 Usher/纖毛基因進行排名驗證（正控制）
• 將基因分為 HIGH / MEDIUM / LOW 三個信心層級

Step 4：產出報告

usher-pipeline report

產出檔案會放在 data/report/ 目錄，包含：

• candidates.tsv — 候選基因清單（可用 Excel 開啟）
• candidates.parquet — 同上，但為高效能二進位格式（適合 R / Python 後續分析）
• score_distribution.png — 分數分佈圖
• evidence_coverage.png — 各證據層覆蓋率圖
• tier_distribution.png — 信心層級分佈圓餅圖
• reproducibility.md — 可重現性報告（含所有參數與資料版本）

選用：驗證報告

usher-pipeline validate

驗證已知 Usher 基因與 SYSCILIA 纖毛基因是否排名在前 25%，確認評分系統的有效性。

---

六大證據層面詳解

1. gnomAD 約束性分析

生物學問題：此基因是否在人類族群中顯示強烈的功能喪失（Loss-of-Function）選擇約束？

資料來源：gnomAD v4.1 約束性指標

科學依據： 如果一個基因對正常生理功能是必要的（例如感覺功能），那麼在人類族群中應該很少觀察到該基因的功能喪失型變異（LoF variants），因為帶有這些變異的個體會有降低的適應性。gnomAD 資料庫透過比較「觀察到的 LoF 變異數量」與「預期的 LoF 變異數量」，計算出約束性指標。

關鍵指標：

• LOEUF（Loss-of-function Observed/Expected Upper bound Fraction）：越低代表約束越強
• pLI（Probability of LoF Intolerance）：越高代表越不容忍 LoF 變異

評分方式： 將 LOEUF 值反轉並正規化至 0–1 範圍：

loeuf_normalized = (LOEUF_max − LOEUF) / (LOEUF_max − LOEUF_min)

分數越高 = 約束性越強 = 該基因對正常功能越重要。

品質控管：要求平均定序深度 ≥30x 且 CDS 涵蓋率 ≥90%，低於此閾值的基因標記為 incomplete_coverage。

---

2. 基因功能註釋

生物學問題：此基因的功能註釋完整程度如何？

資料來源：

• Gene Ontology（GO）— 生物過程、分子功能、細胞組分
• UniProt — 蛋白質註釋品質分數（0–5）
• KEGG / Reactome — 代謝與訊號傳遞路徑

科學依據： 功能註釋的完整程度反映了一個基因被研究的深度。注意：此層面與「新穎性」呈負相關——註釋越少的基因可能代表尚未被發現的生物學。因此在綜合評分中，此層僅佔 15% 權重，讓缺乏註釋但有其他證據支持的新穎候選基因仍能獲得高排名。

評分方式：

annotation_score = 0.5 × GO 組分 + 0.3 × UniProt 組分 + 0.2 × Pathway 組分

其中：
  GO 組分 = log₂(GO term 數量 + 1) / log₂(最大 GO term 數量 + 1)
  UniProt 組分 = UniProt 分數 / 5.0
  Pathway 組分 = 若有任何 pathway 註釋則為 1，否則為 0

---

3. 組織表達特異性

生物學問題：此基因是否特異性地表達在 Usher 症候群相關的組織（視網膜、內耳）？

資料來源：

• HPA（Human Protein Atlas）v23 — 組織層級 RNA 表達量（TPM）
• GTEx v8 — 54 個人體組織的大量 RNA 定序資料
• CellxGene — 單細胞 RNA 定序（光受器細胞、毛細胞群體）

科學依據： Usher 症候群影響視網膜光受器細胞與耳蝸毛細胞。若一個基因在這些組織中高度富集表達，暗示其在這些組織具有特化功能，是值得關注的候選基因。

關鍵指標：

1. Tau 組織特異性指數（τ）：衡量一個基因在各組織間的表達均勻程度

   • τ = 0：遍在表達（housekeeping gene）
   • τ = 1：高度組織特異性
   • 公式：τ = Σ(1 − xᵢ/x_max) / (n − 1)

2. Usher 組織富集度：目標組織（視網膜、小腦、光受器、毛細胞）的平均表達量，除以所有組織的整體平均表達量。比值 > 1 代表在目標組織富集。

評分方式：

expression_score = 0.4 × 富集度百分位數 + 0.3 × τ 特異性 + 0.3 × 目標組織最大表達百分位數

使用百分位數正規化，避免絕對 TPM 值因定序深度差異而產生偏差。

---

4. 亞細胞定位

生物學問題：此蛋白質是否定位在纖毛、中心體或基體等與 Usher 病理機轉相關的亞細胞結構？

資料來源：

• HPA 亞細胞定位資料 — 免疫螢光顯微鏡
• 纖毛蛋白質體學 — 已發表的纖毛質譜資料集（CiliaCarta 等）
• 中心體蛋白質體學 — 已發表的中心體質譜資料集

科學依據： 已知的 Usher 蛋白（MYO7A、USH1C、CDH23 等）都是纖毛或纖毛周邊蛋白。蛋白質定位在纖毛/基體/中心體，是參與纖毛病變途徑的強力機制性證據。

評分方式：

定位區域	基礎分數
纖毛、中心體、基體、轉換區、靜纖毛	1.0
細胞骨架、微管、細胞連接	0.5
僅出現在蛋白質體學資料集	0.3
有定位資料但與纖毛無關	0.0
無定位資料	NULL

證據權重：

• 實驗證據（HPA Enhanced/Supported 可靠度、蛋白質體學）：× 1.0
• 計算預測（HPA Approved/Uncertain 可靠度）：× 0.6

localization_score = 纖毛接近度基礎分數 × 證據類型權重

---

5. 動物模型表型

生物學問題：在小鼠或斑馬魚中，此基因的直系同源物（ortholog）被破壞時，是否會產生感覺或纖毛相關的表型？

資料來源：

• HCOP（HUGO Gene Nomenclature Committee Ortholog Predictions）— 人-鼠/人-魚直系同源物對應
• MGI（Mouse Genome Informatics）— 小鼠基因剔除表型（MP ontology）
• ZFIN（Zebrafish Information Network）— 斑馬魚突變表型
• IMPC（International Mouse Phenotyping Consortium）— 系統性基因剔除篩選

科學依據： 跨物種的感覺表型保守性提供了功能驗證。小鼠的聽力/平衡缺陷及斑馬魚的側線系統缺陷，都能重現人類 Usher 症候群的病理特徵。

表型關鍵字篩選：

• 小鼠：hearing、vision、retina、photoreceptor、cochlea、stereocilia、cilia、vestibular、balance
• 斑馬魚：hearing、ear、otic、otolith、lateral line、hair cell、retina、vision、eye

評分方式：

animal_model_score =
    0.4 × 小鼠分數 × 小鼠信心度 +
    0.3 × 斑馬魚分數 × 斑馬魚信心度 +
    0.3 × IMPC 額外加分

信心度權重：HIGH = 1.0, MEDIUM = 0.7, LOW = 0.4
表型數量縮放：log₂(感覺表型數量 + 1) / log₂(最大數量 + 1)

使用對數縮放防止註釋數量過多的基因主導排名（報酬遞減效應）。

---

6. 文獻探勘

生物學問題：此基因在科學文獻中是否被提及與纖毛或感覺功能相關？文獻證據的品質如何？

資料來源：NCBI PubMed（透過 E-utilities API）

科學依據： 文獻證據反映了累積的科學知識，但存在研究偏差（study bias）——明星基因（如 TP53、BRCA1）擁有大量文獻，但這不代表它們與纖毛相關。本層的正規化策略特別針對這個問題進行校正。

證據品質分級：

等級	說明	權重
direct_experimental	基因剔除/突變 + 纖毛/感覺語境	1.0
functional_mention	纖毛/感覺語境 + ≥3 篇文獻	0.6
hts_hit	高通量篩選命中 + 纖毛/感覺語境	0.3
incidental	有文獻但無纖毛/感覺語境	0.1
none	無文獻	0.0

研究偏差校正：

raw_score = (語境分數 × 品質權重) / log₂(PubMed 總文獻數 + 1)
literature_score = percentile_rank(raw_score)

除以 log₂(總文獻數) 的關鍵意義：一個基因若在 50 篇文獻中有 5 篇提及纖毛，會比在 100,000 篇文獻中有 5 篇提及纖毛得到更高的分數。這鼓勵發現被忽略但有線索的基因。

---

綜合評分與分層

加權綜合分數

六個證據層以可調整的權重合併為單一綜合分數：

證據層	預設權重	生物學意義
gnomAD 約束性	20%	基因的功能必要性
組織表達	20%	在目標組織的特異性表達
功能註釋	15%	已知的功能特徵
亞細胞定位	15%	纖毛結構的接近程度
動物模型	15%	跨物種的功能驗證
文獻探勘	15%	文獻中的纖毛/感覺關聯

NULL-aware 加權平均：

composite_score = Σ(scoreᵢ × weightᵢ) / Σ(weightᵢ)
                  ─── 僅計算非 NULL 的層面 ───

例如：某基因只有 gnomAD（0.8）、表達（0.6）和定位（0.9）三層有資料：

composite_score = (0.8×0.20 + 0.6×0.20 + 0.9×0.15) / (0.20 + 0.20 + 0.15)
               = 0.415 / 0.55
               = 0.755

信心分層

層級	條件	意義
HIGH	綜合分數 ≥ 0.7 且 ≥ 3 層有資料	高優先候選基因，建議進入實驗驗證
MEDIUM	綜合分數 ≥ 0.4 且 ≥ 2 層有資料	中等證據，值得進一步文獻調查
LOW	綜合分數 ≥ 0.2	證據薄弱，需要更多資料
EXCLUDED	低於以上條件	排除，不列入候選清單

品質旗標

旗標	條件	說明
sufficient_evidence	≥ 4 層有分數	資料涵蓋充分
moderate_evidence	≥ 2 層有分數	部分涵蓋
sparse_evidence	≥ 1 層有分數	資料稀疏
no_evidence	0 層有分數	完全無資料

---

驗證機制

管線內建正控制驗證，確認評分系統的有效性：

正控制基因集

1. OMIM Usher 基因（10 個）：MYO7A、USH1C、CDH23、PCDH15、USH1G、CIB2、USH2A、ADGRV1、WHRN、CLRN1
2. SYSCILIA SCGS v2 核心纖毛基因（28 個）：IFT88、IFT140、BBS1、CEP290、RPGR 等

驗證標準

• 已知基因的中位百分位排名應 ≥ 75%（前四分之一）
• 前 10% 候選基因應包含 > 70% 的已知基因（Recall@10%）

如果驗證未通過，表示權重設定或資料品質可能有問題，需要檢視並調整。

---

產出檔案說明

所有結果儲存在 data/report/ 目錄：

檔案	說明	適用對象
candidates.tsv	候選基因清單（Tab 分隔）	用 Excel 或文字編輯器開啟
candidates.parquet	同上，高效能二進位格式	R（arrow::read_parquet）或 Python（polars.read_parquet）
score_distribution.png	分數分佈直方圖	快速了解整體分佈
evidence_coverage.png	各證據層覆蓋率圖	了解哪些層資料最完整
tier_distribution.png	HIGH/MEDIUM/LOW 比例圓餅圖	快速概覽
reproducibility.md	完整的參數、資料版本與軟體環境記錄	論文方法學 / 重現分析

candidates.tsv 欄位說明

核心欄位：

• gene_id — Ensembl 基因 ID（如 ENSG00000154229）
• gene_symbol — HGNC 基因符號（如 MYO7A）
• composite_score — 綜合分數（0–1）
• confidence_tier — 信心層級（HIGH / MEDIUM / LOW）
• evidence_count — 有非 NULL 分數的證據層數量（0–6）

各層分數（0–1，NULL 表示無資料）：

• gnomad_score — 約束性分數
• expression_score — 表達特異性分數
• annotation_score — 功能註釋分數
• localization_score — 亞細胞定位分數
• animal_model_score — 動物模型表型分數
• literature_score — 文獻證據分數

輔助欄位：

• supporting_layers — 有分數的層面清單（如 gnomad,expression,localization）
• evidence_gaps — 缺少資料的層面清單
• quality_flag — 品質旗標

---

設定檔調整

管線設定檔位於 config/default.yaml：

# 資料版本
versions:
  ensembl_release: 113
  gnomad_version: v4.1
  gtex_version: v8
  hpa_version: "23.0"

# 評分權重（可依研究需求調整，總和必須為 1.0）
scoring:
  gnomad: 0.20
  expression: 0.20
  annotation: 0.15
  localization: 0.15
  animal_model: 0.15
  literature: 0.15

# API 設定
api:
  rate_limit_per_second: 5
  max_retries: 5
  timeout_seconds: 30

若要調整權重（例如更重視組織表達），修改 scoring 區塊後重新執行 usher-pipeline score 與 usher-pipeline report 即可。

---

已知限制

限制	說明	影響
GTEx v8 無視網膜組織	GTEx v8 不包含 "Eye - Retina" 組織	視網膜表達資料僅來自 HPA
HPA 基因符號比對落差	HPA 使用 gene symbol，管線以 gene ID 為主鍵	部分基因的 HPA 表達資料可能遺失
gnomAD 轉錄本層級 ID	gnomAD 使用轉錄本 ID，非基因層級	部分基因 JOIN 時可能產生 NaN
文獻探勘速度	NCBI API 限制，~8 基因/分鐘	完整執行需要較長時間；可使用 API key 加速
單一寫入限制	DuckDB 不支援多行程同時寫入	請勿同時執行兩個管線步驟
內耳資料稀缺	人類耳蝸組織的大量轉錄體資料有限	以小腦（含纖毛）及 CellxGene 毛細胞資料作為替代

---

引用資料庫

本管線整合以下公開資料庫與工具：

• gnomAD v4.1 — Karczewski et al. (2020) Nature 581:434-443
• Human Protein Atlas v23 — Uhlén et al. (2015) Science 347:1260419
• GTEx v8 — GTEx Consortium (2020) Science 369:1318-1330
• CellxGene — Chan Zuckerberg Initiative single-cell atlas
• Gene Ontology — Gene Ontology Consortium (2021) Nucleic Acids Res 49:D325-D334
• UniProt — UniProt Consortium (2023) Nucleic Acids Res 51:D523-D531
• MGI — Mouse Genome Informatics, The Jackson Laboratory
• ZFIN — Zebrafish Information Network
• IMPC — International Mouse Phenotyping Consortium
• SYSCILIA SCGS v2 — van Dam et al. (2021) Mol Biol Cell 32:br6
• mygene.info — Xin et al. (2016) Genome Biol 17:91
• NCBI E-utilities — PubMed literature search API

---

授權

MIT License