Handle pre-annotated codon and nucleotide variants in count files

[catchambers]

Support Pre-Annotated DNA Variants in load_experiment + Revisit wt_seq Requirement

Problem

load_experiment currently converts pre-annotated AA variants in variant_seq into canonical aa_seq_diff, but does not provide equivalent conversion for pre-annotated DNA variant notations (e.g., A123T, A.123.T, etc.) into canonical dna_seq_diff.

Related architectural question: should wt_seq always be required, even when inputs are fully pre-annotated?

Proposed Scope

1. Add pre-annotated DNA conversion at ingest in load_experiment:
   • Parse supported DNA notations from variant_seq.
   • Emit canonical dna_seq_diff (ref.position.alt).
   • Preserve existing behavior for full-sequence DNA and AA.
2. Keep validation behavior explicit:
   • If DNA annotation includes a reference base, optionally validate against WT when WT is provided.
   • Decide and document whether mismatch should hard-fail or warn.
3. Reassess wt_seq requirement:
   • Make wt_seq conditionally required only when needed for operations that require sequence context (translation/comparison/position inference/WT checks).
   • Keep required for existing full-sequence workflows unless conditional logic is implemented.

Acceptance Criteria

• Pre-annotated DNA inputs can be ingested without relying on full-sequence diff generation.
• Canonical dna_seq_diff is present and downstream annotation/statistics work unchanged.
• Behavior is defined for WT-reference mismatches in pre-annotated DNA input.
• Documentation states when wt_seq is required vs optional.
• Unit tests cover:
  • Valid pre-annotated DNA normalization.
  • Out-of-range or malformed DNA annotations.
  • WT mismatch behavior (according to chosen policy).
  • Conditional wt_seq requirement rules.

Notes

• Current architecture is reasonable if treated as two pipelines:
  • Ingest-time normalization for pre-annotated variants.
  • Analysis-time derivation for full sequences.
• Unification target should be canonical intermediate columns (aa_seq_diff, dna_seq_diff), not forcing all logic into one function.