@vitessce/scatterplot 2.0.3-beta.0 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vitessce/scatterplot",
-  "version": "2.0.3-beta.0",
+  "version": "3.0.0",
   "author": "Gehlenborg Lab",
   "homepage": "http://vitessce.io",
   "repository": {
@@ -8,34 +8,46 @@
     "url": "git+https://github.com/vitessce/vitessce.git"
   },
   "license": "MIT",
+  "type": "module",
   "main": "dist/index.js",
   "files": [
-    "dist"
+    "src",
+    "dist",
+    "dist-tsc"
   ],
   "dependencies": {
     "@material-ui/core": "~4.12.3",
+    "@material-ui/icons": "~4.11.2",
     "clsx": "^1.1.1",
     "d3-force": "^2.1.1",
     "d3-quadtree": "^1.0.7",
-    "lodash": "^4.17.21",
-    "@vitessce/constants-internal": "2.0.3-beta.0",
-    "@vitessce/icons": "2.0.3-beta.0",
-    "@vitessce/gl": "2.0.3-beta.0",
-    "@vitessce/utils": "2.0.3-beta.0",
-    "@vitessce/tooltip": "2.0.3-beta.0",
-    "@vitessce/vit-s": "2.0.3-beta.0"
+    "lodash-es": "^4.17.21",
+    "@vitessce/constants-internal": "3.0.0",
+    "@vitessce/gl": "3.0.0",
+    "@vitessce/icons": "3.0.0",
+    "@vitessce/tooltip": "3.0.0",
+    "@vitessce/utils": "3.0.0",
+    "@vitessce/vit-s": "3.0.0"
   },
   "devDependencies": {
     "react": "^18.0.0",
-    "vite": "^3.0.0",
-    "vitest": "^0.23.4"
+    "vite": "^4.3.0",
+    "vitest": "^0.23.4",
+    "@testing-library/jest-dom": "^5.16.4",
+    "@testing-library/react": "^13.3.0"
   },
   "peerDependencies": {
     "react": "^16.8.0 || ^17.0.0 || ^18.0.0"
   },
   "scripts": {
-    "start": "tsc --watch",
-    "build": "tsc",
+    "bundle": "pnpm exec vite build -c ../../../scripts/vite.config.js",
     "test": "pnpm exec vitest --run -r ../../../ --dir ."
+  },
+  "module": "dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist-tsc/index.d.ts",
+      "import": "./dist/index.js"
+    }
   }
 }

package/src/EmptyMessage.js

@@ -0,0 +1,11 @@
+import React from 'react';
+
+export default function EmptyMessage(props) {
+  const {
+    visible,
+    message,
+  } = props;
+  return visible ? (
+    <div>{message}</div>
+  ) : null;
+}

package/src/Scatterplot.js

@@ -0,0 +1,396 @@
+/* eslint-disable no-param-reassign */
+import React, { forwardRef } from 'react';
+import { forceSimulation } from 'd3-force';
+import {
+  deck, getSelectionLayers, ScaledExpressionExtension, SelectionExtension,
+} from '@vitessce/gl';
+import { getDefaultColor } from '@vitessce/utils';
+import {
+  AbstractSpatialOrScatterplot, createQuadTree, forceCollideRects, getOnHoverCallback,
+} from './shared-spatial-scatterplot/index.js';
+
+const CELLS_LAYER_ID = 'scatterplot';
+const LABEL_FONT_FAMILY = "-apple-system, 'Helvetica Neue', Arial, sans-serif";
+const NUM_FORCE_SIMULATION_TICKS = 100;
+const LABEL_UPDATE_ZOOM_DELTA = 0.25;
+
+// Default getter function props.
+const makeDefaultGetCellColors = (cellColors, obsIndex, theme) => (object, { index }) => {
+  const [r, g, b, a] = (cellColors && obsIndex && cellColors.get(obsIndex[index]))
+    || getDefaultColor(theme);
+  return [r, g, b, 255 * (a || 1)];
+};
+const makeDefaultGetObsCoords = obsEmbedding => i => ([
+  obsEmbedding.data[0][i],
+  obsEmbedding.data[1][i],
+  0,
+]);
+const makeFlippedGetObsCoords = obsEmbedding => i => ([
+  obsEmbedding.data[0][i],
+  -obsEmbedding.data[1][i],
+  0,
+]);
+const getPosition = (object, { index, data, target }) => {
+  target[0] = data.src.obsEmbedding.data[0][index];
+  target[1] = -data.src.obsEmbedding.data[1][index];
+  target[2] = 0;
+  return target;
+};
+
+/**
+ * React component which renders a scatterplot from cell data.
+ * @param {object} props
+ * @param {string} props.uuid A unique identifier for this component.
+ * @param {string} props.theme The current vitessce theme.
+ * @param {object} props.viewState The deck.gl view state.
+ * @param {function} props.setViewState Function to call to update the deck.gl view state.
+ * @param {object} props.cells
+ * @param {string} props.mapping The name of the coordinate mapping field,
+ * for each cell, for example "PCA" or "t-SNE".
+ * @param {Map} props.cellColors Mapping of cell IDs to colors.
+ * @param {array} props.cellSelection Array of selected cell IDs.
+ * @param {array} props.cellFilter Array of filtered cell IDs. By default, null.
+ * @param {number} props.cellRadius The value for `radiusScale` to pass
+ * to the deck.gl cells ScatterplotLayer.
+ * @param {number} props.cellOpacity The value for `opacity` to pass
+ * to the deck.gl cells ScatterplotLayer.
+ * @param {function} props.getCellCoords Getter function for cell coordinates
+ * (used by the selection layer).
+ * @param {function} props.getCellPosition Getter function for cell [x, y, z] position.
+ * @param {function} props.getCellColor Getter function for cell color as [r, g, b] array.
+ * @param {function} props.getExpressionValue Getter function for cell expression value.
+ * @param {function} props.getCellIsSelected Getter function for cell layer isSelected.
+ * @param {function} props.setCellSelection
+ * @param {function} props.setCellHighlight
+ * @param {function} props.updateViewInfo
+ * @param {function} props.onToolChange Callback for tool changes
+ * (lasso/pan selection tools).
+ * @param {function} props.onCellClick Getter function for cell layer onClick.
+ * @param {object} props.originalViewState A viewState object to pass to
+ * setViewState upon clicking the recenter button.
+ */
+class Scatterplot extends AbstractSpatialOrScatterplot {
+  constructor(props) {
+    super(props);
+
+    // To avoid storing large arrays/objects
+    // in React state, this component
+    // uses instance variables.
+    // All instance variables used in this class:
+    this.cellsQuadTree = null;
+    this.cellsLayer = null;
+    this.cellsData = null;
+    this.cellSetsForceSimulation = forceCollideRects();
+    this.cellSetsLabelPrevZoom = null;
+    this.cellSetsLayers = [];
+
+    // Initialize data and layers.
+    this.onUpdateCellsData();
+    this.onUpdateCellsLayer();
+    this.onUpdateCellSetsLayers();
+  }
+
+  createCellsLayer() {
+    const {
+      obsEmbeddingIndex: obsIndex,
+      theme,
+      cellRadius = 1.0,
+      cellOpacity = 1.0,
+      // cellFilter,
+      cellSelection,
+      setCellHighlight,
+      setComponentHover,
+      getCellIsSelected,
+      cellColors,
+      getCellColor = makeDefaultGetCellColors(cellColors, obsIndex, theme),
+      getExpressionValue,
+      onCellClick,
+      geneExpressionColormap,
+      geneExpressionColormapRange = [0.0, 1.0],
+      cellColorEncoding,
+    } = this.props;
+    return new deck.ScatterplotLayer({
+      id: CELLS_LAYER_ID,
+      // Note that the reference for the object passed to the data prop should not change,
+      // otherwise DeckGL will need to do a full re-render every time .createCellsLayer is called,
+      // which can be very often to handle cellOpacity and cellRadius updates for dynamic opacity.
+      data: this.cellsData,
+      coordinateSystem: deck.COORDINATE_SYSTEM.CARTESIAN,
+      visible: true,
+      pickable: true,
+      autoHighlight: true,
+      filled: true,
+      stroked: true,
+      backgroundColor: (theme === 'dark' ? [0, 0, 0] : [241, 241, 241]),
+      getCellIsSelected,
+      opacity: cellOpacity,
+      radiusScale: cellRadius,
+      radiusMinPixels: 1,
+      radiusMaxPixels: 30,
+      // Our radius pixel setters measure in pixels.
+      radiusUnits: 'pixels',
+      lineWidthUnits: 'pixels',
+      getPosition,
+      getFillColor: getCellColor,
+      getLineColor: getCellColor,
+      getRadius: 1,
+      getExpressionValue,
+      getLineWidth: 0,
+      extensions: [
+        new ScaledExpressionExtension(),
+        new SelectionExtension({ instanced: true }),
+      ],
+      colorScaleLo: geneExpressionColormapRange[0],
+      colorScaleHi: geneExpressionColormapRange[1],
+      isExpressionMode: (cellColorEncoding === 'geneSelection'),
+      colormap: geneExpressionColormap,
+      onClick: (info) => {
+        if (onCellClick) {
+          onCellClick(info);
+        }
+      },
+      onHover: getOnHoverCallback(obsIndex, setCellHighlight, setComponentHover),
+      updateTriggers: {
+        getExpressionValue,
+        getFillColor: [cellColorEncoding, cellSelection, cellColors],
+        getLineColor: [cellColorEncoding, cellSelection, cellColors],
+        getCellIsSelected,
+      },
+    });
+  }
+
+  createCellSetsLayers() {
+    const {
+      theme,
+      cellSetPolygons,
+      viewState,
+      cellSetPolygonsVisible,
+      cellSetLabelsVisible,
+      cellSetLabelSize,
+    } = this.props;
+
+    const result = [];
+
+    if (cellSetPolygonsVisible) {
+      result.push(new deck.PolygonLayer({
+        id: 'cell-sets-polygon-layer',
+        data: cellSetPolygons,
+        stroked: true,
+        filled: false,
+        wireframe: true,
+        lineWidthMaxPixels: 1,
+        getPolygon: d => d.hull,
+        getLineColor: d => d.color,
+        getLineWidth: 1,
+      }));
+    }
+
+    if (cellSetLabelsVisible) {
+      const { zoom } = viewState;
+      const nodes = cellSetPolygons.map(p => ({
+        x: p.centroid[0],
+        y: p.centroid[1],
+        label: p.name,
+      }));
+
+      const collisionForce = this.cellSetsForceSimulation
+        .size(d => ([
+          cellSetLabelSize * 1 / (2 ** zoom) * 4 * d.label.length,
+          cellSetLabelSize * 1 / (2 ** zoom) * 1.5,
+        ]));
+
+      forceSimulation()
+        .nodes(nodes)
+        .force('collision', collisionForce)
+        .tick(NUM_FORCE_SIMULATION_TICKS);
+
+      result.push(new deck.TextLayer({
+        id: 'cell-sets-text-layer',
+        data: nodes,
+        getPosition: d => ([d.x, d.y]),
+        getText: d => d.label,
+        getColor: (theme === 'dark' ? [255, 255, 255] : [0, 0, 0]),
+        getSize: cellSetLabelSize,
+        getAngle: 0,
+        getTextAnchor: 'middle',
+        getAlignmentBaseline: 'center',
+        fontFamily: LABEL_FONT_FAMILY,
+        fontWeight: 'normal',
+      }));
+    }
+
+    return result;
+  }
+
+  createSelectionLayers() {
+    const {
+      obsEmbeddingIndex: obsIndex,
+      obsEmbedding,
+      viewState,
+      setCellSelection,
+    } = this.props;
+    const { tool } = this.state;
+    const { cellsQuadTree } = this;
+    const flipYTooltip = true;
+    const getCellCoords = makeDefaultGetObsCoords(obsEmbedding);
+    return getSelectionLayers(
+      tool,
+      viewState.zoom,
+      CELLS_LAYER_ID,
+      getCellCoords,
+      obsIndex,
+      setCellSelection,
+      cellsQuadTree,
+      flipYTooltip,
+    );
+  }
+
+  getLayers() {
+    const {
+      cellsLayer,
+      cellSetsLayers,
+    } = this;
+    return [
+      cellsLayer,
+      ...cellSetsLayers,
+      ...this.createSelectionLayers(),
+    ];
+  }
+
+  onUpdateCellsData() {
+    const { obsEmbedding } = this.props;
+    if (obsEmbedding) {
+      const getCellCoords = makeDefaultGetObsCoords(obsEmbedding);
+      this.cellsQuadTree = createQuadTree(obsEmbedding, getCellCoords);
+      this.cellsData = {
+        src: {
+          obsEmbedding,
+        },
+        length: obsEmbedding.shape[1],
+      };
+    }
+  }
+
+  onUpdateCellsLayer() {
+    const { obsEmbeddingIndex, obsEmbedding } = this.props;
+    if (obsEmbeddingIndex && obsEmbedding) {
+      this.cellsLayer = this.createCellsLayer();
+    } else {
+      this.cellsLayer = null;
+    }
+  }
+
+  onUpdateCellSetsLayers(onlyViewStateChange) {
+    // Because the label sizes for the force simulation depend on the zoom level,
+    // we _could_ run the simulation every time the zoom level changes.
+    // However, this has a performance impact in firefox.
+    if (onlyViewStateChange) {
+      const { viewState, cellSetLabelsVisible } = this.props;
+      const { zoom } = viewState;
+      const { cellSetsLabelPrevZoom } = this;
+      // Instead, we can just check if the zoom level has changed
+      // by some relatively large delta, to be more conservative
+      // about re-running the force simulation.
+      if (cellSetLabelsVisible
+        && (
+          cellSetsLabelPrevZoom === null
+          || Math.abs(cellSetsLabelPrevZoom - zoom) > LABEL_UPDATE_ZOOM_DELTA
+        )
+      ) {
+        this.cellSetsLayers = this.createCellSetsLayers();
+        this.cellSetsLabelPrevZoom = zoom;
+      }
+    } else {
+      // Otherwise, something more substantial than just
+      // the viewState has changed, such as the label array
+      // itself, so we always want to update the layer
+      // in this case.
+      this.cellSetsLayers = this.createCellSetsLayers();
+    }
+  }
+
+  viewInfoDidUpdate() {
+    const {
+      obsEmbeddingIndex,
+      obsEmbedding,
+    } = this.props;
+    super.viewInfoDidUpdate(
+      obsEmbeddingIndex,
+      obsEmbedding,
+      makeFlippedGetObsCoords,
+    );
+  }
+
+  /**
+   * Here, asynchronously check whether props have
+   * updated which require re-computing memoized variables,
+   * followed by a re-render.
+   * This function does not follow React conventions or paradigms,
+   * it is only implemented this way to try to squeeze out
+   * performance.
+   * @param {object} prevProps The previous props to diff against.
+   */
+  componentDidUpdate(prevProps) {
+    this.viewInfoDidUpdate();
+
+    const shallowDiff = propName => (prevProps[propName] !== this.props[propName]);
+    let forceUpdate = false;
+    if (['obsEmbedding'].some(shallowDiff)) {
+      // Cells data changed.
+      this.onUpdateCellsData();
+      forceUpdate = true;
+    }
+
+    if ([
+      'obsEmbeddingIndex', 'obsEmbedding', 'cellFilter', 'cellSelection', 'cellColors',
+      'cellRadius', 'cellOpacity', 'cellRadiusMode', 'geneExpressionColormap',
+      'geneExpressionColormapRange', 'geneSelection', 'cellColorEncoding',
+      'getExpressionValue',
+    ].some(shallowDiff)) {
+      // Cells layer props changed.
+      this.onUpdateCellsLayer();
+      forceUpdate = true;
+    }
+    if ([
+      'cellSetPolygons', 'cellSetPolygonsVisible',
+      'cellSetLabelsVisible', 'cellSetLabelSize',
+    ].some(shallowDiff)) {
+      // Cell sets layer props changed.
+      this.onUpdateCellSetsLayers(false);
+      forceUpdate = true;
+    }
+    if (shallowDiff('viewState')) {
+      // The viewState prop has changed (due to zoom or pan).
+      this.onUpdateCellSetsLayers(true);
+      forceUpdate = true;
+    }
+    if (forceUpdate) {
+      this.forceUpdate();
+    }
+  }
+
+  recenter() {
+    const { originalViewState, setViewState } = this.props;
+    if (Array.isArray(originalViewState?.target) && typeof originalViewState?.zoom === 'number') {
+      setViewState(originalViewState);
+    }
+  }
+
+  // render() is implemented in the abstract parent class.
+}
+
+/**
+ * Need this wrapper function here,
+ * since we want to pass a forwardRef
+ * so that outer components can
+ * access the grandchild DeckGL ref,
+ * but we are using a class component.
+ */
+const ScatterplotWrapper = forwardRef((props, deckRef) => (
+  <Scatterplot
+    {...props}
+    deckRef={deckRef}
+  />
+));
+ScatterplotWrapper.displayName = 'ScatterplotWrapper';
+export default ScatterplotWrapper;