Service de Recherche d'Ontologies EMBL-EBI (OLS)

Prérequis

1. uv : Lisez la skill uv et suivez ses instructions de configuration pour vous assurer que uv est installé et dans votre PATH.
2. Notification utilisateur : Si le fichier LICENSE_NOTIFICATION.txt n'existe pas déjà dans ce répertoire de skill, alors (1) notifiez l'utilisateur de manière bien visible de vérifier les conditions à https://www.ebi.ac.uk/ols4/api-docs, puis (2) créez le fichier enregistrant le texte de notification et l'horodatage.

Règles principales

• [!IMPORTANT] Utilisez les scripts utilitaires : Vous DEVEZ TOUJOURS utiliser le script utilitaire fourni sous scripts/ pour toutes les interactions API, y compris la vérification du statut. N'UTILISEZ JAMAIS curl ou des requêtes Python personnalisées pour interroger directement l'API.

• Limitation de débit et résilience : Vous DEVEZ respecter les conditions d'utilisation d'EBI avec un maximum de 5 requêtes par seconde. Les scripts utilitaires fournis appliquent automatiquement cette limite.

• Notification : Si cette skill est utilisée, assurez-vous que cela soit mentionné dans la sortie.

Quand utiliser — Recettes rapides

Utilisez cette skill chaque fois qu'une requête utilisateur correspond à l'un de ces motifs :

• Définition d'une maladie, phénotype ou terme → get_term.py --obo_id <ID> --summary
• Sous-types ou enfants d'un terme → get_term.py --obo_id <ID> --relations children
• Parent d'un terme → get_term.py --obo_id <ID> --relations parents
• Ancêtres / catégories de maladie / classifié sous → get_term.py --obo_id <ID> --relations ancestors
• Termes racine d'une ontologie → get_term.py --ontology <id> --roots
• Parents hiérarchiques (is-a + part-of) → get_term.py --obo_id <ID> --relations hierarchicalParents
• Structures faisant partie de / enfants hiérarchiques → get_term.py --obo_id <ID> --relations hierarchicalChildren
• Comparer parents directs vs hiérarchiques → get_term.py --obo_id <ID> --relations parents,hierarchicalParents
• Rechercher un terme (par ex. "apoptosis" dans GO) → search_ols.py --query "..." --ontology <id>
• Trouver un terme GO correspondant à une fonction → search_ols.py --query "..." --ontology go --exact
• Rechercher dans MONDO, CHEBI, CL, UBERON → search_ols.py --query "..." --ontology <id> --defining
• Paginer les résultats de recherche / page suivante → search_ols.py --query "..." --rows N --start <offset>
• Autocomplétion d'un nom partiel → suggest_ols.py --query "..."
• Métadonnées d'ontologie (par ex. info EFO) → get_ontology.py --id <id>
• Statistiques de l'index OLS → get_stats.py

Requêtes multi-étapes (par ex. « Quel est le parent de l'infarctus du myocarde ? ») : Quand l'utilisateur nomme un terme mais que vous ne connaissez pas son OBO ID, complétez en exactement 2 étapes — ne recherchez PAS dans plusieurs ontologies :

1. Rechercher dans la seule ontologie la plus appropriée : search_ols.py --query "myocardial infarction" --ontology doid --exact --rows 1 --output /tmp/step1.json
2. Obtenir les relations en utilisant l'OBO ID de l'étape 1 : get_term.py --obo_id DOID:5844 --relations parents --output /tmp/step2.json

Règle de sélection d'ontologie : TOUJOURS utiliser doid pour les maladies humaines courantes (par ex. diabète, cancer), hp pour les phénotypes, go pour les fonctions géniques, chebi pour les produits chimiques, uberon pour l'anatomie, cl pour les types de cellules. Utiliser mondo UNIQUEMENT quand le contexte multi-espèces est explicitement mentionné ou nécessaire.

Scripts utilitaires

1. Rechercher des termes dans les ontologies

Recherchez des termes d'ontologie par mot-clé et retournez du JSON propre.

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

Important : --output est requis pour tous les scripts. Les résultats sont toujours écrits dans le fichier spécifié. Pour une sortie plus volumineuse, vous pouvez limiter --rows (par ex. 5-10) ou paginer en utilisant --start.

Champs retournés : Les résultats JSON incluent iri, label, description, ontology_name, ontology_prefix, obo_id, short_form, type, is_defining_ontology et exact_synonyms.

Pagination : La sortie inclut un bloc pagination avec start, rows et has_more pour vous permettre de décider si vous souhaitez récupérer plus de résultats.

Options :

• --query : Chaîne de recherche (obligatoire). Recherche dans les labels, synonymes, descriptions et identifiants.
• --ontology : Filtrer par ID d'ontologie (par ex. go, doid, efo, hp). Recommandé quand vous savez quelle ontologie rechercher — évite le bruit de 250+ ontologies.
• --type : Filtrer par type d'entité : class, property, individual ou ontology.
• --exact : Drapeau pour correspondance exacte du label uniquement. Utilisez ceci pour la résolution d'entités lors de la mise en correspondance d'une chaîne utilisateur avec un ID de terme d'ontologie spécifique.
• --defining : Retourner uniquement les termes de leur ontologie de définition (autoritative). Par ex. GO:0005634 uniquement depuis GO, pas des copies référencées croisées.
• --obsolete : Drapeau pour inclure les termes obsolètes dans les résultats.
• --local : Retourner uniquement les termes dans leur ontologie de définition.
• --childrenOf : Limiter aux enfants d'IRI(s) de terme donnés, séparés par des virgules.
• --allChildrenOf : Limiter à tous les enfants incluant les relations transitives (part of, develops from), IRI séparés par des virgules.
• --queryFields : Champs sur lesquels faire la recherche, séparés par des virgules (par ex. label,synonym,description).
• --fieldList : Champs à retourner, séparés par des virgules.
• --groupField : Grouper les résultats par IRI unique.
• --isLeaf : Retourner uniquement les termes feuilles (pas d'enfants).
• --rows : Nombre de résultats à retourner (par défaut 10).
• --start : Décalage de pagination (par défaut 0).
• --output : Chemin du fichier pour enregistrer les résultats (obligatoire).

2. Autocomplétion / Suggestions

Obtenez des suggestions d'autocomplétion pour les noms de termes partiels.

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

Options :

• --query : Terme partiel à autocompléter (obligatoire).
• --ontology : Filtrer par ID(s) d'ontologie, séparés par des virgules.
• --rows : Nombre de suggestions (par défaut 10).
• --start : Décalage de pagination (par défaut 0).
• --output : Chemin du fichier pour enregistrer les résultats (par défaut : stdout).

3. Obtenir les détails d'un terme

Récupérez tous les détails d'un terme d'ontologie spécifique par son OBO ID ou IRI.

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

Champs retournés : Le JSON inclut iri, label, description, obo_id, synonyms, ontology_name, is_obsolete, is_defining_ontology, has_children, is_root, annotation, in_subset et toutes les relations demandées.

Mode résumé : Utilisez --summary pour obtenir un bloc propre et lisible par humain sur stdout (Label, OBO ID, Ontologie, Définition, Synonymes). Le JSON complet est toujours enregistré dans le fichier --output.

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

Options :

• --obo_id : Identifiant de style OBO (par ex. GO:0005634, DOID:9351). Mutuellement exclusif avec --iri. Conversion automatique en IRI avec double encodage.

• --iri : IRI complet du terme. Mutuellement exclusif avec --obo_id.

• --ontology : ID d'ontologie (auto-dérivé de --obo_id s'il n'est pas fourni).

• --relations : Liste de relations à récupérer, séparées par des virgules.

  • Direct (is-a uniquement) : parents, children, ancestors, descendants
  • Hiérarchique (is-a + transitif comme "part of", "develops from") : hierarchicalParents, hierarchicalChildren, hierarchicalAncestors, hierarchicalDescendants
  • Graphe : graph — JSON du graphe complet pour un terme

  Note : Utilisez les variantes hiérarchiques pour les ontologies anatomiques/développementales (UBERON, CL) où les relations transitives comme « part of » et « develops from » sont essentielles pour naviguer dans la hiérarchie.

• --roots : Lister les termes racine de l'ontologie (nécessite --ontology).

• --preferred_roots : Lister les termes racine préférés (nécessite --ontology).

• --summary : Résumé lisible par humain sur stdout, JSON complet dans --output.

• --output : Chemin du fichier pour enregistrer les résultats (par défaut : stdout).

4. Obtenir les détails d'une propriété

Récupérez les détails d'une propriété d'ontologie (type de relation) avec hiérarchie.

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

Options :

• --obo_id : ID de style OBO de la propriété. Mutuellement exclusif avec --iri.
• --iri : IRI complet de la propriété. Mutuellement exclusif avec --obo_id.
• --ontology : ID d'ontologie (requis avec --iri).
• --relations : Séparés par des virgules : parents, children, ancestors, descendants.
• --roots : Lister les propriétés racine de l'ontologie (nécessite --ontology).
• --output : Chemin du fichier pour enregistrer les résultats (par défaut : stdout).

5. Obtenir les détails d'un individu

Récupérez les détails d'un individu d'ontologie (instance).

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

Options :

• --obo_id : ID de style OBO. Mutuellement exclusif avec --iri.
• --iri : IRI complet. Mutuellement exclusif avec --obo_id.
• --ontology : ID d'ontologie (requis avec --iri).
• --types : Récupérer les types directs (classes) de cet individu.
• --alltypes : Récupérer tous les types incluant les classes ancêtres.
• --output : Chemin du fichier pour enregistrer les résultats (par défaut : stdout).

6. Obtenir les informations d'ontologie

Lister les ontologies disponibles ou récupérer les détails d'une ontologie spécifique.

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

Options :

• --id : ID spécifique d'ontologie (par ex. go, efo, doid). S'il est omis, liste toutes les ontologies.
• --page : Numéro de page pour la pagination (par défaut 0).
• --size : Nombre d'ontologies par page (par défaut 20).
• --output : Chemin du fichier pour enregistrer les résultats (par défaut : stdout).

7. Obtenir les statistiques OLS

Récupérez les statistiques de l'index (nombre total d'ontologies, classes, propriétés, individus).

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

Options :

• --output : Chemin du fichier pour enregistrer les résultats (par défaut : stdout).

Référence

• Référence API : Consultez references/api_reference.md pour les IDs d'ontologie courants, le format OBO ID et les points de terminaison clés de l'API.

Flux de travail

1. Utilisez suggest_ols.py pour l'autocomplétion quand vous avez un nom de terme partiel.
2. Recherchez des termes en utilisant search_ols.py. Utilisez --defining pour prioriser les définitions autoratives. Utilisez --exact pour la résolution d'entités.
3. Si les détails complets sont nécessaires, utilisez get_term.py avec l'OBO ID ou l'IRI. Utilisez --summary pour une vue concise.
4. Pour explorer la hiérarchie d'un terme, utilisez get_term.py --relations parents,children pour is-a uniquement, ou --relations hierarchicalParents,hierarchicalChildren pour « part of » etc.
5. Pour explorer de haut en bas, utilisez get_term.py --ontology go --roots.
6. Pour les propriétés ou les individus, utilisez get_property.py ou get_individual.py.
7. Pour découvrir les ontologies disponibles, utilisez get_ontology.py.
8. Pour vérifier le statut de l'index OLS, utilisez get_stats.py.