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.