ancestry

Files (1)

• SKILL.md

SKILL.md (first lines)

# Ancestry Reference-Panel Context

Use this skill when the user asks about ancestry, population context, PCA
projection, reference-panel similarity, or which public reference samples their
genome is closest to.

## Contract

- This capability is a local reference-panel workflow, not an ethnicity or race
  predictor.
- Private tools require current-session Active Genome Index access approval or a genome source
  path supplied in the current chat.
- Public metadata tools do not read an Active Genome Index.
- Private genotype data stays local. Do not upload sample genotypes to external
  APIs or URLs.
- The MVP supports GRCh38 and GRCh37. If `genome_build` is omitted, the tool
  default is GRCh38 unless an approved Active Genome Index provides another
  build; the returned `defaults_applied` records that default.
- Labels are 1000 Genomes reference-panel labels, not ethnicity, nationality,
  race, tribe, caste, religion, or personal identity.
- Output is qualitative reference-panel similarity in PCA space. Do not produce
  component percentages, admixture proportions, haplogroups, local ancestry,
  ancestry dates, or relative matching.

> **Convention:** See `skills/conventions/context-routing.md`.
> **Convention:** See `skills/conventions/evidence-quality.md`.
> **Convention:** See `skills/_output-rules.md`.

## First Actions

1. Use `ancestry.list_reference_panels` to check whether the matching-build
   1000 Genomes 30x panel is installed and to inspect source URLs and label
   definitions.
2. Use `ancestry.build_source_context` when the user asks what the panel means
   or when you need explicit label and method boundaries before answering.
3. For sample-specific questions, use `genomi.describe_context` only
   when the chat asks about current Active Genome Index context or already mentioned a
   genome source. If the user supplied a genome source path, that is approval to read
   it for this session.
4. Use `ancestry.estimate_population_context` as the default sample-specific
   entry point. It runs overlap QC and PCA projection when enough markers are
   usable.
5. Use `ancestry.check_sample_overlap` when you only need QC readiness, and
   `ancestry.project_pca` when the host agent needs raw PCA coordinates and
   nearest reference-neighbor distances.

## Library Handling

The required optional library is build-specific:
`ancestry-1000g-30x-grch38` for GRCh38 samples and
`ancestry-1000g-30x-grch37` for GRCh37 samples. If a private ancestry tool
returns `requires_library_install`, explain that the compact local panel is
needed for marker overlap and PCA projection, then ask before installing with
the returned `ask_user.install_command` or `missing_library.install_command`.
For example:

```bash
genomi install --libraries ancestry-1000g-30x-grch38
genomi install --libraries ancestry-1000g-30x-grch38,liftover-chains,ancestry-1000g-30x-grch37
```

Do not treat a missing panel as evidence about the sample.

## Interpretation Rules

- Report marker overlap, projection readiness, marker-overlap quality, nearest reference
  group labels, and the method boundary.
- Marker-overlap quality is graded by the fraction of the loaded panel covered
  by usable sample dosages. There is no absolute marker-count floor.
- If less than 20% of the loaded panel is usable, do not project.
- If 20%-49% of the loaded panel is usable, projection is allowed with low
  marker-overlap quality and reference-neighbor context only.
- If 50%-79% of the loaded panel is usable, projection is allowed with moderate
  marker-overlap quality.
- If at least 80% of the loaded panel is usable, projection is allowed with
  high marker-overlap quality.
- Use wording like: "The sample projects closest to the EUR reference cluster
  in this panel."
- Do not say "predict ethnicity", "determine origin", or imply personal
  identity from a reference-panel label.

## User-Facing Answer Shape

If an Active Genome Index was projected, give the qualitative reference-panel
similarity, marker-overlap quality, and limitations. If the tool only returned public
metadata, answer directly without an Active Genome Index status disclaimer.

## Cross-Capability Synthesis

A scope-limited result from this capability is not a final user-facing answer
when other Genomi capabilities can contribute orthogonal evidence to the same
question. Returning "cannot answer" while applicable capabilities remain
unexamined is a host-agent failure mode.

## Tools

### ancestry.build_source_context

Explain 1000 Genomes ancestry panel provenance, label meanings, sampling limits, and method boundaries.

**Use when**: The user asks what the ancestry panel means, where labels come from, or why output is reference similarity rather than identity.

**Why necessary**: Ancestry language is easy to overstate; source context gives agents explicit label and method boundaries before answering.

**Not for**: Reading or projecting a user's genome; use ancestry.estimate_population_context after approval.

**Example prompts**: Explain the source and limitations of the ancestry panel.

**Result semantics**: Public metadata only; no Active Genome Index is read.

### ancestry.check_sample_overlap

Check how many installed 1000 Genomes ancestry panel markers are usable in an approved Active Genome Index.

**Use when**: The agent needs to know if a selected sample has enough overlap with the installed ancestry reference panel before projection.

**Why necessary**: Projection is not interpretable below the overlap thresholds; this tool separates QC from interpretation.

**Not for**: Public panel metadata; use ancestry.list_reference_panels. Ethnicity or origin prediction; ancestry tools provide reference-panel similarity only.

From exon-research/genomi, Apache-2.0.

More from exon-research/genomi