@jax-data-science/sci-image-visualizer 0.3.3 → 0.4.0

package/lib/spatial-controls/spatial-charts/spatial-charts.component.d.ts

@@ -0,0 +1,439 @@
+import { AfterViewInit, OnDestroy, OnInit } from '@angular/core';
+import { IVisualizer, ISpatialControls } from '../../contracts/visualizer.contract';
+import { SpatialEmbeddingMeta } from '../../contracts/spatial-dataset.contract';
+import { SpatialColorBy } from '../../contracts/display-types';
+import { OmicsChartKind } from '../../implementations/plotly/omics-trace-builders';
+import * as i0 from "@angular/core";
+/**
+ * Distribution charts over the spatial-omics values — histogram, violin, box —
+ * **linked to the map**: they chart whatever the map is coloured by, and narrow
+ * to the current selection.
+ *
+ * Embedded INSIDE `<spatial-controls>` rather than owning a dialog of its own:
+ * the two are one workflow (change the colour source, watch the distribution
+ * move), and splitting them across two floating windows made the link harder to
+ * see, not easier. It stays a separate component so the pure trace builders and
+ * its own tests keep their boundary.
+ *
+ * Charting the active colour source rather than offering its own value picker is
+ * deliberate: it keeps one source of truth, so what you see on the map and what
+ * you see in the chart cannot disagree, and it makes the link legible without
+ * explaining it.
+ *
+ * Depends only on {@link ISpatialControls} through the `VISUALIZER` contract
+ * token, like `SpatialControlsComponent`. Trace building lives in the pure
+ * `omics-trace-builders`; this component only moves data and owns the div.
+ */
+export declare class SpatialChartsComponent implements OnInit, AfterViewInit, OnDestroy {
+    private readonly viz;
+    /**
+     * Whether the host panel is on screen. The chart only draws when it is: the
+     * enclosing dialog creates and destroys its content, so without this the
+     * component would mount with a div present but no state change to trigger a
+     * first draw.
+     */
+    set active(on: boolean);
+    get active(): boolean;
+    private isActive;
+    /** Per-instance, for the same reason the visualizer's plot div is
+     *  (`visualizer.component.ts`): two mounted charts sharing one DOM id means
+     *  `getElementById` hands both of them the first element, so one instance draws
+     *  into — or purges — the other's canvas. */
+    /** One increment per INSTANCE — a static initializer would run once per class and
+     *  hand every instance the same id, which is the bug this id exists to avoid. Declared
+     *  before the ids because field initializers run in order. */
+    private readonly seq;
+    readonly chartDiv: string;
+    /**
+     * The div inside the detached window.
+     *
+     * A separate id rather than moving the existing div: Angular destroys and recreates a
+     * div across an `*ngIf`, so Plotly would be left holding a detached node. Two divs and
+     * a redraw is both simpler and correct.
+     *
+     * ONE is enough for every kind, because only the active kind is ever plotted. Detaching
+     * is remembered per kind, but at most one window is open at a time.
+     */
+    readonly detachedDiv: string;
+    /**
+     * Whether the chart is shown in its own window rather than inline.
+     *
+     * Detached, it sits ALONGSIDE the spatial-omics dialog instead of inside it — which is
+     * the point: these are read against the map, not instead of it. The dialog is only so
+     * wide.
+     *
+     * One flag for the PANEL, not one per kind. Where the window is, is a property of the
+     * workspace someone has arranged, not of the tab they happen to be on: having put the
+     * charts beside the map, switching from the heatmap to the counts should swap what the
+     * window shows, not yank it back into the dialog and make them detach it again.
+     */
+    detached: boolean;
+    private static readonly CONTINUOUS_KINDS;
+    private static readonly CATEGORICAL_KINDS;
+    /** Available whatever the map is coloured by: the heatmap's subject is a GENE
+     *  LIST crossed with a grouping, not the active colour source. */
+    private static readonly ALWAYS_KINDS;
+    /**
+     * A t-SNE the dataset does not publish, offered so it can be computed here.
+     *
+     * A dropped-in `.h5ad` typically carries one UMAP and a PCA, and no t-SNE — the two
+     * views answer different questions, so having only one is a real gap. Computing it
+     * needs no expression data: t-SNE runs on the PCA scores, which is why this can happen
+     * in the browser at all while PCA cannot.
+     */
+    private static readonly COMPUTABLE;
+    /** The menu suffix that says a click will start work; not part of the name. */
+    private static readonly COMPUTE_SUFFIX;
+    /**
+     * Largest dataset this will offer to embed in the browser.
+     *
+     * t-SNE is O(N²) per iteration — vectorised on the GPU, but not approximated — so the
+     * cost is quadratic in observations. Measured end to end in Firefox on WebGPU: 2,688
+     * points took 95 s. That scales to roughly five and a half minutes at this threshold,
+     * and to about 76 minutes at seqFISH's 19,416, which was also measured offline.
+     *
+     * Past this the option is WITHDRAWN rather than offered with a warning. An hour-long
+     * job started from a button is not a choice a reader can meaningfully consent to in a
+     * dialog, and a t-SNE that large belongs in the offline pipeline, where it can run
+     * once and be served to everyone.
+     */
+    static readonly BROWSER_TSNE_MAX_OBSERVATIONS = 5000;
+    /** Measured anchor for the estimate: seconds for 2,688 points on WebGPU. */
+    private static readonly TSNE_SECONDS_AT;
+    /** Coordinates computed in this browser, by name. Not persisted: a reload recomputes. */
+    private readonly computed;
+    /** The live run, when one is going. */
+    private computeRun;
+    /**
+     * Bumped by every dataset change and by teardown, so a computation in progress can tell
+     * that what it is computing is no longer what is on screen.
+     *
+     * A run is several awaits long — the PCA scores arrive over HTTP, then the worker takes
+     * a minute or more — and the dataset can change at any of them, including BEFORE
+     * `computeRun` exists to be terminated. Without a token, the scores fetched for one
+     * dataset get embedded and drawn over another's observations: a plot of two datasets at
+     * once, which reads as a strange-looking t-SNE rather than as a bug.
+     */
+    private computeToken;
+    /** 0..1 while running, or null before the first report. Drives the progress bar. */
+    computeFraction: number | null;
+    /** Which backend the worker got — 'webgpu', 'wasm' or 'cpu'. Shown while running. */
+    computeBackend: string | null;
+    computeMessage: string | null;
+    computeError: string | null;
+    /** True when a t-SNE is missing but the dataset is too big to embed here. */
+    tsneTooLarge: boolean;
+    /** Observations in the live dataset, kept for the cost estimate. */
+    private observationCount;
+    /** Offered only when the dataset publishes an embedding to draw. */
+    private static readonly EMBEDDING_KINDS;
+    /** The kinds the ACTIVE subject can be drawn as. A category code is a label,
+     *  not a magnitude, so a histogram of it would be meaningless — what a
+     *  categorical column has is a frequency distribution. */
+    get kindOptions(): {
+        label: string;
+        value: OmicsChartKind;
+    }[];
+    controls: ISpatialControls | null;
+    kind: OmicsChartKind;
+    /** Embeddings the dataset publishes, and which of them is drawn. */
+    embeddings: SpatialEmbeddingMeta[];
+    embedding: SpatialEmbeddingMeta | null;
+    private embeddingCoords;
+    /** The categorical colouring behind the embedding's colours, kept so a redraw for a
+     *  selection change does not refetch the column. */
+    private embeddingCodes;
+    /**
+     * Genes the heatmap's rows are, and the vectors behind them.
+     *
+     * Local rather than in `SpatialViewState`, matching how the chart KIND is
+     * held: this is what the panel is charting, not what the map is drawing, and
+     * the renderer has no use for it.
+     */
+    heatmapGenes: string[];
+    /** Z-score each gene across the groups. On by default: without it one loud
+     *  gene saturates the scale and the rest of the panel reads as blank. */
+    heatmapZScore: boolean;
+    /** Past this many selected cells the per-cell view is a texture, not a
+     *  readable panel, so the columns go back to being classes. */
+    private static readonly HEATMAP_CELL_COLUMNS;
+    /**
+     * Column cap for the grouped heatmap.
+     *
+     * Any categorical column can be the x axis, and they are not the same size:
+     * `neurotransmitter` has 9 categories, `class` 34, `subclass` 338. At 338 the
+     * panel is a texture — columns a couple of pixels wide, no readable label —
+     * so past this many the strongest columns are kept and the note says how many
+     * were dropped. See `maxCols` in `spatial-heatmap.ts`.
+     */
+    private static readonly HEATMAP_MAX_COLUMNS;
+    /** Columns the cap dropped from the last render, for the note. */
+    private heatmapHidden;
+    geneOptions: {
+        label: string;
+        value: string;
+    }[];
+    /** Every gene the dataset inlined. `geneOptions` is only ever the best few hundred of
+     *  these — see `gene-search.ts` for why a whole-transcriptome list cannot be handed to
+     *  the control whole. */
+    private geneNames;
+    /** What is typed in the picker's filter box, so the options can be rebuilt when the
+     *  selection changes without losing the query. */
+    private geneQuery;
+    /** Fetched vectors by gene name, so adding a fourth gene does not refetch the
+     *  first three — each is a full per-observation Float32Array. */
+    private readonly geneCache;
+    /** Categorical column the violin/box splits by; null = one trace for all. */
+    groupBy: string | null;
+    groupOptions: {
+        label: string;
+        value: string | null;
+    }[];
+    /** What the map is coloured by — the chart's subject. */
+    colorBy: SpatialColorBy | null;
+    selectionCount: number;
+    /** Set when the active colour source cannot be charted, for an inline hint. */
+    notice: string | null;
+    busy: boolean;
+    private view;
+    private selection;
+    private values;
+    /** Set instead of `values` when the colour source is a categorical column: its
+     *  distribution is counts per category, not a histogram of its codes. */
+    private categorical;
+    private grouping;
+    /** Guards the async value fetch: a fast colour-source change can resolve out
+     *  of order, and a stale vector would be charted against the new label. */
+    private token;
+    /** The same guard for the grouping fetch, which the user can change as fast. */
+    private groupToken;
+    /** Whether the first view emission has been handled. */
+    private primed;
+    private readonly subs;
+    constructor(viz: IVisualizer);
+    ngOnInit(): void;
+    /**
+     * The height the drawn layout asked for, or null where it autosizes.
+     *
+     * {@link resize} needs this: the counts and heatmap layouts size their height
+     * to their content — one band per bar, per gene row — while the distribution
+     * kinds want to fill whatever height they are given.
+     */
+    private drawnHeight;
+    /**
+     * Re-fit the plot to the panel's current width.
+     *
+     * Called by the host when the dialog finishes resizing. Plotly does not notice
+     * a container resize on its own — its `responsive` option listens for WINDOW
+     * resizes only, so dragging a dialog edge reaches it through nothing at all.
+     */
+    resize(): void;
+    /**
+     * Re-fit whatever is plotted in `div` to its container.
+     *
+     * Shared by the panel and the detached window because the rule is the same and getting
+     * it wrong is invisible until it is not: `autosize` takes BOTH dimensions from the
+     * container, which is right only where the layout did not fix its own height. Measured:
+     * autosizing a layout with an explicit height of 500 replaced it with the container's
+     * 400. The counts and heatmap layouts size themselves to their row count, so the
+     * window resize has to set the width ALONE for them and let the height stand.
+     */
+    private refit;
+    ngOnDestroy(): void;
+    ngAfterViewInit(): void;
+    onKind(kind: OmicsChartKind): void;
+    /**
+     * The grouping the heatmap's columns come from, defaulting rather than
+     * demanding one: a heatmap with no columns is not a chart, and "No grouping"
+     * is a sensible answer for a violin but not for this.
+     */
+    private ensureHeatmapGrouping;
+    onHeatmapZScore(on: boolean): void;
+    /** What the heatmap is currently showing, said plainly. */
+    get heatmapNote(): string;
+    /** Gene rows for the heatmap. */
+    onHeatmapGenes(names: string[]): Promise<void>;
+    /**
+     * Fetch any gene the heatmap needs and does not already hold.
+     *
+     * Sequenced on the same token the colour-source load uses: each vector is a
+     * separate request, and a slower one must not paint rows for a gene list the
+     * user has already moved on from.
+     */
+    private loadHeatmapGenes;
+    onGroupBy(name: string | null): Promise<void>;
+    /** True when the current kind would read better with a grouping chosen. */
+    get suggestsGrouping(): boolean;
+    get subject(): string;
+    /** Fetch the active colour source's vector, then draw. */
+    private reload;
+    /**
+     * The embedding scatter — a UMAP over the same observations.
+     *
+     * Answers what the map cannot: the map says WHERE a population sits, this says which
+     * populations there are and how close they are in expression.
+     *
+     * Linked to the map without asking for anything: it reuses `this.categorical`, the same
+     * loaded colouring the counts chart draws from, so the two cannot disagree about what a
+     * colour means and no second fetch happens. A selection dims the rest rather than
+     * dropping it — the embedding's shape is the context that makes a selection legible.
+     */
+    private renderEmbedding;
+    /**
+     * Turn a lasso in the embedding into a selection of observations.
+     *
+     * This is what makes two views of one dataset worth having side by side: draw round a
+     * cluster here and those cells light up on the tissue, because every view reads the
+     * same mask.
+     *
+     * Bound after each draw, and the previous listener removed first: `Plotly.react`
+     * preserves handlers, so re-binding without removing would fire the selection once per
+     * redraw the plot had ever had.
+     */
+    private bindEmbeddingSelection;
+    /**
+     * Drop the embedding's selection handlers from a div another kind is about to use.
+     *
+     * The detached window outlives any one kind — switching tabs swaps its content and
+     * keeps the div — so without this the lasso handlers bound for a UMAP stay live under
+     * the counts plot that replaces it. `plotly_deselect` fires on a plain click in ANY
+     * Plotly chart, so the first click on a bar would silently clear the map's selection.
+     */
+    private unbindEmbeddingSelection;
+    /**
+     * The view the user has set up on the live plot, to carry across a redraw.
+     *
+     * `Plotly.react` resets a 3D scene camera and any zoomed 2D range unless the layout
+     * carries them, so selecting a category or recolouring would throw away an orientation
+     * that took work to find. Rotating a cloud to see a structure and losing it on the next
+     * click makes the plot useless for what it is for.
+     */
+    private liveView;
+    /**
+     * Whether the plot on screen fixed its own height.
+     *
+     * The counts and heatmap layouts size themselves to their row count, so in the detached
+     * window they can be TALLER than the window — which has to scroll rather than clip. An
+     * embedding fixes no height and fills the window instead. The template needs to know
+     * which, because the two want opposite `flex` and `overflow`.
+     */
+    get hasFixedHeight(): boolean;
+    /** Where the active kind draws: its own window, or the shared chart div. */
+    get plotTarget(): string;
+    /**
+     * Header for the detached window — what it is showing, named as its tab is.
+     *
+     * The embedding names the embedding rather than the tab, because "Embedding" beside a
+     * window drawing a t-SNE says less than "t-SNE" does.
+     */
+    get detachedTitle(): string;
+    /**
+     * Move the active kind between its own window and the panel.
+     *
+     * Purges the div it is LEAVING first. Plotly keeps per-div state, and a graph left
+     * behind in a div that Angular then removes leaks its WebGL context — and if the div
+     * comes back, react would resize a plot whose data belongs to the other place.
+     */
+    toggleDetached(): void;
+    /** The detached window is up and its div exists — now the plot can be drawn into it. */
+    onDetachedWindowShown(): void;
+    /** Re-fit the detached window's plot after it is resized. */
+    onDetachedResizeEnd(): void;
+    /**
+     * Rebuild the visible options: the best matches for what is typed, plus what is chosen.
+     *
+     * A capped multi-select that drops its own selections cannot resolve their labels, and
+     * the model loses them on the next change — the chips vanish for no reason the user
+     * can see.
+     */
+    private refreshGeneOptions;
+    /** The gene picker's filter box changed: search the resident names, show the best. */
+    onGeneFilter(query: string): void;
+    /**
+     * Roughly how long a run will take, in seconds, from the measured anchor.
+     *
+     * Shown before the click. A progress bar tells you a job is going; only an estimate
+     * tells you whether to start it.
+     */
+    get computeEstimateSeconds(): number;
+    /** That estimate as something to put on a button. */
+    get computeEstimateLabel(): string;
+    /** Why the option is absent, when a dataset is past the threshold. */
+    get tsneTooLargeNote(): string;
+    /** Whether the selected embedding is one this browser would have to compute. */
+    get isComputable(): boolean;
+    /** Whether it has already been computed in this session. */
+    get isComputed(): boolean;
+    get isComputing(): boolean;
+    /**
+     * Compute the selected embedding here, in a worker.
+     *
+     * The PCA scores come from the port as an ordinary embedding — the server derives them,
+     * because PCA needs the whole expression matrix (185 MB for a Visium dataset) while
+     * t-SNE needs only the scores (0.51 MB). Sending the matrix to the browser to save a
+     * few seconds of arithmetic would be a far slower answer.
+     */
+    computeEmbedding(): Promise<void>;
+    /** Stop a run. It settles shortly after, leaving no embedding. */
+    cancelCompute(): void;
+    /**
+     * Drop any computation in progress, because what it is computing no longer applies.
+     *
+     * Distinct from {@link cancelCompute}, which is the user's Cancel and asks the worker to
+     * stop politely. This one does not wait: the run is settled and the worker killed, so a
+     * dataset switch or a teardown cannot leave a t-SNE grinding on in the background over
+     * observations nothing is showing any more.
+     */
+    private abandonCompute;
+    /**
+     * The dataset's PCA, as row-major scores.
+     *
+     * Assembled from whichever PCA the source offers, widest first — a 3-D one gives t-SNE
+     * three components instead of two for the same request.
+     */
+    private loadPcaScores;
+    /** Which embedding to draw, when the dataset publishes more than one. */
+    onEmbedding(name: string): void;
+    /**
+     * What the chart on screen actually shows, and what it cannot be read for.
+     *
+     * Shown on hover from a `?` beside the tabs. Each of these plots answers a different
+     * question and two of them are routinely over-read — a UMAP's distances and a heatmap's
+     * unscaled colours — so the caveat is part of the explanation rather than a footnote.
+     *
+     * HTML, because the tooltip renders with `[escape]="false"`: a paragraph and a caveat
+     * read as two thoughts, and a single run-on line is skipped rather than read.
+     */
+    get kindHelp(): string;
+    /**
+     * What the embedding on screen is, and how far its geometry can be trusted.
+     *
+     * Per METHOD, because that is the part people get wrong: a PCA's axes are ordered and
+     * measurable while a UMAP's are neither, and the same picture read the two ways supports
+     * opposite conclusions.
+     */
+    private get embeddingHelp();
+    /** What the embedding view is showing, said plainly. */
+    get embeddingNote(): string;
+    private purgePlot;
+    /**
+     * Draw, remembering whether this layout fixed its own height.
+     *
+     * The layout builders return `unknown` on purpose — they keep Plotly's layout
+     * types out of the pure module — so the height is read back by narrowing
+     * rather than declared. `height` is Plotly's own key, not ours.
+     */
+    private draw;
+    private render;
+    /**
+     * Genes × groups mean expression.
+     *
+     * Columns are the grouping column's categories — or, inside a SMALL
+     * selection, the selected cells themselves. A two-column class matrix is a
+     * poor answer for an ROI holding forty cells; "what is in front of me" is the
+     * question there, and each cell earns a column.
+     */
+    private renderHeatmap;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SpatialChartsComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<SpatialChartsComponent, "spatial-charts", never, { "active": { "alias": "active"; "required": false; }; }, {}, never, never, false, never>;
+}