@datagrok/bio 2.27.2 → 2.27.4

package/src/utils/antibody-numbering/number-antibody.ts

@@ -0,0 +1,105 @@
+import * as DG from 'datagrok-api/dg';
+
+import {
+  NumberingScheme, ChainType, SCHEME_REGIONS,
+} from '@datagrok-libraries/bio/src/utils/macromolecule/numbering-schemes';
+
+import {numberSequencesWithImmunum} from './immunum-client';
+
+/** Normalizes an incoming scheme string to the immunum library's accepted values.
+ *  The engine only supports 'imgt' and 'kabat'; the dialog's scheme dropdown is
+ *  populated from the `choices` option on this function's `scheme` parameter, so
+ *  in practice only those two values reach here. */
+function toImmunumScheme(scheme: string): 'imgt' | 'kabat' {
+  return (scheme || '').toLowerCase() === 'kabat' ? 'kabat' : 'imgt';
+}
+
+/** Converts the scheme string to the enum value used by the region-table lookup. */
+function toSchemeEnum(scheme: string): NumberingScheme {
+  return (scheme || '').toLowerCase() === 'kabat' ? NumberingScheme.Kabat : NumberingScheme.IMGT;
+}
+
+/** Immunum returns 'Heavy' / 'Light' but region tables key on Heavy / Light_Kappa
+ *  / Light_Lambda. Use chain code to disambiguate: K → Light_Kappa, L → Light_Lambda.
+ *  Unknown chains fall back to Heavy so the dialog still gets *some* region set. */
+function toRegionChainKey(chainGroup: string, chainCode: string): ChainType {
+  if (chainGroup === 'Light')
+    return chainCode === 'L' ? ChainType.Light_Lambda : ChainType.Light_Kappa;
+  return ChainType.Heavy;
+}
+
+/** Builds a row's region-annotation JSON matching the antpack script output:
+ *  each entry has id/name/description/start/end/visualType/category/sourceScheme.
+ *  The `start` and `end` are **scheme-position codes** (strings), not character
+ *  indices — the dialog resolves them to chars via numbering_map. */
+function buildRegionAnnotations(
+  schemeLabel: string, chainGroup: string, chainCode: string,
+): any[] {
+  if (!chainGroup) return [];
+  const schemeEnum = toSchemeEnum(schemeLabel);
+  const regions = SCHEME_REGIONS[schemeEnum];
+  const chainKey = toRegionChainKey(chainGroup, chainCode);
+  const regionDefs = regions?.[chainKey];
+  if (!regionDefs) return [];
+  const schemeLower = schemeLabel.toLowerCase();
+  return regionDefs.map((r) => ({
+    id: `${schemeLower}-${chainGroup}-${r.name}`.toLowerCase(),
+    name: r.name,
+    description: `${r.name} (${schemeLabel.toUpperCase()} ${r.startPosition}-${r.endPosition})`,
+    start: r.startPosition,
+    end: r.endPosition,
+    visualType: 'region',
+    category: 'structure',
+    sourceScheme: schemeLabel.toUpperCase(),
+    autoGenerated: true,
+  }));
+}
+
+/** Runs immunum numbering on a sequence column and returns a DataFrame matching
+ *  the shape expected by `numbering-ui.ts` (same columns as the antpack Python
+ *  script `number_antibody.py`):
+ *  - `position_names`      — comma-separated list of numbered position codes
+ *  - `chain_type`          — 'Heavy' | 'Light' | ''
+ *  - `annotations_json`    — JSON array of FR/CDR region definitions
+ *  - `numbering_detail`    — JSON array of {position, aa} per numbered residue
+ *  - `numbering_map`       — JSON object mapping position code → char index
+ *
+ *  The numbering runs in a web worker (see `immunum.worker.ts`) so the main
+ *  thread stays responsive even for large columns. */
+export async function numberAntibodyColumn(
+  seqCol: DG.Column<string>,
+  scheme: string,
+): Promise<DG.DataFrame> {
+  const n = seqCol.length;
+  const sequences: string[] = new Array(n);
+  for (let i = 0; i < n; i++)
+    sequences[i] = seqCol.get(i) ?? '';
+
+  const immunumScheme = toImmunumScheme(scheme);
+  const rows = await numberSequencesWithImmunum(sequences, immunumScheme);
+
+  const posCol = DG.Column.fromType(DG.COLUMN_TYPE.STRING, 'position_names', n);
+  const chainCol = DG.Column.fromType(DG.COLUMN_TYPE.STRING, 'chain_type', n);
+  const annotCol = DG.Column.fromType(DG.COLUMN_TYPE.STRING, 'annotations_json', n);
+  const detailCol = DG.Column.fromType(DG.COLUMN_TYPE.STRING, 'numbering_detail', n);
+  const mapCol = DG.Column.fromType(DG.COLUMN_TYPE.STRING, 'numbering_map', n);
+
+  for (let i = 0; i < n; i++) {
+    const r = rows[i];
+    if (!r || r.error || !r.positionNames) {
+      posCol.set(i, '');
+      chainCol.set(i, '');
+      annotCol.set(i, '[]');
+      detailCol.set(i, '');
+      mapCol.set(i, '');
+      continue;
+    }
+    posCol.set(i, r.positionNames);
+    chainCol.set(i, r.chainType);
+    annotCol.set(i, JSON.stringify(buildRegionAnnotations(scheme, r.chainType, r.chainCode)));
+    detailCol.set(i, JSON.stringify(r.numberingDetail));
+    mapCol.set(i, JSON.stringify(r.numberingMap));
+  }
+
+  return DG.DataFrame.fromColumns([posCol, chainCol, annotCol, detailCol, mapCol]);
+}

package/src/utils/antibody-numbering/types.ts

@@ -0,0 +1,48 @@
+/** Position → amino-acid entry in the numbering detail JSON. */
+export interface ImmunumNumberingEntry {
+  /** Position code (e.g. "1", "27A"). */
+  position: string;
+  /** Single-letter residue at this position. */
+  aa: string;
+}
+
+/** Per-row numbering result produced by the immunum worker. */
+export interface ImmunumNumberingRow {
+  /** Comma-separated position codes in scheme order. Empty string on failure. */
+  positionNames: string;
+  /** 'Heavy' / 'Light' / '' — UI-facing chain group. */
+  chainType: string;
+  /** Immunum chain code: H, K, L, A, B, G, D, or ''. */
+  chainCode: string;
+  /** Ordered list of {position, aa} entries for the aligned region. */
+  numberingDetail: ImmunumNumberingEntry[];
+  /** Map from position code → character index in the extracted (gap-free) sequence. */
+  numberingMap: Record<string, number>;
+  /** Alignment confidence in [0, 1]. */
+  confidence: number;
+  /** Error message, empty string on success. */
+  error: string;
+}
+
+export type ImmunumWorkerRequest =
+  | {op: 'init'}
+  | {
+      op: 'number';
+      sequences: string[];
+      /** Immunum scheme: 'imgt' or 'kabat'. */
+      scheme: string;
+      /** Case-insensitive chain codes (e.g. ['H', 'K', 'L']). Defaults to H/K/L. */
+      chains?: string[];
+      /** Minimum confidence in [0, 1]; null/undefined → library default (0.5). */
+      minConfidence?: number | null;
+    };
+
+export type ImmunumWorkerResponse =
+  | {ok: true; rows?: ImmunumNumberingRow[]}
+  | {ok: false; error: string};
+
+/** Supported schemes by immunum. Chothia/AHo are not supported — the UI engine
+ *  dropdown lists all schemes globally so the immunum path falls back for the
+ *  unsupported ones by returning empty rows with errors. */
+export const IMMUNUM_SCHEMES = ['imgt', 'kabat'] as const;
+export type ImmunumScheme = typeof IMMUNUM_SCHEMES[number];

package/src/utils/seq-helper/seq-handler.ts

@@ -11,7 +11,7 @@ import {detectAlphabet, detectHelmAlphabet, splitterAsFastaSimple, StringListSeq
 import {mmDistanceFunctions, MmDistanceFunctionsNames} from '@datagrok-libraries/ml/src/macromolecule-distance-functions';
 import {mmDistanceFunctionType} from '@datagrok-libraries/ml/src/macromolecule-distance-functions/types';
 import {getMonomerLibHelper, IMonomerLibHelper} from '@datagrok-libraries/bio/src/types/monomer-library';
-import {HELM_POLYMER_TYPE, HELM_WRAPPERS_REGEXP, PHOSPHATE_SYMBOL} from '@datagrok-libraries/bio/src/utils/const';
+import {DEOXYRIBOSE_SYMBOL, HELM_POLYMER_TYPE, HELM_WRAPPERS_REGEXP, PHOSPHATE_SYMBOL, RIBOSE_SYMBOL} from '@datagrok-libraries/bio/src/utils/const';
 import {GAP_SYMBOL, GapOriginals} from '@datagrok-libraries/bio/src/utils/macromolecule/consts';
 import {CellRendererBackBase, GridCellRendererTemp} from '@datagrok-libraries/bio/src/utils/cell-renderer-back-base';
 import {HelmTypes} from '@datagrok-libraries/bio/src/helm/consts';
@@ -939,6 +939,11 @@ export class SeqHandler implements ISeqHandler {
 
       if (cm === GAP_SYMBOL)
         om = GapOriginals[NOTATION.FASTA];
+      // For HELM RNA, the splitter triplet-splits each nucleotide into
+      // [sugar, base, phosphate]; FASTA conversion keeps only the base, so
+      // drop standalone sugar/phosphate tokens.
+      else if (isHelm && (cm === PHOSPHATE_SYMBOL || cm === RIBOSE_SYMBOL || cm === DEOXYRIBOSE_SYMBOL))
+        om = '';
       else if (cm === PHOSPHATE_SYMBOL)
         om = '';
       else if (om.length > 1)
@@ -978,7 +983,9 @@ export class SeqHandler implements ISeqHandler {
     return joinToBiln(srcSS);
   }
 
-  /** Splits Helm sequence adjusting nucleotides to single char symbols. (!) Removes lone phosphorus. */
+  /** Splits Helm sequence adjusting nucleotides to single char symbols. (!) Removes lone phosphorus,
+   *  ribose, and deoxyribose tokens (which the underlying splitter emits when triplet-splitting
+   *  each nucleotide of an RNA chain). */
   private splitterAsHelmNucl(src: string): ISeqSplitted {
     const srcMList: ISeqSplitted = this.splitter(src);
     const tgtMList: (string | null)[] = new Array<string>(srcMList.length);
@@ -988,7 +995,8 @@ export class SeqHandler implements ISeqHandler {
       let om: string | null = srcMList.getOriginal(posIdx);
       if (isDna || isRna) {
         om = om.replace(HELM_WRAPPERS_REGEXP, '$1');
-        om = om === PHOSPHATE_SYMBOL ? null : om;
+        if (om === PHOSPHATE_SYMBOL || om === RIBOSE_SYMBOL || om === DEOXYRIBOSE_SYMBOL)
+          om = null;
       }
       tgtMList[posIdx] = om ? om : null;
     }
@@ -1009,18 +1017,26 @@ export class SeqHandler implements ISeqHandler {
 // -- joiners --
 
 function joinToSeparator(seqS: ISeqSplitted, tgtSeparator: string, isHelm: boolean): string {
-  const resMList: string[] = new Array<string>(seqS.length);
+  const resMList: string[] = [];
   for (let posIdx: number = 0; posIdx < seqS.length; ++posIdx) {
     const cm = seqS.getCanonical(posIdx);
     let om = seqS.getOriginal(posIdx);
     if (isHelm)
       om = om.replace(HELM_WRAPPERS_REGEXP, '$1');
 
-    if (cm === GAP_SYMBOL)
-      om = GapOriginals[NOTATION.SEPARATOR];
-    else if (cm === PHOSPHATE_SYMBOL)
-      om = '';
-    resMList[posIdx] = om;
+    if (cm === GAP_SYMBOL) {
+      resMList.push(GapOriginals[NOTATION.SEPARATOR]);
+      continue;
+    }
+    // For HELM RNA, the splitter triplet-splits each nucleotide into
+    // [sugar, base, phosphate]; separator conversion keeps only the base, so
+    // skip standalone sugar/phosphate tokens entirely (rather than emitting
+    // an empty cell that would show up as an extra separator in the output).
+    if (isHelm && (cm === PHOSPHATE_SYMBOL || cm === RIBOSE_SYMBOL || cm === DEOXYRIBOSE_SYMBOL))
+      continue;
+    if (cm === PHOSPHATE_SYMBOL)
+      continue;
+    resMList.push(om);
   }
   return resMList.join(tgtSeparator);
 }