react-cheminfo 0.9.0 → 0.10.0

package/src/projection/ui/projectionSelection.ts

@@ -0,0 +1,87 @@
+/**
+ * What a viewer says about its selection, and the translation between the two
+ * ways of naming a row.
+ *
+ * A plot works in row numbers because that is what it drew, and a caller works
+ * in names because that is what its own table holds. Keeping the translation
+ * here, in one direction each way, is what lets the boundary between them be a
+ * documented promise rather than a habit each tab has to remember.
+ */
+
+import type { ScatterSelectionMode } from '../../scatter/core/scatterSelection.ts';
+
+/** What a gesture did to a projection viewer's selection. */
+export interface ProjectionSelection {
+  /** The selected rows, by name, in the score matrix's row order. */
+  ids: readonly string[];
+  /** The same rows as indices into the score matrix. */
+  indices: readonly number[];
+  /** Whether the gesture replaced the previous selection, added to it, or cut from it. */
+  mode: ScatterSelectionMode;
+  /** Which gesture produced it. */
+  source: 'lasso' | 'point' | 'keyboard' | 'group' | 'clear' | 'all';
+}
+
+/**
+ * Where each name sits in the score matrix.
+ *
+ * The first row wins a repeated name. A duplicate id then costs the reader one
+ * unselectable row, which is a great deal better than silently moving their
+ * selection to whichever sample happened to be named the same thing last.
+ * @param ids - The row names, in the score matrix's row order.
+ * @returns The row each name stands for.
+ */
+export function indexProjectionIds(
+  ids: readonly string[],
+): ReadonlyMap<string, number> {
+  const rows = new Map<string, number>();
+  for (let index = 0; index < ids.length; index++) {
+    const id = ids[index];
+    if (id !== undefined && !rows.has(id)) rows.set(id, index);
+  }
+  return rows;
+}
+
+/**
+ * The rows a list of names stands for, ready for a plot to draw.
+ *
+ * A name nothing answers to is dropped rather than reported as a missing row:
+ * a caller restoring a selection saved before its data was filtered should get
+ * back the samples that are still there, not an error about the ones that are
+ * not.
+ * @param names - The names, or nothing at all.
+ * @param rowOfId - From {@link indexProjectionIds}.
+ * @returns The rows, in the order the names were given.
+ */
+export function projectionRowsOf(
+  names: readonly string[] | undefined,
+  rowOfId: ReadonlyMap<string, number>,
+): readonly number[] {
+  if (names === undefined) return EMPTY_SELECTION;
+  const rows: number[] = [];
+  for (const name of names) {
+    const row = rowOfId.get(name);
+    if (row !== undefined) rows.push(row);
+  }
+  return rows;
+}
+
+/**
+ * The names a list of rows stands for, ready to hand back to a caller.
+ * @param rows - The rows, as indices into the score matrix.
+ * @param ids - The row names.
+ * @returns The names, in the order the rows were given.
+ */
+export function projectionNamesOf(
+  rows: readonly number[],
+  ids: readonly string[],
+): readonly string[] {
+  const names: string[] = [];
+  for (const row of rows) {
+    const name = ids[row];
+    if (name !== undefined) names.push(name);
+  }
+  return names;
+}
+
+const EMPTY_SELECTION: readonly number[] = [];

package/src/projection/ui/projectionTabInfo.ts

@@ -0,0 +1,126 @@
+/**
+ * What each tab answers when the reader presses the question mark.
+ *
+ * The viewer is meant to be embedded in somebody else's page, so the paragraph
+ * that used to stand under every figure now waits behind one glyph in the bar:
+ * a reader who wants it opens it, and everybody else pays no vertical space
+ * for it. Not one word of it was dropped in the move — the sentences are the
+ * reason a reader who has never met a component can read the figure at all —
+ * so they are built here, where what a tab claims about its own numbers can be
+ * checked without rendering a chart.
+ */
+
+import { chartShare } from '../../chart/core/chartLabels.ts';
+import type { ExplainedShares } from '../core/explainedShares.ts';
+import type { LoadingProfiles } from '../core/loadingProfiles.ts';
+import type { ProjectionCopy } from '../core/projectionCopy.ts';
+import { fillCopy } from '../core/projectionCopy.ts';
+
+import { legendTitle, variablesCaption } from './projectionVariablesWords.ts';
+
+/**
+ * What the pair grid says about itself.
+ * @param copy - The words the viewer writes.
+ * @param groupLabel - What the set of groups is called.
+ * @param colored - Whether colour stands for the group at all; uncoloured, the
+ * sentence naming the colour would name something the grid is not drawing.
+ * @returns The paragraph.
+ */
+export function projectionPairsInfo(
+  copy: ProjectionCopy,
+  groupLabel: string,
+  colored: boolean,
+): string {
+  if (!colored) return copy.intro.pairs;
+  const key = fillCopy(copy.legend.pairs, { groups: groupLabel });
+  return `${copy.intro.pairs} ${key}`;
+}
+
+/**
+ * What the "what differs" panels say about themselves.
+ *
+ * Both sentences are needed and neither stands in for the other: the first
+ * says what a panel draws, which changes with the view, and the second says
+ * what its colours mean, which is the only place the grey line is named.
+ * @param profiles - The panels as they were built, or `null` when the run
+ * reported no weights and there is nothing to explain.
+ * @param copy - The words the viewer writes.
+ * @param sample - What the one selected sample is called.
+ * @returns The paragraph.
+ */
+export function projectionVariablesInfo(
+  profiles: LoadingProfiles | null,
+  copy: ProjectionCopy,
+  sample: string,
+): string {
+  if (profiles === null) return '';
+  const caption = variablesCaption(profiles, copy);
+  return `${caption} ${legendTitle(profiles, copy, sample)}`;
+}
+
+/**
+ * What the shares figure says about itself, including its own arithmetic.
+ *
+ * The computed sentence sits between the two written ones because it is the
+ * answer the reader came for — how many components they have to keep — while
+ * the sentences around it say what a bar is and what its colour means.
+ * @param shares - The bars, already worked out.
+ * @param copy - The words the viewer writes.
+ * @returns The paragraph.
+ */
+export function projectionSharesInfo(
+  shares: ExplainedShares | null,
+  copy: ProjectionCopy,
+): string {
+  if (shares === null) return copy.intro.shares;
+  const counted = projectionSharesSentence(shares, copy);
+  const parts = [copy.intro.shares, counted, copy.legend.shares];
+  return parts.filter((part) => part !== '').join(' ');
+}
+
+/**
+ * What the shares tab says about its own numbers, in two sentences at most.
+ *
+ * The second is left out when the reader asked for no target, and when the
+ * first component already reaches it: "the first 1 components together" is
+ * both ungrammatical and a restatement of the sentence before it.
+ * @param shares - The bars.
+ * @param copy - The words the viewer writes.
+ * @returns The sentence.
+ */
+export function projectionSharesSentence(
+  shares: ExplainedShares,
+  copy: ProjectionCopy,
+): string {
+  const { components, target, reachesTargetAt } = shares;
+  const first = components[0];
+  if (first === undefined) return '';
+  const opening = fillCopy(copy.sentence.sharesFirst, {
+    percent: writeShare(first.share),
+  });
+  if (target === 0 || reachesTargetAt === 1) return opening;
+  if (reachesTargetAt !== null) {
+    return `${opening} ${fillCopy(copy.sentence.sharesTarget, {
+      count: String(reachesTargetAt),
+      percent: writeShare(components[reachesTargetAt - 1]?.cumulative ?? 0),
+    })}`;
+  }
+  return `${opening} ${fillCopy(copy.sentence.sharesNoTarget, {
+    count: String(components.length),
+    percent: writeShare(components.at(-1)?.cumulative ?? 0),
+  })}`;
+}
+
+/**
+ * A share written as a percentage, at the precision every other figure of the
+ * family writes it at.
+ *
+ * The bars beside this sentence are named `PC1 — 73.0 %`, so a sentence saying
+ * 72.96% would put the same quantity on screen twice in two shapes and leave
+ * the reader deciding whether they are one number or two.
+ * @param share - The share, between 0 and 1.
+ * @returns It, written out.
+ */
+function writeShare(share: number): string {
+  return `${chartShare(share)}%`;
+}

package/src/projection/ui/projectionTabModels.ts

@@ -0,0 +1,106 @@
+/**
+ * The two figures a tab and the settings bar both have to know about.
+ *
+ * The panels of "what differs" and the bars of "how much each explains" are
+ * each read twice: once by the figure that draws them, and once by the
+ * question mark in the bar, which says in words what the picture says in
+ * marks. Building them here means the pair cannot disagree, and that a
+ * paragraph quoting `95.8%` is quoting the number the bars were drawn from
+ * rather than a second calculation of it.
+ */
+
+import { useMemo } from 'react';
+
+import type { MatrixLike } from '../../chart/core/matrix.ts';
+import type { ExplainedShares } from '../core/explainedShares.ts';
+import { explainedShares } from '../core/explainedShares.ts';
+import type { LoadingProfiles } from '../core/loadingProfiles.ts';
+import { loadingProfiles } from '../core/loadingProfiles.ts';
+import type { ProjectionOptions } from '../core/projectionOptions.ts';
+import type { ProjectionResult } from '../core/projectionResult.ts';
+import type { ProjectionSamples } from '../core/projectionSamples.ts';
+
+/** What {@link useProjectionModels} needs. */
+export interface ProjectionModelsInput {
+  /** What the run produced, whatever produced it. */
+  result: ProjectionResult;
+  /** Who the rows are, for naming the sample a panel rebuilds. */
+  samples: ProjectionSamples;
+  /** Every option, already made safe against the result. */
+  options: ProjectionOptions;
+  /** The selected rows, as indices into the score matrix. */
+  selected: readonly number[];
+}
+
+/** The figures the tabs and the bar share. */
+export interface ProjectionModels {
+  /**
+   * The "what differs" panels, or `null` when the run reported no weights and
+   * the tab is not offered at all.
+   */
+  profiles: LoadingProfiles | null;
+  /** The "how much each explains" bars. */
+  shares: ExplainedShares;
+  /**
+   * What the one selected sample is called, which is the only row a panel ever
+   * names. With none or several selected it is the row number, so the sentence
+   * about it still reads.
+   */
+  sampleName: string;
+}
+
+/**
+ * Build both, once per change.
+ * @param input - See {@link ProjectionModelsInput}.
+ * @returns See {@link ProjectionModels}.
+ */
+export function useProjectionModels(
+  input: ProjectionModelsInput,
+): ProjectionModels {
+  const { result, samples, options, selected } = input;
+  const { loadings, axes, scores } = result;
+
+  const one = selected.length === 1 ? (selected[0] ?? -1) : -1;
+
+  const profiles = useMemo<LoadingProfiles | null>(() => {
+    if (loadings === undefined) return null;
+    return loadingProfiles({
+      loadings,
+      axes,
+      view: options.variablesView,
+      count: options.variablesCount,
+      spread: options.spread,
+      sharedScale: options.sharedScale,
+      order: options.variableOrder,
+      sampleScores:
+        one < 0 ? undefined : rowScores(scores, one, options.variablesCount),
+    });
+  }, [loadings, axes, scores, options, one]);
+
+  const shares = useMemo(
+    () => explainedShares(axes, { target: options.shareTarget }),
+    [axes, options.shareTarget],
+  );
+
+  return {
+    profiles,
+    shares,
+    sampleName: samples.ids[one] ?? `Row ${one + 1}`,
+  };
+}
+
+/**
+ * One row of the score matrix, read where it stands.
+ * @param scores - Where every sample landed.
+ * @param row - Which row.
+ * @param count - How many components the panels draw.
+ * @returns That sample's scores.
+ */
+function rowScores(scores: MatrixLike, row: number, count: number): number[] {
+  const wanted = Math.max(0, Math.min(count, scores.columns));
+  const values = new Array<number>(wanted);
+  for (let column = 0; column < wanted; column++) {
+    values[column] = scores.get(row, column);
+  }
+  return values;
+}

package/src/projection/ui/projectionTabStyles.ts

@@ -0,0 +1,161 @@
+/**
+ * Every rule the tabs are drawn with.
+ *
+ * They are here rather than in each tab because the tabs have to read as one
+ * figure seen several ways: a panel title on "what differs" and the name over
+ * a bar on "how much each explains" are the same size and the same grey, or
+ * the reader meets what looks like two products in one viewer. Every colour is
+ * a family token, so a tab on any site of the family is that site's own grey.
+ *
+ * The numbers are the ones an embedded figure can afford. The viewer is a
+ * guest on somebody else's page, so nothing here reserves room for chrome that
+ * is not carrying information: the explanation is behind the question mark in
+ * the bar and the key floats on the picture, which leaves the tab itself
+ * spending its height on the figure alone.
+ */
+
+import type { CSSProperties } from 'react';
+
+import {
+  CHART_BASE_MARGINS,
+  CHART_TICK_ROOM,
+  CHART_TITLE_OFFSET,
+  CHART_TITLE_ROOM,
+} from '../../chart/ui/chartStyles.ts';
+/** Height a tab takes when the viewer does not say, and the least one panel gets. */
+export const PROJECTION_TAB_HEIGHT = 420;
+export const SMALLEST_PANEL = 110;
+
+/** Room the title over a panel takes, which the panel itself gives up. */
+export const PANEL_TITLE_ROOM = 18;
+
+/**
+ * Where the plot rectangle falls inside a figure whose two axes are both
+ * named, which is every scores map this viewer draws.
+ *
+ * It is the frame's own arithmetic repeated rather than measured, because the
+ * chrome that has to stay off the axis labels — the floating key — is laid out
+ * in HTML beside the drawing rather than inside it, and has nothing to measure
+ * until after it has been placed.
+ */
+export const PROJECTION_PLOT_ROOM = {
+  top: CHART_BASE_MARGINS.top,
+  right: CHART_BASE_MARGINS.right,
+  bottom:
+    CHART_BASE_MARGINS.bottom +
+    CHART_TICK_ROOM.bottom +
+    CHART_TITLE_ROOM.bottom,
+  left: CHART_BASE_MARGINS.left + CHART_TICK_ROOM.left + CHART_TITLE_ROOM.left,
+} as const;
+
+/**
+ * The rectangle the data is drawn in, as a layer of its own.
+ *
+ * Chrome placed in it is placed against the picture rather than against the
+ * figure's box, which is what keeps a floating key off the axis labels without
+ * either of them knowing about the other. It takes no pointer events: only the
+ * card inside it takes those back.
+ */
+export const PROJECTION_PLOT_AREA_STYLE = {
+  position: 'absolute',
+  top: PROJECTION_PLOT_ROOM.top,
+  right: PROJECTION_PLOT_ROOM.right,
+  bottom: PROJECTION_PLOT_ROOM.bottom,
+  left: PROJECTION_PLOT_ROOM.left,
+  pointerEvents: 'none',
+} as const satisfies CSSProperties;
+
+/** A column of panels, tight enough that the stack reads as one figure. */
+export const STACK_STYLE = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 2,
+} as const satisfies CSSProperties;
+
+/**
+ * A panel's title.
+ *
+ * The swatch carries the component's colour and the words never do: the
+ * palette holds a yellow, and a yellow title on a white ground is a title
+ * nobody reads.
+ */
+export const PANEL_TITLE_STYLE = {
+  display: 'inline-flex',
+  alignItems: 'center',
+  gap: 5,
+  color: 'var(--text)',
+  fontSize: 11,
+  fontWeight: 600,
+} as const satisfies CSSProperties;
+
+/** The square of colour in front of a panel's title or a bar's name. */
+export const SWATCH_STYLE = {
+  display: 'inline-block',
+  width: 9,
+  height: 9,
+  borderRadius: 2,
+} as const satisfies CSSProperties;
+
+/**
+ * Everything, as a percentage.
+ *
+ * The shares tab draws its vertical axis from nothing to this rather than from
+ * 0 to 1, so its ticks read 0, 25, 50 … and a reader never has to multiply a
+ * fraction in their head to compare a bar with the sentence about it.
+ */
+export const WHOLE_SHARE = 100;
+
+/** Room under the shares plot for the component names and the caption below them. */
+export const SHARES_BOTTOM_ROOM =
+  CHART_BASE_MARGINS.bottom + CHART_TICK_ROOM.bottom + CHART_TITLE_ROOM.bottom;
+
+/** Where the left edge of the shares plot falls, which its names are laid out from. */
+export const SHARES_LEFT_ROOM =
+  CHART_BASE_MARGINS.left + CHART_TICK_ROOM.left + CHART_TITLE_ROOM.left;
+
+/** Where the right edge of the shares plot falls. */
+export const SHARES_RIGHT_ROOM = CHART_BASE_MARGINS.right;
+
+/** Baselines of a component's name and of the caption under the names. */
+export const SHARES_NAME_OFFSET = 15;
+export const SHARES_CAPTION_OFFSET =
+  CHART_TICK_ROOM.bottom + CHART_TITLE_OFFSET;
+
+/** The layer the component names are written in, outside the frame's own clip. */
+export const AXIS_LAYER_STYLE = {
+  position: 'absolute',
+  inset: 0,
+  pointerEvents: 'none',
+} as const satisfies CSSProperties;
+
+/** One component's name under its bar. */
+export const AXIS_NAME_STYLE = {
+  fill: 'var(--text-muted)',
+  fontSize: 11,
+  userSelect: 'none',
+} as const satisfies CSSProperties;
+
+/** What the horizontal axis measures, written under the names. */
+export const AXIS_CAPTION_STYLE = {
+  fill: 'var(--text-muted)',
+  fontSize: 12,
+  fontWeight: 500,
+  userSelect: 'none',
+} as const satisfies CSSProperties;
+
+/** The running total's own name, written at the right-hand end of its line. */
+export const TOTAL_LABEL_STYLE = {
+  fill: 'var(--text-muted)',
+  fontSize: 11,
+  fontWeight: 600,
+  userSelect: 'none',
+} as const satisfies CSSProperties;
+
+/**
+ * How much one press of the target stepper moves it, in percentage points.
+ *
+ * The bar and the panel behind the cog step the same setting, so they step it
+ * by the same amount: a reader who nudges the target on one and then on the
+ * other must not find it moving in two different sizes.
+ */
+export const PROJECTION_SHARE_STEP = 5;