react-cheminfo 0.10.0 → 0.12.0

package/src/projection/core/pcaResult.ts

@@ -1,6 +1,7 @@
 import type { MatrixLike } from '../../chart/core/matrix.ts';
 import { mappedMatrix, stackedMatrix } from '../../chart/core/matrix.ts';
 
+import { columnStats, widenedLoadings } from './pcaColumns.ts';
 import type { PcaLike } from './pcaLike.ts';
 import type { ProjectionAxis, ProjectionResult } from './projectionResult.ts';
 import type { VariableAxis } from './variableAxis.ts';
@@ -41,8 +42,9 @@ export interface PcaResultOptions {
   scores?: MatrixLike;
   /**
    * Whether the model divided each measurement by its spread — the `scale`
-   * given to `new PCA(...)`. It cannot be read back from the model's public
-   * surface, and getting it wrong offers a view that is the same drawing
+   * given to `new PCA(...)`. A model that reports it through `toJSON`, as
+   * `ml-pca`'s does, is believed instead, so this is read only for a model
+   * that does not. Getting it wrong offers a view that is the same drawing
    * twice.
    * @default false
    */
@@ -82,9 +84,11 @@ export interface PcaResultOptions {
  * @returns The result, with every tab's data filled in.
  * @throws {Error} When `rows` is empty, when a row's length differs from the
  * first row's, when a measurement is not a finite number, or when the model's
- * loadings are not as wide as a row — which is what happens when the model was
- * fitted with `ignoreZeroVariance` and silently dropped a column, and which
- * would otherwise label every loadings panel one measurement out.
+ * loadings are not as wide as a row and the model does not report which
+ * columns it dropped — which is what `ignoreZeroVariance` leaves behind, and
+ * which would otherwise label every loadings panel one measurement out. A
+ * model that does report them keeps each measurement in its own place, with
+ * no weight on the ones it dropped.
  */
 export function pcaResult(
   pca: PcaLike,
@@ -108,8 +112,13 @@ export function pcaResult(
   }
   const width = first.length;
   const { mean, deviation } = columnStats(rows, width);
+  const record = pca.toJSON?.();
 
-  const weights = pca.getLoadings();
+  const weights = widenedLoadings(
+    pca.getLoadings(),
+    record?.excludedFeatures ?? NO_COLUMNS,
+    width,
+  );
   if (weights.columns < width) {
     throw new Error(
       `pcaResult was given rows ${width} measurements wide but a model holding ${weights.columns} weights, which is what \`ignoreZeroVariance\` leaves behind when it drops a column that never moves. Every panel after the dropped one would carry its neighbour's name.`,
@@ -147,50 +156,13 @@ export function pcaResult(
       variables: variables ?? numberedVariables(width),
       mean,
       spread,
-      scales: scaled ? deviation : undefined,
+      scales: (record?.scale ?? scaled) ? deviation : undefined,
       valueLabel,
     },
   };
 }
 
-function columnStats(
-  rows: readonly number[][],
-  width: number,
-): { mean: number[]; deviation: number[] } {
-  // Centred on the average so far, in one pass: a running total of the raw
-  // values squared loses the low bits of a spectrum sitting on a baseline.
-  // `deviation` carries the squared spread until the last loop roots it.
-  const mean = new Array<number>(width).fill(0);
-  const deviation = new Array<number>(width).fill(0);
-  for (let index = 0; index < rows.length; index++) {
-    const row = rows[index];
-    if (row?.length !== width) {
-      throw new Error(
-        `pcaResult was given a row ${row?.length ?? 0} measurements wide at index ${index}, where the first row is ${width} wide.`,
-      );
-    }
-    const seen = index + 1;
-    for (let column = 0; column < width; column++) {
-      const value = row[column];
-      if (value === undefined || !Number.isFinite(value)) {
-        throw new Error(
-          `pcaResult was given ${String(value)} at row ${index}, measurement ${column}. A model carries it on into a map of nothing at all.`,
-        );
-      }
-      const before = mean[column] ?? 0;
-      const step = value - before;
-      const after = before + step / seen;
-      mean[column] = after;
-      deviation[column] = (deviation[column] ?? 0) + step * (value - after);
-    }
-  }
-
-  const divisor = Math.max(1, rows.length - 1);
-  for (let column = 0; column < width; column++) {
-    deviation[column] = Math.sqrt((deviation[column] ?? 0) / divisor);
-  }
-  return { mean, deviation };
-}
+const NO_COLUMNS: readonly number[] = [];
 
 function signsOf(weights: MatrixLike, flip: boolean): Float64Array {
   const signs = new Float64Array(weights.rows).fill(1);

package/src/projection/core/projectionCopy.ts

@@ -1,5 +1,16 @@
-import type { ProjectionCopyPatch } from './projectionCopyPatch.ts';
 import type { ProjectionOptionId } from './projectionOptions.ts';
+import type {
+  ProjectionChoiceWords,
+  ProjectionOutlineWords,
+  ProjectionPanelWords,
+  ProjectionReasonWords,
+} from './projectionPanelWords.ts';
+import {
+  PROJECTION_CHOICE_WORDS,
+  PROJECTION_OUTLINE_WORDS,
+  PROJECTION_PANEL_WORDS,
+  PROJECTION_REASON_WORDS,
+} from './projectionPanelWords.ts';
 import type {
   ProjectionBarWords,
   ProjectionHelp,
@@ -11,12 +22,6 @@ import {
 } from './projectionStrings.ts';
 import type { ProjectionTab } from './projectionTabs.ts';
 
-export type {
-  ProjectionBarWords,
-  ProjectionHelp,
-  ProjectionHelpExample,
-} from './projectionStrings.ts';
-
 /** Every word a projection viewer writes. */
 export interface ProjectionCopy {
   /** What each tab is called. */
@@ -25,10 +30,20 @@ export interface ProjectionCopy {
   shortTab: Record<ProjectionTab, string>;
   /** The words the settings bar writes on itself. */
   bar: ProjectionBarWords;
+  /** The words a settings panel writes around its rows. */
+  panel: ProjectionPanelWords;
+  /** What a greyed control or an unreachable choice tells the pointer. */
+  reason: ProjectionReasonWords;
+  /** What the choices of the settings that offer a few words read. */
+  choice: ProjectionChoiceWords;
+  /** How the size of an outline or a shell is written in full. */
+  outline: ProjectionOutlineWords;
   /** The sentence under each tab and above its figure. */
   intro: {
     /** The map. */
     map: string;
+    /** The cloud. */
+    space: string;
     /** The pair grid. */
     pairs: string;
     /**
@@ -49,6 +64,8 @@ export interface ProjectionCopy {
   legend: {
     /** The map. Carries `{groups}` and `{coverage}`. */
     map: string;
+    /** The cloud. Carries `{groups}` and `{coverage}`. */
+    space: string;
     /** The map with no outlines. Carries `{groups}`. */
     mapNoEllipse: string;
     /** The pair grid. Carries `{groups}`. */
@@ -63,6 +80,12 @@ export interface ProjectionCopy {
     variablesSample: string;
     /** The shares tab. */
     shares: string;
+    /** The note beside a group too small to outline. */
+    notOutlined: string;
+    /** The entry naming the hollow marks of samples placed after fitting. */
+    projected: string;
+    /** The title of a key whose colour stands for nothing, so only shape is left. */
+    shapes: string;
   };
   /** The sentences the viewer builds from the data. */
   sentence: {
@@ -84,6 +107,15 @@ export interface ProjectionCopy {
     lassoRemove: string;
     /** Carries `{names}`. */
     skippedGroups: string;
+    /** Why the hollow dots of samples placed after fitting are worth a look. */
+    projected: string;
+    /** The running total's name on the shares chart. Carries `{percent}`. */
+    runningTotal: string;
+    /**
+     * What pointing at one bar of the shares chart says. Carries `{component}`,
+     * `{share}`, `{count}` and `{total}`.
+     */
+    shareCard: string;
   };
   /** What the buttons read. */
   action: {
@@ -110,6 +142,8 @@ export interface ProjectionCopy {
     component: string;
     /** What many are called. */
     components: string;
+    /** What the vertical axis of a panel drawing weights measures. */
+    weight: string;
   };
 }
 
@@ -126,14 +160,21 @@ export interface ProjectionCopy {
 export const PROJECTION_COPY: ProjectionCopy = {
   tab: {
     map: 'Map',
+    space: 'Map in 3D',
     pairs: 'Every pair',
     variables: 'What differs',
     shares: 'How much each explains',
   },
   shortTab: PROJECTION_SHORT_TAB,
   bar: PROJECTION_BAR_WORDS,
+  panel: PROJECTION_PANEL_WORDS,
+  reason: PROJECTION_REASON_WORDS,
+  choice: PROJECTION_CHOICE_WORDS,
+  outline: PROJECTION_OUTLINE_WORDS,
   intro: {
     map: 'Each dot is one sample. Dots that sit together are alike; dots far apart are the ones that differ most. The two axes are the strongest patterns of difference, called components.',
+    space:
+      'The same map with a third component, in a box you can turn. Two groups that sit on top of each other on the flat map often come apart as soon as the box moves. The frame says which axis is which; the numbers are in the card you get by pointing at a dot.',
     pairs:
       'The same map drawn for every pair of components. A grouping the first two miss often shows up in another pair.',
     variablesContinuous:
@@ -149,6 +190,8 @@ export const PROJECTION_COPY: ProjectionCopy = {
   },
   legend: {
     map: 'Colour = {groups}. Each outline covers about {coverage} of that group, assuming the group is roughly bell-shaped.',
+    space:
+      'Colour = {groups}. Each shell holds about {coverage} of that group, assuming the group is roughly bell-shaped. A shell has to hold a sample in three directions at once, so it is wider than the outline the same share draws on the flat map.',
     mapNoEllipse: 'Colour = {groups}.',
     pairs:
       'Colour = {groups}. The strip along the diagonal shows how the samples spread out along that component on its own.',
@@ -162,6 +205,9 @@ export const PROJECTION_COPY: ProjectionCopy = {
       'Grey is the average sample; the coloured line is {sample} rebuilt from the components shown.',
     shares:
       'Each bar carries the colour its component has on the other tabs; the grey line is the running total.',
+    notOutlined: 'Not outlined: too few samples.',
+    projected: 'Hollow = added after the map was built',
+    shapes: 'Shape = what each mark is.',
   },
   sentence: {
     sharesFirst:
@@ -176,6 +222,11 @@ export const PROJECTION_COPY: ProjectionCopy = {
     lassoAdd: 'Adding to selection',
     lassoRemove: 'Removing from selection',
     skippedGroups: '{names} not outlined: too few samples.',
+    projected:
+      'The hollow dots were placed on the finished map afterwards, so one of them landing far out is a finding rather than a fault.',
+    runningTotal: 'Running total {percent}%',
+    shareCard:
+      '{component} — {share}% of the differences. The first {count} together: {total}%.',
   },
   action: {
     zoomToSelection: 'Zoom to selection',
@@ -190,63 +241,6 @@ export const PROJECTION_COPY: ProjectionCopy = {
     samples: 'samples',
     component: 'component',
     components: 'components',
+    weight: 'Weight',
   },
 };
-
-/**
- * The words the viewer will write, with a site's overrides merged in one key
- * at a time, so a site fixing a single sentence keeps every other default.
- * @param overrides - What the site wants said differently.
- * @returns Every word, complete.
- */
-export function mergeProjectionCopy(
-  overrides?: ProjectionCopyPatch<ProjectionCopy>,
-): ProjectionCopy {
-  if (overrides === undefined) return { ...PROJECTION_COPY };
-  return mergeBranch(
-    PROJECTION_COPY as unknown as Branch,
-    overrides,
-  ) as unknown as ProjectionCopy;
-}
-
-/**
- * A sentence with its placeholders filled in.
- *
- * The placeholders are `{name}`, and one with no value is left in place rather
- * than replaced by an empty string, so a site that mistypes a key sees the
- * mistake in the figure instead of a sentence that quietly loses a number.
- * @param template - The sentence, from {@link ProjectionCopy}.
- * @param values - What each placeholder stands for.
- * @returns The filled sentence.
- */
-export function fillCopy(
-  template: string,
-  values: Readonly<Record<string, string>>,
-): string {
-  return template.replaceAll(PLACEHOLDER, (match: string, name: string) => {
-    const value = values[name];
-    return value === undefined ? match : value;
-  });
-}
-
-const PLACEHOLDER = /\{(?<name>[^{}]+)\}/gu;
-
-type Branch = Record<string, unknown>;
-
-function mergeBranch(base: Branch, overrides: Branch): Branch {
-  const merged: Branch = { ...base };
-  for (const key of Object.keys(overrides)) {
-    const value = overrides[key];
-    if (value === undefined) continue;
-    const current = merged[key];
-    merged[key] =
-      isBranch(current) && isBranch(value)
-        ? mergeBranch(current, value)
-        : value;
-  }
-  return merged;
-}
-
-function isBranch(value: unknown): value is Branch {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}

package/src/projection/core/projectionOptions.ts

@@ -1,8 +1,6 @@
 import type { EllipseSize } from '../../scatter/core/confidenceEllipse.ts';
 import type { ScatterSelectionMode } from '../../scatter/core/scatterSelection.ts';
-
-import type { ProjectionResult } from './projectionResult.ts';
-import { drawableVariablesView } from './variablesView.ts';
+import type { CloudGesture } from '../../scatter3d/core/cloudGesture.ts';
 
 /** What the "what differs" panels draw. */
 export type ProjectionVariablesView =
@@ -33,6 +31,17 @@ export interface ProjectionOptions {
    * @default 1
    */
   yAxis: number;
+  /**
+   * Which axis runs away from the reader, on the cloud alone. The map and the
+   * pair grid never read it, so moving it leaves them where they were.
+   * @default 2
+   */
+  zAxis: number;
+  /**
+   * What a drag over the cloud does: turn the box, or draw a lasso.
+   * @default 'turn'
+   */
+  cloudGesture: CloudGesture;
   /**
    * What decides a dot's colour.
    * @default 'group'
@@ -123,6 +132,8 @@ export type ProjectionOptionId = keyof ProjectionOptions;
 export const DEFAULT_PROJECTION_OPTIONS: ProjectionOptions = {
   xAxis: 0,
   yAxis: 1,
+  zAxis: 2,
+  cloudGesture: 'turn',
   colorBy: 'group',
   ellipse: { kind: 'coverage', probability: 0.95 },
   pointRadius: 3.5,
@@ -139,100 +150,3 @@ export const DEFAULT_PROJECTION_OPTIONS: ProjectionOptions = {
   shareTarget: 0.95,
   selectMode: 'replace',
 };
-
-const SMALLEST_PAIR_GRID = 2;
-const SMALLEST_PANEL_COUNT = 1;
-
-/**
- * The options the viewer will use, with a caller's overrides merged in and
- * every one of them made safe against the result that actually came back.
- *
- * A saved option outlives the data it was made on: reload with fewer samples
- * and axis eight no longer exists. Rather than let a plot ask for a column
- * that is not there, the two axes are pulled back inside what was computed and
- * kept apart, the counts are held inside what exists, and a view whose data is
- * missing falls back to `weights`.
- * @param overrides - What the caller asked for.
- * @param result - The reduced space the options will be applied to.
- * @returns Every option, complete and safe.
- */
-export function resolveProjectionOptions(
-  overrides: Partial<ProjectionOptions> | undefined,
-  result: ProjectionResult,
-): ProjectionOptions {
-  const axisCount = result.axes.length;
-  const lastAxis = Math.max(0, axisCount - 1);
-  const xAxis = clampIndex(pick(overrides, 'xAxis'), lastAxis);
-
-  return {
-    xAxis,
-    yAxis: apart(
-      clampIndex(pick(overrides, 'yAxis'), lastAxis),
-      xAxis,
-      lastAxis,
-    ),
-    colorBy: pick(overrides, 'colorBy'),
-    ellipse: pick(overrides, 'ellipse'),
-    pointRadius: atLeast(pick(overrides, 'pointRadius'), 3.5, 0),
-    showGroupMeans: pick(overrides, 'showGroupMeans'),
-    showGroupLabels: pick(overrides, 'showGroupLabels'),
-    showIds: pick(overrides, 'showIds'),
-    pairCount: clampCount(
-      pick(overrides, 'pairCount'),
-      DEFAULT_PROJECTION_OPTIONS.pairCount,
-      SMALLEST_PAIR_GRID,
-      Math.max(SMALLEST_PAIR_GRID, axisCount),
-    ),
-    variablesView: drawableVariablesView(
-      pick(overrides, 'variablesView'),
-      result.loadings,
-    ),
-    variablesCount: clampCount(
-      pick(overrides, 'variablesCount'),
-      DEFAULT_PROJECTION_OPTIONS.variablesCount,
-      SMALLEST_PANEL_COUNT,
-      Math.max(SMALLEST_PANEL_COUNT, axisCount),
-    ),
-    sharedScale: pick(overrides, 'sharedScale'),
-    showAverage: pick(overrides, 'showAverage'),
-    spread: atLeast(pick(overrides, 'spread'), 2, 0),
-    variableOrder: pick(overrides, 'variableOrder'),
-    shareTarget: Math.min(1, atLeast(pick(overrides, 'shareTarget'), 0.95, 0)),
-    selectMode: pick(overrides, 'selectMode'),
-  };
-}
-
-function pick<Key extends ProjectionOptionId>(
-  overrides: Partial<ProjectionOptions> | undefined,
-  key: Key,
-): ProjectionOptions[Key] {
-  // Only an absent override defers to the default: `ellipse: null` is a
-  // reader who turned the outlines off, not a reader who said nothing.
-  const value = overrides?.[key];
-  return value === undefined ? DEFAULT_PROJECTION_OPTIONS[key] : value;
-}
-
-function clampIndex(value: number, lastAxis: number): number {
-  if (!Number.isFinite(value)) return 0;
-  return Math.min(lastAxis, Math.max(0, Math.floor(value)));
-}
-
-function apart(yAxis: number, xAxis: number, lastAxis: number): number {
-  if (yAxis !== xAxis) return yAxis;
-  // One axis against itself is a diagonal line, which says nothing at all.
-  return xAxis > 0 ? xAxis - 1 : Math.min(1, lastAxis);
-}
-
-function clampCount(
-  value: number,
-  fallback: number,
-  lowest: number,
-  highest: number,
-): number {
-  const wanted = Number.isFinite(value) ? Math.floor(value) : fallback;
-  return Math.min(highest, Math.max(lowest, wanted));
-}
-
-function atLeast(value: number, fallback: number, floor: number): number {
-  return Math.max(floor, Number.isFinite(value) ? value : fallback);
-}

package/src/projection/core/projectionPanelWords.ts

@@ -0,0 +1,152 @@
+import type { ScatterSelectionMode } from '../../scatter/core/scatterSelection.ts';
+import type { CloudGesture } from '../../scatter3d/core/cloudGesture.ts';
+
+import type {
+  ProjectionOptionId,
+  ProjectionOptions,
+} from './projectionOptions.ts';
+
+/** The words a settings panel writes around its rows. */
+export interface ProjectionPanelWords {
+  /**
+   * What each setting is called in the fixed name column of a 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.
+   */
+  name: Record<ProjectionOptionId, string>;
+  /**
+   * What each cluster of a 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.
+   */
+  section: {
+    /** Which pattern of difference each direction of the figure stands for. */
+    axes: string;
+    /** How the marks themselves are drawn. */
+    drawing: string;
+    /** What a drag over the figure does to the selection. */
+    selecting: string;
+    /** What a drag over the cloud does at all, before the selection hears of it. */
+    handling: string;
+    /** What the panels of the "what differs" tab are measured against. */
+    scale: string;
+  };
+}
+
+/**
+ * What the pointer is told about a control that cannot be reached, or a choice
+ * that cannot be taken, written as the thing the data or the reader is missing.
+ */
+export interface ProjectionReasonWords {
+  /** Why the colour cannot be set: the samples carry no groups. */
+  noGroups: string;
+  /** Why the map's outlines cannot be set while nothing is coloured. */
+  uncolouredOutlines: string;
+  /** Why the cloud's shells cannot be set while nothing is coloured. */
+  uncolouredShells: string;
+  /** Why an axis of the map is greyed in the other picker. */
+  axisTakenOnMap: string;
+  /** Why an axis of the cloud is greyed in the two other pickers. */
+  axisTakenInSpace: string;
+  /** Why the "effect on a sample" view is greyed. */
+  noAverage: string;
+  /** Why the "weights in your units" view is greyed. */
+  noScales: string;
+  /** Why the "selected sample" view is greyed. */
+  noSample: string;
+}
+
+/** What the choices of the settings that offer a few words read. */
+export interface ProjectionChoiceWords {
+  /**
+   * What a plain drag does to the selection. One word each, because a segment
+   * has room for one and the line over the plot says the rest while the drag is
+   * under way.
+   */
+  selectMode: Record<ScatterSelectionMode, string>;
+  /** The two orders the bars of a panel can be drawn in, as what the reader gets. */
+  variableOrder: Record<ProjectionOptions['variableOrder'], string>;
+  /**
+   * What a plain drag over the cloud does, written as the action rather than as
+   * the name of a mode: `Turn` is what the hand is about to do.
+   */
+  cloudGesture: Record<CloudGesture, string>;
+}
+
+/** How the size of a group outline, or of a group shell, is written in full. */
+export interface ProjectionOutlineWords {
+  /** The choice that draws no outline on the map. */
+  noOutlines: string;
+  /** The choice that draws no shell in the cloud. */
+  noShells: string;
+  /** A size given as a share. Carries `{share}`. */
+  coverage: string;
+  /** A size given in standard deviations. Carries `{count}` and `{share}`. */
+  standardDeviations: string;
+}
+
+/** The words a settings panel writes when a site overrides nothing. */
+export const PROJECTION_PANEL_WORDS: ProjectionPanelWords = {
+  name: {
+    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',
+  },
+  section: {
+    axes: 'Axes',
+    drawing: 'Drawing',
+    selecting: 'Selecting',
+    handling: 'Handling',
+    scale: 'Scale',
+  },
+};
+
+/** The reasons a greyed control gives when a site overrides nothing. */
+export const PROJECTION_REASON_WORDS: ProjectionReasonWords = {
+  noGroups: 'These samples carry no groups to colour by.',
+  uncolouredOutlines:
+    'Outlines follow the groups, so colour the map by them first.',
+  uncolouredShells:
+    'Shells follow the groups, so colour the cloud by them first.',
+  axisTakenOnMap: 'Already drawn on the other axis.',
+  axisTakenInSpace: 'Already drawn on another axis.',
+  noAverage:
+    'Only when the run reported an average sample to push along the component.',
+  noScales: 'Only when the model divided each measurement by its spread.',
+  noSample: 'Select exactly one sample on the map first.',
+};
+
+/** The words the choices read when a site overrides nothing. */
+export const PROJECTION_CHOICE_WORDS: ProjectionChoiceWords = {
+  selectMode: { replace: 'Replace', add: 'Add', remove: 'Remove' },
+  variableOrder: { original: 'Your order', strongest: 'Strongest first' },
+  cloudGesture: { turn: 'Turn', select: 'Select' },
+};
+
+/** How an outline size is written in full when a site overrides nothing. */
+export const PROJECTION_OUTLINE_WORDS: ProjectionOutlineWords = {
+  noOutlines: 'No outlines',
+  noShells: 'No shells',
+  coverage: '{share} of samples',
+  standardDeviations: '{count} SD (about {share})',
+};

package/src/projection/core/projectionResult.ts

@@ -5,7 +5,7 @@ import type { VariableAxis } from './variableAxis.ts';
 
 /** One axis of a reduced space — a component, a UMAP dimension. */
 export interface ProjectionAxis {
-  /** What it is called on an axis: `PC 1`, `UMAP 1`. */
+  /** What it is called on an axis: `PC1`, `UMAP 1`. */
   name: string;
   /**
    * The share of the differences between the samples it accounts for, between