DRAFT COPY
Geoffrey H. Smith, MD
August 1, 2018
geoffrey.smith@emory.edu
1. HLA-DPB1 Allele Difference Report
This project and the services it implements are for research use only.
This page describes an application programming interface (API) for an HLA-DPB1 allele compatibility prediction system. Compatibility predictions are based on considering recipient antibody reactivity to epitopes at six (6) hypervariable regions in the DPB1 protein [1-4].
The API is implemented as a set of REpresentational State Transfer (REST) web service endpoints. Reference implementations of HTML5 web applications that use the REST API are also provided. The source code for the API and the HTML5 applications is available in GitHub (https://github.com/ghsmith/hladpb1). The API is implemented using Java Enterprise Edition components and is deployed on a Java Application Server. To simplify application development, the REST API maintains some state at the level of the HTTP session, but no state is durably persisted across HTTP sessions.
Returns a JavaScript object notation (JSON) array of HLA-DPB1 alleles. Some filtering is supported using query parameters. Only codons 1-100 are returned.
| name | required | type | description | default | example |
|---|---|---|---|---|---|
| synonymous | no | boolean | If set to false, only the longest protein sequence allele of sets of synonymous alleles is returned. Allele order is based on the IMGT database. | true (i.e., no filtering) | synonymous=false |
| sab | no | boolean | If set to true, only alleles associated with single antigen beads (SAB) are returned. | false (i.e., no filtering) | sab=true |
| hvrMatchCount | no | int | If specified, only alleles with at least this many hypervariable regions matching the refeference allele are returned. | 0 (i.e., no filtering) | hvrMatchCount=4 |
| noCodons | no | boolean | If set to true, codons are not returned, which substantially reduces the JSON payload size. | false | noCodons=true |
GET /hladpb1/resources/alleles?synonymous=false&sab=true&hvrMatchCount=3
returns JSON allele array:
Returns a JSON representation of the allele identified by URL parameter {alleleName}. Only codons 1-100 are returned.
| name | required | type | description | default | example |
|---|---|---|---|---|---|
| noCodons | no | boolean | If set to true, codons are not returned, which substantially reduces the JSON payload size. | false | noCodons=true |
GET /hladpb1/resources/alleles/HLA-DPB1*01:01:01:01
returns JSON allele:
Updates the allele identified by the URL parameter {alleleName} on the server based on the JSON representation of the allele in the body of the request. The update only affects the allele in the HTTP session that is calling the method. This is intended to allow clients to update a limited number of clinically determined allele and hypervariable region properties related to an HLA-DPB1 compatibility evaluation. A JSON representation of an allele is presented in the previous example usage. A JSON representation of a hypervariable region is presented in the subsequent example usage. This method has no output.
| name | required | type | description | default | example |
|---|---|---|---|---|---|
| enumeratedAlleleMode | no | boolean | If set to true, use the enumerated allele properties (donorAlle1, donorAllele2, recipientAllele1, and recipientAllele2) and allow the system to automatically set donorTypeForCompat and recipientTypeForCompat for the compatiblity evaluation. When an enumerated allele property is set for an allele, it is automatically unset for all other alleles. This is intended for use by clients that maintain a distinction between recipient allele #1 and #2 and donor allele #1 and #2. Clients that don't care about this distinction should not use the enumeratedAlleleMode query parameter and just use the donorTypeForCompat and recipientTypeForCompat properties, which are usually easier to work with. | false | enumeratedAlleleMode=true |
| name | type | description | example |
|---|---|---|---|
| allele .referenceForMatches |
boolean |
If set to true, this is the reference allele for all
hypervariable region match properties (properties with
names starting with matches). When this property is
set for an allele, the property is unset for any other
allele (i.e., there can only be one reference allele) and
the following properties are automatically recomputed for
all alleles:
|
{... referenceForMatches: true, ...} |
| allele .recipientAntibodyForCompat |
boolean |
If set to true, designates the allele as reactive with a
recipient antibody, as a recipient type, or as a donor type
and used as the basis for all of the compatibility
properties (properties with names starting with
compat). When any of these properties are set for an
allele, the following properties are automatically
recomputed for all alleles and hypervariable region
variants:
|
{... recipientAntibodyForCompat: true, ...} |
| allele .recipientTypeForCompat |
boolean | {... recipientTypeForCompat: true, ...} |
|
| allele .donorTypeForCompat |
boolean | {... donorTypeForCompat: true, ...} |
|
| allele .recipientAllele1 |
boolean | The enumerated recipient and donor allele properties are only provided for the convenience of clients that need to keep track of which allele represents allele #1 and which allele represents allele #2. When one of these properties is set for an allele, it is concurrently unset for all other alleles (i.e., there can only be one allele #1 and one allele #2). | {... recipientAllele1: true, ...} |
| allele .recipientAllele2 |
boolean | {... recipientAllele2: true, ...} |
|
| allele .donorAllele1 |
boolean | {... donorAllele1: true, ...} |
|
| allele .donorAllele2 |
boolean | {... donorAllele2: true, ...} |
Returns a JavaScript object notation (JSON) array of HLA-DPB1 hypervariable regions. This method takes no parameters
GET /hladpb1/resources/hypervariableRegions
returns JSON hypervariableRegion array:
Returns a JSON representation of the hypervariable region identified by URL parameter {hypervariableRegionName}. This method takes no parameters.
GET /hladpb1/resources/hypervariableRegions/f
returns JSON hypervariableRegion array:
Updates the hypervariable region identified by the URL parameter {hypervariableRegionName} on the server based on the JSON representation of the hypervariableRegion in the body of the request. The update only affects the hypervariable region in the HTTP session that is calling the method. This is intended to allow clients to update a limited number of clinically determined allele and hypervariable region properties related to an HLA-DPB1 compatibility evaluation. A JSON representation of a hypervariable region is presented in the previous example usage. A JSON representation of an allele is presented in the GET /hladpb1/resources/alleles/{alleleName} section. This method takes no parameters and has no output.
| name | type | description | example |
|---|---|---|---|
| hypervariableRegion .variantMap{} .knownReactiveEpitopeForCompat |
boolean |
If set to true, the recipient is assumed to have an antibody
reactive with the epitope regardless of all other
considerations and used as a basis for all of the
compatibility properties (properties with names starting
with compat). When this property is set for a
hypervariable region variant, the following properties are
automatically recomputed for all alleles and hypervariable
region variants:
|
{... knownReactiveEpitopeForCompat: true, ...} |
Returns a JSON representation of the current single antigen bead reagent lot number (each hypervariable region variant is associated with a set of single antigen beads). The reagent lot number is currently administratively specified. This method takes no parameters.
GET /hladpb1/resources/hypervariableRegions/reagentLotNumber
returns JSON reagentLotNumber:
Returns a JSON representation of the current session ID. All changes (e.g., clinical information such as antibody profile) are persisted in the session and are disposed of when the session ends. Sessions automatically time out after 30 minutes. This method takes no parameters.
GET /hladpb1/resources/session
returns JSON sessionId:
End the current session. All changes are immediately disposed. This request has no payload.
These applications demonstrate how the HLA-DPB1 REST API may be used to prognosticate about HLA-DPB1 donor/recipient compatibility. They are presented in order of increasing complexity. Although these applications have some utility in their own right, they are mainly intended to serve as a guide to software engineers seeking to use the HLA-DPB1 REST API in a larger system, such as in a specialty HLA laboratory information system or in a clinical decision support module of an electronic medical record system.
For a given HLA-DPB1 reference allele, this highly interactive report sorts all other HLA-DPB1 alleles from most similar to least similar based on hypervariable region epitopes. This is the most basic usage of the HLA-DPB1 REST API. The report is implemented as an HTML5 web page that uses the jQuery asynchronous JavaScript and XML (AJAX) API to access the HLA-DPB1 REST endpoints described above.
Source code: https://github.com/ghsmith/hladpb1/blob/master/hladpb1-webServices/src/main/webapp/ajaxDifferenceReportPaginated.html
Same as above, but without codons. This version works better on devices that have smaller displays, limited bandwidth, or slower graphics rendering.
Source code: https://github.com/ghsmith/hladpb1/blob/master/hladpb1-webServices/src/main/webapp/ajaxDifferenceReportNoCodons.html
This highly interactive report makes donor/recipient compatibility predictions based on the donor/recipient HLA-DPB1 types and the recipient antibody profile (SAB positivity and/or known reactivity to particular hypervarible epitopes). The report is implemented as a single HTML5 web application that uses the jQuery AJAX API to access the HLA-DPB1 REST endpoints.
Same as above, but without hypervariable regions. This version works better on devices that have smaller displays, limited bandwidth, or slower graphics rendering.
Source code: https://github.com/ghsmith/hladpb1/blob/master/hladpb1-webServices/src/main/webapp/ajaxCompatibilityReportNoHvrs.html
This wizard makes donor/recipient compatibility predictions based on the donor/recipient HLA-DPB1 types and the recipient antibody profile (SAB positivity and/or known reactivity to particular hypervarible epitopes). The wizard is implemented as a static HTML5 web page that uses the jQuery AJAX API to access the HLA-DPB1 REST endpoints and jQuery Mobile user interface components.
Source code: https://github.com/ghsmith/hladpb1/blob/master/hladpb1-webServices/src/main/webapp/ajaxMobileCompatibilityWizard.html
[1] Billen, E. V., Christiaans, M. H., Doxiadis, I. I., Voorter, C. E., & Berg-Loonen, E. M. (2010). HLA-DP antibodies before and after renal transplantation. Tissue Antigens, 75(3), 278-285.
[2] Piazza, A., Poggi, E., Ozzella, G., Borrelli, L., Scornajenghi, K., Monaco, P., Tisone, G., & Adorno, D. (2006). Anti Hla-Dp Antibodies And Graft Failure In Kidney Transplantation. Transplantation, 82(Suppl 2), 242.
[3] Arnold, M., Pei, R., Spriewald, B., & Wassmuth, R. (2005). Anti-HLA class II antibodies in kidney retransplant patients. Tissue Antigens, 65(4), 370-378.
[4] Laux, G., Mansmann, U., Deufel, A., Opelz, G., & Mytilineos, J. (2003). A new epitope-based HLA-DPB matching approach for cadaver kidney retransplants. Transplantation, 75(9), 1527-1532.
Copyright © 2018, Geoffrey H. Smith, MD