embl-ebi-ols

EMBL-EBI Ontology Lookup Service (OLS)

前提条件

1. uv：阅读 uv 技能，并按照其中的设置说明操作，确保已安装 uv 且其位于 PATH 中。
2. 用户通知：如果工作区根目录中尚不存在 .licenses/embl_ebi_ols_LICENSE.txt，则 (1) 显著提醒用户查看 https://www.ebi.ac.uk/ols4/api-docs 中的条款，然后 (2) 创建该文件，记录通知文本和时间戳。

核心规则

• [!IMPORTANT] 使用实用脚本：对于所有 API 交互（包括检查状态），必须始终使用 scripts/ 下提供的实用脚本。绝不要使用 curl 或自定义 Python 请求直接查询 API。

• 速率限制与弹性：必须遵守 EBI 的使用条款，每秒最多发送 5 个请求。提供的实用脚本会自动执行此限制。

• 通知：如果使用了此技能，请确保在输出中提及。

使用场景 — 快速示例

当用户的查询符合以下任一模式时，使用此技能：

• 定义疾病、表型或术语 → get_term.py --obo_id <ID> --summary
• 术语的亚型或子项 → get_term.py --obo_id <ID> --relations children
• 术语的父项 → get_term.py --obo_id <ID> --relations parents
• 祖先项／疾病类别／归类于 → get_term.py --obo_id <ID> --relations ancestors
• 本体的根术语 → get_term.py --ontology <id> --roots
• 层级父项（is-a + part-of）→ get_term.py --obo_id <ID> --relations hierarchicalParents
• 组成结构／层级子项 → get_term.py --obo_id <ID> --relations hierarchicalChildren
• 比较直接父项与层级父项 → get_term.py --obo_id <ID> --relations parents,hierarchicalParents
• 搜索术语（例如，在 GO 中搜索“apoptosis”）→ search_ols.py --query "..." --ontology <id>
• 查找与某项功能匹配的 GO 术语 → search_ols.py --query "..." --ontology go --exact
• 在 MONDO、CHEBI、CL、UBERON 中搜索 → search_ols.py --query "..." --ontology <id> --defining
• 对搜索结果进行分页／获取下一页 → search_ols.py --query "..." --rows N --start <offset>
• 自动补全部分名称 → suggest_ols.py --query "..."
• 本体元数据（例如 EFO 信息）→ get_ontology.py --id <id>
• OLS 索引统计信息 → get_stats.py

多步骤查询（例如，“心肌梗死的父项是什么？”）：如果用户提供了术语，但你不知道其 OBO ID，必须通过恰好 2 步完成查询——不要跨多个本体搜索：

1. 在最合适的单一本体中搜索：search_ols.py --query "myocardial infarction" --ontology doid --exact --rows 1 --output /tmp/step1.json
2. 使用第 1 步中的 OBO ID 获取关系：get_term.py --obo_id DOID:5844 --relations parents --output /tmp/step2.json

本体选择规则：常见人类疾病（例如糖尿病、癌症）始终使用 doid，表型使用 hp，基因功能使用 go，化学物质使用 chebi，解剖结构使用 uberon，细胞类型使用 cl。仅当明确提及或需要跨物种背景时才使用 mondo。

实用脚本

1. 跨本体搜索术语

按关键词搜索本体术语，并返回整洁的 JSON。

uv run scripts/search_ols.py --query "diabetes" \
  --rows 5 --output /tmp/ols_search_results.json 2>/dev/null

重要：所有脚本都必须使用 --output。结果始终会写入指定文件。对于较大的输出，可以通过 --rows 限制结果数量（例如 5-10），或使用 --start 进行分页。

返回字段： JSON 结果包括 iri、label、description、ontology_name、ontology_prefix、obo_id、short_form、type、is_defining_ontology 和 exact_synonyms。

分页： 输出包含一个 pagination 区块，其中有 start、rows 和 has_more，便于你决定是否获取更多结果。 选项：

• --query：搜索字符串（必填）。搜索标签、同义词、描述和标识符。
• --ontology：按本体 ID 筛选（例如，go、doid、efo、hp）。 知道要搜索的本体时建议使用，可避免 250 多个本体带来的干扰。
• --type：按实体类型筛选：class、property、individual 或 ontology。
• --exact：仅精确匹配标签的标志。将用户输入的字符串映射到特定本体术语 ID 时，用于实体解析。
• --defining：仅返回来自其定义（权威）本体的术语。例如，GO:0005634 仅从 GO 返回，不返回交叉引用的副本。
• --obsolete：包含已废弃术语的标志。
• --local：仅返回定义本体中的术语。
• --childrenOf：限制为指定术语 IRI 的子项，多个 IRI 以逗号分隔。
• --allChildrenOf：限制为所有子项（包括传递关系，如 part of、develops from），多个 IRI 以逗号分隔。
• --queryFields：要搜索的字段，以逗号分隔（例如， label,synonym,description）。
• --fieldList：要返回的字段，以逗号分隔。
• --groupField：按唯一 IRI 对结果分组。
• --isLeaf：仅返回叶术语（没有子项）。
• --rows：返回结果数量（默认值为 10）。
• --start：分页偏移量（默认值为 0）。
• --output：保存结果的文件路径（必填）。

2. 自动补全 / 建议

获取部分术语名称的自动补全建议。

uv run scripts/suggest_ols.py --query "diabet" --rows 5 \
  --output /tmp/ols_suggest.json 2>/dev/null

选项：

• --query：要自动补全的部分术语（必填）。
• --ontology：按本体 ID 筛选，多个 ID 以逗号分隔。
• --rows：建议数量（默认值为 10）。
• --start：分页偏移量（默认值为 0）。
• --output：保存结果的文件路径（默认值：stdout）。

3. 获取术语详情

通过 OBO ID 或 IRI 获取特定本体术语的完整详情。

uv run scripts/get_term.py --obo_id "GO:0005634" \
  --output /tmp/ols_term.json 2>/dev/null

返回字段： JSON 包含 iri、label、description、obo_id、 synonyms、ontology_name、is_obsolete、is_defining_ontology、 has_children、is_root、annotation、in_subset 以及任何请求的 关系。

摘要模式： 使用 --summary 可在 stdout 上获取清晰易读的文本块 （标签、OBO ID、本体、定义、同义词）。完整 JSON 始终会保存到 --output 文件。

uv run scripts/get_term.py --obo_id "GO:0005634" --summary \
  --output /tmp/nucleus_full.json

选项：

• --obo_id：OBO 风格的标识符（例如，GO:0005634、DOID:9351）。与 --iri 互斥。自动转换为经过双重编码的 IRI。

• --iri：术语的完整 IRI。与 --obo_id 互斥。

• --ontology：本体 ID（若未提供，则根据 --obo_id 自动推导）。

• --relations：要获取的关系列表，以逗号分隔。

  • 直接关系（仅 is-a）： parents、children、ancestors、 descendants
  • 层级关系（is-a + part of、develops from 等传递关系）： hierarchicalParents、hierarchicalChildren、hierarchicalAncestors、 hierarchicalDescendants
  • 图： graph — 术语的完整图 JSON

  注意：对于解剖学 / 发育学本体（UBERON、CL），请使用层级关系变体，因为 part of 和 develops from 等传递关系对于浏览层级结构至关重要。

• --roots：列出本体的根术语（需要 --ontology）。

• --preferred_roots：列出首选根术语（需要 --ontology）。

• --summary：在 stdout 上输出易读摘要，并将完整 JSON 保存到 --output。

• --output：保存结果的文件路径（默认值：stdout）。

4. 获取属性详情

获取本体属性（关系类型）的详情及其层级结构。

uv run scripts/get_property.py --obo_id "BFO:0000051" --ontology go \
  --output /tmp/ols_property.json 2>/dev/null

选项：

• --obo_id：属性的 OBO 风格 ID。不能与 --iri 同时使用。
• --iri：属性的完整 IRI。不能与 --obo_id 同时使用。
• --ontology：本体 ID（与 --iri 一起使用时必填）。
• --relations：逗号分隔的列表：parents、children、ancestors、 descendants。
• --roots：列出本体的根属性（需要 --ontology）。
• --output：保存结果的文件路径（默认：标准输出）。

5. 获取个体详情

获取本体个体（实例）的详情。

uv run scripts/get_individual.py --obo_id "IAO:0000103" --ontology iao --types \
  --output /tmp/ols_individual.json 2>/dev/null

选项：

• --obo_id：OBO 风格 ID。不能与 --iri 同时使用。
• --iri：完整 IRI。不能与 --obo_id 同时使用。
• --ontology：本体 ID（与 --iri 一起使用时必填）。
• --types：获取该个体的直接类型（类）。
• --alltypes：获取所有类型，包括祖先类。
• --output：保存结果的文件路径（默认：标准输出）。

6. 获取本体信息

列出可用本体，或获取特定本体的详情。

uv run scripts/get_ontology.py --id go \
  --output /tmp/ols_ontology.json 2>/dev/null

选项：

• --id：指定本体 ID（例如 go、efo、doid）。如果省略，则列出 所有本体。
• --page：分页页码（默认 0）。
• --size：每页的本体数量（默认 20）。
• --output：保存结果的文件路径（默认：标准输出）。

7. 获取 OLS 统计信息

获取索引统计信息（本体、类、属性和个体的总数）。

uv run scripts/get_stats.py --output /tmp/ols_stats.json 2>/dev/null

选项：

• --output：保存结果的文件路径（默认：标准输出）。

参考

• API 参考：请参阅 references/api_reference.md，了解常用本体 ID、OBO ID 格式和主要 API 端点。

工作流

1. 如果只有部分术语名称，可使用 suggest_ols.py 自动补全。
2. 使用 search_ols.py 搜索术语。使用 --defining 优先显示权威定义。使用 --exact 进行实体解析。
3. 如果需要完整详情，可使用 OBO ID 或 IRI 调用 get_term.py。使用 --summary 查看简洁视图。
4. 若要探索术语的层级关系，可使用 get_term.py --relations parents,children，仅查询 is-a 关系；也可使用 --relations hierarchicalParents,hierarchicalChildren 查询“part of”等关系。
5. 若要从顶层向下探索，可使用 get_term.py --ontology go --roots。
6. 对于属性或个体，可使用 get_property.py 或 get_individual.py。
7. 若要查找可用本体，可使用 get_ontology.py。
8. 若要检查 OLS 索引状态，可使用 get_stats.py。