[upstream-sync] skills/onekgpd/references/onekgpd_commands.md from K-Dense-AI/scientific-agent-skills@0807ddbc [unknown]

upstream/K-Dense-AI-scientific-agent-skills/catalogue/skills/onekgpd/SKILL.md

@@ -0,0 +1,370 @@
+---
+lineage_type: import
+upstream_source: https://github.com/K-Dense-AI/scientific-agent-skills/blob/0807ddbc/skills/onekgpd/SKILL.md
+upstream_sha: 0807ddbc
+imported_at: 2026-06-29
+prompt_class: unknown
+upstream_changes: accepted
+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.12. 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.0", "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](#sample--population-metadata-offline)).
+-   **Coordinates MUST be resolved against an authoritative source first** — see
+    [Coordinate Provenance](#coordinate-provenance-mandatory-first-step). 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.
+
+```bash
+# 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](#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.
+
+> [!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
+
+```bash
+# 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](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 1000) **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 19 keys: `chr`, `start`, `end`, `ref`,
+`alt`, `af`, `ac`, `an`, `homc`, `hetc`, `misc`, `homfc`, `hetfc`, `misfc`,
+`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](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](references/onekgpd_commands.md) for full
+argument tables and JSON output schemas.
+
+## Typical Workflows
+
+### Which individuals, then which variants they carry
+
+```bash
+# 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
+
+```bash
+# 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](references/onekgpd_commands.md) — full
+    per-command argument tables and the returned-variant output schema.
+-   [references/annotation_vocabularies.md](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/

upstream/K-Dense-AI-scientific-agent-skills/catalogue/skills/onekgpd/references/annotation_vocabularies.md

@@ -0,0 +1,200 @@
+---
+title: "OneKGPd annotation vocabularies"
+task: ""
+lineage_type: import
+upstream_source: https://github.com/K-Dense-AI/scientific-agent-skills/blob/0807ddbc/skills/onekgpd/references/annotation_vocabularies.md
+upstream_sha: 0807ddbc
+imported_at: 2026-06-29
+prompt_class: unknown
+upstream_changes: accepted
+author: upstream
+validated: false
+---
+
+# 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.

upstream/K-Dense-AI-scientific-agent-skills/catalogue/skills/onekgpd/references/onekgpd_commands.md

@@ -0,0 +1,302 @@
+---
+title: "OneKGPd command reference"
+task: ""
+lineage_type: import
+upstream_source: https://github.com/K-Dense-AI/scientific-agent-skills/blob/0807ddbc/skills/onekgpd/references/onekgpd_commands.md
+upstream_sha: 0807ddbc
+imported_at: 2026-06-29
+prompt_class: unknown
+upstream_changes: accepted
+author: upstream
+validated: false
+---
+
+# 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.
+
+---
+
+## 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 | 1000 Genomes dataset allele frequency. |
+| `ac` | float | Dataset allele count (0.5 for male non-PAR het calls on sex chromosomes). |
+| `an` | int | Dataset allele number. |
+| `homc` | int | Homozygous allele count. |
+| `hetc` | int | Heterozygous allele count. |
+| `misc` | int | Missing (no-call) allele count. |
+| `homfc` | int | Female homozygous count (sex chromosomes). |
+| `hetfc` | int | Female heterozygous count (sex chromosomes). |
+| `misfc` | int | Female missing count (sex chromosomes). |
+| `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 | Amino-acid substitution (HGVSp / VEP `Amino_acids`). |
+| `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`.