Capture & surface RefSeq genome/transcript mismatches (warn/refuse in FastaSeqFetcher)

[davmlaw]

🤖 Written by Claude

Split out from #84 (which keeps the docs + recommendation work).

Problem

RefSeq transcript sequences can differ from the genome (substitutions and non-frameshifting indels). When FastaSeqFetcher builds a transcript sequence by pasting genome exons together, those differences are applied silently, so the transcript a user resolves against is not the real RefSeq transcript. There is currently no signal exposed to warn or refuse in that case.

Note the mismatch info is not in the CIGAR/Gap string — Gap only uses M/I/D/F/R, and M ("aligned") already includes mismatches. The real signals live in GFF attributes/notes.

Where the signal is (RefSeq)

Annotation GFF:

• exception=annotated by transcript or proteomic data
• Note=...The RefSeq transcript has N non-frameshifting indel compared to this genomic sequence
• Note=...The RefSeq protein has N non-frameshifting indel compared to this genomic sequence

Alignment GFF (cDNA_match features):

• num_mismatch, pct_identity_gap, pct_coverage

Today cdot only stores the last free-text Note in a note field and parses none of this; FastaSeqFetcher ignores it. Ensembl transcripts always match the genome, so this only affects RefSeq.

Scope

1. Data/generation — parse exception=, the "N non-frameshifting indel compared to this genomic sequence" notes, and (where available) the alignment-GFF num_mismatch / pct_identity_gap / pct_coverage; store structured per-transcript (distinct from the existing free-text note).
2. Schema/format — decide the field shape (e.g. a genome_transcript_mismatch flag and/or pct_identity), bump the schema version, update cdot/models.py + the JSON-schema docs, and keep back-compat loading of older data.
3. Client — FastaSeqFetcher warns/refuses on known-mismatch transcripts, configurable (off / warn / raise), defaulting to warn when the field is present.

Optional cheap interim (no data regen): when both a genome-built and a SeqRepo sequence are available for a transcript, compare them and warn on diff.

Acceptance criteria

• RefSeq generation captures the genome↔transcript mismatch signal into a structured field
• Schema version bumped; new field documented; old data still loads
• FastaSeqFetcher can warn/refuse on mismatched transcripts (configurable)
• Tests cover a known-mismatch RefSeq transcript (a test GFF in tests/test_data/ already carries the "non-frameshifting indel" notes and exception= attributes)

[davmlaw]

🤖 Written by Claude

Folding in the worked examples from #55 (the earlier investigation of this same phenomenon), which give us two concrete known-mismatch RefSeq transcripts to use as test fixtures for the acceptance criteria here.

NM_000399.3 (EGR2) — 1 non-frameshifting indel. GRCh37 and GRCh38 both have the last exon as CIGAR M2190 D1 M282. Same length as the real RefSeq transcript but different content in the middle: RefSeq has a "T" inserted near the start, the genome-exon build has an "A" inserted elsewhere. Signals:

• mRNA/exon: Note=The RefSeq transcript has 1 non-frameshifting indel compared to this genomic sequence;exception=annotated by transcript or proteomic data
• cDNA_match: num_mismatch=0;gap_count=1;pct_identity_gap=99.9664 with Gap=M2190 D1 M282

NM_000314.4 (PTEN) — 1 substitution + 1 indel. On GRCh37, transcript base differs from genome at one position (transcript C vs genome G). Signals:

• mRNA/exon: Note=The RefSeq transcript has 1 substitution and 1 indel compared to this genomic sequence;exception=annotated by transcript or proteomic data
• cDNA_match: num_mismatch=1;gap_count=1;pct_identity_gap=99.9639 with Gap=M666 D1 M444

These cover both relevant cases: a pure indel (num_mismatch=0, signal only in the Note/exception) and a substitution (num_mismatch=1, signal in both the Note and the alignment-GFF). Both are public RefSeq transcripts, so they are fine to add as tests/test_data/ fixtures.

#55 is the original investigation of this and is a duplicate of this issue; pointing it here.