Skip to content

immunum

immunum.Annotator

Annotates antibody and T-cell receptor sequences with IMGT or Kabat position numbers.

Parameters:

Name Type Description Default
chains list[str]

Chain types to consider during auto-detection. Each entry is a case-insensitive string. Accepted values:

  • Antibody heavy chain: "IGH" / "H" / "heavy"
  • Antibody kappa chain: "IGK" / "K" / "kappa"
  • Antibody lambda chain: "IGL" / "L" / "lambda"
  • TCR alpha chain: "TRA" / "A" / "alpha"
  • TCR beta chain: "TRB" / "B" / "beta"
  • TCR gamma chain: "TRG" / "G" / "gamma"
  • TCR delta chain: "TRD" / "D" / "delta"

Pass all chains you want to consider; the annotator scores each and picks the best-matching one. To consider every supported chain pass all seven values.

 required
scheme str

Numbering scheme to use for output positions. Accepted values (case-insensitive):

  • "IMGT" / "i" — IMGT numbering (recommended; used internally)
  • "Kabat" / "k" — Kabat numbering (derived from IMGT)

Note: Kabat is only supported for antibody chains (IGH, IGK, IGL).

 required
min_confidence float | None

Minimum alignment confidence threshold in the range [0, 1]. Sequences scoring below this value raise a ValueError. Defaults to 0.5, which filters non-immunoglobulin sequences while retaining all validated antibody sequences. Pass 0.0 to disable filtering.

 None
Source code in immunum/__init__.py 
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
class Annotator:
    """Annotates antibody and T-cell receptor sequences with IMGT or Kabat position numbers.

    Args:
        chains: Chain types to consider during auto-detection. Each entry is a
            case-insensitive string. Accepted values:

            - Antibody heavy chain: ``"IGH"`` / ``"H"`` / ``"heavy"``
            - Antibody kappa chain: ``"IGK"`` / ``"K"`` / ``"kappa"``
            - Antibody lambda chain: ``"IGL"`` / ``"L"`` / ``"lambda"``
            - TCR alpha chain:       ``"TRA"`` / ``"A"`` / ``"alpha"``
            - TCR beta chain:        ``"TRB"`` / ``"B"`` / ``"beta"``
            - TCR gamma chain:       ``"TRG"`` / ``"G"`` / ``"gamma"``
            - TCR delta chain:       ``"TRD"`` / ``"D"`` / ``"delta"``

            Pass all chains you want to consider; the annotator scores each and picks the
            best-matching one. To consider every supported chain pass all seven values.

        scheme: Numbering scheme to use for output positions. Accepted values
            (case-insensitive):

            - ``"IMGT"`` / ``"i"`` — IMGT numbering (recommended; used internally)
            - ``"Kabat"`` / ``"k"`` — Kabat numbering (derived from IMGT)

            Note: Kabat is only supported for antibody chains (IGH, IGK, IGL).

        min_confidence: Minimum alignment confidence threshold in the range ``[0, 1]``.
            Sequences scoring below this value raise a ``ValueError``. Defaults to
            ``0.5``, which filters non-immunoglobulin sequences while retaining all
            validated antibody sequences. Pass ``0.0`` to disable filtering.
    """

    def __init__(
        self,
        chains: list[str],
        scheme: str,
        min_confidence: float | None = None,
    ):
        """Create an Annotator.

        Args:
            chains: Chain types to consider. See class docstring for accepted values.
            scheme: Numbering scheme — ``"imgt"`` (default) or ``"kabat"``.
            min_confidence: Reject sequences with alignment confidence below this
                threshold. Defaults to ``0.5``; pass ``0.0`` to disable.

        Raises:
            ValueError: If any chain or scheme value is unrecognised, if Kabat is
                requested for TCR chains, or if ``min_confidence`` is outside ``[0, 1]``.
        """
        if min_confidence is not None and not (0 <= min_confidence <= 1.0):
            raise ValueError(
                f"min_confidence should be in [0, 1], got {min_confidence=}"
            )
        self._annotator = _Annotator(
            chains=_normalize_chains(chains),
            scheme=_normalize_scheme(scheme),
            min_confidence=min_confidence,
        )

    def number(self, sequence: str) -> NumberingResult:
        """Assign IMGT or Kabat position numbers to every residue in a sequence.

        Args:
            sequence: Amino-acid sequence string (single-letter codes).

        Returns:
            A `NumberingResult` with the detected chain, scheme, confidence score,
            and a ``{position: residue}`` numbering dict. On failure, ``error`` is
            set and all other fields are ``None``.
        """
        return NumberingResult(**self._annotator.number(sequence))

    def segment(self, sequence: str) -> SegmenationResult:
        """Split a sequence into FR/CDR regions.

        Args:
            sequence: Amino-acid sequence string (single-letter codes).

        Returns:
            A `SegmenationResult` with ``fr1``–``fr4``, ``cdr1``–``cdr3``,
            and any unaligned ``prefix``/``postfix`` residues. On failure,
            ``error`` is set and all region fields are ``None``.
        """
        raw = self._annotator.segment(sequence)
        return SegmenationResult(
            fr1=raw.get("fr1"),
            cdr1=raw.get("cdr1"),
            fr2=raw.get("fr2"),
            cdr2=raw.get("cdr2"),
            fr3=raw.get("fr3"),
            cdr3=raw.get("cdr3"),
            fr4=raw.get("fr4"),
            prefix=raw.get("prefix"),
            postfix=raw.get("postfix"),
            error=raw.get("error"),
        )

_annotator instance-attribute

__init__(chains, scheme, min_confidence=None)

Create an Annotator.

Parameters:

Name Type Description Default
chains list[str]

Chain types to consider. See class docstring for accepted values.

 required
scheme str

Numbering scheme — "imgt" (default) or "kabat".

 required
min_confidence float | None

Reject sequences with alignment confidence below this threshold. Defaults to 0.5; pass 0.0 to disable.

 None

Raises:

Type Description
ValueError

If any chain or scheme value is unrecognised, if Kabat is requested for TCR chains, or if min_confidence is outside [0, 1].
Source code in immunum/__init__.py 
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
def __init__(
    self,
    chains: list[str],
    scheme: str,
    min_confidence: float | None = None,
):
    """Create an Annotator.

    Args:
        chains: Chain types to consider. See class docstring for accepted values.
        scheme: Numbering scheme — ``"imgt"`` (default) or ``"kabat"``.
        min_confidence: Reject sequences with alignment confidence below this
            threshold. Defaults to ``0.5``; pass ``0.0`` to disable.

    Raises:
        ValueError: If any chain or scheme value is unrecognised, if Kabat is
            requested for TCR chains, or if ``min_confidence`` is outside ``[0, 1]``.
    """
    if min_confidence is not None and not (0 <= min_confidence <= 1.0):
        raise ValueError(
            f"min_confidence should be in [0, 1], got {min_confidence=}"
        )
    self._annotator = _Annotator(
        chains=_normalize_chains(chains),
        scheme=_normalize_scheme(scheme),
        min_confidence=min_confidence,
    )

number(sequence)

Assign IMGT or Kabat position numbers to every residue in a sequence.

Parameters:

Name Type Description Default
sequence str

Amino-acid sequence string (single-letter codes).

 required

Returns:

Type Description
NumberingResult

A NumberingResult with the detected chain, scheme, confidence score,
NumberingResult

and a {position: residue} numbering dict. On failure, error is
NumberingResult

set and all other fields are None.
Source code in immunum/__init__.py 
240
241
242
243
244
245
246
247
248
249
250
251
def number(self, sequence: str) -> NumberingResult:
    """Assign IMGT or Kabat position numbers to every residue in a sequence.

    Args:
        sequence: Amino-acid sequence string (single-letter codes).

    Returns:
        A `NumberingResult` with the detected chain, scheme, confidence score,
        and a ``{position: residue}`` numbering dict. On failure, ``error`` is
        set and all other fields are ``None``.
    """
    return NumberingResult(**self._annotator.number(sequence))

segment(sequence)

Split a sequence into FR/CDR regions.

Parameters:

Name Type Description Default
sequence str

Amino-acid sequence string (single-letter codes).

 required

Returns:

Type Description
SegmenationResult

A SegmenationResult with fr1–fr4, cdr1–cdr3,
SegmenationResult

and any unaligned prefix/postfix residues. On failure,
SegmenationResult

error is set and all region fields are None.
Source code in immunum/__init__.py 
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
def segment(self, sequence: str) -> SegmenationResult:
    """Split a sequence into FR/CDR regions.

    Args:
        sequence: Amino-acid sequence string (single-letter codes).

    Returns:
        A `SegmenationResult` with ``fr1``–``fr4``, ``cdr1``–``cdr3``,
        and any unaligned ``prefix``/``postfix`` residues. On failure,
        ``error`` is set and all region fields are ``None``.
    """
    raw = self._annotator.segment(sequence)
    return SegmenationResult(
        fr1=raw.get("fr1"),
        cdr1=raw.get("cdr1"),
        fr2=raw.get("fr2"),
        cdr2=raw.get("cdr2"),
        fr3=raw.get("fr3"),
        cdr3=raw.get("cdr3"),
        fr4=raw.get("fr4"),
        prefix=raw.get("prefix"),
        postfix=raw.get("postfix"),
        error=raw.get("error"),
    )

immunum.NumberingResult dataclass

Python dataclass containing numbering results. Allows for direct attribute access via result.chain, result.numbering, etc.:

from immunum import Annotator

annotator = Annotator(
    chains=["H", "K", "L"],
    scheme="imgt",
)

sequence = "QVQLVQSGAEVKRPGSSVTVSCKASGGSFSTYALSWVRQAPGRGLEWMGGVIPLLTITNYAPRFQGRITITADRSTSTAYLELNSLRPEDTAVYYCAREGTTGKPIGAFAHWGQGTLVTVSS"

result = annotator.number(sequence)
assert result.chain == "H"
assert result.scheme == "IMGT"
assert isinstance(
    result.confidence, float
)
assert result.numbering["1"] == "Q"

for (
    position,
    amino_acid,
) in result.numbering.items():
    print(f"{position}: {amino_acid}")

# 1: Q
# 2: V
# 3: Q
# ...
Source code in immunum/__init__.py 
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
@dataclass(frozen=True)
class NumberingResult:
    """Python dataclass containing numbering results. Allows for direct attribute access
    via `result.chain`, `result.numbering`, etc.:

    ```python
    from immunum import Annotator

    annotator = Annotator(
        chains=["H", "K", "L"],
        scheme="imgt",
    )

    sequence = "QVQLVQSGAEVKRPGSSVTVSCKASGGSFSTYALSWVRQAPGRGLEWMGGVIPLLTITNYAPRFQGRITITADRSTSTAYLELNSLRPEDTAVYYCAREGTTGKPIGAFAHWGQGTLVTVSS"

    result = annotator.number(sequence)
    assert result.chain == "H"
    assert result.scheme == "IMGT"
    assert isinstance(
        result.confidence, float
    )
    assert result.numbering["1"] == "Q"

    for (
        position,
        amino_acid,
    ) in result.numbering.items():
        print(f"{position}: {amino_acid}")

    # 1: Q
    # 2: V
    # 3: Q
    # ...
    ```
    """

    chain: Optional[str]
    scheme: Optional[str]
    confidence: Optional[float]
    numbering: Optional[dict[str, str]]
    query_start: Optional[int]
    query_end: Optional[int]
    error: Optional[str]

chain instance-attribute

scheme instance-attribute

confidence instance-attribute

numbering instance-attribute

query_start instance-attribute

query_end instance-attribute

error instance-attribute

__init__(chain, scheme, confidence, numbering, query_start, query_end, error)

immunum.SegmenationResult dataclass

Python dataclass containing numbering results. Allows for direct atribute access via results.fr1, and also for iterating through segmentation results via as_dict():

from immunum import Annotator

annotator = Annotator(
    chains=["H", "K", "L"],
    scheme="imgt",
)

sequence = "QVQLVQSGAEVKRPGSSVTVSCKASGGSFSTYALSWVRQAPGRGLEWMGGVIPLLTITNYAPRFQGRITITADRSTSTAYLELNSLRPEDTAVYYCAREGTTGKPIGAFAHWGQGTLVTVSS"

result = annotator.segment(sequence)
assert (
    result.fr1
    == "QVQLVQSGAEVKRPGSSVTVSCKAS"
)
assert result.cdr1 == "GGSFSTYA"
assert result.fr2 == "LSWVRQAPGRGLEWMGG"
assert result.cdr2 == "VIPLLTIT"
assert (
    result.fr3
    == "NYAPRFQGRITITADRSTSTAYLELNSLRPEDTAVYYC"
)
assert result.cdr3 == "AREGTTGKPIGAFAH"
assert result.fr4 == "WGQGTLVTVSS"

for (
    segment,
    aminoacids,
) in result.as_dict().items():
    print(f"{segment}: {aminoacids}")

# fr1: QVQLVQSGAEVKRPGSSVTVSCKAS
# cdr1: GGSFSTYA
# fr2: LSWVRQAPGRGLEWMGG
# cdr2: VIPLLTIT
# fr3: NYAPRFQGRITITADRSTSTAYLELNSLRPEDTAVYYC
# cdr3: AREGTTGKPIGAFAH
# fr4: WGQGTLVTVSS
# prefix:
# postfix:
Source code in immunum/__init__.py 
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
@dataclass(frozen=True)
class SegmenationResult:
    """
    Python dataclass containing numbering results. Allows for direct atribute access
    via `results.fr1`, and also for iterating through segmentation results via `as_dict()`:

    ```python
    from immunum import Annotator

    annotator = Annotator(
        chains=["H", "K", "L"],
        scheme="imgt",
    )

    sequence = "QVQLVQSGAEVKRPGSSVTVSCKASGGSFSTYALSWVRQAPGRGLEWMGGVIPLLTITNYAPRFQGRITITADRSTSTAYLELNSLRPEDTAVYYCAREGTTGKPIGAFAHWGQGTLVTVSS"

    result = annotator.segment(sequence)
    assert (
        result.fr1
        == "QVQLVQSGAEVKRPGSSVTVSCKAS"
    )
    assert result.cdr1 == "GGSFSTYA"
    assert result.fr2 == "LSWVRQAPGRGLEWMGG"
    assert result.cdr2 == "VIPLLTIT"
    assert (
        result.fr3
        == "NYAPRFQGRITITADRSTSTAYLELNSLRPEDTAVYYC"
    )
    assert result.cdr3 == "AREGTTGKPIGAFAH"
    assert result.fr4 == "WGQGTLVTVSS"

    for (
        segment,
        aminoacids,
    ) in result.as_dict().items():
        print(f"{segment}: {aminoacids}")

    # fr1: QVQLVQSGAEVKRPGSSVTVSCKAS
    # cdr1: GGSFSTYA
    # fr2: LSWVRQAPGRGLEWMGG
    # cdr2: VIPLLTIT
    # fr3: NYAPRFQGRITITADRSTSTAYLELNSLRPEDTAVYYC
    # cdr3: AREGTTGKPIGAFAH
    # fr4: WGQGTLVTVSS
    # prefix:
    # postfix:
    ```
    """

    fr1: Optional[str]
    cdr1: Optional[str]
    fr2: Optional[str]
    cdr2: Optional[str]
    fr3: Optional[str]
    cdr3: Optional[str]
    fr4: Optional[str]
    prefix: Optional[str]
    postfix: Optional[str]
    error: Optional[str]

    def as_dict(self) -> dict[str, Optional[str]]:
        """Return dict mapping segment names to sequences (excludes error field)

        Returns:
            dict[str, str | None]: dict mapping ['fr1', 'fr2', ...] to their aminoacid sequences
        """
        return {
            "fr1": self.fr1,
            "cdr1": self.cdr1,
            "fr2": self.fr2,
            "cdr2": self.cdr2,
            "fr3": self.fr3,
            "cdr3": self.cdr3,
            "fr4": self.fr4,
            "prefix": self.prefix,
            "postfix": self.postfix,
        }

fr1 instance-attribute

cdr1 instance-attribute

fr2 instance-attribute

cdr2 instance-attribute

fr3 instance-attribute

cdr3 instance-attribute

fr4 instance-attribute

prefix instance-attribute

postfix instance-attribute

error instance-attribute

__init__(fr1, cdr1, fr2, cdr2, fr3, cdr3, fr4, prefix, postfix, error)

as_dict()

Return dict mapping segment names to sequences (excludes error field)

Returns:

Type Description
dict[str, Optional[str]]

dict[str, str | None]: dict mapping ['fr1', 'fr2', ...] to their aminoacid sequences
Source code in immunum/__init__.py 
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
def as_dict(self) -> dict[str, Optional[str]]:
    """Return dict mapping segment names to sequences (excludes error field)

    Returns:
        dict[str, str | None]: dict mapping ['fr1', 'fr2', ...] to their aminoacid sequences
    """
    return {
        "fr1": self.fr1,
        "cdr1": self.cdr1,
        "fr2": self.fr2,
        "cdr2": self.cdr2,
        "fr3": self.fr3,
        "cdr3": self.cdr3,
        "fr4": self.fr4,
        "prefix": self.prefix,
        "postfix": self.postfix,
    }