Skip to content

immunum

Immunum is a high-performance antibody and T-cell receptor sequence numbering tool for Rust, Python, Polars, JavaScript and the command line. Try it in your browser.

Documentation: immunum.enpicom.com.

Crates.io PyPI npm License: MIT CI Docs

Overview

immunum numbers antibody and T-cell receptor variable domain sequences and splits them into framework and complementarity-determining regions. It uses Needleman-Wunsch semi-global alignment against position-specific scoring matrices built from consensus sequences, with BLOSUM62-based substitution scores.

Antibody TCR
IGH (heavy) TRA (alpha)
IGK (kappa) TRB (beta)
IGL (lambda) TRD (delta)
TRG (gamma)

The chain is detected by aligning against every chain you allow and keeping the best match. Positions follow one of five schemes, all derived from the internal IMGT numbering:

  • IMGT: all 7 chains
  • Kabat, Chothia, Martin (extended Chothia) and AHo: antibody chains (IGH, IGK, IGL)

How the schemes and their CDR definitions differ is explained in Concepts.

Quickstart

Python

from immunum import Annotator

annotator = Annotator(chains=["ig"], scheme="imgt")
sequence = "QVQLVQSGAEVKRPGSSVTVSCKASGGSFSTYALSWVRQAPGRGLEWMGGVIPLLTITNYAPRFQGRITITADRSTSTAYLELNSLRPEDTAVYYCAREGTTGKPIGAFAHWGQGTLVTVSS"

result = annotator.number(sequence)
print(result.chain)           # H
print(result.numbering["1"])  # Q

segments = annotator.segment(sequence)
print(segments.cdr3)          # AREGTTGKPIGAFAH

More in the Python guide.

Polars

import polars as pl
import immunum.polars as imp

df = pl.DataFrame({"sequence": [
    "QVQLVQSGAEVKRPGSSVTVSCKASGGSFSTYALSWVRQAPGRGLEWMGGVIPLLTITNYAPRFQGRITITADRSTSTAYLELNSLRPEDTAVYYCAREGTTGKPIGAFAHWGQGTLVTVSS",
    "DIQMTQSPSSLSASVGDRVTITCRASQDVNTAVAWYQQKPGKAPKLLIYSASFLYSGVPSRFSGSRSGTDFTLTISSLQPEDFATYYCQQHYTTPPTFGQGTKVEIK",
]})
cdr3 = df.select(imp.segment("sequence", chains=["ig"], scheme="imgt").struct.field("cdr3"))
print(cdr3["cdr3"].to_list())  # ['AREGTTGKPIGAFAH', 'QQHYTTPPT']

More in the Polars guide.

JavaScript

const { Annotator } = require("immunum");

const annotator = new Annotator(["ig"], "imgt");
const result = annotator.number(
  "QVQLVQSGAEVKRPGSSVTVSCKASGGSFSTYALSWVRQAPGRGLEWMGGVIPLLTITNYAPRFQGRITITADRSTSTAYLELNSLRPEDTAVYYCAREGTTGKPIGAFAHWGQGTLVTVSS",
);
console.log(result.chain);              // "H"
console.log(result.numbering.get("1")); // "Q"
annotator.free();

More in the JavaScript guide.

Rust

use immunum::{Annotator, Chain, Scheme};

let annotator = Annotator::new(&[Chain::IGH, Chain::IGK, Chain::IGL], Scheme::IMGT, None)?;
let sequence = "QVQLVQSGAEVKRPGSSVTVSCKASGGSFSTYALSWVRQAPGRGLEWMGGVIPLLTITNYAPRFQGRITITADRSTSTAYLELNSLRPEDTAVYYCAREGTTGKPIGAFAHWGQGTLVTVSS";

let segments = annotator.segment(sequence)?;
println!("CDR3: {}", segments.cdr3); // AREGTTGKPIGAFAH

More in the Rust guide and on docs.rs.

Command line

$ immunum number sequences.fasta | head -3
sequence_id chain   scheme  confidence  position    residue error   error_kind
seq_1   H   IMGT    0.7845  1   Q
seq_1   H   IMGT    0.7845  2   V
$ immunum segment -s kabat -f jsonl sequences.fasta

More in the command-line guide.

Errors

A setup mistake, such as an unknown chain name, is raised; a sequence that can't be numbered comes back as a result with error and error_kind set, so a batch never stops for one bad sequence. See Errors.