JavaScript
The TypeScript declarations the npm package ships (immunum.d.ts), generated from the bindings
in src/wasm.rs. Results are camelCase: queryStart, queryEnd and errorKind are
query_start, query_end and error_kind in the other interfaces. Examples are in the
JavaScript guide.
/* tslint:disable */
/**
* 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>;
/**
* Error thrown when immunum is set up or called wrongly, such as with an unknown chain name.
* `message` says what went wrong; `kind` is a stable code for it: `"invalid_chain"`,
* `"invalid_scheme"`, `"unsupported_chain"` or `"invalid_min_confidence"`.
*/
export interface ImmunumError extends Error {
kind: string;
}
/**
* Result returned by {@link Annotator.number}. On failure, chain/scheme/confidence/numbering/queryStart/queryEnd are null and error and errorKind contain the reason.
*
* The fields are camelCase on purpose, as JavaScript and TypeScript code expects: `queryStart`,
* `queryEnd` and `errorKind` are `query_start`, `query_end` and `error_kind` in Python, Polars and
* the CLI.
*/
export interface NumberingResult {
/** Detected chain type: `"H"`, `"K"`, `"L"`, `"A"`, `"B"`, `"G"`, or `"D"`. Null on failure. */
chain: string | null;
/** Numbering scheme used: `"IMGT"`, `"Kabat"`, `"Chothia"`, `"Martin"` or `"Aho"`. 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. */
queryStart: number | null;
/** 0-indexed end of the aligned region in the input sequence (inclusive). Null on failure. */
queryEnd: number | null;
/** Error message if numbering failed, null on success. */
error: string | null;
/** What went wrong if numbering failed: `"invalid_sequence"`, `"low_confidence"` or, from {@link Annotator.numberDomains} only, `"domain_too_short"`. Null on success. */
errorKind: string | null;
}
/** FR/CDR segments returned by {@link Annotator.segment}. On failure, every region field is null and error and errorKind contain the reason. */
export interface SegmentationResult {
fr1: string | null;
cdr1: string | null;
fr2: string | null;
cdr2: string | null;
fr3: string | null;
cdr3: string | null;
fr4: string | null;
/** Residues before FR1 (non-canonical N-terminal extension). */
prefix: string | null;
/** Residues after FR4 (non-canonical C-terminal extension). */
postfix: string | null;
/** Error message if segmentation failed, null on success. */
error: string | null;
/** What went wrong if segmentation failed: `"invalid_sequence"`, `"low_confidence"` or, from {@link Annotator.segmentDomains} only, `"domain_too_short"`. Null on success. */
errorKind: string | null;
}
/** Inclusive `[start, end]` position bounds of each FR/CDR region, N- to C-terminal. */
export interface RegionSpans {
fr1: [number, number];
cdr1: [number, number];
fr2: [number, number];
cdr2: [number, number];
fr3: [number, number];
cdr3: [number, number];
fr4: [number, number];
}
/**
* The FR/CDR region boundaries a scheme uses for a chain, both named as for {@link Annotator}.
* IMGT and AHo number every chain alike; Kabat, Chothia and Martin place their CDRs differently
* on heavy and light chains.
*
* @throws {ImmunumError} `invalid_scheme` or `invalid_chain` for an unknown scheme or chain, and
* `unsupported_chain` for a chain the scheme doesn't number (only IMGT numbers TCR chains).
*/
export function regionsFor(scheme: string, chain: string): RegionSpans;
/**
* Annotates antibody and T-cell receptor sequences with scheme-specific position numbers.
*
* @param 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"`
*
* A group of chains is accepted too: `"ig"` (IGH, IGK, IGL), `"tcr"` (TRA, TRB, TRG,
* TRD) or `"all"`. Pass all chains you want to consider; the annotator scores each and
* picks the best-matching one.
*
* @param 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)
* - `"Chothia"` / `"c"` — Chothia numbering (derived from IMGT)
* - `"Martin"` / `"m"` — Martin / extended Chothia numbering (derived from IMGT)
* - `"Aho"` / `"a"` — AHo numbering (derived from IMGT)
*
* Only IMGT supports TCR chains; the other schemes are restricted to antibody
* chains (IGH, IGK, IGL). {@link schemeSupportsChain} checks a pair up front.
*
* @param minConfidence - Optional minimum alignment confidence threshold in the
* range `[0, 1]`. Sequences scoring below this value are rejected with an error.
* Defaults to `0.5` when `null` or omitted.
*
* @throws {ImmunumError} `invalid_chain` for an unknown chain name or no chains,
* `invalid_scheme` for an unknown scheme, `unsupported_chain` for a chain the scheme
* doesn't number and `invalid_min_confidence` for a `minConfidence` outside `[0, 1]`.
*/
export class Annotator {
free(): void;
[Symbol.dispose](): void;
constructor(chains: string[], scheme: string, minConfidence?: number | null);
number(sequence: string): NumberingResult;
/**
* Number every variable domain in a sequence, such as both domains of an scFv. One
* {@link NumberingResult} per domain, ordered by position, each what `number` returns for that
* domain; never empty. A sequence without a domain gives a single result with `error` and
* `errorKind` set: `"low_confidence"` when no alignment reaches the minimum confidence, as
* `number` reports it, or `"domain_too_short"` when the best alignment is confident but shorter
* than a domain must be. So does an invalid sequence, with `"invalid_sequence"`.
*
* A domain that lacks its first IMGT positions (a light chain starting at position 2, say) and
* directly follows other residues, such as a linker, can have the residue just before it
* numbered as its first position: IMGT position 1 is so variable that the sequence alone can't
* tell a linker residue from the domain's own first residue.
*/
numberDomains(sequence: string): NumberingResult[];
segment(sequence: string): SegmentationResult;
/**
* Split every variable domain in a sequence into FR/CDR regions. One
* {@link SegmentationResult} per domain, ordered by position; never empty. A sequence without
* a domain, or an invalid one, gives a single result with `error` and `errorKind` set, as for
* `numberDomains`.
*
* Every residue lands in exactly one domain's regions: a domain's `prefix` holds the residues
* since the previous domain (or the start of the sequence), and only the last domain has the
* residues after it as its `postfix`. All domains' regions in order rebuild the sequence.
*/
segmentDomains(sequence: string): SegmentationResult[];
}
/**
* Whether `scheme` numbers `chain`: IMGT numbers every chain, the other schemes antibody chains
* (IGH, IGK, IGL) only. Takes a scheme and a single chain by the names `Annotator` accepts.
*
* @throws {ImmunumError} `invalid_scheme` or `invalid_chain` for an unknown scheme or chain.
*/
export function schemeSupportsChain(scheme: string, chain: string): boolean;
/**
* The version of immunum this module was built from, such as `"2.0.0"`.
*/
export function version(): string;