@datagrok/bio 2.26.7 → 2.27.0

package/src/utils/pepsea.ts

@@ -1,7 +1,5 @@
-/* eslint-disable max-params */
 /* Do not change these import lines to match external modules in webpack configuration */
 import * as grok from 'datagrok-api/grok';
-import * as ui from 'datagrok-api/ui';
 import * as DG from 'datagrok-api/dg';
 
 import {NOTATION, TAGS as bioTAGS, ALIGNMENT, ALPHABET} from '@datagrok-libraries/bio/src/utils/macromolecule';
@@ -9,9 +7,22 @@ import {ILogger} from '@datagrok-libraries/bio/src/utils/logger';
 
 import {checkForSingleSeqClusters} from './multiple-sequence-alignment';
 import * as C from './constants';
-
 import {_package} from '../package';
 
+export const pepseaMethods = ['mafft --auto', 'mafft', 'linsi', 'ginsi', 'einsi', 'fftns', 'fftnsi', 'nwns', 'nwnsi'];
+
+const ALIGNMENT_META_KEYS = ['AlignedSeq', 'AlignedSubpeptide', 'HELM', 'ID', 'PolymerID'];
+
+type PepseaResponse = {
+  Alignment: {
+    PolymerID: string; AlignedSubpeptide: string; HELM: string;
+    ID: string; AlignedSeq: string; [key: string]: string;
+  }[];
+  AlignmentScore: {[key: string]: number | null};
+};
+
+type PepseaBodyUnit = {ID: string; HELM: string};
+
 export const Pepsea = new class {
   public readonly dcName: string = 'bio';
 
@@ -20,103 +31,117 @@ export const Pepsea = new class {
   }
 }();
 
-export const pepseaMethods = ['mafft --auto', 'mafft', 'linsi', 'ginsi', 'einsi', 'fftns', 'fftnsi', 'nwns', 'nwnsi'];
-const alignmentObjectMetaKeys = ['AlignedSeq', 'AlignedSubpeptide', 'HELM', 'ID', 'PolymerID'];
-type PepseaResponse = {
-  Alignment: {
-    PolymerID: string, AlignedSubpeptide: string, HELM: string, ID: string, AlignedSeq: string, [key: string]: string,
-  }[],
-  AlignmentScore: { [key: string]: number | null },
-};
-type PepseaBodyUnit = { ID: string, HELM: string };
-
-/** Gets the column containing MSA sequences produced by the 'PepSeA' tool from the {@link srcCol} column.
- * Does not add the result column to the dataframe of {@link srcCol}.
- * @async
- * @param {DG.Column} srcCol - The column containing the sequences to be aligned.
- * @param {string} unUsedName - The name of the result column.
- * @param {string} method - The method used for alignment.
- * @param {number} gapOpen - The gap open penalty.
- * @param {number} gapExtend - The gap extension penalty.
- * @param {DG.Column} clustersCol - The column containing the clusters of the sequences.
- * @param logger {ILogger} Logger
- */
-export async function runPepsea(table: DG.DataFrame, srcCol: DG.Column<string>, unUsedName: string,
+
+/** Aligns all sequences in the column using PepSeA Docker container.
+ * Does not handle clustering - aligns all rows as a single group.
+ * Used by the registered sequenceMSA function. */
+export async function alignWithPepsea(
+  srcCol: DG.Column<string>,
+  method: string = 'mafft --auto',
+  gapOpen: number = 1.53,
+  gapExtend: number = 0,
+): Promise<DG.Column<string>> {
+  const container = await Pepsea.getDockerContainer();
+  const rowCount = srcCol.length;
+
+  const body: PepseaBodyUnit[] = [];
+  for (let i = 0; i < rowCount; i++) {
+    const seq = srcCol.get(i);
+    if (seq)
+      body.push({ID: i.toString(), HELM: seq});
+  }
+
+  const response = await requestAlignedObjects(container.id, body, method, gapOpen, gapExtend);
+  const aligned = parseAlignmentResponse(response, rowCount);
+
+  const colName = srcCol.dataFrame?.columns?.getUnusedName(`msa(${srcCol.name})`) ?? `msa(${srcCol.name})`;
+  return createPepseaResultColumn(colName, aligned);
+}
+
+
+/** Aligns sequences with PepSeA, supporting per-cluster alignment.
+ * Used by tests and legacy code paths. */
+export async function runPepsea(
+  table: DG.DataFrame, srcCol: DG.Column<string>, unUsedName: string,
   method: typeof pepseaMethods[number] = 'ginsi', gapOpen: number = 1.53, gapExtend: number = 0.0,
-  clustersCol: DG.Column<string | number> | null = null, logger?: ILogger, onlySelected: boolean = false
+  clustersCol: DG.Column<string | number> | null = null, logger?: ILogger, onlySelected: boolean = false,
 ): Promise<DG.Column<string>> {
-  const pepseaContainer = await Pepsea.getDockerContainer();
-  const peptideCount = srcCol.length;
-  clustersCol ??= DG.Column.int('Clusters', peptideCount).init(0);
-  if (clustersCol.type != DG.COLUMN_TYPE.STRING)
+  const container = await Pepsea.getDockerContainer();
+  const rowCount = srcCol.length;
+
+  clustersCol ??= DG.Column.int('Clusters', rowCount).init(0);
+  if (clustersCol.type !== DG.COLUMN_TYPE.STRING)
     clustersCol = clustersCol.convertTo(DG.TYPE.STRING);
 
-  const clustersColCategories = clustersCol.categories;
-  const clustersColData = clustersCol.getRawData();
-  const bodies: PepseaBodyUnit[][] = new Array(clustersColCategories.length);
-  const clusterIndexes: number[][] = new Array(clustersColCategories.length);
-
-  // Grouping data by clusters
-  if (!onlySelected) {
-    for (let rowIndex = 0; rowIndex < peptideCount; ++rowIndex) {
-      const clusterCategoryIdx = clustersColData[rowIndex];
-      const cluster = clustersColCategories[clusterCategoryIdx];
-      if (!cluster)
-        continue;
-
-      const clusterId = clusterCategoryIdx;
-      const helmSeq = srcCol.get(rowIndex);
-      if (helmSeq) {
-        (bodies[clusterId] ??= []).push({ID: rowIndex.toString(), HELM: helmSeq});
-        (clusterIndexes[clusterCategoryIdx] ??= []).push(rowIndex);
-      }
-    }
-  } else {
-    const selection = table.selection;
-    for (let rowIndex = -1; (rowIndex = selection.findNext(rowIndex, true)) !== -1;) {
-      const clusterCategoryIdx = clustersColData[rowIndex];
-      const cluster = clustersColCategories[clusterCategoryIdx];
-      if (!cluster)
-        continue;
-
-      const clusterId = clusterCategoryIdx;
-      const helmSeq = srcCol.get(rowIndex);
-      if (helmSeq) {
-        (bodies[clusterId] ??= []).push({ID: rowIndex.toString(), HELM: helmSeq});
-        (clusterIndexes[clusterCategoryIdx] ??= []).push(rowIndex);
-      }
+  const categories = clustersCol.categories;
+  const data = clustersCol.getRawData();
+  const bodies: PepseaBodyUnit[][] = new Array(categories.length);
+  const clusterIndexes: number[][] = new Array(categories.length);
+
+  const rows = onlySelected ? selectedRows(table.selection) : allRows(rowCount);
+  for (const rowIndex of rows) {
+    const catIdx = data[rowIndex];
+    if (!categories[catIdx]) continue;
+    const helmSeq = srcCol.get(rowIndex);
+    if (helmSeq) {
+      (bodies[catIdx] ??= []).push({ID: rowIndex.toString(), HELM: helmSeq});
+      (clusterIndexes[catIdx] ??= []).push(rowIndex);
     }
   }
-  checkForSingleSeqClusters(clusterIndexes, clustersColCategories);
-
-  const alignedSequences: string[] = new Array(peptideCount).fill(null);
-  for (const body of bodies) { // getting aligned sequences for each cluster
-    if (!body || body.length === 0)
-      continue;
-    const alignedObject = await requestAlignedObjects(pepseaContainer.id, body, method, gapOpen, gapExtend, logger);
-    const alignments = alignedObject.Alignment;
-
-    for (const alignment of alignments) { // filling alignedSequencesCol
-      alignedSequences[parseInt(alignment.ID)] = Object.entries(alignment)
-        .filter((v) => !alignmentObjectMetaKeys.includes(v[0]))
-        .map((v) => v[1] !== '-' ? v[1] : '')
-        .join(C.PEPSEA.SEPARATOR);
-    }
+  checkForSingleSeqClusters(clusterIndexes, categories);
+
+  const alignedSequences: string[] = new Array(rowCount).fill(null);
+  for (const body of bodies) {
+    if (!body || body.length === 0) continue;
+    const response = await requestAlignedObjects(container.id, body, method, gapOpen, gapExtend, logger);
+    for (const alignment of response.Alignment)
+      alignedSequences[parseInt(alignment.ID)] = extractAlignedSequence(alignment);
   }
 
-  const alignedSequencesCol: DG.Column<string> = DG.Column.fromStrings(unUsedName, alignedSequences);
-  alignedSequencesCol.meta.units = NOTATION.SEPARATOR;
-  alignedSequencesCol.setTag(bioTAGS.separator, C.PEPSEA.SEPARATOR);
-  alignedSequencesCol.setTag(bioTAGS.aligned, ALIGNMENT.SEQ_MSA);
-  alignedSequencesCol.setTag(bioTAGS.alphabet, ALPHABET.UN);
-  alignedSequencesCol.setTag(bioTAGS.alphabetIsMultichar, 'true');
-  alignedSequencesCol.semType = DG.SEMTYPE.MACROMOLECULE;
+  return createPepseaResultColumn(unUsedName, alignedSequences);
+}
+
+
+// --- Helpers ---
+
+function extractAlignedSequence(alignment: PepseaResponse['Alignment'][0]): string {
+  return Object.entries(alignment)
+    .filter(([key]) => !ALIGNMENT_META_KEYS.includes(key))
+    .map(([, val]) => val !== '-' ? val : '')
+    .join(C.PEPSEA.SEPARATOR);
+}
+
+function parseAlignmentResponse(response: PepseaResponse, rowCount: number): string[] {
+  const aligned: string[] = new Array(rowCount).fill(null);
+  for (const alignment of response.Alignment)
+    aligned[parseInt(alignment.ID)] = extractAlignedSequence(alignment);
+  return aligned;
+}
+
+function createPepseaResultColumn(name: string, sequences: string[]): DG.Column<string> {
+  const col = DG.Column.fromStrings(name, sequences);
+  col.meta.units = NOTATION.SEPARATOR;
+  col.setTag(bioTAGS.separator, C.PEPSEA.SEPARATOR);
+  col.setTag(bioTAGS.aligned, ALIGNMENT.SEQ_MSA);
+  col.setTag(bioTAGS.alphabet, ALPHABET.UN);
+  col.setTag(bioTAGS.alphabetIsMultichar, 'true');
+  col.semType = DG.SEMTYPE.MACROMOLECULE;
+  return col;
+}
 
-  return alignedSequencesCol;
+function* selectedRows(selection: DG.BitSet): Generator<number> {
+  for (let i = -1; (i = selection.findNext(i, true)) !== -1;)
+    yield i;
+}
+
+function* allRows(count: number): Generator<number> {
+  for (let i = 0; i < count; i++)
+    yield i;
 }
 
 async function requestAlignedObjects(
-  dockerfileId: string, body: PepseaBodyUnit[], method: string, gapOpen: number, gapExtend: number, logger?: ILogger
+  dockerfileId: string, body: PepseaBodyUnit[], method: string,
+  gapOpen: number, gapExtend: number, logger?: ILogger,
 ): Promise<PepseaResponse> {
   const params = {
     method: 'POST',
@@ -124,37 +149,34 @@ async function requestAlignedObjects(
     body: JSON.stringify(body),
   };
   const path = `/align?method=${method}&gap_open=${gapOpen}&gap_extend=${gapExtend}`;
-  // new dockerContainers API
-  const t1: number = window.performance.now();
+
+  const t1 = window.performance.now();
   // @ts-ignore
   const response: Response = await grok.dapi.docker.dockerContainers.fetchProxy(dockerfileId, path, params);
-  const t2: number = window.performance.now();
-  _package.logger.debug(`Bio: requestAlignedObjects() dockerContainers.fetchProxy(), ET: ${(t2 - t1)} ms`);
-  const responseContentType = response.headers.get('content-type');
-  const isJson: boolean = responseContentType === 'application/json';
-  if (!response.ok && isJson) {
-    const responseJson = await response.json();
-    const pepseaErrorMsg = responseJson['pepsea-error'];
-    if (!!pepseaErrorMsg)
-      throw new Error(`PepSeA error: ${pepseaErrorMsg}`);
-
-    const datagrokErrorMsg = responseJson['datagrok-error'];
-    if (!!datagrokErrorMsg)
-      throw new Error(`Datagrok error: ${datagrokErrorMsg}`);
-
-    throw new Error(response.statusText);
-  } else if (!response.ok && !isJson) {
-    const responseStr = await response.text();
-    throw new Error(`Error: ${responseStr}`);
-  } else if (!isJson) {
-    const responseStr = await response.text();
-    throw new Error(`Error: PepSeA expected JSON response, got '${responseStr}'.`);
+  const t2 = window.performance.now();
+  _package.logger.debug(`Bio: requestAlignedObjects() ET: ${(t2 - t1)} ms`);
+
+  const contentType = response.headers.get('content-type');
+  const isJson = contentType === 'application/json';
+
+  if (!response.ok) {
+    if (isJson) {
+      const json = await response.json();
+      if (json['pepsea-error']) throw new Error(`PepSeA error: ${json['pepsea-error']}`);
+      if (json['datagrok-error']) throw new Error(`Datagrok error: ${json['datagrok-error']}`);
+      throw new Error(response.statusText);
+    }
+    const text = await response.text();
+    throw new Error(`Error: ${text}`);
   }
-  const responseObj = await response.json();
-  // Check for pepsea stderr output
-  if ('pepsea-stderr' in responseObj) {
-    const pepseaStdErr: string = responseObj['pepsea-stderr'] as string;
-    logger?.warning(pepseaStdErr);
+
+  if (!isJson) {
+    const text = await response.text();
+    throw new Error(`Error: PepSeA expected JSON response, got '${text}'.`);
   }
+
+  const responseObj = await response.json();
+  if ('pepsea-stderr' in responseObj)
+    logger?.warning(responseObj['pepsea-stderr'] as string);
   return responseObj as PepseaResponse;
 }

package/src/utils/types.ts

@@ -1,5 +1,4 @@
 import * as DG from 'datagrok-api/dg';
-import {pepseaMethods} from './pepsea';
 
 export type DataFrameDict = { [key: string]: DG.DataFrame };
 
@@ -14,7 +13,11 @@ export type SubstitutionsInfo = Map<string, Map<string, Map<number, number[] | U
 export type SelectionObject = { [position: string]: string[] };
 
 export type MultipleSequenceAlignmentUIOptions = {
-  col?: DG.Column<string> | null, clustersCol?: DG.Column | null,
-  pepsea?: { method?: typeof pepseaMethods[number], gapOpen?: number, gapExtend?: number },
-  kalign?: { gapOpen?: number, gapExtend?: number, terminalGap?: number }
+  col?: DG.Column<string> | null;
+  clustersCol?: DG.Column | null;
+  kalign?: { gapOpen?: number; gapExtend?: number; terminalGap?: number };
+  /** Name of the MSA engine function to use for non-canonical sequences */
+  engine?: string;
+  /** Engine-specific parameters (e.g. method, gapOpen, gapExtend) */
+  engineParams?: Record<string, any>;
 };

package/src/widgets/monomer-info-widget.ts

@@ -5,14 +5,11 @@ import * as DG from 'datagrok-api/dg';
 
 import {IMonomerLib, Monomer} from '@datagrok-libraries/bio/src/types/monomer-library';
 import {HELM_REQUIRED_FIELD as REQ, HELM_RGROUP_FIELDS as RGP} from '@datagrok-libraries/bio/src/utils/const';
+import {MONOMER_MOTIF_SPLITTER, MONOMER_CANONICALIZER_TEMP} from '@datagrok-libraries/bio/src/utils/macromolecule/consts';
+import {IMonomerCanonicalizer} from '@datagrok-libraries/bio/src/utils/macromolecule/types';
 
 import {getCorrectedSmiles, capSmiles} from '../utils/monomer-lib/monomer-manager/monomer-manager';
 
-/** Finds a monomer in the library across all polymer types. */
-function findMonomer(monomerLib: IMonomerLib, symbol: string): Monomer | null {
-  return monomerLib.getMonomer(null, symbol);
-}
-
 /** Caps the monomer (replaces R-groups with cap atoms) and returns capped SMILES. */
 function getCappedSmiles(monomer: Monomer): string | null {
   try {
@@ -22,58 +19,101 @@ function getCappedSmiles(monomer: Monomer): string | null {
   return null;
 }
 
+/** Renders a single-monomer details pane content. */
+function renderMonomerDetails(monomer: Monomer): HTMLElement {
+  const map: {[key: string]: any} = {
+    'Symbol': monomer[REQ.SYMBOL],
+    'Name': monomer[REQ.NAME],
+    'Polymer Type': monomer[REQ.POLYMER_TYPE],
+    'Monomer Type': monomer[REQ.MONOMER_TYPE],
+  };
+  if (monomer[REQ.AUTHOR])
+    map['Author'] = monomer[REQ.AUTHOR];
+  if (monomer.naturalAnalog)
+    map['Natural Analog'] = monomer.naturalAnalog;
+  if (monomer.lib?.source) {
+    let source = monomer.lib.source;
+    if (source.endsWith('.json'))
+      source = source.substring(0, source.length - 5);
+    map['Library'] = source;
+  }
+
+  // Structure
+  if (monomer.molfile)
+    map['Structure'] = grok.chem.drawMolecule(monomer.molfile, 150, 150);
+  else if (monomer.smiles)
+    map['Structure'] = grok.chem.drawMolecule(monomer.smiles, 150, 150);
+
+  // R-Groups
+  const rgroups = monomer[REQ.RGROUPS];
+  if (rgroups && rgroups.length > 0) {
+    for (const rg of rgroups)
+      map[rg[RGP.LABEL] ?? '?'] = rg[RGP.ALTERNATE_ID] ?? '';
+  }
+
+  return ui.tableFromMap(map);
+}
+
+/** Renders the molecule info panel pane content for a single monomer. */
+function renderMoleculePane(monomer: Monomer): HTMLElement {
+  const cappedMol = getCappedSmiles(monomer);
+  if (!cappedMol)
+    return ui.divText('No molecular structure available');
+
+  const molSv = DG.SemanticValue.fromValueType(cappedMol, DG.SEMTYPE.MOLECULE);
+  return ui.panels.infoPanel(molSv).root;
+}
+
+/** Tries to get the canonicalizer from the SemanticValue's cell column. */
+function getCanonicalizer(sv: DG.SemanticValue): IMonomerCanonicalizer | null {
+  try {
+    const col = sv.cell?.column;
+    if (col)
+      return col.temp[MONOMER_CANONICALIZER_TEMP] ?? null;
+  } catch { /* no cell context */ }
+  return null;
+}
+
 /** Creates a widget for the monomer info panel shown in the context panel. */
-export function getMonomerInfoWidget(symbol: string, monomerLib: IMonomerLib): DG.Widget {
-  const monomer = findMonomer(monomerLib, symbol);
-  if (!monomer)
-    return new DG.Widget(ui.divText(`Monomer '${symbol}' not found in the library.`));
+export function getMonomerInfoWidget(sv: DG.SemanticValue, monomerLib: IMonomerLib): DG.Widget {
+  const rawValue = sv.value as string;
+  if (!rawValue)
+    return new DG.Widget(ui.divText('No monomer value.'));
 
-  const acc = ui.accordion('Monomer');
+  // Canonicalize if a canonicalizer is available from the column context
+  const canonicalizer = getCanonicalizer(sv);
+  const canonicalized = canonicalizer ? canonicalizer.canonicalize(rawValue) : rawValue;
 
-  // Details pane — includes general info, structure, and R-groups in one table
-  acc.addPane('Details', () => {
-    const map: {[key: string]: any} = {
-      'Symbol': monomer[REQ.SYMBOL],
-      'Name': monomer[REQ.NAME],
-      'Polymer Type': monomer[REQ.POLYMER_TYPE],
-      'Monomer Type': monomer[REQ.MONOMER_TYPE],
-    };
-    if (monomer[REQ.AUTHOR])
-      map['Author'] = monomer[REQ.AUTHOR];
-    if (monomer.naturalAnalog)
-      map['Natural Analog'] = monomer.naturalAnalog;
-    if (monomer.lib?.source) {
-      let source = monomer.lib.source;
-      if (source.endsWith('.json'))
-        source = source.substring(0, source.length - 5);
-      map['Library'] = source;
-    }
+  // Split by motif splitter — a cell value may contain multiple monomers
+  const symbols = canonicalized.split(MONOMER_MOTIF_SPLITTER).map((s) => s.trim()).filter((s) => s.length > 0);
 
-    // Structure
-    if (monomer.molfile)
-      map['Structure'] = grok.chem.drawMolecule(monomer.molfile, 150, 150);
-    else if (monomer.smiles)
-      map['Structure'] = grok.chem.drawMolecule(monomer.smiles, 150, 150);
-
-    // R-Groups
-    const rgroups = monomer[REQ.RGROUPS];
-    if (rgroups && rgroups.length > 0) {
-      for (const rg of rgroups)
-        map[rg[RGP.LABEL] ?? '?'] = rg[RGP.ALTERNATE_ID] ?? '';
-    }
+  // Resolve monomers from library
+  const monomers: {symbol: string; monomer: Monomer | null}[] =
+    symbols.map((s) => ({symbol: s, monomer: monomerLib.getMonomer(null, s)}));
 
-    return ui.tableFromMap(map);
-  }, true);
+  const found = monomers.filter((m) => m.monomer !== null);
+  if (found.length === 0)
+    return new DG.Widget(ui.divText(`Monomer '${rawValue}' not found in the library.`));
 
-  // Molecule panel pane — cap the monomer first, then embed the generic Molecule context panel
-  acc.addPane('Molecule', () => {
-    const cappedMol = getCappedSmiles(monomer);
-    if (!cappedMol)
-      return ui.divText('No molecular structure available');
+  const acc = ui.accordion('Monomer');
 
-    const molSv = DG.SemanticValue.fromValueType(cappedMol, DG.SEMTYPE.MOLECULE);
-    return ui.panels.infoPanel(molSv).root;
-  }, true);
+  if (found.length === 1) {
+    // Single monomer — flat panes
+    const m = found[0].monomer!;
+    acc.addPane('Details', () => renderMonomerDetails(m), true);
+    acc.addPane('Molecule', () => renderMoleculePane(m), true);
+  } else {
+    // Multiple monomers — one pane per monomer
+    for (const {symbol, monomer} of found) {
+      acc.addPane(symbol, () => {
+        return ui.divV([
+          renderMonomerDetails(monomer!),
+          ui.element('hr'),
+          renderMoleculePane(monomer!),
+        ]);
+      }, true);
+    }
+  }
 
   return new DG.Widget(acc.root);
 }