Skip to content

Getting started

Which interface should I use?

Every interface runs the same Rust core and gives the same numbering; they differ in how you feed it sequences.

You have Use Why
A FASTA file, or sequences in a shell pipeline Command line No code: TSV or JSON out, one record per residue or per sequence
A few sequences up to tens of thousands, in Python Python (immunum.Annotator) Plain objects per sequence; thread-safe and picklable, so it fits thread and process pools
Hundreds of thousands of sequences or more, or data already in a DataFrame Polars (immunum.polars) Runs inside a Polars query on every core, streams larger-than-memory files, and only computes the columns you keep
A Node.js service or tool JavaScript (npm immunum) WebAssembly build of the core with TypeScript types
A Rust program Rust (crate immunum) The core library itself, with no Python or JavaScript runtime
One sequence to look at Demo Runs in your browser; nothing to install

Installation

Python

pip install immunum
pip install "immunum[polars]"   # with Polars, for immunum.polars

Python 3.10 or newer. Prebuilt wheels cover Linux (x86_64 and aarch64, manylinux), macOS (Apple Silicon and Intel) and Windows (x64); elsewhere pip builds from source, which needs Rust. immunum.polars needs Polars, which plain pip install immunum doesn't install.

JavaScript

npm install immunum

The npm package is built for Node.js. It ships its TypeScript types.

Rust

cargo add immunum
cargo add immunum --no-default-features   # the library without the CLI's dependencies

Rust 1.89 or newer. API reference: docs.rs/immunum.

Command line

The Python package installs the immunum command, so uvx runs it without installing anything first, and pip install immunum puts it on your path:

uvx immunum number sequences.fasta

Or build it with Cargo (Rust 1.89 or newer, from rustup):

cargo install immunum

There are no standalone prebuilt binaries. immunum --version prints the version you're running.

Next steps

  • Concepts and FAQ: which chains and schemes to pick, what confidence means, and how flanking residues are handled.
  • The usage guide for your interface, from the table above.
  • Errors: what's raised and what's returned when a sequence can't be numbered.
  • Coming from immunum 1.x? Read Upgrading to 2.0.