| name | qc-validity-federation-user |
| description | Run federation validity checks on a sites-only submission and interpret the QC report. Use when verifying that a partner ran proper QC on data they submitted as AC/AN/nhomalt without sharing genotypes. |
| metadata | {"ecosystem":"genohype","mcp-server":"gnomad-browser-lite","mcp-tools":["get_qc_report"]} |
QC Verify (Federation)
You are helping verify a federation partner's sites-only submission — per-variant AC,
AN, nhomalt stratified by genetic-ancestry group and sex, with no individual genotypes. You
cannot re-run their genotype-level QC; you inspect aggregate statistics and judge whether they
look like the output of a properly-QC'd cohort.
Read docs/spec/qc/README.md for the problem→fingerprint model and the three tiers.
Step 1: Run the checks
Given a sites file (.ht, .vcf.bgz, or Parquet; local, gs://, or s3://):
gbl qc run <source> --out qc-report.json
Everything runs in the partner's own environment; the report contains only aggregates and a
bounded sample of offending variant ids. Raw data does not move.
To review an already-generated report, read qc-report.json directly, or call the
get_qc_report MCP tool / GET /api/qc-report if a gbl serve deployment is configured.
Step 2: Interpret by tier
- Tier 1 (technical validity) — any FAIL is disqualifying. These are mathematically
guaranteed (
AC ≤ AN, AF = AC/AN, subgroups sum to global, nhomalt ≤ AC/2) plus schema.
A FAIL means a pipeline bug, not biology. Report the specific rule and the example variants.
- Tier 2 (biological plausibility) — WARNs need judgment. Compare each measured value to
its band and translate the deviation into the likely upstream cause (see the table below). A
WARN is a signal to investigate, not an automatic reject — it depends on N and ancestry mix.
- Tier 3 (cross-partner) — only meaningful once ≥2 nodes exist; currently deferred.
Step 3: Translate WARNs into likely causes
| Signal in the report | Likely upstream problem |
|---|
| Low Ti/Tv, low known-variant %, high variant count | No / poor variant filtering |
| Inbreeding F ≪ 0 (excess het), distorted SFS, elevated singletons | Sample contamination |
| Excess doubletons / excess common variants | Relatives not removed |
| AF concordance failure vs gnomAD | Ancestry mislabeling |
| Homozygous-alt calls on chrY, chrX anomalies | Sex misassignment |
| Non-uniform AN, missing chromosomes | Coverage problems |
| Wrong counts, unexpected contigs, missing fields | Pipeline misconfiguration |
Step 4: Report
Produce a summary: pass/warn/fail counts; each Tier-1 FAIL with rule + example variants; each
Tier-2 WARN with measured value, band, and the plain-language likely cause; and an overall
recommendation (accept / investigate / reject) — noting explicitly that the borderline call is
a human decision the methods team owns.
Scale
If the sites file is very large, hand off to the gh-cluster and pool-analyzer skills
to run the scan on a distributed pool.
When to use
- Verifying a new partner submission before it enters the federation.
- Re-checking a resubmission after a partner fixes flagged issues.
- Explaining why a submission was flagged, in terms of the upstream QC step that failed.
