ontology-lookup 0.1.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- ontology_lookup-0.1.1/PKG-INFO +1051 -0
- ontology_lookup-0.1.1/README.md +1034 -0
- ontology_lookup-0.1.1/pyproject.toml +64 -0
- ontology_lookup-0.1.1/setup.cfg +4 -0
- ontology_lookup-0.1.1/src/ontology_lookup/__init__.py +25 -0
- ontology_lookup-0.1.1/src/ontology_lookup/api.py +515 -0
- ontology_lookup-0.1.1/src/ontology_lookup/cli.py +778 -0
- ontology_lookup-0.1.1/src/ontology_lookup/config.py +52 -0
- ontology_lookup-0.1.1/src/ontology_lookup/db.py +59 -0
- ontology_lookup-0.1.1/src/ontology_lookup/loader.py +574 -0
- ontology_lookup-0.1.1/src/ontology_lookup/manager.py +685 -0
- ontology_lookup-0.1.1/src/ontology_lookup/models.py +121 -0
- ontology_lookup-0.1.1/src/ontology_lookup/schema.py +96 -0
- ontology_lookup-0.1.1/src/ontology_lookup/service.py +779 -0
- ontology_lookup-0.1.1/src/ontology_lookup.egg-info/PKG-INFO +1051 -0
- ontology_lookup-0.1.1/src/ontology_lookup.egg-info/SOURCES.txt +23 -0
- ontology_lookup-0.1.1/src/ontology_lookup.egg-info/dependency_links.txt +1 -0
- ontology_lookup-0.1.1/src/ontology_lookup.egg-info/entry_points.txt +2 -0
- ontology_lookup-0.1.1/src/ontology_lookup.egg-info/requires.txt +11 -0
- ontology_lookup-0.1.1/src/ontology_lookup.egg-info/top_level.txt +1 -0
- ontology_lookup-0.1.1/tests/test_api.py +307 -0
- ontology_lookup-0.1.1/tests/test_loader.py +195 -0
- ontology_lookup-0.1.1/tests/test_manager.py +388 -0
- ontology_lookup-0.1.1/tests/test_schema_and_db.py +162 -0
- ontology_lookup-0.1.1/tests/test_service.py +265 -0
|
@@ -0,0 +1,1051 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: ontology-lookup
|
|
3
|
+
Version: 0.1.1
|
|
4
|
+
Summary: High-performance, size-optimized local ontology lookup engine
|
|
5
|
+
Requires-Python: >=3.10
|
|
6
|
+
Description-Content-Type: text/markdown
|
|
7
|
+
Requires-Dist: fastapi>=0.100.0
|
|
8
|
+
Requires-Dist: uvicorn>=0.20.0
|
|
9
|
+
Requires-Dist: pydantic>=2.0.0
|
|
10
|
+
Requires-Dist: ijson>=3.3.0
|
|
11
|
+
Requires-Dist: python-dotenv>=1.0.0
|
|
12
|
+
Requires-Dist: cachetools>=5.3.0
|
|
13
|
+
Provides-Extra: dev
|
|
14
|
+
Requires-Dist: pytest>=8.0.0; extra == "dev"
|
|
15
|
+
Requires-Dist: httpx>=0.27.0; extra == "dev"
|
|
16
|
+
Requires-Dist: ruff>=0.4.0; extra == "dev"
|
|
17
|
+
|
|
18
|
+
# Ontology Lookup: High-Performance Multi-Ontology Engine
|
|
19
|
+
|
|
20
|
+
A high-performance, size-optimized local ontology lookup engine, Python library, and REST API built with **Python**, **SQLite (FTS5 + WAL)**, and **FastAPI**.
|
|
21
|
+
|
|
22
|
+
Designed for biological and scientific ontologies (such as HUPO PSI-MS, EDAM, OBI, GO, EFO, ChEBI, CL, DOID) hosted on EMBL-EBI OLS4 or OBO Foundry, this engine provides sub-millisecond, case-insensitive query resolution, hierarchical graph traversal, and concurrent read scalability.
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## Table of Contents
|
|
27
|
+
|
|
28
|
+
1. [Installation, Development and Test](#installation-development-and-test)
|
|
29
|
+
2. [Architecture and Design](#architecture-and-design)
|
|
30
|
+
3. [Download ontology sources from OLS4](#download-ontology-sources-from-ols4)
|
|
31
|
+
4. [Build Multi-ontology Lookup Database](#build-multi-ontology-lookup-database)
|
|
32
|
+
- [CLI Commands](#cli-build-and-database-management)
|
|
33
|
+
- [Create Database](#1-create-database-cli)
|
|
34
|
+
- [Add Ontologies](#2-add-ontologies-cli)
|
|
35
|
+
- [Delete Ontologies](#3-delete-ontologies-cli)
|
|
36
|
+
- [Add, Update, and Delete Term Tags](#4-addupdatedelete-term-tags-cli)
|
|
37
|
+
- [Inspect Database and Ontologies](#5-inspect-database-and-ontologies-cli)
|
|
38
|
+
- [Python API](#python-api-build-and-database-management)
|
|
39
|
+
- [Create Database](#1-create-database-api)
|
|
40
|
+
- [Add Ontologies](#2-add-ontologies-api)
|
|
41
|
+
- [Delete Ontologies](#3-delete-ontologies-api)
|
|
42
|
+
- [Add, Update, and Delete Term Tags](#4-addupdatedelete-term-tags-api)
|
|
43
|
+
- [Inspect Database and Ontologies](#5-inspect-database-and-ontologies-api)
|
|
44
|
+
5. [Search on Multi-ontology Lookup Database](#search-on-multi-ontology-lookup-database)
|
|
45
|
+
- [Starting the REST API Server](#starting-the-rest-api-server)
|
|
46
|
+
- [API Endpoints Reference Table](#api-endpoints-reference-table)
|
|
47
|
+
- [Use Case 1: Term Lookup by CURIE or IRI (Accession)](#use-case-1-term-lookup-by-curie-or-iri-accession)
|
|
48
|
+
- [Use Case 2: Exact Label Match](#use-case-2-exact-label-match)
|
|
49
|
+
- [Use Case 3: Exact Match Search across Labels and Synonyms](#use-case-3-exact-match-search-across-labels-and-synonyms)
|
|
50
|
+
- [Use Case 4: Hierarchy-Constrained Search (Parent CURIE Filter)](#use-case-4-hierarchy-constrained-search-parent-curie-filter)
|
|
51
|
+
- [Use Case 5: CURIE and IRI Resolution](#use-case-5-curie-and-iri-resolution)
|
|
52
|
+
- [Use Case 6: Key-Value Metadata Tag Search](#use-case-6-key-value-metadata-tag-search)
|
|
53
|
+
- [Use Case 7: Recursive Descendants / Children Lookup](#use-case-7-recursive-descendants--children-lookup)
|
|
54
|
+
- [Use Case 8: Freetext Search (Labels, Synonyms, and Definitions)](#use-case-8-freetext-search-labels-synonyms-and-definitions)
|
|
55
|
+
|
|
56
|
+
---
|
|
57
|
+
|
|
58
|
+
## Installation, Development and Test
|
|
59
|
+
|
|
60
|
+
This project requires **Python >= 3.10** and uses [`uv`](https://docs.astral.sh/uv/) for fast, reproducible dependency management and environment isolation.
|
|
61
|
+
|
|
62
|
+
### 1. Installation
|
|
63
|
+
|
|
64
|
+
Clone the repository and install all dependencies:
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
# Clone the repository
|
|
68
|
+
git clone https://github.com/your-org/ontology_lookup.git
|
|
69
|
+
cd ontology_lookup
|
|
70
|
+
|
|
71
|
+
# Sync virtual environment and install dependencies with uv
|
|
72
|
+
uv sync
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Alternatively, install in development mode with standard `pip`:
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
pip install -e ".[dev]"
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
### 2. Environment Configuration
|
|
82
|
+
|
|
83
|
+
Default paths and ingestion parameters are managed via a `.env` file. Copy `.env.example` to start:
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
cp .env.example .env
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
Configurable variables:
|
|
90
|
+
|
|
91
|
+
| Variable | Default Value | Description |
|
|
92
|
+
| --- | --- | --- |
|
|
93
|
+
| `ONTOLOGY_SOURCE_DIR` | `.cache/ontology_jsons` | Default directory containing OLS4 ontology JSON files |
|
|
94
|
+
| `ONTOLOGY_DB_PATH` | `.db/ontology_lookup.db` | Target SQLite database file path |
|
|
95
|
+
| `ONTOLOGY_BATCH_SIZE` | `5000` | SQLite batch insert transaction chunk size |
|
|
96
|
+
| `ONTOLOGY_PARENT_TERMS` | `MS:1000031,MS:1000076,MS:1000008,MS:1003761,...` | Comma-separated target parent CURIEs precomputed for transitive closure lookups |
|
|
97
|
+
|
|
98
|
+
> **Precedence Order**: Command-line flags (e.g. `--db`, `--dir`) override process environment variables, which override values in `.env`.
|
|
99
|
+
|
|
100
|
+
### 3. Development & Quality Checks
|
|
101
|
+
|
|
102
|
+
Run Ruff linter, formatting checks, and pre-commit hooks:
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
# Run Ruff linting
|
|
106
|
+
uv run ruff check .
|
|
107
|
+
|
|
108
|
+
# Automatically apply safe fixes
|
|
109
|
+
uv run ruff check --fix .
|
|
110
|
+
|
|
111
|
+
# Check formatting
|
|
112
|
+
uv run ruff format --check .
|
|
113
|
+
|
|
114
|
+
# Format code
|
|
115
|
+
uv run ruff format .
|
|
116
|
+
|
|
117
|
+
# Install pre-commit hooks
|
|
118
|
+
uv run pre-commit install
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
### 4. Running Tests
|
|
122
|
+
|
|
123
|
+
Run the full test suite across the loader, database manager, query service, and REST API:
|
|
124
|
+
|
|
125
|
+
```bash
|
|
126
|
+
# Run all unit and integration tests
|
|
127
|
+
uv run pytest -v
|
|
128
|
+
|
|
129
|
+
# Run tests with short summary output
|
|
130
|
+
uv run pytest -q
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
---
|
|
134
|
+
|
|
135
|
+
## Architecture and Design
|
|
136
|
+
|
|
137
|
+
```
|
|
138
|
+
+---------------------------------------+
|
|
139
|
+
| OLS4 Compressed Source Dumps |
|
|
140
|
+
| (https://ftp.ebi.ac.uk/.../*.tgz) |
|
|
141
|
+
+-------------------+-------------------+
|
|
142
|
+
|
|
|
143
|
+
v (download & unpack)
|
|
144
|
+
+---------------------------------------+
|
|
145
|
+
| Local Cache: .cache/ontology_jsons/ |
|
|
146
|
+
| ms.json, edam.json, obi.json ... |
|
|
147
|
+
+-------------------+-------------------+
|
|
148
|
+
|
|
|
149
|
+
v
|
|
150
|
+
+---------------------------------------+
|
|
151
|
+
| Streaming Ingestion (ijson) |
|
|
152
|
+
| - Memory-bounded JSON streaming |
|
|
153
|
+
| - Transitive closure precomputation |
|
|
154
|
+
| - Leaf node detection (is_leaf tag) |
|
|
155
|
+
| - Metadata tag normalization |
|
|
156
|
+
+-------------------+-------------------+
|
|
157
|
+
|
|
|
158
|
+
v (Batch Ingest + WAL)
|
|
159
|
+
+-------------------------------------------------------+
|
|
160
|
+
| Optimized SQLite Database |
|
|
161
|
+
| +-------------------------------------------------+ |
|
|
162
|
+
| | terms: (curie, ontology PK, iri, label) | |
|
|
163
|
+
| | term_details (WITHOUT ROWID): | |
|
|
164
|
+
| | (curie, ontology, tag_key, tag_value PK) | |
|
|
165
|
+
| | terms_fts (FTS5 unicode61 porter): | |
|
|
166
|
+
| | (curie UNINDEXED, ontology UNINDEXED, ...) | |
|
|
167
|
+
| | ontologies: (ontology PK, name, prefix, counts) | |
|
|
168
|
+
| | database_info: (created_time, updated_time) | |
|
|
169
|
+
| +-------------------------------------------------+ |
|
|
170
|
+
+---------------------------+---------------------------+
|
|
171
|
+
|
|
|
172
|
+
+-----------------------+-----------------------+
|
|
173
|
+
| |
|
|
174
|
+
v (Direct / Embedded) v (Network / HTTP)
|
|
175
|
+
+-------------------------------+ +-------------------------------+
|
|
176
|
+
| OntologyLookupService | | FastAPI Web Service |
|
|
177
|
+
| - Reusable context manager | | - URI `mode=ro` concurrency |
|
|
178
|
+
| - B-Tree index scans (NOCASE)| | - 2 GB mmap_size |
|
|
179
|
+
| - Precomputed child-of tags | | - Sub-millisecond endpoints |
|
|
180
|
+
+-------------------------------+ +-------------------------------+
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
### Key Architectural Decisions
|
|
184
|
+
|
|
185
|
+
1. **Streaming Multi-Gigabyte Ingestion (`ijson`)**:
|
|
186
|
+
OLS4 ontology files (e.g., `chebi.json`, `ncbitaxon.json`, `pr.json`) range from several hundred megabytes to multiple gigabytes. The ingestion pipeline streams class nodes via `ijson.items` to maintain a constant, low-memory footprint regardless of file size.
|
|
187
|
+
|
|
188
|
+
2. **Cross-Ontology Referencing & Composite Primary Key (`curie, ontology`)**:
|
|
189
|
+
Ontologies frequently reference or import terms defined in other ontologies (for instance, `ms.json` references `OBI:0200114` and `UO:0000001` which are also defined in `obi.json` and `uo.json`). In the `terms` table, the composite primary key `(curie, ontology)` guarantees that every term is uniquely tracked within each referencing ontology, preserving ontology-specific labels, definitions, and relationships without collision. `term_details` similarly links via `FOREIGN KEY (curie, ontology) REFERENCES terms(curie, ontology) ON DELETE CASCADE`.
|
|
190
|
+
|
|
191
|
+
3. **Index-Organized Metadata (`WITHOUT ROWID`)**:
|
|
192
|
+
Metadata tags (`synonym`, `child-of`, `obsolete`, `is_leaf`, `definition`) are stored in `term_details` with a composite primary key `(curie, ontology, tag_key, tag_value)`. Eliminating the standard 64-bit SQLite integer rowid cuts index overhead in half and clusters related tags contiguously on disk for blazing-fast sequential page reads.
|
|
193
|
+
|
|
194
|
+
4. **Case-Insensitive Zero-Cost Matching (`COLLATE NOCASE`)**:
|
|
195
|
+
All identifier and text columns use SQLite's native `COLLATE NOCASE`. Queries match mixed-cased CURIEs (e.g. `ms:1000031` vs `MS:1000031`) or labels via instant B-Tree index lookups without calling `LOWER()` at runtime.
|
|
196
|
+
|
|
197
|
+
5. **Full-Text Autocomplete & Relevance Search (`FTS5`)**:
|
|
198
|
+
SQLite's FTS5 engine (`unicode61` tokenizer with Porter stemming) indexes term labels, synonyms, and definitions with unindexed `ontology` scoping. It enables prefix matching, ranking, and tokenization without requiring external search daemons (e.g. Elasticsearch).
|
|
199
|
+
|
|
200
|
+
6. **Infinite Read Concurrency (WAL + URI `mode=ro` + `mmap`)**:
|
|
201
|
+
- Write-Ahead Logging (`PRAGMA journal_mode = WAL;`) allows readers and writers to operate concurrently without locking.
|
|
202
|
+
- Read-only connections (`file:db.sqlite?mode=ro`) bypass write-lock coordination.
|
|
203
|
+
- `PRAGMA mmap_size = 2147483648;` memory-maps up to 2GB of the database directly into the OS page cache for sub-millisecond retrieval.
|
|
204
|
+
- FastAPI executes synchronous query endpoints in worker thread pools to handle hundreds of concurrent requests efficiently.
|
|
205
|
+
|
|
206
|
+
---
|
|
207
|
+
|
|
208
|
+
## Download ontology sources from OLS4
|
|
209
|
+
|
|
210
|
+
The EMBL-EBI Ontology Lookup Service (OLS4) distributes standardized JSON representations of all hosted ontologies.
|
|
211
|
+
|
|
212
|
+
- **Direct Download URL**: [https://ftp.ebi.ac.uk/pub/databases/spot/ols/latest/ontology_jsons.tgz](https://ftp.ebi.ac.uk/pub/databases/spot/ols/latest/ontology_jsons.tgz)
|
|
213
|
+
- **Default Local Location**: `.cache/ontology_jsons`
|
|
214
|
+
|
|
215
|
+
### 1. Download and Extract the Archive
|
|
216
|
+
|
|
217
|
+
Execute the following commands to download and unpack the ontology JSON files into the `.cache` directory:
|
|
218
|
+
|
|
219
|
+
```bash
|
|
220
|
+
# 1. Create target download directory
|
|
221
|
+
mkdir -p .cache
|
|
222
|
+
|
|
223
|
+
# 2. Download the compressed archive
|
|
224
|
+
curl -L https://ftp.ebi.ac.uk/pub/databases/spot/ols/latest/ontology_jsons.tgz -o .cache/ontology_jsons.tgz
|
|
225
|
+
|
|
226
|
+
# 3. Extract the archive into .cache/
|
|
227
|
+
tar -xzf .cache/ontology_jsons.tgz -C .cache/
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
After extraction, the `.cache/ontology_jsons/` directory will contain individual JSON files named by ontology short name:
|
|
231
|
+
|
|
232
|
+
```text
|
|
233
|
+
.cache/ontology_jsons/
|
|
234
|
+
├── ms.json (Mass Spectrometry Controlled Vocabulary)
|
|
235
|
+
├── edam.json (EDAM Bioinformatics operations, data, formats)
|
|
236
|
+
├── obi.json (Ontology for Biomedical Investigations)
|
|
237
|
+
├── bto.json (BRENDA Tissue Ontology)
|
|
238
|
+
├── cl.json (Cell Ontology)
|
|
239
|
+
├── clo.json (Cell Line Ontology)
|
|
240
|
+
├── chmo.json (Chemical Methods Ontology)
|
|
241
|
+
├── go.json (Gene Ontology)
|
|
242
|
+
└── ... (over 350+ ontologies)
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
### 2. Verify Available Ontologies
|
|
246
|
+
|
|
247
|
+
Use the CLI to inspect available JSON sources in `.cache/ontology_jsons`:
|
|
248
|
+
|
|
249
|
+
```bash
|
|
250
|
+
uv run ontology-lookup list-ontologies --available --dir .cache/ontology_jsons
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
---
|
|
254
|
+
|
|
255
|
+
## Build Multi-ontology Lookup Database
|
|
256
|
+
|
|
257
|
+
The lookup engine provides both **Command-Line Interface (CLI)** and **Python Library API** for creating databases, adding ontologies, deleting ontologies, and managing custom term tags.
|
|
258
|
+
|
|
259
|
+
### CLI: Build and Database Management
|
|
260
|
+
|
|
261
|
+
All CLI operations are invoked via `uv run ontology-lookup` (or `ontology-lookup` if installed in your environment).
|
|
262
|
+
|
|
263
|
+
#### 1. Create Database (CLI)
|
|
264
|
+
|
|
265
|
+
Initialize a new multi-ontology SQLite database from JSON files in the source directory.
|
|
266
|
+
|
|
267
|
+
```bash
|
|
268
|
+
# Build database with core proteomics and biological ontologies:
|
|
269
|
+
uv run ontology-lookup admin init-db \
|
|
270
|
+
--dir .cache/ontology_jsons \
|
|
271
|
+
--ontologies ms,edam,obi,msio \
|
|
272
|
+
--db .db/ontology_lookup.db \
|
|
273
|
+
--clean
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
Parameters:
|
|
277
|
+
|
|
278
|
+
- `--dir`, `-i`: Directory containing ontology JSON files (default: `.cache/ontology_jsons`).
|
|
279
|
+
- `--ontologies`, `-o`: Comma-separated list of short names to ingest (e.g. `ms,edam,obi`). If omitted, all `*.json` files found in the directory are loaded.
|
|
280
|
+
- `--db`, `-d`: Target SQLite database path (default: `.db/ontology_lookup.db`).
|
|
281
|
+
- `--parents`, `-p`: Comma-separated target parent CURIEs for precomputing recursive `child-of` links.
|
|
282
|
+
- `--clean`: Recreates the database from scratch, removing any existing file.
|
|
283
|
+
- `--batch-size`, `-b`: Insert chunk size (default: `5000`).
|
|
284
|
+
|
|
285
|
+
Alternatively, build a database from a single standalone JSON file:
|
|
286
|
+
|
|
287
|
+
```bash
|
|
288
|
+
uv run ontology-lookup admin build \
|
|
289
|
+
--source .cache/ontology_jsons/ms.json \
|
|
290
|
+
--ontology ms \
|
|
291
|
+
--db .db/ontology_lookup.db \
|
|
292
|
+
--clean
|
|
293
|
+
```
|
|
294
|
+
|
|
295
|
+
#### 2. Add Ontologies (CLI)
|
|
296
|
+
|
|
297
|
+
Add or refresh an individual ontology in an existing database without modifying other ontologies:
|
|
298
|
+
|
|
299
|
+
```bash
|
|
300
|
+
# Add or update 'bto' (BRENDA Tissue Ontology) from source directory:
|
|
301
|
+
uv run ontology-lookup admin update-ontology \
|
|
302
|
+
--name bto \
|
|
303
|
+
--dir .cache/ontology_jsons \
|
|
304
|
+
--db .db/ontology_lookup.db
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
Or provide an explicit JSON file path:
|
|
308
|
+
|
|
309
|
+
```bash
|
|
310
|
+
uv run ontology-lookup admin update-ontology \
|
|
311
|
+
--name cl \
|
|
312
|
+
--source /path/to/custom_cl.json \
|
|
313
|
+
--db .db/ontology_lookup.db
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
#### 3. Delete Ontologies (CLI)
|
|
317
|
+
|
|
318
|
+
Completely delete an ontology, its terms, hierarchy links, tags, and full-text search entries:
|
|
319
|
+
|
|
320
|
+
```bash
|
|
321
|
+
# Delete 'obi' from the database:
|
|
322
|
+
uv run ontology-lookup admin delete-ontology \
|
|
323
|
+
--name obi \
|
|
324
|
+
--db .db/ontology_lookup.db
|
|
325
|
+
```
|
|
326
|
+
|
|
327
|
+
#### 4. Add/Update/Delete Term Tags (CLI)
|
|
328
|
+
|
|
329
|
+
Tags allow associating arbitrary key-value metadata (e.g. curation flags, custom categories, sub-classifications) with specific terms. An optional `--ontology / -o` flag allows scoping the tag to a specific ontology representation of the term.
|
|
330
|
+
|
|
331
|
+
```bash
|
|
332
|
+
# Add a custom tag to a term (optionally scoped with -o ms):
|
|
333
|
+
uv run ontology-lookup admin add-tag \
|
|
334
|
+
--curie MS:1000031 \
|
|
335
|
+
--key custom_category \
|
|
336
|
+
--value instrumentation \
|
|
337
|
+
--ontology ms \
|
|
338
|
+
--db .db/ontology_lookup.db
|
|
339
|
+
|
|
340
|
+
# Update an existing tag value:
|
|
341
|
+
uv run ontology-lookup admin update-tag \
|
|
342
|
+
--curie MS:1000031 \
|
|
343
|
+
--key custom_category \
|
|
344
|
+
--value core_hardware \
|
|
345
|
+
--old-value instrumentation \
|
|
346
|
+
--ontology ms \
|
|
347
|
+
--db .db/ontology_lookup.db
|
|
348
|
+
|
|
349
|
+
# Delete a specific tag value:
|
|
350
|
+
uv run ontology-lookup admin delete-tag \
|
|
351
|
+
--curie MS:1000031 \
|
|
352
|
+
--key custom_category \
|
|
353
|
+
--value core_hardware \
|
|
354
|
+
--ontology ms \
|
|
355
|
+
--db .db/ontology_lookup.db
|
|
356
|
+
|
|
357
|
+
# Delete all tags matching a key for a term:
|
|
358
|
+
uv run ontology-lookup admin delete-tag \
|
|
359
|
+
--curie MS:1000031 \
|
|
360
|
+
--key custom_category \
|
|
361
|
+
--db .db/ontology_lookup.db
|
|
362
|
+
```
|
|
363
|
+
|
|
364
|
+
#### 5. Inspect Database and Ontologies (CLI)
|
|
365
|
+
|
|
366
|
+
```bash
|
|
367
|
+
# List all installed ontologies, term counts, versions, and IRI prefixes:
|
|
368
|
+
uv run ontology-lookup list-ontologies --db .db/ontology_lookup.db
|
|
369
|
+
|
|
370
|
+
# View database creation and last-updated metadata:
|
|
371
|
+
uv run ontology-lookup database-info --db .db/ontology_lookup.db
|
|
372
|
+
```
|
|
373
|
+
|
|
374
|
+
---
|
|
375
|
+
|
|
376
|
+
### Python API: Build and Database Management
|
|
377
|
+
|
|
378
|
+
The `OntologyDatabaseManager` ([src/ontology_lookup/manager.py](src/ontology_lookup/manager.py)) class provides programmatic control over database lifecycle operations.
|
|
379
|
+
|
|
380
|
+
#### 1. Create Database (API)
|
|
381
|
+
|
|
382
|
+
```python
|
|
383
|
+
from ontology_lookup.manager import OntologyDatabaseManager, create_database
|
|
384
|
+
|
|
385
|
+
# Option A: Using the OntologyDatabaseManager class
|
|
386
|
+
mgr = OntologyDatabaseManager(
|
|
387
|
+
db_path=".db/ontology_lookup.db",
|
|
388
|
+
default_input_dir=".cache/ontology_jsons",
|
|
389
|
+
batch_size=5000,
|
|
390
|
+
)
|
|
391
|
+
|
|
392
|
+
# Load selected ontologies (or pass ontologies=None to load all available JSONs)
|
|
393
|
+
results = mgr.create_database(
|
|
394
|
+
source_dir=".cache/ontology_jsons",
|
|
395
|
+
ontologies=["ms", "edam", "obi"],
|
|
396
|
+
clean=True,
|
|
397
|
+
)
|
|
398
|
+
print("Ingestion results:", results)
|
|
399
|
+
# Output: {'ms': {'terms': 3542, 'details': 15230}, 'edam': {'terms': 3820, 'details': 12400}, ...}
|
|
400
|
+
|
|
401
|
+
# Option B: Using the module-level helper function
|
|
402
|
+
results = create_database(
|
|
403
|
+
db_path=".db/ontology_lookup.db",
|
|
404
|
+
source_dir=".cache/ontology_jsons",
|
|
405
|
+
ontologies=["ms", "edam"],
|
|
406
|
+
clean=True,
|
|
407
|
+
)
|
|
408
|
+
```
|
|
409
|
+
|
|
410
|
+
#### 2. Add Ontologies (API)
|
|
411
|
+
|
|
412
|
+
**Python API**:
|
|
413
|
+
|
|
414
|
+
```python
|
|
415
|
+
from ontology_lookup.manager import OntologyDatabaseManager
|
|
416
|
+
|
|
417
|
+
mgr = OntologyDatabaseManager(db_path=".db/ontology_lookup.db")
|
|
418
|
+
|
|
419
|
+
# Ingest or update 'chmo' from default source directory:
|
|
420
|
+
terms_count, details_count = mgr.update_ontology(
|
|
421
|
+
ontology_name="chmo",
|
|
422
|
+
source_dir=".cache/ontology_jsons",
|
|
423
|
+
)
|
|
424
|
+
print(f"Added CHMO: {terms_count} terms, {details_count} details.")
|
|
425
|
+
|
|
426
|
+
# Ingest from an explicit file path:
|
|
427
|
+
terms, details = mgr.load_file(
|
|
428
|
+
file_path=".cache/ontology_jsons/bto.json",
|
|
429
|
+
ontology_name="bto",
|
|
430
|
+
)
|
|
431
|
+
```
|
|
432
|
+
|
|
433
|
+
**REST API**:
|
|
434
|
+
|
|
435
|
+
```bash
|
|
436
|
+
# Add or refresh 'chmo' from default source directory
|
|
437
|
+
curl -X POST "http://localhost:8000/ontologies/chmo"
|
|
438
|
+
|
|
439
|
+
# Add or update from specific source directory
|
|
440
|
+
curl -X PUT "http://localhost:8000/ontologies/bto?source_dir=.cache/ontology_jsons"
|
|
441
|
+
```
|
|
442
|
+
|
|
443
|
+
#### 3. Delete Ontologies (API)
|
|
444
|
+
|
|
445
|
+
**Python API**:
|
|
446
|
+
|
|
447
|
+
```python
|
|
448
|
+
from ontology_lookup.manager import OntologyDatabaseManager
|
|
449
|
+
|
|
450
|
+
mgr = OntologyDatabaseManager(db_path=".db/ontology_lookup.db")
|
|
451
|
+
|
|
452
|
+
# Completely remove an ontology and all its associated terms, details, and FTS entries:
|
|
453
|
+
removed_terms = mgr.delete_ontology("obi")
|
|
454
|
+
print(f"Removed {removed_terms} terms from the database.")
|
|
455
|
+
```
|
|
456
|
+
|
|
457
|
+
**REST API**:
|
|
458
|
+
|
|
459
|
+
```bash
|
|
460
|
+
# Delete ontology 'obi' and all its terms/details
|
|
461
|
+
curl -X DELETE "http://localhost:8000/ontologies/obi"
|
|
462
|
+
```
|
|
463
|
+
|
|
464
|
+
#### 4. Add/Update/Delete Term Tags (API)
|
|
465
|
+
|
|
466
|
+
**Python API**:
|
|
467
|
+
|
|
468
|
+
```python
|
|
469
|
+
from ontology_lookup.manager import OntologyDatabaseManager
|
|
470
|
+
|
|
471
|
+
mgr = OntologyDatabaseManager(db_path=".db/ontology_lookup.db")
|
|
472
|
+
|
|
473
|
+
# 1. Add custom tag to term (optionally scoped to a specific ontology)
|
|
474
|
+
success = mgr.add_term_tag(
|
|
475
|
+
curie="MS:1000031",
|
|
476
|
+
tag_key="curation_status",
|
|
477
|
+
tag_value="verified",
|
|
478
|
+
ontology="ms",
|
|
479
|
+
)
|
|
480
|
+
|
|
481
|
+
# 2. Update tag value
|
|
482
|
+
mgr.update_term_tag(
|
|
483
|
+
curie="MS:1000031",
|
|
484
|
+
tag_key="curation_status",
|
|
485
|
+
new_value="approved",
|
|
486
|
+
old_value="verified",
|
|
487
|
+
ontology="ms",
|
|
488
|
+
)
|
|
489
|
+
|
|
490
|
+
# 3. Delete tag
|
|
491
|
+
mgr.delete_term_tag(
|
|
492
|
+
curie="MS:1000031",
|
|
493
|
+
tag_key="curation_status",
|
|
494
|
+
tag_value="approved",
|
|
495
|
+
ontology="ms",
|
|
496
|
+
)
|
|
497
|
+
```
|
|
498
|
+
|
|
499
|
+
**REST API**:
|
|
500
|
+
|
|
501
|
+
```bash
|
|
502
|
+
# 1. Add tag to term (accepts optional ?ontology=ms query parameter)
|
|
503
|
+
curl -X POST "http://localhost:8000/terms/MS:1000031/tags?ontology=ms" \
|
|
504
|
+
-H "Content-Type: application/json" \
|
|
505
|
+
-d '{"tag_key": "curation_status", "tag_value": "verified"}'
|
|
506
|
+
|
|
507
|
+
# 2. Update existing tag value
|
|
508
|
+
curl -X PUT "http://localhost:8000/terms/MS:1000031/tags/curation_status?ontology=ms" \
|
|
509
|
+
-H "Content-Type: application/json" \
|
|
510
|
+
-d '{"tag_value": "approved", "old_value": "verified"}'
|
|
511
|
+
|
|
512
|
+
# 3. Delete specific tag value
|
|
513
|
+
curl -X DELETE "http://localhost:8000/terms/MS:1000031/tags/curation_status?tag_value=approved&ontology=ms"
|
|
514
|
+
|
|
515
|
+
# 4. Delete all tags matching tag_key for the term
|
|
516
|
+
curl -X DELETE "http://localhost:8000/terms/MS:1000031/tags/curation_status"
|
|
517
|
+
```
|
|
518
|
+
|
|
519
|
+
#### 5. Inspect Database and Ontologies (API)
|
|
520
|
+
|
|
521
|
+
**Python API**:
|
|
522
|
+
|
|
523
|
+
```python
|
|
524
|
+
from ontology_lookup.manager import OntologyDatabaseManager
|
|
525
|
+
|
|
526
|
+
mgr = OntologyDatabaseManager(db_path=".db/ontology_lookup.db")
|
|
527
|
+
|
|
528
|
+
# List installed ontologies and summary counts
|
|
529
|
+
installed = mgr.list_installed_ontologies()
|
|
530
|
+
for ont in installed:
|
|
531
|
+
print(f"{ont['ontology']} (v{ont['version']}): {ont['num_of_terms']} terms")
|
|
532
|
+
|
|
533
|
+
# Inspect database timestamp info
|
|
534
|
+
info = mgr.get_database_info()
|
|
535
|
+
print(f"Created: {info['created_time']}, Updated: {info['updated_time']}")
|
|
536
|
+
```
|
|
537
|
+
|
|
538
|
+
**REST API**:
|
|
539
|
+
|
|
540
|
+
```bash
|
|
541
|
+
# List all installed ontologies
|
|
542
|
+
curl -X GET "http://localhost:8000/ontologies"
|
|
543
|
+
|
|
544
|
+
# Get metadata for a specific ontology
|
|
545
|
+
curl -X GET "http://localhost:8000/ontologies/ms"
|
|
546
|
+
|
|
547
|
+
# Inspect database metadata
|
|
548
|
+
curl -X GET "http://localhost:8000/info"
|
|
549
|
+
```
|
|
550
|
+
|
|
551
|
+
---
|
|
552
|
+
|
|
553
|
+
## Search on Multi-ontology Lookup Database
|
|
554
|
+
|
|
555
|
+
The query layer supports **8 primary use cases** available via both the **CLI** and **API** (Python service + REST HTTP endpoints).
|
|
556
|
+
The `search` and `freetext-search` use cases accept multiple ontology filters: pass comma-separated names in the CLI, a list in Python, or repeat the `ontology` query parameter in HTTP requests.
|
|
557
|
+
|
|
558
|
+
### Starting the REST API Server
|
|
559
|
+
|
|
560
|
+
To enable HTTP access to your database, start the FastAPI server:
|
|
561
|
+
|
|
562
|
+
```bash
|
|
563
|
+
uv run ontology-lookup serve --db .db/ontology_lookup.db --host 0.0.0.0 --port 8000
|
|
564
|
+
```
|
|
565
|
+
|
|
566
|
+
Interactive OpenAPI documentation and Swagger UI will be available at:
|
|
567
|
+
|
|
568
|
+
- **Swagger UI**: `http://localhost:8000/docs`
|
|
569
|
+
- **ReDoc UI**: `http://localhost:8000/redoc`
|
|
570
|
+
|
|
571
|
+
### API Endpoints Reference Table
|
|
572
|
+
|
|
573
|
+
| Endpoint | HTTP Method | Query / Path / Body Parameters | Description |
|
|
574
|
+
| --- | --- | --- | --- |
|
|
575
|
+
| `/terms/{accession}` | `GET` | `accession` (path), `ontology` (opt) | Lookup term by CURIE or full IRI (case-insensitive) |
|
|
576
|
+
| `/terms/{accession}/tags` | `POST` | `accession` (path), body `{"tag_key", "tag_value"}` | Add a key-value tag to a term |
|
|
577
|
+
| `/terms/{accession}/tags/{tag_key}` | `PUT` | `accession` (path), `tag_key` (path), body `{"tag_value", "old_value"}` | Update a tag value for a term |
|
|
578
|
+
| `/terms/{accession}/tags/{tag_key}` | `DELETE` | `accession` (path), `tag_key` (path), `tag_value` (opt query) | Delete one or all tags matching key for a term |
|
|
579
|
+
| `/ontologies/{ontology}/terms/{accession}` | `GET` | `ontology` (path), `accession` (path) | Scoped lookup within explicit ontology |
|
|
580
|
+
| `/search/exact` | `GET` | `ontology`, `label` | Exact match lookup on term label |
|
|
581
|
+
| `/search` | `GET` | `q`, `search_in_synonyms`, repeatable `ontology` and `parent_curie`, `limit`, `offset` | Case-insensitive exact match on labels or synonyms |
|
|
582
|
+
| `/search/freetext` | `GET` | `q`, repeatable `ontology` and `parent_curie`, `limit`, `offset` | Ranked freetext search across labels, synonyms, and definitions |
|
|
583
|
+
| `/search/tags` | `GET` | `tag_key`, `tag_value`, `ontology` (opt), `limit`, `offset` | Search terms by metadata tags (e.g. `is_leaf`, `obsolete`) |
|
|
584
|
+
| `/resolve/curie` | `GET` | `iri`, `ontology` (opt) | Resolve a full IRI back to its primary CURIE |
|
|
585
|
+
| `/resolve/iri` | `GET` | `curie`, `ontology` (opt) | Resolve a CURIE to its IRI |
|
|
586
|
+
| `/children/{parent_curie}` | `GET` | `parent_curie` (path), `ontology` (opt), `limit`, `offset` | Get all recursive descendants of a parent CURIE |
|
|
587
|
+
| `/parent-terms` | `GET` | *None* | List parent CURIEs referenced by indexed `child-of` tags |
|
|
588
|
+
| `/ontologies` | `GET` | *None* | List installed ontologies with version, terms, obsoletes, and details |
|
|
589
|
+
| `/ontologies/{ontology}` | `GET` | `ontology` (path) | Get metadata for a specific installed ontology |
|
|
590
|
+
| `/ontologies/{ontology}` | `POST` / `PUT` | `ontology` (path), `source_dir` (opt), `source_file` (opt) | Add or update an ontology from source JSON |
|
|
591
|
+
| `/ontologies/{ontology}` | `DELETE` | `ontology` (path) | Delete an ontology, its terms, hierarchy links, and FTS entries |
|
|
592
|
+
| `/info` | `GET` | *None* | Retrieve database creation and last-updated metadata |
|
|
593
|
+
| `/health` | `GET` | *None* | Service health status and total terms count |
|
|
594
|
+
|
|
595
|
+
---
|
|
596
|
+
|
|
597
|
+
### Use Case 1: Term Lookup by CURIE or IRI (Accession)
|
|
598
|
+
|
|
599
|
+
Fetch the complete record for a term, including aggregated synonyms, hierarchy links (`children_of`), and metadata tags. Case-insensitive.
|
|
600
|
+
|
|
601
|
+
> [!NOTE]
|
|
602
|
+
> **Cross-Ontology Term Referencing**: When a term is referenced or imported by multiple ontologies (e.g. `OBI:0200114` is referenced in `ms` and defined in `obi`), specify `--ontology` to fetch the exact representation for that ontology.
|
|
603
|
+
|
|
604
|
+
#### CLI Examples
|
|
605
|
+
|
|
606
|
+
```bash
|
|
607
|
+
# Example 1: Lookup by CURIE
|
|
608
|
+
uv run ontology-lookup get-term-by-accession --ontology ms --accession MS:1000031 --db .db/ontology_lookup.db
|
|
609
|
+
|
|
610
|
+
# Example 2: Lookup by lowercase CURIE (case-insensitive)
|
|
611
|
+
uv run ontology-lookup get-term-by-accession --ontology ms --accession ms:1000449 --db .db/ontology_lookup.db
|
|
612
|
+
|
|
613
|
+
# Example 3: Lookup cross-referenced term in distinct ontologies
|
|
614
|
+
uv run ontology-lookup get-term-by-accession --ontology ms --accession OBI:0200114 --db .db/ontology_lookup.db
|
|
615
|
+
uv run ontology-lookup get-term-by-accession --ontology obi --accession OBI:0200114 --db .db/ontology_lookup.db
|
|
616
|
+
```
|
|
617
|
+
|
|
618
|
+
#### API Examples
|
|
619
|
+
|
|
620
|
+
```python
|
|
621
|
+
from ontology_lookup.service import OntologyLookupService
|
|
622
|
+
|
|
623
|
+
with OntologyLookupService(db_path=".db/ontology_lookup.db") as svc:
|
|
624
|
+
# Example 1: Lookup by CURIE
|
|
625
|
+
term1 = svc.get_term_by_accession(ontology="ms", accession="MS:1000031")
|
|
626
|
+
print(term1.label, term1.synonyms, term1.children_of)
|
|
627
|
+
|
|
628
|
+
# Example 2: Lookup by lowercase CURIE
|
|
629
|
+
term2 = svc.get_term_by_accession(ontology="ms", accession="ms:1000449")
|
|
630
|
+
print(term2.curie, term2.label)
|
|
631
|
+
|
|
632
|
+
# Example 3: Cross-referenced term lookup across ontologies
|
|
633
|
+
term_ms = svc.get_term_by_accession(ontology="ms", accession="OBI:0200114")
|
|
634
|
+
term_obi = svc.get_term_by_accession(ontology="obi", accession="OBI:0200114")
|
|
635
|
+
print(f"MS: {term_ms.curie} -> {term_ms.label}")
|
|
636
|
+
print(f"OBI: {term_obi.curie} -> {term_obi.label} (tags: {list(term_obi.tags.keys())})")
|
|
637
|
+
```
|
|
638
|
+
|
|
639
|
+
**REST API (HTTP)**:
|
|
640
|
+
|
|
641
|
+
```bash
|
|
642
|
+
# Example 1: Lookup by CURIE
|
|
643
|
+
curl -X GET "http://localhost:8000/terms/MS:1000031"
|
|
644
|
+
|
|
645
|
+
# Example 2: Lookup by lowercase CURIE with explicit ontology
|
|
646
|
+
curl -X GET "http://localhost:8000/ontologies/ms/terms/ms:1000449"
|
|
647
|
+
|
|
648
|
+
# Example 3: Cross-referenced term lookup in distinct ontologies
|
|
649
|
+
curl -X GET "http://localhost:8000/ontologies/ms/terms/OBI:0200114"
|
|
650
|
+
curl -X GET "http://localhost:8000/ontologies/obi/terms/OBI:0200114"
|
|
651
|
+
```
|
|
652
|
+
|
|
653
|
+
---
|
|
654
|
+
|
|
655
|
+
### Use Case 2: Exact Label Match
|
|
656
|
+
|
|
657
|
+
Look up a term by exact label within an ontology (case-insensitive).
|
|
658
|
+
|
|
659
|
+
#### CLI Examples
|
|
660
|
+
|
|
661
|
+
```bash
|
|
662
|
+
# Example 1: Exact instrument label (matches MS:1000031)
|
|
663
|
+
uv run ontology-lookup get-term-by-label --ontology ms --label "instrument model" --db .db/ontology_lookup.db
|
|
664
|
+
|
|
665
|
+
# Example 2: Case-insensitive label query (matches MS:1000449)
|
|
666
|
+
uv run ontology-lookup get-term-by-label --ontology ms --label "LTQ ORBITRAP" --db .db/ontology_lookup.db
|
|
667
|
+
|
|
668
|
+
# Example 3: Exact match in another ontology (matches OBI:0000070)
|
|
669
|
+
uv run ontology-lookup get-term-by-label --ontology obi --label "assay" --db .db/ontology_lookup.db
|
|
670
|
+
```
|
|
671
|
+
|
|
672
|
+
#### API Examples
|
|
673
|
+
|
|
674
|
+
```python
|
|
675
|
+
from ontology_lookup.service import OntologyLookupService
|
|
676
|
+
|
|
677
|
+
with OntologyLookupService(db_path=".db/ontology_lookup.db") as svc:
|
|
678
|
+
# Example 1: Exact label
|
|
679
|
+
term1 = svc.get_term_by_exact_label(ontology="ms", label="instrument model")
|
|
680
|
+
print(term1.curie, term1.label)
|
|
681
|
+
|
|
682
|
+
# Example 2: Case-insensitive label
|
|
683
|
+
term2 = svc.get_term_by_exact_label(ontology="ms", label="LTQ ORBITRAP")
|
|
684
|
+
print(term2.curie, term2.label)
|
|
685
|
+
|
|
686
|
+
# Example 3: Match in OBI
|
|
687
|
+
term3 = svc.get_term_by_exact_label(ontology="obi", label="assay")
|
|
688
|
+
print(term3.curie if term3 else "Not found")
|
|
689
|
+
```
|
|
690
|
+
|
|
691
|
+
**REST API (HTTP)**:
|
|
692
|
+
|
|
693
|
+
```bash
|
|
694
|
+
# Example 1: Exact label
|
|
695
|
+
curl -X GET "http://localhost:8000/search/exact?ontology=ms&label=instrument+model"
|
|
696
|
+
|
|
697
|
+
# Example 2: Case-insensitive uppercase label
|
|
698
|
+
curl -X GET "http://localhost:8000/search/exact?ontology=ms&label=LTQ+ORBITRAP"
|
|
699
|
+
|
|
700
|
+
# Example 3: Biological assay in OBI
|
|
701
|
+
curl -X GET "http://localhost:8000/search/exact?ontology=obi&label=assay"
|
|
702
|
+
```
|
|
703
|
+
|
|
704
|
+
---
|
|
705
|
+
|
|
706
|
+
### Use Case 3: Exact Match Search across Labels and Synonyms
|
|
707
|
+
|
|
708
|
+
Case-insensitive exact matching against complete labels and synonyms. Partial matches and definitions are excluded. Use `freetext-search` (Use Case 8) for ranked keyword and definition search. Optional ontology and parent CURIE filters can narrow the results.
|
|
709
|
+
|
|
710
|
+
#### CLI Examples
|
|
711
|
+
|
|
712
|
+
```bash
|
|
713
|
+
# Example 1: Match a complete label
|
|
714
|
+
uv run ontology-lookup search-by-label --label-or-synonym "orbitrap" -o ms --db .db/ontology_lookup.db
|
|
715
|
+
|
|
716
|
+
# Example 2: Query by synonym (e.g. 'MALDI' matches MS:1000031)
|
|
717
|
+
uv run ontology-lookup search-by-label --label-or-synonym "MALDI" -o ms --db .db/ontology_lookup.db
|
|
718
|
+
|
|
719
|
+
# Example 3: Exact label or synonym across multiple ontologies
|
|
720
|
+
uv run ontology-lookup search-by-label --label-or-synonym "instrument" -o ms,edam -l 10 --db .db/ontology_lookup.db
|
|
721
|
+
```
|
|
722
|
+
|
|
723
|
+
#### API Examples
|
|
724
|
+
|
|
725
|
+
```python
|
|
726
|
+
from ontology_lookup.service import OntologyLookupService
|
|
727
|
+
|
|
728
|
+
with OntologyLookupService(db_path=".db/ontology_lookup.db") as svc:
|
|
729
|
+
# Example 1: Search label
|
|
730
|
+
results1 = svc.search_by_label(label_or_synonym="orbitrap", ontology="ms", limit=5)
|
|
731
|
+
for r in results1:
|
|
732
|
+
print(f"[{r.curie}] {r.label}")
|
|
733
|
+
|
|
734
|
+
# Example 2: Search synonym
|
|
735
|
+
results2 = svc.search_by_label(label_or_synonym="MALDI", ontology="ms")
|
|
736
|
+
for r in results2:
|
|
737
|
+
print(f"[{r.curie}] {r.label}")
|
|
738
|
+
|
|
739
|
+
# Example 3: Exact match across multiple ontologies
|
|
740
|
+
results3 = svc.search_by_label(label_or_synonym="instrument", ontology=["ms", "edam"], limit=10)
|
|
741
|
+
print(f"Found {len(results3)} results")
|
|
742
|
+
```
|
|
743
|
+
|
|
744
|
+
**REST API (HTTP)**:
|
|
745
|
+
|
|
746
|
+
```bash
|
|
747
|
+
# Example 1: Query label
|
|
748
|
+
curl -X GET "http://localhost:8000/search?q=orbitrap&ontology=ms"
|
|
749
|
+
|
|
750
|
+
# Example 2: Query synonym
|
|
751
|
+
curl -X GET "http://localhost:8000/search?q=MALDI&ontology=ms"
|
|
752
|
+
|
|
753
|
+
# Example 3: Multi-ontology search with limit
|
|
754
|
+
curl -X GET "http://localhost:8000/search?q=instrument&ontology=ms&ontology=edam&limit=10"
|
|
755
|
+
```
|
|
756
|
+
|
|
757
|
+
---
|
|
758
|
+
|
|
759
|
+
### Use Case 4: Hierarchy-Constrained Search (Parent CURIE Filter)
|
|
760
|
+
|
|
761
|
+
Restrict exact label or synonym matches to descendants of specific parent terms using indexed hierarchy tags.
|
|
762
|
+
|
|
763
|
+
#### CLI Examples
|
|
764
|
+
|
|
765
|
+
```bash
|
|
766
|
+
# Example 1: Search only descendants of 'instrument model' (MS:1000031)
|
|
767
|
+
uv run ontology-lookup search-by-label --label-or-synonym "LTQ Orbitrap" -o ms -p MS:1000031 --db .db/ontology_lookup.db
|
|
768
|
+
|
|
769
|
+
# Example 2: Search within 'ionization type' (MS:1000008)
|
|
770
|
+
uv run ontology-lookup search-by-label --label-or-synonym "electrospray ionization" -o ms -p MS:1000008 --db .db/ontology_lookup.db
|
|
771
|
+
|
|
772
|
+
# Example 3: Filter across multiple parent CURIEs
|
|
773
|
+
uv run ontology-lookup search-by-label --label-or-synonym "MALDI" -o ms -p MS:1000031,MS:1000008 --db .db/ontology_lookup.db
|
|
774
|
+
```
|
|
775
|
+
|
|
776
|
+
#### API Examples
|
|
777
|
+
|
|
778
|
+
```python
|
|
779
|
+
from ontology_lookup.service import OntologyLookupService
|
|
780
|
+
|
|
781
|
+
with OntologyLookupService(db_path=".db/ontology_lookup.db") as svc:
|
|
782
|
+
# Example 1: Restrict search to instrument models
|
|
783
|
+
res1 = svc.search_by_label(
|
|
784
|
+
label_or_synonym="LTQ Orbitrap", ontology="ms", parent_curie="MS:1000031"
|
|
785
|
+
)
|
|
786
|
+
print(f"Found {len(res1)} matches under MS:1000031")
|
|
787
|
+
|
|
788
|
+
# Example 2: Search within ionization type hierarchy
|
|
789
|
+
res2 = svc.search_by_label(
|
|
790
|
+
label_or_synonym="electrospray ionization", ontology="ms", parent_curie="MS:1000008"
|
|
791
|
+
)
|
|
792
|
+
for r in res2:
|
|
793
|
+
print(r.curie, r.label)
|
|
794
|
+
|
|
795
|
+
# Example 3: Filter across multiple parent CURIEs
|
|
796
|
+
res3 = svc.search_by_label(
|
|
797
|
+
label_or_synonym="MALDI",
|
|
798
|
+
ontology=["ms"],
|
|
799
|
+
parent_curie=["MS:1000031", "MS:1000008"],
|
|
800
|
+
)
|
|
801
|
+
print(f"Multi-parent matches: {len(res3)}")
|
|
802
|
+
```
|
|
803
|
+
|
|
804
|
+
**REST API (HTTP)**:
|
|
805
|
+
|
|
806
|
+
```bash
|
|
807
|
+
# Example 1: Parent filter under instrument model
|
|
808
|
+
curl -X GET "http://localhost:8000/search?q=LTQ+Orbitrap&ontology=ms&parent_curie=MS:1000031"
|
|
809
|
+
|
|
810
|
+
# Example 2: Hierarchy filter under ionization type
|
|
811
|
+
curl -X GET "http://localhost:8000/search?q=electrospray+ionization&ontology=ms&parent_curie=MS:1000008"
|
|
812
|
+
|
|
813
|
+
# Example 3: Multiple parent CURIE filters
|
|
814
|
+
curl -X GET "http://localhost:8000/search?q=MALDI&ontology=ms&parent_curie=MS:1000031&parent_curie=MS:1000008"
|
|
815
|
+
```
|
|
816
|
+
|
|
817
|
+
---
|
|
818
|
+
|
|
819
|
+
### List Indexed Parent Terms
|
|
820
|
+
|
|
821
|
+
List the distinct parent CURIEs referenced by indexed `child-of` hierarchy tags:
|
|
822
|
+
|
|
823
|
+
```bash
|
|
824
|
+
uv run ontology-lookup list-parent-terms --db .db/ontology_lookup.db
|
|
825
|
+
```
|
|
826
|
+
|
|
827
|
+
The same use case is available from the Python service and REST API:
|
|
828
|
+
|
|
829
|
+
```python
|
|
830
|
+
from ontology_lookup.service import OntologyLookupService
|
|
831
|
+
|
|
832
|
+
with OntologyLookupService(db_path=".db/ontology_lookup.db") as svc:
|
|
833
|
+
for parent_curie in svc.get_indexed_parent_terms():
|
|
834
|
+
print(parent_curie)
|
|
835
|
+
```
|
|
836
|
+
|
|
837
|
+
```bash
|
|
838
|
+
curl -X GET "http://localhost:8000/parent-terms"
|
|
839
|
+
```
|
|
840
|
+
|
|
841
|
+
---
|
|
842
|
+
|
|
843
|
+
### Use Case 5: CURIE and IRI Resolution
|
|
844
|
+
|
|
845
|
+
Map bidirectional relationships between persistent IRIs and compact CURIE accessions.
|
|
846
|
+
|
|
847
|
+
#### CLI Examples
|
|
848
|
+
|
|
849
|
+
```bash
|
|
850
|
+
# Example 1: Resolve full IRI to CURIE
|
|
851
|
+
uv run ontology-lookup iri-to-curie --iri "http://purl.obolibrary.org/obo/MS_1000031" --ontology ms --db .db/ontology_lookup.db
|
|
852
|
+
|
|
853
|
+
# Example 2: Resolve CURIE to IRI
|
|
854
|
+
uv run ontology-lookup curie-to-iri --curie "MS:1000031" --ontology ms --db .db/ontology_lookup.db
|
|
855
|
+
|
|
856
|
+
# Example 3: Resolve IRI across entire database (unscoped)
|
|
857
|
+
uv run ontology-lookup iri-to-curie --iri "http://edamontology.org/format_1915" --db .db/ontology_lookup.db
|
|
858
|
+
```
|
|
859
|
+
|
|
860
|
+
#### API Examples
|
|
861
|
+
|
|
862
|
+
```python
|
|
863
|
+
from ontology_lookup.service import OntologyLookupService
|
|
864
|
+
|
|
865
|
+
with OntologyLookupService(db_path=".db/ontology_lookup.db") as svc:
|
|
866
|
+
# Example 1: IRI to CURIE
|
|
867
|
+
res1 = svc.find_curie(iri="http://purl.obolibrary.org/obo/MS_1000031", ontology="ms")
|
|
868
|
+
print(f"CURIE: {res1.curie if res1 else 'Not found'}")
|
|
869
|
+
|
|
870
|
+
# Example 2: CURIE to IRI
|
|
871
|
+
res2 = svc.find_iri(curie="MS:1000031", ontology="ms")
|
|
872
|
+
print(f"IRI: {res2.iri if res2 else 'Not found'}")
|
|
873
|
+
|
|
874
|
+
# Example 3: Unscoped IRI resolution
|
|
875
|
+
res3 = svc.find_curie(iri="http://edamontology.org/format_1915")
|
|
876
|
+
print(f"Unscoped CURIE: {res3.curie if res3 else 'Not found'}")
|
|
877
|
+
```
|
|
878
|
+
|
|
879
|
+
**REST API (HTTP)**:
|
|
880
|
+
|
|
881
|
+
```bash
|
|
882
|
+
# Example 1: Resolve full IRI to CURIE
|
|
883
|
+
curl -X GET "http://localhost:8000/resolve/curie?iri=http%3A%2F%2Fpurl.obolibrary.org%2Fobo%2FMS_1000031&ontology=ms"
|
|
884
|
+
|
|
885
|
+
# Example 2: Resolve CURIE to full IRI
|
|
886
|
+
curl -X GET "http://localhost:8000/resolve/iri?curie=MS:1000031&ontology=ms"
|
|
887
|
+
|
|
888
|
+
# Example 3: Resolve IRI across entire database (unscoped)
|
|
889
|
+
curl -X GET "http://localhost:8000/resolve/curie?iri=http%3A%2F%2Fedamontology.org%2Fformat_1915"
|
|
890
|
+
```
|
|
891
|
+
|
|
892
|
+
---
|
|
893
|
+
|
|
894
|
+
### Use Case 6: Key-Value Metadata Tag Search
|
|
895
|
+
|
|
896
|
+
Query terms by normalized tags such as `is_leaf`, `obsolete`, or custom annotations.
|
|
897
|
+
|
|
898
|
+
#### CLI Examples
|
|
899
|
+
|
|
900
|
+
```bash
|
|
901
|
+
# Example 1: Find obsolete terms in an ontology
|
|
902
|
+
uv run ontology-lookup search-by-tag --tag-key obsolete --tag-value true -o ms --db .db/ontology_lookup.db
|
|
903
|
+
|
|
904
|
+
# Example 2: Find leaf terms (terms without child terms)
|
|
905
|
+
uv run ontology-lookup search-by-tag --tag-key is_leaf --tag-value 1 -o ms -l 10 --db .db/ontology_lookup.db
|
|
906
|
+
|
|
907
|
+
# Example 3: Search terms by custom tag key and value
|
|
908
|
+
uv run ontology-lookup search-by-tag --tag-key custom_category --tag-value instrumentation --db .db/ontology_lookup.db
|
|
909
|
+
```
|
|
910
|
+
|
|
911
|
+
#### API Examples
|
|
912
|
+
|
|
913
|
+
```python
|
|
914
|
+
from ontology_lookup.service import OntologyLookupService
|
|
915
|
+
|
|
916
|
+
with OntologyLookupService(db_path=".db/ontology_lookup.db") as svc:
|
|
917
|
+
# Example 1: Search obsolete terms
|
|
918
|
+
obsoletes = svc.search_by_tag(tag_key="obsolete", tag_value="true", ontology="ms")
|
|
919
|
+
print(f"Found {len(obsoletes)} obsolete terms in MS")
|
|
920
|
+
|
|
921
|
+
# Example 2: Search leaf terms
|
|
922
|
+
leaves = svc.search_by_tag(tag_key="is_leaf", tag_value="1", ontology="ms", limit=5)
|
|
923
|
+
for leaf in leaves:
|
|
924
|
+
print(f"Leaf term: {leaf.curie} - {leaf.label}")
|
|
925
|
+
|
|
926
|
+
# Example 3: Search by custom tag
|
|
927
|
+
custom_terms = svc.search_by_tag(tag_key="custom_category", tag_value="instrumentation")
|
|
928
|
+
print(f"Tagged terms count: {len(custom_terms)}")
|
|
929
|
+
```
|
|
930
|
+
|
|
931
|
+
**REST API (HTTP)**:
|
|
932
|
+
|
|
933
|
+
```bash
|
|
934
|
+
# Example 1: Find obsolete terms
|
|
935
|
+
curl -X GET "http://localhost:8000/search/tags?tag_key=obsolete&tag_value=true&ontology=ms"
|
|
936
|
+
|
|
937
|
+
# Example 2: Find leaf nodes
|
|
938
|
+
curl -X GET "http://localhost:8000/search/tags?tag_key=is_leaf&tag_value=1&ontology=ms&limit=10"
|
|
939
|
+
|
|
940
|
+
# Example 3: Query custom user metadata tags
|
|
941
|
+
curl -X GET "http://localhost:8000/search/tags?tag_key=custom_category&tag_value=instrumentation"
|
|
942
|
+
```
|
|
943
|
+
|
|
944
|
+
---
|
|
945
|
+
|
|
946
|
+
### Use Case 7: Recursive Descendants / Children Lookup
|
|
947
|
+
|
|
948
|
+
Retrieve all terms that inherit from a specified parent CURIE.
|
|
949
|
+
|
|
950
|
+
#### CLI Examples
|
|
951
|
+
|
|
952
|
+
```bash
|
|
953
|
+
# Example 1: Find descendants of instrument model (MS:1000031)
|
|
954
|
+
uv run ontology-lookup get-children --parent MS:1000031 -o ms --db .db/ontology_lookup.db
|
|
955
|
+
|
|
956
|
+
# Example 2: Find descendants of ionization type (MS:1000008)
|
|
957
|
+
uv run ontology-lookup get-children --parent MS:1000008 -o ms --db .db/ontology_lookup.db
|
|
958
|
+
|
|
959
|
+
# Example 3: Paginated descendants query with limit and offset
|
|
960
|
+
uv run ontology-lookup get-children --parent MS:1000031 -o ms --limit 5 --offset 0 --db .db/ontology_lookup.db
|
|
961
|
+
```
|
|
962
|
+
|
|
963
|
+
#### API Examples
|
|
964
|
+
|
|
965
|
+
```python
|
|
966
|
+
from ontology_lookup.service import OntologyLookupService
|
|
967
|
+
|
|
968
|
+
with OntologyLookupService(db_path=".db/ontology_lookup.db") as svc:
|
|
969
|
+
# Example 1: Children of instrument model
|
|
970
|
+
children1 = svc.get_children(parent_curie="MS:1000031", ontology="ms")
|
|
971
|
+
print(f"Children of MS:1000031: {len(children1)}")
|
|
972
|
+
|
|
973
|
+
# Example 2: Children of ionization type
|
|
974
|
+
children2 = svc.get_children(parent_curie="MS:1000008", ontology="ms")
|
|
975
|
+
for child in children2:
|
|
976
|
+
print(f" -> {child.curie}: {child.label}")
|
|
977
|
+
|
|
978
|
+
# Example 3: Paginated children lookup
|
|
979
|
+
children3 = svc.get_children(parent_curie="MS:1000031", ontology="ms", limit=5, offset=5)
|
|
980
|
+
print(f"Page 2 count: {len(children3)}")
|
|
981
|
+
```
|
|
982
|
+
|
|
983
|
+
**REST API (HTTP)**:
|
|
984
|
+
|
|
985
|
+
```bash
|
|
986
|
+
# Example 1: Recursive children of instrument model
|
|
987
|
+
curl -X GET "http://localhost:8000/children/MS:1000031?ontology=ms"
|
|
988
|
+
|
|
989
|
+
# Example 2: Recursive children of ionization type
|
|
990
|
+
curl -X GET "http://localhost:8000/children/MS:1000008?ontology=ms"
|
|
991
|
+
|
|
992
|
+
# Example 3: Paginated children
|
|
993
|
+
curl -X GET "http://localhost:8000/children/MS:1000031?ontology=ms&limit=5&offset=5"
|
|
994
|
+
```
|
|
995
|
+
|
|
996
|
+
---
|
|
997
|
+
|
|
998
|
+
### Use Case 8: Freetext Search (Labels, Synonyms, and Definitions)
|
|
999
|
+
|
|
1000
|
+
Perform ranked search across term labels, synonyms, and detailed text definitions using SQLite FTS5 BM25-based ranking.
|
|
1001
|
+
|
|
1002
|
+
#### CLI Examples
|
|
1003
|
+
|
|
1004
|
+
```bash
|
|
1005
|
+
# Example 1: Match definition text (e.g. manufacturer name)
|
|
1006
|
+
uv run ontology-lookup freetext-search -q "Thermo Scientific" -o ms --db .db/ontology_lookup.db
|
|
1007
|
+
|
|
1008
|
+
# Example 2: Search specific hybrid spectrometer types
|
|
1009
|
+
uv run ontology-lookup freetext-search -q "orbitrap mass spectrometer" -o ms -l 5 --db .db/ontology_lookup.db
|
|
1010
|
+
|
|
1011
|
+
# Example 3: Search multiple ontologies with a parent constraint
|
|
1012
|
+
uv run ontology-lookup freetext-search -q "quadrupole" -o ms,edam -p MS:1000031 --db .db/ontology_lookup.db
|
|
1013
|
+
```
|
|
1014
|
+
|
|
1015
|
+
#### API Examples
|
|
1016
|
+
|
|
1017
|
+
```python
|
|
1018
|
+
from ontology_lookup.service import OntologyLookupService
|
|
1019
|
+
|
|
1020
|
+
with OntologyLookupService(db_path=".db/ontology_lookup.db") as svc:
|
|
1021
|
+
# Example 1: Search definition text
|
|
1022
|
+
results1 = svc.freetext_search(query="Thermo Scientific", ontology="ms")
|
|
1023
|
+
for r in results1:
|
|
1024
|
+
print(f"[{r.curie}] {r.label} (Rank: {r.rank:.2f})")
|
|
1025
|
+
|
|
1026
|
+
# Example 2: Multi-keyword ranked search
|
|
1027
|
+
results2 = svc.freetext_search(query="orbitrap mass spectrometer", ontology=["ms"], limit=5)
|
|
1028
|
+
for r in results2:
|
|
1029
|
+
print(f"[{r.curie}] {r.label}")
|
|
1030
|
+
|
|
1031
|
+
# Example 3: Multi-ontology freetext search with parent filter
|
|
1032
|
+
results3 = svc.freetext_search(
|
|
1033
|
+
query="quadrupole",
|
|
1034
|
+
ontology=["ms", "edam"],
|
|
1035
|
+
parent_curie=["MS:1000031"],
|
|
1036
|
+
)
|
|
1037
|
+
print(f"Matches found: {len(results3)}")
|
|
1038
|
+
```
|
|
1039
|
+
|
|
1040
|
+
**REST API (HTTP)**:
|
|
1041
|
+
|
|
1042
|
+
```bash
|
|
1043
|
+
# Example 1: Search definition text
|
|
1044
|
+
curl -X GET "http://localhost:8000/search/freetext?q=Thermo+Scientific&ontology=ms"
|
|
1045
|
+
|
|
1046
|
+
# Example 2: Multi-keyword ranked search
|
|
1047
|
+
curl -X GET "http://localhost:8000/search/freetext?q=orbitrap+mass+spectrometer&ontology=ms&limit=5"
|
|
1048
|
+
|
|
1049
|
+
# Example 3: Multi-ontology freetext query with parent filter
|
|
1050
|
+
curl -X GET "http://localhost:8000/search/freetext?q=quadrupole&ontology=ms&ontology=edam&parent_curie=MS:1000031"
|
|
1051
|
+
```
|