Base de données ClinVar

Prérequis

1. uv : Lisez le skill uv et suivez ses instructions de configuration pour vous assurer que uv est installé et accessible dans le PATH.

2. Notification utilisateur : Si le fichier LICENSE_NOTIFICATION.txt n'existe pas déjà dans le répertoire de ce skill, alors (1) notifiez l'utilisateur de manière bien visible pour vérifier les conditions à https://www.ncbi.nlm.nih.gov/clinvar/, 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 (facultatif) : Augmente la limite de débit NCBI de 3 à 10 requêtes/seconde. Le skill fonctionne sans, 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'inscrivant à https://www.ncbi.nlm.nih.gov/account/settings/. Si la variable est absente du .env, ne demandez PAS à l'utilisateur de la coller dans le chat (cela fuirait la clé dans le contexte de l'agent). À la place, fournissez cette commande à l'utilisateur — en remplaçant ENV_FILE par le chemin littéral résolu vers le 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 les identifiants automatiquement via dotenv. Ne JAMAIS lire, afficher ou inspecter 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 hors du contexte de l'agent. Voir la section API Key pour plus de détails.

Aperçu

ClinVar est le dossier consensus principal pour les classifications cliniques des variations génomiques humaines. Il fournit la « vérité clinique de référence » pour les labels de pathogénicité (Pathogenic, Likely Pathogenic, Benign, VUS) basés sur les assertions des laboratoires mondiaux.

Quand l'utiliser

Utilisez lorsque vous avez besoin de :

• Trouver la signification clinique actuelle et la cote d'évaluation (statut d'examen) pour une variante spécifique.
• Récupérer les notes cliniciens, critères d'assertion ou justifications pour les classifications de laboratoire clinique antérieures.
• Obtenir le nom de condition préféré et les termes HPO associés pour une variante spécifique.
• Trouver une liste de contrôles de variantes (par ex., « Trouver toutes les variantes Pathogenic du gène HBB à moins de 50 pb d'un signal »).
• Vérifier les interprétations contradictoires pour une variante donnée et identifier les organisations qui soumettent chaque classification.

Ne l'utilisez PAS lorsque vous avez besoin de :

• Trouver des fréquences d'allèles spécifiques dans les populations mondiales (utilisez gnomAD).
• Décrire le rôle biologique normal d'une protéine et les modes de transmission typiques (utilisez OMIM).
• Prédire les effets mécanistiques de mutations nouvelles, comme les décalages du cadre ou l'exon skipping (utilisez AlphaGenome).
• Trouver les calendriers de surveillance recommandés pour les patients porteurs d'une variante pathogène (utilisez GeneReviews).
• Générer ou afficher des modèles structuraux 3D de protéines affectées (utilisez PDB / AlphaFold).

Démarrage rapide

Les requêtes ClinVar sont exécutées via un robuste script wrapper Python pour gérer les limites de débit strictes et l'analyse XML/JSON.

Exemple : Rechercher les variantes BRCA1

uv run scripts/clinvar_api.py search --query "BRCA1[gene]" --output results.json

Règles essentielles

• Contrainte Retmax : La commande search utilise par défaut --retmax 200. Pour toute requête « Lister tout » ou au niveau du gène, vous DEVEZ définir explicitement --retmax plus haut (par ex., 1000) pour assurer la complétude des données.
• Utilisez le Wrapper : Préférez le script wrapper pour les requêtes standard. Il gère la limitation de débit, les tentatives et l'analyse XML complexe pour vous. Si la sortie analysée du script ne contient pas les champs spécifiques dont vous avez besoin, vous pouvez modifier le script ou interroger directement l'API NCBI E-utilities — mais sachez que les schémas XML bruts sont complexes et varient selon les types d'enregistrements.
• Si la limite de débit est atteinte, le script lèvera une erreur claire. Suivez les instructions de prérequis ci-dessus pour aider l'utilisateur à ajouter NCBI_API_KEY au fichier .env.
• Notification : Si ce skill est utilisé, assurez-vous que cela est mentionné dans la sortie.

Scripts utilitaires

1. count — Compter les variantes correspondantes

Objectif : Vérifier combien de variantes correspondent à une requête sans récupérer les ID. Utile pour décider si une search complète est justifiée.

Arguments :

• --query : (Requis) Chaîne de requête NCBI Entrez.
• --output : (Requis) Chemin du fichier JSON de sortie.

Exemple : uv run scripts/clinvar_api.py count \ --query "TP53[gene] AND \"uncertain significance\"[clinsig]" \ --output count.json Sortie : {"total_count": <int>}

2. search — Rechercher des variantes

Objectif : Identifier les variantes en fonction de la localisation génomique, des symboles de gène ou des attributs cliniques en utilisant la syntaxe NCBI Entrez. La commande search paginates automatiquement à travers tous les résultats correspondants pour assurer une récupération complète et déterministe.

# Récupérer TOUTES les variantes correspondantes (comportement par défaut)
uv run scripts/clinvar_api.py search \
  --query "BRCA1[gene]" --output results.json

# Rechercher par chromosome et plage de position
uv run scripts/clinvar_api.py search \
  --query "11[chr] AND 5225000:5226000[chrpos]" --output results.json

# Combiner les termes en utilisant la syntaxe Entrez
uv run scripts/clinvar_api.py search \
  --query "HBB[gene] AND pathogenic[clinsig]" --output results.json

# Limiter les résultats à 50
uv run scripts/clinvar_api.py search \
  --query "TP53[gene]" --retmax 50 --output results.json

Arguments :

• --query : (Requis) Chaîne de requête NCBI Entrez.
• --retmax : Nombre total maximum d'ID de variantes à retourner. Par défaut 0, ce qui signifie « récupérer tous les résultats correspondants ». Définissez un entier positif pour limiter l'ensemble des résultats.
• --page_size : Nombre d'ID à récupérer par requête API (défaut : 500, max : 10000 selon les limites NCBI).
• --output : (Requis) Chemin du fichier JSON de sortie.

Sortie : Un objet JSON contenant :

• total_count — Nombre total de variantes correspondantes dans ClinVar.
• fetched_count — Nombre d'ID réellement récupérés.
• variant_ids — Liste des chaînes d'ID de variation ClinVar.

3. summary — Obtenir un résumé d'interprétation

Objectif : Récupérer les labels de signification clinique essentiels, les cotes d'évaluation (statut d'examen) et les données phénotypiques basiques pour le dépistage rapide des variantes.

# Obtenir un résumé pour un ou plusieurs ID de variation
uv run scripts/clinvar_api.py summary \
  --variant_ids 12345 67890 --output summary.json

Arguments :

• --variant_ids : (Requis) Un ou plusieurs ID de variation ClinVar.
• --output : (Requis) Chemin du fichier JSON de sortie.

Sortie : Une liste JSON d'objets résumés, chacun contenant :

• variant_id, title, clinical_significance, review_status, \ last_evaluated, phenotypes
• genes — liste de {gene_id, symbol, strand}
• variation_type — par ex., single nucleotide variant, Deletion, Insertion
• molecular_consequences — liste de chaînes (par ex., ["missense variant", \ "nonsense"])

4. evidence — Obtenir des preuves cliniques

Objectif : Récupérer l'enregistrement clinique complet pour une variante unique, y compris les justifications libres des cliniciens, les méthodes d'assertion et les notes spécifiques aux soumettants.

# Obtenir la preuve complète pour un seul ID de variation
uv run scripts/clinvar_api.py evidence \
  --variant_id 12345 --output evidence.json

Arguments :

• --variant_id : (Requis) Un seul ID de variation ClinVar.
• --output : (Requis) Chemin du fichier JSON de sortie.

Sortie : Un objet JSON contenant :

• variant_id
• allele_info — {chromosome, position_start, position_stop, reference_allele, alternate_allele, cytogenetic_band, dbsnp_rsid} (GRCh38 préféré)
• conditions — liste de {name, medgen_cui, omim_id, orphanet_id, hpo_terms}
• functional_consequences — liste de {value, sequence_ontology_id}
• structural_variant_details — {outer_start, inner_start, inner_stop, outer_stop, copy_number} (présent uniquement pour les CNVs, sinon null)
• citation_references — liste d'ID PubMed cités dans la section « Citations » globale
• submissions — liste d'enregistrements par soumettant, chacun contenant :
  • submitter_name, classification, curator_notes, assertion_criteria
  • date_last_evaluated — quand le soumettant a examiné en dernier la classification

Workflows typiques

Workflow Count-First (recommandé)

Pour les ensembles de résultats volumineux ou inconnus, utilisez d'abord count pour décider de procéder, puis search (qui pagine automatiquement et retourne total_count / fetched_count), puis summary pour dépister.

# Étape 1 : Évaluer la taille (facultatif — search retourne aussi total_count)
uv run scripts/clinvar_api.py count \
  --query "HBB[gene] AND pathogenic[clinsig]" --output count.json

# Étape 2 : Récupérer tous les ID de variantes (paginates automatiquement)
uv run scripts/clinvar_api.py search \
  --query "HBB[gene] AND pathogenic[clinsig]" --output ids.json

# Étape 3 : Obtenir les résumés (extraire variant_ids de la sortie search)
uv run scripts/clinvar_api.py summary \
  --variant_ids 12345 67890 --output summary.json

Deep Dive : search → evidence

Lorsque vous avez besoin de la vue clinique complète pour une variante spécifique — y compris les justifications des soumettants, les citations PubMed, les conditions liées à l'ontologie et les coordonnées d'allèle — utilisez evidence.

uv run scripts/clinvar_api.py evidence \
  --variant_id 12345 --output evidence.json

Workflow : Découverte robuste de variantes (triangulation)

Les métadonnées ClinVar sont incohérentes. Pour satisfaire les requêtes « Lister tout », ne vous fiez pas à un seul filtre. Effectuez ce qui suit en une seule étape et fusionnez les résultats :

1. Rechercher par label exact (par ex., "3 prime UTR variant"[molecular_consequence]).
2. Rechercher par motif de nomenclature HGVS (par ex., c.*).
3. Rechercher par plage de coordonnées génomiques (en utilisant [chrpos]).

Cette « triangulation » garantit que les variantes structurales avec des labels manquants ne sont pas oubliées.

Vérification du statut Coding vs. Non-Coding via HGVS

molecular_consequences seul peut être ambigu (par ex., splice donor variant apparaît dans les contextes à la fois coding et non-coding). Vérifiez toujours le champ title pour les motifs HGVS :

• c.-… — 5' UTR (non-coding)
• c.*… — 3' UTR (non-coding)
• c.123+N / c.123-N — intronic (non-coding)
• p.Trp146Arg etc. — effet protéique (coding)

Une variante avec HGVS UTR/intronic et pas d'annotation p. est non-coding, même avec des labels de épissage. Inversement, toute annotation p. indique un effet coding.

Référence des métadonnées ClinVar

• 3' UTR
  • Chaîne de recherche : "3 prime UTR variant"[mol_consequence]
  • HGVS : c.*
• 5' UTR
  • Chaîne de recherche : "5 prime UTR variant"[mol_consequence]
  • HGVS : c.-
• Pour trouver les variantes « haute confiance » ou le consensus examiné par un expert, utilisez le filtre review_status. C'est le moyen le plus efficace de distinguer entre les assertions d'un seul laboratoire et la vérité de référence examinée par un panel.

Quand utiliser quels champs

• Label de pathogénicité rapide — Utilisez summary → clinical_significance
• Symbole de gène et brin — Utilisez summary → genes
• Type de variante (SNV, del, etc.) — Utilisez summary → variation_type
• Effet au niveau protéique — Utilisez summary → molecular_consequences
• Coordonnées génomiques (GRCh38) — Utilisez evidence → allele_info
• Conditions liées (ontologie) — Utilisez evidence → conditions
• Conséquence fonctionnelle SO — Utilisez evidence → functional_consequences
• Points de rupture CNV/nombre de copies — Utilisez evidence → structural_variant_details
• Références PubMed — Utilisez evidence → citation_references
• Date du dernier examen par le laboratoire — Utilisez les deux → last_evaluated
• Justifications cliniciennes — Utilisez evidence → submissions[].curator_notes

Récupération des coordonnées génomiques (HG38/GRCh38 par défaut)

Pour obtenir les coordonnées génomiques précises au format <chrom>:<pos>:<ref>><alt> (par ex., chr5:70951945:G>A), vous devez utiliser la commande evidence, car ces détails ne sont pas disponibles dans la sortie summary.

Vous DEVEZ TOUJOURS inclure les coordonnées génomiques au format <chrom>:<pos>:<ref>><alt> lors du listage ou de la présentation de variantes, même si ce n'est pas explicitement demandé par l'utilisateur. Si les coordonnées sont manquantes du résumé, utilisez la commande evidence ou le fallback dbSNP pour les récupérer.

1. Récupérer la preuve : Utilisez uv run scripts/clinvar_api.py evidence --variant_id <ID> --output evidence.json.
2. Extraire les attributs VCF : La commande evidence analyse le XML. Extrayez :
   • Chromosome : Chr
   • Position : positionVCF (ou start)
   • Ref : referenceAlleleVCF (ou referenceAllele)
   • Alt : alternateAlleleVCF (ou alternateAllele) de l'élément SequenceLocation avec Assembly="GRCh38".

Fallback pour les coordonnées imprécises (plage génique) : ClinVar retourne souvent la plage génique complète pour les variantes non-coding. Si les coordonnées extraites correspondent à la plage génique plutôt qu'à une position spécifique, utilisez le skill dbsnp-database pour résoudre les coordonnées précises en utilisant le dbsnp_rsid ou le titre HGVS : 1. Vérifiez la présence de dbsnp_rsid dans la sortie evidence. 2. Exécutez uv run scripts/dbsnp_cli.py resolve-rsid {rsid} pour obtenir les coordonnées GRCh38 précises. 3. Formatez comme <chrom>:<pos>:<ref>><alt> en utilisant les données SPDI ou HGVS de dbSNP.

Remarque sur les variantes structurales

Le champ structural_variant_details est rempli uniquement pour les variantes de nombre de copies (CNVs). Pour les SNVs standards et petits indels, ce champ sera null. Utilisez les champs allele_info (position_start, position_stop, reference_allele, alternate_allele) à la place.

Remarque sur CNV / Large Deletion

Les grandes variantes de nombre de copies (CNVs) ont fréquemment des molecular_consequences vides. Si un titre de variante mentionne « del » et que les coordonnées chevauchent votre région cible, elle est pertinente indépendamment des labels manquants.

Obtention et utilisation d'une clé API

Pour augmenter la limite de débit à 10 requêtes par seconde, vous devez obtenir une clé API NCBI et l'ajouter au fichier .env. Vous pouvez obtenir une clé en suivant les instructions à NCBI ClinVar API docs

Une fois que vous avez une clé, suivez les instructions de prérequis pour l'ajouter au fichier .env.

uv run scripts/clinvar_api.py search --query "BRCA1[gene]" --output results.json

Si une RateLimitError est rencontrée, suivez les instructions de prérequis pour aider l'utilisateur à ajouter NCBI_API_KEY au fichier .env, en fournissant l'URL NCBI ClinVar API docs pour les instructions sur la façon d'en obtenir une.

Bonnes pratiques

• Utilisez toujours uv run pour exécuter python.
• Si jq n'est pas disponible, passez immédiatement à l'utilisation de one-liners Python pour traiter le JSON (par ex., uv run python3 -c "import json; ...").
• Utilisez count avant search pour comprendre la taille de l'ensemble des résultats.
• La commande search récupère tous les résultats par défaut et inclut total_count et fetched_count dans la sortie — vérifiez toujours que ces chiffres correspondent pour confirmer la récupération complète.
• Les résultats Entrez sont non triés. Pour trier par date, récupérez tous les résultats et triez localement par last_evaluated.

Erreurs courantes

• Essayer d'analyser le XML E-utilities vous-même — Utilisez toujours le client clinvar_api.py fourni, qui gère robustement les schémas XML imprévisibles.
• Obtenir HTTP 429 Too Many Requests — Le client lève une exception vous disant de faire une pause. Suivez les instructions de prérequis pour aider l'utilisateur à ajouter NCBI_API_KEY au fichier .env, puis réessayez.
• Envoyer des séquences d'ADN brutes à l'API — L'API attend la nomenclature HGVS, les ID RS ou la syntaxe de coordonnées Entrez appropriée (11[chr] AND 1234[chrpos]), pas les chaînes brutes ATCG.
• Pour les variantes synonymes ou non-coding — La nomenclature HGVS (par ex., CAPN3 AND « c.551C>T ») est plus fiable que les recherches de coordonnées ([chrpos]), car de nombreux enregistrements ClinVar pour ces types n'ont pas de cartographie génomique précise.
• Sensibilité à la casse dans les conséquences moléculaires — ClinVar retourne des chaînes de casse mixte. Utilisez toujours la correspondance insensible à la casse (.lower()) lors du filtrage.
• Analyser la sortie search comme une liste bare — search retourne un objet JSON avec total_count, fetched_count et variant_ids — pas une liste bare.