OneKGPd

OneKGPd: Individuenbasierte Abfragen des 1000-Genome-Projekts

Umfang

Dieses Skill durchsucht den Datensatz des 1000-Genome-Projekts – die erweiterte Hochabdeckungskohorte von 3.202 vollständig genomsequenzierten Individuen, basierend auf der GRCh38-Assemblierung. Alle Ergebnisse stammen aus dieser Kohorte, und die vom Skill zurückgegebenen Probennamen (z. B. HG00096 oder NA21130) identifizieren deren Teilnehmer.

Abfragen werden gegen die genotypischen Daten jedes Individuums der Kohorte aufgelöst. Dies unterstützt zwei komplementäre Frageklassen: die Auswahl von Varianten, die in einer Region getragen werden (kohortenweit oder in einer bestimmten Gruppe von Individuen), sowie die Auswahl der Individuen, die Varianten mit bestimmten Kriterien tragen. Die Variantenauswahl kann nach Allelfrequenz, vorhergesagter Konsequenz, klinischer Signifikanz, AlphaMissense-Klassifikation und den unten aufgeführten anderen Annotationen gefiltert werden. Auch die Verwandtschaft zwischen zwei benannten Individuen ist verfügbar.

Der Genotyp-Status, in dem eine Variante getragen wird – heterozygot oder homozygot – ist ein Kriterium, das Abfragen angeben können; Ergebnisse werden als Varianten oder als Probennamen zurückgegeben, nicht als rohe Genotypen.

Verwendung

Verwenden Sie dieses Skill, wenn Sie:

• Varianten finden möchten, die in einer Region oder mehreren Regionen getragen werden und bestimmte Kriterien in der gesamten Kohorte erfüllen (select-variants).
• Varianten finden möchten, die in einer Region oder mehreren Regionen getragen werden und bestimmte Kriterien in einer bestimmten Gruppe von Individuen erfüllen (select-variants-in-samples).
• Herausfinden möchten, welche 1000-Genome-Individuen Varianten tragen, die bestimmte Kriterien in einer Region oder mehreren Regionen erfüllen (select-samples).
• Zählen möchten, wie viele Individuen bestimmte Varianten tragen (count-samples).
• Jede Variantenabfrage auf heterozygote oder homozygote Träger beschränken möchten, oder beide zusammen abfragen möchten (Standard).
• Identifizieren möchten, welche Individuen an einer einzelnen Position homozygot für die Referenz sind (select-samples-hom-ref).
• Die Verwandtschaft zwischen zwei benannten 1000-Genome-Individuen bestimmen möchten – sowohl den Grad (Zwilling / 1. / 2. / 3. Grad / nicht verwandt) als auch den KING-Verwandtschaftskoeffizienten (kinship).
• Gesamtzahlen des Datensatzes erhalten möchten – Anzahl der Proben, Geschlechterverteilung, Variantenanzahl, Assemblierung (dataset-info).
• Die Variantenauswahl kann nach KGP-Allelfrequenz, gnomAD 4.1 Exom- und gnomAD 4.1 Genom-Allelfrequenz, AlphaMissense-Score und AlphaMissense-Klasse, ClinVar-Signifikanz (202502) und VEP-Annotationen (Auswirkung, Biotyp, Feature-Typ, Variantenklasse, Konsequenzen) spezifiziert werden.

Verwenden Sie dieses Skill NICHT für:

• Die Auflösung eines Gensymbols, einer rsID oder eines Transkripts in Koordinaten, oder das Abrufen der Referenzsequenz. Lösen Sie zuerst die Koordinaten auf (siehe Koordinatenherkunft unten), und fragen Sie dann dieses Skill mit den aufgelösten GRCh38-Koordinaten ab.
• Jede andere Kohorte als das 1000-Genome-Projekt – dieses Skill dient nur diesem Datensatz.

Voraussetzungen

1. uv: Das Skript dieses Skills wird mit uv run ausgeführt, das die Inline-Abhängigkeitsmetadaten des Skripts liest und eine temporäre Umgebung bereitstellt. Stellen Sie sicher, dass uv installiert und im PATH ist (https://docs.astral.sh/uv/).
2. Nutzungsbedingungen: Die Daten des 1000-Genome-Projekts sind offen; Benutzer sollten sich der Nutzungsbedingungen des 1000-Genome-Projekts / IGSR bewusst sein (https://www.internationalgenome.org/data).
3. Zugriffsbeschränkungen: Es gibt keinen API-Schlüssel, keine .env-Datei und kein Ratenbegrenzungs-Token, das konfiguriert werden muss.
4. Keine Anmeldeinformationen erforderlich

Kernregeln

• Verwenden Sie die Wrapper: Führen Sie IMMER die bereitgestellten Hilfsskripte aus, anstatt Ihre eigenen Client-Aufrufe oder Netzwerkanfragen zu konstruieren. Verwenden Sie scripts/onekgpd_api.py für Varianten-/Proben-/Verwandtschaftsabfragen (es übernimmt die Verbindung, das Streaming, die Paginierung und die JSON-Serialisierung), und scripts/onekgpd_meta.py für Proben-/Populationsmetadaten (offline, siehe Proben- & Populationsmetadaten).
• Koordinaten MÜSSEN zuerst gegen eine autoritative Quelle aufgelöst werden – siehe Koordinatenherkunft. Dies ist zwingend, nicht empfohlen.
• Zählen Sie vor dem Auswählen: Jede Varianten- und Probenauswahl hat einen gepaarten Zähl-Befehl. Führen Sie den Zähl-Befehl ZUERST aus, um die Größe des Ergebnisses zu ermitteln, und wählen Sie dann nur aus, wenn die Anzahl überschaubar ist.
• Zygosität standardmäßig beide: Auswahl- und Zähl-Befehle umfassen standardmäßig sowohl heterozygote als auch homozygote Träger. Schränken Sie mit --het-only oder --hom-only ein, wenn die Frage sich auf einen bestimmten Zustand bezieht. (Sie müssen nichts übergeben, um beide zu erhalten.)
• Ausgabe: Skripte schreiben vollständiges JSON in eine Datei (--output, standardmäßig unter /tmp/) und geben eine prägnante Zusammenfassung auf stdout aus. Lesen Sie keine großen JSON-Dateien in den Kontext – verwenden Sie jq oder ein kleines, einmalig ausgeführtes uv run python-Snippet, um Felder zu extrahieren.

Koordinatenherkunft (Zwingender erster Schritt)

Lösen Sie vor jeder regionsbasierten Abfrage das Gen oder Merkmal in GRCh38-Koordinaten gegen eine autoritative Quelle (z. B. Ensembl) auf, und führen Sie die Abfrage mit diesen aufgelösten Koordinaten durch. Die Assemblierung muss explizit sein, und ein Genbereich muss vor der Verwendung in präzise Positionen aufgelöst werden. Dies ist strukturell, nicht empfohlen: Es gibt keine serverseitige Sicherung, die einen falsch platzierten Bereich abfangen würde, daher liefert eine ungeprüfte Koordinate Ergebnisse für eine unbeabsichtigte Position ohne Fehler.

# Lösen Sie zuerst das Gensymbol -> GRCh38-Region mit einer autoritativen Quelle auf,
# und übergeben Sie dann die verifizierten Koordinaten an die OneKGPd-Abfrage unten.

[!CAUTION] Der Datensatz ist GRCh38. Eine GRCh37-Koordinate oder jede Region, die nicht korrekt der beabsichtigten Position auf GRCh38 entspricht, wird Ergebnisse für eine unbeabsichtigte Position zurückgeben, ohne einen Fehler auszulösen. Überprüfen Sie die Assemblierung und die aufgelösten Koordinaten vor der Abfrage.

Befehlsauswahl-Leitfaden

Ordnen Sie die Frage dem Befehl zu. Zähl-Befehle sind günstig und sollten ihrem Auswahl-Gegenstück vorausgehen.

• Welche Individuen tragen passende Varianten in einer Region → count-samples dann select-samples
• Welche Varianten werden in einer Region getragen, kohortenweit → count-variants dann select-variants
• Welche Varianten werden in einer Region getragen, innerhalb einer benannten Gruppe von Individuen → count-variants-in-samples dann select-variants-in-samples
• Wer ist homozygot-Referenz an einer einzelnen Position → count-samples-hom-ref dann select-samples-hom-ref
• Verwandtschaft (Grad + Koeffizient) zwischen zwei benannten Individuen → kinship
• Gesamtzahlen des Datensatzes (Probenanzahl, Geschlechterverteilung, Variantenanzahl, Assemblierung) → dataset-info

Annotationsfilter (gemeinsam für Varianten- und Probenauswahl/-zählung)

Alle Varianten- und Probenauswahl-Befehle (count-variants, select-variants, deren -in-samples-Formen, count-samples, select-samples) akzeptieren dieselben Annotationsfilter. Verschiedene Filterfelder werden mit UND kombiniert; mehrere Werte innerhalb eines Feldes werden mit ODER kombiniert. Aufzählungswerte sind Groß-/Kleinschreibung-unabhängig (z. B. missense_variant oder MISSENSE_VARIANT).

Dies sind Auswahlkriterien, die auf dem Server angewendet werden. Die Felder, die für eine ausgewählte Variante zurückgegeben werden, sind unter Variantenrückgabe-Befehle aufgeführt; ein Kriterium, das zum Filtern verwendet wird, wird nicht unbedingt auf der zurückgegebenen Variante wiederholt.

• --af-lt / --af-gt: Grenzen der Allelfrequenz des 1000-Genome-Datensatzes
• --gnomad-exomes-af-lt / --gnomad-exomes-af-gt: Grenzen der gnomAD v4.1 Exom-AF
• --gnomad-genomes-af-lt / --gnomad-genomes-af-gt: Grenzen der gnomAD v4.1 Genom-AF
• --clin-significance: ClinVar-Signifikanz-Begriffe, CSV (z. B. PATHOGENIC,LIKELY_PATHOGENIC)
• --consequence: Konsequenz-Begriffe der Sequence Ontology, CSV (z. B. MISSENSE_VARIANT,STOP_GAINED)
• --impact: VEP-Auswirkung, CSV (HIGH,MODERATE,LOW,MODIFIER)
• --variant-type, --feature-type, --bio-type: SO-Variantenklasse / VEP-Feature / VEP-Biotyp, CSV
• --alpha-missense-class: AM_LIKELY_BENIGN,AM_LIKELY_PATHOGENIC,AM_AMBIGUOUS (CSV)
• --alpha-missense-score-lt / --alpha-missense-score-gt: AlphaMissense-Score-Grenzen
• --biallelic-only / --multiallelic-only
• --exclude-males / --exclude-females
• --min-len-bp / --max-len-bp: Grenzen der Länge des Alternativ-Allels (bp)

[!NOTE] --alpha-missense-class und --alpha-missense-score-* schließen sich gegenseitig aus (das System ignoriert die Klasse, wenn eine Score-Grenze gesetzt ist). --biallelic-only und --multiallelic-only schließen sich gegenseitig aus. --exclude-males und --exclude-females schließen sich gegenseitig aus. Das Setzen einer *-gt-Grenze, die größer oder gleich ihrer entsprechenden *-lt-Grenze ist, definiert einen leeren Bereich und wird nichts zurückgeben.

[!NOTE] Allelfrequenz-Felder verwenden 0.0, um „nicht in dieser Quelle vorhanden“ zu bedeuten. Also wählt --gnomad-exomes-af-gt 0 Varianten aus, die in gnomAD-Exomen vorhanden sind; ein zurückgegebenes gnomad_exomes_af von 0.0 bedeutet, dass die Variante in gnomAD-Exomen fehlt. Gleiche Konvention für die gnomAD-Genom-AF. Umgekehrt schließen die Grenzen --gnomad-exomes-af-lt / --gnomad-genomes-af-lt nicht annotierte Varianten ein: „AF < X in gnomAD“ schließt Varianten mit gnomAD-AF = 0 ein, d.h. nicht annotierte; kombinieren Sie sie mit --gnomad-*-af-gt 0, um das Vorhandensein in gnomAD zu erzwingen.

[!NOTE] am_score von 0.0 bedeutet nicht bewertet oder nicht von AlphaMissense annotiert – es bedeutet nicht gutartig. Ein echter AlphaMissense-Score ist immer größer als 0.

Schnellstart

# Schritt 1. Lösen Sie Koordinaten gegen eine autoritative Quelle auf – siehe Koordinatenherkunft.
#    Beispiel: BRCA1: chr17:43044292-43170245
# Schritt 2. Größe des Ergebnisses ermitteln: Wie viele Individuen tragen vorhergesagte wahrscheinlich
#    pathogene Missense-Varianten in dieser Region?
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
# Schritt 3. Wenn die Anzahl überschaubar ist, listen Sie diese Individuen auf.
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
# Schritt 4: Für diese Gruppe von Individuen die tatsächlichen Varianten anzeigen, die sie tragen.
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

Befehle

Jeder Befehl schreibt vollständiges JSON in eine Datei (--output PFAD, standardmäßig eine temporäre Datei) und gibt eine prägnante stdout-Zusammenfassung aus. Alle Region-/Proben-Befehle teilen sich: die Regionseingabe (--chrom/--start/--end mit optionalem --ref/--alt, oder eine oder mehrere wiederholte --region CHR:START-END), die Zygositätsflags (--het-only/--hom-only, Standard beide), und die Annotationsfilter oben. Die vollständigen tabellen pro Flag finden Sie in references/onekgpd_commands.md.

Variantenrückgabe-Befehle

select-* gibt passende Varianten zurück; count-* gibt eine ganze Zahl zurück.

• count-variants – zählt Varianten in einer Region, kohortenweit.
• select-variants – wählt Varianten in einer Region aus, kohortenweit. Verwenden Sie --limit N (hartes Limit, Standard 200) oder --page-size N (ruft den vollständigen Satz in Seiten ab); die beiden schließen sich gegenseitig aus. Das Zusammenfassungsflag truncated wird gesetzt, wenn die Obergrenze erreicht ist.
• count-variants-in-samples – wie count-variants, eingeschränkt auf --samples NAME1,NAME2,... (erforderlich).
• select-variants-in-samples – wie select-variants, eingeschränkt auf --samples NAME1,NAME2,... (erforderlich).

Jede zurückgegebene Variante trägt diese 22 Schlüssel: 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. ClinVar-Signifikanz und VEP-Konsequenz sind nur Filterkriterien und werden nicht zurückgegeben. Vollständiges Schema: references/onekgpd_commands.md.

Probenrückgabe-Befehle

• count-samples – zählt Individuen, die eine passende Variante in einer Region tragen.
• select-samples – listet die Namen der Individuen auf, die eine passende Variante tragen. Unterstützt --skip N und --limit N. Gibt nur Namen zurück; um zu sehen, welche Varianten ein Individuum qualifiziert haben, übergeben Sie die Namen an select-variants-in-samples.

Homozygot-Referenz-Befehle

Einzelne Position über --chrom + --position (keine Region).

• count-samples-hom-ref – zählt Individuen mit einem 0/0-Aufruf an der Position. Der Zähler ist ein Sentinel: -1 = an dieser Position existiert überhaupt keine Variante; 0 = eine Variante existiert, aber kein Individuum ist homozygot für die Referenz; >0 = die Anzahl der homozygoten Referenz-Individuen. Die Zusammenfassung gibt an, welcher Fall vorliegt.
• select-samples-hom-ref – listet die Individuen mit einem 0/0-Aufruf an der Position auf.

Verwandtschafts-Befehl

• kinship --sample1 NAME --sample2 NAME – Verwandtschaft zwischen zwei benannten Individuen: der Grad (TWINS_MONOZYGOTIC / FIRST_DEGREE / SECOND_DEGREE / THIRD_DEGREE / UNRELATED) und der KING-Verwandtschafts- koeffizient (phi_bwf).

Datensatzmetadaten-Befehl

• dataset-info – Gesamtzahlen des Datensatzes: samples_total (3.202), weiblich/männlich-Aufteilung, variants_total, assembly (GRCh38) und die Kohortenaufschlüsselung. Keine Region erforderlich; dient gleichzeitig als Konnektivitätsprüfung.

Proben- & Populationsmetadaten (offline)

Population, Geschlecht, Abstammung und Superpopulationsfragen werden von einem zweiten Skript, scripts/onekgpd_meta.py, aus einer im Skill gebündelten Datendatei beantwortet – kein Netzwerk, keine Anmeldeinformationen, keine Koordinaten. Die Proben-IDs sind dieselben Namen, die auch die Varianten-Befehle verwenden, sodass sich die beiden Ebenen kombinieren lassen (z. B. eine Kohorte nach Population auswählen, dann ihre Varianten abfragen). Führen Sie uv run scripts/onekgpd_meta.py <befehl> aus.

Die Kohorte hat 5 Superpopulationen (AFR, AMR, EAS, EUR, SAS) und 26 Populationen.