DRAFT COPY
Geoffrey H. Smith, MD
September 1, 2018
[email protected]
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 epitope reactivity prediction system that uses epitopes defined by the HLA Epitope Registry [1]. Compatibility predictions are based on identifying HLA Epitope Registry epitopes where all of the single antigen beads bearing the epitope are positive in a defined single antigen bead panel.
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/epitopeFinder). 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 alleles in the IMGT database corresponding to the HLA Epitope Registry locus groups ABC (HLA-A, B, C), DRB (HLA-DRB1, 2, 3, 4, & 5), DQ (HLA-DQB1 & A1), and DP (HLA-DPB1 & A1). Only the first allele in the IMGT database corresponding to a set of synonymous alleles is returned.
| name | required | type | description | default | example |
|---|---|---|---|---|---|
| locusGroup | no | String | Only return alleles in the HLA Epitope Registry locus group (ABC, DRB, DQ, DP). | none | locusGroup=ABC |
| startSequenceNumber | no | int | Alleles are sorted as they are in the IMGT database. Only alleles with a zero-based index greater than or equal to this number are returned. | none | startSequenceNumber=0 |
| endSequenceNumber | no | int | Alleles are sorted as they are in the IMGT database. Only alleles with a zero-based index less than this number are returned. | none | endSequenceNumber=10 |
GET /epitopeFinder/resources/alleles?startSequenceNumber=0&endSequenceNumber=10
returns JSON allele array:
Returns a JSON representation of the allele identified by URL parameter {alleleName}. If the allele name can't be resolved as an full IMGT allele names (e.g., HLA-A*01:01:01:01), the system will try to resolve it as an HLA Epitope Registry allele name (e.g., A*01:01).
GET /epitopeFinder/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.
| name | type | description | example |
|---|---|---|---|
| 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).
The following properties are automatically
recomputed for all alleles and epitopes based on the values
of the various ...ForCompat properties:
|
{... recipientAntibodyForCompat: true, ...} |
| allele .recipientTypeForCompat |
boolean | {... recipientTypeForCompat: true, ...} |
|
| allele .donorTypeForCompat |
boolean | {... donorTypeForCompat: true, ...} |
Returns a JSON array of HLA Epitope Registry epitopes.
| name | required | type | description | default | example |
|---|---|---|---|---|---|
| panelAllelesOnly | no | boolean | Only return alleles associated with the epitope that are part of a single antigen bead panel. | false | panelAllelesOnly=true |
| startSequenceNumber | no | int | Epitopes are sorted as they are in the HLA Epitope Registry database. Only epitopes with a zero-based index greater than or equal to this number are returned. | none | startSequenceNumber=0 |
| endSequenceNumber | no | int | Epitopes are sorted as they are in the HLA Epitope Registry database. Only epitopes with a zero-based index greater than this number are returned. | none | endSequenceNumber=10 |
GET /epitopeFinder/resources/epRegEpitopes?panelAllelesOnly=true&startSequenceNumber=0&endSequenceNumber=10
returns JSON epitope array:
Returns a JSON array of HLA Epitope Registry epitopes in the HLA Epitope Registry locus group (ABC, DRB, DQ, DP) identified by the URL parameter {locusGroup}.
| name | required | type | description | default | example |
|---|---|---|---|---|---|
| panelAllelesOnly | no | boolean | Only return alleles associated with the epitope that are part of a single antigen bead panel. | false | panelAllelesOnly=true |
| startSequenceNumber | no | int | Epitopes are sorted as they are in the HLA Epitope Registry database. Only epitopes with a zero-based index greater than or equal to this number are returned. | none | startSequenceNumber=0 |
| endSequenceNumber | no | int | Epitopes are sorted as they are in the HLA Epitope Registry database. Only epitopes with a zero-based index greater than this number are returned. | none | endSequenceNumber=10 |
GET /epitopeFinder/resources/epRegEpitopes/ABC?panelAllelesOnly=true&startSequenceNumber=0&endSequenceNumber=10
returns JSON epitope array:
Returns a JSON HLA Epitope Registry epitope identified by the HLA Epitope Registry locus group (ABC, DRB, DQ, DP) {locusGroup} and the epitope name {epitopeName}.
| name | required | type | description | default | example |
|---|---|---|---|---|---|
| panelAllelesOnly | no | boolean | Only return alleles associated with the epitope that are part of a single antigen bead panel. | false | panelAllelesOnly=true |
GET /epitopeFinder/resources/epRegEpitopes/ABC/62GE?panelAllelesOnly=true
returns JSON epitope:
Returns a JSON array of single antigen bead panels representing the currently active panels. Currently, these panels are administratively specified, although in a more complete implementation the API will allow the panels to be specified by the client.
GET /epitopeFinder/resources/sabPanels
returns JSON single antigen bead panel array:
Returns a JSON representation of the single antigen bead panel identified by the HLA Epitope Registry locus group (ABC, DRB, DQ, DP) {locusGroup}.
GET /epitopeFinder/resources/sabPanels/ABC
returns JSON single antigen bead panel:
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 /epitopeFinder/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 Epitope Finder REST API may be used to prognosticate about HLA 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 Epitope Finder 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.
This report shows the single antigen beads associated with recipient epitopes and characterizes them as present (positive), absent (negative), or unknown (not in the current single antigen bead panel).
Source code: https://github.com/ghsmith/epitopeFinder/blob/master/epitopeFinder-webServices/src/main/webapp/ajaxEpitopeReport.html
This report makes donor/recipient compatibility predictions based on inferred antibody reactivity to epitopes.
Same as above, but without epitopes. This version works better on devices that have smaller displays, limited bandwidth, or slower graphics rendering.
[1] Duquesnoy, R. J., Marrari, M., Mulder, A., L. C. D. Da Mata Sousa, Silva, A. S., & Monte, S. J. (2014). First report on the antibody verification of HLA-ABC epitopes recorded in the website-based HLA Epitope Registry. Tissue Antigens, 83(6), 391-400.
Copyright © 2018, Geoffrey H. Smith, MD