Haplotype Frequency dataset nomenclature version

[zabeen]

Q: does the HLA nomenclature version of a haplotype frequency dataset have to be the same as that used by the matching algorithm component?

[zabeen]

Background: The matching algorithm will usually be on the latest nomenclature version, as it is updated with every run of the data refresh job. However, the nomenclature version of stored haplotype frequencies is not automatically updated, and will only progress if/when a newer file is uploaded that has been encoded to a later HLA version.

Technically speaking, there is no explicit validation in the codebase that compares the HLA version of a newly uploaded haplotype frequency dataset file to the version being used by the matching algorithm; in that respect, Atlas allows the two components to operate using different HLA versions.

However, the HLA metadata dictionary component must contain data for the file's HLA version for the upload to succeed, else it will trigger an exception during import (likely during this HLA validation step).

At present, there are two ways to populate the metadata dictionary with a missing HLA version:

1. Invoke this function on the Atlas installation of interest.

2. Run the Atlas solution locally, and then call this endpoint on the Matching algorithm API, ensuring that the relevant settings on the API project are pointing at the appropriate remote Atlas installation (mainly this one).

[benbelow]

I think there may be one case where this won't work - if:

• The matching algorithm is using a more recent version of nomenclature
• And a donor or patient is typed with a new allele that was introduced in that version
• Then when the HMD comes to expand that allele for match prediction, it won't think it exists, and may fail.

The reverse is not true - i.e. the HMD knows how to go "back in time" through the versions to succesfully expand renamed or deleted alleles - but can't go forward to find ones introduced in newer versions.

It's been a while since I looked through the relevant code though, so this is just from memory. @zabeen does that sound right having looked through this recently?

[zabeen]

@benbelow your theory is correct - and @mmelchers testing notes have proven your theory :)

I haven't thought it through 100%, but at point of match prediction, we may have to do something like:

1. Convert patient/donor HLA to small g/P groups using the data refresh HLA version to avoid HLA lookup exceptions.
2. Use those small gs/P groups to query the HF sets - which may be at an older HLA version - and accept the risk that very new groups (i.e., 1st/2nd field changes) will not be be represented by the HF sets.