Compétence Open Targets Database

Aperçu

Cette compétence fournit l'accès à l'API GraphQL de la plateforme Open Targets. Elle agrège des preuves multimodales provenant de la génétique (GWAS/eQTL), des voies métaboliques, des modèles animaux et des essais cliniques pour classer les associations cible-maladie et identifier les gènes « druggables ».

Prérequis

1. uv : Lisez la compétence uv et suivez ses instructions de configuration pour vous assurer que uv est installé et dans le PATH.
2. Notification utilisateur : Si LICENSE_NOTIFICATION.txt n'existe pas déjà dans le répertoire de cette compétence, alors (1) notifiez l'utilisateur de manière visible de vérifier les conditions d'utilisation à https://platform-docs.opentargets.org/licence, puis (2) créez le fichier enregistrant le texte de notification et l'horodatage.

Règles principales

• Utiliser le wrapper : EXÉCUTEZ TOUJOURS les scripts d'aide fournis pour interroger la base de données plutôt que d'y accéder directement. Les scripts appliquent automatiquement l'utilisation équitable et implémentent la logique de relance.
• Indicateur de sortie : L'indicateur --output est toujours obligatoire car la sortie peut être très grande. Utilisez jq ou écrivez votre propre code pour traiter ce fichier JSON.
• Notification : Si cette compétence est utilisée, assurez-vous que cela soit mentionné dans la sortie.

Référence rapide

Utilisez toujours le script Python fourni scripts/query_opentargets.py pour interroger rapidement la base de données. Il gère la communication API, les relances, le formatage et tronque automatiquement les réponses trop volumineux. N'ÉCRIVEZ JAMAIS vos propres requêtes curl ou similaires.

Utilisation :

uv run scripts/query_opentargets.py --output /tmp/opentargets_results.json [OPTIONS] COMMAND [ARGS]...

Options courantes :

• --output PATH : Obligatoire. Chemin d'écriture du fichier de sortie JSON.
• --limit N : Limite le nombre d'éléments retournés dans les tableaux (50 par défaut). Utilisez un nombre plus petit comme 10 lors d'une exploration préliminaire.
• --page-size N : Définit la taille de pagination de l'API (200 par défaut). Augmentez si vous avez besoin de plus de résultats (par exemple, une étude avec plusieurs ensembles crédibles).

Commandes disponibles :

• get-gwas-studies efo_id : Récupère toutes les études GWAS associées à un identifiant EFO d'ontologie de maladie spécifique (par exemple EFO_0000685).
• get-study-credible-sets study_id : Récupère tous les ensembles crédibles pour un identifiant d'étude donné (par exemple FINNGEN_R12_RX_CROHN_2NDLINE). Retourne la confiance, la méthode de cartographie fine, les informations de variante et de p-valeur.
• get-qtl-credible-sets variant_id : Récupère les ensembles crédibles QTL pour un identifiant de variante spécifique (par exemple 19_44908822_C_T).
• get-l2g variant_id [--study-id ID] : Retourne les prédictions/scores Locus-to-Gene (L2G) pour un locus afin d'identifier le gène causal le plus probable. Seul variant_id est obligatoire ; utilisez --study-id pour filtrer sur une étude spécifique. Accepte le préfixe chr (par exemple chr1_113834946_A_G).
• get-target-druggability ensembl_id : Fournit les données de tractabilité (petite molécule, anticorps, etc.) et les informations de sécurité des essais cliniques pour un gène/cible.
• get-associated-targets efo_id : Trouve tous les gènes cibles associés à un identifiant EFO de maladie spécifique.
• get-associated-diseases ensembl_id : Trouve toutes les maladies associées à un identifiant Ensembl de cible spécifique.
• search-disease query_string : Recherche une maladie par nom pour trouver son identifiant EFO et d'autres métadonnées.
• get-credible-sets-near-target ensembl_id [--window N] : Récupère les ensembles crédibles pour une cible et les filtre pour ceux situés dans une fenêtre génomique autour de la cible. Utile pour trouver des variantes « à proximité » d'un gène.
• custom-query query [--variables '{}'] : Exécutez une requête GraphQL brute pour toute autre donnée Open Targets.

Utilisation des requêtes L2G

La commande get-l2g a deux modes :

• Variante seule (get-l2g <variant_id>) : Retourne les prédictions L2G de tous les ensembles crédibles de toutes les études où cette variante est la variante de tête. Cela peut retourner un grand nombre de résultats (par exemple, des centaines). Utilisez ceci quand l'utilisateur souhaite une vue large du gène le plus probablement causal à un locus, ou quand aucune étude spécifique n'est mentionnée.
• Variante + étude (get-l2g <variant_id> --study-id <study_id>) : Retourne les prédictions L2G uniquement pour les ensembles crédibles de cette étude spécifique. Utilisez ceci quand l'utilisateur pose une question sur une étude GWAS spécifique ou quand vous devez réduire les résultats.

Avertissement de résultats incomplets : Le mode variante seule peut retourner des centaines d'ensembles crédibles. La --page-size par défaut est 200, donc si l'API rapporte un count supérieur au nombre de rows retournées, vous voyez des résultats incomplets. Comparez toujours count au nombre réel de lignes. S'ils diffèrent, augmentez --page-size ou informez l'utilisateur que seul un sous-ensemble a été récupéré.

Interrogation par région

Pour trouver des études avec des variantes « à proximité » d'un gène, utilisez get-credible-sets-near-target, qui améliore l'API de base en effectuant une recherche flexible basée sur la position génomique : uv run scripts/query_opentargets.py --output /tmp/results.json get-credible-sets-near-target ENSG00000156515 --window 500000

Notez que le schéma GraphQL d'Open Targets inclut un paramètre regions pour credibleSets, cependant il effectue une correspondance exacte contre des chaînes de région précalculées (par exemple chr10:68769984-69903496) et il y a certaines données manquantes. Utilisez get-credible-sets-near-target car il permet une recherche de chevauchement de plage génomique.

Cela récupère les ensembles crédibles associés à la cible et les filtre en Python basé sur la position génomique de la variante.

Requêtes GraphQL avancées

Si vous avez besoin d'interroger des endpoints ou des champs non exposés par les sous-commandes intégrées, utilisez le sous-commande custom-query.

Avant d'écrire une requête personnalisée : Lisez la documentation de référence pour comprendre le schéma API, les types et voir des exemples de requêtes. Consultez references/OpenTargets_GraphQL_Guide.md pour tous les détails du schéma, les endpoints et les exemples.

Exemple : Trouver des médicaments pour une maladie

uv run scripts/query_opentargets.py custom-query \
  query drugsForDisease($id: String!) {
    disease(efoId: $id) {
      name
      drugAndClinicalCandidates {
        count
        rows {
          maxClinicalStage
          drug {
            id
            name
          }
        }
      }
    }
  }' \
--variables '{"id": "EFO_1001006"}'
--output '/tmp/opentargets_result.json'

Cotes de confiance en étoiles

La plateforme Open Targets attribue un niveau de confiance à chaque ensemble crédible basé sur la méthode de cartographie fine et les vérifications de qualité. Ceux-ci correspondent aux cotes d'étoiles affichées dans l'interface utilisateur de la plateforme :

Quand les utilisateurs demandent une confiance « N-étoiles », mettez en correspondance leur demande avec la chaîne correspondante dans le champ confidence de la réponse API.

Astuces et erreurs courantes

• Formats d'identifiant :
  • Les identifiants de maladie doivent être au format EFO (par exemple EFO_0000685).
  • Les identifiants de cible doivent être des identifiants Ensembl (par exemple ENSG00000169083), pas des symboles HGNC. Si vous n'avez qu'un symbole de gène, vous devrez peut-être le mapper en premier en utilisant une requête GraphQL search personnalisée.
  • Les identifiants de variante sont formatés comme chromosome_position_ref_alt (par exemple 1_154426264_C_T). Un préfixe chr (par exemple chr1_154426264_C_T) est automatiquement supprimé par l'outil.
  • Les identifiants d'étude peuvent être des identifiants du GWAS Catalog (par exemple GCST90204201) ou des identifiants spécifiques à un projet (par exemple FINNGEN_R12_RX_CROHN_2NDLINE).
• Troncature : L'outil tronque les tableaux plus longs que --limit pour protéger la fenêtre de contexte. Si vous voyez "_truncated", vous pouvez relancer la requête avec une limite plus élevée si vous avez spécifiquement besoin de plus de données, mais soyez prudent avec les grandes valeurs de limite. Utilisez toujours l'indicateur --output pour enregistrer le résultat dans un fichier et éviter la troncature de la sortie du terminal.
• Pagination et résultats incomplets : L'option --page-size (200 par défaut) contrôle le nombre d'éléments récupérés par l'API. Vérifiez toujours le champ count dans la réponse et comparez-le au nombre de rows réellement retournées. Si count > nombre de lignes, vous avez des données incomplètes — augmentez --page-size pour récupérer plus, ou informez l'utilisateur que seul un ensemble de résultats partiels a été retourné. C'est particulièrement important pour get-l2g sans --study-id, qui peut retourner des centaines d'ensembles crédibles.