react-cheminfo 0.9.0 → 0.11.0

package/src/projection/core/projectionSamples.ts

@@ -0,0 +1,170 @@
+import {
+  CHART_SERIES_COLORS,
+  chartSeriesColor,
+} from '../../chart/core/chartPalette.ts';
+
+/** One line of the card that appears when the pointer rests on a sample. */
+export interface ProjectionField {
+  /** What the value is. */
+  label: string;
+  /** The value, already written out. */
+  value: string;
+}
+
+/** Who the rows are: what they are called, what they belong to, what is known. */
+export interface ProjectionSamples {
+  /**
+   * A stable name per row, in the score matrix's row order. It is the currency
+   * of the selection callbacks, so a caller never has to keep a second index.
+   */
+  ids: readonly string[];
+  /**
+   * What each row belongs to — a species, a batch, a cluster. A row with no
+   * group is drawn in the muted ink and left out of every outline.
+   * @default undefined — every row is one crowd
+   */
+  groups?: ReadonlyArray<string | undefined>;
+  /**
+   * The order the groups are listed and coloured in.
+   * @default the order the groups first appear in `groups`
+   */
+  groupOrder?: readonly string[];
+  /**
+   * What the set of groups is called, for the legend's heading and the hover
+   * card — `Species`, `Cluster`, `Batch`.
+   * @default 'Group'
+   */
+  groupLabel?: string;
+  /**
+   * A colour per group. Anything not named here takes the next unused colour
+   * of the shared palette, so two groups never share one.
+   * @default undefined — every group is coloured from the palette
+   */
+  groupColors?: Readonly<Record<string, string>>;
+  /**
+   * Everything else worth showing about one row. A callback rather than an
+   * array, so a table of ten thousand rows builds one record when a reader
+   * points at one row, and none otherwise.
+   * @default undefined — the card shows the id, the group and the two axes
+   */
+  fields?: (index: number) => readonly ProjectionField[];
+}
+
+/** The groups as the viewer draws them, resolved once per change. */
+export interface ResolvedProjectionGroups {
+  /** What the set of groups is called. */
+  label: string;
+  /** The groups, in the order they are listed and coloured. */
+  entries: ReadonlyArray<{
+    /** The group's own name, which is also its id. */
+    id: string;
+    /** What it is called; the same as `id` today, kept apart for a future translation. */
+    label: string;
+    /** Its colour. */
+    color: string;
+    /** How many rows are in it. */
+    count: number;
+  }>;
+  /** Which group each row is in, as an index into `entries`, or `-1`. */
+  groupOf: Int32Array;
+}
+
+const NO_GROUP = -1;
+const DEFAULT_GROUP_LABEL = 'Group';
+
+interface GroupEntry {
+  id: string;
+  label: string;
+  color: string;
+  count: number;
+}
+
+/**
+ * The groups a set of samples has, in a shape a legend and a plot can both
+ * read.
+ *
+ * A group named in `groupOrder` but held by no row is kept, so a legend does
+ * not reshuffle when a filter empties one; a row naming a group that is not in
+ * `groupOrder` is appended in the order it appears.
+ * @param samples - Who the rows are.
+ * @param count - How many rows there are, which is the score matrix's height.
+ * @returns The resolved groups. A set of samples with no `groups` gives no
+ * entries at all, and every row lands at `-1`.
+ */
+export function resolveProjectionGroups(
+  samples: ProjectionSamples,
+  count: number,
+): ResolvedProjectionGroups {
+  const rowCount = Number.isFinite(count) ? Math.max(0, Math.floor(count)) : 0;
+  const label = samples.groupLabel ?? DEFAULT_GROUP_LABEL;
+  const groupOf = new Int32Array(rowCount).fill(NO_GROUP);
+  const { groups, groupColors, groupOrder } = samples;
+  if (groups === undefined) return { label, entries: [], groupOf };
+
+  const entries: GroupEntry[] = [];
+  const indexOfGroup = new Map<string, number>();
+  if (groupOrder !== undefined) {
+    for (const id of groupOrder) appendGroup(entries, indexOfGroup, id);
+  }
+
+  for (let row = 0; row < rowCount; row++) {
+    const id = groups[row];
+    if (id === undefined) continue;
+    const at = appendGroup(entries, indexOfGroup, id);
+    groupOf[row] = at;
+    const entry = entries[at];
+    if (entry !== undefined) entry.count++;
+  }
+
+  paintGroups(entries, groupColors);
+  return { label, entries, groupOf };
+}
+
+function appendGroup(
+  entries: GroupEntry[],
+  indexOfGroup: Map<string, number>,
+  id: string,
+): number {
+  const known = indexOfGroup.get(id);
+  if (known !== undefined) return known;
+  const at = entries.length;
+  indexOfGroup.set(id, at);
+  entries.push({ id, label: id, color: '', count: 0 });
+  return at;
+}
+
+function paintGroups(
+  entries: GroupEntry[],
+  pinned: Readonly<Record<string, string>> | undefined,
+): void {
+  // Every pinned colour is taken out of the palette before any group draws
+  // from it, so pinning the third group's hue onto the first does not leave
+  // two groups wearing it.
+  const taken = new Set<string>();
+  if (pinned !== undefined) {
+    for (const entry of entries) {
+      const color = pinned[entry.id];
+      if (color !== undefined) taken.add(color.toLowerCase());
+    }
+  }
+
+  let cursor = 0;
+  for (const entry of entries) {
+    const own = pinned?.[entry.id];
+    if (own !== undefined) {
+      entry.color = own;
+      continue;
+    }
+    let color = chartSeriesColor(cursor, 'group');
+    while (
+      cursor < CHART_SERIES_COLORS.length &&
+      taken.has(color.toLowerCase())
+    ) {
+      cursor++;
+      color = chartSeriesColor(cursor, 'group');
+    }
+    cursor++;
+    taken.add(color.toLowerCase());
+    entry.color = color;
+  }
+}

package/src/projection/core/projectionStrings.ts

@@ -0,0 +1,281 @@
+import type {
+  ProjectionOptionId,
+  ProjectionVariablesView,
+} from './projectionOptions.ts';
+import type { ProjectionTab } from './projectionTabs.ts';
+
+/** A worked case under a piece of help: the construct, and what it does. */
+export interface ProjectionHelpExample {
+  /** The construct itself, shown in monospace. */
+  code: string;
+  /**
+   * What the construct is applied to, when showing it alone is half a
+   * demonstration.
+   * @default undefined
+   */
+  input?: string;
+  /**
+   * One line saying what the example demonstrates.
+   * @default undefined
+   */
+  note?: string;
+}
+
+/**
+ * Everything one option's help says.
+ *
+ * It restates the shape the help domain renders rather than importing it,
+ * because that type is declared beside a React component and every word of a
+ * viewer has to stay readable from a server. The shapes match, so a piece of
+ * help written here is handed straight to a tooltip.
+ */
+export interface ProjectionHelp {
+  /** First line, in bold: what the option is, not what its label already says. */
+  title: string;
+  /** The explanation, one or two sentences. */
+  body: string;
+  /**
+   * A concrete case, because a definition without one is what makes a reader
+   * give up.
+   * @default undefined
+   */
+  example?: ProjectionHelpExample;
+}
+
+/**
+ * The help behind every option's glyph.
+ *
+ * It is keyed by {@link ProjectionOptionId} rather than written as a loose
+ * list, so a control added to the floating bar cannot ship without the
+ * sentence that says what it does.
+ */
+export const PROJECTION_HELP: Record<ProjectionOptionId, ProjectionHelp> = {
+  xAxis: {
+    title: 'Across',
+    body: 'Which pattern of difference runs left to right. The first one is the strongest.',
+  },
+  yAxis: {
+    title: 'Up',
+    body: 'Which pattern of difference runs bottom to top.',
+  },
+  zAxis: {
+    title: 'Into',
+    body: 'Which pattern of difference runs away from you, into the box. Only the cloud draws it; the map and the pair grid never read it.',
+  },
+  cloudGesture: {
+    title: 'Drag does',
+    body: 'Turning the box and drawing a lasso both want a plain drag, so you say which one it is. Inside a lasso, Shift still adds and Alt still takes away.',
+  },
+  colorBy: {
+    title: 'Colour by',
+    body: 'What a dot’s colour stands for. Colouring by nothing is useful when the groups are what you are trying to find rather than what you already know.',
+  },
+  ellipse: {
+    title: 'Group outlines',
+    body: 'Each outline is drawn to cover about that share of its group’s samples, assuming the group is roughly bell-shaped. It is a summary of where a group sits, not a boundary.',
+    example: {
+      code: '95% of samples',
+      note: 'Two standard deviations is often assumed to mean 95%. On a map it covers 86%, which is why the choices here are written as shares.',
+    },
+  },
+  pointRadius: {
+    title: 'Dot size',
+    body: 'Smaller dots for a crowded map, larger ones for a sparse one or a projector.',
+  },
+  showGroupMeans: {
+    title: 'Group averages',
+    body: 'Marks the average position of each group with a cross. A sample far from its own cross is the one the grouping fits worst.',
+  },
+  showGroupLabels: {
+    title: 'Category names',
+    body: 'Writes each group’s name once, over the middle of that group. Names that would land on each other are moved aside, with a line back to the crowd they name, and one with nowhere left to go is dropped rather than written over another. Past a handful of groups the key runs out of room and this is the only way to tell which crowd is which without counting colours.',
+  },
+  showIds: {
+    title: 'Sample names',
+    body: 'Writes every sample’s own name beside its dot. It is what turns a dot sitting on its own into something you can go and look up. In a crowd there is only room for some of the names, so the ones that do not fit are left out rather than written over each other.',
+    example: {
+      code: '0326_3a',
+      note: 'The name is whatever you handed in as the sample’s id, so it is the one you can find again in your own files.',
+    },
+  },
+  pairCount: {
+    title: 'Components',
+    body: 'How many components the grid lays out, up to six. Past that the cells get too small to read, so the grid drops one on its own when the panel is narrow.',
+  },
+  variablesView: {
+    title: 'Show',
+    body: 'What each panel draws. "Effect on a sample" is the only one you can read without knowing how the maths works: it shows what a sample at each end of this component actually looks like.',
+  },
+  variablesCount: {
+    title: 'Panels',
+    body: 'How many components to draw. The later ones usually carry noise rather than a pattern.',
+  },
+  sharedScale: {
+    title: 'One scale for all',
+    body: 'Draws every panel on the same vertical scale, so a component that accounts for two per cent of the differences looks small. Fitting each panel to itself makes it look as important as the first.',
+  },
+  showAverage: {
+    title: 'Average sample',
+    body: 'Draws the average of all your samples faintly behind each panel. Without it you cannot tell which peak a wiggle belongs to.',
+  },
+  spread: {
+    title: 'How far',
+    body: 'How far along the component the average sample is pushed. Two standard deviations reaches past most of your samples in both directions.',
+  },
+  variableOrder: {
+    title: 'Bar order',
+    body: 'Keep your column order so the panels line up and can be read down a column, or sort each panel by how heavily that component leans on each measurement.',
+  },
+  shareTarget: {
+    title: 'Target',
+    body: 'Marks how many components you need before they account for this much of the differences. Set it to zero to draw no marker.',
+  },
+  selectMode: {
+    title: 'Drag does',
+    body: 'What a plain drag does to what is already selected. Holding shift always adds and holding alt always removes, whatever this says.',
+  },
+};
+
+/**
+ * The short form of each tab's name, for a bar too narrow for the long one.
+ *
+ * Written out rather than truncated, because "How much each explains" cut to
+ * the width that fits reads "How much each e…", which tells the reader less
+ * than the one word the tab is actually about.
+ */
+export const PROJECTION_SHORT_TAB: Record<ProjectionTab, string> = {
+  map: 'Map',
+  space: '3D',
+  pairs: 'Pairs',
+  variables: 'Differs',
+  shares: 'Explains',
+};
+
+/** The words the settings bar writes on itself. */
+export interface ProjectionBarWords {
+  /**
+   * The one word written in front of each setting's value where the bar has
+   * room for it. One word rather than the setting's full name: the name is
+   * read once and the value every time, so `Outlines 95%` is what a reader
+   * scanning the bar needs and `Group outlines` is what the pointer is told.
+   */
+  key: {
+    /** In front of what the colour stands for. */
+    colorBy: string;
+    /** In front of how much of a group its outline covers. */
+    ellipse: string;
+    /** In front of what a drag over the cloud does. */
+    cloudGesture: string;
+    /** In front of how many components the pair grid lays out. */
+    pairCount: string;
+    /** In front of what the "what differs" panels are drawing. */
+    variablesView: string;
+    /** In front of how much of the differences is to be accounted for. */
+    shareTarget: string;
+  };
+  /**
+   * What each of the map's two name switches is called.
+   *
+   * They ride the bar as glyphs rather than words — a switch has no value to
+   * write, so a word beside it would be a caption, and four captions is the
+   * bar the ladder exists to avoid — so this is what the pointer and a screen
+   * reader are told, and it has to name the action rather than the setting.
+   */
+  switches: {
+    /** The switch that writes each group's name over its own crowd. */
+    showGroupLabels: string;
+    /** The switch that writes each sample's name beside its dot. */
+    showIds: string;
+  };
+  /** What "the colour stands for nothing" reads. */
+  uncoloured: string;
+  /** What "no outlines at all" reads where there is no room for a sentence. */
+  noOutlines: string;
+  /** What the settings gathered into one chip are called together. */
+  settings: string;
+  /**
+   * What each view of the "what differs" tab is called.
+   *
+   * They are the reader's own choice rather than the jargon, which is why
+   * `rescaled` is offered as weights in their units: a reader who has not met
+   * a loading cannot pick between four words they have never seen.
+   */
+  view: Record<ProjectionVariablesView, string>;
+}
+
+/** The words the settings bar writes when a site overrides nothing. */
+export const PROJECTION_BAR_WORDS: ProjectionBarWords = {
+  key: {
+    colorBy: 'Colour',
+    ellipse: 'Outlines',
+    cloudGesture: 'Drag',
+    pairCount: 'Components',
+    variablesView: 'Show',
+    shareTarget: 'Target',
+  },
+  switches: {
+    showGroupLabels: 'Show category',
+    showIds: 'Show sample ID',
+  },
+  uncoloured: 'Nothing',
+  noOutlines: 'None',
+  settings: 'How this is drawn',
+  view: {
+    effect: 'Effect on a sample',
+    weights: 'Weights',
+    rescaled: 'Weights in your units',
+    sample: 'Selected sample',
+  },
+};
+
+/**
+ * What each setting is called in the fixed name column of a settings panel.
+ *
+ * The column is eight characters wide and a name in it never wraps, so a name
+ * written in full overlaps the control it names: `One scale for all` runs into
+ * its own switch. Nothing is lost by shortening it, because the sentence the
+ * name gives up is the one the help behind the name still says in full — which
+ * is the whole point of hanging the explanation off the words.
+ */
+export const PROJECTION_PANEL_NAME: Record<ProjectionOptionId, string> = {
+  xAxis: 'Across',
+  yAxis: 'Up',
+  zAxis: 'Into',
+  cloudGesture: 'Drag does',
+  colorBy: 'Colour by',
+  ellipse: 'Outlines',
+  pointRadius: 'Dot size',
+  showGroupMeans: 'Averages',
+  showGroupLabels: 'Category',
+  showIds: 'Sample ID',
+  pairCount: 'Components',
+  variablesView: 'Show',
+  variablesCount: 'Panels',
+  sharedScale: 'One scale',
+  showAverage: 'Average',
+  spread: 'How far',
+  variableOrder: 'Bar order',
+  shareTarget: 'Target',
+  selectMode: 'Drag does',
+};
+
+/**
+ * What each cluster of a settings panel is called, written over it in small
+ * capitals.
+ *
+ * They name the question a cluster answers rather than the settings inside it:
+ * a heading that repeats the names under it has told the reader nothing and
+ * has spent a line of the panel saying it.
+ */
+export const PROJECTION_PANEL_SECTION = {
+  /** Which pattern of difference each direction of the map stands for. */
+  axes: 'Axes',
+  /** How the marks themselves are drawn. */
+  drawing: 'Drawing',
+  /** What a drag over the figure does to the selection. */
+  selecting: 'Selecting',
+  /** What a drag over the cloud does at all, before the selection hears of it. */
+  handling: 'Handling',
+  /** What the panels of the "what differs" tab are measured against. */
+  scale: 'Scale',
+} as const;

package/src/projection/core/projectionTabDefaults.ts

@@ -0,0 +1,63 @@
+import type { ProjectionOptions } from './projectionOptions.ts';
+import { DEFAULT_PROJECTION_OPTIONS } from './projectionOptions.ts';
+import type { ProjectionTab } from './projectionTabs.ts';
+
+/**
+ * The settings each tab owns, back at the values the figure came with.
+ *
+ * A panel offers a way back, and it has to be the way back from *its* figure
+ * rather than from all four: a reader who has spent a minute on the pair grid
+ * and presses Reset there expects the grid to return, not the map's axes to
+ * move behind their back. So each tab lists exactly the options it reads, and
+ * the patch a panel sends touches nothing else.
+ *
+ * A tab lists an option it shares with another — the colour, the outlines —
+ * because it genuinely draws with it; sharing is what makes the two figures
+ * read as one picture, and a reset that skipped the shared settings would
+ * leave the tab half restored.
+ */
+export const PROJECTION_TAB_DEFAULTS: Record<
+  ProjectionTab,
+  Partial<ProjectionOptions>
+> = {
+  map: {
+    xAxis: DEFAULT_PROJECTION_OPTIONS.xAxis,
+    yAxis: DEFAULT_PROJECTION_OPTIONS.yAxis,
+    colorBy: DEFAULT_PROJECTION_OPTIONS.colorBy,
+    ellipse: DEFAULT_PROJECTION_OPTIONS.ellipse,
+    pointRadius: DEFAULT_PROJECTION_OPTIONS.pointRadius,
+    showGroupMeans: DEFAULT_PROJECTION_OPTIONS.showGroupMeans,
+    showGroupLabels: DEFAULT_PROJECTION_OPTIONS.showGroupLabels,
+    showIds: DEFAULT_PROJECTION_OPTIONS.showIds,
+    selectMode: DEFAULT_PROJECTION_OPTIONS.selectMode,
+  },
+  space: {
+    xAxis: DEFAULT_PROJECTION_OPTIONS.xAxis,
+    yAxis: DEFAULT_PROJECTION_OPTIONS.yAxis,
+    zAxis: DEFAULT_PROJECTION_OPTIONS.zAxis,
+    cloudGesture: DEFAULT_PROJECTION_OPTIONS.cloudGesture,
+    colorBy: DEFAULT_PROJECTION_OPTIONS.colorBy,
+    ellipse: DEFAULT_PROJECTION_OPTIONS.ellipse,
+    pointRadius: DEFAULT_PROJECTION_OPTIONS.pointRadius,
+    showGroupLabels: DEFAULT_PROJECTION_OPTIONS.showGroupLabels,
+    showIds: DEFAULT_PROJECTION_OPTIONS.showIds,
+    selectMode: DEFAULT_PROJECTION_OPTIONS.selectMode,
+  },
+  pairs: {
+    pairCount: DEFAULT_PROJECTION_OPTIONS.pairCount,
+    colorBy: DEFAULT_PROJECTION_OPTIONS.colorBy,
+    ellipse: DEFAULT_PROJECTION_OPTIONS.ellipse,
+    pointRadius: DEFAULT_PROJECTION_OPTIONS.pointRadius,
+  },
+  variables: {
+    variablesView: DEFAULT_PROJECTION_OPTIONS.variablesView,
+    variablesCount: DEFAULT_PROJECTION_OPTIONS.variablesCount,
+    sharedScale: DEFAULT_PROJECTION_OPTIONS.sharedScale,
+    showAverage: DEFAULT_PROJECTION_OPTIONS.showAverage,
+    spread: DEFAULT_PROJECTION_OPTIONS.spread,
+    variableOrder: DEFAULT_PROJECTION_OPTIONS.variableOrder,
+  },
+  shares: {
+    shareTarget: DEFAULT_PROJECTION_OPTIONS.shareTarget,
+  },
+};

package/src/projection/core/projectionTabs.ts

@@ -0,0 +1,65 @@
+import type { ProjectionAxis, ProjectionResult } from './projectionResult.ts';
+
+/** Which tab of a projection viewer is showing. The ids are stable, so a site may put one in its own URL. */
+export type ProjectionTab = 'map' | 'space' | 'pairs' | 'variables' | 'shares';
+
+const PAIRS_MINIMUM_AXES = 3;
+
+/**
+ * How many axes a cloud needs, which is one per direction of the box.
+ *
+ * A run that produced two is not shown a third empty axis: the cloud would be
+ * a flat map stood on its edge, which says less than the map it came from.
+ */
+const SPACE_MINIMUM_AXES = 3;
+
+/**
+ * The tabs a result can actually fill.
+ *
+ * A tab is offered because the data for it exists, never because a caller
+ * remembered to ask. That is what stops a UMAP viewer from showing an empty
+ * "how much each explains" tab, and it makes a new method a data shape rather
+ * than a code change — there is no place in the viewer where a method's name
+ * is tested. The map always exists, so the answer is never empty; the shares
+ * tab needs three axes as well as a share on each, because a two-bar chart is
+ * not worth a tab.
+ * A site embedding the viewer in a page of its own may narrow the answer with
+ * `allowed`, which is the one thing that is a caller's business rather than the
+ * data's: a page that only has room for the map, or that has already explained
+ * the components in its own prose, says so. It can only ever take tabs away —
+ * naming one the result cannot fill does not conjure it.
+ * @param result - The reduced space.
+ * @param allowed - The tabs the site permits, in any order.
+ * @returns The tabs, in reading order. Never empty: the map survives every
+ * filter, because a viewer with no panel at all is not a viewer.
+ */
+export function projectionTabs(
+  result: ProjectionResult,
+  allowed?: readonly ProjectionTab[],
+): ProjectionTab[] {
+  const tabs: ProjectionTab[] = ['map'];
+  const enoughAxes = result.axes.length >= PAIRS_MINIMUM_AXES;
+
+  if (result.axes.length >= SPACE_MINIMUM_AXES) tabs.push('space');
+  if (enoughAxes) tabs.push('pairs');
+  if (result.loadings !== undefined) tabs.push('variables');
+  if (enoughAxes && everyAxisPublishesAShare(result.axes)) tabs.push('shares');
+  if (allowed === undefined) return tabs;
+
+  const permitted = new Set(allowed);
+  const kept: ProjectionTab[] = [];
+  for (const tab of tabs) {
+    if (permitted.has(tab)) kept.push(tab);
+  }
+  return kept.length === 0 ? ['map'] : kept;
+}
+
+function everyAxisPublishesAShare(axes: readonly ProjectionAxis[]): boolean {
+  for (const axis of axes) {
+    const { share } = axis;
+    // One axis without a share is enough: a running total with a hole in it
+    // reads as a total, and would be wrong by however much the hole holds.
+    if (share === undefined || !Number.isFinite(share)) return false;
+  }
+  return true;
+}