Mac UI Usage Instructions

Welcome to the MAC Service UI!

The MAC Service encodes MACs from compressed allele lists (CAL) and GL strings. The service can be called programmatically or with this user interface. For more information on calling it programmatically please contact new-allelecodes@nmdp.org.

The interface has four functions. Encoding MACS; finding MACs without encoding the list if there isn’t a MAC assigned yet; decoding, or finding, the allele list for a MAC and expanding the allele list for a MAC into all possible alleles.

Definitions and instructions for using these functions are provided below.

Questions? Please contact new-allelecodes@nmdp.org.

Enjoy!

Logging in

Look up, Decode, and Expand functions are available without logging in. You must provide an email address and login if you would like to Encode a MAC.

Instructions

Look up an allele list to find a MAC without encoding a new MAC

  1. Select IMGT HLA DB Release. Choose the version number of the IMGT allele database release that was used for the allele list generated. If you don’t know, use the highest release number.
  2. Enter between 1 - 50 CALs or GL strings into the Encode Input box. Each CAL or GL string must be on its own line. The UI will assign a number to the CAL or GL string. This number will be used in the Encode Result box to link the request list and MAC together.
  3. Click the Look Up button. It will return all MAC designations for the CALs or GL strings entered but will not assign a new MAC.
  4. The MAC designation results will be displayed in the Encode Result box.

Encode a new MAC with an allele list

  1. Select IMGT HLA DB Release. Choose the version number of the IMGT allele database release that was used for the allele list generated. If you don’t know, use the highest release number.
  2. Enter between 1 - 50 CALs or GL strings into the Encode Input box. Each CAL or GL string must be on its own line. The UI will assign a number to the CAL or GL string. This number will be used in the Encode Result box to link the request list and MAC together.
  3. Click the Encode button. It will return all MAC designations for the CALs or GL strings entered. It will assign a new MAC designation when necessary.
  4. The results will be displayed in the Encode Result box.

Decode a MAC to find its allele list

Important note – this function does not test for allele validity. It simply decodes the MAC with the locus and allele-family provided.

  1. Select IMGT HLA DB Release. Choose the IMGT allele database release number. If you have no preference use the most current version.
  2. Enter a MAC designation into the MAC designation look up box. HLA- may be prepended to the MAC designation.
  3. Click the Decode button.
  4. The results will be displayed in the Decode Result box.

Expand a MAC to find all possible alleles represented by this MAC

  1. Select IMGT HLA DB Release. Choose the IMGT allele database release number. If you have no preference use the most current version.
  2. Enter a MAC designation into the MAC designation look up box. HLA- may be prepended to the MAC designation.
  3. Click the Expand button.
  4. The results will be displayed in the Expand Result box.

Definitions

CAL (Compressed Allele List) An allele list short-hand. Used frequently when creating MACs. The locus is used only once.

Examples
B*40:01/40:07/40:10/40:16
B*57:17/57:57

Decode Provides the allele list for a MAC at the given locus and allele-family. This function does not test for allele validity.

Decode Result The results of a MAC designation decode will be displayed here.

Encode Use this button to find the MAC designation for a CAL or GL string. If a MAC has not yet been assigned to the list this action will automatically create one.

Encode Input Enter a CAL or GL string here to look up or encode a MAC. A number will be added to the request to connect it to the results.

Encode Result The results of a CAL or GL string look up or encode will be displayed in this box. The number listed here connects these results to the number of the request in the Encode Input box.

Expand Provides all of the alleles that could be represented by the MAC designation in the database version selected. Full allele names are shown.

Expand Result The results of a MAC designation expand will be displayed here.

GL string (Genotype list string) A machine readable method for transmitting allelic typing results that is an improvement over MACs. In addition to allowing allele ambiguities to be represented it allows allele pairing information to be retained. The full allele name with locus must be used. GL strings can be used with Gene Systems other than HLA.
Read more here: http://www.ncbi.nlm.nih.gov/pmc/articles/PMC3715123/

Example:

Testing result

Allele 1 Allele 2
B*57:17 B*40:01
B*40:07
B*40:10
B*40:16
B*57:57 B*40:09
B*40:10
GL String
B*57:17+B*40:01/B*40:07/B*40:10/B*40:16|B*57:57+B*40:09/B*40:10
or
HLA-B*57:17+ HLA-B*40:01/ HLA-B*40:07/ HLA-B*40:10/ HLA-B*40:16| HLA-B*57:57+ HLA-B*40:09/ HLA-B*40:10

IMGT HLA DB Release The quarterly release of new HLA allele names. The most recent 5 database releases are available for creating MACs. The selection chosen in this box applies to all functions available on the MAC Service UI. More information can be found here: https://www.ebi.ac.uk/ipd/imgt/hla/.

Look up Use this button to find the MAC designation for a CAL or GL string. A MAC will not be automatically created if it doesn’t exist.

MAC (Multiple Allele Code) A combination of letters assigned to a list of alleles from an HLA typing result. The MAC system is used to compress large lists of alleles generated from HLA typing into a smaller size for display on computers and paper.

Examples
HA01/07/10/16
DUKU31:01/31:14N/31:23

MAC designation An allele code used at a specific locus and allele-family.

Examples
DRB1*04:HA DRB1*04:01/DRB1*04:07/DRB1*04:10/DRB1*04:16
B*40:HA B*40:01/B*40:07/B*40:10/B*40:16
A*31:DUKU A*31:01/A*31:14N/A*31:23

MAC designation look up Enter a MAC designation here to see its allele list.

Error Messages

Deleted or renamed alleles
If you receive an “Invalid allele” error message for an allele you know is correct check your database version. The allele can only be used in a database version in which it was not deleted or renamed. Deleted or renamed alleles are allowed to be used in the creation of new MACs for 1 year after the database release they were renamed in.

Look up and Encode result

Bad allele string The characters provided are not a properly formatted GL String or MAC.

Source string may not be null Typically, this means there’s a blank line.

Invalid allele “[Bad allele]’ at [##] The characters listed are not recognized as a valid allele name.

  • Check for any unintentional characters.
  • If you know the allele name to be correct make sure it has not been deleted or renamed in the database version selected.
  • The locus must be provided on only the first allele, or all of the alleles in the input.

Decode and Expand result

Incorrect format detected The MAC entered is not recognized.

  • Make sure the locus is correct.
  • The input must begin with a locus or HLA-[MAC designation]

Returns MAC designation that was used as an input If a the letters are not a valid MAC the MAC designation that was entered in the look up will appear in the Decode Result box.