@datagrok/bio 2.27.2 → 2.27.4

package/package.json

@@ -5,7 +5,7 @@
     "name": "Davit Rizhinashvili",
     "email": "drizhinashvili@datagrok.ai"
   },
-  "version": "2.27.2",
+  "version": "2.27.4",
   "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.7",
+    "@datagrok-libraries/bio": "^5.64.0",
     "@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",

package/src/demo/bio01b-hierarchical-clustering-and-activity-cliffs.ts

@@ -13,6 +13,7 @@ import {DemoScript} from '@datagrok-libraries/tutorials/src/demo-script';
 import {MmDistanceFunctionsNames} from '@datagrok-libraries/ml/src/macromolecule-distance-functions';
 import {getClusterMatrixWorker} from '@datagrok-libraries/math';
 import {DimReductionMethods} from '@datagrok-libraries/ml/src/multi-column-dimensionality-reduction/types';
+import {awaitCheck} from '@datagrok-libraries/test/src/test';
 
 const dataFn: string = 'samples/FASTA_PT_activity.csv';
 
@@ -117,25 +118,37 @@ export async function demoActivityCliffsCyclic() {
   ui.setUpdateIndicator(tv.root, true);
   try {
     const seqEncodingFunc = DG.Func.find({name: 'macromoleculePreprocessingFunction', package: 'Bio'})[0];
-    const activityCliffsViewer = (await PackageFunctions.activityCliffs(
+    await PackageFunctions.activityCliffs(
       df, df.getCol('Sequence'), df.getCol('Activity'),
       96, DimReductionMethods.UMAP, MmDistanceFunctionsNames.MONOMER_CHEMICAL_DISTANCE,
-      seqEncodingFunc, {}, true)) as DG.ScatterPlotViewer;
-    tv.dockManager.dock(activityCliffsViewer, DG.DOCK_TYPE.RIGHT, null, 'Activity Cliffs', 0.65);
-    await DG.delay(100);
-    const cliffsLink: HTMLButtonElement = $(activityCliffsViewer.root)
-      .find('button.scatter_plot_link,cliffs_grid').get()[0] as HTMLButtonElement;
-    cliffsLink.click();
-    await DG.delay(100);
+      seqEncodingFunc, {}, true);
+
+    let scatterPlot: DG.Viewer | undefined;
+    await awaitCheck(() => {
+      for (const v of tv.viewers) {
+        if (v.type === DG.VIEWER.SCATTER_PLOT) {
+          scatterPlot = v;
+          return true;
+        }
+      }
+      return false;
+    }, '', 10000);
+
+    let link: HTMLCollectionOf<Element> | undefined;
+    await awaitCheck(() => {
+      link = scatterPlot!.root.getElementsByClassName('scatter_plot_link');
+      return link.length > 0;
+    }, '', 5000);
+    (link![0] as HTMLElement).click();
+    await DG.delay(500);
+
     tv.grid.props.rowHeight = 180;
     tv.grid.col('sequence') && (tv.grid.col('sequence')!.width = 300);
     tv.grid.col('structure') && (tv.grid.col('structure')!.width = 300);
     const cliffsGrid = Array.from(tv.viewers).find((v) => v !== tv.grid && v.type === DG.VIEWER.GRID) as DG.Grid;
     if (cliffsGrid) {
       cliffsGrid.props.rowHeight = 40;
-      cliffsGrid.col('seq_diff')!.width = 600;
-      tv.dockManager.dock(cliffsGrid, DG.DOCK_TYPE.DOWN, null, 'Cliffs', 0.35);
-      tv.dockManager.dock(activityCliffsViewer, DG.DOCK_TYPE.RIGHT, null, 'Activity Cliffs', 0.55);
+      cliffsGrid.col('seq_diff') && (cliffsGrid.col('seq_diff')!.width = 600);
     }
   } catch (err: any) {
     handleError(err);

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,17 @@ 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...

package/src/package.ts

@@ -86,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}/**/);
@@ -479,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({
@@ -492,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({
@@ -501,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({
@@ -993,6 +997,20 @@ 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)',

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/tests/detectors-tests.ts

@@ -462,8 +462,12 @@ MWRSWY-CKHPMWRSWY-CKHP`;
   // sample_testHelm.csv
   // columns: ID,Test type,HELM string,Valid?,Mol Weight,Mol Formula,SMILES
   test('samplesTestHelmCsv', async () => {
+    // Alphabet size of 8 reflects splitterAsHelm's triplet-splitting of HELM
+    // RNA monomers (each `sugar(base)phosphate` becomes 3 tokens), which can
+    // collapse what used to be N distinct triple-tokens into a smaller union
+    // of {sugar(s), bases, phosphate(s)} symbols.
     await _testDf(readSamples(Samples.testHelmCsv), {
-      'HELM string': new PosCol(NOTATION.HELM, null, null, 9, true),
+      'HELM string': new PosCol(NOTATION.HELM, null, null, 8, true),
     }, seqHelper);
   });
 

package/src/tests/splitters-test.ts

@@ -59,18 +59,22 @@ category('splitters', async () => {
         'D-Tyr_Et', 'D-Dap', 'dV', 'E', 'N', 'pnG', 'Phe_4Me'],
     ],
 
+    // splitterAsHelm triplet-splits HELM RNA monomers `sugar(base)phosphate`
+    // into 3 tokens, and `sugar(base)` (terminal-only) into 2. Standalone
+    // tokens that don't match either form (e.g. lone `P`, or non-terminal
+    // `R(U)` without a phosphate) are kept verbatim.
     testHelm1: [
       'RNA1{R(U)P.R(T)P.R(G)P.R(C)P.R(A)}$$$$',
-      ['R(U)P', 'R(T)P', 'R(G)P', 'R(C)P', 'R(A)'],
+      ['R', 'U', 'P', 'R', 'T', 'P', 'R', 'G', 'P', 'R', 'C', 'P', 'R', 'A'],
     ],
 
     testHelm2: [
       'RNA1{P.R(U)P.R(T)}$$$$',
-      ['P', 'R(U)P', 'R(T)'],
+      ['P', 'R', 'U', 'P', 'R', 'T'],
     ],
     testHelm3: [
-      'RNA1{P.R(U).P.R(T)}$$$$',
-      ['P', 'R(U)', 'P', 'R(T)'],
+      'RNA1{P.R(U).P.R(T)}$$$$', // invalid helm, but oh well,
+      ['P', 'R(U)', 'P', 'R', 'T'],
     ],
   };
 

package/src/tests/to-atomic-level-tests.ts

@@ -356,6 +356,150 @@ PEPTIDE1{Lys_Boc.hHis.Aca.Cys_SEt.T.dK.Thr_PO3H2.Aca.Tyr_PO3H2.Thr_PO3H2.Aca.Tyr
   }
 });
 
+/** Tests for the linear HELM-RNA path: must preserve modified sugars,
+ * phosphates, and bases per nucleotide. The non-linear (HELM via POM)
+ * path is the reference; the linear path is expected to match it on
+ * canonical SMILES for these inputs. */
+category('toAtomicLevelHelmRna', async () => {
+  let monomerLibHelper: IMonomerLibHelper;
+  let userLibSettings: UserLibSettings;
+  let seqHelper: ISeqHelper;
+  let monomerLib: IMonomerLib;
+  let rdKitModule: RDModule;
+
+  before(async () => {
+    rdKitModule = await getRdKitModule();
+    seqHelper = await getSeqHelper();
+    monomerLibHelper = await getMonomerLibHelper();
+    userLibSettings = await getUserLibSettings();
+    await monomerLibHelper.loadMonomerLibForTests();
+    monomerLib = monomerLibHelper.getMonomerLib();
+  });
+
+  after(async () => {
+    await setUserLibSettings(userLibSettings);
+    await monomerLibHelper.loadMonomerLib(true);
+  });
+
+  /** Build a single-row HELM RNA dataframe and run the linear converter,
+   * returning the canonical SMILES of the resulting molfile. */
+  async function helmRnaLinearToSmiles(srcHelm: string): Promise<string> {
+    const srcCsv = `seq\n${srcHelm}`;
+    const df = DG.DataFrame.fromCsv(srcCsv);
+    await grok.data.detectSemanticTypes(df);
+    const seqCol = df.getCol('seq');
+    expect(seqCol.semType, DG.SEMTYPE.MACROMOLECULE);
+
+    const res = await _toAtomicLevel(df, seqCol, monomerLib, seqHelper, rdKitModule);
+    if (!res.molCol)
+      throw new Error(`_toAtomicLevel returned no molCol for HELM '${srcHelm}'. ` +
+        `Warnings: ${(res.warnings ?? []).join(' / ')}`);
+
+    const molfile: string | null = res.molCol.get(0);
+    if (!molfile)
+      throw new Error(`_toAtomicLevel produced an empty molfile for HELM '${srcHelm}'`);
+    let smiles: string;
+    try {
+      smiles = grok.chem.convert(molfile, grok.chem.Notation.Unknown, grok.chem.Notation.Smiles);
+    } catch (err: any) {
+      throw new Error(`SMILES conversion threw for HELM '${srcHelm}': ${err?.message ?? err}\n` +
+        `--- MOLFILE START ---\n${molfile}\n--- MOLFILE END ---`);
+    }
+    // RDKit signals a parse failure by returning the literal string
+    // "MALFORMED_INPUT_VALUE" — surface it together with the offending molfile.
+    if (smiles === 'MALFORMED_INPUT_VALUE' || /^MALFORMED/.test(smiles)) {
+      throw new Error(`RDKit could not parse molfile produced for HELM '${srcHelm}'.\n` +
+        `--- MOLFILE START ---\n${molfile}\n--- MOLFILE END ---`);
+    }
+    return smiles;
+  }
+
+  // Unmodified RNA HELM — regression baseline. The linear path must produce
+  // a real RNA backbone (sugar + phosphate + base per nucleotide), not just
+  // a chain of bases.
+  test('rna-canonical', async () => {
+    const smiles = await helmRnaLinearToSmiles(`RNA1{r(A)p.r(C)p.r(G)p}$$$$`);
+    // Should at minimum contain phosphate (P), ribose oxygens, and a purine ring.
+    expect(/P/.test(smiles), true, `expected phosphate in SMILES: ${smiles}`);
+    // Purine fragment (any ring closure digit): n<d>cnc<d> or N<d>C=N (case insensitive).
+    expect(/n\dcnc\d/.test(smiles) || /n\dcnc/i.test(smiles), true,
+      `expected purine ring fragment in SMILES: ${smiles}`);
+  });
+
+  // Modified base — 5-methylcytosine. Linear path should preserve the
+  // methyl branch on the cytidine of position 0.
+  test('rna-modified-base', async () => {
+    const smilesPlain = await helmRnaLinearToSmiles(`RNA1{r(C)p.r(A)p}$$$$`);
+    const smilesMod = await helmRnaLinearToSmiles(`RNA1{r([m5C])p.r(A)p}$$$$`);
+    expect(smilesPlain !== smilesMod, true,
+      `m5C must change the SMILES vs. plain C. plain=${smilesPlain} mod=${smilesMod}`);
+  });
+
+  // Modified phosphate — phosphorothioate. The linker between positions 0
+  // and 1 must change (S replaces a non-bridging O).
+  test('rna-modified-phosphate', async () => {
+    const smilesPlain = await helmRnaLinearToSmiles(`RNA1{r(A)p.r(C)p}$$$$`);
+    const smilesMod = await helmRnaLinearToSmiles(`RNA1{r(A)[Rsp].r(C)p}$$$$`);
+    expect(smilesPlain !== smilesMod, true,
+      `Rsp phosphorothioate must change the SMILES vs. plain p. plain=${smilesPlain} mod=${smilesMod}`);
+    expect(/S/.test(smilesMod), true,
+      `expected sulfur in phosphorothioate SMILES: ${smilesMod}`);
+    // HELM explicitly wrote 2 phosphates (one Rsp at position 0, one p at
+    // position 1); both must appear in the molecule, so two P atoms total.
+    const pCountPlain = (smilesPlain.match(/P/g) || []).length;
+    const pCountMod = (smilesMod.match(/P/g) || []).length;
+    expect(pCountPlain, 2, `expected 2 phosphates in plain: ${smilesPlain}`);
+    expect(pCountMod, 2, `expected 2 phosphates in modified: ${smilesMod}`);
+  });
+
+  // Modified sugar — 2'-fluoro ribose. Position 0 sugar gets a fluorine.
+  test('rna-modified-sugar', async () => {
+    const smilesPlain = await helmRnaLinearToSmiles(`RNA1{r(A)p.r(C)p}$$$$`);
+    const smilesMod = await helmRnaLinearToSmiles(`RNA1{[fl2r](A)p.r(C)p}$$$$`);
+    expect(smilesPlain !== smilesMod, true,
+      `fl2r (2'-F ribose) must change the SMILES vs. plain r. plain=${smilesPlain} mod=${smilesMod}`);
+    expect(/F/.test(smilesMod), true,
+      `expected fluorine in 2'-F ribose SMILES: ${smilesMod}`);
+  });
+
+  // HELM omits the trailing phosphate (3'-OH terminus on the sugar). The
+  // splitter must split the partial `r(C)` into [r, C], assembly must skip
+  // the trailing P emit, and counts must agree.
+  test('rna-no-trailing-phosphate', async () => {
+    const smilesWith = await helmRnaLinearToSmiles(`RNA1{r(A)p.r(C)p}$$$$`);
+    const smilesNoTail = await helmRnaLinearToSmiles(`RNA1{r(A)p.r(C)}$$$$`);
+    // Both should produce valid molecules with at least one P (the linker
+    // between the two nucleotides is always present).
+    expect(/P/.test(smilesNoTail), true,
+      `expected the inter-nucleotide phosphate to remain: ${smilesNoTail}`);
+    // The version WITH trailing phosphate should have exactly one more P
+    // atom than the version without.
+    const pCountWith = (smilesWith.match(/P/g) || []).length;
+    const pCountNoTail = (smilesNoTail.match(/P/g) || []).length;
+    expect(pCountWith, pCountNoTail + 1,
+      `expected pCountWith - pCountNoTail === 1, got with=${pCountWith}, noTail=${pCountNoTail}. ` +
+      `with=${smilesWith}, noTail=${smilesNoTail}`);
+  });
+
+  // Missing trailing phosphate combined with modifications.
+  test('rna-no-trailing-phosphate-with-modifications', async () => {
+    const smiles = await helmRnaLinearToSmiles(`RNA1{[fl2r]([m5C])[Rsp].r(A)}$$$$`);
+    expect(/F/.test(smiles), true, `expected fluorine: ${smiles}`);
+    expect(/S/.test(smiles), true, `expected sulfur: ${smiles}`);
+    // Exactly one phosphate (the Rsp linker), no trailing P.
+    const pCount = (smiles.match(/P/g) || []).length;
+    expect(pCount, 1, `expected exactly 1 phosphate: ${smiles}`);
+  });
+
+  // All three modifications combined. End-to-end smoke test.
+  test('rna-all-modifications', async () => {
+    const smiles = await helmRnaLinearToSmiles(`RNA1{[fl2r]([m5C])[Rsp].r(A)p}$$$$`);
+    expect(/F/.test(smiles), true, `expected fluorine: ${smiles}`);
+    expect(/S/.test(smiles), true, `expected sulfur: ${smiles}`);
+    expect(/P/.test(smiles), true, `expected phosphorus: ${smiles}`);
+  });
+});
+
 
 function polishMolfile(mol: string): string {
   return mol.replaceAll('\r\n', '\n')