embl-ebi-ols

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

EMBL-EBI Ontology Lookup Service (OLS)

EMBL-EBI本体查找服务（OLS）

Prerequisites

前提条件

uv
: Read the
```
uv
```
skill and follow its Setup instructions to ensure
```
uv
```
is installed and on PATH.
User Notification: If LICENSE_NOTIFICATION.txt does not already exist in this skill directory then (1) prominently notify the user to check the terms at https://www.ebi.ac.uk/ols4/api-docs, then (2) create the file recording the notification text and timestamp.

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

Core Rules

核心规则

[!IMPORTANT] Use the Utility Scripts: You MUST ALWAYS use the provided utility script under
```
scripts/
```
for all API interactions, including checking status. NEVER use
```
curl
```
or custom Python requests to query API directly.
Rate Limiting & Resilience: You MUST respect EBI's Terms of Use with a maximum 5 requests per second. The provided utility scripts automatically enforce this.
Notification: If this skill is used, ensure this is mentioned in the output.

[!IMPORTANT] 使用实用脚本：所有API交互（包括状态检查）必须始终使用
```
scripts/
```
下提供的实用脚本。绝不能直接使用
```
curl
```
或自定义Python请求来查询API。
速率限制与弹性：必须遵守EBI的使用条款，每秒最多5次请求。提供的实用脚本会自动执行此限制。
通知：如果使用此技能，需确保在输出中提及这一点。

When to Use — Quick Recipes

使用场景速查

Use this skill whenever a user query matches one of these patterns:

Definition of a disease, phenotype, or term →
```
get_term.py --obo_id <ID> --summary
```

Subtypes or children of a term →

get_term.py --obo_id <ID> --relations children

Parent of a term →

get_term.py --obo_id <ID> --relations parents

Ancestors / disease categories / classified under →
```
get_term.py --obo_id <ID> --relations ancestors
```
Root terms of an ontology →
```
get_term.py --ontology <id> --roots
```

Hierarchical parents (is-a + part-of) →

get_term.py --obo_id <ID> --relations hierarchicalParents

Structures part of / hierarchical children →

get_term.py --obo_id <ID> --relations hierarchicalChildren

Compare direct vs hierarchical parents →

get_term.py --obo_id <ID> --relations parents,hierarchicalParents

Search for a term (e.g., "apoptosis" in GO) →
```
search_ols.py --query "..." --ontology <id>
```

Find a GO term matching a function →

search_ols.py --query "..." --ontology go --exact

Search in MONDO, CHEBI, CL, UBERON →

search_ols.py --query "..." --ontology <id> --defining

Paginate search results / next page →

search_ols.py --query "..." --rows N --start <offset>

Autocomplete a partial name →
```
suggest_ols.py --query "..."
```
Ontology metadata (e.g., EFO info) →
```
get_ontology.py --id <id>
```
OLS index statistics →
```
get_stats.py
```

Multi-step queries (e.g., "What is the parent of myocardial infarction?"): When the user names a term but you don't know its OBO ID, complete in exactly 2 steps — do NOT search across multiple ontologies:
Search in the single most appropriate ontology:
search_ols.py --query "myocardial infarction" --ontology doid --exact --rows 1 --output /tmp/step1.json
Get relations using the OBO ID from step 1:
get_term.py --obo_id DOID:5844 --relations parents --output /tmp/step2.json
Ontology selection rule: ALWAYS use
doid
for common human diseases (e.g., diabetes, cancer),
hp
for phenotypes,
go
for gene functions,
chebi
for chemicals,
uberon
for anatomy,
cl
for cell types. Use
mondo
ONLY when cross-species context is explicitly mentioned or needed.

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

疾病、表型或术语的定义 →
```
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个步骤完成——不要跨多个本体搜索：
在最合适的单个本体中搜索：
search_ols.py --query "myocardial infarction" --ontology doid --exact --rows 1 --output /tmp/step1.json
使用步骤1中的OBO ID获取关系：
get_term.py --obo_id DOID:5844 --relations parents --output /tmp/step2.json
本体选择规则：常见人类疾病（如糖尿病、癌症）始终使用
doid
，表型使用
hp
，基因功能使用
go
，化学物质使用
chebi
，解剖结构使用
uberon
，细胞类型使用
cl
。仅当明确提及或需要跨物种上下文时才使用
mondo
。

Utility Scripts

实用脚本

1. Search Terms Across Ontologies

Search for ontology terms by keyword and return clean JSON.

bash

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

Important:
--output
is required for all scripts. Results are always written to the specified file. For larger output, you can limit
--rows
(e.g., 5-10) or paginate using
--start
.

Returned Fields: JSON results include

iri

label

description

ontology_name

ontology_prefix

obo_id

short_form

type

is_defining_ontology

, and

exact_synonyms

Pagination: Output includes a

pagination

block with

start

rows

, and

has_more

so you can decide whether to fetch more results.

Options:

```
--query
```
: Search string (required). Searches labels, synonyms, descriptions, and identifiers.
```
--ontology
```
: Filter by ontology ID (e.g.,
```
go
```
,
```
doid
```
,
```
efo
```
,
```
hp
```
). Recommended when you know which ontology to search — avoids noise from 250+ ontologies.
```
--type
```
: Filter by entity type:
```
class
```
,
```
property
```
,
```
individual
```
, or
```
ontology
```
.
```
--exact
```
: Flag for exact label match only. Use this for entity resolution when mapping a user's string to a specific ontology term ID.
```
--defining
```
: Only return terms from their defining (authoritative) ontology. E.g.,
```
GO:0005634
```
only from GO, not cross-referenced copies.
```
--obsolete
```
: Flag to include obsolete terms in results.
```
--local
```
: Only return terms in their defining ontology.
```
--childrenOf
```
: Restrict to children of given term IRI(s), comma-separated.
```
--allChildrenOf
```
: Restrict to all children including transitive relations (part of, develops from), comma-separated IRIs.
```
--queryFields
```
: Comma-separated fields to search in (e.g.,
```
label,synonym,description
```
).
```
--fieldList
```
: Comma-separated fields to return.
```
--groupField
```
: Group results by unique IRI.
```
--isLeaf
```
: Only return leaf terms (no children).
```
--rows
```
: Number of results to return (default 10).
```
--start
```
: Pagination offset (default 0).
```
--output
```
: File path to save results (required).

2. Autocomplete / Suggest

Get autocomplete suggestions for partial term names.

bash

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

Options:

```
--query
```
: Partial term to autocomplete (required).
```
--ontology
```
: Filter by ontology ID(s), comma-separated.
```
--rows
```
: Number of suggestions (default 10).
```
--start
```
: Pagination offset (default 0).
```
--output
```
: File path to save results (default: stdout).

3. Get Term Details

Retrieve full details for a specific ontology term by its OBO ID or IRI.

bash

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

Returned Fields: JSON includes

iri

label

description

obo_id

synonyms

ontology_name

is_obsolete

is_defining_ontology

has_children

is_root

annotation

in_subset

, and any requested relations.

Summary Mode: Use

--summary

to get a clean, human-readable block on stdout (Label, OBO ID, Ontology, Definition, Synonyms). The full JSON is always saved to the

--output

file.

bash

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

Options:

```
--obo_id
```
: OBO-style identifier (e.g.,
```
GO:0005634
```
,
```
DOID:9351
```
). Mutually exclusive with
```
--iri
```
. Auto-converts to IRI with double encoding.
```
--iri
```
: Full IRI of the term. Mutually exclusive with
```
--obo_id
```
.
```
--ontology
```
: Ontology ID (auto-derived from
```
--obo_id
```
if not provided).
```
--relations
```
: Comma-separated list of relations to fetch.
- Direct (is-a only):
```
parents
```
  ,
```
children
```
  ,
```
ancestors
```
  ,
```
descendants
```
- Hierarchical (is-a + transitive like "part of", "develops from"):
```
hierarchicalParents
```
  ,
```
hierarchicalChildren
```
  ,
```
hierarchicalAncestors
```
  ,
```
hierarchicalDescendants
```
- Graph:
```
graph
```
  — full graph JSON for a term
Note: Use hierarchical variants for anatomical/developmental ontologies (UBERON, CL) where transitive relations like "part of" and "develops from" are critical for navigating the hierarchy.
```
--roots
```
: List root terms of the ontology (requires
```
--ontology
```
).
```
--preferred_roots
```
: List preferred root terms (requires
```
--ontology
```
).
```
--summary
```
: Human-readable summary on stdout, full JSON to
```
--output
```
.
```
--output
```
: File path to save results (default: stdout).

4. Get Property Details

Retrieve details for an ontology property (relation type) with hierarchy.

bash

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

Options:

```
--obo_id
```
: OBO-style ID of the property. Mutually exclusive with
```
--iri
```
.
```
--iri
```
: Full IRI of the property. Mutually exclusive with
```
--obo_id
```
.
```
--ontology
```
: Ontology ID (required with
```
--iri
```
).

--relations

: Comma-separated:

parents

children

ancestors

descendants

```
--roots
```
: List root properties of the ontology (requires
```
--ontology
```
).
```
--output
```
: File path to save results (default: stdout).

5. Get Individual Details

Retrieve details for an ontology individual (instance).

bash

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

Options:

```
--obo_id
```
: OBO-style ID. Mutually exclusive with
```
--iri
```
.
```
--iri
```
: Full IRI. Mutually exclusive with
```
--obo_id
```
.
```
--ontology
```
: Ontology ID (required with
```
--iri
```
).
```
--types
```
: Fetch the direct types (classes) of this individual.
```
--alltypes
```
: Fetch all types including ancestor classes.
```
--output
```
: File path to save results (default: stdout).

6. Get Ontology Information

List available ontologies or retrieve details for a specific one.

bash

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

Options:

```
--id
```
: Specific ontology ID (e.g.,
```
go
```
,
```
efo
```
,
```
doid
```
). If omitted, lists all ontologies.
```
--page
```
: Page number for pagination (default 0).
```
--size
```
: Number of ontologies per page (default 20).
```
--output
```
: File path to save results (default: stdout).

7. Get OLS Statistics

Retrieve index statistics (total ontologies, classes, properties, individuals).

bash

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

Options:

```
--output
```
: File path to save results (default: stdout).

1. 跨本体搜索术语

按关键词搜索本体术语并返回简洁的JSON结果。

bash

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. 自动补全/建议

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

bash

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
```
：保存结果的文件路径（默认：标准输出）。

3. 获取术语详情

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

bash

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

在标准输出上获取简洁的人类可读块（标签、OBO ID、本体、定义、同义词）。完整JSON始终保存到

--output

指定的文件。

bash

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
```
：在标准输出显示人类可读摘要，完整JSON保存到
```
--output
```
。
```
--output
```
：保存结果的文件路径（默认：标准输出）。

4. 获取属性详情

检索带层级的本体属性（关系类型）详情。

bash

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. 获取个体详情

检索本体个体（实例）的详情。

bash

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. 获取本体信息

列出可用本体或检索特定本体的详情。

bash

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统计信息

检索索引统计信息（本体总数、类、属性、个体数量）。

bash

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

选项：

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

Reference

参考资料

API Reference: See references/api_reference.md for common ontology IDs, OBO ID format, and key API endpoints.

API参考：查看references/api_reference.md获取常见本体ID、OBO ID格式和关键API端点。

Workflow

工作流程

Use
```
suggest_ols.py
```
for autocomplete when you have a partial term name.
Search for terms using
```
search_ols.py
```
. Use
```
--defining
```
to prioritize authoritative definitions. Use
```
--exact
```
for entity resolution.
If full details are needed, use
```
get_term.py
```
with the OBO ID or IRI. Use
```
--summary
```
for a concise view.

To explore a term's hierarchy, use

get_term.py --relations parents,children

for is-a only, or

--relations hierarchicalParents,hierarchicalChildren

for "part of" etc.

To explore from the top down, use
```
get_term.py --ontology go --roots
```
.
For properties or individuals, use
```
get_property.py
```
or
```
get_individual.py
```
.
To discover available ontologies, use
```
get_ontology.py
```
.
To check OLS index status, use
```
get_stats.py
```
.

当有部分术语名称时，使用
```
suggest_ols.py
```
进行自动补全。
使用
```
search_ols.py
```
搜索术语。使用
```
--defining
```
优先获取权威定义。使用
```
--exact
```
进行实体解析。
如果需要完整详情，使用
```
get_term.py
```
并传入OBO ID或IRI。使用
```
--summary
```
获取简洁视图。

要探索术语的层级，使用

get_term.py --relations parents,children

获取仅is-a关系，或使用

--relations hierarchicalParents,hierarchicalChildren

获取"part of"等关系。

要自上而下探索，使用
```
get_term.py --ontology go --roots
```
。
对于属性或个体，使用
```
get_property.py
```
或
```
get_individual.py
```
。
要发现可用本体，使用
```
get_ontology.py
```
。
要检查OLS索引状态，使用
```
get_stats.py
```
。