react-cheminfo 0.75.0 → 0.77.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];
+}

package/src/osiris/core/riskAppearance.ts

@@ -0,0 +1,86 @@
+/**
+ * How one risk reads on screen: the word for it, and the tone its square takes.
+ *
+ * Three levels, and they are exactly the three `DrugScoreCalculator` multiplies
+ * by — no risk ×1, medium ×0.8, high ×0.6 — so the colours say what the score
+ * already counted. A fourth tone exists for the state the library calls
+ * `RISK_UNKNOWN`, which means its tables did not load: it is grey, never green,
+ * because "nothing was assessed" and "nothing was found" are different answers
+ * and showing them alike is the one mistake that makes the panel dishonest.
+ *
+ * A fifth, `pending`, is ours: the prediction costs a fifth of a second and the
+ * square is on screen before it comes back.
+ */
+
+import { RISK_LEVEL_LABELS } from './constants.ts';
+import type { RiskLevel } from './types.ts';
+
+/** What a square is painted with, before the stylesheet turns it into a colour. */
+export type RiskTone = 'pending' | 'unknown' | 'none' | 'low' | 'high';
+
+/** How one risk is shown. */
+export interface RiskAppearance {
+  /** The stylesheet's `data-level`, which picks the square's colour. */
+  tone: RiskTone;
+  /** What the square says next to the risk's name, e.g. `High risk`. */
+  label: string;
+  /**
+   * Whether the level is worth opening: an explanation exists for an assessed
+   * risk and for nothing else.
+   */
+  explainable: boolean;
+}
+
+/** What a square says while its molecule is still being predicted. */
+export const PENDING_RISK_LABEL = 'Predicting…';
+
+/**
+ * What a square says when there is no molecule to predict.
+ *
+ * The comparison page draws the panel before a row is picked, and a square that
+ * said `Predicting…` there would claim work nobody asked for — under a heading
+ * inviting the reader to pick a row, which is a plain contradiction.
+ */
+export const IDLE_RISK_LABEL = 'Not predicted yet';
+
+/**
+ * What the predictor's own page says about its alerts, word for word.
+ *
+ * Quoted rather than paraphrased: it is the sentence that stops a red square
+ * being read as a verdict, and rewriting it would put our words over his.
+ */
+export const RISK_CAVEAT =
+  'Toxicity risk alerts are by no means meant to be a fully reliable toxicity prediction. Nor should be concluded from the absence of risk alerts that a particular substance is completely free of any toxic effect.';
+
+/**
+ * What is said in place of a highlight when the compound's own idCode is on one
+ * of the RTECS-derived lists. There is no fragment to point at, and painting the
+ * whole molecule would call the compound its own toxicophore.
+ */
+export const KNOWN_MOLECULE_NOTE =
+  'This exact compound is on the list, so there is no fragment to point at.';
+
+/**
+ * The tone and the word for one risk.
+ * @param level - How the risk came back, or `undefined` when there is none yet.
+ * @param pending - Whether a prediction is actually running for this molecule.
+ * @default false
+ * @returns See {@link RiskAppearance}.
+ */
+export function riskAppearance(
+  level: RiskLevel | undefined,
+  pending = false,
+): RiskAppearance {
+  if (level === undefined) {
+    return {
+      tone: 'pending',
+      label: pending ? PENDING_RISK_LABEL : IDLE_RISK_LABEL,
+      explainable: false,
+    };
+  }
+  return {
+    tone: level,
+    label: RISK_LEVEL_LABELS[level],
+    explainable: level !== 'unknown',
+  };
+}

package/src/osiris/core/riskDetail.ts

@@ -0,0 +1,120 @@
+/**
+ * Why one risk came back as it did, with the offending substructure located on
+ * the molecule.
+ *
+ * The match runs in the predictor's own mode —
+ * `new SSSearcher({ matchAtomCharge: true, matchAromDBondToDelocalized: false })`,
+ * which is OpenChemLib's mode 1. The JavaScript default is mode 8, and it can
+ * disagree with what `assessRisk` actually found, which would leave a risk
+ * reported with nothing highlighted and no way to tell why.
+ */
+
+import type * as OCL from 'openchemlib';
+
+import { RISK_TYPE_CODES } from './constants.ts';
+import type { OsirisPredictors } from './predictors.ts';
+import { parseRiskFindings } from './riskFindings.ts';
+import type {
+  DetailEntry,
+  RiskDetail,
+  RiskFinding,
+  RiskType,
+} from './types.ts';
+
+/**
+ * What the predictor found, and where on the molecule it found it.
+ * @param molecule - The molecule the risk was assessed on. It is copied before being searched.
+ * @param risk - Which of the four risks to explain.
+ * @param predictors - OpenChemLib with its resources registered and checked.
+ * @returns One finding per sentence the predictor printed, and one per matched fragment.
+ */
+export function riskDetail(
+  molecule: OCL.Molecule,
+  risk: RiskType,
+  predictors: OsirisPredictors,
+): RiskDetail {
+  const working = molecule.getCompactCopy();
+  const entries = predictors.toxicity.getDetail(
+    working,
+    RISK_TYPE_CODES[risk],
+  ) as readonly DetailEntry[];
+
+  const findings: RiskFinding[] = [];
+  for (const finding of parseRiskFindings(entries)) {
+    findings.push(
+      finding.idCode === null
+        ? finding
+        : { ...finding, ...locate(working, finding.idCode, predictors) },
+    );
+  }
+  return { risk, findings };
+}
+
+interface Match {
+  atoms: number[];
+  bonds: number[];
+}
+
+function locate(
+  molecule: OCL.Molecule,
+  fragmentIdCode: string,
+  predictors: OsirisPredictors,
+): Match {
+  let fragment: OCL.Molecule;
+  try {
+    fragment = predictors.Molecule.fromIDCode(fragmentIdCode);
+  } catch {
+    return { atoms: [], bonds: [] };
+  }
+
+  const searcher = new predictors.SSSearcher({
+    matchAtomCharge: true,
+    matchAromDBondToDelocalized: false,
+  });
+  searcher.setMol(fragment, molecule);
+  if (!searcher.isFragmentInMolecule()) return { atoms: [], bonds: [] };
+  searcher.findFragmentInMolecule({ countMode: 'overlapping' });
+
+  const atoms = new Set<number>();
+  const bonds = new Set<number>();
+  for (const match of searcher.getMatchList()) {
+    collect(molecule, fragment, match, atoms, bonds);
+  }
+  return { atoms: sorted(atoms), bonds: sorted(bonds) };
+}
+
+/**
+ * Add one match's atoms and bonds to the running sets.
+ *
+ * A fragment atom the query marked as an exclude group maps to -1, and a bond
+ * between two matched atoms may not exist in the molecule when the fragment
+ * matched through a bridge, so both are checked rather than assumed.
+ * @param molecule - The molecule searched.
+ * @param fragment - The fragment that matched.
+ * @param map - The molecule's atom for each of the fragment's, -1 for none.
+ * @param atoms - The matched atoms so far, added to.
+ * @param bonds - The matched bonds so far, added to.
+ */
+function collect(
+  molecule: OCL.Molecule,
+  fragment: OCL.Molecule,
+  map: readonly number[],
+  atoms: Set<number>,
+  bonds: Set<number>,
+): void {
+  for (const atom of map) {
+    if (atom >= 0) atoms.add(atom);
+  }
+  for (let bond = 0; bond < fragment.getAllBonds(); bond++) {
+    const first = map[fragment.getBondAtom(0, bond)];
+    const second = map[fragment.getBondAtom(1, bond)];
+    if (first === undefined || second === undefined) continue;
+    if (first < 0 || second < 0) continue;
+    const found = molecule.getBond(first, second);
+    if (found !== -1) bonds.add(found);
+  }
+}
+
+function sorted(values: Set<number>): number[] {
+  return Array.from(values).toSorted((a, b) => a - b);
+}

package/src/osiris/core/riskDetailRequest.ts

@@ -0,0 +1,64 @@
+/**
+ * Asking a worker why one risk came back as it did, and asking again when the
+ * set's cancel took the question with it.
+ *
+ * An explanation travels on a properties channel, and `cancel` drops every
+ * request on every channel — the reader's click included, which then reads as
+ * the channel's own words in place of the findings. It is not part of the set
+ * being abandoned, so it is simply asked for again.
+ *
+ * A channel of its own would be the other way, and is worse here: a channel
+ * makes its worker on the first request, so the first click would wait for
+ * OpenChemLib and the 398 kB of resource tables to load in a cold worker,
+ * where the shared one is already warm. The retry costs one more message on a
+ * worker that is running anyway.
+ */
+
+import { CancelledRequestError } from '../../worker/core/errors.ts';
+import type { WorkerChannel } from '../../worker/core/workerChannelTypes.ts';
+
+import type {
+  PredictRequest,
+  PredictResponse,
+  RiskDetailRequest,
+} from './predictProtocol.ts';
+
+type Channel = WorkerChannel<PredictRequest, PredictResponse>;
+
+/** What the reader is told when the second ask was dropped as well. */
+export const RISK_DETAIL_DROPPED =
+  'That explanation was dropped when the run stopped. Close the risk square and open it again.';
+
+/**
+ * Ask a worker to explain one risk, once more if a cancel dropped the ask.
+ * @param channelOf - Picks the channel to ask on, called again for the retry so it lands on whichever worker is least busy by then.
+ * @param request - The explanation to ask for.
+ * @param mayRetry - Whether asking again can still be answered: false once the pool is terminated, or once its resources are known not to have loaded.
+ * @returns Whatever the worker answered, including its `unavailable`.
+ * @throws {Error} When the ask was dropped and cannot be made again.
+ */
+export async function requestRiskDetail(
+  channelOf: () => Channel,
+  request: RiskDetailRequest,
+  mayRetry: () => boolean,
+): Promise<PredictResponse> {
+  try {
+    return await channelOf().request(request);
+  } catch (error) {
+    if (!(error instanceof CancelledRequestError)) throw error;
+    if (!mayRetry()) throw new Error(RISK_DETAIL_DROPPED, { cause: error });
+  }
+  return askAgain(channelOf, request);
+}
+
+async function askAgain(
+  channelOf: () => Channel,
+  request: RiskDetailRequest,
+): Promise<PredictResponse> {
+  try {
+    return await channelOf().request(request);
+  } catch (error) {
+    if (!(error instanceof CancelledRequestError)) throw error;
+    throw new Error(RISK_DETAIL_DROPPED, { cause: error });
+  }
+}

package/src/osiris/core/riskFindings.ts

@@ -0,0 +1,92 @@
+/**
+ * Reading what the toxicity predictor printed.
+ *
+ * `getDetail` answers a flat list of typed strings — 1 is an idCode, 2 is text,
+ * 3 is a number — in which a text line heads the idCodes that follow it. Which
+ * text line it is matters more than anything else the tool shows: "This
+ * molecule is known to be mutagenic" means the compound's own idCode is in a
+ * list derived from RTECS, and the idCode that follows is **the molecule
+ * itself**; "High-risk fragments indicating Mutagenicity" means a substructure
+ * matched, and the idCodes that follow are the substructures.
+ *
+ * Telling them apart is what keeps the red square honest: aspirin, caffeine and
+ * paracetamol all come back high through the first branch, and highlighting the
+ * whole molecule there would call the compound its own toxicophore.
+ */
+
+import type { DetailEntry, RiskFinding } from './types.ts';
+
+/** An idCode, to be drawn as a structure. */
+const ID_CODE = 1;
+/** Plain text. */
+const TEXT = 2;
+
+/**
+ * Turn what the predictor printed into the lines a page shows.
+ *
+ * The matched atoms are left empty here: finding them needs the molecule and
+ * the predictor's own match mode, which `riskDetail` supplies.
+ * @param entries - What `ToxicityPredictor.getDetail` returned.
+ * @returns One finding per sentence, and one per matched fragment.
+ */
+export function parseRiskFindings(
+  entries: readonly DetailEntry[],
+): RiskFinding[] {
+  const findings: RiskFinding[] = [];
+  let heading: Heading = { kind: 'note', description: '', severity: null };
+
+  for (const entry of entries) {
+    if (entry.type === TEXT) {
+      heading = readHeading(entry.value);
+      // A fragment heading says nothing on its own; it is repeated on each of
+      // the fragments that follow it, so the page can draw one row per match.
+      if (heading.kind !== 'fragment') findings.push(line(heading));
+      continue;
+    }
+    if (entry.type !== ID_CODE) continue;
+    // The idCode under a known-molecule heading is the molecule itself.
+    if (heading.kind !== 'fragment') continue;
+    findings.push({ ...line(heading), idCode: entry.value });
+  }
+
+  return findings;
+}
+
+interface Heading {
+  kind: RiskFinding['kind'];
+  description: string;
+  severity: RiskFinding['severity'];
+}
+
+function line(heading: Heading): RiskFinding {
+  return {
+    kind: heading.kind,
+    description: heading.description,
+    severity: heading.severity,
+    idCode: null,
+    atoms: [],
+    bonds: [],
+  };
+}
+
+/** `This molecule is known to be mutagenic:` and its three siblings. */
+const KNOWN = /^This molecule is known to be /i;
+const HIGH_RISK = /^High-risk fragments/i;
+const MEDIUM_RISK = /^Medium-risk fragments/i;
+const NOTHING_FOUND = /^No indication for /i;
+
+function readHeading(value: string): Heading {
+  if (KNOWN.test(value)) {
+    return { kind: 'known', description: value, severity: null };
+  }
+  if (HIGH_RISK.test(value)) {
+    return { kind: 'fragment', description: value, severity: 'high' };
+  }
+  if (MEDIUM_RISK.test(value)) {
+    return { kind: 'fragment', description: value, severity: 'medium' };
+  }
+  if (NOTHING_FOUND.test(value)) {
+    return { kind: 'none', description: value, severity: null };
+  }
+  return { kind: 'note', description: value, severity: null };
+}

package/src/osiris/core/runPredictionJob.ts

@@ -0,0 +1,49 @@
+/**
+ * One prediction, wherever it runs.
+ *
+ * The worker serves this, and a page with no `Worker` at all — a unit test,
+ * Node — runs the same function on its own thread. One code path, so what the
+ * tests prove is what the page does.
+ */
+
+import { errorMessage } from '../../error/core/toError.ts';
+
+import { predictIdCode, riskDetailOfIdCode } from './predictIdCode.ts';
+import type { PredictRequest, PredictResponse } from './predictProtocol.ts';
+import { loadPredictors } from './predictors.ts';
+
+/**
+ * Answer one job.
+ *
+ * A structure that cannot be read, or that holds no atoms, throws: that is one
+ * bad row, and the run carries on without it. Resources that did not load
+ * return `unavailable` instead, because that is every row and the run must stop.
+ * @param request - The job.
+ * @returns The answer.
+ * @throws {Error} When the molecule itself could not be read or predicted.
+ */
+export async function runPredictionJob(
+  request: PredictRequest,
+): Promise<PredictResponse> {
+  let predictors;
+  try {
+    predictors = await loadPredictors(request.resources);
+  } catch (error) {
+    return { kind: 'unavailable', message: errorMessage(error) };
+  }
+
+  if (request.kind === 'riskDetail') {
+    return {
+      kind: 'riskDetail',
+      detail: riskDetailOfIdCode(request.idCode, request.risk, predictors),
+    };
+  }
+
+  return {
+    kind: 'properties',
+    key: request.key,
+    properties: predictIdCode(request.idCode, predictors, {
+      ...(request.label === undefined ? {} : { label: request.label }),
+    }),
+  };
+}