AlphaGenome – Google DeepMind DNA 調控密碼統一模型完整教學

AlphaGenome 是 Google DeepMind 開發的統一基因體模型 (unified genomic model)，能從 DNA 序列 (DNA sequence) 同時預測 gene expression (基因表現)、splicing patterns (剪接模式)、chromatin features (染色質特徵) 與 contact maps (接觸圖譜)，最長可分析 100 萬鹼基對，並達到 single base-pair resolution (單鹼基解析度)。
論文：Avsec et al., Nature 649, 1206–1218 (2026). DOI: 10.1038/s41586-025-10014-0

1. 專案概述 (Project Overview)

1.1 AlphaGenome 是什麼

AlphaGenome 是 Google DeepMind 推出的 regulatory variant-effect prediction (調控變異效應預測) 統一模型。它接受原始 DNA 序列作為輸入，透過單一模型同時預測多種功能性輸出 (multimodal predictions)：

輸出模態 (Output Modality)	說明	對應 OutputType
ATAC-seq	Chromatin accessibility (染色質開放性)	`ATAC`
CAGE	Cap Analysis of Gene Expression (基因表現)	`CAGE`
DNase	DNase I hypersensitive sites (DNA酶超敏感位點)	`DNASE`
RNA-seq	Gene expression tracks (RNA 定序基因表現)	`RNA_SEQ`
ChIP-seq (Histone)	Histone modification patterns (組蛋白修飾)	`CHIP_HISTONE`
ChIP-seq (TF)	Transcription factor binding (轉錄因子結合)	`CHIP_TF`
Splice sites	Donor / acceptor splice sites (剪接位點)	`SPLICE_SITES`
Splice site usage	Fraction of splice site utilization (剪接位點使用比例)	`SPLICE_SITE_USAGE`
Splice junctions	Split-read RNA-seq junction counts (剪接接合點)	`SPLICE_JUNCTIONS`
Contact maps	3D DNA-DNA contact probabilities (3D 接觸圖譜)	`CONTACT_MAPS`
PRO-cap	Precision Run-On + capping (精確啟動子活性)	`PROCAP`

1.2 關鍵數字

Stars: 1,948 / Forks: 262
語言: Python (100%)
授權: Apache License 2.0 (API 限非商業用途)
序列長度支援: 16 KB, 100 KB, 500 KB, 1 MB (2^14 ~ 2^20 bp)
論文出處: Nature 2026, DOI: 10.1038/s41586-025-10014-0
建立日期: 2024-10-16
最後更新: 2026-06-17

1.3 與同類工具比較

 1+------------------+----------+-----------+------------+----------+
 2| 特性              | Enformer | Borzoi    | Nucleotide | AlphaGenome |
 3|                  |          |           | Transformer|             |
 4+------------------+----------+-----------+------------+----------+
 5| 序列長度 (max bp) | 196,608  | 524,288   | 6,000      | 1,048,576   |
 6| 多模態輸出        | 部分     | 部分      | 有限       | 完整 (11種) |
 7| Contact maps     | 否       | 否        | 否         | 是          |
 8| Variant scoring  | 手動     | 手動      | 有限       | 內建多策略  |
 9| API 存取         | 否       | 否        | 否         | 是 (gRPC)   |
10| 視覺化程式庫      | 否       | 否        | 否         | 內建        |
11+------------------+----------+-----------+------------+----------+

1.4 適用場景

Regulatory variant interpretation (調控變異解讀): 判斷 non-coding variant 是否影響基因表現
Gene expression prediction (基因表現預測): 從 DNA 序列預測組織特異性表現量
Splicing analysis (剪接分析): 預測 splice site 使用率與新剪接事件
Chromatin profiling (染色質圖譜): 預測 ATAC / DNase / histone modification 模式
3D genome structure (3D 基因體結構): 預測 DNA-DNA contact probability
In silico mutagenesis (ISM; 電腦模擬突變): 系統性掃描序列中每個位點的影響

2. 核心架構與技術原理 (Architecture & Technical Principles)

2.1 系統架構總覽


graph TB
    subgraph Client["AlphaGenome Python Client"]
        A[User Code] --> B[DnaClient]
        B --> C[gRPC Channel]
        B --> D[Variant Scorers]
        B --> E[ISM Module]
        B --> F[Visualization]
    end

    subgraph API["AlphaGenome API Server (Google Cloud)"]
        C --> G[gRPC Endpoint]
        G --> H[AlphaGenome Model]
        H --> I[Multimodal Output]
    end

    subgraph DataLayer["Data Layer"]
        J[genome.Interval] --> B
        K[genome.Variant] --> B
        L[ontology.OntologyTerm] --> B
        M[TrackData / JunctionData] --> F
    end

    I --> N[Output Dataclass]
    N --> O[TrackData per modality]
    O --> F
    D --> P[ScoreVariantOutput / AnnData]

    style Client fill:#e8f4f8,stroke:#2196F3
    style API fill:#fff3e0,stroke:#FF9800
    style DataLayer fill:#e8f5e9,stroke:#4CAF50

2.2 核心元件解析

2.2.1 DnaClient – API 存取層

DnaClient 是與 AlphaGenome 伺服器溝通的核心類別，透過 gRPC streaming 傳輸預測結果。主要方法：

方法	用途	輸入	輸出
`predict_sequence()`	從原始 DNA 字串預測	sequence string + output types	`Output`
`predict_interval()`	從基因體座標預測	`Interval` + output types	`Output`
`predict_variant()`	預測 variant 對各模態的影響	`Interval` + `Variant`	`VariantOutput` (ref + alt)
`score_variant()`	量化 variant effect	`Interval` + `Variant` + scorers	`ScoreVariantOutput` (AnnData)
`score_ism_variants()`	系統性 ISM 掃描	`Interval` + ISM interval	ISM scores
`score_interval()`	對整段區間評分	`Interval` + scorers	`ScoreIntervalOutput`
`output_metadata()`	查詢模型支援的 tracks	output types	metadata dict

2.2.2 Data Layer – 基因體資料結構


classDiagram
    class Interval {
        +str chromosome
        +int start
        +int end
        +Strand strand
        +str name
        +int width
        +resize()
        +shift()
        +contains()
        +overlaps()
    }

    class Variant {
        +str chromosome
        +int position
        +str reference_bases
        +str alternate_bases
    }

    class Strand {
        <>
        POSITIVE
        NEGATIVE
        UNSTRANDED
    }

    class TrackData {
        +Interval interval
        +ndarray data
        +list track_names
        +resize()
        +slice_tracks()
    }

    class JunctionData {
        +Interval interval
        +DataFrame junctions
    }

    Interval --> Strand
    TrackData --> Interval
    JunctionData --> Interval
    Variant --> Interval : references

關鍵設計: Interval 使用 0-based, half-open 座標系統 (與 BED format 相同)，而 Variant 的 position 使用 1-based 座標 (與 VCF format 相同)。

2.2.3 Variant Scoring Pipeline (變異評分管線)


flowchart LR
    A[REF + ALT\n序列] --> B[模型預測\n各模態]
    B --> C{Indel?}
    C -->|Yes| D[Indel Alignment\n對齊]
    C -->|No| E[Spatial Mask\n空間遮罩]
    D --> E
    E --> F[Aggregation\n聚合計算]
    F --> G[ALT - REF\n差異量化]
    G --> H[Scalar Score\nper track]

    style A fill:#e3f2fd
    style H fill:#c8e6c9

Aggregation Types (聚合類型)：

類型	公式	適用場景
`DIFF_MEAN`	mean(ALT) - mean(REF)	一般用途
`DIFF_SUM`	sum(ALT) - sum(REF)	累積效應
`DIFF_SUM_LOG2`	sum(log2(ALT)) - sum(log2(REF))	Log-scale 預測
`DIFF_LOG2_SUM`	log2(sum(ALT)) - log2(sum(REF))	Log fold change
`L2_DIFF`	l2_norm(ALT - REF)	方向無關的變化量
`L2_DIFF_LOG1P`	l2_norm(log1p(ALT) - log1p(REF))	Log-scale L2 差異
`ACTIVE_MEAN`	max(mean(ALT), mean(REF))	活性判斷
`ACTIVE_SUM`	max(sum(ALT), sum(REF))	累積活性

Spatial Mask Types (空間遮罩)：

CENTER_MASK: 以 variant 位置為中心的遮罩
GENE_MASK_LFC: 基於 gene annotation 的遮罩 (log fold change)
GENE_MASK_SPLICING: 針對 splicing 分析的基因遮罩
CONTACT_MAP: 處理 2D tensor 的中心遮罩
PA_QTL: Polyadenylation QTL 專用評分

2.3 支援的序列長度

1SEQUENCE_LENGTH_16KB  = 2**14   #    16,384 bp
2SEQUENCE_LENGTH_100KB = 2**17   #   131,072 bp
3SEQUENCE_LENGTH_500KB = 2**19   #   524,288 bp
4SEQUENCE_LENGTH_1MB   = 2**20   # 1,048,576 bp

序列長度必須嚴格等於上述四種之一。較長的序列能捕獲更多 distal regulatory elements (遠端調控元件)，但 API 回應時間也更長。

2.4 Ontology System (本體論系統)

AlphaGenome 使用 ontology terms (如 UBERON:0001157 代表 liver/肝臟) 來指定組織與細胞類型。透過 ontology_terms 參數，使用者可以請求特定組織情境下的預測結果。

3. 安裝與環境設定 (Installation & Setup)

3.1 系統需求

Python: >= 3.10 (支援 3.10, 3.11, 3.12, 3.13)
作業系統: Linux, macOS, Windows (需支援 gRPC)
網路: 需要存取 AlphaGenome API endpoint
API Key: 需從 deepmind.google.com/science/alphagenome 申請

3.2 安裝步驟

方法 A：從 GitHub clone 安裝 (推薦)

1# 建立虛擬環境 (使用 uv)
2uv venv alphagenome-env
3source alphagenome-env/bin/activate
4
5# Clone 並安裝
6git clone https://github.com/google-deepmind/alphagenome.git
7cd alphagenome
8pip install .

方法 B：使用 hatch (開發模式)

1git clone https://github.com/google-deepmind/alphagenome.git
2cd alphagenome
3pip install hatch
4hatch shell   # 自動建立開發環境

3.3 API Key 設定

前往 AlphaGenome 申請頁面取得 API key
API 限 非商業用途 (non-commercial use)，須遵守 Terms of Use

1# 建議透過環境變數管理
2export ALPHAGENOME_API_KEY="your-api-key-here"

1import os
2from alphagenome.models import dna_client
3
4api_key = os.environ["ALPHAGENOME_API_KEY"]
5model = dna_client.create(api_key)

3.4 驗證安裝

 1from alphagenome.data import genome
 2from alphagenome.models import dna_client
 3
 4# 建立 client
 5model = dna_client.create("YOUR_API_KEY")
 6
 7# 查詢可用的 output metadata
 8metadata = model.output_metadata(
 9    requested_outputs=[dna_client.OutputType.RNA_SEQ]
10)
11print(metadata)  # 應顯示支援的 tracks 資訊

3.5 核心依賴一覽

 1absl-py          # Google 基礎工具
 2anndata          # AnnData 格式 (scRNA-seq 標準)
 3grpcio >= 1.67.1 # gRPC 通訊
 4matplotlib       # 視覺化
 5numpy            # 數值計算
 6pandas           # 表格資料
 7scipy            # 科學計算
 8seaborn          # 統計視覺化
 9protobuf >= 5.28 # Protocol Buffers
10zstandard        # 壓縮

4. 使用教學與範例 (Usage Tutorial & Examples)

4.1 基本預測：從基因體座標預測 RNA-seq

 1from alphagenome.data import genome
 2from alphagenome.models import dna_client
 3import os
 4
 5# 初始化 client
 6model = dna_client.create(os.environ["ALPHAGENOME_API_KEY"])
 7
 8# 定義基因體區間 (0-based, half-open)
 9interval = genome.Interval(
10    chromosome='chr22',
11    start=35677410,
12    end=36725986       # 約 1 MB 區間
13)
14
15# 進行預測
16output = model.predict_interval(
17    interval=interval,
18    requested_outputs=[dna_client.OutputType.RNA_SEQ],
19    ontology_terms=['UBERON:0001157'],  # Liver (肝臟)
20)
21
22# 存取結果
23rna_seq_data = output.rna_seq  # TrackData 物件
24print(f"Track names: {rna_seq_data.track_names}")
25print(f"Data shape: {rna_seq_data.data.shape}")
26print(f"Interval: {rna_seq_data.interval}")

4.2 變異效應預測 (Variant Effect Prediction)

 1from alphagenome.data import genome
 2from alphagenome.models import dna_client
 3from alphagenome.visualization import plot_components
 4import matplotlib.pyplot as plt
 5
 6model = dna_client.create(os.environ["ALPHAGENOME_API_KEY"])
 7
 8# 定義區間與變異
 9interval = genome.Interval(chromosome='chr22', start=35677410, end=36725986)
10variant = genome.Variant(
11    chromosome='chr22',
12    position=36201698,      # 1-based (VCF 格式)
13    reference_bases='A',
14    alternate_bases='C',
15)
16
17# 預測 variant effect
18outputs = model.predict_variant(
19    interval=interval,
20    variant=variant,
21    ontology_terms=['UBERON:0001157'],
22    requested_outputs=[dna_client.OutputType.RNA_SEQ],
23)
24
25# 存取 REF 與 ALT 預測結果
26ref_rna = outputs.reference.rna_seq
27alt_rna = outputs.alternate.rna_seq
28
29# 視覺化
30plot_components.plot(
31    [
32        plot_components.OverlaidTracks(
33            tdata={'REF': ref_rna, 'ALT': alt_rna},
34            colors={'REF': 'dimgrey', 'ALT': 'red'},
35        ),
36    ],
37    interval=ref_rna.interval.resize(2**15),
38    annotations=[plot_components.VariantAnnotation([variant], alpha=0.8)],
39)
40plt.title("RNA-seq: REF vs ALT at chr22:36201698 A>C")
41plt.show()

4.3 量化變異評分 (Variant Scoring)

 1from alphagenome.models import variant_scorers
 2
 3# 定義評分策略
 4scorers = [
 5    variant_scorers.VariantScorer(
 6        base_scorer=variant_scorers.BaseVariantScorer.CENTER_MASK,
 7        aggregation=variant_scorers.AggregationType.DIFF_LOG2_SUM,
 8        output_type=dna_client.OutputType.RNA_SEQ,
 9        mask_half_width=5000,
10    ),
11    variant_scorers.VariantScorer(
12        base_scorer=variant_scorers.BaseVariantScorer.CENTER_MASK,
13        aggregation=variant_scorers.AggregationType.L2_DIFF,
14        output_type=dna_client.OutputType.ATAC,
15        mask_half_width=2000,
16    ),
17]
18
19# 執行評分
20score_output = model.score_variant(
21    interval=interval,
22    variant=variant,
23    variant_scorers=scorers,
24    ontology_terms=['UBERON:0001157'],
25)
26
27# 結果為 AnnData 格式
28print(score_output.scores)  # AnnData object
29print(score_output.scores.to_df())  # 轉為 DataFrame

4.4 多模態同時預測

 1# 同時請求多種輸出模態
 2output = model.predict_interval(
 3    interval=interval,
 4    requested_outputs=[
 5        dna_client.OutputType.RNA_SEQ,
 6        dna_client.OutputType.ATAC,
 7        dna_client.OutputType.CHIP_HISTONE,
 8        dna_client.OutputType.SPLICE_SITES,
 9        dna_client.OutputType.CONTACT_MAPS,
10    ],
11    ontology_terms=['UBERON:0001157'],
12)
13
14# 各模態獨立存取
15print(f"RNA-seq shape:  {output.rna_seq.data.shape}")
16print(f"ATAC shape:     {output.atac.data.shape}")
17print(f"Histone shape:  {output.chip_histone.data.shape}")
18print(f"Splice shape:   {output.splice_sites.data.shape}")
19print(f"Contact shape:  {output.contact_maps.data.shape}")

4.5 視覺化範例

 1from alphagenome.visualization import plot_components, plot_transcripts
 2
 3# 多軌視覺化
 4fig, axes = plt.subplots(4, 1, figsize=(14, 12), sharex=True)
 5
 6# Track 1: RNA-seq
 7plot_components.plot(
 8    [plot_components.SingleTrack(tdata=output.rna_seq)],
 9    interval=interval.resize(2**15),
10    ax=axes[0],
11)
12axes[0].set_title("RNA-seq")
13
14# Track 2: ATAC
15plot_components.plot(
16    [plot_components.SingleTrack(tdata=output.atac)],
17    interval=interval.resize(2**15),
18    ax=axes[1],
19)
20axes[1].set_title("ATAC-seq")
21
22# Track 3: Histone ChIP
23plot_components.plot(
24    [plot_components.SingleTrack(tdata=output.chip_histone)],
25    interval=interval.resize(2**15),
26    ax=axes[2],
27)
28axes[2].set_title("Histone ChIP-seq")
29
30# Track 4: Splice sites
31plot_components.plot(
32    [plot_components.SingleTrack(tdata=output.splice_sites)],
33    interval=interval.resize(2**15),
34    ax=axes[3],
35)
36axes[3].set_title("Splice Sites")
37
38plt.tight_layout()
39plt.show()

4.6 Colab Notebooks 導覽

Notebook	內容	連結
`quick_start.ipynb`	基本使用與首次預測	Colab
`visualization_modality_tour.ipynb`	所有模態的視覺化教學	Colab
`essential_commands.ipynb`	核心 API 指令總覽	Colab
`batch_variant_scoring.ipynb`	批次變異評分	Colab
`splicing_variant_scoring.ipynb`	剪接變異專用評分	Colab
`tissue_ontology_mapping.ipynb`	組織 ontology 對照	Colab
`variant_scoring_ui.ipynb`	互動式 variant 評分 UI	Colab
`example_analysis_workflow.ipynb`	完整分析工作流範例	Colab

5. 進階功能與最佳實踐 (Advanced Features & Best Practices)

5.1 In Silico Mutagenesis (ISM; 電腦模擬突變)

ISM 是系統性地將序列中每個位置替換為其他三種鹼基，觀察對預測結果的影響：

 1from alphagenome.interpretation import ism
 2
 3# 定義目標區間 (建議不超過 10 bp 的 ISM window)
 4ism_interval = genome.Interval(
 5    chromosome='chr22',
 6    start=36201695,
 7    end=36201705,   # 10 bp window
 8)
 9
10# 執行 ISM
11ism_output = model.score_ism_variants(
12    interval=interval,         # 完整預測區間
13    ism_interval=ism_interval, # ISM 掃描區間
14    variant_scorers=scorers,
15    ontology_terms=['UBERON:0001157'],
16)
17
18# 結果包含每個突變位點的評分
19print(ism_output.scores.to_df())


flowchart TD
    A[原始序列\nACGTACGTAC] --> B[Position 1\nCCGTACGTAC\nGCGTACGTAC\nTCGTACGTAC]
    A --> C[Position 2\nAAGTACGTAC\nAGGTACGTAC\nATGTACGTAC]
    A --> D[...]
    A --> E[Position 10\nACGTACGTAA\nACGTACGTAG\nACGTACGTAT]
    B --> F[Score Matrix\n30 variants x N tracks]
    C --> F
    D --> F
    E --> F

    style A fill:#e3f2fd
    style F fill:#c8e6c9

注意: ISM 的 ism_interval 寬度上限為 MAX_ISM_INTERVAL_WIDTH = 10 bp。超過此寬度時，client 會自動分塊 (chunking) 並使用 concurrent.futures 並行處理。

5.2 批次變異評分策略

 1# 準備多個 variants
 2variants = [
 3    genome.Variant('chr22', 36201698, 'A', 'C'),
 4    genome.Variant('chr22', 36201700, 'G', 'T'),
 5    genome.Variant('chr22', 36201720, 'C', 'A'),
 6]
 7
 8# 逐一評分 (API 限制，每次一個 variant)
 9results = []
10for v in variants:
11    score = model.score_variant(
12        interval=interval,
13        variant=v,
14        variant_scorers=scorers,
15        ontology_terms=['UBERON:0001157'],
16    )
17    results.append(score)
18
19# 合併結果
20import pandas as pd
21all_scores = pd.concat([r.scores.to_df() for r in results])

5.3 Retry 機制與錯誤處理

DnaClient 內建 gRPC retry 機制，自動處理暫時性錯誤：

RESOURCE_EXHAUSTED: API 速率限制，自動 exponential backoff
UNAVAILABLE: 伺服器暫時不可用，自動重試

1# 預設參數：
2# max_attempts = 5
3# initial_backoff = 1.25s
4# backoff_multiplier = 1.5
5# jitter = 0.2 (+-20%)
6
7# 自訂 retry 行為（進階用法需修改 source）

5.4 序列長度選擇指南


flowchart TD
    Q[我的分析目標?] --> A{需要長距離\n調控資訊?}
    A -->|No| B{分析 promoter\n附近?}
    A -->|Yes| C{需要 contact\nmaps?}
    B -->|Yes| D[16 KB\n快速、低延遲]
    B -->|No| E[100 KB\n涵蓋 enhancer]
    C -->|Yes| F[1 MB\n完整 TAD 結構]
    C -->|No| G[500 KB\n遠端 enhancer]

    style D fill:#c8e6c9
    style E fill:#fff9c4
    style F fill:#ffccbc
    style G fill:#ffe0b2

序列長度	適用場景	預估回應時間
16 KB	Promoter-proximal variant、快速篩選	最快
100 KB	標準 regulatory variant 分析	快
500 KB	Distal enhancer、locus-level 分析	中等
1 MB	TAD structure、contact maps、完整調控景觀	最慢

5.5 Variant Scorer 組合最佳實踐

每次 API 請求最多可包含 20 個 variant scorers (MAX_VARIANT_SCORERS_PER_REQUEST = 20)。建議組合：

 1# 標準 eQTL 評估組合
 2eqtl_scorers = [
 3    # RNA-seq: log fold change
 4    variant_scorers.VariantScorer(
 5        base_scorer=variant_scorers.BaseVariantScorer.GENE_MASK_LFC,
 6        aggregation=variant_scorers.AggregationType.DIFF_LOG2_SUM,
 7        output_type=dna_client.OutputType.RNA_SEQ,
 8    ),
 9    # CAGE: expression change
10    variant_scorers.VariantScorer(
11        base_scorer=variant_scorers.BaseVariantScorer.GENE_MASK_LFC,
12        aggregation=variant_scorers.AggregationType.DIFF_LOG2_SUM,
13        output_type=dna_client.OutputType.CAGE,
14    ),
15    # ATAC: chromatin change
16    variant_scorers.VariantScorer(
17        base_scorer=variant_scorers.BaseVariantScorer.CENTER_MASK,
18        aggregation=variant_scorers.AggregationType.L2_DIFF,
19        output_type=dna_client.OutputType.ATAC,
20        mask_half_width=2000,
21    ),
22    # Splicing: junction usage change
23    variant_scorers.VariantScorer(
24        base_scorer=variant_scorers.BaseVariantScorer.GENE_MASK_SPLICING,
25        aggregation=variant_scorers.AggregationType.DIFF_SUM,
26        output_type=dna_client.OutputType.SPLICE_SITE_USAGE,
27    ),
28]

5.6 Gene Annotation 整合

AlphaGenome 隨附 GENCODE 資料集 (modified version)，用於 gene mask variant scoring：

1from alphagenome.data import gene_annotation
2
3# 載入 gene annotation (GENCODE)
4ga = gene_annotation.load_default()
5
6# 查詢特定基因
7gene = ga.get_gene('BRCA1')
8print(f"Gene: {gene.name}, Interval: {gene.interval}")

6. 與 Apotek 管線的整合潛力 (Integration with Apotek Pipeline)

6.1 與 WP1 Genomics Analysis 的關聯

AlphaGenome 直接對應 Apotek WP1 (genomics analysis) 的核心需求：


flowchart LR
    subgraph Apotek_WP1["Apotek WP1: Genomics Analysis"]
        A[Candidate\nVariants] --> B[Variant\nPrioritization]
        B --> C[Functional\nAnnotation]
        C --> D[Regulatory\nImpact]
        D --> E[Target\nValidation]
    end

    subgraph AlphaGenome_API["AlphaGenome Integration Points"]
        F[predict_variant\nREF vs ALT] --> C
        G[score_variant\neQTL / sQTL] --> D
        H[predict_interval\nChromatin landscape] --> B
        I[score_ism_variants\nFine-mapping] --> E
        J[Contact Maps\n3D structure] --> D
    end

    style Apotek_WP1 fill:#e8f4f8,stroke:#2196F3
    style AlphaGenome_API fill:#fff3e0,stroke:#FF9800

6.2 具體整合場景

Non-coding variant prioritization (非編碼變異優先排序): 對候選基因周圍的 regulatory variants 進行 variant effect prediction，量化其對 gene expression 的影響
Tissue-specific expression prediction (組織特異性表現預測): 使用 ontology terms 指定目標組織，預測候選基因在不同組織中的表現模式
Splicing impact assessment (剪接影響評估): 評估 variants 對 splice site usage 的影響，辨識可能導致異常剪接的突變

場景 B：表觀基因體景觀分析

 1# 範例：分析目標基因座的表觀基因體景觀
 2target_interval = genome.Interval(
 3    chromosome='chr17',
 4    start=43044295,
 5    end=43170245,    # BRCA1 locus region
 6)
 7
 8# 多組織 chromatin profiling
 9tissues = [
10    'UBERON:0000955',  # Brain (大腦)
11    'UBERON:0001157',  # Liver (肝臟)
12    'CL:0000084',      # T cell (T 細胞)
13]
14
15for tissue in tissues:
16    output = model.predict_interval(
17        interval=target_interval,
18        requested_outputs=[
19            dna_client.OutputType.ATAC,
20            dna_client.OutputType.CHIP_HISTONE,
21            dna_client.OutputType.RNA_SEQ,
22        ],
23        ontology_terms=[tissue],
24    )
25    # 比較不同組織的 chromatin accessibility
26    print(f"Tissue {tissue}: ATAC mean = {output.atac.data.mean():.4f}")

場景 C：3D Genome Structure 分析

AlphaGenome 的 contact maps 預測可用於理解基因座的 3D 結構，辨識 enhancer-promoter interactions (增強子-啟動子互動)：

 1output = model.predict_interval(
 2    interval=target_interval,
 3    requested_outputs=[dna_client.OutputType.CONTACT_MAPS],
 4    ontology_terms=['UBERON:0001157'],
 5)
 6
 7# Contact map 為 2D tensor
 8contact_data = output.contact_maps.data
 9print(f"Contact map shape: {contact_data.shape}")
10# 可用於識別 TAD boundaries 和 enhancer-promoter loops

6.3 整合架構建議


flowchart TB
    subgraph Input["Input Layer"]
        V[VCF variants] --> P[Variant Parser]
        G[Gene List] --> P
    end

    subgraph Process["Processing Layer"]
        P --> Q[Queue Manager\nrate limiting]
        Q --> AG[AlphaGenome API\nvia DnaClient]
        AG --> S[Score Aggregator]
    end

    subgraph Output["Output Layer"]
        S --> R[Results DataFrame]
        R --> CSV[CSV Export]
        R --> VIZ[Visualization]
    end

    style Input fill:#e8f5e9
    style Process fill:#e3f2fd
    style Output fill:#fff3e0

建議的整合步驟：

將 VCF 中的 candidate variants 轉換為 genome.Variant 物件
根據 variant 位置建立適當大小的 genome.Interval (建議 100 KB ~ 500 KB)
使用 score_variant() 搭配 eQTL / sQTL scorer 組合進行批次評分
對 top-ranked variants 使用 predict_variant() 產生詳細視覺化報告

6.4 注意事項

API rate limit: 適合中小規模分析 (數千次預測)，不適合全基因體掃描 (>100 萬次)
非商業限制: API 限非商業用途；若需商業應用，須申請 commercial offering
本地模型: 模型推論完全在 Google Cloud 端執行，本地不需 GPU；但需穩定網路連線
資料安全: DNA 序列會傳送至 Google API，需評估合規性 (HIPAA / institutional policy)

7. 常見問題與限制 (FAQ & Limitations)

7.1 常見問題

Q: 需要 GPU 嗎？ A: 不需要。模型推論在 Google Cloud 端執行，本地只需 Python 環境即可使用。

Q: API 免費嗎？ A: 對非商業用途免費，但有 rate limit。商業用途需另行申請。

Q: 支援哪些物種？ A: 目前僅支援 人類基因體 (human genome)。

Q: Variant position 是 0-based 還是 1-based？ A: genome.Variant.position 使用 1-based 座標 (與 VCF 相同)，而 genome.Interval 使用 0-based, half-open 座標 (與 BED 相同)。

Q: 可以離線使用嗎？ A: 不行。本 repo 提供的是 client-side SDK，模型推論必須透過 API 存取。模型本身的研究代碼在 alphagenome_research 另一個 repo。

Q: 每次請求最多可以帶幾個 variant scorers？ A: 最多 20 個 (MAX_VARIANT_SCORERS_PER_REQUEST)。

Q: ISM 掃描的最大寬度是？ A: 單次 ISM 請求最大 10 bp (MAX_ISM_INTERVAL_WIDTH)，超過會自動分塊並行處理。

7.2 已知限制

限制	說明
僅人類基因體	不支援其他物種
API-only inference	無法在本地執行模型推論
序列長度固定	必須為 16K / 100K / 500K / 1M 之一
Rate limit	查詢速率視需求而定，不適合 >1M 次預測
非商業限制	API 限非商業用途
網路依賴	需穩定網路連線至 Google Cloud
Training data bias	訓練資料以歐裔人群為主，其他族群的預測準確度可能較低
Indel 長度	對極長 insertion / deletion 的預測能力有限

7.3 疑難排解

 1# 常見錯誤 1: 序列長度不符
 2# ValueError: Sequence length must be one of [16384, 131072, 524288, 1048576]
 3# 解法: 使用 interval.resize() 調整至支援的長度
 4interval = interval.resize(2**17)  # 調整為 100 KB
 5
 6# 常見錯誤 2: gRPC RESOURCE_EXHAUSTED
 7# grpc.RpcError with StatusCode.RESOURCE_EXHAUSTED
 8# 解法: 降低請求頻率，client 會自動 retry (最多 5 次)
 9
10# 常見錯誤 3: Invalid variant bases
11# ValueError: Variant bases must be in {A, C, G, T, N}
12# 解法: 確認 variant 的 reference_bases 和 alternate_bases 只含 ACGTN
13
14# 常見錯誤 4: API key 無效
15# grpc.RpcError with StatusCode.UNAUTHENTICATED
16# 解法: 確認 API key 正確且未過期

7.4 延伸資源

論文: Avsec et al. (2026) Nature 649, 1206-1218
官方文件: alphagenomedocs.com
社群論壇: alphagenomecommunity.com
研究代碼: github.com/google-deepmind/alphagenome_research
YouTube 教學: AlphaGenome 101 tutorial
Email 支援: alphagenome@google.com

引用 (Citation)

 1@article{alphagenome,
 2  title={Advancing regulatory variant effect prediction with {AlphaGenome}},
 3  author={Avsec, {\v Z}iga and Latysheva, Natasha and Cheng, Jun and others},
 4  journal={Nature},
 5  volume={649},
 6  number={8099},
 7  pages={1206--1218},
 8  year={2026},
 9  doi={10.1038/s41586-025-10014-0}
10}

本教學由 Claude Code 自動生成 – 2026-06-20 Source: google-deepmind/alphagenome (1,948 stars, Apache-2.0)

AlphaGenome -- Google DeepMind DNA 調控密碼統一模型完整教學

Contents