@vitessce/heatmap 3.0.0 → 3.1.0

package/src/Heatmap.js

@@ -65,22 +65,22 @@ function shouldUsePaddedImplementation(dataLength) {
  * for DeckGL.
  * @param {number} props.width The width of the canvas.
  * @param {number} props.height The height of the canvas.
- * @param {object} props.expressionMatrix An object { rows, cols, matrix },
- * where matrix is a flat Uint8Array, rows is a list of cell ID strings,
- * and cols is a list of gene ID strings.
+ * @param {null|Uint8Array} props.uint8ObsFeatureMatrix A flat Uint8Array
+ * containing the expression data.
  * @param {Map} props.cellColors Map of cell ID to color. Optional.
  * If defined, the key ordering is used to order the cell axis of the heatmap.
  * @param {array} props.cellColorLabels array of labels to place beside cell color
  * tracks. Only works for transpose=true.
- * @param {function} props.clearPleaseWait The clear please wait callback,
- * called when the expression matrix has loaded (is not null).
  * @param {function} props.setCellHighlight Callback function called on
  * hover with the cell ID. Optional.
  * @param {function} props.setGeneHighlight Callback function called on
  * hover with the gene ID. Optional.
  * @param {function} props.updateViewInfo Callback function that gets called with an
- * object { uuid, project() } where project is a function that maps (cellId, geneId)
- * to canvas (x,y) coordinates. Used to show tooltips. Optional.
+ * object { uuid, project(), projectFromId() } where
+ * project is the DeckGL Viewport.project function, and
+ * projectFromId is a wrapper around project that
+ * takes (cellId, geneId) as parameters and returns
+ * canvas (x,y) pixel coordinates. Used to show tooltips. Optional.
  * @param {boolean} props.transpose By default, false.
  * @param {string} props.variablesTitle By default, 'Genes'.
  * @param {string} props.observationsTitle By default, 'Cells'.
@@ -91,6 +91,9 @@ function shouldUsePaddedImplementation(dataLength) {
  * @param {string} props.colormap The name of the colormap function to use.
  * @param {array} props.colormapRange A tuple [lower, upper] to adjust the color scale.
  * @param {function} props.setColormapRange The setter function for colormapRange.
+ * @param {string[]} props.obsIndex The cell ID list.
+ * @param {string[]} props.featureIndex The gene ID list.
+ * @param {null|Map<string,string>} props.featureLabelsMap A map of featureIndex to featureLabel.
  */
 const Heatmap = forwardRef((props, deckRef) => {
   const {
@@ -100,12 +103,11 @@ const Heatmap = forwardRef((props, deckRef) => {
     setViewState,
     width: viewWidth,
     height: viewHeight,
-    expressionMatrix: expression,
+    uint8ObsFeatureMatrix,
     cellColors,
     cellColorLabels = [''],
     colormap,
     colormapRange,
-    clearPleaseWait,
     setComponentHover,
     setCellHighlight = createDefaultUpdateCellsHover('Heatmap'),
     setGeneHighlight = createDefaultUpdateGenesHover('Heatmap'),
@@ -122,7 +124,9 @@ const Heatmap = forwardRef((props, deckRef) => {
     hideVariableLabels = false,
     onHeatmapClick,
     setColorEncoding,
+    obsIndex,
     featureIndex,
+    featureLabelsMap,
   } = props;
 
   const viewState = {
@@ -136,12 +140,6 @@ const Heatmap = forwardRef((props, deckRef) => {
 
   const workerPool = useMemo(() => new HeatmapWorkerPool(), []);
 
-  useEffect(() => {
-    if (clearPleaseWait && expression) {
-      clearPleaseWait('expression-matrix');
-    }
-  }, [clearPleaseWait, expression]);
-
   const tilesRef = useRef();
   const dataRef = useRef();
   const [axisLeftLabels, setAxisLeftLabels] = useState([]);
@@ -164,23 +162,23 @@ const Heatmap = forwardRef((props, deckRef) => {
   // it back and forth from the worker thread.
   useEffect(() => {
     // Store the expression matrix Uint8Array in the dataRef.
-    if (expression && expression.matrix
-      && !shouldUsePaddedImplementation(expression.matrix.length)
+    if (uint8ObsFeatureMatrix
+      && !shouldUsePaddedImplementation(uint8ObsFeatureMatrix.length)
     ) {
-      dataRef.current = copyUint8Array(expression.matrix);
+      dataRef.current = copyUint8Array(uint8ObsFeatureMatrix);
     }
-  }, [dataRef, expression]);
+  }, [dataRef, uint8ObsFeatureMatrix]);
 
   // Check if the ordering of axis labels needs to be changed,
   // for example if the cells "selected" (technically just colored)
   // have changed.
   useEffect(() => {
-    if (!expression) {
+    if (!obsIndex) {
       return;
     }
 
     const newCellOrdering = (!cellColors || cellColors.size === 0
-      ? expression.rows
+      ? obsIndex
       : Array.from(cellColors.keys())
     );
 
@@ -193,41 +191,41 @@ const Heatmap = forwardRef((props, deckRef) => {
         setAxisLeftLabels(newCellOrdering);
       }
     }
-  }, [expression, cellColors, axisTopLabels, axisLeftLabels, transpose]);
+  }, [obsIndex, cellColors, axisTopLabels, axisLeftLabels, transpose]);
 
   // Set the genes ordering.
   useEffect(() => {
-    if (!expression) {
+    if (!featureIndex) {
       return;
     }
     if (transpose) {
-      setAxisLeftLabels(expression.cols);
+      setAxisLeftLabels(featureIndex);
     } else {
-      setAxisTopLabels(expression.cols);
+      setAxisTopLabels(featureIndex);
     }
-  }, [expression, transpose]);
+  }, [featureIndex, transpose]);
 
   const [longestCellLabel, longestGeneLabel] = useMemo(() => {
-    if (!expression) {
+    if (!obsIndex || !featureIndex) {
       return ['', ''];
     }
 
     return [
-      getLongestString(expression.rows),
-      getLongestString([...expression.cols, ...cellColorLabels]),
+      getLongestString(obsIndex),
+      getLongestString([...featureIndex, ...cellColorLabels]),
     ];
-  }, [expression, cellColorLabels]);
+  }, [featureIndex, cellColorLabels, obsIndex]);
 
   // Creating a look up dictionary once is faster than calling indexOf many times
   // i.e when cell ordering changes.
   const expressionRowLookUp = useMemo(() => {
     const lookUp = new Map();
-    if (expression?.rows) {
+    if (obsIndex) {
       // eslint-disable-next-line no-return-assign
-      expression.rows.forEach((cell, j) => (lookUp.set(cell, j)));
+      obsIndex.forEach((cell, j) => (lookUp.set(cell, j)));
     }
     return lookUp;
-  }, [expression]);
+  }, [obsIndex]);
 
   const width = axisTopLabels.length;
   const height = axisLeftLabels.length;
@@ -274,7 +272,7 @@ const Heatmap = forwardRef((props, deckRef) => {
   useEffect(() => {
     updateViewInfo({
       uuid,
-      project: (cellId, geneId) => {
+      projectFromId: (cellId, geneId) => {
         const colI = transpose ? axisTopLabels.indexOf(cellId) : axisTopLabels.indexOf(geneId);
         const rowI = transpose ? axisLeftLabels.indexOf(geneId) : axisLeftLabels.indexOf(cellId);
         return heatmapToMousePosition(
@@ -324,7 +322,7 @@ const Heatmap = forwardRef((props, deckRef) => {
   // then new tiles need to be generated,
   // so add a new task to the backlog.
   useEffect(() => {
-    if (!expression || !expression.matrix || expression.matrix.length < DATA_TEXTURE_SIZE ** 2) {
+    if (!uint8ObsFeatureMatrix || uint8ObsFeatureMatrix.length < DATA_TEXTURE_SIZE ** 2) {
       return;
     }
     // Use a uuid to give the task a unique ID,
@@ -336,7 +334,7 @@ const Heatmap = forwardRef((props, deckRef) => {
     ) {
       setBacklog(prev => [...prev, uuidv4()]);
     }
-  }, [dataRef, expression, axisTopLabels, axisLeftLabels, xTiles, yTiles]);
+  }, [dataRef, uint8ObsFeatureMatrix, axisTopLabels, axisLeftLabels, xTiles, yTiles]);
 
   // When the backlog has updated, a new worker job can be submitted if:
   // - the backlog has length >= 1 (at least one job is waiting), and
@@ -349,16 +347,15 @@ const Heatmap = forwardRef((props, deckRef) => {
     if (dataRef.current
       && dataRef.current.buffer.byteLength && expressionRowLookUp.size > 0
       && !shouldUsePaddedImplementation(dataRef.current.length)) {
-      const { cols, matrix } = expression;
       const promises = range(yTiles).map(i => range(xTiles).map(async j => workerPool.process({
         curr,
         tileI: i,
         tileJ: j,
         tileSize: TILE_SIZE,
         cellOrdering: transpose ? axisTopLabels : axisLeftLabels,
-        cols,
+        cols: featureIndex,
         transpose,
-        data: matrix.buffer.slice(),
+        data: uint8ObsFeatureMatrix.buffer.slice(),
         expressionRowLookUp,
       })));
       const process = async () => {
@@ -374,8 +371,8 @@ const Heatmap = forwardRef((props, deckRef) => {
       };
       process();
     }
-  }, [axisLeftLabels, axisTopLabels, backlog, expression, transpose,
-    xTiles, yTiles, workerPool, expressionRowLookUp]);
+  }, [axisLeftLabels, axisTopLabels, backlog, uint8ObsFeatureMatrix, transpose,
+    xTiles, yTiles, workerPool, expressionRowLookUp, featureIndex]);
 
   useEffect(() => {
     setIsRendering(backlog.length > 0);
@@ -384,8 +381,8 @@ const Heatmap = forwardRef((props, deckRef) => {
   // Create the padded expression matrix for holding data which can then be bound to the GPU.
   const paddedExpressions = useMemo(() => {
     const cellOrdering = transpose ? axisTopLabels : axisLeftLabels;
-    if (expression?.matrix && cellOrdering.length
-      && gl && shouldUsePaddedImplementation(expression.matrix.length)) {
+    if (uint8ObsFeatureMatrix && cellOrdering.length
+      && gl && shouldUsePaddedImplementation(uint8ObsFeatureMatrix.length)) {
       let newIndex = 0;
       for (
         let cellOrderingIndex = 0;
@@ -397,13 +394,13 @@ const Heatmap = forwardRef((props, deckRef) => {
         const cellIndex = expressionRowLookUp.get(cell);
         for (
           let geneIndex = 0;
-          geneIndex < expression.cols.length;
+          geneIndex < featureIndex.length;
           geneIndex += 1
         ) {
-          const index = cellIndex * expression.cols.length + geneIndex;
+          const index = cellIndex * featureIndex.length + geneIndex;
           paddedExpressionContainer[
             newIndex % (DATA_TEXTURE_SIZE * DATA_TEXTURE_SIZE)
-          ] = expression.matrix[index];
+          ] = uint8ObsFeatureMatrix[index];
           newIndex = transpose ? newIndex + cellOrdering.length : newIndex + 1;
         }
       }
@@ -425,8 +422,9 @@ const Heatmap = forwardRef((props, deckRef) => {
     transpose,
     axisTopLabels,
     axisLeftLabels,
-    expression,
+    uint8ObsFeatureMatrix,
     expressionRowLookUp,
+    featureIndex,
     gl,
   ]);
 
@@ -436,8 +434,8 @@ const Heatmap = forwardRef((props, deckRef) => {
   // - the `aggSizeX` or `aggSizeY` have changed, or
   // - the cell ordering has changed.
   const heatmapLayers = useMemo(() => {
-    const usePaddedExpressions = expression?.matrix
-      && shouldUsePaddedImplementation(expression?.matrix.length);
+    const usePaddedExpressions = uint8ObsFeatureMatrix
+      && shouldUsePaddedImplementation(uint8ObsFeatureMatrix.length);
     if ((!tilesRef.current || backlog.length) && !usePaddedExpressions) {
       return [];
     }
@@ -445,7 +443,6 @@ const Heatmap = forwardRef((props, deckRef) => {
       const cellOrdering = transpose ? axisTopLabels : axisLeftLabels;
       // eslint-disable-next-line no-inner-declarations, no-shadow
       function getLayer(i, j) {
-        const { cols } = expression;
         return new PaddedExpressionHeatmapBitmapLayer({
           id: `heatmapLayer-${i}-${j}`,
           image: paddedExpressions,
@@ -460,8 +457,8 @@ const Heatmap = forwardRef((props, deckRef) => {
           numXTiles: xTiles,
           numYTiles: yTiles,
           origDataSize: transpose
-            ? [cols.length, cellOrdering.length]
-            : [cellOrdering.length, cols.length],
+            ? [featureIndex.length, cellOrdering.length]
+            : [cellOrdering.length, featureIndex.length],
           aggSizeX,
           aggSizeY,
           colormap,
@@ -503,16 +500,24 @@ const Heatmap = forwardRef((props, deckRef) => {
       (tile, index) => getLayer(Math.floor(index / xTiles), index % xTiles, tile),
     );
     return layers;
-  }, [expression, backlog.length, transpose, axisTopLabels, axisLeftLabels, yTiles, xTiles,
-    paddedExpressions, matrixLeft, tileWidth, matrixTop, tileHeight,
-    aggSizeX, aggSizeY, colormap, colormapRange, tileIteration]);
+  }, [uint8ObsFeatureMatrix, backlog.length, transpose, axisTopLabels, axisLeftLabels,
+    paddedExpressions, matrixLeft, tileWidth, matrixTop, tileHeight, yTiles, xTiles,
+    aggSizeX, aggSizeY, colormap, colormapRange, tileIteration, featureIndex]);
   const axisLeftDashes = (transpose ? variablesDashes : observationsDashes);
   const axisTopDashes = (transpose ? observationsDashes : variablesDashes);
 
   // Map cell and gene names to arrays with indices,
   // to prepare to render the names in TextLayers.
-  const axisTopLabelData = useMemo(() => axisTopLabels.map((d, i) => [i, (axisTopDashes ? `- ${d}` : d)]), [axisTopLabels, axisTopDashes]);
-  const axisLeftLabelData = useMemo(() => axisLeftLabels.map((d, i) => [i, (axisLeftDashes ? `${d} -` : d)]), [axisLeftLabels, axisLeftDashes]);
+  // We do the mapping with featureLabelsMap here at one of the final steps before rendering
+  // since it is for presentational purposes.
+  const axisTopLabelData = useMemo(() => (!transpose && featureLabelsMap
+    ? axisTopLabels.map(d => featureLabelsMap.get(d) || d)
+    : axisTopLabels
+  ).map((d, i) => [i, (axisTopDashes ? `- ${d}` : d)]), [axisTopLabels, axisTopDashes, transpose, featureLabelsMap]);
+  const axisLeftLabelData = useMemo(() => (transpose && featureLabelsMap
+    ? axisLeftLabels.map(d => featureLabelsMap.get(d) || d)
+    : axisLeftLabels
+  ).map((d, i) => [i, (axisLeftDashes ? `${d} -` : d)]), [axisLeftLabels, axisLeftDashes, transpose, featureLabelsMap]);
   const cellColorLabelsData = useMemo(() => cellColorLabels.map((d, i) => [i, d && (transpose ? `${d} -` : `- ${d}`)]), [cellColorLabels, transpose]);
 
   const hideTopLabels = (transpose ? hideObservationLabels : hideVariableLabels);
@@ -697,7 +702,7 @@ const Heatmap = forwardRef((props, deckRef) => {
 
   // Set up the onHover function.
   function onHover(info, event) {
-    if (!expression) {
+    if (!uint8ObsFeatureMatrix) {
       return;
     }
 
@@ -728,10 +733,10 @@ const Heatmap = forwardRef((props, deckRef) => {
       setTrackHighlight(null);
       setColorEncoding('geneSelection');
     } else { // we are hovering over a cell colored track
-      const obsI = expression.rows.indexOf(transpose
+      const obsI = obsIndex.indexOf(transpose
         ? axisTopLabels[trackColI]
         : axisLeftLabels[trackColI]);
-      const cellIndex = expression.rows[obsI];
+      const cellIndex = obsIndex[obsI];
       setTrackHighlight([cellIndex, trackI, mouseX, mouseY]);
       highlightedCell = cellIndex;
       setColorEncoding('cellSelection');
@@ -749,17 +754,17 @@ const Heatmap = forwardRef((props, deckRef) => {
       numCols: width,
     });
 
-    const obsI = expression.rows.indexOf(transpose
+    const obsI = obsIndex.indexOf(transpose
       ? axisTopLabels[colI]
       : axisLeftLabels[rowI]);
-    const varI = expression.cols.indexOf(transpose
+    const varI = featureIndex.indexOf(transpose
       ? axisLeftLabels[rowI]
       : axisTopLabels[colI]);
 
-    const obsId = expression.rows[obsI];
+    const obsId = obsIndex[obsI];
 
     // We need to use featureIndex here,
-    // because expression.cols may be mapped to
+    // because featureIndex may be mapped to
     // use featureLabels (if those were available in the dataset).
     // Highlights and selections are assumed to be in terms of
     // obsIndex/featureIndex (as opposed to obsLabels/featureLabels).

package/src/Heatmap.test.jsx

@@ -1,7 +1,7 @@
 /* eslint-disable func-names */
+import { describe, it, expect, afterEach } from 'vitest';
 import '@testing-library/jest-dom';
 import { cleanup, render } from '@testing-library/react';
-import { afterEach } from 'vitest';
 import React from 'react';
 
 import Heatmap from './Heatmap.js';

package/src/HeatmapSubscriber.js

@@ -101,24 +101,25 @@ export function HeatmapSubscriber(props) {
   // setObsColorEncoding with 'geneSelection' or 'cellSetSelection' upon a click.
   const [hoveredColorEncoding, setHoveredColorEncoding] = useState('geneSelection');
 
-  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,
+    coordinationScopes, obsType, loaders, dataset,
   );
   // TODO: support multiple feature labels using featureLabelsType coordination values.
-  const [{ featureLabelsMap }, featureLabelsStatus] = useFeatureLabelsData(
-    loaders, dataset, addUrl, false, {}, {},
+  const [{ featureLabelsMap }, featureLabelsStatus, featureLabelsUrls] = useFeatureLabelsData(
+    loaders, dataset, false, {}, {},
     { featureType },
   );
-  const [{ obsIndex, featureIndex, obsFeatureMatrix }, matrixStatus] = useObsFeatureMatrixData(
-    loaders, dataset, addUrl, true, {}, {},
+  const [
+    { obsIndex, featureIndex, obsFeatureMatrix }, matrixStatus, matrixUrls,
+  ] = useObsFeatureMatrixData(
+    loaders, dataset, true, {}, {},
     { obsType, featureType, featureValueType },
   );
-  const [{ obsSets: cellSets, obsSetsMembership }, obsSetsStatus] = useObsSetsData(
-    loaders, dataset, addUrl, false,
+  const [{ obsSets: cellSets, obsSetsMembership }, obsSetsStatus, obsSetsUrls] = useObsSetsData(
+    loaders, dataset, false,
     { setObsSetSelection: setCellSetSelection, setObsSetColor: setCellSetColor },
     { obsSetSelection: cellSetSelection, obsSetColor: cellSetColor },
     { obsType },
@@ -128,6 +129,11 @@ export function HeatmapSubscriber(props) {
     matrixStatus,
     obsSetsStatus,
   ]);
+  const urls = useUrls([
+    featureLabelsUrls,
+    matrixUrls,
+    obsSetsUrls,
+  ]);
 
   const [uint8ObsFeatureMatrix, obsFeatureMatrixExtent] = useUint8ObsFeatureMatrix(
     { obsFeatureMatrix },
@@ -160,20 +166,6 @@ export function HeatmapSubscriber(props) {
     return null;
   }, [variablesLabel, featureLabelsMap]);
 
-  const expressionMatrix = useMemo(() => {
-    if (obsIndex && featureIndex && uint8ObsFeatureMatrix) {
-      return {
-        rows: obsIndex,
-        cols: (featureLabelsMap
-          ? featureIndex.map(key => featureLabelsMap.get(key) || key)
-          : featureIndex
-        ),
-        matrix: uint8ObsFeatureMatrix.data,
-      };
-    }
-    return null;
-  }, [obsIndex, featureIndex, uint8ObsFeatureMatrix, featureLabelsMap]);
-
   const cellsCount = obsIndex ? obsIndex.length : 0;
   const genesCount = featureIndex ? featureIndex.length : 0;
 
@@ -239,12 +231,14 @@ export function HeatmapSubscriber(props) {
         width={width}
         theme={theme}
         uuid={uuid}
-        expressionMatrix={expressionMatrix}
+        uint8ObsFeatureMatrix={uint8ObsFeatureMatrix?.data}
         cellColors={cellColors}
         colormap={geneExpressionColormap}
         setIsRendering={setIsRendering}
         setCellHighlight={setCellHighlight}
         setGeneHighlight={setGeneHighlight}
+        featureLabelsMap={featureLabelsMap}
+        obsIndex={obsIndex}
         featureIndex={featureIndex}
         setTrackHighlight={setTrackHighlight}
         setComponentHover={() => {

package/src/HeatmapTooltipSubscriber.js

@@ -16,8 +16,8 @@ export default function HeatmapTooltipSubscriber(props) {
   const [cellInfo, cellCoord] = (obsHighlight && getObsInfo ? (
     [
       getObsInfo(obsHighlight),
-      (viewInfo && viewInfo.project
-        ? viewInfo.project(obsHighlight, null)[(transpose ? 0 : 1)]
+      (viewInfo && viewInfo.projectFromId
+        ? viewInfo.projectFromId(obsHighlight, null)[(transpose ? 0 : 1)]
         : null),
     ]
   ) : ([null, null]));
@@ -25,8 +25,8 @@ export default function HeatmapTooltipSubscriber(props) {
   const [geneInfo, geneCoord] = (featureHighlight && getFeatureInfo ? (
     [
       getFeatureInfo(featureHighlight),
-      (viewInfo && viewInfo.project
-        ? viewInfo.project(null, featureHighlight)[(transpose ? 1 : 0)]
+      (viewInfo && viewInfo.projectFromId
+        ? viewInfo.projectFromId(null, featureHighlight)[(transpose ? 1 : 0)]
         : null),
     ]
   ) : ([null, null]));

package/src/utils.test.js

@@ -1,3 +1,4 @@
+import { describe, it, expect } from 'vitest';
 import { mouseToHeatmapPosition, heatmapToMousePosition } from './utils.js';
 
 describe('heatmap tooltip utils', () => {