Decode MAC and CWD 2.0 Reductions (#224)

* Supports Decoding to MAC code from allele list

* exclude tests for distribution

* CWD Reduction
 - add `cwd_redux` method to produce CWD only allele list
 - create `cwd2` table on load
 - `cwd-redux` endpoint to allow CWD reduction

* Bump version to 1.0.0rc5

* Set the sample files name the same as remote.

* Documentation on CWD changes

* Make P,G group alleles explicit lookups.

* - renamed method to `lookup_mac` to align with terminology
- Updated README with links to MacUI
- Fixed api verbage

* Allow P group in `redux` REST endpoint

Author: pbashyal-nmdp

Dockerfile

@@ -4,7 +4,7 @@ LABEL MAINTAINER="Pradeep Bashyal"
 
 WORKDIR /app
 
-ARG PY_ARD_VERSION=1.0.0rc4
+ARG PY_ARD_VERSION=1.0.0rc5
 
 COPY requirements.txt /app
 RUN pip install --no-cache-dir --upgrade pip && \

MANIFEST.in

@@ -6,7 +6,7 @@ include LICENSE
 include README.rst
 include pyard/*.csv
 
-recursive-include tests *
+recursive-exclude tests *
 recursive-exclude * __pycache__
 recursive-exclude * *.py[co]
 

README.md

@@ -21,6 +21,7 @@ Human leukocyte antigen (HLA) genes encode cell surface proteins that are import
     * [Using `py-ard` from R](#using-py-ard-from-r-code)
     * [Perform Reduxtion](#reduce-typings)
     * [DRBX blending](#perform-drb1-blending-with-drb3-drb4-and-drb5)
+    * [Expand/Lookup MAC](#mac-codes)
 3. [Command Line Tools](#command-line-tools)
     * [`pyard-import` Import Reference Data](#pyard-import-import-the-latest-ipd-imgthla-database)
     * [`pyard-status` Show Statuses of Databases](#pyard-status-show-database-status)
@@ -183,12 +184,41 @@ pyard.dr_blender(drb1='HLA-DRB1*03:01+DRB1*04:01', drb3='DRB3*01:01', drb4='DRB4
 # >>> 'DRB3*01:01+DRB4*01:03'
 ```
 
-### Expand MAC codes
+## MAC Codes
+
+`py-ard` supports not only reducing to various types but helps in expanding and
+looking up MAC representation. See [MAC Service UI](https://hml.nmdp.org/MacUI/) for detail.
+
+### Expand MAC
 
 You can also use `py-ard` to expand MAC codes. Use `expand_mac` method on `ard`.
 ```python
 ard.expand_mac('HLA-A*01:BC')
-# ['HLA-A*01:02', 'HLA-A*01:03']
+# 'HLA-A*01:02/HLA-A*01:03'
+```
+
+### Lookup MAC
+
+Find the corresponding MAC code for an allele list GL String.
+
+```python
+ard.lookup_mac('A*01:02/A*01:01/A*01:03')
+# A*01:MN
+```
+
+### CWD Reduction
+
+Reduce a MAC code or an allele list GL String to CWD reduced list.
+```python
+ard.cwd_redux("B*15:01:01/B*15:01:03/B*15:04/B*15:07/B*15:26N/B*15:27")
+# => B*15:01/B*15:07
+```
+
+The above 2 methods can be chained to get back a MAC code that has a CWD reduced version.
+
+```python
+ard.lookup_mac(ard.cwd_redux("B*15:01:01/B*15:01:03/B*15:04/B*15:07/B*15:26N/B*15:27"))
+# 'B*15:AH'
 ```
 
 ### Using `py-ard` from R code

api-spec.yaml

@@ -2,16 +2,16 @@ openapi: 3.0.3
 info:
   title: ARD Reduction
   description: Reduce to ARD Level
-  version: "1.0.0rc4"
+  version: "1.0.0rc5"
 servers:
   - url: 'http://localhost:8080'
 tags:
   - name: Database
     description: IPD-IMGT/HLA DB Information
   - name: ARD Reduction
     description: Reduce GL String to ARD
-  - name: MAC Expansion
-    description: Expand MAC to alleles
+  - name: MAC
+    description: Expand/Collapse MAC to/from alleles
   - name: DRBX Blender
     description: Blend DRBX based on DRB1 and DRB3/4/5
   - name: Validation
@@ -55,6 +55,7 @@ paths:
                   type: string
                   enum:
                     - G
+                    - P
                     - lg
                     - lgx
                     - W
@@ -84,10 +85,59 @@ paths:
                     description: Describes what went wrong
                     type: string
                     example: "Invalid HLA locus"
+  /cwd-redux:
+    post:
+      tags:
+        - CWD Reduction
+      operationId: api.cwd_redux_controller
+      summary: Reduce to CWD/MAC
+      description: |
+        Given a GL String of Allele List or a MAC find only the CWD alleles and a corresponding
+        MAC if available.
+      requestBody:
+        content:
+          application/json:
+            schema:
+              properties:
+                gl_string:
+                  description: GL String of Allele List or a MAC code
+                  type: string
+                  example: "A*26:CBJTR"
+      responses:
+        200:
+          description: CWD Result
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  gl_string:
+                    description: GL String of Allele List or a MAC code
+                    type: string
+                    example: "A*26:CBJTR"
+                  cwd:
+                    description: CWD reduced version of GL String
+                    type: string
+                    example: "A*26:01/A*25:01"
+                  cwd_mac:
+                    description: MAC of reduced CWD if available
+                    type: string
+                    example: "A*26:BYHR"
+        400:
+          description: Invalid GL String Form
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  message:
+                    description: Describes what went wrong
+                    type: string
+                    example: "Invalid HLA locus"
   /mac/{allele_code}:
     get:
       tags:
-        - MAC Expansion
+        - MAC
       operationId: api.mac_expand_controller
       summary: Expand MAC (Allele Code)
       description: |
@@ -116,7 +166,57 @@ paths:
                     description: GL String version of expanded MAC
                     type: string
                     example: "HLA-A*01:01/HLA-A*01:02"
-                  expansion:
+                  alleles:
+                    description: Alleles corresponding to MAC
+                    type: array
+                    example:
+                      - "HLA-A*01:01"
+                      - "HLA-A*01:02"
+        400:
+          description: Invalid MAC Code
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  message:
+                    description: MAC Code is not valid
+                    type: string
+                    example: "Invalid MAC Code"
+  /mac:
+    post:
+      tags:
+        - MAC
+      operationId: api.mac_lookup_controller
+      summary: Lookup MAC from Alleles
+      description: |
+        Given a allele list as a GL String, find corresponding MAC
+      requestBody:
+        content:
+          application/json:
+            schema:
+              properties:
+                gl_string:
+                  description: GL String version of allele list
+                  type: string
+                  example: "HLA-A*01:01/HLA-A*01:02"
+      responses:
+        200:
+          description: MAC corresponding to Alleles
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  mac:
+                    description: MAC
+                    type: string
+                    example: "HLA-A*01:AB"
+                  gl_string:
+                    description: Supplied GL String
+                    type: string
+                    example: "HLA-A*01:01/HLA-A*01:02"
+                  alleles:
                     description: Alleles corresponding to MAC
                     type: array
                     example:

api.py

@@ -53,18 +53,32 @@ def redux_controller():
 def mac_expand_controller(allele_code: str):
     try:
         if ard.is_mac(allele_code):
-            alleles = ard.expand_mac(allele_code)
+            allele_list = ard.expand_mac(allele_code)
             return {
                 "mac": allele_code,
-                "alleles": alleles,
-                "gl_string": "/".join(alleles),
+                "alleles": allele_list.split("/"),
+                "gl_string": allele_list,
             }, 200
         else:
             return {"message": f"{allele_code} is not a valid MAC"}, 404
     except PyArdError as e:
         return {"message": e.message}, 400
 
 
+def mac_lookup_controller():
+    if request.json:
+        try:
+            allele_list = request.json["gl_string"]
+            mac_code = ard.lookup_mac(allele_list)
+            return {
+                "mac": mac_code,
+                "alleles": allele_list.split("/"),
+                "gl_string": allele_list,
+            }, 200
+        except PyArdError as e:
+            return {"message": e.message}, 400
+
+
 def drbx_blender_controller():
     if request.json:
         try:
@@ -93,3 +107,31 @@ def splits_controller(allele: str):
         return {"broad": mapping[0], "splits": mapping[1]}, 200
 
     return {"message": f"No Broad/Splits matched {allele}"}, 404
+
+
+def cwd_redux_controller():
+    if request.json:
+        # Check the request has required inputs
+        try:
+            gl_string = request.json["gl_string"]
+        except KeyError:
+            return {"message": "gl_string and reduction_method not provided"}, 404
+        # Perform redux
+        try:
+            cwd = ard.cwd_redux(ard.redux(gl_string, "lgx"))
+        except PyArdError as e:
+            return {"message": e.message}, 400
+
+        # If the cwd reduction is a single locus or empty
+        if "/" in cwd:
+            try:
+                cwd_mac = ard.lookup_mac(cwd)
+            except pyard.exceptions.InvalidMACError as e:
+                cwd_mac = ""
+        else:
+            cwd_mac = ""
+
+        return {"gl_string": gl_string, "cwd": cwd, "cwd_mac": cwd_mac}, 200
+
+    # if no data is sent
+    return {"message": "No input data provided"}, 404