@datagrok/bio 2.26.8 → 2.27.1

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>;
 };