Base de données Ensembl : Mappage d'ID et Caractéristiques Génomiques

Prérequis

uv : Lisez la skill uv et suivez ses instructions de configuration pour vous assurer que uv est installé et accessible via PATH.
Notification utilisateur : Si LICENSE_NOTIFICATION.txt n'existe pas déjà dans le répertoire de cette skill, alors (1) notifiez l'utilisateur de manière bien visible de vérifier les conditions à https://useast.ensembl.org/index.html et https://github.com/Ensembl/ensembl-rest/wiki, puis (2) créez le fichier enregistrant le texte de notification et l'horodatage.

Aperçu

La base de données Ensembl est une ressource pour l'annotation du génome. Cette skill vous permet d'interagir avec l'API REST Ensembl pour résoudre des symboles ambigus, croiser des références d'ID (RefSeq, HGNC, UniProt, ENSG), récupérer des séquences brutes et obtenir des structures de transcrit détaillées.

Concepts clés :

ENSG (Gène) : Identifiant stable pour un gène humain. Les autres espèces auront des codes espèces à trois lettres différents.
ENST (Transcrit) : Identifiant stable pour un transcrit (isoforme d'épissage).
ENSP (Protéine) : Identifiant stable pour une protéine traduite.
MANE Select : Le transcrit primaire consensus convenu entre Ensembl et NCBI.
Canonical : Le transcrit représentatif d'Ensembl (utilisé si MANE n'est pas disponible ou n'est pas humain).

Règles Fondamentales

Utilisez le Wrapper : TOUJOURS exécuter les scripts d'assistance fournis pour interroger la base de données plutôt que d'accéder directement à la base de données. Les scripts appliquent automatiquement la limite de débit requise de manière gracieuse.
Espèce par défaut : Si l'espèce est absente ou ambiguë dans la demande, utiliser par défaut "human". Vous DEVEZ explicitement signaler ce défaut à l'utilisateur pour vous assurer qu'il en est conscient.
Transcrits primaires : Lors de la liste des transcrits pour un gène, ne retourner que le transcrit MANE Select (pour l'humain) ou le transcrit Canonical (pour les autres) à moins que l'utilisateur ne demande explicitement toutes les isoformes alternatives. Vous DEVEZ signaler à l'utilisateur quand plusieurs transcrits sont disponibles et que vous utilisez par défaut le transcrit primaire.
Gestion de l'assemblage : L'assemblage par défaut est GRCh38. Pour les demandes GRCh37, vous DEVEZ utiliser le drapeau --assembly GRCh37. Vous DEVEZ explicitement signaler à l'utilisateur quand un assemblage non-standard est utilisé.
Emplacement de sortie : Le script écrit la sortie JSON/FASTA complète dans les fichiers temporaires en /tmp par défaut, ou dans un fichier spécifié par l'utilisateur en utilisant le drapeau --output. Il imprime aussi un résumé concis à stdout.
Notification : Si cette skill est utilisée, assurez-vous que cela soit mentionné dans la sortie.

Commandes Disponibles

1. Résoudre Gene ID — Résoudre un symbole, alias ou ID RefSeq en ID ENSG. Se replie automatiquement sur la résolution des synonymes si le symbole principal n'est pas trouvé.

uv run scripts/ensembl_api.py resolve-gene TP53 --species human --output tp53.json
uv run scripts/ensembl_api.py resolve-gene PCL2 --output pcl2.json # Se replie sur la résolution des synonymes

2. Mapper ID vers Base de Données Externe — Croiser une référence d'ID Ensembl vers UniProt, HGNC, RefSeq, etc.

uv run scripts/ensembl_api.py map-id ENSG00000141510 --external-db UniProt --output uniprot_map.json
uv run scripts/ensembl_api.py map-id ENST00000269305 --external-db RefSeq_mRNA --output refseq_map.json

3. Obtenir une Séquence Génomique — Récupérer l'ADN brut pour une fenêtre de coordonnées. Supporte GRCh37 via --assembly GRCh37.

uv run scripts/ensembl_api.py get-sequence 17:7661779-7687550 --species human --output seq.txt
uv run scripts/ensembl_api.py get-sequence chr9:21971100-21971200 --assembly GRCh37 --output seq_grch37.txt

4. Résumé Gène — Métadonnées haut niveau : symbole, biotype, description, localisation chromosomique.

uv run scripts/ensembl_api.py gene-summary ENSG00000141510 --output gene_summary.json

5. Lister Transcrits — Tous les transcrits d'un gène, avec filtres optionnels --only-mane ou --only-canonical. La sortie inclut le Transcript Support Level (TSL).

uv run scripts/ensembl_api.py transcripts ENSG00000141510 --only-mane --output transcripts_mane.json
uv run scripts/ensembl_api.py transcripts ENSG00000141510 --only-canonical --output transcripts_canonical.json
uv run scripts/ensembl_api.py transcripts ENSG00000141510 --output transcripts_all.json

5b. TSS Canonique — Obtenir la coordonnée unique du site de début de transcription (TSS) pour le transcrit canonique d'un gène.

[!NOTE] Contrairement à la commande standard transcripts, canonical-tss accepte à la fois les symboles (par ex. TP53) et les ID Ensembl, et les résout automatiquement. Elle effectue aussi le calcul pour l'orientation du brin (TSS est Start pour le brin + et End pour le brin -), produisant directement la coordonnée entière unique.

uv run scripts/ensembl_api.py canonical-tss TP53 --output tp53_tss.json
uv run scripts/ensembl_api.py canonical-tss ENSG00000141510 --output tss.json

6. Structure Transcrit — Coordonnées d'exons, limites CDS et régions UTR 5'/3' calculées pour un transcrit.

uv run scripts/ensembl_api.py transcript-structure ENST00000269305 --output structure.json

7. Info Protéine — ID ENSP et longueur de séquence pour un transcrit.

uv run scripts/ensembl_api.py protein-info ENST00000269305 --output protein_info.json

8. Séquence Protéine — FASTA acide aminé pour un ID transcrit (ENST) ou protéine (ENSP).

uv run scripts/ensembl_api.py protein-sequence ENST00000269305 --output protein.fasta
uv run scripts/ensembl_api.py protein-sequence ENSP00000269305 --output protein_ensp.fasta

9. Conséquence Variante (VEP) — Prédire les conséquences moléculaires d'une variante génomique. Inclut des plugins sous licence ouverte : AlphaMissense, Conservation, DosageSensitivity, IntAct, MaveDB, OpenTargets, LoF (Loftee), NMD, UTRAnnotator, mutfunc, LOEUF.

uv run scripts/ensembl_api.py vep 9:21971147:T:C --species human --output vep.json
uv run scripts/ensembl_api.py vep rs699 --species human --output vep_rs699.json

Exemple de sortie VEP à stdout :

[*] Variant: 9:21971147:T>C
[*] Most severe consequence: missense_variant
[*] Found 15 transcript consequences.

[*] VEP Predictions:

  - ENST00000304494 (CDKN2A): Consequence = missense_variant
  - ENST00000304494 (CDKN2A): Amino Acids = N/S
  - ENST00000304494 (CDKN2A): SIFT = deleterious (0.01)
  - ENST00000304494 (CDKN2A): AlphaMissense Class = likely_benign
  - ENST00000304494 (CDKN2A): AlphaMissense Pathogenicity = 0.2129
  - ENST00000304494 (CDKN2A): Conservation = 2.05
  - ENST00000304494 (CDKN2A): Dosage Sensitivity (Haplo) = 0.889228328567991
  - ENST00000304494 (CDKN2A): Dosage Sensitivity (Triplo) = 0.135514349094646
  - ENST00000304494 (CDKN2A): Loss of Function (LOEUF) = 0.791

Présenter les résultats VEP : Après exécution de la commande VEP, vous DEVEZ présenter la liste VEP Predictions complète de stdout à l'utilisateur. Cette liste contient à la fois les prédictions VEP standard (Consequence, Amino Acids, SIFT, PolyPhen) et les résultats des plugins sous licence ouverte (AlphaMissense, Conservation, Dosage Sensitivity, LOEUF, Loftee LoF, NMD, UTRAnnotator, Mutfunc). NE PAS simplement résumer — montrer la liste complète pour que l'utilisateur voie toutes les prédictions. Si la liste est très longue (nombreux transcrits), montrer en détail les lignes du transcrit MANE Select / canonical et noter que les données complètes sont dans la sortie JSON.

Analyse des Sorties

Si l'utilisateur a besoin de données structurales détaillées et imbriquées (comme les coordonnées entières précises de l'Exon 2 d'un transcrit) qui ne sont pas résumées en stdout :

Localiser le fichier JSON (soit spécifié via --output, soit le chemin du fichier temporaire imprimé par le script).
Utiliser les outils de terminal comme jq ou écrire rapidement un snippet python jetable pour extraire le point de données spécifique demandé. Ne pas tenter de lire le fichier JSON entier dans votre contexte s'il est très volumineux.

Requêtes Personnalisées

Si vous avez besoin de faire un appel API que le script ne supporte pas (par ex. récupérer des annotations de domaine protéique, mappage de coordonnées entre assemblages, recherches d'homologie, déséquilibre de liaison ou recherches de phénotypes), consultez references/ensembl_rest_api_reference.md pour une référence complète des endpoints disponibles, paramètres et champs de réponse.

CRITIQUE : Lors de l'écriture de scripts personnalisés ou de l'utilisation d'alternatives aux scripts fournis, vous DEVEZ respecter les limites de débit de l'API REST Ensembl (maximum 15 requêtes par seconde) et gérer gracieusement les erreurs 429 Too Many Requests (par ex. avec backoff exponentiel).

ensembl-database