Merge pull request #203 from pbashyal-nmdp/broad_split_api

Broads and Splits

Author: mmaiers-nmdp

.pre-commit-config.yaml

@@ -7,7 +7,7 @@ repos:
             -   id: check-yaml
             -   id: check-added-large-files
     -   repo: https://github.com/psf/black
-        rev: 22.3.0
+        rev: 23.1.0
         hooks:
             -   id: black
                 language_version: python3

README.md

@@ -192,6 +192,16 @@ DRB1*08:01:01G/DRB1*08:02:01G/DRB1*08:03:02G/DRB1*08:04:01G/DRB1*08:05/ ...
 $ pyard -i 3290 --gl 'A1' -r lgx # For a particular version of DB
 A*01:01/A*01:02/A*01:03/A*01:06/A*01:07/A*01:08/A*01:09/A*01:10/A*01:12/ ...
 ```
+
+### Find Broad/Splits of an allele or serology typing
+```shell
+$ pyard --splits "A*10"
+A*10 = A*25/A*26/A*34/A*66
+
+$ pyard --splits B14
+B14 = B64/B65
+```
+
 ### Batch Reduce a CSV file
 
 `pyard-csv-reduce` can be used to batch process a CSV file with HLA typings. See [documentation](extras/README.md) for instructions on how to configure and run.

api-spec.yaml

@@ -261,3 +261,52 @@ paths:
                     description: Describes what went wrong
                     type: string
                     example: "All of DRB1_SLUG, DRB3, DRB4, DRB5 values not provided"
+  /splits/{allele}:
+    get:
+      tags:
+        - Broad Splits
+      operationId: api.splits_controller
+      summary: Search Broad Split Mapping
+      description: |
+        Given a broad or a split, broad/split mappings will
+        be returned if available.
+      parameters:
+        - name: allele
+          in: path
+          description: A valid Allele/Serology
+          required: true
+          schema:
+            type: string
+          example: A*10
+      responses:
+        200:
+          description: Broad/Split mapping
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  broad:
+                    description: Broad Allele
+                    type: string
+                    example: "A*10"
+                  splits:
+                    description: Corresponding Splits
+                    type: array
+                    example:
+                      - "A*25"
+                      - "A*26"
+                      - "A*34"
+                      - "A*66"
+        404:
+          description: |
+            Broad/Split mapping not found for the given allele
+          content:
+            application/json:
+                schema:
+                  type: object
+                  properties:
+                    message:
+                      description: Mapping not found
+                      type: string
+                      example: "Broad/Split not found"

api.py

@@ -84,3 +84,11 @@ def drbx_blender_controller():
 def version_controller():
     version = ard.get_db_version()
     return {"version": version}, 200
+
+
+def splits_controller(allele: str):
+    mapping = pyard.find_broad_splits(allele)
+    if mapping:
+        return {"broad": mapping[0], "splits": mapping[1]}, 200
+
+    return {"message": f"No Broad/Splits matched {allele}"}, 404

pyard/__init__.py

@@ -23,6 +23,7 @@
 #
 from .pyard import ARD
 from .blender import blender as dr_blender
+from .broad_splits import find_splits as find_broad_splits
 
 __author__ = """NMDP Bioinformatics"""
 __version__ = "0.9.1"

pyard/broad_splits.py

@@ -20,6 +20,7 @@
 #    > http://www.fsf.org/licensing/licenses/lgpl.html
 #    > http://www.opensource.org/licenses/lgpl-license.php
 #
+import re
 
 #
 # Broad, Splits and Associated Antigens
@@ -44,24 +45,36 @@
     "DRB1*02": ["DRB1*15", "DRB1*16"],
     "DRB1*06": ["DRB1*13", "DRB1*14"],
 }
-broad_splits_ser_mapping = {
-    "A9": ["A23", "A24"],
-    "A10": ["A25", "A26", "A34", "A66"],
-    "A19": ["A29", "A30", "A31", "A32", "A33", "A74"],
-    "A28": ["A68", "A69"],
-    "B5": ["B51", "B52"],
-    "B12": ["B44", "B45"],
-    "B15": ["B62", "B63", "B75", "B76", "B77"],
-    "B16": ["B38", "B39"],
-    "B17": ["B57", "B58"],
-    "B21": ["B49", "B50"],
-    "B22": ["B54", "B55", "B56"],
-    "B40": ["B60", "B61"],
-    "B70": ["B71", "B72"],
-    "Cw3": ["Cw9", "Cw10"],
-    "DQ1": ["DQ5", "DQ6"],
-    "DR2": ["DR15", "DR16"],
-    "DR3": ["DR17", "DR18"],
-    "DR5": ["DR11", "DR12"],
-    "DR6": ["DR13", "DR14"],
-}
+
+# Loaded at runtime
+broad_splits_ser_mapping = None
+
+HLA_regex = re.compile("^HLA-")
+
+
+def find_splits(allele: str) -> tuple:
+    if HLA_regex.search(allele):
+        prefix = True
+        allele_name = allele.split("-")[1]
+    else:
+        prefix = False
+        allele_name = allele
+
+    if "*" in allele_name:
+        mapping = broad_splits_dna_mapping
+    else:
+        mapping = broad_splits_ser_mapping
+
+    if allele_name in mapping:
+        return _get_mapping(allele_name, mapping, prefix)
+
+    for broad in mapping:
+        if allele_name in mapping[broad]:
+            return _get_mapping(broad, mapping, prefix)
+
+
+def _get_mapping(broad, mapping, prefix):
+    if prefix:
+        return "HLA-" + broad, list(map(lambda x: "HLA-" + x, mapping[broad]))
+    else:
+        return broad, mapping[broad]

pyard/data_repository.py

@@ -29,9 +29,9 @@
 
 import pandas as pd
 
-from . import db
+from . import db, broad_splits
 from .broad_splits import broad_splits_dna_mapping
-from .broad_splits import broad_splits_ser_mapping
+from .load import load_serology_broad_split_mapping
 from .misc import (
     get_2field_allele,
     get_3field_allele,
@@ -390,7 +390,7 @@ def generate_alleles_and_xx_codes_and_who(
     xx_codes = xx_df.groupby(["1d"]).apply(lambda x: list(x["Allele"])).to_dict()
 
     # Update xx codes with broads and splits
-    for broad, splits in broad_splits_dna_mapping.items():
+    for broad, splits in broad_splits.broad_splits_dna_mapping.items():
         for split in splits:
             if broad in xx_codes:
                 xx_codes[broad].extend(xx_codes[split])
@@ -635,15 +635,15 @@ def generate_serology_mapping(db_connection: sqlite3.Connection, imgt_version):
 
         # map alleles for split serology to their corresponding broad
         # Update xx codes with broads and splits
-        for broad, splits in broad_splits_ser_mapping.items():
+        for broad, splits in broad_splits.broad_splits_ser_mapping.items():
             for split in splits:
                 try:
                     sero_mapping[broad] = "/".join(
                         [sero_mapping[broad], sero_mapping[split]]
                     )
-
                 except KeyError:
-                    sero_mapping[broad] = sero_mapping[split]
+                    if split in sero_mapping:
+                        sero_mapping[broad] = sero_mapping[split]
 
         # re-sort allele lists into smartsort order
         for sero in sero_mapping.keys():
@@ -724,3 +724,23 @@ def set_db_version(db_connection: sqlite3.Connection, imgt_version):
 
 def get_db_version(db_connection: sqlite3.Connection):
     return db.get_user_version(db_connection)
+
+
+def generate_serology_broad_split_mapping(db_connection, imgt_version):
+    if not db.table_exists(db_connection, "serology_broad_split_mapping"):
+        sero_mapping = load_serology_broad_split_mapping(imgt_version)
+        # Save the `splits` as a "/" delimited string to db
+        sero_splits = {sero: "/".join(splits) for sero, splits in sero_mapping.items()}
+        db.save_dict(
+            db_connection,
+            table_name="serology_broad_split_mapping",
+            dictionary=sero_splits,
+            columns=("serology", "splits"),
+        )
+        return sero_mapping
+
+    sero_mapping = db.load_dict(
+        db_connection, "serology_broad_split_mapping", ("serology", "splits")
+    )
+    sero_splits = {k: v.split("/") for k, v in sero_mapping.items()}
+    return sero_splits

pyard/load.py

@@ -0,0 +1,34 @@
+from typing import Dict, List
+
+import pandas as pd
+
+IMGT_HLA_URL = "https://raw.githubusercontent.com/ANHIG/IMGTHLA/"
+
+
+def add_locus_name(locus: str, splits: str) -> List:
+    split_list = map(lambda sero: locus + sero, splits.split("/"))
+    return list(split_list)
+
+
+#
+# Derived from rel_ser_ser.txt
+# https://raw.githubusercontent.com/ANHIG/IMGTHLA/Latest/wmda/rel_ser_ser.txt
+#
+def load_serology_broad_split_mapping(imgt_version: str) -> Dict:
+    ser_ser_url = f"{IMGT_HLA_URL}{imgt_version}/wmda/rel_ser_ser.txt"
+    df_p = pd.read_csv(
+        ser_ser_url,
+        skiprows=6,
+        names=["Locus", "A", "Splits", "Associated"],
+        usecols=[0, 1, 2],
+        dtype="string",
+        sep=";",
+    ).dropna()
+
+    df_p["Sero"] = df_p["Locus"] + df_p["A"]
+    df_p["Splits"] = df_p[["Locus", "Splits"]].apply(
+        lambda x: add_locus_name(x["Locus"], x["Splits"]), axis=1
+    )
+
+    sero_mapping = df_p[["Sero", "Splits"]].set_index("Sero")["Splits"].to_dict()
+    return sero_mapping

pyard/pyard.py

@@ -28,6 +28,7 @@
 
 from . import db
 from . import data_repository as dr
+from . import broad_splits
 from .smart_sort import smart_sort_comparator
 from .exceptions import InvalidAlleleError, InvalidMACError, InvalidTypingError
 from .misc import get_n_field_allele, get_2field_allele, expression_chars
@@ -119,6 +120,9 @@ def __init__(
         self.shortnulls = dr.generate_short_nulls(self.db_connection, self.who_group)
 
         # Load Serology mappings
+        broad_splits.broad_splits_ser_mapping = (
+            dr.generate_serology_broad_split_mapping(self.db_connection, imgt_version)
+        )
         dr.generate_serology_mapping(self.db_connection, imgt_version)
         # Load V2 to V3 mappings
         dr.generate_v2_to_v3_mapping(self.db_connection, imgt_version)

scripts/pyard

@@ -64,6 +64,7 @@ if __name__ == "__main__":
         dest="redux_type",
         help="Reduction Method",
     )
+    parser.add_argument("--splits", dest="splits", help="Find Broad and Splits")
 
     args = parser.parse_args()
 
@@ -78,5 +79,11 @@ if __name__ == "__main__":
         print(f"IPD-IMGT/HLA version:", version)
         sys.exit(0)
 
+    if args.splits:
+        mapping = pyard.find_broad_splits(args.splits)
+        if mapping:
+            print(f"{mapping[0]} = {'/'.join(mapping[1])}")
+        sys.exit(0)
+
     print(ard.redux_gl(args.gl_string, args.redux_type))
     del ard