@jax-data-science/sci-image-visualizer 0.8.2 → 0.9.0

package/lib/spatial-controls/spatial-charts/chart-help.d.ts

@@ -0,0 +1,69 @@
+import type { SpatialEmbeddingMeta } from '../../contracts/spatial-dataset.contract';
+import type { OmicsChartKind } from '../../implementations/plotly/omics-trace-builders';
+/**
+ * The spatial charts' kind catalogue and the prose that explains each chart: pure
+ * functions of what is charted, so none of the ~150 lines of text sit in the component and
+ * each sentence is testable on its own.
+ */
+/** A chart kind as the kind picker offers it. */
+export interface ChartKindOption {
+    label: string;
+    value: OmicsChartKind;
+}
+/** What a continuous value can be drawn as. */
+export declare const CONTINUOUS_KINDS: readonly ChartKindOption[];
+/** What a categorical column can be drawn as: a category code is a label, not a magnitude,
+ *  so a histogram of it would be meaningless — what it has is a frequency distribution. */
+export declare const CATEGORICAL_KINDS: readonly ChartKindOption[];
+/** Available whatever the map is coloured by: the heatmap's subject is a GENE LIST crossed
+ *  with a grouping, not the active colour source. */
+export declare const ALWAYS_KINDS: readonly ChartKindOption[];
+/**
+ * Offered only when the dataset publishes an embedding to draw. Labelled for what it is
+ * rather than for one instance of it: this view draws whatever embedding the dataset
+ * publishes — a UMAP, a PCA, a t-SNE — and calling the tab "UMAP" while it showed a PCA
+ * would be a lie the picker beneath it immediately contradicts.
+ */
+export declare const EMBEDDING_KINDS: readonly ChartKindOption[];
+/**
+ * The kinds the active subject can be drawn as. An embedding is a property of the DATASET,
+ * not of the colour source, so it is offered whenever one is published and never
+ * otherwise — a tab that draws nothing is worse than an absent one.
+ */
+export declare function chartKindOptions(categorical: boolean, hasEmbeddings: boolean): ChartKindOption[];
+/**
+ * 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.
+ */
+export declare function kindHelp(kind: OmicsChartKind, embedding: Pick<SpatialEmbeddingMeta, 'name' | 'label'> | null): 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.
+ */
+export declare function embeddingHelp(embedding: Pick<SpatialEmbeddingMeta, 'name' | 'label'> | null): string;
+/** What the embedding view is showing, said plainly. */
+export declare function embeddingNote(meta: Pick<SpatialEmbeddingMeta, 'name' | 'label' | 'derived' | 'params'> | null, coloured: boolean, selectionCount: number): string;
+/** What the heatmap is showing, as {@link heatmapNote} says it. */
+export interface HeatmapNoteState {
+    geneCount: number;
+    selectionCount: number;
+    zScore: boolean;
+    /** Columns the cap dropped from the last render. */
+    hidden: number;
+    groupBy: string | null;
+    /** The grouped view's column cap. */
+    maxColumns: number;
+    /** Up to this many selected cells, each is its own column. */
+    cellColumns: number;
+}
+/** What the heatmap is currently showing, said plainly. */
+export declare function heatmapNote(s: HeatmapNoteState): string;

package/lib/spatial-controls/spatial-charts/plotly-chart-host.d.ts

@@ -0,0 +1,98 @@
+/** Plotly config: a static-ish analysis chart, not an editable figure. */
+export declare const CHART_CONFIG: {
+    displaylogo: boolean;
+    responsive: boolean;
+    modeBarButtonsToRemove: string[];
+};
+/**
+ * Config for the embedding, which unlike the distributions is a plot you SELECT in.
+ *
+ * The lasso and box-select are kept — drawing round a cluster is how a population gets
+ * picked out of a UMAP — and the wheel zooms, because exploring an embedding means zooming
+ * into a cluster and reaching for a toolbar button to do it breaks that.
+ */
+export declare const EMBEDDING_CONFIG: {
+    displaylogo: boolean;
+    responsive: boolean;
+    scrollZoom: boolean;
+    modeBarButtonsToRemove: string[];
+};
+/** What a lasso or box selection in a plot reports. */
+export interface PlotSelectionHandlers {
+    /** The observation indices selected (empty for a selection that caught nothing). */
+    selected(indices: number[]): void;
+    /** The modebar's deselect, or a plain click on empty space. */
+    deselected(): void;
+}
+/** The view the user has set up on a live plot: a 3D camera, or a zoomed 2D range. */
+export interface LivePlotView {
+    camera?: unknown;
+    ranges?: {
+        x: unknown;
+        y: unknown;
+    };
+}
+/**
+ * Plotly I/O for the spatial charts, keyed by the id of the div drawn into: drawing,
+ * purging, re-fitting to the container, binding a selection, and reading back the view
+ * the user has set up. The only place the charts import Plotly.
+ *
+ * Remembers whether the last drawn layout fixed its own height, because re-fitting depends
+ * on it (see {@link refit}).
+ */
+export declare class PlotlyChartHost {
+    /**
+     * The height the drawn layout asked for, or null where it autosizes. 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;
+    /** Whether the plot on screen fixed its own height. */
+    get hasFixedHeight(): boolean;
+    /**
+     * Draw into `div`, 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.
+     */
+    draw(div: string, traces: unknown, layout: unknown, config?: unknown): Promise<void>;
+    /** Purge `div`, freeing its plot (and WebGL context); a div with no plot is fine. */
+    purge(div: string): void;
+    /**
+     * Re-fit whatever is plotted in `div` to its container.
+     *
+     * Plotly does not notice a container resize on its own — its `responsive` option listens
+     * for WINDOW resizes only. And `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 for them the width is set ALONE
+     * and the height left to stand.
+     */
+    refit(div: string): void;
+    /**
+     * Turn a lasso or box selection in `div` into observation indices.
+     *
+     * Bound after each draw, and the previous listeners removed first: `Plotly.react`
+     * preserves handlers, so re-binding without removing would fire the selection once per
+     * redraw the plot had ever had.
+     */
+    bindSelection(div: string, handlers: PlotSelectionHandlers): void;
+    /**
+     * Drop the selection handlers from a div another chart is about to use.
+     *
+     * `plotly_deselect` fires on a plain click in ANY Plotly chart, so handlers left bound
+     * for an embedding would make the first click on a bar clear the map's selection.
+     */
+    unbindSelection(div: string): void;
+    /**
+     * The view the user has set up on the live plot in `div`, 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. Null where nothing is drawn yet, or a 2D plot is not zoomed:
+     * passing an autoranged range back would freeze the axes and stop the plot re-fitting
+     * when the data changes.
+     */
+    liveView(div: string): LivePlotView | null;
+}

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

@@ -0,0 +1,26 @@
+import { EventEmitter } from '@angular/core';
+import * as i0 from "@angular/core";
+/**
+ * The detached chart window: a non-modal, draggable, resizable dialog beside the
+ * spatial-omics dialog, holding the plot div (by {@link divId}) and whatever is projected
+ * under it (the chart's hints).
+ *
+ * Presentational: the charts panel draws into the div, and decides what closing,
+ * showing and resizing the window mean.
+ */
+export declare class SpatialChartWindowComponent {
+    /** The window's header — what it is showing. */
+    title: string;
+    /** The id of the div the chart is drawn into. */
+    divId: string;
+    /** Whether the drawn layout fixed its own height (and so the window scrolls). */
+    fixedHeight: boolean;
+    /** The window was closed: put the chart back. */
+    readonly closed: EventEmitter<void>;
+    /** The window is up and its div exists: the chart can be drawn into it. */
+    readonly shown: EventEmitter<void>;
+    /** The window was resized: re-fit the chart. */
+    readonly resizeEnd: EventEmitter<void>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SpatialChartWindowComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<SpatialChartWindowComponent, "spatial-chart-window", never, { "title": { "alias": "title"; "required": false; }; "divId": { "alias": "divId"; "required": false; }; "fixedHeight": { "alias": "fixedHeight"; "required": false; }; }, { "closed": "closed"; "shown": "shown"; "resizeEnd": "resizeEnd"; }, never, ["*"], true, never>;
+}