1ablang/
 2├── __init__.py          # 匯出 ABtokenizer, AbLang, AbRep, AbHead, pretrained
 3├── tokenizers.py        # ABtokenizer — AA 字元 ↔ token ID 雙向轉換
 4├── embedding.py         # AbEmbeddings — AA 嵌入 + 位置嵌入 + LayerNorm + Dropout
 5├── encoderblocks.py     # EncoderBlocks → EncoderBlock → MHA + IntermediateLayer
 6├── fairseq_mha.py       # MultiheadAttention（改自 fairseq，支援逐 head 權重輸出）
 7├── extra_fns.py         # 啟動函數對照表 ACT2FN（GELU 等）
 8├── model.py             # AbLang = AbRep + AbHead；AbRep = Embeddings + Encoder
 9├── pretrained.py        # pretrained class — 模型下載、推論介面、四種模式
10└── model-weights-*/     # 自動下載的預訓練權重（heavy / light 各一組）

1# 建議使用 uv 建立獨立虛擬環境
2uv venv ablang-env --python 3.10
3source ablang-env/bin/activate
4
5# 從 PyPI 安裝
6uv pip install ablang
7
8# 或從 GitHub 安裝最新版
9uv pip install git+https://github.com/oxpig/AbLang.git

1requests        # 模型權重下載
2torch>=1.6      # PyTorch 後端
3numpy           # 數值計算
4pandas          # 資料處理（rescoding align 模式使用）
5numba           # JIT 加速（spread sequence 生成）

1# 透過 bioconda 安裝
2conda install -c bioconda anarci
3
4# 或從 GitHub 安裝
5uv pip install git+https://github.com/oxpig/ANARCI.git

1import ablang
2
3# 使用 GPU（需安裝 CUDA 版 PyTorch）
4heavy_ablang = ablang.pretrained("heavy", device='cuda')
5heavy_ablang.freeze()

 1import ablang
 2
 3# ---- 初始化重鏈模型 ----
 4heavy_ablang = ablang.pretrained("heavy")
 5heavy_ablang.freeze()  # 切換為推論模式 (eval mode)
 6
 7# ---- 範例序列 ----
 8# * 代表遮蔽位置 (masked position)，即缺失/未知的殘基
 9seqs = [
10    # 完整序列（作為對照）
11    'EVQLVESGPGLVQPGKSLRLSCVASGFTFSGYGMHWVRQAPGKGLEWIALIIYDESNKYYADSVKGRFTISRDNSKNTLYLQMSSLRAEDTAVFYCAKVKFYDPTAPNDYWGQGTLVTVSS',
12    # 有零星缺失 + 末端大段缺失的序列
13    '*************PGKSLRLSCVASGFTFSGYGMHWVRQAPGKGLEWIALIIYDESNK*YADSVKGRFTISRDNSKNTLYLQMSSLRAEDTAVFYCAKVKFYDPTAPNDYWGQGTL*****',
14]
15
16# ---- 基本修復（已知缺失位置）----
17restored = heavy_ablang(seqs, mode='restore')
18print("基本修復結果：")
19for i, seq in enumerate(restored):
20    print(f"  序列 {i+1}: {seq[:30]}...")
21
22# ---- 對齊修復（末端缺失長度未知）----
23seqs_unknown_end = [
24    'EVQLVESGPGLVQPGKSLRLSCVASGFTFSGYGMHWVRQAPGKGLEWIALIIYDESNKYYADSVKGRFTISRDNSKNTLYLQMSSLRAEDTAVFYCAKVKFYDPTAPNDYWGQGTLVTVSS',
25    # 前後截斷、缺失長度不明
26    'PGKSLRLSCVASGFTFSGYGMHWVRQAPGKGLEWIALIIYDESNK*YADSVKGRFTISRDNSKNTLYLQMSSLRAEDTAVFYCAKVKFYDPTAPNDYWGQGTL',
27]
28
29restored_aligned = heavy_ablang(seqs_unknown_end, mode='restore', align=True)
30print("\n對齊修復結果（自動推斷缺失長度）：")
31for i, seq in enumerate(restored_aligned):
32    print(f"  序列 {i+1}: {seq[:30]}...")

1基本修復結果：
2  序列 1: EVQLVESGPGLVQPGKSLRLSCVASGFTFS...
3  序列 2: QVQLVESGGGVVQPGKSLRLSCVASGFTFS...
4
5對齊修復結果（自動推斷缺失長度）：
6  序列 1: EVQLVESGPGLVQPGKSLRLSCVASGFTFS...
7  序列 2: QVQLVESGGGVVQPGKSLRLSCVASGFTFS...

 1import ablang
 2import numpy as np
 3from sklearn.ensemble import RandomForestClassifier
 4from sklearn.model_selection import cross_val_score
 5
 6# ---- 初始化 ----
 7heavy_ablang = ablang.pretrained("heavy")
 8heavy_ablang.freeze()
 9
10# ---- 抗體序列資料（實際應用中從資料庫讀取）----
11antibody_sequences = [
12    'EVQLVESGPGLVQPGKSLRLSCVASGFTFSGYGMHWVRQAPGKGLEWIALIIYDESNKYYADSVKGRFTISRDNSKNTLYLQMSSLRAEDTAVFYCAKVKFYDPTAPNDYWGQGTLVTVSS',
13    'QVQLVQSGAEVKKPGSSVKVSCKASGGTFSSYAISWVRQAPGQGLEWMGGIIPIFGTANYAQKFQGRVTITADESTSTAYMELSSLRSEDTAVYYCARRGYSGSFYYYAMDVWGQGTTVTVSS',
14    'EVQLLESGGGLVQPGGSLRLSCAASGFTFSSYAMSWVRQAPGKGLEWVSAISGSGGSTYYADSVKGRFTISRDNSKNTLYLQMNSLRAEDTAVYYCAKYYDILTGYYPFDYWGQGTLVTVSS',
15    # ... 更多序列
16]
17# 假設的結合活性標籤（0=不結合, 1=結合）
18labels = [1, 0, 1]  # 範例標籤
19
20# ---- 方法 A: 序列層級編碼 → 直接用於分類 ----
21seq_embeddings = heavy_ablang(antibody_sequences, mode='seqcoding')
22print(f"序列編碼維度: {seq_embeddings.shape}")
23# → (3, 768)  —— 每條序列一個固定長度的向量
24
25# 使用 sklearn 進行分類（範例）
26# clf = RandomForestClassifier(n_estimators=100, random_state=42)
27# scores = cross_val_score(clf, seq_embeddings, labels, cv=3)
28
29# ---- 方法 B: 殘基層級編碼 → 用於位置特異性預測 ----
30res_embeddings = heavy_ablang(antibody_sequences, mode='rescoding')
31print(f"殘基編碼：每條序列為 list，第一條維度 = {res_embeddings[0].shape}")
32# → (seq_len, 768)  —— 每個殘基一個向量
33
34# ---- 方法 C: 似然度矩陣 → 突變掃描 ----
35likelihoods = heavy_ablang(antibody_sequences, mode='likelihood')
36print(f"似然度矩陣維度: {likelihoods.shape}")
37# → (3, max_len+2, 20)  —— 每個位置 20 種 AA 的機率
38
39# 找出特定位置最可能的突變
40position = 50  # 查看第 50 個殘基
41aa_order = 'ARNDCQEGHILKMFPSTWYV'  # AbLang 字彙順序
42top3_idx = np.argsort(likelihoods[0, position+1, :])[::-1][:3]  # +1 for start token
43print(f"\n位置 {position} 最可能的 3 個殘基:")
44for idx in top3_idx:
45    print(f"  {aa_order[idx]}: {likelihoods[0, position+1, idx]:.4f}")

 1import ablang
 2import numpy as np
 3import pandas as pd
 4
 5# ---- 初始化（可指定 CPU 核心數加速 ANARCI）----
 6heavy_ablang = ablang.pretrained("heavy", ncpu=8)
 7heavy_ablang.freeze()
 8
 9# ---- 從 OAS 格式檔案讀取序列（模擬）----
10# 實際場景：從 OAS bulk download 或內部 NGS pipeline 輸出讀取
11repertoire_df = pd.DataFrame({
12    'sequence_heavy': [
13        'EVQLVESGPGLVQPGKSLRLSCVASGFTFSGYGMHWVRQAPGKGLEWIALIIYDESNKYYADSVKGRFTISRDNSKNTLYLQMSSLRAEDTAVFYCAKVKFYDPTAPNDYWGQGTLVTVSS',
14        '*************PGKSLRLSCVASGFTFSGYGMHWVRQAPGKGLEWIALIIYDESNKYYADSVKGRFTISRDNSKNTLYLQMSSLRAEDTAVFYCAKVKFYDPTAPNDYWGQGTLVTVSS',
15        'PGKSLRLSCVASGFTFSGYGMHWVRQAPGKGLEWIALIIYDESNK*YADSVKGRFTISRDNSKNTLYLQMSSLRAEDTAVFYCAKVKFYDPTAPNDYWGQGTL',
16    ],
17    'has_missing': [False, True, True],
18    'v_gene': ['IGHV1-2', 'IGHV3-30', 'IGHV1-69'],
19})
20
21print(f"Repertoire 大小: {len(repertoire_df)} 條序列")
22print(f"缺失序列比例: {repertoire_df['has_missing'].mean():.1%}")
23
24# ---- Step 1: 修復所有缺失序列 ----
25seqs_to_restore = repertoire_df['sequence_heavy'].tolist()
26
27# splitSize 控制批次大小，避免 OOM
28restored_seqs = heavy_ablang(
29    seqs_to_restore,
30    mode='restore',
31    align=True,      # 處理末端未知長度缺失
32    splitSize=50      # 每批 50 條
33)
34
35repertoire_df['restored_heavy'] = restored_seqs
36print("\n修復完成！")
37print(repertoire_df[['v_gene', 'has_missing', 'restored_heavy']].head())
38
39# ---- Step 2: 產生序列嵌入用於聚類 ----
40embeddings = heavy_ablang(
41    repertoire_df['restored_heavy'].tolist(),
42    mode='seqcoding'
43)
44
45print(f"\n嵌入矩陣維度: {embeddings.shape}")
46# 後續可接 UMAP / t-SNE 降維 + HDBSCAN 聚類
47# 用於 clonotype clustering / 功能性分群
48
49# ---- Step 3: CDR3 區域突變景觀 (Mutational Landscape) ----
50# 利用 likelihood 模式做 in-silico 飽和突變掃描
51target_seq = repertoire_df['restored_heavy'].iloc[0]
52likelihoods = heavy_ablang([target_seq], mode='likelihood')
53
54# 計算每個位置的 entropy（熵值越高 = 可容忍更多突變）
55from scipy.stats import entropy
56
57position_entropy = []
58for pos in range(1, len(target_seq) + 1):  # skip start token
59    probs = likelihoods[0, pos, :]
60    probs_normalized = np.exp(probs) / np.exp(probs).sum()  # softmax
61    position_entropy.append(entropy(probs_normalized))
62
63print(f"\n位置 entropy 統計：")
64print(f"  平均: {np.mean(position_entropy):.3f}")
65print(f"  最低（最保守）: {np.min(position_entropy):.3f} at position {np.argmin(position_entropy)+1}")
66print(f"  最高（最可變）: {np.max(position_entropy):.3f} at position {np.argmax(position_entropy)+1}")

1NGS 定序 → 序列組裝 → [AbLang 修復缺失] → ANARCI 編號 → 功能篩選 →
2  ├── 親和力成熟 (Affinity Maturation): [AbLang likelihood] 引導突變設計
3  ├── 可開發性評估 (Developability): [AbLang seqcoding] 作為特徵輸入
4  ├── 結構建模: [AbLang 完整序列] → ColabFold/AlphaFold2
5  └── 抗體設計: [AbLang rescoding] + DiffAb 3D 設計

1AbLang 序列修復/生成候選 → ANARCI IMGT 編號 → DiffAb CDR 結構設計 → 結合 AbLang 嵌入評分

1缺失序列 → AbLang restore → 完整序列 → ColabFold multimer → 抗體-抗原複合體結構

1scRNA-seq → cellranger → BCR 序列 (常有缺失) → AbLang restore →
2  ├── AbLang seqcoding → 與 scGPT cell embedding 整合 → 功能性 B 細胞分群
3  └── AbLang likelihood → 體細胞超突變 (SHM) 熱點分析