@czi-sds/data-viz 2.3.0 → 2.4.1

package/dist/shared/colorScales.esm.d.ts

@@ -0,0 +1,45 @@
+//#region src/common/colorScales.d.ts
+/** RGB triplet with each channel in the range 0-255. */
+type Rgb = [number, number, number];
+/** A stop on a continuous color scale, positioned at `t` in the range 0-1. */
+interface ContinuousColorStop {
+  t: number;
+  color: string;
+}
+/**
+ * A band on a stepped color scale. `threshold` is the upper bound of the band
+ * on the normalized 0-1 value range; `label` is rendered above the band in the
+ * legend.
+ */
+interface SteppedColorStop {
+  threshold: number;
+  color: string;
+  label: string;
+}
+/**
+ * How values map to colors, both in a visualization and in its legend. A
+ * continuous scale interpolates between its stops and renders as a gradient
+ * bar; a stepped scale renders as discrete bands.
+ */
+type ColorScale = {
+  kind: "continuous";
+  stops: ContinuousColorStop[];
+} | {
+  kind: "stepped";
+  stops: SteppedColorStop[];
+};
+/**
+ * Perceptually uniform sequential scale (matplotlib's plasma), the default for
+ * value overlays.
+ */
+declare const PLASMA_COLOR_SCALE: ColorScale;
+/**
+ * Colors a raw value against a scale, normalizing it into `min`-`max` first.
+ * Returns null when the value sits at or below `min`, or when the range is
+ * degenerate, so callers can fall back to a neutral color.
+ */
+declare function sampleColorScale(scale: ColorScale, value: number, max: number, min?: number): Rgb | null;
+/** CSS `linear-gradient` spanning a continuous scale, for the legend bar. */
+declare function toCssGradient(stops: ContinuousColorStop[]): string;
+//#endregion
+export { sampleColorScale as a, SteppedColorStop as i, ContinuousColorStop as n, toCssGradient as o, PLASMA_COLOR_SCALE as r, ColorScale as t };

package/dist/shared/colorScales.esm.js

@@ -0,0 +1,103 @@
+"use client";
+//#region src/common/colorScales.ts
+/**
+* Perceptually uniform sequential scale (matplotlib's plasma), the default for
+* value overlays.
+*/
+const PLASMA_COLOR_SCALE = {
+	kind: "continuous",
+	stops: [
+		{
+			color: "#0D0887",
+			t: 0
+		},
+		{
+			color: "#7E03A8",
+			t: .25
+		},
+		{
+			color: "#CC4778",
+			t: .5
+		},
+		{
+			color: "#F89441",
+			t: .75
+		},
+		{
+			color: "#F0F921",
+			t: 1
+		}
+	]
+};
+/** Parses `#RRGGBB` (or `RRGGBB`) into an RGB triplet. */
+function hexToRgb(hex) {
+	const h = hex.replace("#", "");
+	return [
+		parseInt(h.substring(0, 2), 16),
+		parseInt(h.substring(2, 4), 16),
+		parseInt(h.substring(4, 6), 16)
+	];
+}
+/** Linearly interpolates a continuous scale at `t`, clamped to 0-1. */
+function sampleContinuousScale(stops, t) {
+	if (stops.length === 0) return [
+		0,
+		0,
+		0
+	];
+	const first = stops[0];
+	const last = stops[stops.length - 1];
+	const clamped = Math.min(1, Math.max(0, t));
+	let lo = first;
+	let hi = last;
+	for (let i = 0; i < stops.length - 1; i++) {
+		const current = stops[i];
+		const next = stops[i + 1];
+		if (clamped >= current.t && clamped <= next.t) {
+			lo = current;
+			hi = next;
+			break;
+		}
+	}
+	const loRgb = hexToRgb(lo.color);
+	const hiRgb = hexToRgb(hi.color);
+	const f = hi.t === lo.t ? 0 : (clamped - lo.t) / (hi.t - lo.t);
+	return [
+		Math.round(loRgb[0] + f * (hiRgb[0] - loRgb[0])),
+		Math.round(loRgb[1] + f * (hiRgb[1] - loRgb[1])),
+		Math.round(loRgb[2] + f * (hiRgb[2] - loRgb[2]))
+	];
+}
+/**
+* Picks the band a normalized value falls into on a stepped scale.
+*
+* A value lands in the first band whose threshold it falls short of, which puts
+* each threshold at the bottom of the band above it: against thresholds of 0.5,
+* 0.7 and 0.9, a value of exactly 0.7 reads as the 0.7-0.9 band, not the one
+* below.
+*/
+function sampleSteppedScale(stops, t) {
+	for (const stop of stops) if (t < stop.threshold) return hexToRgb(stop.color);
+	const last = stops[stops.length - 1];
+	return last ? hexToRgb(last.color) : [
+		0,
+		0,
+		0
+	];
+}
+/**
+* Colors a raw value against a scale, normalizing it into `min`-`max` first.
+* Returns null when the value sits at or below `min`, or when the range is
+* degenerate, so callers can fall back to a neutral color.
+*/
+function sampleColorScale(scale, value, max, min = 0) {
+	if (max <= min || value <= min) return null;
+	const t = Math.min(1, (value - min) / (max - min));
+	return scale.kind === "continuous" ? sampleContinuousScale(scale.stops, t) : sampleSteppedScale(scale.stops, t);
+}
+/** CSS `linear-gradient` spanning a continuous scale, for the legend bar. */
+function toCssGradient(stops) {
+	return `linear-gradient(to right, ${stops.map((stop) => `${stop.color} ${stop.t * 100}%`).join(", ")})`;
+}
+//#endregion
+export { toCssGradient as i, sampleColorScale as n, sampleSteppedScale as r, PLASMA_COLOR_SCALE as t };

package/dist/shared/index.cjs.d.ts

@@ -0,0 +1,183 @@
+import { HTMLAttributes } from "react";
+import { DatasetComponentOption, ECharts, EChartsOption, ScatterSeriesOption } from "echarts";
+
+//#region src/core/HeatmapChart/hooks/utils.d.ts
+interface CreateChartOptionsProps {
+  /**
+   * The crosshair following the pointer. One object applies to both axes; a
+   * two-entry array configures them separately.
+   * https://echarts.apache.org/en/option.html#axisPointer
+   */
+  axisPointer?: EChartsOption["axisPointer"];
+  /**
+   * The cells, as a flat array of objects whose fields are named by `encode`.
+   * The data point object shape can be whatever you like, but it must be consistent with the `encode` option
+   * For example, if the data point shape is:
+   * {
+   *   geneIndex: 0,
+   *   cellTypeIndex: 0,
+   *   percentage: 0.5
+   * }
+   * and you want geneIndex to be encoded to x axis and cellTypeIndex to be encoded to y axis, then make sure your encode option is:
+   * encode: {
+   *   x: 'geneIndex',
+   *   y: 'cellTypeIndex'
+   * }
+   */
+  data: DatasetComponentOption["source"];
+  /**
+   * ECharts' dataZoom configuration for that window, merged over the defaults
+   * it sets. One object applies to both axes; a two-entry array configures them
+   * separately. It reaches the chart only while `camera.active` is true.
+   *
+   * The `dataZoom` prop is utilized for implementing zoom functionality within a
+   * specific area of the chart. This feature empowers users to inspect data in
+   * granular detail, obtain an overview of the entire dataset, or eliminate
+   * outlier points.
+   * By applying the `dataZoom` prop while locking the zoom level, the chart
+   * efficiently renders a confined portion of the heatmap. This selective
+   * rendering strategy becomes especially advantageous when dealing with
+   * extensive datasets. Instead of rendering the entire heatmap at once,
+   * the chart dynamically loads and renders specific segments as the user
+   * scrolls through the data. This approach optimizes performance and enables
+   * the creation of heatmaps with large amounts of data.
+   * https://echarts.apache.org/en/option.html#dataZoom
+   */
+  dataZoom?: EChartsOption["dataZoom"];
+  /**
+   * Renders only a window of the grid, measured in cells, and lets the pointer
+   * pan it. Sizes are ignored unless `active` is true.
+   *
+   * The `camera` prop is utilized for implementing camera view port functionality
+   * within a specific area of the chart. This feature empowers users to render
+   * a confined portion of the heatmap. This selective rendering strategy becomes
+   * especially advantageous when dealing with extensive datasets. Instead of
+   * rendering the entire heatmap at once, the chart dynamically loads and renders
+   * specific segments as the user scrolls through the data. This approach optimizes
+   * performance and enables the creation of heatmaps with large amounts of data.
+   *
+   * The `height` and `width` properties are used to specify the dimensions of the
+   * camera view port. The `active` property is used to enable or disable the camera
+   * view port functionality.
+   */
+  camera?: {
+    active: boolean;
+    height: number;
+    width: number;
+  };
+  /**
+   * How a cell is drawn while the pointer is over it. Takes the same shape as
+   * `itemStyle`: color, border, opacity.
+   * https://echarts.apache.org/en/option.html#series-scatter.emphasis
+   */
+  emphasis?: ScatterSeriesOption["emphasis"];
+  /**
+   * The categories along the x axis. A cell's encoded x value is an index into
+   * this array.
+   * For example:
+   * [{ value: "gene1", textStyle: { color: "red" } }, "gene2", "gene3"]
+   */
+  xAxisData: CategoryAxisData;
+  /**
+   * The categories along the y axis.
+   * For example:
+   * [{ value: "cellType1", textStyle: { color: "red" } }, "cellType2", "cellType3"]
+   */
+  yAxisData: CategoryAxisData;
+  /**
+   * Width of the chart in pixels. Must be greater than zero; the component
+   * throws otherwise.
+   */
+  width: number;
+  /**
+   * Height of the chart in pixels, under the same rule.
+   */
+  height: number;
+  /**
+   * Which fields of a data item place it on each axis. Omitting it leaves
+   * ECharts to guess from the field order.
+   * For example, if the data is:
+   * {
+   *   geneIndex: 0,
+   *   cellTypeIndex: 0,
+   *   percentage: 0.5
+   * }
+   * and we want to encode `geneIndex` to x axis and `cellTypeIndex` to y axis, then
+   * encode: {
+   *  x: 'geneIndex',
+   *  y: 'cellTypeIndex'
+   * }
+   * https://echarts.apache.org/en/option.html#series-scatter.encode
+   */
+  encode?: {
+    x: string;
+    y: string;
+  };
+  /**
+   * How a cell is painted. Its color accepts a callback receiving the data
+   * item, which is how a value becomes a color.
+   * https://echarts.apache.org/en/option.html#series-scatter.itemStyle
+   */
+  itemStyle?: ScatterSeriesOption["itemStyle"];
+  /**
+   * The shape of a cell. Circles turn the grid into a dot plot, where diameter
+   * can carry a second measurement.
+   */
+  symbol?: "circle" | "rect" | "roundRect";
+  /**
+   * Cell size in pixels: one number, a [width, height] pair, or a callback
+   * given the data item. Set it to the cell pitch for a solid grid.
+   *
+   * `symbolSize` can be set to single numbers like 10, or use an array to represent width and height. For example, [20, 10] means symbol width is 20, and height is 10.
+   *
+   * If size of symbols needs to be different, you can set with callback function in the following format:
+   *
+   * (value: Array|number, params: Object) => number|Array
+   *
+   * The first parameter value is the value in data, and the second parameter params is the rest parameters of data item.
+   * https://echarts.apache.org/en/option.html#series-scatter.symbolSize
+   */
+  symbolSize?: ScatterSeriesOption["symbolSize"];
+  /**
+   * Where the plotting area sits inside the container. The function form
+   * receives the computed default, for insetting it without recomputing the
+   * size.
+   * https://echarts.apache.org/en/option.html#grid
+   */
+  grid?: EChartsOption["grid"] | ((defaultOption: EChartsOption["grid"]) => EChartsOption["grid"]);
+  /**
+   * Anything else ECharts understands, merged over the generated options.
+   * https://echarts.apache.org/en/option.html
+   */
+  options?: EChartsOption;
+  /**
+   * ECharts event listeners by name. Each handler gets the raw event, whose
+   * data property is the cell, and the chart instance.
+   * https://echarts.apache.org/en/api.html#events
+   */
+  onEvents?: Record<string, (event: unknown, chart: ECharts) => void>;
+}
+type OrdinalRawValue = string | number;
+/**
+ * (thuang): This copies echarts' CategoryAxisBaseOption["data"] type, since it's not exported
+ */
+type CategoryAxisData = (OrdinalRawValue | {
+  value: OrdinalRawValue;
+  /**
+   * (thuang): This should be echarts `TextCommonOption` type, but it's not exported
+   */
+  textStyle?: never;
+})[];
+//#endregion
+//#region src/core/HeatmapChart/index.d.ts
+interface HeatmapChartProps extends HTMLAttributes<HTMLDivElement>, CreateChartOptionsProps {
+  /**
+   * Which renderer ECharts initialises with. Canvas copes better with very
+   * large grids. Changing it rebuilds the chart.
+   * @default "svg"
+   */
+  echartsRendererMode?: "svg" | "canvas";
+}
+declare const _default: import("react").MemoExoticComponent<import("react").ForwardRefExoticComponent<HeatmapChartProps & import("react").RefAttributes<HTMLDivElement>>>;
+//#endregion
+export { _default as n, HeatmapChartProps as t };

package/dist/shared/index.esm.d.ts

@@ -0,0 +1,183 @@
+import { DatasetComponentOption, ECharts, EChartsOption, ScatterSeriesOption } from "echarts";
+import { HTMLAttributes } from "react";
+
+//#region src/core/HeatmapChart/hooks/utils.d.ts
+interface CreateChartOptionsProps {
+  /**
+   * The crosshair following the pointer. One object applies to both axes; a
+   * two-entry array configures them separately.
+   * https://echarts.apache.org/en/option.html#axisPointer
+   */
+  axisPointer?: EChartsOption["axisPointer"];
+  /**
+   * The cells, as a flat array of objects whose fields are named by `encode`.
+   * The data point object shape can be whatever you like, but it must be consistent with the `encode` option
+   * For example, if the data point shape is:
+   * {
+   *   geneIndex: 0,
+   *   cellTypeIndex: 0,
+   *   percentage: 0.5
+   * }
+   * and you want geneIndex to be encoded to x axis and cellTypeIndex to be encoded to y axis, then make sure your encode option is:
+   * encode: {
+   *   x: 'geneIndex',
+   *   y: 'cellTypeIndex'
+   * }
+   */
+  data: DatasetComponentOption["source"];
+  /**
+   * ECharts' dataZoom configuration for that window, merged over the defaults
+   * it sets. One object applies to both axes; a two-entry array configures them
+   * separately. It reaches the chart only while `camera.active` is true.
+   *
+   * The `dataZoom` prop is utilized for implementing zoom functionality within a
+   * specific area of the chart. This feature empowers users to inspect data in
+   * granular detail, obtain an overview of the entire dataset, or eliminate
+   * outlier points.
+   * By applying the `dataZoom` prop while locking the zoom level, the chart
+   * efficiently renders a confined portion of the heatmap. This selective
+   * rendering strategy becomes especially advantageous when dealing with
+   * extensive datasets. Instead of rendering the entire heatmap at once,
+   * the chart dynamically loads and renders specific segments as the user
+   * scrolls through the data. This approach optimizes performance and enables
+   * the creation of heatmaps with large amounts of data.
+   * https://echarts.apache.org/en/option.html#dataZoom
+   */
+  dataZoom?: EChartsOption["dataZoom"];
+  /**
+   * Renders only a window of the grid, measured in cells, and lets the pointer
+   * pan it. Sizes are ignored unless `active` is true.
+   *
+   * The `camera` prop is utilized for implementing camera view port functionality
+   * within a specific area of the chart. This feature empowers users to render
+   * a confined portion of the heatmap. This selective rendering strategy becomes
+   * especially advantageous when dealing with extensive datasets. Instead of
+   * rendering the entire heatmap at once, the chart dynamically loads and renders
+   * specific segments as the user scrolls through the data. This approach optimizes
+   * performance and enables the creation of heatmaps with large amounts of data.
+   *
+   * The `height` and `width` properties are used to specify the dimensions of the
+   * camera view port. The `active` property is used to enable or disable the camera
+   * view port functionality.
+   */
+  camera?: {
+    active: boolean;
+    height: number;
+    width: number;
+  };
+  /**
+   * How a cell is drawn while the pointer is over it. Takes the same shape as
+   * `itemStyle`: color, border, opacity.
+   * https://echarts.apache.org/en/option.html#series-scatter.emphasis
+   */
+  emphasis?: ScatterSeriesOption["emphasis"];
+  /**
+   * The categories along the x axis. A cell's encoded x value is an index into
+   * this array.
+   * For example:
+   * [{ value: "gene1", textStyle: { color: "red" } }, "gene2", "gene3"]
+   */
+  xAxisData: CategoryAxisData;
+  /**
+   * The categories along the y axis.
+   * For example:
+   * [{ value: "cellType1", textStyle: { color: "red" } }, "cellType2", "cellType3"]
+   */
+  yAxisData: CategoryAxisData;
+  /**
+   * Width of the chart in pixels. Must be greater than zero; the component
+   * throws otherwise.
+   */
+  width: number;
+  /**
+   * Height of the chart in pixels, under the same rule.
+   */
+  height: number;
+  /**
+   * Which fields of a data item place it on each axis. Omitting it leaves
+   * ECharts to guess from the field order.
+   * For example, if the data is:
+   * {
+   *   geneIndex: 0,
+   *   cellTypeIndex: 0,
+   *   percentage: 0.5
+   * }
+   * and we want to encode `geneIndex` to x axis and `cellTypeIndex` to y axis, then
+   * encode: {
+   *  x: 'geneIndex',
+   *  y: 'cellTypeIndex'
+   * }
+   * https://echarts.apache.org/en/option.html#series-scatter.encode
+   */
+  encode?: {
+    x: string;
+    y: string;
+  };
+  /**
+   * How a cell is painted. Its color accepts a callback receiving the data
+   * item, which is how a value becomes a color.
+   * https://echarts.apache.org/en/option.html#series-scatter.itemStyle
+   */
+  itemStyle?: ScatterSeriesOption["itemStyle"];
+  /**
+   * The shape of a cell. Circles turn the grid into a dot plot, where diameter
+   * can carry a second measurement.
+   */
+  symbol?: "circle" | "rect" | "roundRect";
+  /**
+   * Cell size in pixels: one number, a [width, height] pair, or a callback
+   * given the data item. Set it to the cell pitch for a solid grid.
+   *
+   * `symbolSize` can be set to single numbers like 10, or use an array to represent width and height. For example, [20, 10] means symbol width is 20, and height is 10.
+   *
+   * If size of symbols needs to be different, you can set with callback function in the following format:
+   *
+   * (value: Array|number, params: Object) => number|Array
+   *
+   * The first parameter value is the value in data, and the second parameter params is the rest parameters of data item.
+   * https://echarts.apache.org/en/option.html#series-scatter.symbolSize
+   */
+  symbolSize?: ScatterSeriesOption["symbolSize"];
+  /**
+   * Where the plotting area sits inside the container. The function form
+   * receives the computed default, for insetting it without recomputing the
+   * size.
+   * https://echarts.apache.org/en/option.html#grid
+   */
+  grid?: EChartsOption["grid"] | ((defaultOption: EChartsOption["grid"]) => EChartsOption["grid"]);
+  /**
+   * Anything else ECharts understands, merged over the generated options.
+   * https://echarts.apache.org/en/option.html
+   */
+  options?: EChartsOption;
+  /**
+   * ECharts event listeners by name. Each handler gets the raw event, whose
+   * data property is the cell, and the chart instance.
+   * https://echarts.apache.org/en/api.html#events
+   */
+  onEvents?: Record<string, (event: unknown, chart: ECharts) => void>;
+}
+type OrdinalRawValue = string | number;
+/**
+ * (thuang): This copies echarts' CategoryAxisBaseOption["data"] type, since it's not exported
+ */
+type CategoryAxisData = (OrdinalRawValue | {
+  value: OrdinalRawValue;
+  /**
+   * (thuang): This should be echarts `TextCommonOption` type, but it's not exported
+   */
+  textStyle?: never;
+})[];
+//#endregion
+//#region src/core/HeatmapChart/index.d.ts
+interface HeatmapChartProps extends HTMLAttributes<HTMLDivElement>, CreateChartOptionsProps {
+  /**
+   * Which renderer ECharts initialises with. Canvas copes better with very
+   * large grids. Changing it rebuilds the chart.
+   * @default "svg"
+   */
+  echartsRendererMode?: "svg" | "canvas";
+}
+declare const _default: import("react").MemoExoticComponent<import("react").ForwardRefExoticComponent<HeatmapChartProps & import("react").RefAttributes<HTMLDivElement>>>;
+//#endregion
+export { _default as n, HeatmapChartProps as t };