react-cheminfo 0.76.0 → 0.77.0

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 }),
+    }),
+  };
+}

package/src/osiris/core/scales.ts

@@ -0,0 +1,236 @@
+/**
+ * The scale every displayed property is read on: how wide the bar is, where
+ * the good band sits, and which published number the labelled mark names.
+ *
+ * Eight of the ten come verbatim from DataWarrior's own `MolecularPropertyHelper.SPEC`
+ * table — the same ranges its own property views draw — so nothing here is a
+ * cut-off picked to look right. The two it has no entry for, drug-likeness and
+ * the drug score, keep the legacy explorer's ranges, and take their fitness
+ * from `DrugScoreCalculator`'s own terms rather than from a new guess.
+ *
+ * The preferred band and the published threshold are different numbers on
+ * purpose: cLogP's band closes at 4, where DataWarrior puts it, while the
+ * published rule of thumb the mark names is 5. The band draws the colour, the
+ * threshold draws the line.
+ */
+
+import type { PropertyKey } from './propertyKeys.ts';
+
+/** A published rule of thumb, drawn on the bar as a labelled mark. */
+export interface PropertyThreshold {
+  /** Where on the bar the mark goes. */
+  value: number;
+  /** How it reads, e.g. `≤ 5`. */
+  label: string;
+}
+
+/** Where a shared scale's numbers come from. */
+export type ScaleSource = 'datawarrior' | 'legacy';
+
+/** How one property is drawn, ranged and judged. */
+export interface PropertyScale {
+  /** The field of `OsirisProperties` this describes. */
+  key: PropertyKey;
+  /** What the panel and the table column call it. */
+  label: string;
+  /** The unit, empty where the quantity is dimensionless. */
+  unit: string;
+  /** Decimals the value is shown to; `0` for a count. */
+  decimals: number;
+  /** The left end of the bar, and of the plot axis. */
+  rangeMin: number;
+  /** The right end of the bar, and of the plot axis. */
+  rangeMax: number;
+  /** The bottom of the preferred band, or `null` when it has no lower bound. */
+  preferredMin: number | null;
+  /** The top of the preferred band, or `null` when it has no upper bound. */
+  preferredMax: number | null;
+  /**
+   * How far outside the band the fitness takes to fall away. `null` for a
+   * quantity that is already a 0-to-1 fitness.
+   */
+  halfWidth: number | null;
+  /**
+   * Whether a larger number is the better one. `null` where the property has a
+   * band rather than a direction — a molecule wants some stereocentres, not as
+   * many or as few as possible.
+   */
+  higherIsBetter: boolean | null;
+  /** The published rule of thumb to mark, or `null` where there is none. */
+  threshold: PropertyThreshold | null;
+  /** Whether the bar grows from the middle rather than from the left. */
+  diverging: boolean;
+  /** Where the range and the band came from. */
+  source: ScaleSource;
+}
+
+/** How each displayed property is drawn, ranged and judged. */
+export const PROPERTY_SCALES: Record<PropertyKey, PropertyScale> = {
+  logP: {
+    key: 'logP',
+    label: 'cLogP',
+    unit: '',
+    decimals: 2,
+    rangeMin: 0,
+    rangeMax: 8,
+    preferredMin: null,
+    preferredMax: 4,
+    halfWidth: 0.5,
+    higherIsBetter: false,
+    threshold: { value: 5, label: '≤ 5' },
+    diverging: false,
+    source: 'datawarrior',
+  },
+  logS: {
+    key: 'logS',
+    label: 'Solubility',
+    unit: 'log(mol/L)',
+    decimals: 2,
+    rangeMin: -8,
+    rangeMax: 2,
+    preferredMin: -4,
+    preferredMax: null,
+    halfWidth: 0.5,
+    higherIsBetter: true,
+    threshold: { value: -4, label: '> −4' },
+    diverging: false,
+    source: 'datawarrior',
+  },
+  molecularWeight: {
+    key: 'molecularWeight',
+    label: 'Molweight',
+    unit: 'g/mol',
+    decimals: 2,
+    rangeMin: 0,
+    rangeMax: 800,
+    preferredMin: null,
+    preferredMax: 400,
+    halfWidth: 50,
+    higherIsBetter: false,
+    threshold: { value: 450, label: '< 450' },
+    diverging: false,
+    source: 'datawarrior',
+  },
+  polarSurfaceArea: {
+    key: 'polarSurfaceArea',
+    label: 'TPSA',
+    unit: 'Ų',
+    decimals: 2,
+    rangeMin: 0,
+    rangeMax: 250,
+    preferredMin: null,
+    preferredMax: 120,
+    halfWidth: 20,
+    higherIsBetter: false,
+    threshold: null,
+    diverging: false,
+    source: 'datawarrior',
+  },
+  druglikeness: {
+    key: 'druglikeness',
+    label: 'Druglikeness',
+    unit: '',
+    decimals: 2,
+    rangeMin: -10,
+    rangeMax: 10,
+    preferredMin: 0,
+    preferredMax: null,
+    // `DrugScoreCalculator` scores drug-likeness as 1/(1+e^-d), which is this
+    // same valuation with a lower bound of 0 and a half-width of 1. So the
+    // ramp behind the bar is the library's own term, not a second opinion.
+    halfWidth: 1,
+    higherIsBetter: true,
+    threshold: { value: 0, label: '> 0' },
+    diverging: true,
+    source: 'legacy',
+  },
+  acceptorCount: {
+    key: 'acceptorCount',
+    label: 'H-bond acceptors',
+    unit: '',
+    decimals: 0,
+    rangeMin: 0,
+    rangeMax: 16,
+    preferredMin: null,
+    preferredMax: 10,
+    halfWidth: 1,
+    higherIsBetter: false,
+    threshold: null,
+    diverging: false,
+    source: 'datawarrior',
+  },
+  donorCount: {
+    key: 'donorCount',
+    label: 'H-bond donors',
+    unit: '',
+    decimals: 0,
+    rangeMin: 0,
+    rangeMax: 8,
+    preferredMin: null,
+    preferredMax: 5,
+    halfWidth: 0.5,
+    higherIsBetter: false,
+    threshold: null,
+    diverging: false,
+    source: 'datawarrior',
+  },
+  stereoCenterCount: {
+    key: 'stereoCenterCount',
+    label: 'Stereocentres',
+    unit: '',
+    decimals: 0,
+    rangeMin: 0,
+    rangeMax: 8,
+    preferredMin: 1,
+    preferredMax: 3,
+    halfWidth: 2,
+    higherIsBetter: null,
+    threshold: null,
+    diverging: false,
+    source: 'datawarrior',
+  },
+  rotatableBondCount: {
+    key: 'rotatableBondCount',
+    label: 'Rotatable bonds',
+    unit: '',
+    decimals: 0,
+    rangeMin: 0,
+    rangeMax: 20,
+    preferredMin: null,
+    preferredMax: 4,
+    halfWidth: 5,
+    higherIsBetter: false,
+    threshold: null,
+    diverging: false,
+    source: 'datawarrior',
+  },
+  drugScore: {
+    key: 'drugScore',
+    label: 'Drug score',
+    unit: '',
+    decimals: 2,
+    // The legacy bar, kept: it grows from the middle and runs -1 to 1, so a
+    // score always sits in its right half. The quantity itself is a product of
+    // terms in (0.5, 1) and four risk factors, so it cannot leave (0, 1).
+    rangeMin: -1,
+    rangeMax: 1,
+    preferredMin: null,
+    preferredMax: null,
+    // Already a 0-to-1 fitness: it is the product of the four valuations
+    // `DrugScoreCalculator` computes, so valuing it again would square it.
+    halfWidth: null,
+    higherIsBetter: true,
+    threshold: null,
+    diverging: true,
+    source: 'legacy',
+  },
+};
+
+/**
+ * How one property is drawn, ranged and judged.
+ * @param key - Which of the ten.
+ * @returns Its scale.
+ */
+export function propertyScale(key: PropertyKey): PropertyScale {
+  return PROPERTY_SCALES[key];
+}