react-cheminfo 0.76.0 → 0.77.0

package/src/osiris/core/predictIdCode.ts

@@ -0,0 +1,69 @@
+/**
+ * Prediction from the only thing worth keeping per row.
+ *
+ * A row never holds an `OCL.Molecule` — ten thousand of them cost 198 MB — so
+ * what travels to a worker is the idCode, and the molecule is rebuilt there in
+ * a quarter of a millisecond against the 380 ms the prediction itself costs.
+ */
+
+import { splitIdCode } from '../../structure/core/editorValue.ts';
+
+import type { ComputePropertiesOptions } from './computeProperties.ts';
+import { computeProperties } from './computeProperties.ts';
+import type { OsirisPredictors } from './predictors.ts';
+import { riskDetail } from './riskDetail.ts';
+import type { OsirisProperties, RiskDetail, RiskType } from './types.ts';
+
+/**
+ * What is said when an idCode cannot be read.
+ *
+ * An idCode is written by a program, not typed by a chemist, so there is no
+ * position to point at and no parser reason worth repeating: OpenChemLib
+ * answers a malformed one with `Cannot set properties of undefined`, which
+ * names nothing anyone can act on. Worse, it does not always throw — `zzzz`
+ * reads as a 117-atom molecule — so this is the floor, not the whole guard.
+ */
+export const UNREADABLE_ID_CODE_MESSAGE = 'This structure could not be read.';
+
+/**
+ * Predict everything the tool shows, from an idCode.
+ * @param value - The idCode, with the editor's atom coordinates after a space or without them.
+ * @param predictors - OpenChemLib with its resources registered and checked.
+ * @param options - See {@link ComputePropertiesOptions}.
+ * @returns The ten numbers, the four risks, and what to call the molecule.
+ * @throws {Error} When the idCode cannot be read, or describes no atoms.
+ */
+export function predictIdCode(
+  value: string,
+  predictors: OsirisPredictors,
+  options: ComputePropertiesOptions = {},
+): OsirisProperties {
+  return computeProperties(read(value, predictors), predictors, options);
+}
+
+/**
+ * Why one risk came back as it did, from an idCode.
+ * @param value - The idCode, coordinates included or not.
+ * @param risk - Which of the four risks to explain.
+ * @param predictors - OpenChemLib with its resources registered and checked.
+ * @returns The findings, with the matched atoms and bonds of every fragment.
+ * @throws {Error} When the idCode cannot be read.
+ */
+export function riskDetailOfIdCode(
+  value: string,
+  risk: RiskType,
+  predictors: OsirisPredictors,
+): RiskDetail {
+  return riskDetail(read(value, predictors), risk, predictors);
+}
+
+function read(value: string, predictors: OsirisPredictors) {
+  const { idCode, coordinates } = splitIdCode(value);
+  try {
+    return coordinates === undefined
+      ? predictors.Molecule.fromIDCode(idCode)
+      : predictors.Molecule.fromIDCode(idCode, coordinates);
+  } catch (error) {
+    throw new Error(UNREADABLE_ID_CODE_MESSAGE, { cause: error });
+  }
+}

package/src/osiris/core/predictProtocol.ts

@@ -0,0 +1,78 @@
+/**
+ * What the page asks a prediction worker, and what it answers.
+ *
+ * One molecule per request. Two of the three answers are ordinary results; the
+ * third, `unavailable`, is how a worker says its resource tables did not load.
+ * That one travels as a *successful* answer on purpose: a rejection would be
+ * indistinguishable from the ordinary failure of one unreadable structure,
+ * whereas this one means every answer from every worker is worthless and the
+ * run must stop and say so.
+ */
+
+import type { ResourceSource } from './predictors.ts';
+import type { OsirisProperties, RiskDetail, RiskType } from './types.ts';
+
+/** What every request carries, whichever job it asks for. */
+interface BaseRequest {
+  /**
+   * Where the worker registers OpenChemLib's resources from. In a browser this
+   * is always the absolute URL of the site's own `openchemlib-resources.json`,
+   * resolved on the main thread: a worker has no `document`, so it cannot read
+   * the deployment's mount path itself. The parsed tables are accepted as well,
+   * for the in-process fallback where there is no worker to post them to.
+   */
+  resources: ResourceSource;
+}
+
+/** Predict everything the tool shows for one molecule. */
+export interface PropertiesRequest extends BaseRequest {
+  kind: 'properties';
+  /** The caller's key for the row, echoed back so answers can arrive in any order. */
+  key: string;
+  /** The idCode, with the editor's atom coordinates after a space or without. */
+  idCode: string;
+  /**
+   * The name the source carried.
+   * @default the canonical SMILES
+   */
+  label?: string;
+}
+
+/** Explain why one risk came back as it did. */
+export interface RiskDetailRequest extends BaseRequest {
+  kind: 'riskDetail';
+  /** The idCode, coordinates included or not. */
+  idCode: string;
+  /** Which of the four risks to explain. */
+  risk: RiskType;
+}
+
+/** One job for a prediction worker. */
+export type PredictRequest = PropertiesRequest | RiskDetailRequest;
+
+/** What a prediction worker answers. */
+export type PredictResponse =
+  | { kind: 'properties'; key: string; properties: OsirisProperties }
+  | { kind: 'riskDetail'; detail: RiskDetail }
+  | { kind: 'unavailable'; message: string };
+
+/**
+ * Whether a message is a job this worker handles, so anything else is refused
+ * rather than read as one.
+ * @param value - Whatever was posted.
+ * @returns True when it is a well-formed request.
+ */
+export function isPredictRequest(value: unknown): value is PredictRequest {
+  if (typeof value !== 'object' || value === null) return false;
+  const request = value as {
+    kind?: unknown;
+    resources?: unknown;
+    idCode?: unknown;
+    key?: unknown;
+    risk?: unknown;
+  };
+  if (typeof request.idCode !== 'string') return false;
+  if (request.resources === undefined) return false;
+  if (request.kind === 'properties') return typeof request.key === 'string';
+  return request.kind === 'riskDetail' && typeof request.risk === 'string';
+}

package/src/osiris/core/predictionPool.ts

@@ -0,0 +1,237 @@
+/**
+ * A pool of prediction workers, answering one molecule at a time each.
+ *
+ * `createWorkerChannel` from `react-cheminfo/core` does the per-worker half —
+ * request identifiers so answers match callers whatever order they arrive in,
+ * timeouts, cancellation, and the in-process fallback where a page has no
+ * `Worker` at all. What it does not do is spread work over several workers, so
+ * that is what this adds: one channel per worker, a queue the pool owns, and at
+ * most one outstanding job per channel, which is what makes reordering possible
+ * at all. A channel asked for everything at once would post everything at once,
+ * and the row the reader is looking at would be answered forty-eighth.
+ */
+
+import { errorMessage } from '../../error/core/toError.ts';
+import { CancelledRequestError } from '../../worker/core/errors.ts';
+import { createWorkerChannel } from '../../worker/core/workerChannel.ts';
+import type { WorkerChannel } from '../../worker/core/workerChannelTypes.ts';
+
+import { predictionPoolSize } from './poolSize.ts';
+import type {
+  PredictionInput,
+  PredictionPool,
+  PredictionPoolOptions,
+  PredictionProgress,
+} from './poolTypes.ts';
+import type { PredictRequest, PredictResponse } from './predictProtocol.ts';
+import { createPredictionQueue } from './predictionQueue.ts';
+import { PredictorsUnavailableError } from './predictors.ts';
+import { requestRiskDetail } from './riskDetailRequest.ts';
+import { runPredictionJob } from './runPredictionJob.ts';
+import type { RiskDetail, RiskType } from './types.ts';
+
+type Channel = WorkerChannel<PredictRequest, PredictResponse>;
+
+interface Slot {
+  channel: Channel;
+  busy: boolean;
+}
+
+/**
+ * Start a pool of prediction workers.
+ *
+ * Workers are created lazily by the channels, on their first job, so a page
+ * that never predicts anything never loads OpenChemLib.
+ * @param options - See {@link PredictionPoolOptions}.
+ * @returns The pool.
+ */
+export function createPredictionPool(
+  options: PredictionPoolOptions,
+): PredictionPool {
+  const {
+    resources,
+    onResult,
+    onProgress,
+    onUnavailable,
+    createWorker,
+    runInProcess,
+    timeoutMs = 60_000,
+  } = options;
+  const size = predictionPoolSize(options.size);
+  const run = runInProcess ?? runPredictionJob;
+
+  const slots: Slot[] = [];
+  for (let index = 0; index < size; index++) {
+    slots.push({
+      channel: createWorkerChannel<PredictRequest, PredictResponse>(
+        createWorker,
+        {
+          name: `osiris-prediction-${index}`,
+          defaultTimeoutMs: timeoutMs,
+          runInProcess: run,
+        },
+      ),
+      busy: false,
+    });
+  }
+
+  const queue = createPredictionQueue();
+  const inFlight = new Set<string>();
+  let generation = 0;
+  let done = 0;
+  let total = 0;
+  let running = false;
+  let terminated = false;
+  let unavailable: string | null = null;
+
+  function progress(): PredictionProgress {
+    return { done, total, pending: queue.size + inFlight.size, running };
+  }
+
+  function report(): void {
+    onProgress?.(progress());
+  }
+
+  function pump(): void {
+    if (unavailable !== null) return;
+    for (const slot of slots) {
+      if (slot.busy) continue;
+      const next = queue.take();
+      if (next === undefined) break;
+      dispatch(slot, next);
+    }
+  }
+
+  function dispatch(slot: Slot, input: PredictionInput): void {
+    const era = generation;
+    slot.busy = true;
+    inFlight.add(input.key);
+    const request: PredictRequest = {
+      kind: 'properties',
+      resources,
+      key: input.key,
+      idCode: input.idCode,
+      ...(input.label === undefined ? {} : { label: input.label }),
+    };
+    slot.channel.request(request).then(
+      (response) => {
+        settle(slot, input, era, response, null);
+      },
+      (error: unknown) => {
+        settle(slot, input, era, null, error);
+      },
+    );
+  }
+
+  function settle(
+    slot: Slot,
+    input: PredictionInput,
+    era: number,
+    response: PredictResponse | null,
+    error: unknown,
+  ): void {
+    slot.busy = false;
+    inFlight.delete(input.key);
+
+    // An answer from a cancelled run is not counted and not reported, but the
+    // slot it just freed is still dispatched from: a submit made in the same
+    // turn as the cancel found every slot busy and queued its molecules here.
+    if (era === generation) {
+      if (response?.kind === 'unavailable') {
+        stop(response.message);
+        return;
+      }
+      if (response?.kind === 'properties') {
+        done += 1;
+        onResult?.({
+          key: input.key,
+          ok: true,
+          properties: response.properties,
+        });
+      } else if (error !== null && !(error instanceof CancelledRequestError)) {
+        done += 1;
+        onResult?.({ key: input.key, ok: false, message: errorMessage(error) });
+      }
+    }
+
+    pump();
+    if (queue.size === 0 && inFlight.size === 0) running = false;
+    report();
+  }
+
+  function clear(): void {
+    generation += 1;
+    queue.clear();
+    inFlight.clear();
+    running = false;
+    for (const slot of slots) slot.channel.cancel();
+  }
+
+  function stop(message: string): void {
+    clear();
+    unavailable = message;
+    report();
+    onUnavailable?.(message);
+  }
+
+  function leastBusy(): Slot {
+    let best = slots[0] as Slot;
+    for (const slot of slots) {
+      if (slot.channel.pendingCount < best.channel.pendingCount) best = slot;
+    }
+    return best;
+  }
+
+  return {
+    size,
+    get progress() {
+      return progress();
+    },
+
+    submit(molecules) {
+      if (unavailable !== null) return;
+      if (!running && queue.size === 0 && inFlight.size === 0) {
+        done = 0;
+        total = 0;
+      }
+      for (const input of molecules) {
+        if (inFlight.has(input.key)) continue;
+        if (queue.add(input)) total += 1;
+      }
+      running = queue.size > 0 || inFlight.size > 0;
+      pump();
+      report();
+    },
+
+    prioritize(keys) {
+      queue.prioritize(keys);
+    },
+
+    async riskDetail(idCode: string, risk: RiskType): Promise<RiskDetail> {
+      const response = await requestRiskDetail(
+        () => leastBusy().channel,
+        { kind: 'riskDetail', resources, idCode, risk },
+        () => !terminated && unavailable === null,
+      );
+      if (response.kind === 'unavailable') {
+        stop(response.message);
+        throw new PredictorsUnavailableError(response.message);
+      }
+      if (response.kind !== 'riskDetail') {
+        throw new Error('The worker answered something other than a detail.');
+      }
+      return response.detail;
+    },
+
+    cancel() {
+      clear();
+      report();
+    },
+
+    terminate() {
+      terminated = true;
+      clear();
+      for (const slot of slots) slot.channel.terminate();
+    },
+  };
+}

package/src/osiris/core/predictionQueue.ts

@@ -0,0 +1,89 @@
+/**
+ * What is still to be predicted, in the order it will be.
+ *
+ * Arrival order by default, because that is the order the reader read the file
+ * in. On top of it sits a short list of keys to answer first — the rows
+ * actually on screen — which is re-laid every time the reader scrolls or
+ * focuses a row. A key named as wanted that has since been answered or removed
+ * is skipped rather than looked up again.
+ */
+
+import type { PredictionInput } from './poolTypes.ts';
+
+/** The molecules waiting, and which of them to take next. */
+export interface PredictionQueue {
+  /** How many are waiting. */
+  readonly size: number;
+  /**
+   * Whether one is waiting.
+   * @param key - The row's key.
+   * @returns True when it is still queued.
+   */
+  has: (key: string) => boolean;
+  /**
+   * Queue one molecule, unless its key is already waiting.
+   * @param input - The molecule.
+   * @returns True when it was added.
+   */
+  add: (input: PredictionInput) => boolean;
+  /**
+   * Take the next molecule to predict: the first still-queued key of the wanted
+   * list, else the one that has waited longest.
+   * @returns The molecule, or `undefined` when nothing is waiting.
+   */
+  take: () => PredictionInput | undefined;
+  /**
+   * Replace the list of keys to answer first.
+   * @param keys - The keys, most wanted first.
+   */
+  prioritize: (keys: readonly string[]) => void;
+  /** Forget everything waiting. */
+  clear: () => void;
+}
+
+/**
+ * A queue of molecules to predict.
+ * @returns The queue, empty.
+ */
+export function createPredictionQueue(): PredictionQueue {
+  const waiting = new Map<string, PredictionInput>();
+  let wanted: readonly string[] = [];
+  let cursor = 0;
+
+  return {
+    get size() {
+      return waiting.size;
+    },
+    has: (key) => waiting.has(key),
+    add(input) {
+      if (waiting.has(input.key)) return false;
+      waiting.set(input.key, input);
+      return true;
+    },
+    take() {
+      while (cursor < wanted.length) {
+        const key = wanted[cursor] as string;
+        cursor += 1;
+        const next = waiting.get(key);
+        if (next !== undefined) {
+          waiting.delete(key);
+          return next;
+        }
+      }
+      const first = waiting.keys().next();
+      if (first.done === true) return undefined;
+      const next = waiting.get(first.value) as PredictionInput;
+      waiting.delete(first.value);
+      return next;
+    },
+    prioritize(keys) {
+      wanted = [...keys];
+      cursor = 0;
+    },
+    clear() {
+      waiting.clear();
+      wanted = [];
+      cursor = 0;
+    },
+  };
+}

package/src/osiris/core/predictors.ts

@@ -0,0 +1,142 @@
+/**
+ * OpenChemLib, loaded once and proved to be working before anything is
+ * predicted with it.
+ *
+ * Both predictors throw `static resources must be registered first` until
+ * `Resources.register*` has run — but only when *nothing* was registered. If
+ * something else was, `new ToxicityPredictor()` constructs happily, prints to
+ * the console, and answers every `assessRisk` with `RISK_UNKNOWN`, on which
+ * `DrugScoreCalculator` applies no penalty at all. The failure therefore reads
+ * on screen as four clean molecules and a healthy score. So the tables are
+ * proved here, at start-up, against a molecule whose answer is known: a
+ * fragment match that must come back high, and a drug-likeness that must be a
+ * real number. Between them the two families of resource file are both covered.
+ *
+ * The check costs about 160 ms once per worker, most of which is warm-up the
+ * first real molecule would have paid anyway — measured, a first prediction is
+ * 320 ms cold against 191 ms warm.
+ */
+
+import type * as OCL from 'openchemlib';
+
+import {
+  NO_FRAGMENT_MATCHED,
+  RISK_TYPE_CODES,
+  UNKNOWN_NUMBER,
+} from './constants.ts';
+
+/**
+ * Where the resource tables come from: the URL of the site's own
+ * `openchemlib-resources.json`, or the parsed file itself.
+ *
+ * A URL must be absolute. `registerFromUrl` resolves a relative one against
+ * `import.meta.url`, which after a build is a hashed chunk under `assets/`, so
+ * it answers 404 and every prediction quietly becomes unknown.
+ */
+export type ResourceSource = string | Readonly<Record<string, string>>;
+
+/** OpenChemLib, registered, checked and ready to predict with. */
+export interface OsirisPredictors {
+  /** Reads an idCode or a SMILES into a molecule. */
+  Molecule: typeof OCL.Molecule;
+  /** cLogP, solubility, TPSA and the four counts. */
+  MoleculeProperties: typeof OCL.MoleculeProperties;
+  /** Finds a toxicophore on a molecule, in the predictor's own match mode. */
+  SSSearcher: typeof OCL.SSSearcher;
+  /** The four spline terms and the four risk factors. */
+  DrugScoreCalculator: typeof OCL.DrugScoreCalculator;
+  /** The four risk assessments and their explanations. */
+  toxicity: OCL.ToxicityPredictor;
+  /** The 5294-fragment drug-likeness table. */
+  druglikeness: OCL.DruglikenessPredictor;
+}
+
+/** The tables did not load, so nothing may be predicted. */
+export class PredictorsUnavailableError extends Error {
+  override name = 'PredictorsUnavailableError';
+}
+
+/**
+ * OpenChemLib with its resources registered and checked.
+ *
+ * Loaded lazily — the library is 340 kB gzipped and does not tree-shake — and
+ * kept, because `Resources.register` replaces the whole map rather than merging
+ * into it, so registering twice with different keys silently unregisters the
+ * first set.
+ * @param source - The resources URL, or the parsed resources themselves.
+ * @returns The predictors, proved to answer.
+ * @throws {PredictorsUnavailableError} When the resources did not load, or loaded and answer nothing.
+ */
+export function loadPredictors(
+  source: ResourceSource,
+): Promise<OsirisPredictors> {
+  if (loaded === null) loaded = start(source);
+  return loaded;
+}
+
+/** Forget the loaded predictors, so the next call registers again. */
+export function resetPredictors(): void {
+  loaded = null;
+}
+
+let loaded: Promise<OsirisPredictors> | null = null;
+
+/**
+ * A failed load is not kept: a fetch that failed once may well answer on the
+ * next try, and a cached rejection would turn one lost packet into a page that
+ * stays broken until it is reloaded.
+ * @param source - The resources URL, or the parsed resources themselves.
+ * @returns The predictors, proved to answer.
+ */
+function start(source: ResourceSource): Promise<OsirisPredictors> {
+  const pending = build(source);
+  void pending.catch(() => {
+    if (loaded === pending) loaded = null;
+  });
+  return pending;
+}
+
+/** Benzidine — its mutagenicity comes from a fragment match, not from a list. */
+const PROBE_ID_CODE = 'dg}@@@mIe]e^ftx@H@H@@';
+
+const UNAVAILABLE =
+  'The prediction tables did not load, so no risk or drug-likeness can be computed. Reload the page.';
+
+async function build(source: ResourceSource): Promise<OsirisPredictors> {
+  const ocl = await import('openchemlib');
+  try {
+    if (typeof source === 'string') await ocl.Resources.registerFromUrl(source);
+    else ocl.Resources.register({ ...source });
+  } catch {
+    throw new PredictorsUnavailableError(UNAVAILABLE);
+  }
+
+  let toxicity: OCL.ToxicityPredictor;
+  let druglikeness: OCL.DruglikenessPredictor;
+  try {
+    toxicity = new ocl.ToxicityPredictor();
+    druglikeness = new ocl.DruglikenessPredictor();
+  } catch {
+    throw new PredictorsUnavailableError(UNAVAILABLE);
+  }
+
+  const probe = ocl.Molecule.fromIDCode(PROBE_ID_CODE);
+  const risk = toxicity.assessRisk(probe, RISK_TYPE_CODES.mutagenic);
+  const likeness = druglikeness.assessDruglikeness(probe);
+  if (
+    risk !== 3 ||
+    likeness === UNKNOWN_NUMBER ||
+    likeness === NO_FRAGMENT_MATCHED
+  ) {
+    throw new PredictorsUnavailableError(UNAVAILABLE);
+  }
+
+  return {
+    Molecule: ocl.Molecule,
+    MoleculeProperties: ocl.MoleculeProperties,
+    SSSearcher: ocl.SSSearcher,
+    DrugScoreCalculator: ocl.DrugScoreCalculator,
+    toxicity,
+    druglikeness,
+  };
+}

package/src/osiris/core/propertyKeys.ts

@@ -0,0 +1,54 @@
+/**
+ * Which of a molecule's predicted numbers the tool shows, and in which order.
+ *
+ * The order is the legacy panel's, top to bottom, and it is the same order the
+ * comparison table's columns and the plot's default axes take: a reader who
+ * learned the panel reads the table without relearning it. The keys are the
+ * field names of {@link OsirisProperties}, so an address carrying
+ * `axes=logP,logS` names the same things the panel does.
+ */
+
+import type { OsirisProperties } from './types.ts';
+
+/** The ten numbers the tool shows, in the order it shows them. */
+export const PROPERTY_KEYS = [
+  'logP',
+  'logS',
+  'molecularWeight',
+  'polarSurfaceArea',
+  'druglikeness',
+  'acceptorCount',
+  'donorCount',
+  'stereoCenterCount',
+  'rotatableBondCount',
+  'drugScore',
+] as const;
+
+/** One of the ten displayed properties. */
+export type PropertyKey = (typeof PROPERTY_KEYS)[number];
+
+/**
+ * Whether a string names a displayed property, so an address that carries
+ * something else is ignored rather than plotted as a blank axis.
+ * @param value - Whatever the address or the reader supplied.
+ * @returns True when it is one of the ten.
+ */
+export function isPropertyKey(value: string): value is PropertyKey {
+  return (PROPERTY_KEYS as readonly string[]).includes(value);
+}
+
+/**
+ * One property of one molecule.
+ *
+ * `null` means the predictor could not answer — never zero, and never the
+ * library's own sentinel, both of which plot and sort as real values.
+ * @param properties - What was predicted for the molecule.
+ * @param key - Which of the ten to read.
+ * @returns The number, or `null` when it is unknown.
+ */
+export function propertyValue(
+  properties: OsirisProperties,
+  key: PropertyKey,
+): number | null {
+  return properties[key];
+}