JASPAR 转录因子结合位点数据库 API 查询实战指南：在 scientific-agent-skills 中实现可复现的 motif 检索

JASPAR 是面向转录因子（TF）结合位点研究的权威开放数据库，收录了大量物种的 TF 结合谱（binding profiles / motifs）。本文以 scientific-agent-skills 仓库中 database-lookup 技能所封装的 JASPAR 参考文档 为核心，系统讲解其 REST API 的地址、鉴权方式、核心端点、过滤参数与返回结构，并结合仓库中的检索契约（retrieval contract）、分页与出处记录规范，给出可直接复制运行的 curl 请求与下游分析衔接方案。读完本文，你将能够在科学 Agent 工作流中快速定位任意转录因子的结合谱、按物种与集合做批量筛选，并把检索结果安全地送入 motif 比对或基因组注释等下游分析。

一、JASPAR 是什么，为什么需要单独一份 API 参考

在基因调控研究中，"某个转录因子结合在哪些序列基序上"是频率极高的查询需求。JASPAR 通过维护每个转录因子的位置频率矩阵（position frequency matrix, PFM）为这类问题提供了权威的机器可读答案。它被 database-lookup 技能收录于 Biology & Genomics 分组，与 ENCODE、ENdb 等调控资源互补：ENCODE 提供实验测定数据（如 CTCF 的 ChIP-seq），而 JASPAR 提供经人工审编的 TF 结合基序谱（见 database-lookup 技能可用数据库清单 中 JASPAR 一行 "TF binding profiles/motifs"）。

在 database-lookup 技能的整体框架下，JASPAR 参考文件遵循统一的单数据库自描述格式：包含 base URL、鉴权、关键端点、过滤参数、示例调用与限流说明。调用前应先阅读 检索契约文件，明确目标实体（TF）、接受的标识符（matrix ID / tax ID / 名称）、物种约束、过滤条件与期望输出，再进行有界请求。

二、Base URL 与鉴权方式

JASPAR REST API 的服务器地址与鉴权规则非常简单：

• Base URL：https://jaspar.elixir.no/api/v1/
• 鉴权：无需任何 API Key，公开匿名访问即可。

这使 JASPAR 非常适合作为 Agent 优先选择的免密钥数据库。与之相对，仓库中大量其他数据库（如 FRED、NCBI、DisGeNET 等）需要注册密钥，参见 SKILL.md 中"需 API Key 的数据库"表。JASPAR 属于"无鉴权即可用"的一类，检索时无需维护 .env 凭据，也无需在 provenance 中处理鉴权状态。

三、核心端点总览

JASPAR API v1 以 REST 资源化方式组织。参考文件用一张表覆盖了最常用端点：

端点	说明
/matrix/	列出全部 TF 结合谱
/matrix/{matrix_id}/	获取指定结合谱（例如 CTCF 使用 MA0139.1）
/matrix/?tax_id={id}&collection=CORE	按物种 + 集合过滤
/matrix/{id}/?format=jaspar	以 JASPAR 格式返回结合谱
/matrix/{id}/?format=meme	以 MEME 格式返回结合谱
/matrix/{id}/?format=transfac	以 TRANSFAC 格式返回结合谱
/taxon/	列出分类学分组
/collection/	列出集合（CORE、CNE 等）

要点解读：

1. matrix_id 是检索的关键标识符。JASPAR 的 ID 形如 MA0139.1，MA 前缀 + 数字编号 + 版本后缀。以 CTCF 为例，MA0139.1 即其代表性结合谱。在做"查询某 TF 的结合基序"类任务时，应先确认其 matrix ID（可通过 /matrix/?name=... 名称检索获得）。

2. format 参数控制返回的序列格式，是 JASPAR 与下游生信工具衔接的关键：jaspar、meme、transfac 三种格式分别对应不同软件生态的 motif 表示规范。在仓库的 Biopython 参考文档 advanced.md 中可以看到，Bio.motifs 正是用 motifs.read(handle, "jaspar") 读取这类文件，并明确"Supported formats: jaspar, meme, transfac, pfm"——也就是说，从 JASPAR API 拉到的这三种格式都能被 Biopython 直接消费，用于后续扫描与打分。

3. /taxon/ 与 /collection/ 是"元数据发现"端点：前者用于确认某物种对应的 tax_id，后者用于确认可用的集合名称，适合在正式检索前先做一次探测性调用。

四、过滤参数详解

/matrix/ 列表端点支持组合过滤。参考文档列出以下参数：

• tax_id — NCBI 分类学 ID（人类为 9606）
• collection — 集合名，如 CORE、CNE、PHYLOFACTS 等
• tf_class — 转录因子结构类别
• name — 转录因子名称搜索
• page、page_size — 分页控制

参数语义与使用建议

• tax_id 采用的是 NCBI Taxonomy ID 体系，与仓库 常见标识符格式表 中记录的其他数据库一致。请勿直接使用拉丁学名，如需查询非人类物种，应先用 /taxon/ 端点确认其 NCBI tax ID。

• collection 决定数据审编级别与来源。CORE 是经过人工审编的高置信度集合，是日常研究的首选默认；CNE（conserved non-coding elements）等其他集合覆盖不同进化与调控场景。若不指定，API 可能返回混合集合的结果，因此在做严谨检索时，应显式给出 collection 并记录该过滤条件。

• tf_class / name 属于"服务器端过滤"——API 在返回前即按这些字段筛除记录。使用时应结合检索契约，将"服务器端能表达的过滤"与"必须取回本地再过滤的条件"区分开，这是 retrieval-contract.md 明确要求的步骤 3。

• page / page_size 提供基于页码的分页。仓库 SKILL.md 的分页章节指出 JASPAR 这类分页模式为 "Page number: page=1&per_page=50 → increment page"。做全量检索（如"人类 CORE 集合全部 motif"）时必须遍历所有页并核对总数，不能只看第一页。

五、示例调用：从单条查询到批量筛选

参考文档给出了三条可直接执行的示例 URL：

# 获取 CTCF 结合谱
https://jaspar.elixir.no/api/v1/matrix/MA0139.1/

# 人类 CORE 集合的 TF 结合谱（每页 10 条）
https://jaspar.elixir.no/api/v1/matrix/?tax_id=9606&collection=CORE&page_size=10

# 以 MEME 格式获取结合谱
https://jaspar.elixir.no/api/v1/matrix/MA0139.1/?format=meme

在 Agent 环境中推荐使用 curl 落地（对应仓库 SKILL.md 中"若平台无专用 fetch 工具则回退 curl"的建议），并显式设置 Accept 头与 URL 编码：

# 单条查询：CTCF 的 JSON 元数据
curl -s -H "Accept: application/json" \
  "https://jaspar.elixir.no/api/v1/matrix/MA0139.1/"

# 按物种 + 集合过滤 + 分页
curl -s -H "Accept: application/json" \
  "https://jaspar.elixir.no/api/v1/matrix/?tax_id=9606&collection=CORE&page_size=10&page=1"

# 拉取 MEME 格式 motif 文件（供下游软件直接使用）
curl -s -H "Accept: application/json" \
  "https://jaspar.elixir.no/api/v1/matrix/MA0139.1/?format=meme"

实操提醒：查询参数中的 tax_id、collection 均为简单键值，通常无需编码；但若以 name 检索含空格或特殊字符的 TF 名，应使用 --data-urlencode 或预先 URL 编码，避免请求失败——这正是仓库 请求指南 反复强调的注意事项。

工作流示例：查某个 TF 并转为 PWM 做扫描

参考文件展示的是"数据获取"一侧；仓库 Biopython 文档展示了"数据消费"一侧。把两者串起来，即是一条完整的 motif 分析链路：

1. 用 /matrix/?name=CTCF&collection=CORE 确认 matrix ID；
2. 用 format=meme（或 jaspar）拉取矩阵文件；
3. 用 Bio.motifs 读取并用 PWM/PSSM 在序列上扫描。

Biopython 侧的读取与扫描代码见 advanced.md，其中 motifs.read(handle, "jaspar") 读单条、motifs.parse 读多条、motif.counts.normalize(pseudocounts=0.5) 生成 PWM、pwm.log_odds() 生成 PSSM 后用 pssm.search(test_seq, threshold=5.0) 定位命中位置。这样 JASPAR 的矩阵就与仓库内既有的序列分析能力形成了闭环。

六、返回格式：读懂 PFM 字段

JASPAR 的 /matrix/ 与 /matrix/{id}/ 默认返回 JSON。参考文档说明，结合谱记录包含以下核心字段：

• matrix_id — 矩阵 ID，如 MA0139.1
• name — 转录因子名称，如 CTCF
• pfm — 位置频率矩阵（position frequency matrix），以 A/C/G/T 四碱基为键的字典
• sequence_logo — 序列 Logo 图片 URL
• species — 物种信息
• class — TF 结构类别
• family — TF 家族

一个典型的 pfm 结构形如：

{
  "matrix_id": "MA0139.1",
  "name": "CTCF",
  "pfm": {
    "A": [14, 4, 0, ...],
    "C": [10, 12, 24, ...],
    "G": [0, 6, 0, ...],
    "T": [0, 2, 0, ...]
  },
  "species": [...],
  "class": "...",
  "family": "...",
  "sequence_logo": "https://..."
}

解读要点：

• PFM 是"计数"而非"概率"：每个位置上的数字表示该碱基在结合位点实例中的出现次数。若需转化为位置权重矩阵（PWM），需按列归一化（通常加伪计数），与 Biopython 中 motif.counts.normalize(pseudocounts=0.5) 的语义对应。
• sequence_logo 是可视化 URL，适合人类审阅，但不建议在自动化管道中依赖外链图片——结构化数据应取自 pfm 本身。
• species / class / family 字段是本地二次过滤的天然依据：当 API 不支持按 family 过滤时，可先按 collection 服务器端过滤，再在本地按 family/class 字段筛除不需要的记录，并把每一步删除数量记入 provenance（对齐 完整性协议 第 4 节）。

七、分页与全量检索：不要只取第一页

当需求是"获取人类 CORE 集合的全部 TF 结合谱"这类穷尽式检索时，必须遵循仓库的 Completeness Protocol：

1. 先以 page_size 请求第一页并读取响应中的总数元数据（count/total）；
2. 估算总页数 = ceil(total / page_size)，评估调用成本；
3. 按 page=1,2,3,... 顺序翻页，记录每页返回数与累计数；
4. 校验"服务器总数 == 各页返回数之和"；
5. 若中途翻页失败或计数对不上，应显式报出该不完整状态，而不是给出看似完整的汇总——"Fail visible, not plausible"。

对于"查单个 TF（如 CTCF）"的目标性查询，第一页通常已足够，无需翻页；这类场景按仓库规范仍应记录端点、参数与访问日期以保证可复现。

八、Rate Limits 与调用纪律

参考文档对限流的态度是：

No published limits. Be reasonable.

即官方未公布硬性速率上限，但要求调用方自律。结合仓库通用请求纪律，建议对 JASPAR 采用以下保守策略：

• 串行或低并发调用，避免突发脉冲式请求打满服务器；
• 单次穷尽式检索前先做 count 探测，超过 10,000 条记录或 100 次 API 调用需先与用户确认并给出简短检索计划（对齐 SKILL.md 的 bound total work 原则）；
• 若偶遇 HTTP 429/503，短暂等待后重试一次；
• JASPAR 无鉴权，不存在密钥泄露风险，但仍需遵守"外部响应即不可信数据"原则：不把返回 JSON 直接拼入 shell 命令，只抽取所需字段并重新校验后再用于下游调用（参见 retrieval-contract.md 的响应安全处理）。

九、可复现的检索出处记录模板

将 JASPAR 查询结果用于论文或下游分析前，建议按 database-lookup 技能的 Retrieval Summary 模板 记录出处。一个针对 JASPAR 的填写示例：

Target: CTCF 转录因子结合谱
Scope: targeted lookup（单条 matrix 记录）
Access date: （填写实际访问日期）
Primary database: JASPAR（Biology & Genomics）
Endpoint: /matrix/MA0139.1/
Parameters: format=json（或 format=meme）
Identifier conversions: 基因名 CTCF → JASPAR matrix_id MA0139.1
Server-side filters: 无
Local filters: 无
Count reconciliation: 目标单条检索，返回 1 条记录，与预期一致
Warnings: JASPAR 无官方限流数值，未发布缓存版本策略

完整框架（含 Target / Databases queried / Parameters / Count reconciliation / Warnings 等全部字段）可直接复用仓库 SKILL.md 的输出格式 与 Provenance Template，让任何 Agent 或人类都能重复本次检索。

十、常见问题与排错建议

结合仓库 错误恢复章节 的通用思路，JASPAR 检索失败时依次排查：

1. matrix ID 是否带版本号：MA0139 与 MA0139.1 不同，注意版本后缀，更新版本可能已替换旧版（如 MA0139.3）。
2. tax_id 是否用错：人类为 9606；用学名直接传参通常无效，需先经 /taxon/ 解析。
3. 集合名拼写：CORE 等集合名需与 /collection/ 端点返回的名称完全一致。
4. 分页参数名：JASPAR 使用 page + page_size，不要误用 offset/limit 或 per_page。
5. 格式参数影响返回结构：加 format=meme/format=transfac 后返回的是纯文本格式而非 JSON 元数据，解析方式需相应切换；若只想读 JSON 元数据，不要带 format 参数。

结语

JASPAR 以零鉴权、REST 化、多格式导出的设计成为科学 Agent 获取转录因子结合谱的首选数据源之一。本文围绕 jaspar.md 的端点、参数与响应结构，补充了 curl 落地方式、PFM 语义解读、分页完整性校验与出处记录模板，并将其与仓库中的 database-lookup 技能总纲、检索契约 及 Biopython motif 分析能力 打通。在 Agent 场景中实践"先定契约 → 有界调用 → 核数对账 → 记录出处"的流程，即可让每一次 JASPAR 查询都可审计、可复现。