alterlab-alphafold-db

AlphaFold Database

概述

AlphaFold DB 是由 Google DeepMind 和 EMBL-EBI 维护的 AI 预测蛋白质 3D 结构公共仓库。第 6 版（2025 年 10 月，与 UniProt 2025_03 同步）包含约 2.41 亿个预测结果，包括约 4 万种异构体及输入的 MSA；自 2026 年 3 月起，还提供预计算的同源二聚体和异源二聚体复合物预测。获取带置信度指标的结构预测，下载坐标文件，检索批量数据集，并将预测结果集成到计算工作流中。

何时使用此技能

在以下场景中处理 AI 预测的蛋白质结构时，应使用此技能：

• 根据 UniProt ID 或蛋白质名称检索蛋白质结构预测
• 下载用于结构分析的 PDB/mmCIF 坐标文件
• 分析预测置信度指标（pLDDT、PAE），评估可靠性
• 获取蛋白质组批量数据集（EMBL-EBI FTP 或 Google Cloud Platform）
• 将预测结构与实验数据进行比较
• 开展基于结构的药物发现或蛋白质工程
• 为缺少实验结构的蛋白质构建结构模型
• 将 AlphaFold 预测结果集成到计算流程中

不适用的场景

场景	改用
根据 PDB ID 获取实验测定的 X-ray / cryo-EM / NMR 结构	alterlab-pdb
自行折叠新序列或突变序列，或自定义蛋白质–蛋白质复合物（ColabFold / AF2-Multimer）	alterlab-alphafold
蛋白质–配体或蛋白质–核酸协同折叠	alterlab-boltz
仅查询蛋白质序列、功能注释或登录号映射	alterlab-uniprot

核心功能

下文各项功能均提供可直接复制粘贴运行的 Python 示例，详见 references/code_examples.md。需要可运行代码时，请加载该文件；此处的摘要 介绍了路由方式和关键决策。

1. 搜索和检索预测结果

按优先顺序提供三种入口：

• Biopython（推荐）：Bio.PDB.alphafold_db.get_predictions(accession)、 download_cif_for(...)、get_structural_models_for(...) — 最简单的方式。
• 直接调用 REST：GET https://alphafold.ebi.ac.uk/api/prediction/{uniprot_id}。 响应是该登录号对应的所有模型的列表 — 包括标准 序列和异构体（P00520-2、……），以及部分条目中的第三方 模型 — 因此应选择 uniprotAccession 与查询值相符的记录， 不要直接使用 [0]。模型 ID 是 modelEntityId（例如 AF-P00520-F1）；旧名称 entryId 已于公布的 2026-06-25 日期停用，因此 不要在新代码中使用它。默认不包含复合物模型，除非传入 ?include_complexes=true（或调用 /api/complex/{id}）。
• 仅有基因名称或 PDB ID 时，先查找登录号 — 使用 UniProt ID 映射任务 API （code_examples.md §1 中的 get_uniprot_ids 辅助函数；有效数据库名称见 https://rest.uniprot.org/configure/idmapping/fields）。

2. 下载结构文件

/prediction 响应中包含带版本号的文件 URL — 请使用这些 URL，不要 自行拼接 _v{N} 后缀。 数据库版本会更新（当前为 v6），旧的 _v4 文件 URL 现在会返回 404：

• cifUrl / pdbUrl / bcifUrl — 原子坐标（mmCIF / PDB / 二进制 CIF）。
• plddtDocUrl — 每个残基的 pLDDT 分数（0-100）。
• paeDocUrl — PAE 矩阵。

下载示例（从 API 获取 URL 并写入字节数据）见 code_examples.md §2。

3. 使用置信度指标

• pLDDT：从 plddtDocUrl 获取，读取 confidence['confidenceScore']（键： residueNumber、confidenceScore、confidenceCategory）；阈值见下文 “置信度解读指南”。
• PAE：从 paeDocUrl 获取。该端点返回一个仅含单个对象的 JSON 数组，因此需先使用 [0]，再访问键 （pae[0]['predicted_aligned_error']）。可视化示例见 code_examples.md §3。

4. 批量数据访问（FTP v6 或 Google Cloud v4）

• 模式生物、全球健康蛋白质组、Swiss-Prot（v6）： 每个蛋白质组对应一个 tar 文件，位于 https://ftp.ebi.ac.uk/pub/databases/alphafold/latest/ （例如，UP000005640_9606_HUMAN_v6.tar；索引文件是上级目录中的 download_metadata.json）。置信度较低的复合物预测仅支持批量下载，位于 .../alphafold/collaborations/nvda/ 下。
• 任何分类群（v4）： 使用 gsutil 访问 gs://public-datasets-deepmind-alphafold-v4/proteomes/，或查询 bigquery-public-data.deepmind_alphafold.metadata，按生物或置信度筛选。物种下载辅助工具会验证分类 ID，并使用列表形式的 subprocess.run（绝不使用 shell=True）。

参见 code_examples.md §4 和 references/api_reference.md（批量下载）。

5. 解析和分析结构

使用 Bio.PDB.MMCIFParser 解析 mmCIF；pLDDT 存储在 B 因子列中（residue['CA'].get_bfactor()）。接触图和 B 因子提取示例见 code_examples.md §5。

6. 批量处理多个蛋白质

循环遍历登录号 → 获取预测 → 统计置信度 → 汇总为 DataFrame。完整示例见 code_examples.md §6。

安装和设置

uv pip install biopython requests          # core: structure access + API
uv pip install numpy matplotlib pandas scipy  # analysis + PAE plots
uv pip install google-cloud-bigquery gsutil   # optional: bulk GCP access

3D-Beacons 替代方案： 也可以通过 3D-Beacons 联邦 API 访问 AlphaFold （https://www.ebi.ac.uk/pdbe/pdbe-kb/3dbeacons/api/uniprot/summary/{id}.json）， 筛选 structures[i]['summary']['provider'] == 'AlphaFold DB' 的条目。示例见 code_examples.md（3D-Beacons 部分）。

常见用例

结构蛋白质组学

• 下载完整蛋白质组预测结果以进行分析
• 识别蛋白质中的高置信度结构区域
• 将预测结构与实验数据进行比较
• 为蛋白质家族构建结构模型

药物发现

• 获取用于对接研究的靶蛋白结构
• 分析结合位点构象
• 在预测结构中识别可成药口袋
• 比较同源蛋白之间的结构

蛋白质工程

• 使用 pLDDT 识别稳定/不稳定区域
• 在高置信度区域设计突变
• 使用 PAE 分析结构域架构
• 对蛋白质变体和突变进行建模

进化研究

• 比较不同物种间直系同源蛋白的结构
• 分析结构特征的保守性
• 研究结构域演化模式
• 识别具有重要功能的区域

关键概念

UniProt 登录号： 蛋白质的主要标识符（例如，“P00520”）。查询 AlphaFold DB 时必需。

AlphaFold 模型 ID（modelEntityId）： DeepMind 单体模型的格式为 AF-[UniProt accession]-F[fragment number]（例如，“AF-P00520-F1”；异构体的格式类似于 “AF-P00520-2-F1”）。复合物和第三方模型使用不透明的数字 ID（例如，“AF-0000000365776990”）；/api/prediction/{id} 接受这两种格式。

pLDDT（预测局部距离差异测试）： 逐残基置信度指标（0-100）。数值越高，表示预测置信度越高。

PAE（预测对齐误差）： 表示残基对之间相对位置置信度的矩阵。较低的数值（<5 Å）表示相对位置较为可靠。

数据库版本： REST API 和 FTP latest/ 归档提供 v6（响应中报告 latestVersion / allVersions）；GCS/BigQuery 数据集则滞后于 v4。文件 URL 中包含版本后缀（例如，model_v6.cif，较新的第三方模型则从 _v1 开始）——请从预测响应中读取这些 URL，而不要对后缀进行硬编码。

片段编号： 大型蛋白质可能会拆分为多个片段。片段编号会显示在 AlphaFold ID 中（例如，F1、F2）。

置信度解读指南

pLDDT 阈值：

• >90：置信度极高，适合进行详细分析
• 70-90：置信度高，主链结构通常可靠
• 50-70：置信度低，使用时需谨慎，区域可能具有柔性
• <50：置信度极低，可能无序或不可靠

PAE 指南：

• <5 Å：对结构域之间的相对位置有较高置信度
• 5-10 Å：对排列方式有中等置信度
• >15 Å：相对位置不确定，结构域可能具有活动性

资源

references/code_examples.md

针对每项核心能力编写的实用 Python 示例，可直接复制粘贴使用：获取预测结果（Biopython / REST / UniProt 映射）、下载文件、分析 pLDDT + PAE、通过 GCP/BigQuery 批量访问、解析 mmCIF、批量处理，以及使用 3D-Beacons 替代方案。

需要可运行的代码时，请加载此文件。

references/api_reference.md

全面的 API 文档，涵盖：

• 完整的 REST API 端点规范
• 文件格式详情和数据架构
• Google Cloud 数据集结构和访问模式
• 高级查询示例和批处理策略
• 速率限制、缓存和最佳实践
• 常见问题排查

详细了解 API、批量下载策略或处理大型数据集时，请查阅此参考文档。

重要说明

数据使用和署名

• AlphaFold DB 采用 CC-BY-4.0 许可，可免费使用
• 引用：Jumper et al.（2021）Nature，以及你所使用版本对应的 AFDB 论文：v4 对应 Varadi et al.（2024）NAR，v6 对应 Bertoni et al.（2026）NAR（doi:10.1093/nar/gkaf1226）
• 预测结果是计算模型，而非实验结构
• 在下游分析前，务必评估置信度指标

版本管理

• REST API 和 FTP latest/ 提供 v6（latestVersion）；GCS/BigQuery 批量数据集仍为 v4
• 从 /prediction 响应中读取文件 URL，切勿硬编码 _v{N} 后缀
• 旧的 _v4 文件 URL 现在会返回 404；已被取代的版本会从 /files 中移除（旧版本仍保留在 FTP 站点的 v1/–v6/ 下）
• v6 字段重命名（entryId→modelEntityId、uniprotStart/End→sequenceStart/End、uniprotSequence→sequence、isReviewed→isUniProtReviewed）已于 2026-06-25 到期；paeImageUrl 计划移除，请改用 paeDocUrl
• 记录下载结果对应的版本

数据质量注意事项

• pLDDT 高并不保证功能准确
• 低置信度区域在体内可能无序
• PAE 表示结构域的相对置信度，而非绝对位置
• 预测结果不包含配体、翻译后修饰和辅因子
• 默认的 /prediction 结果为单链。预计算的复合物（约 1.7M 个高置信度同源二聚体和约 80k 个异源二聚体，于 2026 年 3 月至 5 月期间加入）仅在设置 include_complexes=true 或调用 /api/complex/{id} 时返回；评估时除了 pLDDT，还应参考界面指标（ipTM、pDockQ）。对于数据库中没有的复合物，请自行折叠（alterlab-alphafold）

性能提示

• 简单的单蛋白访问请使用 Biopython
• 批量下载请使用 FTP 蛋白质组 tar 文件或 Google Cloud（速度远快于逐个下载文件）
• 将下载的文件缓存在本地，避免重复下载
• BigQuery 免费层：每月可处理 1 TB 数据
• 大规模下载时，请考虑网络带宽

其他资源

• AlphaFold DB 网站： https://alphafold.ebi.ac.uk/
• API 文档： https://alphafold.ebi.ac.uk/api-docs（机器可读规范：https://alphafold.ebi.ac.uk/api/openapi.json）
• 发行说明 / FTP 更新日志： https://www.ebi.ac.uk/pdbe/news/alphafold-database-release-notes, https://ftp.ebi.ac.uk/pub/databases/alphafold/CHANGELOG.txt
• Google Cloud 数据集： https://cloud.google.com/blog/products/ai-machine-learning/alphafold-protein-structure-database
• 3D-Beacons API： https://www.ebi.ac.uk/pdbe/pdbe-kb/3dbeacons/
• AlphaFold 论文：
  • Nature（2021）：https://doi.org/10.1038/s41586-021-03819-2
  • Nucleic Acids Research（2024）：https://doi.org/10.1093/nar/gkad1011
• Biopython 文档： https://biopython.org/docs/dev/api/Bio.PDB.alphafold_db.html
• GitHub 仓库： https://github.com/google-deepmind/alphafold

脚本

scripts/query_alphafold.py — AlphaFold REST API 的可运行辅助脚本（无需密钥）：

python scripts/query_alphafold.py prediction P00520
python scripts/query_alphafold.py confidence P00520 --summary
python scripts/query_alphafold.py download P00520 --fmt cif -o ./structures