Guides › IPD-IMGT/HLA releases

How to find what changed between two IPD-IMGT/HLA releases

Updated 2026-10-30 · allele examples checked against IPD-IMGT/HLA 3.66.0 on 2026-10-30

To see what changed between two IPD-IMGT/HLA releases, compare the two releases' columns in Allelelist_history.txt, row by row, keyed on the HLA ID. An ID that has a name only in the newer release was added, one that has a name only in the older release was removed, and one whose name differs was renamed.

Comparing two allele lists as plain sets of names does not work. A renamed allele shows up as one name "removed" and another "added", and you lose the fact that it is the same sequence.

What changed from 3.65.0 to 3.66.0

Computed from Allelelist_history.txt in release 3.66.0:

Of the 24 renames, 22 were existing alleles that gained one or more fields because a close relative was named, for example B*40:12:01 becoming B*40:12:01:01, A*01:284 becoming A*01:284:01, and C*14:21N becoming C*14:21:01N. A*03:534 gained two fields at once and became A*03:534:01:01. One allele lost a suffix (A*02:01:14Q became A*02:01:14) and one moved to a different allele group (DQA1*01:209N became DQA1*03:100N).

The previous quarter, 3.64.0 to 3.65.0, had 647 additions, no removals and 25 renames by the same method.

Why the HLA ID is the key

The IPD-IMGT/HLA README describes Allelelist_history.txt as "a csv file detailing for each allele the official name used in each release of the database". Each row is one HLA ID, such as HLA02908; each column after the first is a release, written without dots and newest first (3660, 3650, and so on back to 1050). A release in which the ID had no name holds NA.

In release 3.66.0 the file has 111 release columns, from 1.05.0 to 3.66.0. Because the ID is stable, a row reads as one allele's naming history: HLA02908 is A*02:01:14 in 3.00.0 to 3.03.0, A*02:01:14Q in 3.04.0 to 3.65.0, and A*02:01:14 again in 3.66.0.

The same README says a release number has three parts: the nomenclature version, the quarterly release and the sequence version. So 3660 in the header is release 3.66.0.

Compare two releases step by step

1. Download Allelelist_history.txt from the newer of the two releases. It contains every earlier release as a column, so one file is enough.
2. Skip the header lines that start with #, then read the file as CSV with the HLA_ID column as the key.
3. For each row, read the two release columns you are comparing and treat NA as no name.
4. Classify each row: name only in the newer column is added; only in the older column is removed; different in both is renamed; identical is unchanged.
5. For renamed and removed rows, look the old name up in Deleted_alleles.txt to get the recorded reason.
6. Record which release's history file you used, so the comparison can be reproduced.

The same comparison in Python

This is the code used for the counts above. It needs only the standard library.

import csv

def release_diff(path, old, new):
    """Compare two release columns of Allelelist_history.txt, e.g. "3650" and "3660"."""
    with open(path, encoding="utf-8") as fh:
        rows = csv.DictReader(line for line in fh if not line.startswith("#"))
        added, removed, renamed = [], [], []
        for row in rows:
            a, b = row[old], row[new]
            a = None if a == "NA" else a
            b = None if b == "NA" else b
            if b and not a:
                added.append((row["HLA_ID"], b))
            elif a and not b:
                removed.append((row["HLA_ID"], a))
            elif a and b and a != b:
                renamed.append((row["HLA_ID"], a, b))
    return added, removed, renamed

added, removed, renamed = release_diff("Allelelist_history.txt", "3650", "3660")
print(len(added), len(removed), len(renamed))   # 772 0 24 for the 3.66.0 file

To restrict the comparison to one locus, filter on the part of the name before the *. To compare releases that are years apart, pass their columns directly; there is no need to step through the releases in between, although doing so shows when each change happened.

What the diff does not tell you

• Why a name changed. The reason is in Deleted_alleles.txt for suffix changes, group moves and deletions. The four 3.66.0 field additions checked above (A*01:284, B*40:12:01, A*03:534, C*14:21N) have no entry in that file; a field is added because a close relative was named.
• Group changes. G and P groups are recalculated every release from the sequences. Group membership can therefore change without any allele name changing. Compare hla_nom_g.txt and hla_nom_p.txt between releases for that.
• Sequence changes without a name change. The README lists sversion_history.txt, which records each allele's sequence version per release.

The same answer from the API

GET /v1/releases/diff?from=3.65.0&to=3.66.0 returns the added, removed and renamed names between any two releases in the history, optionally for one locus with &locus=A. For 3.65.0 to 3.66.0 it reports 772 added, 0 removed and 24 renamed, the same as the file comparison. POST /v1/translate answers the narrower question "what are these particular stored names called now".

What changed at each move of HLA-Verify's own release pin is listed at /releases. For the kinds of change behind a rename, see IPD-IMGT/HLA releases and why names change and deleted alleles and their successors.

Frequently asked questions

How many alleles were added in IPD-IMGT/HLA 3.66.0?

Compared with 3.65.0, 772 HLA IDs gained a name in 3.66.0, none lost one and 24 were renamed, according to Allelelist_history.txt in release 3.66.0.

Can I compare two releases by diffing Allelelist.txt?

Only for additions you can afford to misread. A renamed allele appears as one removal and one addition, so compare by HLA ID using Allelelist_history.txt instead.

What does NA mean in Allelelist_history.txt?

That the HLA ID had no name in that release, usually because the allele had not yet been named.

Do I need every release in between to compare two releases?

No. The history file in the newer release has a column for every release back to 1.05.0, so any two columns can be compared directly.