@datagrok/bio 2.27.1 → 2.27.3

package/package.json

@@ -5,7 +5,7 @@
     "name": "Davit Rizhinashvili",
     "email": "drizhinashvili@datagrok.ai"
   },
-  "version": "2.27.1",
+  "version": "2.27.3",
   "description": "Bioinformatics support (import/export of sequences, conversion, visualization, analysis). [See more](https://github.com/datagrok-ai/public/blob/master/packages/Bio/README.md) for details.",
   "repository": {
     "type": "git",
@@ -44,7 +44,7 @@
   ],
   "dependencies": {
     "@biowasm/aioli": "^3.1.0",
-    "@datagrok-libraries/bio": "^5.63.6",
+    "@datagrok-libraries/bio": "^5.63.7",
     "@datagrok-libraries/chem-meta": "^1.2.9",
     "@datagrok-libraries/math": "^1.2.6",
     "@datagrok-libraries/ml": "^6.10.11",
@@ -59,6 +59,8 @@
     "datagrok-api": "^1.26.3",
     "dayjs": "^1.11.4",
     "fastest-levenshtein": "^1.0.16",
+    "file-loader": "^6.2.0",
+    "immunum": "^1.1.0",
     "openchemlib": "^7.2.3",
     "rxjs": "^6.5.5",
     "style-loader": "^3.3.1",
@@ -69,7 +71,7 @@
     "@datagrok-libraries/helm-web-editor": "^1.1.16",
     "@datagrok-libraries/js-draw-lite": "^0.0.10",
     "@datagrok/chem": "^1.17.1",
-    "@datagrok/dendrogram": "^1.2.33",
+    "@datagrok/dendrogram": "^1.4.11",
     "@datagrok/eda": "^1.4.13",
     "@datagrok/helm": "^2.13.1",
     "@datagrok/peptides": "^1.27.4",

package/src/package-api.ts

@@ -162,7 +162,7 @@ export namespace funcs {
   }
 
   /**
-  Assigns antibody numbering (IMGT/Kabat/Chothia/AHo) using AntPack
+  Assigns antibody numbering (IMGT/Kabat/Chothia/AHo)
   */
   export async function applyNumberingScheme(): Promise<void> {
     return await grok.functions.call('Bio:ApplyNumberingScheme', {});
@@ -284,6 +284,20 @@ export namespace funcs {
     return await grok.functions.call('Bio:PepseaMsa', { sequenceCol, method, gapOpen, gapExtend });
   }
 
+  /**
+  Assigns antibody numbering (IMGT/Kabat) using the immunum WASM library
+  */
+  export async function immunumAntibodyNumbering(df: DG.DataFrame , seqCol: DG.Column , scheme: string ): Promise<DG.DataFrame> {
+    return await grok.functions.call('Bio:ImmunumAntibodyNumbering', { df, seqCol, scheme });
+  }
+
+  /**
+  Builds a MacromoleculeDifference column from two sequence columns (seq1#seq2)
+  */
+  export async function compareSequences(): Promise<void> {
+    return await grok.functions.call('Bio:CompareSequences', {});
+  }
+
   /**
   Visualizes sequence composition on a WebLogo plot
   */

package/src/package-test.ts

@@ -38,6 +38,7 @@ import './tests/activity-cliffs-tests';
 import './tests/sequence-space-test';
 import './tests/scoring';
 import './tests/projects-tests';
+import './tests/antibody-numbering-tests';
 
 
 export const _package = new DG.Package();

package/src/package.g.ts

@@ -234,7 +234,7 @@ export async function getRegionTopMenu(table: DG.DataFrame, sequence: DG.Column,
 }
 
 //name: Apply Numbering Scheme
-//description: Assigns antibody numbering (IMGT/Kabat/Chothia/AHo) using AntPack
+//description: Assigns antibody numbering (IMGT/Kabat/Chothia/AHo)
 //top-menu: Bio | Annotate | Apply Numbering Scheme...
 export function applyNumberingScheme() : void {
   PackageFunctions.applyNumberingScheme();
@@ -456,6 +456,24 @@ export async function pepseaMsa(sequenceCol: DG.Column<any>, method: string, gap
   return await PackageFunctions.pepseaMsa(sequenceCol, method, gapOpen, gapExtend);
 }
 
+//name: Immunum
+//description: Assigns antibody numbering (IMGT/Kabat) using the immunum WASM library
+//input: dataframe df 
+//input: column seqCol { semType: Macromolecule }
+//input: string scheme = 'imgt' { choices: ["imgt","kabat"] }
+//output: dataframe result
+//meta.role: antibodyNumbering
+export async function immunumAntibodyNumbering(df: DG.DataFrame, seqCol: DG.Column<any>, scheme: string) : Promise<any> {
+  return await PackageFunctions.immunumAntibodyNumbering(df, seqCol, scheme);
+}
+
+//name: Compare Sequences
+//description: Builds a MacromoleculeDifference column from two sequence columns (seq1#seq2)
+//top-menu: Bio | Analyze | Compare sequences...
+export function compareSequences() : void {
+  PackageFunctions.compareSequences();
+}
+
 //name: Composition Analysis
 //description: Visualizes sequence composition on a WebLogo plot
 //output: viewer result

package/src/package.ts

@@ -44,6 +44,7 @@ import {SequenceSimilarityViewer} from './analysis/sequence-similarity-viewer';
 import {SequenceDiversityViewer} from './analysis/sequence-diversity-viewer';
 import {invalidateMols, MONOMERIC_COL_TAGS, SubstructureSearchDialog} from './substructure-search/substructure-search';
 import {convert} from './utils/convert';
+import {compareSequencesUI} from './utils/compare-sequences';
 import {getMacromoleculeColumnPropertyPanel} from './widgets/representations';
 import {getMonomerInfoWidget} from './widgets/monomer-info-widget';
 import {saveAsFastaUI} from './utils/save-as-fasta';
@@ -85,6 +86,10 @@ import {BilnNotationProvider} from './utils/biln';
 import {showMonomerCollectionsView} from './utils/monomer-lib/monomer-collections-view';
 import {ISequenceColumnInput} from '@datagrok-libraries/bio/src/utils/sequence-column-input';
 import {SequenceColumnInput} from './utils/sequence-column-input';
+import {showNumberingSchemeDialog} from './utils/annotations/numbering-ui';
+import {showLiabilityScannerDialog} from './utils/annotations/liability-scanner-ui';
+import {showAnnotationManagerDialog} from './utils/annotations/annotation-manager-ui';
+import {numberAntibodyColumn} from './utils/antibody-numbering/number-antibody';
 
 import * as api from './package-api';
 export const _package = new BioPackage(/*{debug: true}/**/);
@@ -478,11 +483,11 @@ export class PackageFunctions {
 
   @grok.decorators.func({
     name: 'Apply Numbering Scheme',
-    description: 'Assigns antibody numbering (IMGT/Kabat/Chothia/AHo) using AntPack',
+    description: 'Assigns antibody numbering (IMGT/Kabat/Chothia/AHo)',
     'top-menu': 'Bio | Annotate | Apply Numbering Scheme...',
   })
   static applyNumberingScheme(): void {
-    import('./utils/annotations/numbering-ui').then((m) => m.showNumberingSchemeDialog());
+    showNumberingSchemeDialog();
   }
 
   @grok.decorators.func({
@@ -491,7 +496,7 @@ export class PackageFunctions {
     'top-menu': 'Bio | Annotate | Scan Liabilities...',
   })
   static scanLiabilities(): void {
-    import('./utils/annotations/liability-scanner-ui').then((m) => m.showLiabilityScannerDialog());
+    showLiabilityScannerDialog();
   }
 
   @grok.decorators.func({
@@ -500,7 +505,7 @@ export class PackageFunctions {
     'top-menu': 'Bio | Annotate | Manage Annotations...',
   })
   static manageAnnotations(): void {
-    import('./utils/annotations/annotation-manager-ui').then((m) => m.showAnnotationManagerDialog());
+    showAnnotationManagerDialog();
   }
 
   @grok.decorators.func({
@@ -992,6 +997,29 @@ export class PackageFunctions {
     return alignWithPepsea(sequenceCol, method, gapOpen, gapExtend);
   }
 
+  @grok.decorators.func({
+    name: 'Immunum',
+    description: 'Assigns antibody numbering (IMGT/Kabat) using the immunum WASM library',
+    meta: {role: 'antibodyNumbering'},
+  })
+  static async immunumAntibodyNumbering(
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    @grok.decorators.param({type: 'dataframe'}) df: DG.DataFrame,
+    @grok.decorators.param({type: 'column', options: {semType: 'Macromolecule'}}) seqCol: DG.Column<string>,
+    @grok.decorators.param({type: 'string', options: {choices: ['imgt', 'kabat'], initialValue: 'imgt'}}) scheme: string,
+  ): Promise<DG.DataFrame> {
+    return numberAntibodyColumn(seqCol, scheme);
+  }
+
+  @grok.decorators.func({
+    name: 'Compare Sequences',
+    description: 'Builds a MacromoleculeDifference column from two sequence columns (seq1#seq2)',
+    'top-menu': 'Bio | Analyze | Compare sequences...',
+  })
+  static compareSequences(): void {
+    compareSequencesUI();
+  }
+
   @grok.decorators.func({
     name: 'Composition Analysis',
     description: 'Visualizes sequence composition on a WebLogo plot',

package/src/tests/antibody-numbering-tests.ts

@@ -0,0 +1,190 @@
+import * as grok from 'datagrok-api/grok';
+import * as DG from 'datagrok-api/dg';
+
+import {category, expect, test} from '@datagrok-libraries/test/src/test';
+
+import {_package} from '../package';
+import {numberSequencesWithImmunum} from '../utils/antibody-numbering/immunum-client';
+import {numberAntibodyColumn} from '../utils/antibody-numbering/number-antibody';
+
+/** Canonical test sequences picked from samples/antibodies.csv.
+ *  - heavyChain1/2 are IGH variable regions starting with the classic EVQL/QVQL motifs
+ *  - lightChain1/2 are IGK/IGL variable regions (DIQM/DIVM/DIVL...)
+ *  These are stable inputs for immunum so unit tests can assert exact chain type
+ *  and region coverage without fetching the CSV from the server. */
+const HEAVY_1 = 'QVQLVQSGAEVKKPGASVKVSCKASGYTFTGYYMHWVRQAPGQGLEWMGWINPNSGGTNYAQKFQGRVTMTRDTSISTAYMELSRLRSDDTAVYYCARVAPGALDYWGQGTLVTVSS';
+const HEAVY_2 = 'EVQLVESGGGLVQPGGSLRLSCAASGFTFSSYAMSWVRQAPGKGLEWVSAISGSGGSTYYADSVKGRFTISRDNSKNTLYLQMNSLRAEDTAVYYCAKDHYSGSGSYYYYFDYWGQGTLVTVSS';
+const LIGHT_KAPPA = 'DIQMTQSPSSLSASVGDRVTITCRASQDVSTAVAWYQQKPGKAPKLLIYSASFLYSGVPSRFSGSGSGTDFTLTISSLQPEDFATYYCQQSYSTPRTFGQGTKVEIK';
+const LIGHT_LAMBDA = 'QSALTQPASVSGSPGQSITISCTGTSSDVGGYNYVSWYQQHPGKAPKLMIYDVSNRPSGVSNRFSGSKSGNTASLTISGLQAEDEADYYCSSYTSSSTLVFGGGTKLTVL';
+
+/** FR/CDR counts we expect in the immunum annotation JSON for IMGT/Kabat.
+ *  The engine only accepts IMGT and Kabat — those are the choices declared in
+ *  package.ts and surfaced in the dialog's scheme dropdown. */
+const EXPECTED_REGION_COUNT = 7; // FR1, CDR1, FR2, CDR2, FR3, CDR3, FR4
+const EXPECTED_REGION_NAMES = ['FR1', 'CDR1', 'FR2', 'CDR2', 'FR3', 'CDR3', 'FR4'];
+
+/** Sanity range for alignment confidence on canonical antibody sequences. */
+const MIN_CONFIDENCE = 0.5;
+
+category('antibody numbering (immunum)', () => {
+  // Each numberSequencesWithImmunum call spawns a fresh worker and terminates
+  // it before returning — no shared setup / teardown needed.
+
+  test('worker: heavy chain (IMGT)', async () => {
+    const [row] = await numberSequencesWithImmunum([HEAVY_1], 'imgt');
+    expect(row.chainType, 'Heavy');
+    expect(row.chainCode, 'H');
+    expect(row.confidence >= MIN_CONFIDENCE, true);
+    expect(row.positionNames.length > 0, true);
+    expect(row.numberingDetail.length > 0, true);
+    // numbering_map indices must fall inside the input sequence
+    for (const idx of Object.values(row.numberingMap))
+      expect(idx >= 0 && idx < HEAVY_1.length, true);
+    expect(row.numberingDetail.length, Object.keys(row.numberingMap).length);
+  });
+
+  test('worker: light kappa chain (IMGT)', async () => {
+    const [row] = await numberSequencesWithImmunum([LIGHT_KAPPA], 'imgt');
+    expect(row.chainType, 'Light');
+    expect(row.chainCode === 'K' || row.chainCode === 'L', true);
+    expect(row.confidence >= MIN_CONFIDENCE, true);
+    expect(row.numberingDetail.length > 0, true);
+  });
+
+  test('worker: light lambda chain (IMGT)', async () => {
+    const [row] = await numberSequencesWithImmunum([LIGHT_LAMBDA], 'imgt');
+    expect(row.chainType, 'Light');
+    expect(row.confidence >= MIN_CONFIDENCE, true);
+  });
+
+  test('worker: batch numbering', async () => {
+    const rows = await numberSequencesWithImmunum(
+      [HEAVY_1, LIGHT_KAPPA, HEAVY_2, LIGHT_LAMBDA], 'imgt');
+    expect(rows.length, 4);
+    expect(rows[0].chainType, 'Heavy');
+    expect(rows[1].chainType, 'Light');
+    expect(rows[2].chainType, 'Heavy');
+    expect(rows[3].chainType, 'Light');
+  });
+
+  test('worker: empty / short sequences fail gracefully', async () => {
+    const rows = await numberSequencesWithImmunum(['', 'AAAA', '   '], 'imgt');
+    expect(rows.length, 3);
+    for (const r of rows) {
+      expect(r.positionNames, '');
+      expect(r.numberingDetail.length, 0);
+      expect(r.error.length > 0, true);
+    }
+  });
+
+  test('worker: kabat scheme returns kabat-style position codes', async () => {
+    const [imgt] = await numberSequencesWithImmunum([HEAVY_1], 'imgt');
+    const [kabat] = await numberSequencesWithImmunum([HEAVY_1], 'kabat');
+    expect(imgt.chainType, 'Heavy');
+    expect(kabat.chainType, 'Heavy');
+    // Kabat numbering keys should not match IMGT one-for-one — the schemes
+    // number the same residues differently. A weak but robust check: the set
+    // of keys differs.
+    const imgtKeys = new Set(Object.keys(imgt.numberingMap));
+    const kabatKeys = new Set(Object.keys(kabat.numberingMap));
+    let differ = false;
+    for (const k of kabatKeys) if (!imgtKeys.has(k)) {differ = true; break;}
+    expect(differ, true);
+  });
+
+  test('numberAntibodyColumn: DataFrame shape matches antpack script', async () => {
+    const col = DG.Column.fromStrings('seq', [HEAVY_1, LIGHT_KAPPA, '']);
+    col.semType = DG.SEMTYPE.MACROMOLECULE;
+    const result = await numberAntibodyColumn(col, 'imgt');
+
+    // Required columns, same names as the Python script
+    for (const name of ['position_names', 'chain_type', 'annotations_json',
+      'numbering_detail', 'numbering_map']) {
+      expect(result.col(name) !== null, true);
+    }
+    expect(result.rowCount, 3);
+
+    // Row 0 — heavy chain: all 5 fields populated
+    expect(result.get('position_names', 0).length > 0, true);
+    expect(result.get('chain_type', 0), 'Heavy');
+    const annot0 = JSON.parse(result.get('annotations_json', 0));
+    expect(annot0.length, EXPECTED_REGION_COUNT);
+    expect(annot0.map((a: any) => a.name).join(','), EXPECTED_REGION_NAMES.join(','));
+    for (const a of annot0) {
+      expect(a.visualType, 'region');
+      expect(a.category, 'structure');
+      expect(a.sourceScheme, 'IMGT');
+      expect(a.autoGenerated, true);
+    }
+
+    // Row 1 — light chain: region JSON has same structure
+    expect(result.get('chain_type', 1), 'Light');
+    const annot1 = JSON.parse(result.get('annotations_json', 1));
+    expect(annot1.length, EXPECTED_REGION_COUNT);
+
+    // Row 2 — empty input: all fields blank / '[]'
+    expect(result.get('position_names', 2), '');
+    expect(result.get('chain_type', 2), '');
+    expect(result.get('annotations_json', 2), '[]');
+    expect(result.get('numbering_detail', 2), '');
+    expect(result.get('numbering_map', 2), '');
+  });
+
+  test('numberAntibodyColumn: numbering_map indices line up with sequence', async () => {
+    const col = DG.Column.fromStrings('seq', [HEAVY_1]);
+    col.semType = DG.SEMTYPE.MACROMOLECULE;
+    const result = await numberAntibodyColumn(col, 'imgt');
+
+    const detail = JSON.parse(result.get('numbering_detail', 0));
+    const map = JSON.parse(result.get('numbering_map', 0));
+
+    // For each numbered position: sequence[charIdx] must equal the recorded aa
+    for (const entry of detail) {
+      const idx = map[entry.position];
+      expect(typeof idx === 'number', true);
+      expect(HEAVY_1[idx], entry.aa);
+    }
+  });
+
+  test('numberAntibodyColumn: annotations_json start/end resolve via numbering_map', async () => {
+    const col = DG.Column.fromStrings('seq', [HEAVY_1]);
+    col.semType = DG.SEMTYPE.MACROMOLECULE;
+    const result = await numberAntibodyColumn(col, 'imgt');
+
+    const annotations = JSON.parse(result.get('annotations_json', 0));
+    const map = JSON.parse(result.get('numbering_map', 0));
+    // FR1 start (position "1") must be present and resolve to a valid char index.
+    const fr1 = annotations.find((a: any) => a.name === 'FR1');
+    expect(fr1 !== undefined, true);
+    const startIdx = map[fr1.start];
+    expect(typeof startIdx === 'number', true);
+    expect(startIdx >= 0 && startIdx < HEAVY_1.length, true);
+  });
+
+  test('numberAntibodyColumn: loads antibodies.csv sample subset', async () => {
+    let df: DG.DataFrame;
+    try {
+      df = await _package.files.readCsv('samples/antibodies.csv');
+    } catch (err) {
+      // Sample may not be deployed on every server; skip instead of failing.
+      console.warn('antibodies.csv not available — skipping', err);
+      return;
+    }
+    const hcCol = df.col('AntibodyHC') ?? df.col('HeavyChain') ?? df.columns.byName('AntibodyHC');
+    if (!hcCol) return;
+
+    // Subset to the first 10 rows so the test finishes in seconds.
+    const subset = DG.Column.fromStrings('seq',
+      Array.from({length: Math.min(10, hcCol.length)}, (_, i) => hcCol.get(i) ?? ''));
+    subset.semType = DG.SEMTYPE.MACROMOLECULE;
+
+    const result = await numberAntibodyColumn(subset, 'imgt');
+    expect(result.rowCount, subset.length);
+
+    let heavyCount = 0;
+    for (let i = 0; i < result.rowCount; i++)
+      if (result.get('chain_type', i) === 'Heavy') heavyCount++;
+    // Expect the majority of the HC column to be classified as heavy.
+    expect(heavyCount >= Math.ceil(subset.length * 0.6), true);
+  });
+});

package/src/utils/annotations/numbering-ui.ts

@@ -7,99 +7,48 @@ import {TAGS as bioTAGS, ALIGNMENT, ALPHABET, NOTATION} from '@datagrok-librarie
 import {
   SeqAnnotation, SeqAnnotationHit, AnnotationCategory,
 } from '@datagrok-libraries/bio/src/utils/macromolecule/annotations';
-import {NumberingScheme} from '@datagrok-libraries/bio/src/utils/macromolecule/numbering-schemes';
 import {
   setColumnAnnotations, getColumnAnnotations,
   getOrCreateAnnotationColumn, getRowAnnotations, setRowAnnotations, mergeRowHits,
 } from './annotation-manager';
-import {_package} from '../../package';
-import type {NumberingResult, Scheme} from '../antibody-numbering (WIP)';
-import {VdRegionsViewer} from '../../viewers/vd-regions-viewer';
-import { VdRegion, VdRegionType } from '@datagrok-libraries/bio/src/viewers/vd-regions';
-
-const BUILTIN_ENGINE_KEY = '__builtin__';
-const BUILTIN_ENGINE_LABEL = 'Built-in (TypeScript)';
-
-/** An engine entry: either a dynamically discovered DG.Func or the built-in TS engine. */
+/** An engine entry — a dynamically discovered DG.Func with meta.role: 'antibodyNumbering'. */
 interface NumberingEngine {
-  /** Display label for the dropdown */
   label: string;
-  /** Unique key — nqName for DG.Func engines, BUILTIN_ENGINE_KEY for built-in */
+  /** Unique key — `${package}:${name}`. */
   key: string;
-  /** The DG.Func to call, or null for the built-in engine */
-  func: DG.Func | null;
+  func: DG.Func;
 }
 
-/** Discovers all registered antibody numbering engines + the built-in TS engine.
- *  Dynamic engines (meta.role = 'antibodyNumbering') come first; built-in is last. */
+/** Discovers all registered antibody numbering engines (functions with
+ *  meta.role = 'antibodyNumbering'). Built-in engines: Bio package ships an
+ *  immunum-WASM-based engine; other packages (Proteomics etc.) can register
+ *  AntPack/ANARCI/etc. by adding their own meta.role function. */
 function discoverEngines(): NumberingEngine[] {
   const engines: NumberingEngine[] = [];
-
   const funcs = DG.Func.find({meta: {role: 'antibodyNumbering'}});
   if (funcs.length === 0) {
-    grok.shell.error('No antibody numbering engines found. Make sure that Proteomics plugin is installed and up to date.');
-    throw new Error('No external antibody numbering engines found. Make sure that Proteomics plugin is installed and up to date.');
+    grok.shell.error('No antibody numbering engines found. Make sure the Bio package is up to date.');
+    throw new Error('No antibody numbering engines found.');
   }
   for (const f of funcs) {
     const pkgName = f.package?.name ?? '';
-    const label = f.friendlyName || f.name;
     engines.push({
-      label: label,
+      label: f.friendlyName || f.name,
       key: pkgName ? `${pkgName}:${f.name}` : f.name,
       func: f,
     });
   }
-
-  // Built-in TS engine is always last
-  engines.push({label: BUILTIN_ENGINE_LABEL, key: BUILTIN_ENGINE_KEY, func: null});
   return engines;
 }
 
-/** Converts TS NumberingResult[] to a DG.DataFrame matching the expected output shape.
- *  Columns: position_names, chain_type, annotations_json, numbering_detail, numbering_map. */
-export function numberingResultsToDataFrame(results: NumberingResult[]): DG.DataFrame {
-  const n = results.length;
-  const posNames = DG.Column.fromType(DG.COLUMN_TYPE.STRING, 'position_names', n);
-  const chainTypes = DG.Column.fromType(DG.COLUMN_TYPE.STRING, 'chain_type', n);
-  const annotJson = DG.Column.fromType(DG.COLUMN_TYPE.STRING, 'annotations_json', n);
-  const numDetail = DG.Column.fromType(DG.COLUMN_TYPE.STRING, 'numbering_detail', n);
-  const numMap = DG.Column.fromType(DG.COLUMN_TYPE.STRING, 'numbering_map', n);
-
-  for (let i = 0; i < n; i++) {
-    const r = results[i];
-    if (r.error && r.percentIdentity < 0.3) {
-      posNames.set(i, '');
-      chainTypes.set(i, '');
-      annotJson.set(i, '[]');
-      numDetail.set(i, '');
-      numMap.set(i, '');
-    } else {
-      posNames.set(i, r.positionNames);
-      chainTypes.set(i, r.chainType);
-      annotJson.set(i, JSON.stringify(r.annotations));
-      numDetail.set(i, JSON.stringify(r.numberingDetail));
-      numMap.set(i, JSON.stringify(r.numberingMap));
-    }
-  }
-
-  return DG.DataFrame.fromColumns([posNames, chainTypes, annotJson, numDetail, numMap]);
-}
-
-/** Runs the built-in TS numbering engine on all rows of a sequence column. */
-async function runBuiltinNumbering(
-  seqCol: DG.Column<string>, schemeName: string,
-): Promise<DG.DataFrame> {
-  const {numberSequences, extractSequence} = await import('../antibody-numbering (WIP)');
-  const scheme = schemeName.toLowerCase() as Scheme;
-
-  const sequences: string[] = [];
-  for (let i = 0; i < seqCol.length; i++) {
-    const raw = seqCol.get(i);
-    sequences.push(extractSequence(raw ?? ''));
-  }
-
-  const results = numberSequences(sequences, scheme);
-  return numberingResultsToDataFrame(results);
+/** Reads the `scheme` parameter's declared choices off an engine function.
+ *  Engines advertise which schemes they support via the `choices` option of
+ *  their `scheme: string` parameter; if the function has none we fall back to
+ *  a single generic IMGT option so the dropdown is never empty. */
+function getEngineSchemes(engine: NumberingEngine): string[] {
+  const schemeInput = engine.func.inputs.find((p) => p.name.toLowerCase() === 'scheme');
+  const choices = schemeInput?.choices ?? [];
+  return choices.length > 0 ? choices.slice() : ['imgt'];
 }
 
 export function showNumberingSchemeDialog(): void {
@@ -117,45 +66,40 @@ export function showNumberingSchemeDialog(): void {
 
   const engines = discoverEngines();
   const engineLabels = engines.map((e) => e.label);
-  const schemeChoices = Object.values(NumberingScheme);
 
   const tableInput = ui.input.table('Table', {value: df});
   const seqInput = ui.input.column('Sequence', {
     table: df, value: seqCols[0],
     filter: (col: DG.Column) => col.semType === DG.SEMTYPE.MACROMOLECULE,
   });
-  const schemeInput = ui.input.choice('Scheme', {value: NumberingScheme.IMGT, items: schemeChoices});
   const engineInput = ui.input.choice('Engine', {
     value: engineLabels[0], items: engineLabels,
   });
-  // const populateRegions = ui.input.bool('Populate FR/CDR regions', {value: true});
-  // const openVdRegions = ui.input.bool('Open VD Regions viewer', {value: true});
+  const initialSchemes = getEngineSchemes(engines[0]);
+  const schemeInput = ui.input.choice('Scheme', {value: initialSchemes[0], items: initialSchemes});
+
+  // Switch the scheme list when the user picks a different engine — each engine
+  // advertises its own set via the `scheme` parameter's `choices`.
+  engineInput.onChanged.subscribe(() => {
+    const selected = engines.find((e) => e.label === engineInput.value);
+    if (!selected) return;
+    const schemes = getEngineSchemes(selected);
+    const prev = schemeInput.value;
+    schemeInput.items = schemes;
+    schemeInput.value = schemes.includes(prev ?? '') ? prev : schemes[0];
+  });
 
   const dialog = ui.dialog({title: 'Apply Antibody Numbering'})
-    .add(ui.inputs([tableInput, seqInput, schemeInput, engineInput]))
+    .add(ui.inputs([tableInput, seqInput, engineInput, schemeInput]))
     .onOK(async () => {
       const seqCol = seqInput.value!;
       const schemeName = schemeInput.value!;
       const selectedLabel = engineInput.value!;
-      const engine = engines.find((e) => e.label === selectedLabel) ?? engines[engines.length - 1];
+      const engine = engines.find((e) => e.label === selectedLabel) ?? engines[0];
       const pi = DG.TaskBarProgressIndicator.create(`Applying ${schemeName} numbering...`);
       try {
-        let result: DG.DataFrame;
-        if (engine.func)
-          result = await engine.func.apply({df: df, seqCol: seqCol, scheme: schemeName.toLowerCase()});
-        else
-          result = await runBuiltinNumbering(seqCol, schemeName);
-
+        const result: DG.DataFrame = await engine.func.apply({df: df, seqCol: seqCol, scheme: schemeName});
         applyNumberingResults(df, seqCol, result, schemeName, true, engine.label);
-
-        // // Open VD Regions viewer
-        // if (openVdRegions.value && grok.shell.tv) {
-        //   try {
-        //     await grok.shell.tv.dataFrame.plot.fromType('VdRegions', {});
-        //   } catch (err) {
-        //     console.warn('Could not open VD Regions viewer:', err);
-        //   }
-        // }
       } catch (err: any) {
         grok.shell.error(`Numbering failed: ${err.message ?? err}`);
         console.error(err);

package/src/utils/antibody-numbering/immunum-client.ts

@@ -0,0 +1,45 @@
+import type {
+  ImmunumNumberingRow, ImmunumWorkerRequest, ImmunumWorkerResponse,
+} from './types';
+
+/** Short-lived worker: we spin it up per call and tear it down immediately
+ *  after. Numbering is a one-shot batch operation — keeping the worker alive
+ *  would pin the immunum WASM instance (≈700 KB) in memory indefinitely. */
+function spawnWorker(): Worker {
+  return new Worker(new URL('./immunum.worker', import.meta.url));
+}
+
+function callOnce(worker: Worker, req: ImmunumWorkerRequest): Promise<ImmunumWorkerResponse> {
+  return new Promise((resolve, reject) => {
+    const ch = new MessageChannel();
+    ch.port1.onmessage = ({data}) => {
+      ch.port1.close();
+      resolve(data as ImmunumWorkerResponse);
+    };
+    ch.port1.onmessageerror = (err) => {
+      ch.port1.close();
+      reject(err);
+    };
+    worker.postMessage({req}, [ch.port2]);
+  });
+}
+
+/** Runs immunum numbering on a batch of sequences inside a web worker. Spawns a
+ *  fresh worker for this call and terminates it before returning so the WASM
+ *  instance is freed. Throws on WASM/init errors; individual per-row errors
+ *  are attached to each row's `error` field. */
+export async function numberSequencesWithImmunum(
+  sequences: string[],
+  scheme: string,
+  chains?: string[],
+  minConfidence?: number | null,
+): Promise<ImmunumNumberingRow[]> {
+  const worker = spawnWorker();
+  try {
+    const resp = await callOnce(worker, {op: 'number', sequences, scheme, chains, minConfidence});
+    if (!resp.ok) throw new Error(resp.error);
+    return resp.rows ?? [];
+  } finally {
+    worker.terminate();
+  }
+}