@vitessce/heatmap 2.0.2 → 2.0.3

package/src/Heatmap.test.fixtures.js

@@ -0,0 +1,21 @@
+export const expressionMatrix = {
+  rows: ['cell-0', 'cell-1', 'cell-2', 'cell-3', 'cell-4'],
+  cols: ['gene-0', 'gene-1', 'gene-2', 'gene-3'],
+  // "An image with an 'F' on it has a clear direction so it's easy to tell
+  // if it's turned or flipped etc when we use it as a texture."
+  // - https://webglfundamentals.org/webgl/lessons/webgl-3d-textures.html
+  matrix: Uint8Array.from([
+    0, 255, 255, 0,
+    0, 255, 0, 0,
+    0, 255, 255, 0,
+    0, 255, 0, 0,
+    0, 255, 0, 0,
+  ]),
+};
+
+export const cellColors = new Map([
+  ['cell-1', [0, 0, 255]],
+  ['cell-0', [0, 0, 255]],
+  ['cell-3', [255, 0, 0]],
+  ['cell-2', [255, 0, 0]],
+]);

package/src/Heatmap.test.jsx

@@ -0,0 +1,31 @@
+/* eslint-disable func-names */
+import '@testing-library/jest-dom';
+import { cleanup, render, screen } from '@testing-library/react'
+import { afterEach } from 'vitest'
+
+import Heatmap from './Heatmap';
+import { expressionMatrix, cellColors } from './Heatmap.test.fixtures';
+
+afterEach(() => {
+  cleanup()
+});
+
+describe('<Heatmap/>', () => {
+  it('renders a DeckGL element', function () {
+    const { container } = render(
+      <Heatmap
+        uuid="heatmap-0"
+        theme="dark"
+        width={100}
+        height={100}
+        colormap="plasma"
+        colormapRange={[0.0, 1.0]}
+        expressionMatrix={expressionMatrix}
+        cellColors={cellColors}
+        transpose
+        viewState={{ zoom: 0, target: [0, 0] }}
+      />,
+    );
+    expect(container.querySelectorAll('#deckgl-overlay-heatmap-0-wrapper').length).toEqual(1);
+  });
+});

package/src/HeatmapOptions.js

@@ -0,0 +1,71 @@
+import React, { useCallback } from 'react';
+import debounce from 'lodash/debounce';
+import Slider from '@material-ui/core/Slider';
+import TableCell from '@material-ui/core/TableCell';
+import TableRow from '@material-ui/core/TableRow';
+import { usePlotOptionsStyles, OptionsContainer, OptionSelect } from '@vitessce/vit-s';
+import { GLSL_COLORMAPS } from '@vitessce/gl';
+
+export default function HeatmapOptions(props) {
+  const {
+    geneExpressionColormap,
+    setGeneExpressionColormap,
+    geneExpressionColormapRange,
+    setGeneExpressionColormapRange,
+  } = props;
+
+  const classes = usePlotOptionsStyles();
+
+  function handleGeneExpressionColormapChange(event) {
+    setGeneExpressionColormap(event.target.value);
+  }
+
+  function handleColormapRangeChange(event, value) {
+    setGeneExpressionColormapRange(value);
+  }
+  const handleColormapRangeChangeDebounced = useCallback(
+    debounce(handleColormapRangeChange, 5, { trailing: true }),
+    [handleColormapRangeChange],
+  );
+
+  return (
+    <OptionsContainer>
+      <TableRow>
+        <TableCell className={classes.labelCell} htmlFor="gene-expression-colormap-select">
+          Gene Expression Colormap
+        </TableCell>
+        <TableCell className={classes.inputCell}>
+          <OptionSelect
+            className={classes.select}
+            value={geneExpressionColormap}
+            onChange={handleGeneExpressionColormapChange}
+            inputProps={{
+              id: 'gene-expression-colormap-select',
+            }}
+          >
+            {GLSL_COLORMAPS.map(cmap => (
+              <option key={cmap} value={cmap}>{cmap}</option>
+            ))}
+          </OptionSelect>
+        </TableCell>
+      </TableRow>
+      <TableRow>
+        <TableCell className={classes.labelCell}>
+          Gene Expression Colormap Range
+        </TableCell>
+        <TableCell className={classes.inputCell}>
+          <Slider
+            classes={{ root: classes.slider, valueLabel: classes.sliderValueLabel }}
+            value={geneExpressionColormapRange}
+            onChange={handleColormapRangeChangeDebounced}
+            aria-labelledby="gene-expression-colormap-range-slider"
+            valueLabelDisplay="auto"
+            step={0.005}
+            min={0.0}
+            max={1.0}
+          />
+        </TableCell>
+      </TableRow>
+    </OptionsContainer>
+  );
+}

package/src/HeatmapSubscriber.js

@@ -0,0 +1,253 @@
+import React, {
+  useState, useCallback, useMemo,
+} from 'react';
+import plur from 'plur';
+import {
+  TitleInfo,
+  useDeckCanvasSize,
+  useGetObsInfo,
+  useReady,
+  useUrls,
+  useObsSetsData,
+  useObsFeatureMatrixData,
+  useMultiObsLabels,
+  useFeatureLabelsData,
+  useCoordination, useLoaders,
+  useSetComponentHover, useSetComponentViewInfo,
+  registerPluginViewType,
+} from '@vitessce/vit-s';
+import { capitalize, commaNumber, getCellColors } from '@vitessce/utils';
+import { mergeObsSets } from '@vitessce/sets-utils';
+import { COMPONENT_COORDINATION_TYPES, ViewType } from '@vitessce/constants-internal';
+import Heatmap from './Heatmap';
+import HeatmapTooltipSubscriber from './HeatmapTooltipSubscriber';
+import HeatmapOptions from './HeatmapOptions';
+
+
+/**
+ * @param {object} props
+ * @param {number} props.uuid The unique identifier for this component.
+ * @param {object} props.coordinationScopes The mapping from coordination types to coordination
+ * scopes.
+ * @param {function} props.removeGridComponent The callback function to pass to TitleInfo,
+ * to call when the component has been removed from the grid.
+ * @param {string} props.title The component title.
+ * @param {boolean} props.transpose Whether to
+ * render as cell-by-gene or gene-by-cell.
+ * @param {boolean} props.disableTooltip Whether to disable the
+ * tooltip on mouse hover.
+ */
+export function HeatmapSubscriber(props) {
+  const {
+    uuid,
+    coordinationScopes,
+    removeGridComponent,
+    theme,
+    transpose,
+    observationsLabelOverride,
+    variablesLabelOverride,
+    disableTooltip = false,
+    title = 'Heatmap',
+  } = props;
+
+  const loaders = useLoaders();
+  const setComponentHover = useSetComponentHover();
+  const setComponentViewInfo = useSetComponentViewInfo(uuid);
+
+  // Get "props" from the coordination space.
+  const [{
+    dataset,
+    obsType,
+    featureType,
+    featureValueType,
+    heatmapZoomX: zoomX,
+    heatmapTargetX: targetX,
+    heatmapTargetY: targetY,
+    featureSelection: geneSelection,
+    obsHighlight: cellHighlight,
+    featureHighlight: geneHighlight,
+    obsSetSelection: cellSetSelection,
+    obsSetColor: cellSetColor,
+    additionalObsSets: additionalCellSets,
+    featureValueColormap: geneExpressionColormap,
+    featureValueColormapRange: geneExpressionColormapRange,
+  }, {
+    setHeatmapZoomX: setZoomX,
+    setHeatmapZoomY: setZoomY,
+    setHeatmapTargetX: setTargetX,
+    setHeatmapTargetY: setTargetY,
+    setObsHighlight: setCellHighlight,
+    setFeatureHighlight: setGeneHighlight,
+    setObsSetSelection: setCellSetSelection,
+    setObsSetColor: setCellSetColor,
+    setFeatureValueColormapRange: setGeneExpressionColormapRange,
+    setFeatureValueColormap: setGeneExpressionColormap,
+  }] = useCoordination(COMPONENT_COORDINATION_TYPES[ViewType.HEATMAP], coordinationScopes);
+
+  const observationsLabel = observationsLabelOverride || obsType;
+  const observationsPluralLabel = plur(observationsLabel);
+  const variablesLabel = variablesLabelOverride || featureType;
+  const variablesPluralLabel = plur(variablesLabel);
+
+  const observationsTitle = capitalize(observationsPluralLabel);
+  const variablesTitle = capitalize(variablesPluralLabel);
+
+  const [isRendering, setIsRendering] = useState(false);
+
+  const [urls, addUrl] = useUrls(loaders, dataset);
+  const [width, height, deckRef] = useDeckCanvasSize();
+
+  // Get data from loaders using the data hooks.
+  const [obsLabelsTypes, obsLabelsData] = useMultiObsLabels(
+    coordinationScopes, obsType, loaders, dataset, addUrl,
+  );
+  // TODO: support multiple feature labels using featureLabelsType coordination values.
+  const [{ featureLabelsMap }, featureLabelsStatus] = useFeatureLabelsData(
+    loaders, dataset, addUrl, false, {}, {},
+    { featureType },
+  );
+  const [{ obsIndex, featureIndex, obsFeatureMatrix }, matrixStatus] = useObsFeatureMatrixData(
+    loaders, dataset, addUrl, true, {}, {},
+    { obsType, featureType, featureValueType },
+  );
+  const [{ obsSets: cellSets, obsSetsMembership }, obsSetsStatus] = useObsSetsData(
+    loaders, dataset, addUrl, false,
+    { setObsSetSelection: setCellSetSelection, setObsSetColor: setCellSetColor },
+    { obsSetSelection: cellSetSelection, obsSetColor: cellSetColor },
+    { obsType },
+  );
+  const isReady = useReady([
+    featureLabelsStatus,
+    matrixStatus,
+    obsSetsStatus,
+  ]);
+
+  const mergedCellSets = useMemo(() => mergeObsSets(
+    cellSets, additionalCellSets,
+  ), [cellSets, additionalCellSets]);
+
+  const cellColors = useMemo(() => getCellColors({
+    // Only show cell set selection on heatmap labels.
+    cellColorEncoding: 'cellSetSelection',
+    geneSelection,
+    cellSets: mergedCellSets,
+    cellSetSelection,
+    cellSetColor,
+    obsIndex,
+    theme,
+  }), [mergedCellSets, geneSelection, theme,
+    cellSetColor, cellSetSelection, obsIndex]);
+
+  const getObsInfo = useGetObsInfo(
+    observationsLabel, obsLabelsTypes, obsLabelsData, obsSetsMembership,
+  );
+
+  const getFeatureInfo = useCallback((featureId) => {
+    if (featureId) {
+      return { [`${capitalize(variablesLabel)} ID`]: featureId };
+    }
+    return null;
+  }, [variablesLabel]);
+
+  const expressionMatrix = useMemo(() => {
+    if (obsIndex && featureIndex && obsFeatureMatrix) {
+      return {
+        rows: obsIndex,
+        cols: (featureLabelsMap
+          ? featureIndex.map(key => featureLabelsMap.get(key) || key)
+          : featureIndex
+        ),
+        matrix: obsFeatureMatrix.data,
+      };
+    }
+    return null;
+  }, [obsIndex, featureIndex, obsFeatureMatrix, featureLabelsMap]);
+
+  const cellsCount = obsIndex ? obsIndex.length : 0;
+  const genesCount = featureIndex ? featureIndex.length : 0;
+
+  const setTrackHighlight = useCallback(() => {
+    // No-op, since the default handler
+    // logs in the console on every hover event.
+  }, []);
+
+  const cellColorLabels = useMemo(() => ([
+    `${capitalize(observationsLabel)} Set`,
+  ]), [observationsLabel]);
+
+  const selectedCount = cellColors.size;
+  return (
+    <TitleInfo
+      title={title}
+      info={`${commaNumber(cellsCount)} ${plur(observationsLabel, cellsCount)} × ${commaNumber(genesCount)} ${plur(variablesLabel, genesCount)},
+             with ${commaNumber(selectedCount)} ${plur(observationsLabel, selectedCount)} selected`}
+      urls={urls}
+      theme={theme}
+      removeGridComponent={removeGridComponent}
+      isReady={isReady && !isRendering}
+      options={(
+        <HeatmapOptions
+          geneExpressionColormap={geneExpressionColormap}
+          setGeneExpressionColormap={setGeneExpressionColormap}
+          geneExpressionColormapRange={geneExpressionColormapRange}
+          setGeneExpressionColormapRange={setGeneExpressionColormapRange}
+        />
+      )}
+    >
+      <Heatmap
+        ref={deckRef}
+        transpose={transpose}
+        viewState={{ zoom: zoomX, target: [targetX, targetY] }}
+        setViewState={({ zoom, target }) => {
+          setZoomX(zoom);
+          setZoomY(zoom);
+          setTargetX(target[0]);
+          setTargetY(target[1]);
+        }}
+        colormapRange={geneExpressionColormapRange}
+        setColormapRange={setGeneExpressionColormapRange}
+        height={height}
+        width={width}
+        theme={theme}
+        uuid={uuid}
+        expressionMatrix={expressionMatrix}
+        cellColors={cellColors}
+        colormap={geneExpressionColormap}
+        setIsRendering={setIsRendering}
+        setCellHighlight={setCellHighlight}
+        setGeneHighlight={setGeneHighlight}
+        setTrackHighlight={setTrackHighlight}
+        setComponentHover={() => {
+          setComponentHover(uuid);
+        }}
+        updateViewInfo={setComponentViewInfo}
+        observationsTitle={observationsTitle}
+        variablesTitle={variablesTitle}
+        variablesDashes={false}
+        observationsDashes={false}
+        cellColorLabels={cellColorLabels}
+        useDevicePixels
+      />
+      {!disableTooltip && (
+      <HeatmapTooltipSubscriber
+        parentUuid={uuid}
+        width={width}
+        height={height}
+        transpose={transpose}
+        getObsInfo={getObsInfo}
+        getFeatureInfo={getFeatureInfo}
+        obsHighlight={cellHighlight}
+        featureHighlight={geneHighlight}
+      />
+      )}
+    </TitleInfo>
+  );
+}
+
+export function register() {
+  registerPluginViewType(
+    ViewType.HEATMAP,
+    HeatmapSubscriber,
+    COMPONENT_COORDINATION_TYPES[ViewType.HEATMAP],
+  );
+}

package/src/HeatmapTooltipSubscriber.js

@@ -0,0 +1,51 @@
+import React from 'react';
+import { Tooltip2D, TooltipContent } from '@vitessce/tooltip';
+import { useComponentHover, useComponentViewInfo } from '@vitessce/vit-s';
+
+export default function HeatmapTooltipSubscriber(props) {
+  const {
+    parentUuid,
+    width, height, transpose,
+    getObsInfo, getFeatureInfo,
+    obsHighlight, featureHighlight,
+  } = props;
+
+  const sourceUuid = useComponentHover();
+  const viewInfo = useComponentViewInfo(parentUuid);
+
+  const [cellInfo, cellCoord] = (obsHighlight && getObsInfo ? (
+    [
+      getObsInfo(obsHighlight),
+      (viewInfo && viewInfo.project
+        ? viewInfo.project(obsHighlight, null)[(transpose ? 0 : 1)]
+        : null),
+    ]
+  ) : ([null, null]));
+
+  const [geneInfo, geneCoord] = (featureHighlight && getFeatureInfo ? (
+    [
+      getFeatureInfo(featureHighlight),
+      (viewInfo && viewInfo.project
+        ? viewInfo.project(null, featureHighlight)[(transpose ? 1 : 0)]
+        : null),
+    ]
+  ) : ([null, null]));
+
+  const x = (transpose ? cellCoord : geneCoord);
+  const y = (transpose ? geneCoord : cellCoord);
+
+  return (
+    (cellInfo || geneInfo ? (
+      <Tooltip2D
+        x={x}
+        y={y}
+        parentUuid={parentUuid}
+        parentWidth={width}
+        parentHeight={height}
+        sourceUuid={sourceUuid}
+      >
+        <TooltipContent info={{ ...geneInfo, ...cellInfo }} />
+      </Tooltip2D>
+    ) : null)
+  );
+}

package/src/HeatmapWorkerPool.js

@@ -0,0 +1,52 @@
+import { HeatmapWorker } from '@vitessce/workers';
+import { Pool } from '@vitessce/utils';
+
+// Reference: https://github.com/developit/jsdom-worker/issues/14#issuecomment-1268070123
+function createWorker() {
+  return new HeatmapWorker();
+}
+
+/**
+ * Pool for workers to decode chunks of the images.
+ * This is a line-for-line copy of GeoTIFFs old implementation: https://github.com/geotiffjs/geotiff.js/blob/v1.0.0-beta.6/src/pool.js
+ */
+export default class HeatmapPool extends Pool {
+  constructor() {
+    super(createWorker);
+  }
+
+  /**
+   * Process each heatmap tile
+   * @param {object} params The arguments passed to the heatmap worker.
+   * @param {string} params.curr The current task uuid.
+   * @param {number} params.xTiles How many tiles required in the x direction?
+   * @param {number} params.yTiles How many tiles required in the y direction?
+   * @param {number} params.tileSize How many entries along each tile axis?
+   * @param {string[]} params.cellOrdering The current ordering of cells.
+   * @param {string[]} params.rows The name of each row (cell ID).
+   * Does not take transpose into account (always cells).
+   * @param {string[]} params.cols The name of each column (gene ID).
+   * Does not take transpose into account (always genes).
+   * @param {ArrayBuffer} params.data The array buffer.
+   * Need to transfer back to main thread when done.
+   * @param {boolean} params.transpose Is the heatmap transposed?
+   * @returns {array} [message, transfers]
+   * @returns {Promise.<ArrayBuffer>} the decoded result as a `Promise`
+   */
+  async process(args) {
+    const currentWorker = await this.waitForWorker();
+    return new Promise((resolve, reject) => {
+      currentWorker.onmessage = (event) => {
+        // this.workers.push(currentWorker);
+        this.finishTask(currentWorker);
+        resolve(event.data);
+      };
+      currentWorker.onerror = (error) => {
+        // this.workers.push(currentWorker);
+        this.finishTask(currentWorker);
+        reject(error);
+      };
+      currentWorker.postMessage(['getTile', args], [args.data]);
+    });
+  }
+}

package/src/heatmap-indexing.tex

@@ -0,0 +1,65 @@
+\documentclass[a4paper]{article}
+
+\usepackage[utf8]{inputenc}
+\usepackage[T1]{fontenc}
+\usepackage{textcomp}
+\usepackage[english]{babel}
+\usepackage{amsmath, amsthm, amssymb, fancyhdr, enumitem, bbm}
+
+
+% figure support
+\usepackage{import}
+\usepackage{xifthen}
+\pdfminorversion=7
+\usepackage{pdfpages}
+\usepackage{transparent}
+\newcommand{\incfig}[1]{%
+	\def\svgwidth{\columnwidth}
+	\import{./figures/}{#1.pdf_tex}
+}
+
+\pdfsuppresswarningpagegroup=1
+
+\pagestyle{fancy}
+\fancyhf{}
+\lhead{\textsc{Ilan Gold, vitessce-heatmap}}
+
+\newcommand{\Rr}{\mathbb{R}}
+\newcommand{\Qq}{\mathbb{Q}}
+\newcommand{\Zz}{\mathbb{Z}}
+\newcommand{\Cc}{\mathbb{C}}
+
+\newtheorem*{theorem*}{Theorem}
+\newtheorem*{lemma*}{Lemma}
+\newtheorem*{corollary*}{Corollary}
+\newtheorem*{definition*}{Definition}
+\newtheorem*{remark*}{Remark}
+\newtheorem*{example*}{Example}
+\newtheorem{theorem}{Theorem}
+\newtheorem{lemma}{Lemma}                                                                                                                                                         \newtheorem{corollary}{Corollary}
+\newtheorem{definition}{Definition}
+\newtheorem{remark}{Remark}
+\newtheorem{example}{Example}
+
+\begin{document}
+
+	\begin{center}
+		\Large{\textsc{Heatmap Indexing}}
+	\end{center}
+
+	We first define a \textbf{data matrix} $M \in \Rr^{n\times m}$.  We then have a \textbf{tile size} $\tau$ so that we have  $\left\lceil \frac{n}{\tau} \right\rceil = R$ row tiles and $\left\lceil \frac{m}{\tau} \right\rceil = C $ column tiles.  Because this data matrix cannot fit on the GPU it must be reshaped into a $M^{*} \in \Rr^{p \times p}$ \textbf{reshaped matrix} where $p$ is the max texture size on the computer (we assume that  $mn < p^{2}$ otherwise this doesn't work).  
+
+	The data is thus reshaped into this new matrix in row major order under the mapping $\phi: \{0, \ldots, n - 1\} \times \{0, \ldots, m-1\}  \to \{0, \ldots p-1\}^{2}$ \[
+	\phi:	(i, j) \to \left( \left\lfloor  \frac{\left( i * m \right) + j}{p}\right\rfloor, (\left( i * m \right) + j) - p \left\lfloor \frac{\left( i * m \right) + j}{p}\right\rfloor   \right) 
+	.\] 
+	Assume we have some fragment within a tile \[
+		F = \left( \left( a, b \right), \left( x, y \right)   \right) \in [0,1]^{2} \times \left( \{0, \ldots, C - 1\} \times \{0, \ldots, R-1\}  \right) = \mathcal{F}
+		\] defined by \textbf{fragment coordinates} $\left( a, b \right) \in [0,1]^{2}$, in normalized fragment space, and $\left( x,y \right) \in   \{0, \ldots, C - 1\} \times \{0, \ldots, R-1\}  $ the \textbf{tile coordinates}. Note that we are following the graphics convention, not the matrix convention - for matrices, the first coordinate represents row number (i.e going "up and down") but in graphics, the first coordinate represents the lateral coordinate, in this case for both the coordiante and the fragment coordinate.  
+
+		In summary, every fragment in the total fragment space $\mathcal{F}$ (over all tiles) is described by what tile it is in, $\left( x, y \right) $, and the coordinates within that tile in normalized fragment space $(a,b)$. We are then able to define the coordinates of the tile in terms of the original data matrix coordinates by the mapping $\psi: \mathcal{F} \to \{0, \ldots, n - 1\} \times \{0, \ldots, m-1\}  $ \[
+		\psi: (\left( a, b \right), \left( x, y \right) = T) \to \left( y * \tau + \left\lfloor b * \tau \right\rfloor, x * \tau + \left\lfloor a * \tau \right\rfloor \right)   
+	.\]  
+	This mapping takes the $[0,1]$ fragment, finds the coordinate within the tile that is correct independent of the underlying data (this is the floor term), and then offsets this coordinate by which tile of the data matrix we are in.
+
+	Thus the mapping $\phi \circ \psi: \mathcal{F} \to \{0, \ldots p-1\}^{2} $ is a mapping from a fragment within a given tile to a spot on the reshaped data matrix, and this mapping only relies on knowing $m, n, p, \tau$ and  $F$, all of which are accessible for every fragment by binding these parameters as uniforms.  By then normalizing the image of $\phi \circ \psi$ i.e dividing both coordinates by  $p$, we would get a final coordinate  in $[0, 1]^{2}$ which can be used to sample the reshaped data texture.
+\end{document}

package/src/index.js

@@ -0,0 +1,2 @@
+export { HeatmapSubscriber, register } from './HeatmapSubscriber';
+export { default as Heatmap } from './Heatmap';