immunum 0.9.2 → 1.1.0

package/README.md

@@ -1,6 +1,8 @@
-# immunum
+![Immunum Logo](https://raw.githubusercontent.com/ENPICOM/immunum/master/docs/assets/immunum_logotype.svg)
 
-High-performance antibody and TCR sequence numbering in Rust, Python, and WebAssembly.
+Immunum is a high-performance antibody and TCR sequence numbering tool for Rust, Python, Polars and JS/TS.
+
+Try it in your browser: [interactive demo](https://immunum.enpicom.com/demo/).
 
 [![Crates.io](https://img.shields.io/crates/v/immunum)](https://crates.io/crates/immunum)
 [![PyPI](https://img.shields.io/pypi/v/immunum)](https://pypi.org/project/immunum/)
@@ -16,7 +18,7 @@ High-performance antibody and TCR sequence numbering in Rust, Python, and WebAss
 Available as:
 
 - **Rust crate** — core library and CLI
-- **Python package** — via PyPI (`pip install immunum`), with a [Polars](https://pola.rs) plugin for vectorized batch processing
+- **Python package** — with a [Polars](https://pola.rs) plugin for vectorized batch processing
 - **npm package** — for Node.js and browsers
 
 ### Supported chains
@@ -28,13 +30,15 @@ Available as:
 | IGL (lambda) | TRD (delta) |
 |              | TRG (gamma) |
 
+Chain codes: `H` (IGH), `K` (IGK), `L` (IGL), `A` (TRA), `B` (TRB), `D` (TRD), `G` (TRG).
+
+Chain type is automatically detected by aligning against all loaded chains and selecting the best match.
+
 ### Numbering schemes
 
 - **IMGT** — all 7 chain types
 - **Kabat** — antibody chains (IGH, IGK, IGL)
 
-Chain type is automatically detected by aligning against all loaded chains and selecting the best match.
-
 ## Table of Contents
 
 - [Python](#python)
@@ -46,6 +50,7 @@ Chain type is automatically detected by aligning against all loaded chains and s
   - [Installation](#installation-1)
   - [Usage](#usage)
 - [Rust](#rust)
+  - [Installation](#installation-2)
   - [Usage](#usage-1)
 - [CLI](#cli)
   - [Options](#options)
@@ -99,8 +104,6 @@ assert result.cdr3 == 'AREGTTGKPIGAFAH'
 assert result.fr4 == 'WGQGTLVTVSS'
 ```
 
-Chains: `"H"` (heavy), `"K"` (kappa), `"L"` (lambda), `"A"` (TRA), `"B"` (TRB), `"G"` (TRG), `"D"` (TRD).
-
 ### Polars plugin
 
 For batch processing, `immunum.polars` registers elementwise Polars expressions:
@@ -138,9 +141,7 @@ npm install immunum
 ### Usage
 
 ```js
-import init, { Annotator } from "immunum";
-
-await init(); // load the wasm module
+const { Annotator } = require("immunum");
 
 const annotator = new Annotator(["H", "K", "L"], "imgt");
 
@@ -148,18 +149,27 @@ const sequence =
   "QVQLVQSGAEVKRPGSSVTVSCKASGGSFSTYALSWVRQAPGRGLEWMGGVIPLLTITNYAPRFQGRITITADRSTSTAYLELNSLRPEDTAVYYCAREGTTGKPIGAFAHWGQGTLVTVSS";
 
 const result = annotator.number(sequence);
-console.log(result.chain); // "H"
+console.log(result.chain);      // "H"
 console.log(result.confidence); // 0.97
-console.log(result.numbering); // { "1": "E", "2": "V", ... }
+console.log(result.numbering);  // { "1": "Q", "2": "V", ... }
 
 const segments = annotator.segment(sequence);
-console.log(segments.cdr3);
+console.log(segments.cdr3); // "AREGTTGKPIGAFAH"
 
 annotator.free(); // or use `using annotator = new Annotator(...)` with explicit resource management
 ```
 
 ## Rust
 
+### Installation
+
+Add to `Cargo.toml`:
+
+```toml
+[dependencies]
+immunum = "0.9"
+```
+
 ### Usage
 
 ```rust
@@ -174,20 +184,14 @@ let annotator = Annotator::new(
 let sequence = "QVQLVQSGAEVKRPGSSVTVSCKASGGSFSTYALSWVRQAPGRGLEWMGGVIPLLTITNYAPRFQGRITITADRSTSTAYLELNSLRPEDTAVYYCAREGTTGKPIGAFAHWGQGTLVTVSS";
 
 let result = annotator.number(sequence).unwrap();
-
 println!("Chain: {}", result.chain);        // IGH
 println!("Confidence: {:.2}", result.confidence);
-
 for (aa, pos) in sequence.chars().zip(result.positions.iter()) {
     println!("{} -> {}", aa, pos);
 }
-```
-
-Add to `Cargo.toml`:
 
-```toml
-[dependencies]
-immunum = "0.9"
+let segments = annotator.segment(sequence).unwrap();
+println!("CDR3: {}", segments.cdr3);
 ```
 
 ## CLI

package/immunum.d.ts

@@ -1,34 +1,45 @@
 /* tslint:disable */
 /* eslint-disable */
 
-/** Numbered residues keyed by IMGT/Kabat position string (e.g. `"112A"`). */
-export type Numbering = Record<string, string>;
+/**
+ * Ordered position → residue map, iterated in IMGT-correct order.
+ * Keys are position strings (e.g. `"112A"`) and values are single-character residues.
+ */
+export type Numbering = Map<string, string>;
 
-/** Result returned by {@link Annotator.number}. */
+/** Result returned by {@link Annotator.number}. On failure, chain/scheme/confidence/numbering/query_start/query_end are null and error contains the reason. */
 export interface NumberingResult {
-    /** Detected chain type: `"H"`, `"K"`, `"L"`, `"A"`, `"B"`, `"G"`, or `"D"`. */
-    chain: string;
-    /** Numbering scheme used: `"imgt"` or `"kabat"`. */
-    scheme: string;
-    /** Alignment confidence score between 0 and 1. */
-    confidence: number;
-    /** Position-to-residue mapping for the aligned region. */
-    numbering: Numbering;
+    /** Detected chain type: `"H"`, `"K"`, `"L"`, `"A"`, `"B"`, `"G"`, or `"D"`. Null on failure. */
+    chain: string | null;
+    /** Numbering scheme used: `"imgt"` or `"kabat"`. Null on failure. */
+    scheme: string | null;
+    /** Alignment confidence score between 0 and 1. Null on failure. */
+    confidence: number | null;
+    /** Position-to-residue mapping for the aligned region. Null on failure. */
+    numbering: Numbering | null;
+    /** 0-indexed start of the aligned region in the input sequence (inclusive). Null on failure. */
+    query_start: number | null;
+    /** 0-indexed end of the aligned region in the input sequence (inclusive). Null on failure. */
+    query_end: number | null;
+    /** Error message if numbering failed, null on success. */
+    error: string | null;
 }
 
-/** FR/CDR segments returned by {@link Annotator.segment}. */
+/** FR/CDR segments returned by {@link Annotator.segment}. On failure, all region fields are absent and error contains the reason. */
 export interface SegmentationResult {
-    fr1: string;
-    cdr1: string;
-    fr2: string;
-    cdr2: string;
-    fr3: string;
-    cdr3: string;
-    fr4: string;
+    fr1?: string;
+    cdr1?: string;
+    fr2?: string;
+    cdr2?: string;
+    fr3?: string;
+    cdr3?: string;
+    fr4?: string;
     /** Residues before FR1 (non-canonical N-terminal extension). */
-    prefix: string;
+    prefix?: string;
     /** Residues after FR4 (non-canonical C-terminal extension). */
-    postfix: string;
+    postfix?: string;
+    /** Error message if segmentation failed, null on success. */
+    error: string | null;
 }
 
 /**
@@ -62,4 +73,5 @@ export class Annotator {
     constructor(chains: string[], scheme: string, min_confidence?: number | null);
     number(sequence: string): NumberingResult;
     segment(sequence: string): SegmentationResult;
+
 }

package/immunum.js

@@ -40,10 +40,7 @@ class Annotator {
         const ptr0 = passStringToWasm0(sequence, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
         const len0 = WASM_VECTOR_LEN;
         const ret = wasm.annotator_number(this.__wbg_ptr, ptr0, len0);
-        if (ret[2]) {
-            throw takeFromExternrefTable0(ret[1]);
-        }
-        return takeFromExternrefTable0(ret[0]);
+        return ret;
     }
     /**
      * @param {string} sequence
@@ -53,10 +50,7 @@ class Annotator {
         const ptr0 = passStringToWasm0(sequence, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
         const len0 = WASM_VECTOR_LEN;
         const ret = wasm.annotator_segment(this.__wbg_ptr, ptr0, len0);
-        if (ret[2]) {
-            throw takeFromExternrefTable0(ret[1]);
-        }
-        return takeFromExternrefTable0(ret[0]);
+        return ret;
     }
 }
 if (Symbol.dispose) Annotator.prototype[Symbol.dispose] = Annotator.prototype.free;
@@ -83,6 +77,10 @@ function __wbg_get_imports() {
         __wbg___wbindgen_throw_6ddd609b62940d55: function(arg0, arg1) {
             throw new Error(getStringFromWasm0(arg0, arg1));
         },
+        __wbg_new_49d5571bd3f0c4d4: function() {
+            const ret = new Map();
+            return ret;
+        },
         __wbg_new_ab79df5bd7c26067: function() {
             const ret = new Object();
             return ret;
@@ -91,6 +89,10 @@ function __wbg_get_imports() {
             const ret = Reflect.set(arg0, arg1, arg2);
             return ret;
         }, arguments); },
+        __wbg_set_bf7251625df30a02: function(arg0, arg1, arg2) {
+            const ret = arg0.set(arg1, arg2);
+            return ret;
+        },
         __wbindgen_cast_0000000000000001: function(arg0) {
             // Cast intrinsic for `F64 -> Externref`.
             const ret = arg0;

package/package.json

@@ -4,7 +4,7 @@
     "ENPICOM <dev@enpicom.com>"
   ],
   "description": "Fast antibody and T-cell receptor numbering in Rust and Python",
-  "version": "0.9.2",
+  "version": "1.1.0",
   "license": "MIT",
   "repository": {
     "type": "git",