← Về thư mục
📄 / / profiles / r-and-d / raw_evidence / scientific-agent-skills / skills / onekgpd / SKILL.md

name: onekgpd description: > Query the 1000 Genomes Project dataset (3,202 whole-genome-sequenced individuals, GRCh38) at the level of individual participants. Use when a question is about individuals or variants in the 1000 Genomes Project cohort: which individuals carry variants matching specific criteria in a gene or region, which individuals are homozygous-reference at a position, which variants exist in the dataset or carried by specified individuals in a gene or region, the relatedness between two specified individuals. Variants are returned with 1000 Genomes allele frequencies (AF), gnomAD v4.1 exome and genome AF, AlphaMissense score, and HGVSp annotations. license: MIT compatibility: Requires Python >=3.11. Variant and sample queries require outbound network access to the public 1000 Genomes query endpoint over TLS; the sample/population metadata commands run fully offline over a data file bundled in the skill. No credentials, API keys, or environment variables are used. allowed-tools: Write Bash metadata: version: "1.2" skill-author: Dnaerys

OneKGPd: Individual-Level Queries over the 1000 Genomes Project

Scope

This skill queries the 1000 Genomes Project dataset — the extended high-coverage cohort of 3,202 whole-genome-sequenced individuals, on the GRCh38 assembly. All results are drawn from this cohort, and sample names returned by the skill (for example HG00096 or NA21130) identify its participants.

Queries resolve against the cohort's per-individual genotype data. This supports two complementary classes of question: selecting variants carried within a region (across the whole cohort or within a specified set of individuals), and selecting the individuals who carry variants matching given criteria. Variant selection can be filtered by allele frequency, predicted consequence, clinical significance, AlphaMissense classification, and the other annotation axes listed below. Relatedness between two named individuals is also available.

The genotype state in which a variant is carried — heterozygous or homozygous — is a criterion that queries may specify; results are returned as variants or as sample names, not as raw genotypes.

When to Use

Use this skill when you need to:

Do NOT use this skill for:

Prerequisites

  1. uv: This skill's script is run with uv run, which reads the script's inline dependency metadata and provisions an ephemeral environment. Ensure uv is installed and on PATH (https://docs.astral.sh/uv/).
  2. Data use terms: The 1000 Genomes Project data is open; users should be aware of the 1000 Genomes Project / IGSR data-use terms (https://www.internationalgenome.org/data).
  3. Access constraints: There is no API key, no .env file, and no rate-limit token to configure.
  4. No credentials required

Core Rules

Coordinate Provenance (MANDATORY FIRST STEP)

Before any region-based query, resolve the gene or feature to GRCh38 coordinates against an authoritative source (for example Ensembl), and query with those resolved coordinates. The assembly must be explicit, and a gene-range must be resolved to precise positions before use. This is structural, not advisory: there is no source-side guardrail that would catch a misplaced region, so an unverified coordinate produces results for an unintended location with no error.

# Resolve gene symbol -> GRCh38 region with an authoritative source FIRST,
# then pass the verified coordinates to the OneKGPd query below.

[!CAUTION] The dataset is GRCh38. A GRCh37 coordinate, or any region that does not correctly correspond to the intended feature on GRCh38, will return results for an unintended location without raising an error. Verify the assembly and the resolved coordinates before querying.

Command Selection Guide

Match the question to the command. Counting commands are cheap and should precede their selection counterpart.

Annotation filters (shared across variant and sample selection/counting)

All variant- and sample-selection commands (count-variants, select-variants, their -in-samples forms, count-samples, select-samples) accept the same annotation filters. Different filter fields are combined with AND; multiple values within one field are combined with OR. Enum values are case-insensitive (e.g. missense_variant or MISSENSE_VARIANT).

These are selection criteria applied on the server. The fields returned on a selected variant are listed under Variant-returning commands; a criterion used for filtering is not necessarily echoed back on the returned variant.

[!NOTE] --alpha-missense-class and --alpha-missense-score-* are mutually exclusive (the engine ignores the class when a score bound is set). --biallelic-only and --multiallelic-only are mutually exclusive. --exclude-males and --exclude-females are mutually exclusive. Setting a *-gt bound greater than or equal to its matching *-lt bound defines an empty range and will return nothing.

[!NOTE] Allele-frequency fields use 0.0 to mean "not present in that source." So --gnomad-exomes-af-gt 0 selects variants that are in gnomAD exomes; a returned gnomad_exomes_af of 0.0 means the variant is absent from gnomAD exomes. The same convention for gnomAD genomes AF. Conversely, --gnomad-exomes-af-lt / --gnomad-genomes-af-lt bounds include unannotated variants: "AF < X in gnomAD" includes variants with gnomAD AF = 0, i.e. unannotated; pair it with --gnomad-*-af-gt 0 to require presence in gnomAD.

[!NOTE] am_score of 0.0 means not scored or not annotated by AlphaMissense - it does not mean benign. A real AlphaMissense score is always greater than 0.

Quick Start

# Step 1. Resolve coordinates against an authoritative source — see Coordinate Provenance.
#    example: BRCA1: chr17:43044292-43170245
# Step 2. Size the result set: how many individuals carry predicted likely-pathogenic
#    missense variants in this 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
# Step 3. If the count is manageable, list those individuals.
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
# Step 4: For that set of individuals, see the actual variants they carry.
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

Commands

Each command writes full JSON to a file (--output PATH, default a temp file) and prints a concise stdout summary. All region/sample commands share: the region input (--chrom/--start/--end with optional --ref/--alt, or one or more repeated --region CHR:START-END), the zygosity flags (--het-only/--hom-only, default both), and the annotation filters above. The full per-flag tables live in references/onekgpd_commands.md.

Variant-returning commands

select-* return matching variants; count-* return an integer count.

Each returned variant carries these 22 keys: 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 significance and VEP consequence are filter criteria only and are not returned. Full schema: references/onekgpd_commands.md.

Sample-returning commands

Homozygous-reference commands

Single position via --chrom + --position (not a region).

Relatedness command

Dataset metadata command

Sample & population metadata (offline)

Population, sex, pedigree, and superpopulation questions are answered by a second script, scripts/onekgpd_meta.py, from a data file bundled in the skill — no network, no credentials, no coordinates. The sample IDs are the same names the variant commands use, so the two layers compose (e.g. pick a cohort by population, then query its variants). Run uv run scripts/onekgpd_meta.py <command>.

The cohort has 5 superpopulations (AFR, AMR, EAS, EUR, SAS) and 26 populations. Population/superpopulation values match case-insensitively by short code or full name; sample IDs are case-sensitive.

See references/onekgpd_commands.md for full argument tables and JSON output schemas.

Typical Workflows

Which individuals, then which variants they carry

# Step 1: resolve gene -> verified GRCh38 region (authoritative source).
# Step 2: count individuals carrying a qualifying variant in the region.
uv run scripts/onekgpd_api.py count-samples \
  --chrom <chr> --start <start> --end <end> \
  --consequence MISSENSE_VARIANT --alpha-missense-class AM_LIKELY_PATHOGENIC \
  --output /tmp/n.json
# Step 3: list those individuals.
uv run scripts/onekgpd_api.py select-samples \
  --chrom <chr> --start <start> --end <end> \
  --consequence MISSENSE_VARIANT --alpha-missense-class AM_LIKELY_PATHOGENIC \
  --output /tmp/who.json
# Step 4: for that set of individuals, see the actual variants they carry.
uv run scripts/onekgpd_api.py select-variants-in-samples \
  --chrom <chr> --start <start> --end <end> \
  --samples <name1,name2,...> \
  --consequence MISSENSE_VARIANT --alpha-missense-class AM_LIKELY_PATHOGENIC \
  --output /tmp/variants.json

Homozygous-reference carriers at a position of interest

# After identifying a position of interest (verified coordinate):
uv run scripts/onekgpd_api.py count-samples-hom-ref \
  --chrom <chr> --position <pos> --output /tmp/homref_n.json
uv run scripts/onekgpd_api.py select-samples-hom-ref \
  --chrom <chr> --position <pos> --output /tmp/homref.json

Common Mistakes

References