Requêtes sur la Base de Données ChEMBL

Prérequis

uv: Lisez la skill uv et suivez ses instructions de configuration pour vous assurer que uv est installé et disponible dans le PATH.
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 pour vérifier les conditions à https://chembl.gitbook.io/chembl-interface-documentation/about, puis (2) créez le fichier en enregistrant le texte de notification et l'horodatage.

Règles Fondamentales

[!IMPORTANT] Utilisez les Scripts Utilitaires: Vous DEVEZ TOUJOURS utiliser le script utilitaire fourni scripts/chembl_api.py pour toutes les interactions avec l'API ChEMBL, y compris la vérification du statut. N'utilisez JAMAIS curl ou des requêtes Python personnalisées pour interroger directement l'API ChEMBL. Cela garantit que le rate limit est appliqué et que les nouvelles tentatives se font aussi sur les erreurs réseau.
Sortie vers Fichier (Obligatoire): Le flag --output est obligatoire pour chaque sous-commande. Tous les résultats JSON sont écrits dans le fichier spécifié. Après l'exécution de la commande, lisez le fichier de sortie avec jq ou votre propre code pour extraire les données. Les résultats de listes sont généralement enveloppés dans un tableau JSON clé par le nom du endpoint (par exemple, molecules, activities).
Notification: Si cette skill est utilisée, assurez-vous que cela est mentionné dans la sortie.

Script Utilitaire

Toutes les requêtes de l'API ChEMBL utilisent un script unique avec des sous-commandes:

uv run scripts/chembl_api.py <subcommand> --output <file> [options]

1. Vérifier le Statut de l'API

uv run scripts/chembl_api.py status --output /tmp/status.json

2. Requêtes sur les Molécules

Récupérer par ID ChEMBL: bash uv run scripts/chembl_api.py molecule --id CHEMBL25 --output /tmp/mol.json

Rechercher par nom: bash uv run scripts/chembl_api.py molecule --search "aspirin" --limit 3 --output /tmp/mol_search.json

Récupération par lot: bash uv run scripts/chembl_api.py molecule --ids "CHEMBL25;CHEMBL1642" --limit 10 --output /tmp/mol_batch.json

Filtrer par propriétés: bash uv run scripts/chembl_api.py molecule --filter molecule_properties__mw_freebase__lte=500 --limit 5 --output /tmp/mol_filter.json

Filtrer par plage: bash uv run scripts/chembl_api.py molecule --filter molecule_properties__mw_freebase__range=150,200 --limit 5 --output /tmp/mol_range.json

Télécharger fichier de structure SDF: bash uv run scripts/chembl_api.py molecule --id CHEMBL25 --dl_format sdf --output /tmp/aspirin.sdf

Conseil: Les fichiers SDF/MOL peuvent être directement transmis à des outils comme PyMOL ou RDKit pour la visualisation 3D et l'analyse.

3. Requêtes sur les Cibles

Rechercher des cibles: bash uv run scripts/chembl_api.py target --search "EGFR" --limit 5 --output /tmp/targets.json

Récupérer par ID: bash uv run scripts/chembl_api.py target --id CHEMBL203 --output /tmp/egfr.json

4. Données de Bioactivité

Récupérer l'activité par ID: bash uv run scripts/chembl_api.py activity --id 31863 --output /tmp/act.json

Rechercher les activités: bash uv run scripts/chembl_api.py activity --search "EGFR" --limit 5 --output /tmp/act_search.json

Filtrer les activités pour une cible: bash uv run scripts/chembl_api.py activity --filter target_chembl_id=CHEMBL203 standard_type=IC50 --limit 10 --output /tmp/egfr_ic50.json

Normaliser les unités de bioactivité en nM: bash uv run scripts/chembl_api.py activity --filter target_chembl_id=CHEMBL203 standard_type=IC50 --limit 5 --normalize --output /tmp/egfr_normalized.json

Important: Les valeurs de bioactivité arrivent dans différentes unités (nM, µM, pM). Utilisez --normalize pour convertir toutes les valeurs en nM pour une comparaison cohérente. Chaque enregistrement inclura normalized_value_nM et normalization_note.

5. Informations sur les Médicaments

Récupérer les détails du médicament: bash uv run scripts/chembl_api.py drug --id CHEMBL25 --output /tmp/drug.json

Indications du médicament: bash uv run scripts/chembl_api.py drug_indication --filter molecule_chembl_id=CHEMBL25 --limit 10 --output /tmp/indications.json

Filtrer les indications par phase: bash uv run scripts/chembl_api.py drug_indication --filter molecule_chembl_id=CHEMBL25 max_phase_for_ind=4.0 --limit 10 --output /tmp/approved_indications.json

Avertissements sur les médicaments: bash uv run scripts/chembl_api.py drug_warning --limit 5 --output /tmp/warnings.json

Mécanismes d'action: bash uv run scripts/chembl_api.py mechanism --filter molecule_chembl_id=CHEMBL25 --limit 5 --output /tmp/mech.json

6. Recherches Basées sur la Structure

Remarque: Les recherches de similarité et de sous-structure sont effectuées côté serveur sur la base de données pré-indexée de ChEMBL. Elles ne nécessitent pas d'installation RDKit locale.

Recherche de similarité (SMILES + seuil): bash uv run scripts/chembl_api.py similarity --smiles "CC(=O)Oc1ccccc1C(=O)O" --similarity 85 --limit 5 --output /tmp/similar.json

Recherche de sous-structure (SMILES): bash uv run scripts/chembl_api.py substructure --smiles "c1ccccc1" --limit 5 --output /tmp/substruct.json

7. Image de Composé

Télécharger une image de structure 2D (SVG par défaut, redimensionnable pour publication):

uv run scripts/chembl_api.py image --id CHEMBL25 --output /tmp/chembl25.svg

Options:

--dimensions: Taille d'image en pixels (max 500, défaut 500).
--engine: Moteur de rendu (défaut: rdkit).
--img_format: Format de sortie — svg (défaut, vecteur) ou png (raster).

8. Références Croisées avec Autres Bases de Données

ChEMBL s'intègre avec UniProt, Ensembl, PubChem et d'autres bases de données. Motifs courants de références croisées:

Trouver une cible ChEMBL à partir d'une accession UniProt: bash uv run scripts/chembl_api.py target --filter target_components__accession=P00533 --limit 5 --output /tmp/uniprot_target.json

Résoudre un ID ChEMBL quelconque vers son type d'entité: bash uv run scripts/chembl_api.py chembl_id_lookup --id CHEMBL203 --output /tmp/lookup.json

Consulter les sources de références croisées: bash uv run scripts/chembl_api.py xref_source --limit 10 --output /tmp/xrefs.json

Conseil: Utilisez le endpoint target_component pour trouver les accessions UniProt, les noms de gènes et les séquences protéiques pour toute cible ChEMBL.

9. Pagination

Tous les endpoints de liste supportent --limit et --offset pour la pagination:

# Première page: 2 résultats à partir du décalage 0
uv run scripts/chembl_api.py molecule --limit 2 --offset 0 --output /tmp/page1.json

# Deuxième page: 2 résultats suivants à partir du décalage 2
uv run scripts/chembl_api.py molecule --limit 2 --offset 2 --output /tmp/page2.json

La réponse inclut page_meta avec total_count, limit, offset, next et les liens previous. Utilisez des valeurs --offset successives pour naviguer à travers les grands ensembles de résultats.

10. Autres Endpoints

Tous les endpoints restants suivent le même motif:

uv run scripts/chembl_api.py <subcommand> --output <file> [--id ID | --ids ID1;ID2 | --search QUERY] [--limit N] [--offset N] [--filter KEY=VAL ...]

Sous-commandes clés en un coup d'œil:

molecule (searchable: true): Molécules/composés — le point d'entrée principal
target (searchable: true): Cibles pharmaceutiques (protéines, organismes, etc.)
activity (searchable: true): Données de bioactivité (IC50, Ki, EC50, etc.)
drug (searchable: false): Médicaments approuvés
mechanism (searchable: false): Mécanismes d'action
assay (searchable: true): Descriptions d'essais
similarity (searchable: false): Recherche de similarité (spécial)
substructure (searchable: false): Recherche de sous-structure (spécial)
image (searchable: false): Téléchargement d'image de composé (spécial)

Liste complète des sous-commandes:

activity_supp (searchable: false): Données de bioactivité supplémentaires
assay_class (searchable: false): Classifications d'essais
atc_class (searchable: false): Classifications de médicaments ATC
binding_site (searchable: false): Informations sur le site de liaison
biotherapeutic (searchable: false): Molécules biothérapeutiques
cell_line (searchable: false): Détails des lignées cellulaires
chembl_id_lookup (searchable: true): Résolution d'ID ChEMBL
chembl_release (searchable: false): Informations de version de base de données
compound_record (searchable: false): Enregistrements de composés
compound_structural_alert (searchable: false): Alertes structurales
document (searchable: true): Documents littéraires
document_similarity (searchable: false): Similarité de documents
drug_indication (searchable: false): Indications des médicaments
drug_warning (searchable: false): Avertissements de sécurité des médicaments
go_slim (searchable: false): Termes GO slim
metabolism (searchable: false): Données de métabolisme
molecule_form (searchable: false): Formes de molécules (sels/parents)
organism (searchable: false): Organismes
protein_classification (searchable: true): Classifications de protéines
source (searchable: false): Sources de données
target_component (searchable: false): Composants de cibles protéiques
target_relation (searchable: false): Relations de cibles
tissue (searchable: false): Types de tissus
xref_source (searchable: false): Sources de références croisées
status (searchable: false): Vérification de statut d'API (spécial)

Options Communes

--output FILE: Obligatoire. Chemin du fichier de sortie pour les résultats JSON.
--id ID: Récupérer un seul enregistrement par ID.
--ids ID1;ID2;...: Récupération par lot de plusieurs enregistrements.
--search QUERY: Recherche en texte libre (uniquement pour les endpoints searchable, marqués ✓).
--limit N: Nombre maximal de résultats à retourner (défaut: 5).
--offset N: Décalage de pagination.
--filter KEY=VAL: Paramètres de filtre (peut être spécifié plusieurs fois).
--normalize: (activity uniquement) Normaliser les valeurs en nM.
--dl_format sdf|mol: (molecule uniquement) Télécharger le fichier de structure.

Référence

Référence des Endpoints d'API: Voir references/api_endpoints.md pour la liste complète des endpoints et opérateurs de filtre.

Workflow

Utilisez status --output /tmp/status.json pour vérifier que l'API est disponible.
Recherchez des cibles, des molécules ou des médicaments en utilisant la sous-commande appropriée.
Lisez le fichier JSON de sortie pour extraire les IDs et les données.
Utilisez les IDs issus des résultats de recherche pour récupérer les enregistrements détaillés.
Interrogez activity avec des filtres pour obtenir des données de bioactivité pour des cibles/molécules. Utilisez --normalize lors de la comparaison de valeurs entre études.
Utilisez similarity ou substructure pour les requêtes basées sur la structure côté serveur.
Téléchargez les images de composés avec image ou les fichiers de structure avec molecule --dl_format sdf.
Utilisez target --filter target_components__accession=<UniProt> pour les références croisées avec UniProt.

chembl-database