本文へ移動
cccskills
無料GitHub で公開

pubtator-entity-search

NLM PubTator3 实体级关系挖掘 — 检索"疾病-药物-基因-化学品-突变"在生物医学文献中的标注与关系。

当用户问"哪些研究讨论了 BTK 抑制剂与肺曲霉病"、"基因 X 与疾病 Y 的关联"、"药物-基因相互作用"、"找含某突变的文献"、"PubTator / 实体标注 / NER / annotation / biomedical entity / 疾病基因关联 / 药物-基因 / 化学品-疾病 / 突变检索"时使用。

无需 API key。**实体级 · 关系挖掘**定位 — 不做文献综合检索(用 pubmed-eutils / europepmc-search)、不做全文(用 BioC)、不做试验(用 ct-v2)。

EthanYoQ/Skill-hub
インストール方法を見る

含まれるファイル（1）

  • SKILL.md9.2 KB

SKILL.md（原文）

インストールする前に、エージェントに与えられる指示の中身を確認できます。

PubTator3 Entity & Relation Search

封装 NLM PubTator3 RESTful API,用于在 PubMed 文献中做实体级标注 + 关系挖掘。 聚焦"疾病 - 药物 - 基因 - 化学品 - 突变 - 物种"的联动检索,适合"实体 X 与实体 Y 在文献中怎样被讨论"这类问题。

1. 何时使用本技能

适合:

  • "哪些文献提到了 BTK 抑制剂用于侵袭性肺曲霉病" — 实体 + 关系
  • "基因 EGFR 在非小细胞肺癌中的相关研究" — 共现 / 关联
  • "找出讨论 voriconazole 与 CYP2C19 相互作用的文献" — 药物-基因
  • "把这一组 PMID 里的疾病/药物/基因都标出来" — 标注提取
  • "ibrutinib 在文献中映射到哪个 MeSH/DrugBank ID" — 实体规范化

不适合(用其他技能):

  • 用 MeSH 树/出版类型/PubDate 做文献检索 → pubmed-eutils + Clinical Queries
  • 拿全文 XML/段落 → BioC (BioC PubMed/PMC)
  • 临床试验注册信息 → ct-v2 (ClinicalTrials.gov)
  • 综合性自然语言检索 → europepmc-search

2. API 概览(无需 Key)

Base URL: https://www.ncbi.nlm.nih.gov/research/pubtator3-api/

PubTator3 是 NLM 开放服务,不需要 API key,但请遵守速率限制(建议 ≤ 3 req/s,失败时退避)。

核心端点:

端点用途
GET /search/?text=<query>自由文本/实体检索文献
GET /publications/export/biocjson?pmids=<csv>拉取 PMID 的实体标注 BioC-JSON
GET /entity/autocomplete/?query=<text>&concept=<type>实体规范化(text → ID)
GET /relations?e1=<id>&e2=<id>关系/共现挖掘

文档: https://www.ncbi.nlm.nih.gov/research/pubtator3-api/

3. 核心能力(5 个函数)

3.1 search_by_entity(entity_text, entity_type=None, max_results=50)

检索包含某实体的 PubMed 文献。

GET /search/?text=@<TYPE>_<ID> 或 ?text=<free text>

示例:text=@DISEASE_MESH:D055744 → 侵袭性曲霉病。 返回 {pmids:[...], score:[...]}。

3.2 search_by_relation(entity1_id, relation_type, entity2_id)

检索表达"实体1 — 关系 — 实体2"的文献。

GET /relations?e1=<id1>&e2=<id2>&type=<relation>

返回涉及该关系的 PMID 列表 + 句级证据片段(若有)。

3.3 annotate_pmid(pmid_list)

给定 PMID 数组,返回标题 + 摘要内的全部实体标注。

GET /publications/export/biocjson?pmids=12345,67890&full=false

解析 BioC-JSON documents[].passages[].annotations[]。

3.4 entity_normalize(free_text, concept=None)

自由文本 → 标准实体 ID。

GET /entity/autocomplete/?query=BTK%20inhibitor&concept=chemical

返回 [{name, id, type, score}, ...],例如 BTK inhibitor → MeSH:D000077180。

3.5 find_co_mentions(entity1_id, entity2_id, top_n=20, recent_years=None)

共现分析 — 找两实体共同出现最多的文献,可按近 N 年过滤。 内部组合 search + annotate 验证两实体确实在同一文献被标注。

4. 实体类型 Reference

类型 (concept)标识体系示例 ID说明
GeneNCBI Gene695 (BTK)蛋白编码基因
DiseaseMeSH / OMIMMESH:D055744 (Invasive Pulmonary Aspergillosis)疾病 / 综合征
ChemicalMeSH / DrugBankMESH:D000077594 (ibrutinib)化学品 / 药物
VariantdbSNP / ClinVar / tmVarrs113488022多态位点 / 变异
MutationtmVarp.V600E蛋白/核酸级具体突变
SpeciesNCBI Taxonomy9606 (Homo sapiens)物种
CellLineCellosaurusCVCL_0030 (HeLa)细胞系

Variant 与 Mutation 在 PubTator3 多被合并为 Variant;查询时统一用 concept=variant。

5. 关系类型 Reference

PubTator3 关系标签(在 /relations 端点的 type 参数):

关系含义典型主语 → 宾语
treat / treats治疗Chemical → Disease
cause / causes致病 / 引发Chemical/Variant → Disease
interact_with相互作用Gene ↔ Gene / Chemical ↔ Gene
associate / associated_with关联(弱因果)Gene ↔ Disease / Variant ↔ Disease
regulate / regulates调控(上下游)Gene → Gene
inhibit / inhibits抑制Chemical → Gene/Protein
co-occur共现(无方向)任意 ↔ 任意

当不确定关系语义时,优先使用 co-occur 做共现挖掘,再人工/二次核对方向。

6. 输出格式(标准 schema)

每条标注统一输出:

{
    "pmid": "12345",
    "entity_text": "BTK",
    "entity_type": "Gene",
    "identifier": "695",            # NCBI Gene ID / MeSH / dbSNP / ...
    "section": "Title",             # Title / Abstract
    "offset": 23,                   # 字符级起点(passage 内)
    "length": 3,
    "confidence": 0.95,             # PubTator3 置信度(若 API 返回)
}

关系输出:

{
    "pmid": "12345",
    "subject": {"text": "ibrutinib", "type": "Chemical", "id": "MESH:D000077594"},
    "predicate": "inhibits",
    "object":  {"text": "BTK",       "type": "Gene",     "id": "695"},
    "evidence_sentence": "Ibrutinib irreversibly inhibits BTK ...",
    "section": "Abstract",
}

7. 典型工作流

用例 A:疾病 + 药物联动

"找近 5 年讨论 BTK 抑制剂与侵袭性肺曲霉病关系的文献"

  1. entity_normalize("BTK inhibitor", "chemical") → MESH:D000077180
  2. entity_normalize("invasive pulmonary aspergillosis", "disease") → MESH:D055744
  3. find_co_mentions(e1, e2, top_n=30, recent_years=5)
  4. 对返回 PMID 用 annotate_pmid() 提取上下文实体 → 输出三元组表

用例 B:批量标注

"把这 20 个 PMID 里所有疾病/药物/基因列出来"

  1. annotate_pmid([...20 PMIDs...])
  2. 按 entity_type ∈ {Gene, Disease, Chemical} 过滤 → 去重计数 → 输出频次表

用例 C:实体规范化

"ibrutinib 的 MeSH 是什么?DrugBank 呢?"

  1. entity_normalize("ibrutinib", "chemical")
  2. 取首条 hit 的 id 字段(MeSH);若需 DrugBank 走 cross-ref(PubTator3 主返回 MeSH)

8. 实现要点

  • 使用 requests + tenacity 做指数退避(429 / 5xx)
  • concept 参数小写:gene | disease | chemical | variant | species | cellline
  • BioC-JSON 路径:documents[*].passages[*].annotations[*].infons.{type,identifier} + text + locations[0].offset/length
  • 一次 annotate_pmid 上限 100 PMID(超过自动分批)
  • 自由文本 + 实体混合查询语法:text=ibrutinib AND @DISEASE_MESH:D055744

9. 错误处理

错误处理
429 Too Many Requests退避 2s → 4s → 8s,最多 5 次
5xx同上退避
实体规范化无 hit返回空列表 + 建议:换同义词 / 改 concept
BioC-JSON 缺 annotations该 PMID 暂未被 PubTator 标注,跳过并记录
PMID 不存在在响应中按 PMID 标 status=not_found

不要静默吞错;每个失败请求记录 {pmid, endpoint, status_code, message}。

10. 安全 / 合规

  • 公共 NLM API,无 PHI
  • 不要把用户上传的非公开文本发给 PubTator3 — 仅检索公开 PMID
  • 输出注明 "Source: NLM PubTator3, retrieved <date>"
  • PubTator3 标注属机器抽取,置信度 < 0.8 的关系应人工核对

11. 与其他 skill 的协同

用户问题路由
"哪些研究讨论 X 与 Y 的关系" / "实体级关联"本技能
"近 5 年所有 X 的 RCT" / "MeSH + 出版类型筛选"pubmed-eutils + Clinical Queries
"PMID 12345 全文写了什么"BioC-PubMed/PMC
"正在招募的 X 临床试验"ct-v2 (ClinicalTrials.gov)
"Europe PMC 综合检索 + 引文"europepmc-search

本技能输出的 PMID 集合可直接喂给 pubmed-eutils / BioC 做下游展开。

12. 快速 cheatsheet

# 1) 文本 → 实体 ID
GET /entity/autocomplete/?query=ibrutinib&concept=chemical

# 2) 实体检索文献
GET /search/?text=@CHEMICAL_MESH:D000077594

# 3) 关系挖掘
GET /relations?e1=MESH:D000077594&e2=695&type=inhibits

# 4) PMID 批量标注
GET /publications/export/biocjson?pmids=12345,67890

# 5) 共现:先 search,各拿 PMID 集合 → 求交 → 按引用/年份排序

实体类型缩写(查询前缀):@GENE_、@DISEASE_MESH:、@CHEMICAL_MESH:、@VARIANT_、@SPECIES_、@CELLLINE_。

版本: v1.0 · 维护: 跟随 NLM PubTator3 API 文档更新(关注 endpoints 变更与新增 concept)。

レビュー

まだレビューはありません。使ってみた感想をお寄せください。

ログインしてレビューを書く

同じリポジトリのスキル

概要と使いどころ

aact-bulk-trials

無料

使用 AACT (Aggregate Analysis of ClinicalTrials.gov) PostgreSQL 数据仓库进行批量、历史、聚合性临床试验数据挖掘。Use this skill when the user requests bulk SQL analysis over the full clinical trials data warehouse — historical trial trends, disease landscapes, similar-design matching, or multi-year aggregations across hundreds of thousands of NCT records. 触发场景包括：AACT 查询、临床试验批量分析、PostgreSQL 试验数据、全量 NCT 检索、试验数据挖掘、历史试验分析、clinical trials data warehouse、SQL trials、bulk trial analysis、disease landscape、试验设计相似性匹配、跨年度聚合、sponsor/phase/country 多维统计。**与 clinical-trials-v2 差异**：本 skill 走批量 SQL · 离线大数据（PostgreSQL）；v2 走实时 API · 单查询。两者互补：单条 NCT 实时状态用 v2，百万级历史挖掘用本 skill。支持云端公共 PostgreSQL（aact-db.ctti-clinicaltrials.org · 零部署）和每日 dump 本地还原（高性能 · 离线）两种连接方式，自动检测优先用本地。跨平台（macOS/Linux/Windows）参数化 SQL 防注入，read-only 强制保护。

日本語の概要は準備中です。原文の説明を表示しています。

EthanYoQ/Skill-hub112026年10月5日 更新

aact-bulk-trials

無料

使用 AACT (Aggregate Analysis of ClinicalTrials.gov) PostgreSQL 数据库进行大批量临床试验历史分析与数据挖掘。触发场景包括：AACT 查询、临床试验批量分析、PostgreSQL 试验数据、全量 NCT 检索、试验数据挖掘、clinical trials data warehouse、疾病领域全景分析、设计相似试验匹配、跨年度试验趋势聚合。本 skill 通过 SQL 接口处理百万级试验记录，支持云端公共 PostgreSQL 服务（aact-db.ctti-clinicaltrials.org）和每日 dump 本地还原两种连接方式，自动检测并优先使用本地高性能模式。

日本語の概要は準備中です。原文の説明を表示しています。

EthanYoQ/Skill-hub112026年10月5日 更新

adaptive-quality-gate

無料

Use when work produces a deliverable, factual claim, dataset, code change, decision, publication, deployment, automation, or irreversible action whose failure would matter; when the user asks for a quality gate, acceptance criteria, QA, completeness, validation, audit, evidence, preflight, release readiness, or a definition of done; or before claiming completion on medium- or high-risk work. Automatically decide whether a formal gate is warranted, derive task-specific pass/fail criteria, gather evidence, and block unsupported completion. Make sure to use this skill even when the user does not say "quality gate" if consequential work needs acceptance criteria or completion evidence. Skip formal gating for trivial, reversible, low-impact requests.

日本語の概要は準備中です。原文の説明を表示しています。

EthanYoQ/Skill-hub112026年10月5日 更新

add-changeset

無料

Create a changeset file in .changeset/ that describes a user-facing change for the release notes

日本語の概要は準備中です。原文の説明を表示しています。

EthanYoQ/Skill-hub112026年10月5日 更新

add-competitor

無料

Add a new competitor to the AI Visibility Tool Directory — researches the tool, generates data, takes a screenshot, and inserts into the codebase

日本語の概要は準備中です。原文の説明を表示しています。

EthanYoQ/Skill-hub112026年10月5日 更新

add-lang

無料

Add tree-sitter language support to codegraph end-to-end — wire the grammar + extractor, write tests, then benchmark extraction quality and retrieval value on 3 popular real-world repos. Use when the user runs /add-lang <language> or asks to add/support a new language (e.g. Lua, Elixir, Zig, OCaml) in codegraph.

日本語の概要は準備中です。原文の説明を表示しています。

EthanYoQ/Skill-hub112026年10月5日 更新

EthanYoQ のスキルをすべて見る

このスキルの問題を報告する