OneKGPd

OneKGPd : requêtes au niveau individuel sur le projet 1000 Génomes

Périmètre

Cette compétence interroge le jeu de données du projet 1000 Génomes — la cohorte étendue à haute couverture de 3 202 individus séquencés en génome entier, sur l'assemblage GRCh38. Tous les résultats sont issus de cette cohorte, et les noms d'échantillons renvoyés par la compétence (par exemple HG00096 ou NA21130) identifient ses participants.

Les requêtes sont résolues sur les données génotypiques par individu de la cohorte. Cela permet deux classes complémentaires de questions : la sélection des variants portés dans une région (sur toute la cohorte ou dans un ensemble spécifié d'individus), et la sélection des individus qui portent des variants correspondant à des critères donnés. La sélection des variants peut être filtrée par fréquence allélique, conséquence prédite, signification clinique, classification AlphaMissense et les autres axes d'annotation listés ci-dessous. La parenté entre deux individus nommés est également disponible.

L'état génotypique dans lequel un variant est porté — hétérozygote ou homozygote — est un critère que les requêtes peuvent préciser ; les résultats sont renvoyés sous forme de variants ou de noms d'échantillons, pas de génotypes bruts.

Quand utiliser

Utilisez cette compétence lorsque vous avez besoin de :

• Trouver des variants portés dans une région ou un ensemble de régions correspondant à certains critères sur toute la cohorte (select-variants).
• Trouver des variants portés dans une région ou un ensemble de régions correspondant à certains critères dans un ensemble spécifique d'individus (select-variants-in-samples).
• Trouver quels individus du projet 1000 Génomes portent des variants correspondant à certains critères dans une région ou un ensemble de régions (select-samples).
• Compter combien d'individus portent des variants spécifiques (count-samples).
• Restreindre toute requête de variants à un portage hétérozygote uniquement ou homozygote uniquement, ou interroger les deux ensemble (par défaut).
• Identifier les individus qui sont homozygotes de référence à une position unique (select-samples-hom-ref).
• Déterminer la parenté entre deux individus nommés du projet 1000 Génomes — à la fois le degré (jumeau / 1er / 2e / 3e / non apparenté) et le coefficient de parenté KING (kinship).
• Obtenir les totaux du jeu de données — nombre d'échantillons, répartition par sexe, nombre de variants, assemblage (dataset-info).
• La sélection des variants peut être spécifiée par la fréquence allélique KGP, la fréquence allélique des exomes gnomAD 4.1 et des génomes gnomAD 4.1, le score AlphaMissense et la classe AlphaMissense, la signification ClinVar (202502), et les annotations VEP (impact, biotype, type de caractéristique, classe de variant, conséquences).

N'utilisez PAS cette compétence pour :

• Résoudre un symbole de gène, un rsID ou un transcrit en coordonnées, ou récupérer une séquence de référence. Résolvez d'abord les coordonnées (voir Provenance des coordonnées ci-dessous), puis interrogez cette compétence avec la région GRCh38 résolue.
• Toute cohorte autre que le projet 1000 Génomes — cette compétence ne sert que ce jeu de données.

Prérequis

1. uv : Le script de cette compétence est exécuté avec uv run, qui lit les métadonnées de dépendances en ligne du script et provisionne un environnement éphémère. Assurez-vous que uv est installé et dans le PATH (https://docs.astral.sh/uv/).
2. Conditions d'utilisation des données : Les données du projet 1000 Génomes sont ouvertes ; les utilisateurs doivent connaître les conditions d'utilisation des données du projet 1000 Génomes / IGSR (https://www.internationalgenome.org/data).
3. Contraintes d'accès : Il n'y a pas de clé API, pas de fichier .env, et pas de jeton de limite de débit à configurer.
4. Aucune information d'identification requise

Règles fondamentales

• Utilisez les wrappers : Exécutez TOUJOURS les scripts d'assistance fournis plutôt que de construire vos propres appels client ou requêtes réseau. Utilisez scripts/onekgpd_api.py pour les requêtes de variants/échantillons/parenté (il gère la connexion, le streaming, la pagination et la sérialisation JSON), et scripts/onekgpd_meta.py pour les métadonnées d'échantillons/populations (hors ligne, voir Métadonnées d'échantillons et de populations).
• Les coordonnées DOIVENT être résolues d'abord par rapport à une source faisant autorité — voir Provenance des coordonnées. C'est obligatoire, pas facultatif.
• Comptez avant de sélectionner : chaque sélection de variant et d'échantillon a une commande de comptage associée. Appelez la commande de comptage en PREMIER pour évaluer la taille de l'ensemble de résultats, puis sélectionnez uniquement si le nombre est gérable.
• La zygosité par défaut est les deux : les commandes de sélection et de comptage incluent par défaut le portage hétérozygote et homozygote. Réduisez avec --het-only ou --hom-only lorsque la question concerne spécifiquement un état. (Vous n'avez pas besoin de passer quoi que ce soit pour obtenir les deux.)
• Sortie : les scripts écrivent le JSON complet dans un fichier (--output, par défaut sous /tmp/) et affichent un résumé concis sur stdout. Ne lisez pas les grands fichiers JSON dans le contexte — utilisez jq ou un petit snippet uv run python jetable pour extraire les champs.

Provenance des coordonnées (ÉTAPE OBLIGATOIRE)

Avant toute requête basée sur une région, résolvez le gène ou la caractéristique en coordonnées GRCh38 par rapport à une source faisant autorité (par exemple Ensembl), et interrogez avec ces coordonnées résolues. L'assemblage doit être explicite, et une plage génique doit être résolue en positions précises avant utilisation. C'est structurel, pas facultatif : il n'y a pas de barrière de sécurité côté source qui signalerait une région mal placée, donc une coordonnée non vérifiée produit des résultats pour un emplacement non intentionnel sans erreur.

# Résolvez d'abord le symbole du gène -> région GRCh38 avec une source faisant autorité,
# puis passez les coordonnées vérifiées à la requête OneKGPd ci-dessous.

[!ATTENTION] Le jeu de données est GRCh38. Une coordonnée GRCh37, ou toute région qui ne correspond pas correctement à la caractéristique prévue sur GRCh38, renverra des résultats pour un emplacement non intentionnel sans déclencher d'erreur. Vérifiez l'assemblage et les coordonnées résolues avant d'interroger.

Guide de sélection des commandes

Faites correspondre la question à la commande. Les commandes de comptage sont économiques et doivent précéder leur commande de sélection correspondante.

• Quels individus portent des variants correspondants dans une région ? → count-samples puis select-samples
• Quels variants sont portés dans une région, sur toute la cohorte ? → count-variants puis select-variants
• Quels variants sont portés dans une région, dans un ensemble nommé d'individus ? → count-variants-in-samples puis select-variants-in-samples
• Qui est homozygote de référence à une position unique ? → count-samples-hom-ref puis select-samples-hom-ref
• Parenté (degré + coefficient) entre deux individus nommés ? → kinship
• Totaux du jeu de données (nombre d'échantillons, répartition par sexe, total des variants, assemblage) → dataset-info

Filtres d'annotation (partagés entre la sélection/le comptage de variants et d'échantillons)

Toutes les commandes de sélection et de comptage de variants et d'échantillons (count-variants, select-variants, leurs formes -in-samples, count-samples, select-samples) acceptent les mêmes filtres d'annotation. Différents champs de filtre sont combinés avec ET ; plusieurs valeurs dans un même champ sont combinées avec OU. Les valeurs d'énumération sont insensibles à la casse (par exemple missense_variant ou MISSENSE_VARIANT).

Ce sont des critères de sélection appliqués sur le serveur. Les champs renvoyés sur un variant sélectionné sont listés dans Commandes renvoyant des variants ; un critère utilisé pour le filtrage n'est pas nécessairement renvoyé sur le variant.

• --af-lt / --af-gt : limites de fréquence allélique du jeu de données 1000 Génomes
• --gnomad-exomes-af-lt / --gnomad-exomes-af-gt : limites de fréquence allélique des exomes gnomAD v4.1
• --gnomad-genomes-af-lt / --gnomad-genomes-af-gt : limites de fréquence allélique des génomes gnomAD v4.1
• --clin-significance : termes de signification ClinVar, CSV (par exemple PATHOGENIC,LIKELY_PATHOGENIC)
• --consequence : termes de conséquence de l'Ontologie des Séquences, CSV (par exemple MISSENSE_VARIANT,STOP_GAINED)
• --impact : impact VEP, CSV (HIGH,MODERATE,LOW,MODIFIER)
• --variant-type, --feature-type, --bio-type : classe de variant SO / caractéristique VEP / biotype VEP, CSV
• --alpha-missense-class : AM_LIKELY_BENIGN,AM_LIKELY_PATHOGENIC,AM_AMBIGUOUS (CSV)
• --alpha-missense-score-lt / --alpha-missense-score-gt : limites du score AlphaMissense
• --biallelic-only / --multiallelic-only
• --exclude-males / --exclude-females
• --min-len-bp / --max-len-bp : limites de longueur de l'allèle alternatif (pb)

[!NOTE] --alpha-missense-class et --alpha-missense-score-* s'excluent mutuellement (le moteur ignore la classe lorsqu'une limite de score est définie). --biallelic-only et --multiallelic-only s'excluent mutuellement. --exclude-males et --exclude-females s'excluent mutuellement. Définir une limite *-gt supérieure ou égale à sa limite *-lt correspondante définit une plage vide et ne renverra rien.

[!NOTE] Les champs de fréquence allélique utilisent 0.0 pour signifier "non présent dans cette source." Ainsi --gnomad-exomes-af-gt 0 sélectionne les variants qui sont dans les exomes gnomAD ; un gnomad_exomes_af renvoyé de 0.0 signifie que le variant est absent des exomes gnomAD. Même convention pour la fréquence allélique des génomes gnomAD. Inversement, les limites --gnomad-exomes-af-lt / --gnomad-genomes-af-lt incluent les variants non annotés : "AF < X dans gnomAD" inclut les variants avec AF gnomAD = 0, c'est-à-dire non annotés ; associez-le avec --gnomad-*-af-gt 0 pour exiger la présence dans gnomAD.

[!NOTE] am_score de 0.0 signifie non scoré ou non annoté par AlphaMissense - cela ne signifie pas bénin. Un vrai score AlphaMissense est toujours supérieur à 0.

Démarrage rapide

# Étape 1. Résolvez les coordonnées par rapport à une source faisant autorité — voir
#    Provenance des coordonnées.
#    exemple : BRCA1: chr17:43044292-43170245
# Étape 2. Évaluez la taille de l'ensemble de résultats : combien d'individus portent
#    des variants faux-sens prédits comme potentiellement pathogènes dans cette région ?
uv run scripts/onekgpd_api.py count-samples \
  --chrom chr17 --start 43044292 --end 43170245 \
  --consequence MISSENSE_VARIANT \
  --alpha-missense-class AM_LIKELY_PATHOGENIC \
  --output /tmp/count.json
# Étape 3. Si le nombre est gérable, listez ces individus.
uv run scripts/onekgpd_api.py select-samples \
  --chrom chr17 --start 43044292 --end 43170245 \
  --consequence MISSENSE_VARIANT \
  --alpha-missense-class AM_LIKELY_PATHOGENIC \
  --output /tmp/samples.json
# Étape 4 : Pour cet ensemble d'individus, voyez les variants réels qu'ils portent.
uv run scripts/onekgpd_api.py select-variants-in-samples \
  --chrom chr17 --start 43044292 --end 43170245 \
  --samples HG03169,NA20506 \
  --consequence MISSENSE_VARIANT --alpha-missense-class AM_LIKELY_PATHOGENIC \
  --output /tmp/variants.json

Commandes

Chaque commande écrit le JSON complet dans un fichier (--output CHEMIN, par défaut un fichier temporaire) et affiche un résumé concis sur stdout. Toutes les commandes de région/d'échantillons partagent : l'entrée de région (--chrom/--start/--end avec --ref/--alt optionnels, ou une ou plusieurs --region CHR:START-END répétées), les indicateurs de zygosité (--het-only/--hom-only, par défaut les deux), et les filtres d'annotation ci-dessus. Les tableaux complets par indicateur se trouvent dans références/onekgpd_commands.md.

Commandes renvoyant des variants

select-* renvoie les variants correspondants ; count-* renvoie un nombre entier.

• count-variants — compte les variants dans une région, sur toute la cohorte.
• select-variants — sélectionne les variants dans une région, sur toute la cohorte. Utilisez --limit N (limite stricte, par défaut 200) ou --page-size N (récupère l'ensemble complet par pages) ; les deux s'excluent mutuellement. Le résumé marque truncated lorsque la limite est atteinte.
• count-variants-in-samples — comme count-variants, restreint à --samples NOM1,NOM2,... (obligatoire).
• select-variants-in-samples — comme select-variants, restreint à --samples NOM1,NOM2,... (obligatoire).

Chaque variant renvoyé porte ces 22 clés : chr, start, end, ref, alt, af, ac, an, hom_samples, het_samples, mis_samples, hom_samples_fx, het_samples_fx, mis_samples_fx, hom_samples_mxy, het_samples_mxy, mis_samples_mxy, gnomad_exomes_af, gnomad_genomes_af, am_score, amino_acids, biallelic. La signification ClinVar et la conséquence VEP sont uniquement des critères de filtrage et ne sont pas renvoyées. Schéma complet : références/onekgpd_commands.md.

Commandes renvoyant des échantillons

• count-samples — compte les individus portant un variant correspondant dans une région.
• select-samples — liste les noms des individus portant un variant correspondant. Supporte --skip N et --limit N. Renvoie uniquement les noms ; pour voir quels variants qualifient un individu, passez les noms dans select-variants-in-samples.

Commandes homozygotes de référence

Position unique via --chrom + --position (pas une région).

• count-samples-hom-ref — compte les individus avec un appel 0/0 à la position. Le nombre est un sentinelle : -1 = aucun variant n'existe à cette position du tout ; 0 = un variant existe mais aucun individu n'est homozygote de référence ; >0 = le nombre d'individus homozygotes de référence. Le résumé indique le cas.
• select-samples-hom-ref — liste les individus avec un appel 0/0 à la position.

Commande de parenté

• kinship --sample1 NOM --sample2 NOM — parenté entre deux individus nommés : le degré (TWINS_MONOZYGOTIC / FIRST_DEGREE / SECOND_DEGREE / THIRD_DEGREE / UNRELATED) et le coefficient de parenté KING (phi_bwf).

Commande de métadonnées du jeu de données

• dataset-info — totaux du jeu de données : samples_total (3 202), répartition femmes/hommes, variants_total, assembly (GRCh38), et la répartition par cohorte. Aucune région requise ; sert également de vérification de connectivité.

Métadonnées d'échantillons et de populations (hors ligne)

Les questions de population, de sexe, de pedigree et de superpopulation sont traitées par un deuxième script, scripts/onekgpd_meta.py, à partir d'un fichier de données inclus dans la compétence — aucun réseau, aucune information d'identification, aucune coordonnée. Les ID d'échantillons sont les mêmes noms que ceux utilisés par les commandes de variants, donc les deux couches se composent (par exemple, choisissez une cohorte par population, puis interrogez ses variants). Exécutez uv run scripts/onekgpd_meta.py <commande>.

La cohorte compte 5 superpopulations (AFR, AMR, EAS, EUR, SAS) et 26 populations.