Intégration de la base de données dbSNP

Prérequis

1. uv : Lisez le 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 visible pour vérifier les conditions à https://www.ncbi.nlm.nih.gov/snp/, puis (2) créez le fichier en enregistrant le texte de notification et l'horodatage.

3. Fichier .env : Assurez-vous que le fichier .env existe dans votre répertoire personnel. Créez-en un s'il n'existe pas.

4. NCBI_API_KEY (optionnel) : Relève la limite de débit NCBI de 3 à 10 requêtes/seconde. Le skill fonctionne sans elle, mais une clé est recommandée si l'utilisateur prévoit de nombreuses requêtes ou rencontre une erreur 429. L'utilisateur peut en obtenir une gratuitement en s'enregistrant à https://www.ncbi.nlm.nih.gov/account/settings/. Si la variable manque dans .env, ne demandez PAS à l'utilisateur de la coller dans le chat (cela pourrait divulguer la clé dans le contexte de l'agent). Donnez plutôt à l'utilisateur cette commande — en remplaçant ENV_FILE par le chemin littéral résolu du fichier .env :

   printf "Enter NCBI API key (typing hidden): " && read -s key && echo && echo "NCBI_API_KEY=$key" >> "ENV_FILE" && echo "Saved."

   Les scripts chargent automatiquement les identifiants via dotenv. N'EVER lisez, n'imprimez, n'inspectez pas le fichier .env ou ses variables (par ex. pas de cat, grep, echo, printenv, ou os.environ.get sur les clés). Les identifiants doivent rester en dehors du contexte de l'agent. Consultez la section Clé API pour plus de détails.

Règles fondamentales

• Utilisez le wrapper : EXÉCUTEZ TOUJOURS le script wrapper fourni scripts/dbsnp_cli.py pour interroger la base de données plutôt que de construire des requêtes HTTP ou curl personnalisées. Le script gère automatiquement la limitation de débit, les tentatives et l'analyse JSON.
• Choix de commande : N'UTILISEZ PAS search-region pour trouver le rsID d'une variante spécifique ; utilisez plutôt resolve-variant.
• Taille de sortie : Évitez d'utiliser --full sur get-variant sauf si spécifiquement nécessaire, car les payloads bruts peuvent dépasser 1 MB.
• Sécurité shell : Encadrez toujours les chaînes HGVS entre guillemets simples pour éviter les erreurs d'expansion shell.
• Notification : Si ce skill est utilisé, assurez-vous que c'est mentionné dans la sortie.

Quand utiliser

Utilisez ce skill quand vous avez besoin de :

• Mapper une variante génomique à son rsID canonique (à partir de coordonnées VCF ou de notation HGVS).
• Récupérer les données résumées d'un rsID : type de variante, associations géniques, signification clinique et fréquences d'allèles dans les populations.
• Convertir un rsID en coordonnées génomiques sur un assembly spécifique.
• Trouver toutes les variantes connues dans une région chromosomique.

N'UTILISEZ PAS quand vous avez besoin de :

• Obtenir des classifications de pathogénicité clinique avec les justifications des soumetteurs (utilisez clinvar-database).
• Obtenir les fréquences d'allèles précises au niveau de la population stratifiées par ascendance (utilisez gnomad-database).
• Prédire l'effet fonctionnel d'une mutation nouvelle (utilisez alphagenome-single-variant-analysis).
• Afficher les structures protéiques 3D affectées par une variante (utilisez alphafold-database-fetch-and-analyze / pdb-database).

Guide de sélection des commandes

Choisissez la bonne commande du premier coup. Faites correspondre l'entrée de l'utilisateur à la bonne sous-commande ci-dessous — un appel de commande suffit presque toujours.

• L'utilisateur vous donne… : Exécutez cette commande
• Un rsID (par ex. rs7412, rs268) : get-variant
• Des coordonnées génomiques : chrom pos ref alt (par ex. 8 19962213 C T) : resolve-variant
• Une chaîne HGVS (par ex. NC_000008.11:g.19962213del) : resolve-hgvs
• Un rsID et ils veulent les coordonnées en retour : resolve-rsid
• Une région chromosomique (chrom start end) : search-region

[!CAUTION] N'UTILISEZ PAS search-region pour trouver le rsID d'une variante spécifique. Si l'utilisateur fournit un chromosome, une position, un allèle de référence et un allèle alternatif (quatre valeurs), utilisez resolve-variant — c'est une recherche directe, en un seul appel API. search-region est seulement pour explorer toutes les variantes dans une plage positionnelle et retourne des centaines/milliers de résultats.

Démarrage rapide

# Consulter la variante rs7412 : type, gène, signification clinique, MAF
uv run scripts/dbsnp_cli.py get-variant rs7412 --output /tmp/rs7412.json

# Trouver le rsID pour une variante à chr8:19962213 C>T
uv run scripts/dbsnp_cli.py resolve-variant 8 19962213 C T \
  --output /tmp/resolve.json

Toutes les sous-commandes écrivent le JSON sur disque. Sauvegardez toujours la sortie dans le répertoire /tmp/. Le flag --output est obligatoire.

Commandes

1. get-variant — Récupérer un enregistrement de variante

Récupère l'enregistrement RefSNP pour un rsID. Par défaut, la sortie est abrégée aux champs les plus utiles. Les deux rs268 et 268 sont acceptés.

uv run scripts/dbsnp_cli.py get-variant rs268 --output /tmp/rs268.json
uv run scripts/dbsnp_cli.py get-variant 268 --assembly GCF_000001405.40 \
  --output /tmp/rs268.json

Arguments :

• rsid (positionnel, obligatoire) : L'identifiant RefSNP.
• --assembly : Accession d'assembly RefSeq (par défaut : GCF_000001405.40 = GRCh38).
• --full : Retourner le payload JSON brut complet — voir l'avertissement ci-dessous.
• --output : Chemin du fichier de sortie (par défaut : /tmp/dbsnp_output.json).

Champs de sortie abrégés :

• refsnp_id : rsID numérique
• variant_type : par ex. snv, ins, del, delins
• genes : Liste triée de symboles de gènes (noms de locus)
• clinical_significances : Liste des étiquettes de signification clinique
• minor_allele_frequencies : Nom de l'étude, nombre d'allèles, nombre total
• placements : Placements génomiques pour l'assembly demandé

[!WARNING] À propos de --full : Le payload RefSNP brut fait généralement 50–500 KB et peut dépasser 1 MB pour les variantes cliniquement significatives avec de nombreuses soumissions. N'utilisez --full que quand vous avez spécifiquement besoin de données absentes de la sortie abrégée — par exemple :

• La nomenclature HGVS complète pour tous les transcrits et isoformes protéiques.
• L'historique complet des soumissions avec les détails individuels des soumetteurs et les horodatages.
• Les ventilations des fréquences d'allèles au niveau de la population par sous-population au sein d'une étude (par ex. comptes gnomAD par population).
• L'ensemble complet des placements génomiques sur plusieurs assemblies (GRCh37 et GRCh38 simultanément).
• L'historique de fusion montrant quels rsIDs plus anciens ont été fusionnés dans celui-ci.

2. resolve-variant — Coordonnées génomiques → rsID

Détermine le(s) rsID pour une variante donnée ses coordonnées génomiques (chromosome, position, allèle de référence, allèle alternatif). C'est la commande à utiliser quand l'utilisateur fournit une variante comme coordonnées séparées par des espaces comme 8 19962213 C T.

uv run scripts/dbsnp_cli.py resolve-variant 8 19962213 C T \
  --output /tmp/resolve.json

Arguments :

• chrom (positionnel) : Numéro de chromosome (par ex. 8) ou accession de séquence RefSeq (par ex. NC_000008.11). Les chromosomes X et Y doivent être passés comme leurs équivalents numériques : 23 pour X et 24 pour Y.
• pos (positionnel) : Position génomique basée sur 1.
• ref (positionnel) : Allèle de référence (par ex. C).
• alts (positionnel) : Allèle(s) alternatif(s), séparés par des virgules (par ex. T).
• --assembly : Accession d'assembly RefSeq (par défaut : GCF_000001405.40).
• --output : Chemin du fichier de sortie (par défaut : /tmp/dbsnp_output.json).

Sortie : {"rsids": ["12345", "67890"]}

3. resolve-rsid — rsID → Coordonnées génomiques

Obtient le placement génomique (ID de séquence et détails d'allèles) pour un rsID connu sur un assembly spécifique.

uv run scripts/dbsnp_cli.py resolve-rsid rs7412 --output /tmp/coords.json

Arguments :

• rsid (positionnel) : L'identifiant RefSNP.
• --assembly : Accession d'assembly RefSeq (par défaut : GCF_000001405.40).
• --output : Chemin du fichier de sortie (par défaut : /tmp/dbsnp_output.json).

Sortie : {"rsid": "7412", "assembly": "...", "placements": [...]}

4. resolve-hgvs — HGVS → rsID

Trouve le(s) rsID correspondant à une expression HGVS.

uv run scripts/dbsnp_cli.py resolve-hgvs 'NC_000008.11:g.19962213del' \
  --output /tmp/hgvs.json

Arguments :

• hgvs (positionnel) : La chaîne HGVS.
• --assembly : Accession d'assembly RefSeq (par défaut : GCF_000001405.40).
• --output : Chemin du fichier de sortie (par défaut : /tmp/dbsnp_output.json).

Sortie : {"rsids": ["12345"]}

[!TIP] Les chaînes HGVS contiennent souvent des caractères que les shells interprètent (deux-points, signes supérieurs à). Encadrez-les toujours entre guillemets simples pour éviter l'expansion shell.

5. search-region — Recherche de variantes régionales

Trouve tous les rsIDs dans une région chromosomique bornée.

uv run scripts/dbsnp_cli.py search-region 7 117100000 117300000 \
  --output /tmp/region.json

Arguments :

• chrom (positionnel) : Chromosome (par ex. 7). Utilisez 23 pour le chromosome X et 24 pour le chromosome Y.
• start (positionnel) : Position de début.
• end (positionnel) : Position de fin.
• --retmax : Nombre maximum de rsIDs à retourner (par défaut : 500, plafond : 5 000).
• --output : Chemin du fichier de sortie (par défaut : /tmp/dbsnp_output.json).

Sortie :

{
  "rsids": ["12345", "67890", "..."],
  "returned": 500,
  "total_available": 1423,
  "truncated": true,
  "note": "Only 500 of 1423 variants returned.  Increase --retmax ..."
}

Quand total_available dépasse le nombre de résultats retournés, la sortie inclut un flag truncated et une note. Augmentez --retmax pour récupérer davantage (jusqu'à 5 000).

Workflows typiques

Identifier une variante connue à partir de coordonnées

# Étape 1 : Mapper les coordonnées VCF au rsID
uv run scripts/dbsnp_cli.py resolve-variant 19 44908684 T C \
  --output /tmp/step1.json

# Étape 2 : Obtenir tous les détails pour le rsID résolu
uv run scripts/dbsnp_cli.py get-variant <rsid_from_step1> \
  --output /tmp/step2.json

Explorer les variantes dans une région génique

# Étape 1 : Trouver toutes les variantes dans une région couvrant le gène CFTR
uv run scripts/dbsnp_cli.py search-region 7 117100000 117300000 \
  --retmax 1000 --output /tmp/region.json

# Étape 2 : Récupérer les détails sur les rsIDs individuels d'intérêt
uv run scripts/dbsnp_cli.py get-variant <rsid> --output /tmp/detail.json

Traduire la notation HGVS en coordonnées génomiques

# Étape 1 : Obtenir le rsID pour une expression HGVS
uv run scripts/dbsnp_cli.py resolve-hgvs 'NC_000019.10:g.44908684T>C' \
  --output /tmp/hgvs.json

# Étape 2 : Résoudre ce rsID en coordonnées de style VCF
uv run scripts/dbsnp_cli.py resolve-rsid <rsid> --output /tmp/coords.json

Assemblies par défaut et repli automatique

Les endpoints Variation Services (utilisés par get-variant, resolve-variant, resolve-rsid, resolve-hgvs) attendent une accession d'assembly RefSeq. L'accession RefSeq pour GRCh38 est GCF_000001405.40, et pour GRCh37 elle est GCF_000001405.25.

La sous-commande search-region recherche toujours les positions GRCh38.

[!IMPORTANT] Repli automatique d'assembly : Les commandes resolve-variant et resolve-hgvs essaient automatiquement GRCh38 en premier. Si aucun rsID n'est trouvé, elles réessaient avec GRCh37 avant de signaler l'échec. Quand un repli se produit, la sortie JSON inclut un champ "note" expliquant quel assembly a réussi. Vous n'avez pas besoin de réessayer manuellement avec un assembly différent — le script gère cela de manière transparente.

Vous avez seulement besoin d'annuler --assembly quand vous voulez spécifiquement restreindre la recherche à un assembly (par ex. parce que vous savez que les coordonnées de l'utilisateur sont GRCh37).

Clé API NCBI et limitation de débit

Sans clé API, le script est limité à 3 requêtes par seconde. Avec une clé, cela augmente à 10 requêtes par seconde.

uv run scripts/dbsnp_cli.py get-variant rs268 --output out.json

Si une erreur RateLimitError est levée, pausez l'exécution et suivez les instructions de prérequis pour aider l'utilisateur à ajouter NCBI_API_KEY au fichier .env. Consultez references/api-notes.md pour les détails.

Dépannage des erreurs HTTP 500

Mismatch d'allèle de référence

Si vous recevez une erreur HTTP 500 avec un message détaillant que l'allèle de référence affirmé n'égale pas la séquence de référence :

Ce que cela signifie : La position des coordonnées est probablement valide, mais l'allèle de référence (ref) que vous avez fourni ne correspond pas à la base à cette position dans l'assembly demandé.

Action : 1. NE RÉESSAYEZ PAS mécaniquement exactement la même requête. 2. Vérifiez l'assembly : Les coordonnées sont spécifiques à l'assembly. 3. Changez d'assembly : Si vous interrogiez GRCh37, essayez GRCh38 (en utilisant --assembly GCF_000001405.40), ou si vous interrogiez GRCh38, essayez GRCh37 (en utilisant --assembly GCF_000001405.25).

Erreurs courantes

• Erreur : Oublier de citer les chaînes HGVS Fix : Encadrez entre guillemets simples : 'NC_000008.11:g.19962213del'

• Erreur : Passer un nom de chromosome à resolve-variant au lieu d'une accession de séquence Fix : Utilisez l'ID de chromosome numérique (par ex. 8) ou une accession RefSeq comme NC_000008.11

• Erreur : Utiliser --full sur get-variant sans en avoir besoin Fix : La sortie abrégée couvre la plupart des cas d'usage ; --full retourne 50–500 KB+ de JSON

• Erreur : S'attendre à ce que search-region retourne tous les résultats par défaut Fix : Le --retmax par défaut est 500 ; vérifiez total_available dans la sortie pour voir si les résultats ont été tronqués

• Erreur : Utiliser des coordonnées GRCh37 avec search-region Fix : search-region utilise toujours les positions GRCh38 ; lifez les coordonnées en premier si vous commencez à partir de GRCh37

• Erreur : Réessayer manuellement resolve-variant ou resolve-hgvs avec un --assembly différent quand le premier appel échoue Fix : Le script essaye automatiquement GRCh38 puis GRCh37 ; un seul appel suffit

• Erreur : Passer X ou Y comme valeur de chromosome Fix : Utilisez les équivalents numériques : 23 pour le chromosome X et 24 pour le chromosome Y. Le CLI traite les chromosomes numériquement par défaut.