1提供的內容：
2  - AlphaMissense 模型的完整實作（modules_missense.py）
3  - 訓練 loss function（clipped sigmoid cross-entropy）
4  - 資料管線（pipeline_missense.py）— 建立推論輸入特徵
5  - 預計算預測資料（託管於 Google Cloud Storage）
6
7不提供的內容：
8  - 訓練好的模型權重（weights）
9  - 因此無法直接用此 repo 進行新的預測

 1alphamissense/
 2├── LICENSE                          # Apache 2.0
 3├── README.md
 4├── requirements.txt                 # JAX/Haiku 依賴
 5├── setup.py                         # 套件安裝
 6├── test/
 7│   ├── test_installation.py         # 安裝驗證腳本
 8│   └── test_sequence.fasta          # 測試用 FASTA
 9└── alphamissense/
10    ├── __init__.py
11    ├── version.py
12    ├── common/
13    │   └── residue_constants.py     # 胺基酸常數定義
14    ├── data/
15    │   ├── pipeline_missense.py     # 資料管線（核心）
16    │   ├── mmcif_parsing.py         # mmCIF 結構解析
17    │   ├── msa_identifiers.py       # MSA 序列識別
18    │   ├── parsers.py               # 序列格式解析器
19    │   ├── templates.py             # 模板處理
20    │   └── tools/
21    │       ├── jackhmmer.py         # HMMER 搜尋包裝
22    │       └── utils.py             # 工具輔助函式
23    └── model/
24        ├── config.py                # 模型配置（48 層 Evoformer 等）
25        ├── modules_missense.py      # AlphaMissense 模型主體（核心）
26        ├── modules.py               # 共用模組（來自 AlphaFold）
27        ├── common_modules.py        # 基礎神經網路元件
28        ├── folding_multimer.py      # 結構預測模組
29        ├── layer_stack.py           # 層堆疊工具
30        ├── mapping.py               # 張量映射
31        ├── prng.py                  # 安全亂數產生器
32        ├── utils.py                 # 模型工具函式
33        └── geometry/                # 3D 幾何運算
34            ├── rigid_matrix_vector.py
35            ├── rotation_matrix.py
36            ├── struct_of_array.py
37            ├── vector.py
38            └── test_utils.py

1@dataclasses.dataclass(frozen=True)
2class ProteinVariant:
3    sequence: str          # 原始蛋白質序列
4    position: int          # 1-based 位置
5    reference_aa: str      # 參考胺基酸（單字母）
6    alternate_aa: str      # 替換胺基酸（單字母）
7    protein_id: str        # 序列識別碼
8    pathogenicity: Optional[bool]  # 訓練用標籤

1score = ref_score - variant_score  (logit difference)
2
3其中：
4  ref_score    = logits · one_hot(reference_aa)   — 參考胺基酸的 logit
5  variant_score = logits · one_hot(alternate_aa)  — 替換胺基酸的 logit
6  
7  logit_diff > 0 → 替換降低適應性 → 較可能致病
8  logit_diff < 0 → 替換不影響或提升適應性 → 較可能良性

1# cluster_bias_mask 確保前兩列永遠被保留：
2# 第 0 列 = 目標序列 (target sequence)
3# 第 1 列 = 帶 mask 的變異序列 (masked variant row)
4cluster_bias_mask = batch['cluster_bias_mask']
5logits += cluster_bias_mask * 1e6  # 確保被選中

1# Ubuntu/Debian
2sudo apt update
3sudo apt install python3.11-venv aria2 hmmer
4
5# HMMER Suite 提供 jackhmmer 二進位檔
6# aria2 用於高速下載基因資料庫

 1git clone https://github.com/google-deepmind/alphamissense.git
 2cd alphamissense
 3
 4# 建立虛擬環境
 5python3 -m venv ./venv
 6source venv/bin/activate
 7
 8# 安裝 Python 依賴
 9pip install -r requirements.txt
10pip install -e .

1venv/bin/python test/test_installation.py

 1absl-py==1.0.0          # Google 的 Python 基礎函式庫
 2biopython==1.79         # 生物序列解析
 3dm-haiku==0.0.10        # DeepMind 的 JAX 神經網路框架
 4dm-tree==0.1.8          # 巢狀資料結構操作
 5immutabledict==2.0.0    # 不可變字典
 6jax==0.4.14             # Google 的數值計算框架
 7jaxlib==0.4.14          # JAX 後端
 8ml-collections==0.1.0   # ML 配置管理
 9numpy==1.24.3           # 數值運算
10scipy==1.11.1           # 科學運算
11typing_extensions==4.7.1 # 型別提示擴充

1# 使用 uv 替代 pip（更快、更安全）
2uv venv .venv --python 3.11
3source .venv/bin/activate
4uv pip install -r requirements.txt
5uv pip install -e .

1# 預計算資料託管在 Google Cloud Storage
2# 瀏覽器存取：
3# https://console.cloud.google.com/storage/browser/dm_alphamissense
4
5# 使用 gsutil 下載（需安裝 Google Cloud SDK）
6gsutil -m cp -r gs://dm_alphamissense/ ./alphamissense_predictions/

 1# 1. 安裝 VEP
 2# https://www.ensembl.org/info/docs/tools/vep/script/vep_download.html
 3
 4# 2. 下載 AlphaMissense VEP plugin
 5# https://www.ensembl.org/info/docs/tools/vep/script/vep_plugins.html
 6
 7# 3. 執行 VEP + AlphaMissense
 8vep --input_file variants.vcf \
 9    --plugin AlphaMissense,file=AlphaMissense_hg38.tsv.gz \
10    --output_file annotated_variants.vcf

 1from alphamissense.data import pipeline_missense
 2
 3# 建立資料管線
 4pipeline = pipeline_missense.DataPipeline(
 5    jackhmmer_binary_path='/usr/bin/jackhmmer',
 6    protein_sequence_file='sequences.fasta',           # 目標蛋白質 FASTA
 7    uniref90_database_path='databases/uniref90/uniref90.fasta',
 8    mgnify_database_path='databases/mgnify/mgy_clusters_2022_05.fa',
 9    small_bfd_database_path='databases/small_bfd/bfd-first_non_consensus_sequences.fasta',
10)

1# 處理一個 missense variant
2sample = pipeline.process(
3    protein_id='Q08708',        # FASTA 中的序列 ID
4    reference_aa='A',           # 參考胺基酸（大寫單字母）
5    alternate_aa='C',           # 替換胺基酸
6    position=3,                 # 位置（1-based！）
7    msa_output_dir='./msa_cache',  # MSA 結果快取目錄
8)
9# sample 是 FeatureDict (dict[str, np.ndarray])

 1import jax
 2import jax.numpy as jnp
 3from alphamissense.model import config
 4from alphamissense.model import modules_missense
 5
 6# 建立模型
 7cfg = config.model_config()
 8model_runner = modules_missense.RunModel(cfg, params=None)
 9
10# 轉為 JAX 陣列
11sample_jax = jax.tree_map(jnp.asarray, sample)
12
13# 推論（注意：params=None 時使用隨機初始化的權重，僅供測試）
14output = model_runner.predict(sample_jax, random_seed=0)
15
16# 取得致病性分數
17pathogenicity_score = output['logit_diff']['variant_pathogenicity']
18print(f"致病性分數: {pathogenicity_score}")

1from alphamissense.model import config
2
3# 預設配置
4cfg_default = config.model_config()
5
6# model_3 配置：啟用 Extra MSA Stack
7cfg_model3 = config.model_config('model_3')
8# 差異：enable_extra_msa_stack = True（預設為 False）

 1# Spatial cropping 會從 Google Cloud Storage 取得結構
 2# 存取路徑格式：
 3AFDB_BUCKET = 'gs://public-datasets-deepmind-alphafold-v4'
 4# 需要 gsutil 並有網路存取權限
 5
 6# DataPipeline 建構時設定 crop_size 和 spatial_crop_size
 7pipeline = pipeline_missense.DataPipeline(
 8    jackhmmer_binary_path='/usr/bin/jackhmmer',
 9    protein_sequence_file='sequences.fasta',
10    uniref90_database_path='...',
11    mgnify_database_path='...',
12    small_bfd_database_path='...',
13    crop_size=512,           # 裁切後的殘基數
14    msa_crop_size=256,       # 裁切後的 MSA 序列數
15    use_spatial_cropping=True,  # 啟用空間裁切
16)

1def clipped_sigmoid_cross_entropy(
2    logits, labels,
3    clip_negative_at_logit=0.0,    # 負樣本的 clip 閾值
4    clip_positive_at_logit=-1.0,   # 正樣本的 clip 閾值
5):
6    # 在 logit 空間中 clip，避免過度自信
7    # 這讓模型對邊界案例保持適當的不確定性

 1import pandas as pd
 2from alphamissense.data import pipeline_missense
 3
 4# 假設有一組變異清單
 5variants = pd.DataFrame({
 6    'protein_id': ['Q08708', 'Q08708', 'P04637'],
 7    'position': [3, 15, 248],
 8    'ref_aa': ['A', 'G', 'R'],
 9    'alt_aa': ['C', 'D', 'W'],
10})
11
12pipeline = pipeline_missense.DataPipeline(...)
13
14# 批次處理（同一蛋白質的 MSA 可共用快取）
15results = []
16for _, row in variants.iterrows():
17    sample = pipeline.process(
18        protein_id=row['protein_id'],
19        reference_aa=row['ref_aa'],
20        alternate_aa=row['alt_aa'],
21        position=row['position'],
22        msa_output_dir=f'./msa_cache/{row["protein_id"]}',
23    )
24    results.append(sample)

 1import pandas as pd
 2
 3# 下載後讀取預計算資料
 4# 檔案格式為 TSV，包含所有 ~71M missense variants
 5predictions = pd.read_csv(
 6    'AlphaMissense_aa_substitutions.tsv.gz',
 7    sep='\t',
 8    comment='#',
 9)
10
11# 欄位說明：
12# CHROM, POS, REF, ALT           — 基因體座標
13# genome                          — 基因體版本 (hg38)
14# uniprot_id                      — UniProt ID
15# transcript_id                   — Ensembl transcript ID
16# protein_variant                 — 蛋白質變異 (e.g. A3C)
17# am_pathogenicity                — 致病性分數
18# am_class                        — 分類 (likely_pathogenic / likely_benign / ambiguous)
19
20# 查詢特定蛋白質的所有變異
21tp53_variants = predictions[predictions['uniprot_id'] == 'P04637']
22print(f"TP53 共有 {len(tp53_variants)} 個可能的 missense variants")
23
24# 篩選 likely pathogenic
25tp53_pathogenic = tp53_variants[tp53_variants['am_class'] == 'likely_pathogenic']
26print(f"其中 {len(tp53_pathogenic)} 個被預測為 likely pathogenic")

1# 在現有 VEP 流程中加入 AlphaMissense plugin
2vep --input_file patient_variants.vcf \
3    --plugin AlphaMissense,file=AlphaMissense_hg38.tsv.gz \
4    --plugin CADD,snv=whole_genome_SNVs.tsv.gz \
5    --output_file annotated.vcf \
6    --vcf

 1import pandas as pd
 2
 3class AlphaMissenseLookup:
 4    """AlphaMissense 預計算分數查詢器"""
 5    
 6    def __init__(self, predictions_path: str):
 7        self.predictions = pd.read_csv(
 8            predictions_path, sep='\t', comment='#',
 9            usecols=['uniprot_id', 'protein_variant', 
10                     'am_pathogenicity', 'am_class'],
11        )
12        # 建立索引加速查詢
13        self.predictions.set_index(
14            ['uniprot_id', 'protein_variant'], inplace=True
15        )
16    
17    def query(self, uniprot_id: str, variant: str):
18        """查詢單一變異的致病性分數
19        
20        Args:
21            uniprot_id: UniProt ID (e.g. 'P04637')
22            variant: 變異描述 (e.g. 'R248W')
23        
24        Returns:
25            dict with 'score' and 'classification'
26        """
27        try:
28            row = self.predictions.loc[(uniprot_id, variant)]
29            return {
30                'score': row['am_pathogenicity'],
31                'classification': row['am_class'],
32            }
33        except KeyError:
34            return {'score': None, 'classification': 'not_found'}

 1def consensus_pathogenicity(
 2    alphamissense_score: float,
 3    cadd_phred: float,
 4    revel_score: float,
 5    weights: dict = None,
 6) -> dict:
 7    """多工具共識致病性評分
 8    
 9    Args:
10        alphamissense_score: AM 分數 (0-1)
11        cadd_phred: CADD Phred 分數 (0-99)
12        revel_score: REVEL 分數 (0-1)
13        weights: 各工具權重
14    
15    Returns:
16        共識結果 dict
17    """
18    if weights is None:
19        weights = {'am': 0.4, 'cadd': 0.3, 'revel': 0.3}
20    
21    # 正規化 CADD 到 0-1 範圍
22    cadd_normalized = min(cadd_phred / 40.0, 1.0)
23    
24    consensus = (
25        weights['am'] * alphamissense_score +
26        weights['cadd'] * cadd_normalized +
27        weights['revel'] * revel_score
28    )
29    
30    return {
31        'consensus_score': consensus,
32        'am_class': _classify_am(alphamissense_score),
33        'tools_agree': _check_agreement(
34            alphamissense_score, cadd_phred, revel_score
35        ),
36    }

1@article{AlphaMissense2023,
2  author  = {Jun Cheng and Guido Novati and Joshua Pan and ...},
3  journal = {Science},
4  title   = {Accurate proteome-wide missense variant effect 
5             prediction with AlphaMissense},
6  year    = {2023},
7  doi     = {10.1126/science.adg7492},
8}

1position=3,  # Integer, note that the position is 1-based!

1# 常見問題：JAX 與 CUDA 版本不匹配
2# 解決方式：安裝與你的 CUDA 版本對應的 jaxlib
3pip install jax[cuda12_pip] -f https://storage.googleapis.com/jax-releases/jax_cuda_releases.html
4
5# 常見問題：NumPy 2.x 不相容
6# 解決方式：固定 NumPy 版本
7pip install "numpy<2.0"