Decide what a clinically accessible variant evidence download looks like

[bencap]

Summary

Manuscript review called our variant-level JSON export not clinically accessible: for a tool aimed at clinical interpretation, a reviewer expected something like CSV or a formatted report. We should (1) settle what we should offer, and (2) produce a description of this format that the manuscript can then describe.

Problem

The MaveMD variant page's "Download annotations" split button offers up to three options: Pathogenicity Statement, Functional Impact Statement, Functional Study Result. Each one fetches the corresponding /mapped-variants/{urn}/va/{type} response and saves JSON.stringify(data) to a .json file.

What an unsuspecting clinician actually receives is a deeply nested GA4GH VA-Spec object serialized onto a single line. It is a correct machine artifact but an unusable human one. Nothing in it is skimmable, and it is not in a shape anyone would attach to a variant curation record.

Two secondary problems worth deciding on at the same time:

• The three options are each conditional on mapping data, a non-NA score, and the relevant calibrations existing. When a condition fails the option is silently absent, so a user cannot tell whether a format does not exist for this variant or the feature is broken.
• Our download surface as a whole has grown without a stated inventory. Today it spans: score set scores CSV, counts CSV, custom-column CSV, metadata .txt, mapped variants .json, annotated variants .ndjson (streamed), and the three per-variant VA-Spec .json exports above. The manuscript has to describe these, which is a good forcing function for deciding which are intentional.

Questions to resolve

1. What is the artifact for? Reading at the bench, attaching to a curation record, or machine ingestion? These pull in different directions and might require distinct solutions.
2. Format. A flat CSV/TSV with one row per measurement, a formatted PDF/HTML report, or both? A report is a much heavier lift and adds a rendering dependency but is perhaps nicer for attachment. CSV is cheap and composes with the refactor in the companion issue, but requires additional parsing by a clinician.
3. Minimum content set. Score, calibrated evidence strength and direction, assay description, score set and publication citation, calibration provenance, gnomAD and ClinVar context. Which of these are required for the download to be clinically useful on its own, without the web page next to it?
4. Scope: one variant or the equivalence class? The page routinely shows several measurements across multiple assays. A single-measurement download may be the wrong default.
5. Missing-option discoverability. Do we render unavailable formats as disabled with a reason, rather than omitting them?

Definition of done

• A decision recorded on this issue covering questions 1–5.
• A stated, enumerable list of the download formats we intend to support, suitable for the manuscript.
• Follow-up implementation issues filed against that decision, plus user-facing docs for each format we commit to.

Notes

• The per-variant export path is the variant screen's download options calling into the variant lookup composable, which serializes the route response directly.
• Companion issue: refactor: extract score set CSV generation into a dedicated, tested module #798.