explain ref agree normalization rules

[reece]

Finally got around to Larry's requests for explaining ref agree normalization rules.

Instead of writing a new section, I overhauled an existing related section (should-normalize).

[reece]

Did y'all (i.e., @ahwagner , @andreasprlic ) see that I addressed #377 in this PR a few weeks ago?
@larrybabb approved

[ahwagner]

Thanks for the ping on this thread @reece, I missed the original.

I think these changes accurately represent prior discussion on these points. I do think that the distinction between Allele and variant is artificial, particularly as we do not normalize reference-agree and reference-disagree Alleles the same. In addition, we (for well-justified reasons) represent Alleles as a state on a reference sequence, inherently comparing the state to some underlying reference.

To be very clear about what I mean, for two (short) reference sequences:

Reference 1: AACTA
Reference 2: AACGA

A resultant sequence of AACCA may be expressed as two different Alleles, conceptually:

• A C at interresidue coordinates <3,4> on Reference 1
• A C at interresidue coordinates <3,4> on Reference 2

Each of these result in different digests, as the information of the reference sequence is inherent to the representation of each Allele. The primary distinction between Allele and similar entities from other major variant formats is that we:

1. Do not represent the reference state as it is retrievable
2. Do not provide special character representation (e.g. =) of the reference-match state

I am not advocating that we compute resultant sequence to create digests; the process is far too cumbersome to be practical in implementation and the gains would be nearly non-existent (i.e. analogous reference sequences are too dissimilar for the above scenario to realistically occur). But I think we should revise the text here to better capture the notion of allele as a reference-match agnostic state instead of a reference-sequence agnostic state. The edits I have suggested here reflect this subtlety.

[reece]

Looks good to me (but I'm not a reviewer and am totally powerless! Yay!)

[ahwagner]

Changed applied per 👍 from @reece

[reece]

Anyone want to hit the merge button?