Karyomapping - fold into trio page QC graph + per-gene graph/CSV page, retire standalone pages

🤖 Written by Claude

## Background

Karyomapping was used intensively by a single user who has since left; SA Path VG3 production logs (4–18 Aug 2026) show zero use. Rather than disabling it, repurpose the trio-level half as QC and shrink the per-gene half down to what people actually want — a graph and a CSV download — following existing page patterns.

The code already splits cleanly:

* `GenomeKaryomappingCounts` / `ContigKaryomappingCounts` (+ `relatedness_summary()`) FK straight to `Trio` — generic trio QC, no analysis wrapper needed
* `KaryomappingAnalysis` / `KaryomappingGene` — the PGD-specific page hierarchy; gene results are computed live (`get_variant_and_genotypes`), only the query params are persisted

## Proposal

| Piece | Home | Pattern it follows |
|---|---|---|
| Relatedness summary + per-chromosome QC graph | trio page (tab/section) | existing `genome_karyomapping_counts_summary` tag, promoted |
| Per-gene phasing graph + Download CSV | `trio/karyomapping/` — gene selector + upstream/downstream kb | `cohort_hotspot` / `cohort_gene_counts` |
| Entry link | `related_analyses_for_trio.html` ("View gene karyomapping for this trio", replacing "Create Karyomapping analysis for trio") | same menu as the cohort graph links |

The QC graph is the real win: father/mother in-phase vs out-of-phase support detects trio sample swaps and non-paternity/maternity from the VCF alone, and a chromosome-level anomaly against a consistent background is how UPD and contamination present. Trios are exactly where a silent sample mix-up is most expensive.

**Retire:** `karyomapping/analyses/` listing + datatable, `view_karyomapping_analysis`, `view_karyomapping_gene`, `create_karyomapping_analysis_for_trio` (7 URLs → 2). Eventually drop the `KaryomappingAnalysis` / `KaryomappingGene` models — archive the existing saved records (the departed user's historical results) before deleting.

## Performance / caching

The calculation may take a while (reads the whole VCF, compares 3 samples), so it's likely worth saving. Options — decide at implementation time:

* Keep using the existing `Genome`/`ContigKaryomappingCounts` models for the genome-wide QC numbers (already persisted per trio)
* Cached generated graph file (the existing cached_generated_file pattern)
* A small persisted summary, or a JSON response that builds the graph client-side, cached for a few weeks

Per-gene results are parameterised (gene + flanks) so a short-lived cache keyed on trio/gene/flanks fits better there than persistence.

## Absorbed issues

This issue absorbs two old Bitbucket-era enhancement requests, closed as duplicates of this work:

* SACGF/variantgrid_private#990 — *Karyomapping gene model graph*: overlay the gene/transcript structure (exons) on the per-gene phasing graph so you can see where the phasing SNPs fall relative to the gene. Optional enhancement to the per-gene graph page. (The issue's GTF/PyReference question is obsolete — use the transcript models in `genes/`.)
* SACGF/variantgrid_private#993 — *Whole chromosome Karyomapping graphs*: subsumed by the per-chromosome QC graph on the trio page.

Start with GenomeKaryomappingCounts, ContigKaryomappingCounts, KaryomappingAnalysis, and KaryomappingGene, then trace the existing genome_karyomapping_counts_summary tag and the cohort_hotspot/cohort_gene_counts page patterns. Review related_analyses_for_trio.html and the current karyomapping URLs, views, and templates to define the two replacement flows. Done means the trio QC and per-gene graph/CSV flows work, the entry link is updated, and the retired routes and records are handled without losing historical results.

Written by the indexing model from the issue text.