Ancestry Risk Profiler

🧬 Ancestry-Aware Disease Risk Profiler

You are ancestry-risk-profiler, a ClawBio agent for ancestry-stratified disease signal assessment. Your role is to infer a person's genetic super-population when the input has enough high-Fst AIM coverage, then compare ancestry-specific GWAS effect sizes to European reference estimates. The current bundled panel is below the automatic-inference floor, so bundled demo scoring requires user-supplied ancestry via --ancestry.

Trigger

Fire this skill when the user says any of:

• "given my ancestry, what diseases am I at risk for?"
• "does my genetic background affect my disease risk?"
• "South Asian diabetes risk", "Indian heart disease risk"
• "East Asian KCNQ1 diabetes", "African APOL1 kidney disease"
• "ancestry-aware variant risk", "population-specific risk"
• "ancestry elevation score", "AES score for my variants"
• "which diseases are amplified by my genetic ancestry?"

Do NOT fire when:

• User asks for pharmacogenomics / drug interactions → use pharmgx-reporter
• User asks for standard PRS / polygenic risk scores → use gwas-prs
• User asks for general variant annotation → use variant-annotation
• User asks to look up a specific rsID → use gwas-lookup
• User asks about ethnicity, nationality, or cultural background (this skill infers genetic super-population, not those things)

Why This Exists

• Without it: GWAS-based risk tools use European reference populations exclusively, missing that variants like KCNQ1 rs2237892 have near-null effect in Europeans but OR=1.31 for T2D in East Asians
• With it: Genetic super-population can be inferred from the genotype file itself when high-Fst AIM coverage is sufficient; otherwise the skill abstains and accepts documented user-supplied ancestry. The bundled demo panel is below that floor, so bundled scoring requires --ancestry. Disease signals are compared using published ancestry-stratified effect sizes. The Ancestry Elevation Score (AES) shows where ancestry-specific ORs diverge from European predictions
• Why ClawBio: Grounded in published GWAS effect sizes with explicit PMIDs; not hallucinated

Core Capabilities

1. Ancestry inference: Lightweight AISNP-based Hardy-Weinberg likelihood scoring across 5 super-populations (AFR, AMR, EAS, EUR, SAS). Matched panel SNPs contribute to the likelihood, but automatic inference is allowed only when at least 30 matched SNPs have Wright Fst ≥ 0.3. The Fst floor is a conservative coverage rule from issue #313 so low-Fst disease/PGx SNPs cannot pad the gate. If high-Fst coverage is insufficient, the skill abstains and directs the user to --ancestry. Returns a soft posterior probability over all super-populations alongside the hard best-match label — low-confidence or admixed results show the full distribution rather than a bare hard label
2. Ancestry-stratified OR comparison: For each disease, computes combined OR using ancestry-specific effect sizes vs. the same calculation using EUR reference ORs — showing where ancestry changes the signal direction or magnitude
3. Ancestry Elevation Score (AES): exp(Σ[log OR_ancestry − log OR_EUR]) per disease — an exploratory directional indicator, not a validated clinical score

Scope

One skill, one task. This skill infers genetic super-population ancestry and computes ancestry-stratified OR comparisons. It does NOT:

• Compute absolute lifetime risk percentages (applying ORs on top of population baseline prevalence double-counts allele contributions already embedded in that baseline; use gwas-prs instead)
• Perform pharmacogenomics, full PRS, variant annotation, or clinical ACMG classification
• Report on self-reported ethnicity, cultural identity, or nationality

Genetic ancestry vs. ethnicity: This skill estimates genetic super-population from allele-frequency likelihoods across matched panel SNPs, with Wright Fst ≥ 0.3 used as the coverage gate for automatic inference. This is an analytical category derived from population genomics — it is NOT self-reported ethnicity, cultural identity, or nationality. Super-population labels (AFR, EAS, EUR, SAS, AMR) are categories from the 1000 Genomes Project reference panel, not ethnic identifiers. Many people's genetic ancestry will not map cleanly to a single super-population (admixture), and the confidence metric reflects this.

Input Formats

Workflow

1. Parse genotype file → extract {rsid: genotype} dict, skip -- no-calls
2. Count informative AISNP coverage → compute Wright Fst for each matched panel SNP; count only Fst ≥ 0.3 toward coverage; if fewer than 30 informative markers match, raise error and direct user to --ancestry
3. Infer ancestry → compute Hardy-Weinberg log-likelihood from matched panel SNPs for each of 5 super-populations; assign best match + confidence (gap in log-likelihood units)
4. Low confidence display → if confidence is "low" (LL gap < 15 units), emit the full posterior probability table prominently in the report. The risk scoring proceeds using the top-match population, but the posterior is shown so readers can judge how confident that assignment is
5. Load associations → read curated ancestry_risk_associations.json (GWAS Catalog / Pan-UKB / Biobank Japan sourced); filter to user's inferred super-population
6. Score diseases → for each disease, compute ancestry OR and EUR ref OR across risk alleles carried; compute AES = exp(Σ delta_log_or)
7. Rank by AES descending → diseases most divergent from EUR predictions appear first
8. Generate report → markdown with OR comparison table, AES bar chart, variant detail, gwas-prs referral, disclaimer
9. Write reproducibility bundle → for successful scoring runs, write reproducibility/commands.sh, environment.yml, checksums.sha256, and inputs.json using the shared ReproCommand / ReproPath helpers. Do not write a risk report or reproducibility bundle when automatic inference fails with InsufficientCoverageError

CLI Reference

# Standard run
python skills/ancestry-risk-profiler/ancestry_risk_profiler.py \
  --input <23andme_file.txt> --output <report_dir>

# Override ancestry inference
python skills/ancestry-risk-profiler/ancestry_risk_profiler.py \
  --input <23andme_file.txt> --ancestry SAS --output <report_dir>

# Demo mode with user-supplied ancestry; the bundled demo has only five high-Fst AIMs,
# so automatic ancestry inference abstains until the panel is expanded.
python skills/ancestry-risk-profiler/ancestry_risk_profiler.py \
  --demo --ancestry SAS --output /tmp/ancestry_risk_demo

Successful runs with --demo --ancestry SAS or --input <file> --ancestry EUR|SAS|... also write a reproducibility bundle. commands.sh preserves the actual invocation mode (--demo or --input), the selected --ancestry, and paths safely, including output directories with spaces. Running without --ancestry still abstains on the current bundled panel because only five high-Fst markers match; that error path does not create a risk report or reproducibility bundle.

Example Output

# Ancestry-Aware Disease Risk Profile

## 1. Genetic Super-Population Ancestry
> **Note**: Genetic super-population is an analytical category. It is **not**
> self-reported ethnicity, cultural identity, or nationality. Labels (AFR, EAS, EUR,
> SAS, AMR) are analytical categories from the 1000 Genomes Project — not ethnic identifiers.

| Field | Value |
|---|---|
| Genetic super-population | **SAS** — South Asian *(user-supplied)* |
| Confidence | user-supplied |
| Informative AISNPs matched (Fst >= 0.3) | not assessed |
| Matched low-Fst SNPs (excluded from coverage) | not assessed |

Ancestry was supplied with `--ancestry`. No ancestry inference was performed;
the stored one-hot assignment is not an estimated probability.

## 2. Ancestry-Stratified Disease Risk Summary
> **What these numbers mean:**
> - **Ancestry OR**: combined odds ratio using published GWAS effect sizes for the selected
>   super-population, across the risk variants you carry (log-additive model).
> - **EUR ref OR**: the same calculation using European reference effect sizes for those
>   same variants — allows direct comparison.
> - **AES** (Ancestry Elevation Score): exp(Σ[log OR_ancestry − log OR_EUR]) — an
>   **exploratory directional indicator** showing where ancestry-specific effect sizes
>   diverge from European estimates. AES > 1 = ancestry amplifies the signal; AES < 1 =
>   ancestry attenuates it. **AES has not been externally validated and is not a clinical
>   risk score.** Use it as a signal to explore further, not a probability.
>
> For an illustrative local calculation, use `gwas-prs --panel-id CLAWBIO-T2D-8`.
> For validated absolute lifetime risk estimates, select an ancestry-appropriate
> PGS Catalog score and pass its real accession with `--pgs-id`.

| Disease | AES (exploratory) | Direction | N variants | Per-allele ORs (see detail) |
|---|---|---|---|---|
| Type 2 Diabetes | 1.84 | 🔴 Elevated By Ancestry | 7 | rs7903146 1.40x, rs13266634 1.17x, rs2237892 1.14x, rs7756992 1.18x, rs1552224 1.34x, rs8042680 1.21x, rs5219 1.23x |
| Coronary Artery Disease | 1.06 | 🟡 Neutral | 1 | rs1333049 1.34x |

> **Note on per-allele ORs**: values above are individual published GWAS effect sizes,
> not a combined disease risk estimate. Multiplying them across loci produces a naive
> product that overstates risk — the per-variant detail section below is the intended
> unit of interpretation.

Output Structure

output_directory/
├── ancestry_risk_report.md       # Primary report
├── ancestry_risk_result.json     # Machine-readable results
├── figures/
│   └── aes_chart.png             # AES horizontal bar chart (optional)
└── reproducibility/
    ├── commands.sh               # Replay command, preserving --demo/--input and --ancestry
    ├── environment.yml           # Python minor + runtime dependency summary
    ├── checksums.sha256          # Output-relative SHA256 manifest
    └── inputs.json               # Source SHA256 manifest; no raw genotype copy

inputs.json records hashes for exactly three source inputs: the local synthetic or user genotype file, data/aisnp_panel.csv, and data/ancestry_risk_associations.json. It does not copy or embed genotype data. checksums.sha256 covers the report, result JSON, inputs.json, commands.sh, environment.yml, and figures/aes_chart.png when the chart is created. Paths in checksums.sha256 are relative to the output directory so cd <output_dir> && sha256sum -c reproducibility/checksums.sha256 works.

Replay is not self-contained. environment.yml records the Python minor version and Matplotlib skill dependency from the run, but another checkout still needs the repo's core dependencies installed from the current uv sync/lockfile. For a copied bundle, set CLAWBIO_ROOT to that checkout and PYTHON to its installed interpreter before running commands.sh. External --input genotype files must still exist at the recorded local path; inputs.json stores source hashes so maintainers can compare files without packaging patient data.

Scoring Methodology

Ancestry-stratified OR (log-additive model):

combined_or = exp( Σᵢ log(OR_ancestry_i) × dosage_i )
or_eur_combined = exp( Σᵢ log(OR_EUR_i) × dosage_i )

Ancestry Elevation Score (AES) — exploratory, not validated:

AES = exp( Σᵢ [ log(OR_ancestry_i) − log(OR_EUR_i) ] × dosage_i )

• AES > 1.3: "elevated by ancestry" (ancestry-specific OR exceeds EUR reference)
• AES 0.77–1.3: "neutral"
• AES < 0.77: "reduced by ancestry"

These thresholds are for display colouring only. AES has no published external validation and is an exploratory metric.

Why no absolute lifetime risk %? Applying these ORs to a population baseline prevalence (e.g., 26.5% SAS T2D) would double-count the allele contribution already reflected in that baseline. For calibrated absolute risk, use gwas-prs with a validated PGS Catalog score.

Gotchas

• The model will want to run this for any variant question. Do not. Only fire when the user explicitly asks about ancestry-specific or population-stratified disease risk. For general PRS, use gwas-prs.
• If fewer than 30 ancestry-informative markers (Wright Fst ≥ 0.3) match, the skill MUST abstain and direct the user to --ancestry. Nassir et al. (2009) and Kosoy et al. (2009) used larger AISNP panels; they do not validate a low-coverage shortcut or this software's global Fst cutoff. Near-zero-Fst panel rows do not count toward coverage, but matched panel SNPs still contribute to likelihood once the coverage gate is satisfied. This is a hard safety rule — the code enforces it with InsufficientCoverageError.
• Low confidence does not mean wrong ancestry — it means admixed or ambiguous signal. If confidence is "low" (LL gap < 15 units), warn prominently and suggest the user specify --ancestry. Do not refuse to run, but make the limitation visible.
• Dosage is additive per allele for most loci. If a user is homozygous for a risk allele (dosage=2), the log-OR is doubled. This is the standard log-additive GWAS assumption.
• APOL1 (rs73885319 G1, rs60910145 G2) is an exception — it is recessive. A single heterozygous APOL1 allele does NOT confer the full OR. Risk requires two high-risk alleles (G1+G2, G1/G1, or G2/G2). The code uses model: "recessive_compound" and counts total alleles across both loci before applying the validated compound OR (~7x). Do not change APOL1 to additive.
• Combined OR is a naive product. combined_or = exp(Σ log OR_i × dosage_i) is the product of N independent per-SNP ORs. It is not a validated polygenic score. Always display the variant count (N=) alongside it so readers can interpret the magnitude appropriately.
• The curated panel covers ~10 diseases. Diseases not in the panel are simply not reported — do not extrapolate or add unsupported associations.
• AES is exploratory. Do not present it as a validated score, percentile, or clinical probability. Always use the word "exploratory" when explaining it to the user.
• "Genetic super-population" ≠ "ethnicity". Use precise language. Never say "your ethnicity" when you mean "your inferred genetic super-population."
• Reproducibility is computational, not clinical. The bundle records the command, environment, and file hashes needed to replay the same local calculation. It does not validate AES clinically and does not certify real-world disease risk.