What it does. 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. Part of K-Dense-AI/scientific-agent-skills (AI Scientist skills) (K-Dense-AI/scientific-agent-skills).

Upstream	K-Dense-AI/scientific-agent-skills
Skill file	skills/onekgpd/SKILL.md
License	MIT
Author	K-Dense Inc.
Fetched	2026-09-10

Install

• npx skills add K-Dense-AI/scientific-agent-skills --skill onekgpd, or copy the skill folder into ~/.claude/skills/onekgpd/.
• Raw file: curl -sL https://raw.githubusercontent.com/K-Dense-AI/scientific-agent-skills/HEAD/skills/onekgpd/SKILL.md

SKILL.md (verbatim)

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:

• Find variants carried in a region or set of regions matching some criteria across the whole cohort (select-variants).
• Find variants carried in a region or set of regions matching some criteria in specific set of individuals (select-variants-in-samples).
• Find which 1000 Genomes individuals carry variants matching some criteria in a region or set of regions (select-samples).
• Count how many individuals carry specific variants (count-samples).
• Restrict any variant query to heterozygous-only or homozygous-only carriage, or query both together (default).
• Identify which individuals are homozygous reference at a single position (select-samples-hom-ref).
• Determine the relatedness between two named 1000 Genomes individuals — both the degree (twin / 1st / 2nd / 3rd / unrelated) and the KING kinship coefficient (kinship).
• Get dataset totals — sample count, sex split, variant count, assembly (dataset-info).
• Variant selection can be specified by KGP allele frequency, gnomAD 4.1 exome and gnomAD 4.1 genome allele frequency, AlphaMissense Score and AlphaMissense Class, ClinVar significance (202502), and VEP annotations (impact, biotype, feature type, variant class, consequences).

Do NOT use this skill for:

• Resolving a gene symbol, rsID, or transcript to coordinates, or fetching reference sequence. Resolve coordinates first (see Coordinate Provenance below), then query this skill with the resolved GRCh38 region.
• Any cohort other than the 1000 Genomes Project — this skill serves only that dataset.

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

• Use the Wrappers: ALWAYS execute the provided helper scripts rather than constructing your own client calls or network requests. Use scripts/onekgpd_api.py for variant/sample/kinship queries (it handles the connection, streaming, pagination, and JSON serialization), and scripts/onekgpd_meta.py for sample/population metadata (offline, see Sample & population metadata).
• Coordinates MUST be resolved against an authoritative source first — see Coordinate Provenance. This is mandatory, not advisory.
• Count before you select: every variant and sample selection has a paired counting command. Call the count command FIRST to size the result set, then select only if the count is manageable.
• Zygosity defaults to both: selection and counting commands include both heterozygous and homozygous carriage by default. Narrow with --het-only or --hom-only when the question is specifically about one state. (You do not need to pass anything to get both.)
• Output: scripts write full JSON to a file (--output, default under /tmp/) and print a concise summary to stdout. Do not read large JSON files into context — use jq or a small disposable uv run python snippet to extract fields.

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.

• Which individuals carry matching variants in a region → count-samples then select-samples
• Which variants are carried in a region, cohort-wide → count-variants then select-variants
• Which variants are carried in a region, within a named set of individuals → count-variants-in-samples then select-variants-in-samples
• Who is homozygous-reference at a single position → count-samples-hom-ref then select-samples-hom-ref
• Relatedness (degree + coefficient) between two named individuals → kinship
• Dataset totals (sample count, sex split, variant total, assembly) → dataset-info

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.

• --af-lt / --af-gt: 1000 Genomes dataset allele frequency bounds
• --gnomad-exomes-af-lt / --gnomad-exomes-af-gt: gnomAD v4.1 exome AF bounds
• --gnomad-genomes-af-lt / --gnomad-genomes-af-gt: gnomAD v4.1 genome AF bounds
• --clin-significance: ClinVar significance terms, CSV (e.g. PATHOGENIC,LIKELY_PATHOGENIC)
• --consequence: Sequence Ontology consequence terms, CSV (e.g. MISSENSE_VARIANT,STOP_GAINED)
• --impact: VEP impact, CSV (HIGH,MODERATE,LOW,MODIFIER)
• --variant-type, --feature-type, --bio-type: SO variant class / VEP feature / VEP biotype, CSV
• --alpha-missense-class: AM_LIKELY_BENIGN,AM_LIKELY_PATHOGENIC,AM_AMBIGUOUS (CSV)
• --alpha-missense-score-lt / --alpha-missense-score-gt: AlphaMissense score bounds
• --biallelic-only / --multiallelic-only
• --exclude-males / --exclude-females
• --min-len-bp / --max-len-bp: alternate-allele length bounds (bp)

[!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.

• count-variants — count variants in a region, cohort-wide.
• select-variants — select variants in a region, cohort-wide. Use --limit N (hard cap, default 200) or --page-size N (retrieve the full set in pages); the two are mutually exclusive. The summary flags truncated when the cap is reached.
• count-variants-in-samples — as count-variants, restricted to --samples NAME1,NAME2,... (required).
• select-variants-in-samples — as select-variants, restricted to --samples NAME1,NAME2,... (required).

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

• count-samples — count individuals carrying a matching variant in a region.
• select-samples — list the names of individuals carrying a matching variant. Supports --skip N and --limit N. Returns names only; to see which variants qualified an individual, feed the names into select-variants-in-samples.

Homozygous-reference commands

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

• count-samples-hom-ref — count individuals with a 0/0 call at the position. The count is a sentinel: -1 = no variant exists at that position at all; 0 = a variant exists but no individual is homozygous reference; >0 = the number of homozygous-reference individuals. The summary states which case.
• select-samples-hom-ref — list the individuals with a 0/0 call at the position.

Relatedness command

• kinship --sample1 NAME --sample2 NAME — relatedness between two named individuals: the degree (TWINS_MONOZYGOTIC / FIRST_DEGREE / SECOND_DEGREE / THIRD_DEGREE / UNRELATED) and the KING kinship coefficient (phi_bwf).

Dataset metadata command

• dataset-info — dataset totals: samples_total (3,202), female/male split, variants_total, assembly (GRCh38), and the cohort breakdown. No region required; doubles as a connectivity check.

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.

• sample-metadata --samples NA19240,HG00096 — family, gender, parents, children, population, superpopulation, and phase3 status for the given samples.
• list-populations — all 26 populations with superpopulation and sample count (use to discover valid values).
• list-superpopulations — the 5 superpopulations with sample count and constituent populations.
• population-stats --populations YRI [--populations CHS …] — per-population sex split, phase3 count, and trio membership. Repeat --populations for multiple values (full names contain commas, so they are not comma-separated).
• superpopulation-summary --superpopulations EAS [--superpopulations EUR …] — per-superpopulation totals with a per-population breakdown.
• select-samples-by-population --population YRI and/or --superpopulation AFR, with optional --skip/--limit (default 0 / 50, max 3202) — the sample IDs in a population and/or superpopulation; both given intersects. Feed the names into select-variants-in-samples to see their variants.

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

• Mistake: Querying with an unverified coordinate. Fix: Always resolve gene/feature → GRCh38 against an authoritative source first. A misplaced region returns results for an unintended location without error.
• Mistake: Calling a selection command before its counting command. Fix: Count first; selection result sets can be large.
• Mistake: Assuming a GRCh37 coordinate will work. Fix: The dataset is GRCh38 only.

References

• references/onekgpd_commands.md — full per-command argument tables and the returned-variant output schema.
• references/annotation_vocabularies.md — the controlled-vocabulary terms accepted by the CSV filter flags (consequence, impact, biotype, feature type, ClinVar significance, AlphaMissense class, variant class).
• 1000 Genomes Project / IGSR: https://www.internationalgenome.org/
• 1000 Genomes Project dataset online: https://dnaerys.org/online/

Other files in this skill

• assets/kgpe.json
• references/annotation_vocabularies.md
• references/onekgpd_commands.md
• scripts/onekgpd_api.py
• scripts/onekgpd_meta.py

references/annotation_vocabularies.md (verbatim)

OneKGPd annotation vocabularies

Controlled-vocabulary terms accepted by the CSV annotation-filter flags of onekgpd_api.py. Values are case-insensitive and resolved by exact member name; pass them as comma-separated lists (e.g. --consequence MISSENSE_VARIANT,STOP_GAINED). Multiple values within one flag are combined with OR; different flags combine with AND.

These lists are the complete set of valid tokens for each flag. A value not in the relevant list is rejected with an error listing the valid values.

Consequence (SO consequence terms) — --consequence

41 terms:

• TRANSCRIPT_ABLATION
• SPLICE_ACCEPTOR_VARIANT
• SPLICE_DONOR_VARIANT
• STOP_GAINED
• FRAMESHIFT_VARIANT
• STOP_LOST
• START_LOST
• TRANSCRIPT_AMPLIFICATION
• INFRAME_INSERTION
• INFRAME_DELETION
• MISSENSE_VARIANT
• PROTEIN_ALTERING_VARIANT
• SPLICE_REGION_VARIANT
• INCOMPLETE_TERMINAL_CODON_VARIANT
• START_RETAINED_VARIANT
• STOP_RETAINED_VARIANT
• SYNONYMOUS_VARIANT
• CODING_SEQUENCE_VARIANT
• MATURE_MIRNA_VARIANT
• FIVE_PRIME_UTR_VARIANT
• THREE_PRIME_UTR_VARIANT
• NON_CODING_TRANSCRIPT_EXON_VARIANT
• INTRON_VARIANT
• NMD_TRANSCRIPT_VARIANT
• NON_CODING_TRANSCRIPT_VARIANT
• UPSTREAM_GENE_VARIANT
• DOWNSTREAM_GENE_VARIANT
• TFBS_ABLATION
• TFBS_AMPLIFICATION
• TF_BINDING_SITE_VARIANT
• REGULATORY_REGION_ABLATION
• REGULATORY_REGION_AMPLIFICATION
• FEATURE_ELONGATION
• REGULATORY_REGION_VARIANT
• FEATURE_TRUNCATION
• INTERGENIC_VARIANT
• SPLICE_POLYPYRIMIDINE_TRACT_VARIANT
• SPLICE_DONOR_5TH_BASE_VARIANT
• SPLICE_DONOR_REGION_VARIANT
• CODING_TRANSCRIPT_VARIANT
• SEQUENCE_VARIANT

Impact (VEP impact) — --impact

4 terms:

• HIGH
• MODERATE
• LOW
• MODIFIER

VariantType (SO variant class) — --variant-type

34 terms:

• SNV
• INSERTION
• DELETION
• INDEL
• SUBSTITUTION
• INVERSION
• TRANSLOCATION
• DUPLICATION
• ALU_INSERTION
• COMPLEX_STRUCTURAL_ALTERATION
• COMPLEX_SUBSTITUTION
• COPY_NUMBER_GAIN
• COPY_NUMBER_LOSS
• COPY_NUMBER_VARIATION
• INTERCHROMOSOMAL_BREAKPOINT
• INTERCHROMOSOMAL_TRANSLOCATION
• INTRACHROMOSOMAL_BREAKPOINT
• INTRACHROMOSOMAL_TRANSLOCATION
• LOSS_OF_HETEROZYGOSITY
• MOBILE_ELEMENT_DELETION
• MOBILE_ELEMENT_INSERTION
• NOVEL_SEQUENCE_INSERTION
• SHORT_TANDEM_REPEAT_VARIATION
• TANDEM_DUPLICATION
• PROBE
• ALU_DELETION
• HERV_DELETION
• HERV_INSERTION
• LINE1_DELETION
• LINE1_INSERTION
• SVA_DELETION
• SVA_INSERTION
• COMPLEX_CHROMOSOMAL_REARRANGEMENT
• SEQUENCE_ALTERATION

FeatureType (VEP feature type) — --feature-type

3 terms:

• TRANSCRIPT
• REGULATORYFEATURE
• MOTIFFEATURE

BioType (VEP biotype) — --bio-type

47 terms:

• PROCESSED_TRANSCRIPT
• LNCRNA
• ANTISENSE
• MACRO_LNCRNA
• NON_CODING
• RETAINED_INTRON
• SENSE_INTRONIC
• SENSE_OVERLAPPING
• LINCRNA
• NCRNA
• MIRNA
• MISCRNA
• PIRNA
• RRNA
• SIRNA
• SNRNA
• SNORNA
• TRNA
• VAULTRNA
• PROTEIN_CODING
• PSEUDOGENE
• IG_PSEUDOGENE
• POLYMORPHIC_PSEUDOGENE
• PROCESSED_PSEUDOGENE
• TRANSCRIBED_PSEUDOGENE
• TRANSLATED_PSEUDOGENE
• UNITARY_PSEUDOGENE
• UNPROCESSED_PSEUDOGENE
• READTHROUGH
• STOP_CODON_READTHROUGH
• TEC
• TR_GENE
• TR_C_GENE
• TR_D_GENE
• TR_J_GENE
• TR_V_GENE
• IG_GENE
• IG_C_GENE
• IG_D_GENE
• IG_J_GENE
• IG_V_GENE
• NONSENSE_MEDIATED_DECAY
• PROMOTER
• PROMOTER_FLANKING_REGION
• ENHANCER
• CTCF_BINDING_SITE
• OPEN_CHROMATIN_REGION

ClinSignificance (ClinVar significance) — --clin-significance

19 terms:

• CLNSIG_BENIGN
• LIKELY_BENIGN
• UNCERTAIN_SIGNIFICANCE
• LIKELY_PATHOGENIC
• PATHOGENIC
• DRUG_RESPONSE
• ASSOCIATION
• RISK_FACTOR
• PROTECTIVE
• AFFECTS
• CONFERS_SENSITIVITY
• CONFLICTING_INTERPRETATIONS
• NOT_PROVIDED
• OTHER
• LIKELY_PATHOGENIC_LOW_PENETRANCE
• PATHOGENIC_LOW_PENETRANCE
• UNCERTAIN_RISK_ALLELE
• LIKELY_RISK_ALLELE
• ESTABLISHED_RISK_ALLELE

AlphaMissense (class) — --alpha-missense-class

3 terms:

• AM_LIKELY_BENIGN
• AM_LIKELY_PATHOGENIC
• AM_AMBIGUOUS

Notes

• ClinVar "benign" is the token CLNSIG_BENIGN (note the CLNSIG_ prefix); all other ClinSignificance tokens are the bare term.
• AlphaMissense class is mutually exclusive with the AlphaMissense score bounds (--alpha-missense-score-lt/-gt): set one or the other, not both.

references/onekgpd_commands.md (verbatim)

OneKGPd command reference

Full argument tables for every onekgpd_api.py subcommand and the schema of a returned variant. Run with uv run scripts/onekgpd_api.py <command> [flags].

Coordinates are GRCh38, 1-based inclusive. Resolve a gene/feature to coordinates against an authoritative source before querying. Every command writes full JSON to a file (--output PATH, default a temp file) and prints a short summary to stdout.

Shared flags

Connection / output (all commands)

flag	type	required	default	description
--output	path	no	temp file	Write full JSON here; otherwise a onekgpd_<cmd>_*.json temp file is created and its path printed.

There is no endpoint, credential, assembly, or timeout flag: the skill targets the public 1000 Genomes instance on GRCh38 only.

Region input (count/select variants and samples)

Provide either a single region or one-or-more --region, not both.

flag	type	required	default	description
--chrom	str	single-region mode	–	Chromosome: chr17, 17, X, MT (case-insensitive).
--start	int	with --chrom	–	1-based inclusive start.
--end	int	with --chrom	–	1-based inclusive end (≥ start).
--ref	str	no	–	Narrow to one reference allele (single-region only).
--alt	str	no	–	Narrow to one alternate allele (single-region only).
--region	CHR:START-END	multi-region mode	–	A region; repeat the flag for multiple regions.
--min-len-bp	int	no	–	Minimum alternate-allele length (bp).
--max-len-bp	int	no	–	Maximum alternate-allele length (bp).

Zygosity (count/select variants and samples)

flag	type	required	default	description
--het-only	switch	no	both	Include HETEROZYGOUS variants ONLY (0/1 genotypes).
--hom-only	switch	no	both	Include HOMOZYGOUS variants ONLY (1/1 genotypes).

With no zygosity flag, both HETEROZYGOUS (0/1) and HOMOZYGOUS (1/1) carriage are queried — use the default when you need homozygous OR heterozygous variants, or when uncertain. --het-only and --hom-only are mutually exclusive.

Annotation filters (count/select variants and samples)

See annotation_vocabularies.md for the valid CSV terms. Different filter fields combine with AND; multiple CSV values within one field combine with OR.

flag	type	maps to
--af-lt / --af-gt	float	1000 Genomes dataset AF bounds
--gnomad-exomes-af-lt / --gnomad-exomes-af-gt	float	gnomAD v4.1 exomes AF bounds
--gnomad-genomes-af-lt / --gnomad-genomes-af-gt	float	gnomAD v4.1 genomes AF bounds
--clin-significance	CSV	ClinVar significance terms
--consequence	CSV	SO consequence terms
--impact	CSV	VEP impact (HIGH,MODERATE,LOW,MODIFIER)
--variant-type	CSV	SO variant class terms
--feature-type	CSV	VEP feature types
--bio-type	CSV	VEP biotypes
--alpha-missense-class	CSV	AM_LIKELY_BENIGN,AM_LIKELY_PATHOGENIC,AM_AMBIGUOUS
--alpha-missense-score-lt / --alpha-missense-score-gt	float	AlphaMissense score bounds
--biallelic-only / --multiallelic-only	switch	site multiplicity (mutually exclusive)
--exclude-males / --exclude-females	switch	sex exclusion (mutually exclusive)

Mutual exclusions enforced: --biallelic-only/--multiallelic-only, --exclude-males/--exclude-females, and --alpha-missense-class vs the AlphaMissense score bounds. Setting a *-gt ≥ its matching *-lt defines an empty range and returns nothing.

The --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.

---

Commands

dataset-info

No flags beyond --output. Returns dataset totals (sample count, sex split, variant total, assembly) and the cohort breakdown. Doubles as a connectivity check.

JSON: {command, samples_total, females_total, males_total, variants_total, assembly, cohorts:[{cohort_name, samples_count, female_count, male_count, synthetic}]}.

count-variants

Region + zygosity + annotation flags. Counts variants in the region(s), cohort-wide. JSON: {command, count, request, result_incomplete}.

select-variants

SELECT variants which exist in ANY genomic region provided.

Region + zygosity + annotation flags, plus pagination:

flag	type	required	default	description
--limit	int	no	200	Hard cap on returned variants (mutually exclusive with --page-size).
--page-size	int	no	–	Retrieve ALL matching variants in pages of this size (full walk).

JSON: {command, count_returned, truncated, request, result_incomplete, variants:[…]}. truncated is true when the count hit --limit (more may exist; raise --limit or use --page-size). Empty variants array if no matches.

count-variants-in-samples

As count-variants, plus --samples CSV (required) — counts variants carried by the named individuals.

select-variants-in-samples

As select-variants, plus --samples CSV (required) — selects variants carried by the named individuals.

count-samples

Region + zygosity + annotation flags. Counts how many individuals carry a matching variant. JSON: {command, count, request, result_incomplete}.

select-samples

Region + zygosity + annotation flags, plus pagination:

flag	type	required	default	description
--skip	int	no	–	Skip the first N individuals.
--limit	int	no	–	Return at most N individuals.

Returns the names of individuals carrying a matching variant. To see which variants qualified them, feed the names into select-variants-in-samples. JSON: {command, count, samples:[…], request, result_incomplete}. Empty samples array if no matches.

count-samples-hom-ref

flag	type	required	description
--chrom	str	yes	Chromosome.
--position	int	yes	1-based position.

Counts individuals with a homozygous-reference (0/0) call at the position. JSON: {command, count, variant_present, request}. The count is a sentinel:

• -1 → no variant exists at the position at all (variant_present=false).
• 0 → a variant exists, but no individual is homozygous reference.
• >0 → number of homozygous-reference individuals.

select-samples-hom-ref

Same --chrom/--position as above. Lists the individuals with a homozygous- reference call at the position. JSON: {command, count, samples:[…], request}.

kinship

flag	type	required	description
--sample1	str	yes	First sample name.
--sample2	str	yes	Second sample name.

Returns the relatedness degree and the KING kinship coefficient between the two named individuals. JSON: {command, sample1, sample2, degree, phi_bwf, result_incomplete}. degree ∈ {TWINS_MONOZYGOTIC, FIRST_DEGREE, SECOND_DEGREE, THIRD_DEGREE, UNRELATED}; phi_bwf is the KING between-family robust coefficient (≈ 0.5 monozygotic, 0.25 first-degree, 0.125 second-degree, 0.0625 third-degree).

---

Returned-variant output schema

select-variants and select-variants-in-samples return a variants array; each element has these keys (filter-only criteria such as ClinVar significance and VEP consequence are not echoed back on a returned variant):

key	type	meaning
chr	str	Chromosome, e.g. chr17.
start	int	1-based inclusive start.
end	int	1-based inclusive end.
ref	str	Reference allele.
alt	str	Alternate allele.
af	float	Dataset allele frequency.
ac	float	Dataset allele count (0.5 for male non-PAR het calls on on X and Y chromosomes).
an	int	Dataset allele number.
hom_samples	int	Number of all samples with a homozygous genotype.
het_samples	int	Number of all samples with a heterozygous genotype.
mis_samples	int	Number of all samples with a missing (no-call) genotype.
hom_samples_fx	int	Number of female samples with a homozygous genotype, X chromosome only (0 outside X).
het_samples_fx	int	Number of female samples with a heterozygous genotype, X chromosome only (0 outside X).
mis_samples_fx	int	Number of female samples with a missing (no-call) genotype, X chromosome only (0 outside X).
hom_samples_mxy	int	Number of male samples with a homozygous genotype, X & Y chromosomes only (0 outside X and Y).
het_samples_mxy	int	Number of male samples with a heterozygous genotype, X & Y chromosomes only (0 outside X and Y).
mis_samples_mxy	int	Number of male samples with a missing (no-call) genotype, X & Y chromosomes only (0 outside X and Y).
gnomad_exomes_af	float	gnomAD v4.1 exomes AF. 0.0 = absent from gnomAD exomes.
gnomad_genomes_af	float	gnomAD v4.1 genomes AF. 0.0 = absent from gnomAD genomes.
am_score	float	AlphaMissense score. 0.0 = not annotated.
amino_acids	str	HGVSp Amino-acid substitution.
biallelic	bool	Whether the site was biallelic in the input VCFs.

---

Sample & population metadata commands (offline)

A second script, scripts/onekgpd_meta.py, answers population/pedigree questions from a data file bundled in the skill (assets/kgpe.json) — no network, no credentials, no dependencies. Run with uv run scripts/onekgpd_meta.py <command> [flags]. The sample identifier is the same name used by the variant/kinship commands (e.g. NA19240), so the two layers compose (e.g. select-samples-by-population → select-variants-in-samples).

The 1000 Genomes cohort has 5 superpopulations (AFR Africa, AMR America, EAS East Asia, EUR Europe, SAS South Asia) and 26 populations. Use list-populations / list-superpopulations to discover valid codes and full names. Population/superpopulation values are matched case-insensitively against either the short code or the full name; sample IDs are case-sensitive.

All six commands write JSON to --output (or a temp file) and print a summary.

sample-metadata

flag	type	required	description
--samples	CSV	yes	Comma-separated sample IDs (case-sensitive), e.g. NA19240,HG00096.

JSON: {command, samples:[{...}]} ordered by sample_id. Each sample object:

key	type	meaning
sample_id	str	Sample identifier (externalIDs).
family_id	str|null	Family/pedigree ID; null if absent.
gender	str	male / female.
paternal_id	str|null	Father's sample_id; null if not in the dataset.
maternal_id	str|null	Mother's sample_id; null if not in the dataset.
relationship	str|null	mother / father / child / null.
children	list[str]	Sorted children whose both parents are recorded; [] if none.
population_code	str	e.g. YRI.
population	str	e.g. Yoruba in Ibadan, Nigeria.
superpopulation_code	str	e.g. AFR.
superpopulation	str	e.g. Africa.
phase3	str	"TRUE" / "FALSE" (phase-3 inclusion flag).

list-populations

No flags. JSON: {command, populations:[{population_code, population, superpopulation_code, superpopulation, sample_count}]}, ordered by (superpopulation, population). 26 entries.

list-superpopulations

No flags. JSON: {command, superpopulations:[{superpopulation_code, superpopulation, sample_count, populations:[codes]}]}, ordered by superpopulation. 5 entries.

population-stats

flag	type	required	description
--populations	repeatable	yes	One population code or full name per flag; repeat for multiple. Repeated (not CSV) because full names contain commas. Case-insensitive.

JSON: {command, populations:[{population_code, population, superpopulation_code, superpopulation, sample_count, male_count, female_count, phase3_count, trio_count}]}, ordered by population. trio_count = samples that are offspring with both parents in the dataset (not the relationship label).

superpopulation-summary

flag	type	required	description
--superpopulations	repeatable	yes	One superpopulation code or full name per flag; repeat for multiple. Case-insensitive.

JSON: {command, superpopulations:[{superpopulation_code, superpopulation, sample_count, male_count, female_count, phase3_count, trio_count, populations:[ <population-stats object>]}]}. The per-superpopulation counts are sums over the nested per-population breakdown.

select-samples-by-population

flag	type	required	default	description
--population	str	one of the two	–	Population code or full name (case-insensitive).
--superpopulation	str	one of the two	–	Superpopulation code or full name (case-insensitive).
--skip	int	no	0	Number of results to skip (≥ 0).
--limit	int	no	50	Max results to return (1–3202).

At least one of --population / --superpopulation is required; when both are given the results are intersected (AND). JSON: {command, count, samples:[ids], request:{population, superpopulation, skip, limit}}, sample IDs ordered ascending then paginated by skip/limit.

Back to K-Dense-AI/scientific-agent-skills (AI Scientist skills) or Agent skills.