Support Version 2 Nomenclature

  - Add initial support for importing V2 into db
  - Lookup V2 nomenclature

Author: pbashyal-nmdp

pyard/data_repository.py

@@ -1,3 +1,25 @@
+# -*- coding: utf-8 -*-
+#
+#    py-ard
+#    Copyright (c) 2020 Be The Match operated by National Marrow Donor Program. All Rights Reserved.
+#
+#    This library is free software; you can redistribute it and/or modify it
+#    under the terms of the GNU Lesser General Public License as published
+#    by the Free Software Foundation; either version 3 of the License, or (at
+#    your option) any later version.
+#
+#    This library is distributed in the hope that it will be useful, but WITHOUT
+#    ANY WARRANTY; with out even the implied warranty of MERCHANTABILITY or
+#    FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
+#    License for more details.
+#
+#    You should have received a copy of the GNU Lesser General Public License
+#    along with this library;  if not, write to the Free Software Foundation,
+#    Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA.
+#
+#    > http://www.fsf.org/licensing/licenses/lgpl.html
+#    > http://www.opensource.org/licenses/lgpl-license.php
+#
 import functools
 import sqlite3
 
@@ -299,3 +321,25 @@ def generate_serology_mapping(db_connection: sqlite3.Connection, imgt_version):
         # Save the serology mapping to db
         db.save_dict(db_connection, table_name='serology_mapping',
                      dictionary=sero_mapping, columns=('serology', 'allele_list'))
+
+
+def generate_v2_to_v3_mapping(db_connection: sqlite3.Connection, imgt_version):
+    if not db.table_exists(db_connection, 'v2_mapping'):
+        # TODO: Create mapping table using both the allele list history and
+        #  deleted alleles as reference.
+        # Temporary Example
+        v2_to_v3_example = {
+            "A*0104": "A*01:04N",
+            "A*0105N": "A*01:04N",
+            "A*0111": "A*01:11N",
+            "A*01123": "A*01:123N",
+            "A*0115": "A*01:15N",
+            "A*0116": "A*01:16N",
+            "A*01160": "A*01:160N",
+            "A*01162": "A*01:162N",
+            "A*01178": "A*01:178N",
+            "A*01179": "A*01:179N",
+            "DRB5*02ZB": "DRB5*02:UTV",
+        }
+        db.save_dict(db_connection, table_name='v2_mapping',
+                     dictionary=v2_to_v3_example, columns=('v2', 'v3'))

pyard/db.py

@@ -1,3 +1,25 @@
+# -*- coding: utf-8 -*-
+#
+#    py-ard
+#    Copyright (c) 2020 Be The Match operated by National Marrow Donor Program. All Rights Reserved.
+#
+#    This library is free software; you can redistribute it and/or modify it
+#    under the terms of the GNU Lesser General Public License as published
+#    by the Free Software Foundation; either version 3 of the License, or (at
+#    your option) any later version.
+#
+#    This library is distributed in the hope that it will be useful, but WITHOUT
+#    ANY WARRANTY; with out even the implied warranty of MERCHANTABILITY or
+#    FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
+#    License for more details.
+#
+#    You should have received a copy of the GNU Lesser General Public License
+#    along with this library;  if not, write to the Free Software Foundation,
+#    Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA.
+#
+#    > http://www.fsf.org/licensing/licenses/lgpl.html
+#    > http://www.opensource.org/licenses/lgpl-license.php
+#
 import pathlib
 import sqlite3
 from typing import Tuple, Dict, Set, List
@@ -92,7 +114,7 @@ def serology_to_alleles(connection: sqlite3.Connection, serology: str) -> List[s
     :return: List of alleles
     """
     serology_query = "SELECT allele_list from serology_mapping where serology = ?"
-    cursor = connection.execute(serology_query, (serology, ))
+    cursor = connection.execute(serology_query, (serology,))
     result = cursor.fetchone()
     cursor.close()
     if result:
@@ -102,6 +124,23 @@ def serology_to_alleles(connection: sqlite3.Connection, serology: str) -> List[s
     return alleles
 
 
+def v2_to_v3_allele(connection: sqlite3.Connection, v2_allele: str) -> str:
+    """
+    Look up V3 version of the allele in the database.
+
+    :param connection: db connection of type sqlite.Connection
+    :param v2_allele: V2 allele
+    :return: V3 allele
+    """
+    v2_query = "SELECT v3 from v2_mapping where v2 = ?"
+    cursor = connection.execute(v2_query, (v2_allele,))
+    result = cursor.fetchone()
+    cursor.close()
+    if result:
+        return result[0]
+    return ''
+
+
 def is_valid_mac_code(connection: sqlite3.Connection, code: str) -> bool:
     """
     Check db if the MAC code exists.
@@ -215,4 +254,4 @@ def load_dict(connection: sqlite3.Connection, table_name: str, columns: Tuple[st
     cursor.execute(select_all_query)
     table_as_dict = {k: v for k, v in cursor.fetchall()}
     cursor.close()
-    return table_as_dict
+    return table_as_dict

pyard/pyard.py

@@ -27,8 +27,8 @@
 
 from . import db
 from .data_repository import generate_ars_mapping, generate_mac_codes, generate_alleles_and_xx_codes, \
-    generate_serology_mapping
-from .db import is_valid_mac_code, mac_code_to_alleles
+    generate_serology_mapping, generate_v2_to_v3_mapping
+from .db import is_valid_mac_code, mac_code_to_alleles, v2_to_v3_allele
 from .smart_sort import smart_sort_comparator
 
 HLA_regex = re.compile("^HLA-")
@@ -66,6 +66,8 @@ def __init__(self, imgt_version: str = 'Latest',
         self.dup_g, self._G, self._lg, self._lgx = generate_ars_mapping(self.db_connection, imgt_version)
         # Load Serology mappings
         generate_serology_mapping(self.db_connection, imgt_version)
+        # Load V2 to V3 mappings
+        generate_v2_to_v3_mapping(self.db_connection, imgt_version)
 
         # Close the current read-write db connection
         self.db_connection.close()
@@ -172,6 +174,11 @@ def redux_gl(self, glstring: str, redux_type: str) -> str:
             return "/".join(sorted(set([self.redux_gl(a, redux_type) for a in glstring.split("/")]),
                                    key=functools.cmp_to_key(smart_sort_comparator)))
 
+        # Handle V2 to V3 mapping
+        if self.is_v2(glstring):
+            glstring = self._map_v2_to_v3(glstring)
+            return self.redux_gl(glstring, redux_type)
+
         # Handle Serology
         if self.is_serology(glstring):
             alleles = self._get_alleles_from_serology(glstring)
@@ -232,6 +239,17 @@ def is_mac(gl: str) -> bool:
         """
         return re.search(r":\D+", gl) is not None
 
+    @staticmethod
+    def is_v2(allele: str) -> bool:
+        """
+        Version 2 of the nomenclature is a single field.
+        It does not have any ':' field separator.
+        Eg: A*0104
+        :param allele: Possible allele
+        :return: Is the allele in V2 nomenclature
+        """
+        return '*' in allele and not ':' in allele
+
     def _is_valid_allele(self, allele):
         """
         Test if allele is valid in the current imgt database
@@ -255,7 +273,7 @@ def _get_alleles(self, code, locus_antigen) -> Iterable[str]:
         # else it's a group expansion
         is_allelic_expansion = any([':' in allele for allele in alleles])
         if is_allelic_expansion:
-            locus = locus_antigen.split('*')[0] # Just keep the locus name
+            locus = locus_antigen.split('*')[0]  # Just keep the locus name
             alleles = [f'{locus}*{a}' for a in alleles]
         else:
             alleles = [f'{locus_antigen}:{a}' for a in alleles]
@@ -272,6 +290,14 @@ def _get_alleles_from_serology(self, serology) -> Iterable[str]:
         else:
             return alleles
 
+    def _map_v2_to_v3(self, v2_allele):
+        """
+        Get V3 version of V2 versioned allele
+        :param v2_allele: V2 versioned allele
+        :return: V3 versioned allele
+        """
+        return v2_to_v3_allele(self.db_connection, v2_allele)
+
     def isvalid(self, allele: str) -> bool:
         """
         Determines validity of an allele
@@ -283,7 +309,9 @@ def isvalid(self, allele: str) -> bool:
         """
         if allele == '':
             return False
-        if not self.is_mac(allele) and not self.is_serology(allele):
+        if not self.is_mac(allele) and \
+                not self.is_serology(allele) and \
+                not self.is_v2(allele):
             # Alleles ending with P or G are valid_alleles
             if allele.endswith(('P', 'G')):
                 # remove the last character
@@ -330,7 +358,7 @@ def mac_toG(self, allele: str) -> str:
         """
         locus_antigen, code = allele.split(":")
         if HLA_regex.search(allele):
-            locus_antigen = locus_antigen.split("-")[1] # Remove HLA- prefix
+            locus_antigen = locus_antigen.split("-")[1]  # Remove HLA- prefix
         if is_valid_mac_code(self.db_connection, code):
             alleles = self._get_alleles(code, locus_antigen)
             group = [self.toG(a) for a in alleles]
@@ -370,7 +398,7 @@ def expand_mac(self, mac_code: str):
         locus_antigen, code = mac_code.split(":")
         if is_valid_mac_code(self.db_connection, code):
             if HLA_regex.search(mac_code):
-                locus_antigen = locus_antigen.split("-")[1] # Remove HLA- prefix
+                locus_antigen = locus_antigen.split("-")[1]  # Remove HLA- prefix
                 return ['HLA-' + a for a in self._get_alleles(code, locus_antigen)]
             else:
                 return list(self._get_alleles(code, locus_antigen))

tests/features/version2.feature

@@ -0,0 +1,16 @@
+Feature: Version 2 Nomenclature
+
+  py-ard is able to reduce version 2 HLA nomenclature.
+
+  Scenario Outline:
+
+    Given the version 2 typing is <Version2>
+    When reducing on the <Level> level (ambiguous)
+    Then the reduced allele is found to be <Redux Allele>
+
+
+    Examples: Valid A serology typings
+      | Version2  | Level | Redux Allele                                                   |
+      | A*0105N   | G     | A*01:01:01G                                                    |
+      | A*0111    | G     | A*01:11N                                                       |
+      | DRB5*02ZB | G     | DRB5*01:02:01G/DRB5*01:03/DRB5*02:02:01G/DRB5*02:03/DRB5*02:04 |

tests/steps/redux_allele.py

@@ -27,3 +27,8 @@ def step_impl(context, redux_allele):
 @given("the serology typing is {serology}")
 def step_impl(context, serology):
     context.allele = serology
+
+
+@given("the version 2 typing is {v2_allele}")
+def step_impl(context, v2_allele):
+    context.allele = v2_allele