Count antigen matches per locus and donor

[zabeen]

• Atlas performs matching at the P-group level for both molecular and serology typings.
• The MatchingResult.TotalMatchCount represents the total, potential P-group match count, and this should always align with the mismatch criteria provided in the search request.
• Atlas generates two more counts, one based on scoring (ScoringResult.TotalMatchCount) and the other based on match prediction (MatchPredictionResult.OverallMatchCount)
• The original intent of the scoring count (and all scoring results) is to allow the consumer to rank matching donors from "best" potential match to "worst".
• WMDA has begun to use ScoringResult.TotalMatchCount to filter out donors that have too many antigen mismatches, caused by this known issue.
  • However, the scoring result count is affected by every kind of scoring-determined mismatch, e.g., expressing vs. null allele mismatches, which means genuine matches that users expect to see are not being shown in Search and Match.
• If WMDA wish to hide donors that have too many antigen mismatches, the safest solution would be to add a new property to the scoring results object that counts the number of antigen matches at each score locus and in total.
• This would be an extension of the existing feature, IsAntigenMatch, that is calculated for each scored position.

Acceptance Criteria for Locus Antigen Match Count

No null allele in both patient and donor typings

Given a locus for which scoring has been requested
When the patient and donor typing at said locus have no null alleles
And both positions are antigen matched
Then the locus antigen match count should be 2

Given a locus for which scoring has been requested
When the patient and donor typing at said locus have no null allele
And one position is antigen matched
And the other position is antigen mismatched
Then the locus antigen match count should be 1

Given a locus for which scoring has been requested
When the patient and donor typing at said locus have no null allele
And both positions are antigen mismatched
Then the locus antigen match count should be 0

One null allele in patient XOR donor typing

Given a locus for which scoring has been requested
When the patient xor donor typing at said locus contains one null allele
And the expressing pair of patient-donor typings is antigen matched
Then the locus antigen match count should be 2

Given a locus for which scoring has been requested
When the patient xor donor typing at said locus contains one null allele
And the expressing pair of patient-donor typings is antigen mismatched
Then the locus antigen match count should be 0

One null allele in both the patient and donor typings

Given a locus for which scoring has been requested
When the patient and donor typing at said locus each contain one null allele
And the expressing pair of patient-donor typings is antigen matched
Then the locus antigen match count should be 2

Given a locus for which scoring has been requested
When the patient and donor typing at said locus each contain one null allele
And the expressing pair of patient-donor typings is antigen mismatched
Then the locus antigen match count should be 0

Acceptance Criteria for Total Antigen Match Count

Given a search request where scoring has been requested
And the loci to score specifies loci A, B, C, DQB1, DRB1, and DPB1
And the loci to exclude from score aggregation specifies locus DPB1
When the donor has an antigen match count of 2 at every scored locus
Then the total antigen match count should be 10 (i.e., the DPB1 antigen match count should not be included)

[zabeen]

HLD

1. Implement issue #1073 that deals with alleles that do not have a serology assignment.
2. Update null-allele handling logic within AntigenMatching services:
   • If locus being scored contains a null allele, then assign the IsAntigenMatch value of the expressing orientation to the null-containing orientation. (Similar approach as that used in matching, where the P-group of the expressing typing is applied to the null allele-containing position).
3. Add new prop, ScoringResult.ScoringResultsByLocus.[LocusName].AntigenMatchCount, to be calculated as follows:
   • For a given score locus, count the number of times IsAntigenMatch is true.
   • Possible values would be 0, 1 or 2.
4. Add new prop, ScoringResult.AntigenMatchCount, to be calculated as follows during score aggregation:
   • Sum the locus AntigenMatchCount across every locus listed in SearchRequest.ScoringCriteria.LociToScore but not listed in SearchRequest.ScoringCriteria.LociToExcludeFromAggregateScore.

[zabeen]

@RimkePostel @mmelchers please could you read the description of this ticket and confirm whether this would be an adequate solution?

[mmelchers]

This ticket is only about the antigen match count. IF we would switch to that field, then we could end up in a situation where we would get a 10/10 but still the scoring would indicate a mismatch. That is not acceptable as it would be confusing to the search coordinators.

[zabeen]

Will not be doing this work - will instead raise a new ticket so that null allele vs. expressing is assigned a grade other than Mismatch