react-cheminfo 0.9.0 → 0.11.0

package/lib/overlay/ui/overlayValueStyles.d.ts

@@ -0,0 +1,101 @@
+/**
+ * The rules a control that writes its own value is drawn with.
+ *
+ * A bar over a figure used to name its settings and hide their answers: a
+ * caption reading `Colour by` beside a box the reader had to open to learn it
+ * said `Species`. The name of a setting is read once, on the first visit; its
+ * value is read every time the figure is looked at. So these controls write
+ * the value and leave the name to the pointer, the screen reader and the menu
+ * they open.
+ *
+ * None of them carries an outline or a fill at rest. The bar already has one
+ * container edge in the sunken track the tabs sit in, and a second and third
+ * box beside it turn the chrome into the loudest thing on a page whose point
+ * is the picture underneath. What stands in for the box is the ink — the value
+ * at full strength, its key word in the caption's grey — and a ground that
+ * only appears under the pointer.
+ */
+import type { CSSProperties } from 'react';
+import type { OverlayMetrics } from '../core/overlayMetrics.ts';
+/** How a value-bearing control stands. */
+export interface OverlayValueLook {
+    /**
+     * Whether the pointer is over it.
+     * @default false
+     */
+    hovered?: boolean;
+    /**
+     * Whether the keyboard is on it. Drawn as a ring rather than as the hover
+     * ground, because a reader tabbing through a bar has to be able to tell
+     * where the focus is from a control the pointer happens to be resting on.
+     * @default false
+     */
+    focused?: boolean;
+    /**
+     * Whether the choices behind it are showing.
+     * @default false
+     */
+    active?: boolean;
+    /**
+     * Whether it cannot be pressed.
+     * @default false
+     */
+    disabled?: boolean;
+}
+/**
+ * A setting written as its value.
+ *
+ * Its height is a control's, so it stands level with the tab track beside it,
+ * and its width floors at the button size — which is what keeps a setting
+ * reading `95%` at forty pixels under a fingertip instead of shrinking to the
+ * width of three characters.
+ * @param metrics - The measurements the chrome is drawn from.
+ * @param look - See {@link OverlayValueLook}.
+ * @returns The button's rules.
+ */
+export declare function overlayValueButtonStyle(metrics: OverlayMetrics, look: OverlayValueLook): CSSProperties;
+/**
+ * Several settings gathered into one control.
+ *
+ * It takes the sunken ground the tab track has rather than an outline of its
+ * own, so the two things on the bar that hold more than they show are told
+ * apart from the bare glyphs by the same device. Fully rounded, because that
+ * is what says a chip holds a reading rather than that it is one more button.
+ * @param metrics - The measurements the chrome is drawn from.
+ * @param look - See {@link OverlayValueLook}.
+ * @returns The chip's rules.
+ */
+export declare function overlayChipStyle(metrics: OverlayMetrics, look: OverlayValueLook): CSSProperties;
+/**
+ * The value itself, which is what the reader is scanning for.
+ * @returns The value's rules.
+ */
+export declare function overlayValueTextStyle(): CSSProperties;
+/**
+ * The key word in front of a value.
+ *
+ * The caption's grey at the caption's weight, so a reader scanning the bar for
+ * how the figure is drawn reads `Species` and steps over `Colour` — and the
+ * pair still reads as one control rather than as a label and a button.
+ * @returns The key word's rules.
+ */
+export declare function overlayValueKeyStyle(): CSSProperties;
+/**
+ * The hairline between two settings inside a chip.
+ *
+ * Short of the chip's full height, so it separates the two readings without
+ * cutting the chip in half.
+ * @param metrics - The measurements the chrome is drawn from.
+ * @returns The separator's rules.
+ */
+export declare function overlayChipSeparatorStyle(metrics: OverlayMetrics): CSSProperties;
+/**
+ * The caret saying there is more behind the words.
+ *
+ * Faint, because it is the one part of these controls the reader never needs
+ * to read — it says that the value can be changed, and the value is what they
+ * came to see.
+ * @returns The caret's rules.
+ */
+export declare function overlayCaretStyle(): CSSProperties;
+//# sourceMappingURL=overlayValueStyles.d.ts.map

package/lib/overlay/ui/overlayValueStyles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlayValueStyles.d.ts","sourceRoot":"","sources":["../../../src/overlay/ui/overlayValueStyles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAE3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAEhE,0CAA0C;AAC1C,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,cAAc,EACvB,IAAI,EAAE,gBAAgB,GACrB,aAAa,CAwBf;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,cAAc,EACvB,IAAI,EAAE,gBAAgB,GACrB,aAAa,CAyBf;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,aAAa,CAKrD;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,IAAI,aAAa,CAKpD;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,cAAc,GACtB,aAAa,CAOf;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,IAAI,aAAa,CAKjD"}

package/lib/overlay/ui/overlayValueStyles.js

@@ -0,0 +1,166 @@
+/**
+ * The rules a control that writes its own value is drawn with.
+ *
+ * A bar over a figure used to name its settings and hide their answers: a
+ * caption reading `Colour by` beside a box the reader had to open to learn it
+ * said `Species`. The name of a setting is read once, on the first visit; its
+ * value is read every time the figure is looked at. So these controls write
+ * the value and leave the name to the pointer, the screen reader and the menu
+ * they open.
+ *
+ * None of them carries an outline or a fill at rest. The bar already has one
+ * container edge in the sunken track the tabs sit in, and a second and third
+ * box beside it turn the chrome into the loudest thing on a page whose point
+ * is the picture underneath. What stands in for the box is the ink — the value
+ * at full strength, its key word in the caption's grey — and a ground that
+ * only appears under the pointer.
+ */
+/**
+ * A setting written as its value.
+ *
+ * Its height is a control's, so it stands level with the tab track beside it,
+ * and its width floors at the button size — which is what keeps a setting
+ * reading `95%` at forty pixels under a fingertip instead of shrinking to the
+ * width of three characters.
+ * @param metrics - The measurements the chrome is drawn from.
+ * @param look - See {@link OverlayValueLook}.
+ * @returns The button's rules.
+ */
+export function overlayValueButtonStyle(metrics, look) {
+    const { hovered = false, focused = false, active = false } = look;
+    const { disabled = false } = look;
+    const lit = !disabled && (hovered || active);
+    return {
+        boxSizing: 'border-box',
+        display: 'inline-flex',
+        alignItems: 'center',
+        gap: OVERLAY_VALUE_GAP,
+        minWidth: metrics.buttonSize,
+        height: metrics.controlHeight,
+        padding: `0 ${metrics.paddingX}px`,
+        border: 'none',
+        borderRadius: metrics.controlRadius + 1,
+        background: lit ? 'var(--surface-sunken)' : 'transparent',
+        color: 'var(--text)',
+        font: 'inherit',
+        fontSize: metrics.fontSize,
+        lineHeight: 1,
+        whiteSpace: 'nowrap',
+        cursor: disabled ? 'default' : 'pointer',
+        opacity: disabled ? 0.6 : 1,
+        ...focusRing(focused && !disabled),
+    };
+}
+/**
+ * Several settings gathered into one control.
+ *
+ * It takes the sunken ground the tab track has rather than an outline of its
+ * own, so the two things on the bar that hold more than they show are told
+ * apart from the bare glyphs by the same device. Fully rounded, because that
+ * is what says a chip holds a reading rather than that it is one more button.
+ * @param metrics - The measurements the chrome is drawn from.
+ * @param look - See {@link OverlayValueLook}.
+ * @returns The chip's rules.
+ */
+export function overlayChipStyle(metrics, look) {
+    const { hovered = false, focused = false, active = false } = look;
+    const { disabled = false } = look;
+    const lit = !disabled && (hovered || active);
+    return {
+        boxSizing: 'border-box',
+        display: 'inline-flex',
+        alignItems: 'center',
+        gap: OVERLAY_VALUE_GAP,
+        minWidth: metrics.buttonSize,
+        height: metrics.controlHeight,
+        padding: `0 ${metrics.paddingX + 2}px`,
+        border: 'none',
+        borderRadius: metrics.controlHeight / 2,
+        background: 'var(--surface-sunken)',
+        color: 'var(--text)',
+        boxShadow: lit ? 'inset 0 0 0 1px var(--border)' : undefined,
+        font: 'inherit',
+        fontSize: metrics.fontSize,
+        lineHeight: 1,
+        whiteSpace: 'nowrap',
+        cursor: disabled ? 'default' : 'pointer',
+        opacity: disabled ? 0.6 : 1,
+        ...focusRing(focused && !disabled),
+    };
+}
+/**
+ * The value itself, which is what the reader is scanning for.
+ * @returns The value's rules.
+ */
+export function overlayValueTextStyle() {
+    return {
+        color: 'var(--text)',
+        fontWeight: 600,
+    };
+}
+/**
+ * The key word in front of a value.
+ *
+ * The caption's grey at the caption's weight, so a reader scanning the bar for
+ * how the figure is drawn reads `Species` and steps over `Colour` — and the
+ * pair still reads as one control rather than as a label and a button.
+ * @returns The key word's rules.
+ */
+export function overlayValueKeyStyle() {
+    return {
+        color: 'var(--text-muted)',
+        fontWeight: 500,
+    };
+}
+/**
+ * The hairline between two settings inside a chip.
+ *
+ * Short of the chip's full height, so it separates the two readings without
+ * cutting the chip in half.
+ * @param metrics - The measurements the chrome is drawn from.
+ * @returns The separator's rules.
+ */
+export function overlayChipSeparatorStyle(metrics) {
+    return {
+        width: 1,
+        height: Math.max(10, metrics.controlHeight - 14),
+        background: 'var(--border)',
+        margin: `0 ${OVERLAY_VALUE_GAP}px`,
+    };
+}
+/**
+ * The caret saying there is more behind the words.
+ *
+ * Faint, because it is the one part of these controls the reader never needs
+ * to read — it says that the value can be changed, and the value is what they
+ * came to see.
+ * @returns The caret's rules.
+ */
+export function overlayCaretStyle() {
+    return {
+        display: 'inline-flex',
+        color: 'var(--text-faint)',
+    };
+}
+/** What is left between the swatches, the words and the caret. */
+const OVERLAY_VALUE_GAP = 4;
+/**
+ * The ring around the control the keyboard is on.
+ *
+ * Offset by a pixel so it reads as a ring around the control rather than as
+ * the outline these controls spend the rest of their life not having. It falls
+ * back to the text colour on a page that never declared an accent, since a
+ * focus ring nobody can see is the one accessibility fault a keyboard reader
+ * cannot work around.
+ * @param focused - Whether the keyboard is on it.
+ * @returns The outline rules, or nothing.
+ */
+function focusRing(focused) {
+    if (!focused)
+        return {};
+    return {
+        outline: '2px solid var(--accent, var(--text))',
+        outlineOffset: 1,
+    };
+}
+//# sourceMappingURL=overlayValueStyles.js.map

package/lib/overlay/ui/overlayValueStyles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlayValueStyles.js","sourceRoot":"","sources":["../../../src/overlay/ui/overlayValueStyles.ts"],"names":[],"mappings":"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"}

package/lib/projection/core/embeddingResult.d.ts

@@ -0,0 +1,60 @@
+import type { MatrixLike } from '../../chart/core/matrix.ts';
+import type { ProjectionMarker, ProjectionResult } from './projectionResult.ts';
+/** How a {@link ProjectionResult} is built from coordinates alone. */
+export interface EmbeddingResultOptions {
+    /**
+     * What each axis is called.
+     * @default the axes numbered `Dimension 1` upward
+     */
+    names?: readonly string[];
+    /**
+     * What the method is called in the headings.
+     * @default 'Embedding'
+     */
+    method?: string;
+    /**
+     * Reference points drawn over the map.
+     * @default undefined
+     */
+    markers?: readonly ProjectionMarker[];
+    /**
+     * How many leading rows the model was built from, the rest having been
+     * placed into it afterwards — a `getEmbedding()` followed by a `transform()`
+     * gives exactly that order.
+     * @default undefined — every row built the model
+     */
+    fittedCount?: number;
+    /**
+     * Whether the coordinates are copied on the way in.
+     *
+     * They are, because the library that produces most of them hands out the
+     * array it is still working on. Every published `umap-js`, 1.0.0 through
+     * 1.4.0, returns its live embedding from `getEmbedding()` without a copy,
+     * and its `transform()` writes back into that same array whenever the batch
+     * being placed is the same size as the training set — so a viewer holding
+     * the reference would quietly redraw coordinates that had moved under it,
+     * with nothing anywhere reporting a fault. The copy costs one pass over
+     * `rows × columns`, and an embedding has two or three columns by
+     * definition, which is what makes the safe default affordable here and not
+     * on the principal-component path.
+     *
+     * Pass `false` for a progressive layout that is being animated: during
+     * fitting the live array is the point, and a copy would freeze the picture
+     * on its first frame.
+     * @default true
+     */
+    snapshot?: boolean;
+}
+/**
+ * Coordinates from any method as the viewer reads them.
+ *
+ * This is the door every method that is not a principal component analysis
+ * comes through. No axis carries a share and there are no loadings, so the
+ * viewer offers exactly the tabs the coordinates can fill — which for a
+ * two-dimensional UMAP is the map alone.
+ * @param coordinates - One row per sample, one column per axis.
+ * @param options - See {@link EmbeddingResultOptions}.
+ * @returns The result.
+ */
+export declare function embeddingResult(coordinates: ReadonlyArray<ArrayLike<number>> | MatrixLike, options?: EmbeddingResultOptions): ProjectionResult;
+//# sourceMappingURL=embeddingResult.d.ts.map

package/lib/projection/core/embeddingResult.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embeddingResult.d.ts","sourceRoot":"","sources":["../../../src/projection/core/embeddingResult.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAG7D,OAAO,KAAK,EAEV,gBAAgB,EAChB,gBAAgB,EACjB,MAAM,uBAAuB,CAAC;AAE/B,sEAAsE;AACtE,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,OAAO,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACtC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,WAAW,EAAE,aAAa,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,GAAG,UAAU,EAC1D,OAAO,GAAE,sBAA2B,GACnC,gBAAgB,CAiBlB"}

package/lib/projection/core/embeddingResult.js

@@ -0,0 +1,52 @@
+import { rowMatrix } from "../../chart/core/matrix.js";
+/**
+ * Coordinates from any method as the viewer reads them.
+ *
+ * This is the door every method that is not a principal component analysis
+ * comes through. No axis carries a share and there are no loadings, so the
+ * viewer offers exactly the tabs the coordinates can fill — which for a
+ * two-dimensional UMAP is the map alone.
+ * @param coordinates - One row per sample, one column per axis.
+ * @param options - See {@link EmbeddingResultOptions}.
+ * @returns The result.
+ */
+export function embeddingResult(coordinates, options = {}) {
+    const { names, method = 'Embedding', markers, fittedCount, snapshot = true, } = options;
+    // A matrix is told from a list of rows by the one method a matrix has.
+    const read = isMatrix(coordinates) ? coordinates : rowMatrix(coordinates);
+    const scores = snapshot ? copyMatrix(read) : read;
+    const axes = [];
+    for (let index = 0; index < scores.columns; index++) {
+        axes.push({ name: names?.[index] ?? `Dimension ${index + 1}` });
+    }
+    return { method, axes, scores, markers, fittedCount };
+}
+/**
+ * The same values, in a buffer nothing else holds.
+ * @param source - The matrix to read.
+ * @returns A matrix over a private copy of every value.
+ */
+function copyMatrix(source) {
+    const { rows, columns } = source;
+    const values = new Float64Array(rows * columns);
+    for (let row = 0; row < rows; row++) {
+        const offset = row * columns;
+        for (let column = 0; column < columns; column++) {
+            values[offset + column] = source.get(row, column);
+        }
+    }
+    return {
+        rows,
+        columns,
+        get(row, column) {
+            if (row < 0 || row >= rows || column < 0 || column >= columns) {
+                return Number.NaN;
+            }
+            return values[row * columns + column];
+        },
+    };
+}
+function isMatrix(coordinates) {
+    return typeof coordinates.get === 'function';
+}
+//# sourceMappingURL=embeddingResult.js.map

package/lib/projection/core/embeddingResult.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embeddingResult.js","sourceRoot":"","sources":["../../../src/projection/core/embeddingResult.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAsDvD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAC7B,WAA0D,EAC1D,UAAkC,EAAE;IAEpC,MAAM,EACJ,KAAK,EACL,MAAM,GAAG,WAAW,EACpB,OAAO,EACP,WAAW,EACX,QAAQ,GAAG,IAAI,GAChB,GAAG,OAAO,CAAC;IACZ,uEAAuE;IACvE,MAAM,IAAI,GAAG,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;IAC1E,MAAM,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAElD,MAAM,IAAI,GAAqB,EAAE,CAAC;IAClC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,CAAC;QACpD,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,KAAK,CAAC,IAAI,aAAa,KAAK,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC;IAClE,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC;AACxD,CAAC;AAED;;;;GAIG;AACH,SAAS,UAAU,CAAC,MAAkB;IACpC,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;IACjC,MAAM,MAAM,GAAG,IAAI,YAAY,CAAC,IAAI,GAAG,OAAO,CAAC,CAAC;IAChD,KAAK,IAAI,GAAG,GAAG,CAAC,EAAE,GAAG,GAAG,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC;QACpC,MAAM,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC;QAC7B,KAAK,IAAI,MAAM,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC;YAChD,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QACpD,CAAC;IACH,CAAC;IACD,OAAO;QACL,IAAI;QACJ,OAAO;QACP,GAAG,CAAC,GAAW,EAAE,MAAc;YAC7B,IAAI,GAAG,GAAG,CAAC,IAAI,GAAG,IAAI,IAAI,IAAI,MAAM,GAAG,CAAC,IAAI,MAAM,IAAI,OAAO,EAAE,CAAC;gBAC9D,OAAO,MAAM,CAAC,GAAG,CAAC;YACpB,CAAC;YACD,OAAO,MAAM,CAAC,GAAG,GAAG,OAAO,GAAG,MAAM,CAAW,CAAC;QAClD,CAAC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,QAAQ,CACf,WAA0D;IAE1D,OAAO,OAAQ,WAA0B,CAAC,GAAG,KAAK,UAAU,CAAC;AAC/D,CAAC"}

package/lib/projection/core/explainedShares.d.ts

@@ -0,0 +1,51 @@
+import type { ProjectionAxis } from './projectionResult.ts';
+/** One bar of the "how much each explains" tab. */
+export interface ComponentShare {
+    /** The number written on the axis, counting from one. */
+    number: number;
+    /** What it is called, e.g. `PC 3`. */
+    label: string;
+    /** Its colour, the same one it carries on every other tab. */
+    color: string;
+    /** Its own share, between 0 and 1. */
+    share: number;
+    /** Everything up to and including it, between 0 and 1. */
+    cumulative: number;
+    /**
+     * The variance of its scores, for the fine print of a hover card.
+     * @default undefined
+     */
+    eigenvalue?: number;
+}
+/** Everything the "how much each explains" tab draws. */
+export interface ExplainedShares {
+    /** One entry per component, largest first. */
+    components: readonly ComponentShare[];
+    /** The cumulative share the marker aims at; `0` draws no marker. */
+    target: number;
+    /**
+     * The number, counting from one, of the first component reaching the target,
+     * or `null` when none of them does.
+     */
+    reachesTargetAt: number | null;
+}
+/** How {@link explainedShares} builds its bars. */
+export interface ExplainedSharesOptions {
+    /**
+     * The cumulative share the marker aims at; `0` draws none.
+     * @default 0.95
+     */
+    target?: number;
+}
+/**
+ * The bars of the "how much each explains" tab.
+ *
+ * The running total is accumulated here rather than read from the model, so a
+ * result from any method reaches the tab the same way, and so the last value
+ * is a real 1 rather than the 1.0000000000000002 a floating-point sum returns.
+ * @param axes - The axes, in order; every one must carry a share.
+ * @param options - See {@link ExplainedSharesOptions}.
+ * @returns The bars.
+ */
+export declare function explainedShares(axes: readonly ProjectionAxis[], options?: ExplainedSharesOptions): ExplainedShares;
+//# sourceMappingURL=explainedShares.d.ts.map

package/lib/projection/core/explainedShares.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explainedShares.d.ts","sourceRoot":"","sources":["../../../src/projection/core/explainedShares.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,mDAAmD;AACnD,MAAM,WAAW,cAAc;IAC7B,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,KAAK,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,yDAAyD;AACzD,MAAM,WAAW,eAAe;IAC9B,8CAA8C;IAC9C,UAAU,EAAE,SAAS,cAAc,EAAE,CAAC;IACtC,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,mDAAmD;AACnD,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,SAAS,cAAc,EAAE,EAC/B,OAAO,GAAE,sBAA2B,GACnC,eAAe,CAyCjB"}

package/lib/projection/core/explainedShares.js

@@ -0,0 +1,55 @@
+import { chartSeriesColor } from "../../chart/core/chartPalette.js";
+/**
+ * The bars of the "how much each explains" tab.
+ *
+ * The running total is accumulated here rather than read from the model, so a
+ * result from any method reaches the tab the same way, and so the last value
+ * is a real 1 rather than the 1.0000000000000002 a floating-point sum returns.
+ * @param axes - The axes, in order; every one must carry a share.
+ * @param options - See {@link ExplainedSharesOptions}.
+ * @returns The bars.
+ */
+export function explainedShares(axes, options = {}) {
+    const { target = DEFAULT_TARGET } = options;
+    const aim = Number.isFinite(target) ? Math.min(1, Math.max(0, target)) : 0;
+    const components = [];
+    let running = 0;
+    for (let index = 0; index < axes.length; index++) {
+        const axis = axes[index];
+        if (axis === undefined)
+            continue;
+        // An axis that publishes no share stands at zero rather than stopping the
+        // tab: the tab is only offered when every axis has one, so this is the
+        // shape a caller reaches by asking for it anyway.
+        const share = Number.isFinite(axis.share)
+            ? Math.max(0, axis.share ?? 0)
+            : 0;
+        running += share;
+        components.push({
+            number: index + 1,
+            label: axis.name,
+            color: chartSeriesColor(index, 'component'),
+            share,
+            cumulative: running,
+            eigenvalue: axis.eigenvalue,
+        });
+    }
+    const last = components.at(-1);
+    if (last !== undefined && Math.abs(running - 1) < ROUNDING) {
+        last.cumulative = 1;
+    }
+    let reachesTargetAt = null;
+    if (aim > 0) {
+        for (const component of components) {
+            if (component.cumulative >= aim) {
+                reachesTargetAt = component.number;
+                break;
+            }
+        }
+    }
+    return { components, target: aim, reachesTargetAt };
+}
+const DEFAULT_TARGET = 0.95;
+/** How far off 1 a whole model's shares may land and still be a whole model. */
+const ROUNDING = 1e-9;
+//# sourceMappingURL=explainedShares.js.map

package/lib/projection/core/explainedShares.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explainedShares.js","sourceRoot":"","sources":["../../../src/projection/core/explainedShares.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AA6CpE;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAC7B,IAA+B,EAC/B,UAAkC,EAAE;IAEpC,MAAM,EAAE,MAAM,GAAG,cAAc,EAAE,GAAG,OAAO,CAAC;IAC5C,MAAM,GAAG,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAE3E,MAAM,UAAU,GAAqB,EAAE,CAAC;IACxC,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC;QACjD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;QACzB,IAAI,IAAI,KAAK,SAAS;YAAE,SAAS;QACjC,0EAA0E;QAC1E,uEAAuE;QACvE,kDAAkD;QAClD,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC;YACvC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC;YAC9B,CAAC,CAAC,CAAC,CAAC;QACN,OAAO,IAAI,KAAK,CAAC;QACjB,UAAU,CAAC,IAAI,CAAC;YACd,MAAM,EAAE,KAAK,GAAG,CAAC;YACjB,KAAK,EAAE,IAAI,CAAC,IAAI;YAChB,KAAK,EAAE,gBAAgB,CAAC,KAAK,EAAE,WAAW,CAAC;YAC3C,KAAK;YACL,UAAU,EAAE,OAAO;YACnB,UAAU,EAAE,IAAI,CAAC,UAAU;SAC5B,CAAC,CAAC;IACL,CAAC;IAED,MAAM,IAAI,GAAG,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/B,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,GAAG,CAAC,CAAC,GAAG,QAAQ,EAAE,CAAC;QAC3D,IAAI,CAAC,UAAU,GAAG,CAAC,CAAC;IACtB,CAAC;IAED,IAAI,eAAe,GAAkB,IAAI,CAAC;IAC1C,IAAI,GAAG,GAAG,CAAC,EAAE,CAAC;QACZ,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACnC,IAAI,SAAS,CAAC,UAAU,IAAI,GAAG,EAAE,CAAC;gBAChC,eAAe,GAAG,SAAS,CAAC,MAAM,CAAC;gBACnC,MAAM;YACR,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,eAAe,EAAE,CAAC;AACtD,CAAC;AAED,MAAM,cAAc,GAAG,IAAI,CAAC;AAE5B,gFAAgF;AAChF,MAAM,QAAQ,GAAG,IAAI,CAAC"}

package/lib/projection/core/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * A dimension-reduction run in the one shape the viewer reads, whatever
+ * produced it.
+ *
+ * `pcaResult` is the door for a fitted `ml-pca` model and `embeddingResult`
+ * the door for everything else — UMAP, t-SNE, a k-means table, coordinates
+ * from a file. Neither imports the library that made them: a model is
+ * described structurally, so this package depends on none of them.
+ *
+ * A result carries only what its method can honestly say. An embedding
+ * publishes no share of the variance and no weights, and it is that absence,
+ * rather than a flag anyone has to remember to set, that leaves the viewer
+ * showing the map alone instead of three empty tabs.
+ */
+export type { EmbeddingResultOptions } from './embeddingResult.ts';
+export { embeddingResult } from './embeddingResult.ts';
+export type { ComponentShare, ExplainedShares, ExplainedSharesOptions, } from './explainedShares.ts';
+export { explainedShares } from './explainedShares.ts';
+export type { LoadingProfile, LoadingProfiles, LoadingProfilesOptions, } from './loadingProfiles.ts';
+export { loadingProfiles } from './loadingProfiles.ts';
+export type { PcaLike } from './pcaLike.ts';
+export type { PcaResultOptions } from './pcaResult.ts';
+export { pcaResult } from './pcaResult.ts';
+export type { ProjectionCopy } from './projectionCopy.ts';
+export { PROJECTION_COPY, fillCopy, mergeProjectionCopy, } from './projectionCopy.ts';
+export type { ProjectionCopyPatch } from './projectionCopyPatch.ts';
+export type { ProjectionColorBy, ProjectionOptionId, ProjectionOptions, ProjectionVariablesView, } from './projectionOptions.ts';
+export { DEFAULT_PROJECTION_OPTIONS, resolveProjectionOptions, } from './projectionOptions.ts';
+export type { ProjectionAxis, ProjectionLoadings, ProjectionMarker, ProjectionResult, } from './projectionResult.ts';
+export type { ProjectionField, ProjectionSamples, ResolvedProjectionGroups, } from './projectionSamples.ts';
+export { resolveProjectionGroups } from './projectionSamples.ts';
+export type { ProjectionBarWords, ProjectionHelp, ProjectionHelpExample, } from './projectionStrings.ts';
+export { PROJECTION_HELP } from './projectionStrings.ts';
+export type { ProjectionTab } from './projectionTabs.ts';
+export { projectionTabs } from './projectionTabs.ts';
+export type { ContinuousVariableAxis, NamedVariableAxis, PeaksVariableAxis, VariableAxis, } from './variableAxis.ts';
+export { variableCount, variableDecimals, variableLabel, variablePositions, } from './variableAxis.ts';
+//# sourceMappingURL=index.d.ts.map

package/lib/projection/core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/projection/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,YAAY,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EACV,cAAc,EACd,eAAe,EACf,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EACV,cAAc,EACd,eAAe,EACf,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EACL,eAAe,EACf,QAAQ,EACR,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,YAAY,EACV,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,uBAAuB,GACxB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,0BAA0B,EAC1B,wBAAwB,GACzB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACV,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EACV,eAAe,EACf,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACjE,YAAY,EACV,kBAAkB,EAClB,cAAc,EACd,qBAAqB,GACtB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,YAAY,EACV,sBAAsB,EACtB,iBAAiB,EACjB,iBAAiB,EACjB,YAAY,GACb,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,iBAAiB,GAClB,MAAM,mBAAmB,CAAC"}

package/lib/projection/core/index.js

@@ -0,0 +1,25 @@
+/**
+ * A dimension-reduction run in the one shape the viewer reads, whatever
+ * produced it.
+ *
+ * `pcaResult` is the door for a fitted `ml-pca` model and `embeddingResult`
+ * the door for everything else — UMAP, t-SNE, a k-means table, coordinates
+ * from a file. Neither imports the library that made them: a model is
+ * described structurally, so this package depends on none of them.
+ *
+ * A result carries only what its method can honestly say. An embedding
+ * publishes no share of the variance and no weights, and it is that absence,
+ * rather than a flag anyone has to remember to set, that leaves the viewer
+ * showing the map alone instead of three empty tabs.
+ */
+export { embeddingResult } from "./embeddingResult.js";
+export { explainedShares } from "./explainedShares.js";
+export { loadingProfiles } from "./loadingProfiles.js";
+export { pcaResult } from "./pcaResult.js";
+export { PROJECTION_COPY, fillCopy, mergeProjectionCopy, } from "./projectionCopy.js";
+export { DEFAULT_PROJECTION_OPTIONS, resolveProjectionOptions, } from "./projectionOptions.js";
+export { resolveProjectionGroups } from "./projectionSamples.js";
+export { PROJECTION_HELP } from "./projectionStrings.js";
+export { projectionTabs } from "./projectionTabs.js";
+export { variableCount, variableDecimals, variableLabel, variablePositions, } from "./variableAxis.js";
+//# sourceMappingURL=index.js.map

package/lib/projection/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/projection/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAMvD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAMvD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAGvD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,OAAO,EACL,eAAe,EACf,QAAQ,EACR,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAQ7B,OAAO,EACL,0BAA0B,EAC1B,wBAAwB,GACzB,MAAM,wBAAwB,CAAC;AAYhC,OAAO,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AAMjE,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAOrD,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,iBAAiB,GAClB,MAAM,mBAAmB,CAAC"}