react-cheminfo 0.76.0 → 0.77.0

package/src/osiris/core/types.ts

@@ -0,0 +1,103 @@
+/**
+ * What the tool predicts about one molecule, and how a risk is explained.
+ *
+ * Every quantity OpenChemLib can fail to compute is `number | null` here, never
+ * the library's own sentinel: cLogP and solubility answer `-999`, the polar
+ * surface area `-1`, drug-likeness `-999` when the tables did not load and `-1`
+ * when no fragment matched, and a risk `0`. None of them is `NaN`, and
+ * `DrugScoreCalculator` consumes every one of them and returns a plausible
+ * number, so a sentinel that leaves this module is a wrong value on screen with
+ * nothing to say it is wrong.
+ */
+
+/** The four risks OSIRIS assesses, in the order the library numbers them. */
+export const RISK_TYPES = [
+  'mutagenic',
+  'tumorigenic',
+  'irritant',
+  'reproductive',
+] as const;
+
+/** One of the four risks. */
+export type RiskType = (typeof RISK_TYPES)[number];
+
+/**
+ * How risky one type came back.
+ *
+ * `unknown` is the library's `RISK_UNKNOWN`, which it returns when its fragment
+ * tables did not load — never "nothing was found", which is `none`.
+ */
+export type RiskLevel = 'unknown' | 'none' | 'low' | 'high';
+
+/** Everything the tool shows for one molecule. */
+export interface OsirisProperties {
+  /** The canonical idCode, read before anything touched the molecule. */
+  idCode: string;
+  /** The canonical SMILES, for a link and for a download. */
+  smiles: string;
+  /** A name from the source, or the SMILES when it carried none. */
+  label: string;
+  /** e.g. `C6H6`. */
+  molecularFormula: string;
+  /** The relative molecular weight in g/mol — 78.11 for benzene, never the monoisotopic mass. */
+  molecularWeight: number;
+  /** cLogP, the octanol/water partition coefficient. */
+  logP: number | null;
+  /** Aqueous solubility, log10 of mol/L at 25 °C and pH 7.5. */
+  logS: number | null;
+  /** Topological polar surface area, in Ų. */
+  polarSurfaceArea: number | null;
+  /** Drug-likeness: positive is drug-like, negative is not. */
+  druglikeness: number | null;
+  /** The drug score, 0 to 1. `null` whenever any of its inputs was unknown. */
+  drugScore: number | null;
+  /** Every nitrogen and oxygen — the OSIRIS definition, not Lipinski's. */
+  acceptorCount: number;
+  /** Every nitrogen and oxygen carrying at least one hydrogen. */
+  donorCount: number;
+  /** Atoms with a real, non-pseudo parity. */
+  stereoCenterCount: number;
+  /** Single, non-ring, non-terminal, non-amide bonds. */
+  rotatableBondCount: number;
+  /** How the four risks came back. */
+  risks: Record<RiskType, RiskLevel>;
+}
+
+/** Which branch of the predictor produced one line of a risk explanation. */
+export type RiskFindingKind = 'known' | 'fragment' | 'none' | 'note';
+
+/** One line of why a risk came back as it did. */
+export interface RiskFinding {
+  /**
+   * `known` — the molecule's own idCode is in the RTECS-derived list, so there
+   * is nothing to highlight. `fragment` — an alerting substructure matched.
+   * `none` — nothing was found. `note` — anything else the predictor printed.
+   */
+  kind: RiskFindingKind;
+  /** The sentence the predictor printed, verbatim. */
+  description: string;
+  /** How alerting the matched fragment is, or `null` when this is not a fragment. */
+  severity: 'high' | 'medium' | null;
+  /** The fragment's idCode, or `null` — a known molecule carries no fragment. */
+  idCode: string | null;
+  /** The molecule's atoms the fragment matched, so the page can highlight them. */
+  atoms: readonly number[];
+  /** The molecule's bonds the fragment matched. */
+  bonds: readonly number[];
+}
+
+/** Why one risk came back as it did. */
+export interface RiskDetail {
+  /** Which of the four risks this explains. */
+  risk: RiskType;
+  /** What the predictor printed, one entry per sentence or matched fragment. */
+  findings: readonly RiskFinding[];
+}
+
+/** One entry of a `ParameterizedString[]`, as OpenChemLib hands it over. */
+export interface DetailEntry {
+  /** 1 is an idCode, 2 is text, 3 is a number written out. */
+  type: number;
+  /** The entry itself. */
+  value: string;
+}

package/src/osiris/core/valuation.ts

@@ -0,0 +1,44 @@
+/**
+ * DataWarrior's own fuzzy fitness, ported from
+ * `com.actelion.research.chem.prediction.MolecularPropertyHelper`.
+ *
+ * It is what turns a predicted number into the green-to-red ramp behind it,
+ * and it is the library's arithmetic rather than a cut-off invented here: a
+ * property inside its preferred band scores 1, and the score falls away
+ * smoothly outside it over `halfWidth`. There is no cliff anywhere, so a cLogP
+ * of 4.01 does not look categorically worse than one of 3.99.
+ */
+
+/**
+ * How well one value sits in a preferred band, from 0 to 1.
+ *
+ * A bound given as `null` is simply not applied, which is how a property
+ * bounded on one side only — a solubility that must be high enough, a weight
+ * that must be low enough — scores against the one bound it has. The original
+ * passes `Double.NaN` for an absent bound and `NaN` is accepted here too.
+ *
+ * The Java comment claims the fitness at `max + halfWidth` is `1/e`; the
+ * arithmetic gives `1/(1+e)`, and the arithmetic is what was ported.
+ * @param value - The predicted number.
+ * @param min - The bottom of the preferred band, or `null` when there is none.
+ * @param max - The top of the preferred band, or `null` when there is none.
+ * @param halfWidth - How far outside the band the score takes to fall away.
+ * @returns The fitness, or `NaN` when the value is `NaN`.
+ */
+export function getValuation(
+  value: number,
+  min: number | null,
+  max: number | null,
+  halfWidth: number,
+): number {
+  if (Number.isNaN(value)) return Number.NaN;
+
+  let v = 1;
+  if (min !== null && !Number.isNaN(min)) {
+    v *= 1 / (1 + Math.exp((min - value) / halfWidth));
+  }
+  if (max !== null && !Number.isNaN(max)) {
+    v *= 1 / (1 + Math.exp((value - max) / halfWidth));
+  }
+  return v;
+}

package/src/osiris/ui/PropertyBar.tsx

@@ -0,0 +1,77 @@
+/**
+ * One property's bar: a track, a fill whose colour is how good the value is,
+ * and the published rule of thumb marked on it.
+ *
+ * The colour is handed to the stylesheet as a number rather than mixed here.
+ * A ramp computed in JavaScript would be a hex code in a component, which is
+ * the one thing a site of this family may not write: the green, the amber and
+ * the red are the shared status tokens, and `properties.css` mixes them.
+ *
+ * The bar carries no accessible text of its own. It draws the same number the
+ * row already prints beside it, so announcing it twice would only make the
+ * panel longer to listen to.
+ */
+
+import type { CSSProperties, ReactElement } from 'react';
+
+import type { BarGeometry } from '../core/barGeometry.ts';
+
+/** What {@link PropertyBar} needs. */
+export interface PropertyBarProps {
+  /** Where the fill and the mark go, from `barGeometry`. */
+  geometry: BarGeometry;
+}
+
+/**
+ * Draw one property's bar.
+ * @param props - See {@link PropertyBarProps}.
+ * @returns The track, its fill and its labelled mark.
+ */
+export function PropertyBar(props: PropertyBarProps): ReactElement {
+  const { geometry } = props;
+  // `--fitness` is a custom property, which React sets verbatim and
+  // `CSSProperties` has no name for; the stylesheet reads it in the `calc()`
+  // that mixes the ramp.
+  const fill = {
+    left: percent(geometry.start),
+    width: percent(geometry.length),
+    '--fitness': geometry.fitness.toFixed(4),
+  } as CSSProperties;
+
+  return (
+    <div className="property-bar" aria-hidden="true">
+      <div className="property-bar__track">
+        {geometry.origin === 0 ? null : (
+          <div
+            className="property-bar__origin"
+            style={{ left: percent(geometry.origin) }}
+          />
+        )}
+        <div className="property-bar__fill" style={fill} />
+        {geometry.mark === null ? null : (
+          <div
+            className="property-bar__mark"
+            style={{ left: percent(geometry.mark) }}
+          />
+        )}
+      </div>
+      {geometry.mark === null || geometry.markLabel === null ? null : (
+        <span
+          className="property-bar__threshold"
+          style={{ left: percent(geometry.mark) }}
+        >
+          {geometry.markLabel}
+        </span>
+      )}
+    </div>
+  );
+}
+
+/**
+ * A fraction of the track, as a CSS length.
+ * @param fraction - 0 at the left end, 1 at the right.
+ * @returns The percentage, to two decimals.
+ */
+function percent(fraction: number): string {
+  return `${(fraction * 100).toFixed(2)}%`;
+}

package/src/osiris/ui/PropertyPanel.tsx

@@ -0,0 +1,227 @@
+/**
+ * Everything OSIRIS predicts about one molecule: the four toxicity risks, then
+ * the ten numbers, in the order the original panel showed them.
+ *
+ * One panel wherever a molecule is predicted — beside an editor's canvas, for
+ * the row of a table the reader focused, beside a drawing — because a second
+ * panel would be a second place for the same ten rows to drift apart.
+ *
+ * The sections stand whether or not there is anything in them. A prediction
+ * costs a fifth of a second, and a panel that appeared only once it was ready
+ * would move the page under the reader's eye every time they drew a bond.
+ *
+ * Which explanation is open is the caller's state — it belongs to the page, and
+ * on the explorer it is what a click on a square changes — but *fetching* it is
+ * the panel's own business, so no page repeats the dance.
+ */
+
+import { Callout, H5 } from '@blueprintjs/core';
+import type { ReactElement, ReactNode } from 'react';
+import { useEffect, useState } from 'react';
+import { MF } from 'react-mf';
+
+import { errorMessage } from '../../error/core/toError.ts';
+import { PagePart } from '../../share/ui/PagePart.tsx';
+import type { PropertyKey } from '../core/propertyKeys.ts';
+import { PROPERTY_KEYS } from '../core/propertyKeys.ts';
+import type { OsirisProperties, RiskDetail, RiskType } from '../core/types.ts';
+
+import { PropertyRows } from './PropertyRows.tsx';
+import { RiskFindings } from './RiskFindings.tsx';
+import { RiskPanel } from './RiskPanel.tsx';
+
+/** What {@link PropertyPanel} needs. */
+export interface PropertyPanelProps {
+  /**
+   * What was predicted, or `null` when there is nothing to show yet.
+   * @default null
+   */
+  properties?: OsirisProperties | null;
+  /**
+   * The atom layout to draw the molecule with, in an explanation. Empty leaves
+   * openchemlib to invent one.
+   * @default ''
+   */
+  coordinates?: string;
+  /**
+   * Whether a prediction is running for the molecule the panel is showing.
+   * @default false
+   */
+  pending?: boolean;
+  /**
+   * What went wrong with this structure, in one sentence, or `null`.
+   * @default null
+   */
+  problem?: string | null;
+  /**
+   * Whether to open on the molecule's formula and name. Off for a host that
+   * already shows the formula beside the panel, such as a structure editor's
+   * side panel.
+   * @default true
+   */
+  head?: boolean;
+  /**
+   * Whether to draw the four risks, and the explanation a square opens. Off
+   * for a page answering a question about the numbers alone.
+   * @default true
+   */
+  risks?: boolean;
+  /**
+   * The property rows to draw, in the panel's order whatever order they are
+   * given in. Empty leaves the section out, for a page answering a question
+   * about the risks alone.
+   * @default PROPERTY_KEYS
+   */
+  rows?: readonly PropertyKey[];
+  /**
+   * What is said when there is nothing predicted and nothing running.
+   * @default 'Nothing to predict yet.'
+   */
+  emptyMessage?: ReactNode;
+  /**
+   * Which risk has its explanation open.
+   * @default null
+   */
+  openRisk?: RiskType | null;
+  /**
+   * Called with the risk to open, or `null` to close it. Without it the squares
+   * are not clickable.
+   * @default undefined
+   */
+  onOpenRisk?: (risk: RiskType | null) => void;
+  /**
+   * Why a risk came back as it did. Without it no explanation is offered.
+   * @default undefined
+   */
+  loadDetail?: (structure: string, risk: RiskType) => Promise<RiskDetail>;
+}
+
+/** One fetched explanation, and the request it answers. */
+interface DetailAnswer {
+  key: string;
+  detail: RiskDetail | null;
+  error: string | null;
+}
+
+/**
+ * The risks and the properties of one molecule.
+ * @param props - See {@link PropertyPanelProps}.
+ * @returns The two panels, and the open explanation between them.
+ */
+export function PropertyPanel(props: PropertyPanelProps): ReactElement {
+  const {
+    properties = null,
+    coordinates = '',
+    pending = false,
+    problem = null,
+    head = true,
+    risks = true,
+    rows = PROPERTY_KEYS,
+    emptyMessage = 'Nothing to predict yet.',
+    openRisk = null,
+    onOpenRisk,
+    loadDetail,
+  } = props;
+
+  const structure =
+    properties === null
+      ? ''
+      : coordinates === ''
+        ? properties.idCode
+        : `${properties.idCode} ${coordinates}`;
+  const answer = useRiskDetail(structure, openRisk, loadDetail);
+
+  return (
+    <div className="property-panel">
+      {problem === null ? null : (
+        <Callout intent="warning" compact>
+          {problem}
+        </Callout>
+      )}
+
+      {properties === null ? (
+        <p className="osiris-note">{pending ? 'Predicting…' : emptyMessage}</p>
+      ) : head ? (
+        <header className="property-panel__head">
+          <MF mf={properties.molecularFormula} />
+          <span className="property-panel__label">{properties.label}</span>
+        </header>
+      ) : null}
+
+      {risks ? (
+        <PagePart part="risks">
+          <RiskPanel
+            risks={properties?.risks ?? null}
+            pending={pending}
+            openRisk={openRisk}
+            onOpenRisk={onOpenRisk}
+          />
+        </PagePart>
+      ) : null}
+
+      {!risks ||
+      openRisk === null ||
+      structure === '' ||
+      loadDetail === undefined ? null : (
+        <PagePart part="detail">
+          <RiskFindings
+            risk={openRisk}
+            structure={structure}
+            detail={answer?.detail ?? null}
+            error={answer?.error ?? null}
+          />
+        </PagePart>
+      )}
+
+      {rows.length === 0 ? null : (
+        <PagePart part="properties">
+          <section className="property-section">
+            <H5>Predicted properties</H5>
+            <PropertyRows properties={properties} keys={rows} />
+          </section>
+        </PagePart>
+      )}
+    </div>
+  );
+}
+
+/**
+ * Fetch the open risk's explanation, and answer only about the request that is
+ * open now.
+ *
+ * The answer carries the request it belongs to rather than being cleared when a
+ * new one starts: clearing would mean writing state from inside the effect, and
+ * comparing keys says the same thing without the extra render.
+ * @param structure - The molecule: an idCode, with its coordinates after a space.
+ * @param openRisk - Which risk is open, or `null`.
+ * @param loadDetail - What answers the question, or `undefined` when nothing does.
+ * @returns The answer to the open request, or `null` while it is being worked out.
+ */
+function useRiskDetail(
+  structure: string,
+  openRisk: RiskType | null,
+  loadDetail:
+    ((structure: string, risk: RiskType) => Promise<RiskDetail>) | undefined,
+): DetailAnswer | null {
+  const key =
+    openRisk === null || structure === '' ? '' : `${structure} ${openRisk}`;
+  const [answer, setAnswer] = useState<DetailAnswer | null>(null);
+
+  useEffect(() => {
+    if (key === '' || openRisk === null || loadDetail === undefined) return;
+    let live = true;
+    loadDetail(structure, openRisk).then(
+      (detail) => {
+        if (live) setAnswer({ key, detail, error: null });
+      },
+      (error: unknown) => {
+        if (live) setAnswer({ key, detail: null, error: errorMessage(error) });
+      },
+    );
+    return () => {
+      live = false;
+    };
+  }, [key, structure, openRisk, loadDetail]);
+
+  return answer !== null && answer.key === key ? answer : null;
+}

package/src/osiris/ui/PropertyRows.tsx

@@ -0,0 +1,92 @@
+/**
+ * The ten predicted numbers, one row each: a name, a bar and a value.
+ *
+ * The order is the legacy panel's — cLogP, solubility, molweight, TPSA,
+ * drug-likeness, the two hydrogen-bond counts, stereocentres, rotatable bonds,
+ * drug score — and it is `PROPERTY_KEYS`, which the comparison table's columns
+ * and the plot's default axes also read. A reader who learned the panel reads
+ * the table without relearning it.
+ *
+ * A value the predictor could not answer prints the missing marker and draws no
+ * bar. It is never zero: `DrugScoreCalculator` consumes every sentinel and
+ * hands back a plausible number, so a bar drawn from one would be a wrong
+ * answer with nothing saying it is wrong.
+ */
+
+import type { ReactElement } from 'react';
+
+import { MISSING_VALUE } from '../../format/core/missing.ts';
+import { formatDecimal } from '../../format/core/numbers.ts';
+import { barGeometry } from '../core/barGeometry.ts';
+import type { PropertyKey } from '../core/propertyKeys.ts';
+import { PROPERTY_KEYS, propertyValue } from '../core/propertyKeys.ts';
+import { propertyScale } from '../core/scales.ts';
+import type { OsirisProperties } from '../core/types.ts';
+
+import { PropertyBar } from './PropertyBar.tsx';
+
+/** What {@link PropertyRows} needs. */
+export interface PropertyRowsProps {
+  /**
+   * What was predicted, or `null` while the molecule is still being worked on —
+   * in which case every row stands with its name and no value, so nothing moves
+   * when the answer arrives.
+   * @default null
+   */
+  properties?: OsirisProperties | null;
+  /**
+   * The rows to draw. They are drawn in the panel's order whatever order they
+   * are given in, so a narrowed panel still reads as the whole one does.
+   * @default PROPERTY_KEYS
+   */
+  keys?: readonly PropertyKey[];
+}
+
+/**
+ * The property rows, all ten unless fewer are asked, in the panel's order.
+ * @param props - See {@link PropertyRowsProps}.
+ * @returns One row per property.
+ */
+export function PropertyRows(props: PropertyRowsProps): ReactElement {
+  const { properties = null, keys = PROPERTY_KEYS } = props;
+
+  return (
+    <div className="property-rows">
+      {PROPERTY_KEYS.filter((key) => keys.includes(key)).map((key) => (
+        <PropertyRow
+          key={key}
+          propertyKey={key}
+          value={properties === null ? null : propertyValue(properties, key)}
+        />
+      ))}
+    </div>
+  );
+}
+
+interface PropertyRowProps {
+  propertyKey: PropertyKey;
+  value: number | null;
+}
+
+function PropertyRow(props: PropertyRowProps): ReactElement {
+  const { propertyKey, value } = props;
+  const scale = propertyScale(propertyKey);
+  const geometry = barGeometry(propertyKey, value);
+
+  return (
+    <div className="property-row">
+      <span className="property-row__label">
+        {scale.label}
+        {scale.unit === '' ? null : (
+          <span className="property-row__unit">{scale.unit}</span>
+        )}
+      </span>
+      <span className="property-row__bar">
+        {geometry === null ? null : <PropertyBar geometry={geometry} />}
+      </span>
+      <span className="property-row__value">
+        {value === null ? MISSING_VALUE : formatDecimal(value, scale.decimals)}
+      </span>
+    </div>
+  );
+}

package/src/osiris/ui/RiskFindings.tsx

@@ -0,0 +1,137 @@
+/**
+ * Why one risk came back as it did.
+ *
+ * Two branches of the predictor reach the same red square and mean different
+ * things. *This molecule is known to be mutagenic* means the compound's own
+ * idCode is in a list derived from RTECS — data on this exact compound, and
+ * nothing on the drawing to point at. *High-risk fragments indicating
+ * Mutagenicity* means a substructure matched, and that substructure is drawn
+ * beside the molecule with its atoms painted on it.
+ *
+ * Telling them apart is the whole point of opening a square: aspirin, caffeine
+ * and paracetamol are all red through the first branch, and highlighting the
+ * whole molecule there would call the compound its own toxicophore.
+ *
+ * A fragment heading is repeated on each of the fragments under it, so it is
+ * printed once and the matches follow.
+ */
+
+import { Callout, Spinner } from '@blueprintjs/core';
+import type { ReactElement } from 'react';
+
+import { Structure } from '../../structure/ui/Structure.tsx';
+import { RISK_LABELS } from '../core/constants.ts';
+import { KNOWN_MOLECULE_NOTE } from '../core/riskAppearance.ts';
+import type { RiskDetail, RiskFinding, RiskType } from '../core/types.ts';
+
+/** What {@link RiskFindings} needs. */
+export interface RiskFindingsProps {
+  /** Which risk is open. */
+  risk: RiskType;
+  /** The molecule it was assessed on: the idCode, with its coordinates after a space. */
+  structure: string;
+  /**
+   * What the predictor found, or `null` while it is being worked out.
+   * @default null
+   */
+  detail?: RiskDetail | null;
+  /**
+   * Why the explanation could not be fetched, or `null`.
+   * @default null
+   */
+  error?: string | null;
+}
+
+/** How big a drawing in the explanation is, in pixels. */
+const DRAWING = { width: 190, height: 130 };
+
+/**
+ * The explanation of one risk.
+ * @param props - See {@link RiskFindingsProps}.
+ * @returns The predictor's own sentences, with every matched fragment drawn.
+ */
+export function RiskFindings(props: RiskFindingsProps): ReactElement {
+  const { risk, structure, detail = null, error = null } = props;
+
+  if (error !== null) {
+    return <Callout intent="warning">{error}</Callout>;
+  }
+  if (detail === null) {
+    return (
+      // A div, not a paragraph: the spinner draws a div of its own.
+      <div className="osiris-note osiris-note--working">
+        <Spinner size={14} /> Working out why {RISK_LABELS[risk]} came back as
+        it did.
+      </div>
+    );
+  }
+
+  return (
+    <div className="risk-findings">
+      {detail.findings.map((finding, index) => (
+        <Finding
+          // The predictor prints each heading once and each matching fragment
+          // once under it, so the pair names the line without an index.
+          key={`${finding.kind}:${finding.description}:${finding.idCode ?? ''}`}
+          finding={finding}
+          structure={structure}
+          heading={
+            detail.findings[index - 1]?.description === finding.description
+              ? null
+              : finding.description
+          }
+        />
+      ))}
+    </div>
+  );
+}
+
+interface FindingProps {
+  finding: RiskFinding;
+  structure: string;
+  heading: string | null;
+}
+
+function Finding(props: FindingProps): ReactElement {
+  const { finding, structure, heading } = props;
+
+  return (
+    <div className="risk-finding">
+      {heading === null ? null : (
+        <p className="risk-finding__heading">{heading}</p>
+      )}
+      {finding.kind === 'known' ? (
+        <p className="osiris-note">{KNOWN_MOLECULE_NOTE}</p>
+      ) : null}
+      {finding.idCode === null ? null : (
+        <div className="risk-finding__drawings">
+          <figure className="risk-finding__figure">
+            <Structure
+              idCode={finding.idCode}
+              width={DRAWING.width}
+              height={DRAWING.height}
+            />
+            <figcaption>
+              {finding.severity === 'medium' ? 'Medium-risk' : 'High-risk'}{' '}
+              fragment
+            </figcaption>
+          </figure>
+          <figure className="risk-finding__figure">
+            <Structure
+              idCode={structure}
+              width={DRAWING.width}
+              height={DRAWING.height}
+              atomHighlight={[...finding.atoms]}
+              bondHighlight={[...finding.bonds]}
+            />
+            <figcaption>
+              {finding.atoms.length === 0
+                ? 'Not located on this drawing'
+                : 'Where it sits on the molecule'}
+            </figcaption>
+          </figure>
+        </div>
+      )}
+    </div>
+  );
+}