Paper: reframe around resolution goal, fair comparisons, terminology

[davmlaw]

🤖 Written by Claude

Addresses the paper feedback in claude/paper_feedbac_2026-08-19.md (#112). Paper-only prose and framing changes; no data-content or client-code changes, so no changelog entry.

Framing (the "north star")

• Abstract Motivation and Introduction now lead with the actual goal, resolving as many real-world HGVS descriptions as possible (the Shariant use case), rather than "a better UTA".
• Added a spine sentence to the intro casting broad coverage, string cleaning, and version substitution as the three things that serve that goal.
• Fixed the UTA framing to the real tradeoff (local PostgreSQL install vs a slow, often firewalled public server).

Fair comparisons

• Removed the "nearly four orders of magnitude" claim (cdot local vs UTA remote) from the abstract and R3. R3 now reports the two matched comparisons: local-to-local (~4x) and remote-to-remote (cdot REST vs public UTA).
• Restructured R2: the Ensembl-enriched sample is presented as a capability check (UTA holds no Ensembl at all), not an accuracy headline. Dropped the unfair aggregate figure; RefSeq parity plus the historical submitted corpus are now the fair head-to-head. The apparent "818 Ensembl vs not one Ensembl string" contradiction is resolved by explicitly contrasting the enriched sample with the natural (RefSeq-only) submission mix.

Terminology

• "version fallback" / "version bumping" → "version substitution" throughout.
• "Tier 1 / Tier 2" → "public data / private data".
• "a version bump can move a variant" → "changes the coordinate a variant projects to".
• "What laboratories actually submit" → past tense; search-box corpus described as the regex-matched subset.

Trims and citations

• Cite the Ensembl VEP RefSeq alignment-gap limitation (ensembl-vep#1053) in R1, precise to the c.-to-genomic direction.
• Compressed the JSON-format, benchmarking, and Ensembl TARK sections.
• Discussion now opens on the general-purpose transcript-source angle.

Deferred

Added claude/plans/new_analyses_plan.md capturing the five feedback items that need re-running scripts or new data (time-bucketed submitted sampling, local UTA over all of ClinVar, submitter-attribution for missing versions, warm-cache benchmark rerun, dropping non-HGVS input from the R4 residual). These are not in this PR.

Quick build renders cleanly (snakemake -s paper/Snakefile), all template fact references resolve.

[davmlaw]

Motivation still doesn't tell the story - Australian Genomics Shariant project had to collect historical c.HGVS from labs across the country. cdot is spun out of that work, and broad goal of the project is to fit
into ecosystem and help resolve as many HGVS as possible (so cleaning, and whole catalog of historical). I feel "What laboratories submitted" should be "ClinVar submissions as historical record of transcripts used" or something like
that. There should be vibepaper facts for: "the production corpus (N = 32,752) ... 1,721 rescued queriesthe production corpus (N = 32,752)." and "The 3.3% of the production corpus (1,075 queries; 826 unique strings)"

[davmlaw]

🤖 Written by Claude

Pushed c26effa addressing the review, plus two of the deferred analyses.

Your PR comments

• Motivation / north star: the abstract motivation now leads with the Shariant origin (Australian Genomics pooling historical c.HGVS from labs nationwide, cdot spun out to resolve as many as possible). The intro already carried this at para 3; the abstract was the gap.
• "What laboratories submitted": renamed to "ClinVar submissions as a historical record of transcripts used" and reworded the lead-in to frame it as the historical record, not present-tense behaviour.
• vibepaper facts: the hardcoded cleaning-corpus numbers (N, rescued, residual) are now a real fact file (cleaning_corpus.csv, wired into the Snakefile), templated across R4, Table 2 and Table S6.

Deferred analyses folded in

• R4 residual: non-HGVS input (81 pasted URLs / prose that slipped the regex) is removed from the corpus before counting, per your data-collection-artifact point. Residual 3.3% → 3.0%.
• R2 fair sampling: rebuilt the submitted corpus from the VCV XML with per-pair submission dates, and now report two seed-42 draws: a recency-biased whole-file random draw and a time-bucketed draw balanced across 2008–2026 eras. R2 leads with the fair one (cdot 98.0% vs UTA 79.9%); it is harder than the random draw (99.0/82.2) and widens the cdot–UTA gap, because older submissions cite the superseded versions the corpus exists to exercise. Adopted the more complete self-contained XML corpus (3.20M pairs); version_not_current moved 81.8% → 75.1% as a result.

Still open (awaiting your steer): warm-cache benchmark rerun (R3), full local-UTA over all ClinVar, and the submitter-attribution analysis.