@vitessce/scatterplot 2.0.3-beta.0 → 3.0.0

package/src/shared-spatial-scatterplot/ToolMenu.js

@@ -0,0 +1,143 @@
+import React from 'react';
+import clsx from 'clsx';
+import { SELECTION_TYPE } from '@vitessce/gl';
+import { PointerIconSVG, SelectLassoIconSVG } from '@vitessce/icons';
+import { makeStyles } from '@material-ui/core';
+import { CenterFocusStrong } from '@material-ui/icons';
+
+const useStyles = makeStyles(() => ({
+  button: {
+    display: 'inline-flex',
+    '&:active': {
+      opacity: '.65',
+      extend: 'iconClicked',
+    },
+  },
+  tool: {
+    position: 'absolute',
+    display: 'inline',
+    zIndex: '1000',
+    opacity: '.65',
+    color: 'black',
+    '&:hover': {
+      opacity: '.90',
+    },
+  },
+  iconClicked: {
+    // Styles for the clicked state
+    boxShadow: 'none',
+    transform: 'scale(0.98)', // make the button slightly smaller
+  },
+  icon: {
+    // btn btn-outline-secondary mr-2 icon
+    padding: '0',
+    height: '2em',
+    width: '2em',
+    backgroundColor: 'white',
+
+    display: 'inline-block',
+    fontWeight: '400',
+    textAlign: 'center',
+    verticalAlign: 'middle',
+    cursor: 'pointer',
+    userSelect: 'none',
+    border: '1px solid #6c757d',
+    fontSize: '16px',
+    lineHeight: '1.5',
+    borderRadius: '4px',
+    transition: 'color 0.15s ease-in-out, background-color 0.15s ease-in-out, border-color 0.15s ease-in-out, box-shadow 0.15s ease-in-out',
+    color: '#6c757d',
+
+    marginRight: '8px',
+
+    '& > svg': {
+      verticalAlign: 'middle',
+      color: 'black',
+    },
+    '&:active': {
+      extend: 'iconClicked',
+    },
+
+  },
+  toolActive: {
+    // active
+    color: '#fff',
+    backgroundColor: '#6c757d',
+    borderColor: '#6c757d',
+    boxShadow: '0 0 0 3px rgba(108, 117, 125, 0.5)',
+  },
+}));
+
+export function IconTool(props) {
+  const {
+    alt, onClick, isActive, children,
+  } = props;
+  const classes = useStyles();
+  return (
+    <button
+      className={clsx(classes.icon, { [classes.toolActive]: isActive })}
+      onClick={onClick}
+      type="button"
+      title={alt}
+    >
+      {children}
+    </button>
+  );
+}
+
+export function IconButton(props) {
+  const {
+    alt, onClick, children,
+  } = props;
+  const classes = useStyles();
+  return (
+    <button
+      className={clsx(classes.icon, classes.button)}
+      onClick={onClick}
+      type="button"
+      title={alt}
+    >
+      {children}
+    </button>
+  );
+}
+
+export default function ToolMenu(props) {
+  const {
+    setActiveTool,
+    activeTool,
+    visibleTools = { pan: true, selectLasso: true },
+    recenterOnClick = () => {},
+  } = props;
+  const classes = useStyles();
+
+  const onRecenterButtonCLick = () => {
+    recenterOnClick();
+  };
+
+  return (
+    <div className={classes.tool}>
+      {visibleTools.pan && (
+      <IconTool
+        alt="pointer tool"
+        onClick={() => setActiveTool(null)}
+        isActive={activeTool === null}
+      ><PointerIconSVG />
+      </IconTool>
+      )}
+      {visibleTools.selectLasso ? (
+        <IconTool
+          alt="select lasso"
+          onClick={() => setActiveTool(SELECTION_TYPE.POLYGON)}
+          isActive={activeTool === SELECTION_TYPE.POLYGON}
+        ><SelectLassoIconSVG />
+        </IconTool>
+      ) : null}
+      <IconButton
+        alt="click to recenter"
+        onClick={() => onRecenterButtonCLick()}
+      ><CenterFocusStrong />
+      </IconButton>
+    </div>
+  );
+}

package/src/shared-spatial-scatterplot/ToolMenu.test.jsx

@@ -0,0 +1,26 @@
+import '@testing-library/jest-dom';
+import { cleanup, render } from '@testing-library/react';
+import { afterEach, expect } from 'vitest';
+import React from 'react';
+
+import { IconTool, IconButton } from './ToolMenu.js';
+
+afterEach(() => {
+  cleanup();
+});
+
+describe('ToolMenu.js', () => {
+  describe('<IconTool />', () => {
+    it('renders with title attribute', () => {
+      const { container } = render(<IconTool isActive alt="Lasso" />);
+      expect(container.querySelectorAll('[title="Lasso"]').length).toEqual(1);
+    });
+  });
+
+  describe('<IconButton />', () => {
+    it('renders with title attribute', () => {
+      const { container } = render(<IconButton alt="click to recenter" />);
+      expect(container.querySelectorAll('[title="click to recenter"]').length).toEqual(1);
+    });
+  });
+});

package/src/shared-spatial-scatterplot/cursor.js

@@ -0,0 +1,23 @@
+export const getCursorWithTool = () => 'crosshair';
+export const getCursor = interactionState => (interactionState.isDragging
+  ? 'grabbing' : 'default'
+);
+
+export function getOnHoverCallback(obsIndex, setObsHighlight, setComponentHover) {
+  return (info) => {
+    // Notify the parent component that its child component is
+    // the "hover source".
+    if (setComponentHover) {
+      setComponentHover();
+    }
+    if (info.index) {
+      const obsId = obsIndex[info.index];
+      if (setObsHighlight) {
+        setObsHighlight(obsId);
+      }
+    } else if (setObsHighlight) {
+      // Clear the currently-hovered cell info by passing null.
+      setObsHighlight(null);
+    }
+  };
+}

package/src/shared-spatial-scatterplot/dynamic-opacity.js

@@ -0,0 +1,58 @@
+import { deck } from '@vitessce/gl';
+import { clamp } from 'lodash-es';
+
+// Reference: https://observablehq.com/@rreusser/selecting-the-right-opacity-for-2d-point-clouds
+// Reference: https://observablehq.com/@bmschmidt/dot-density-election-maps-with-webgl
+export function getPointSizeDevicePixels(devicePixelRatio, zoom, xRange, yRange, width, height) {
+  // Size of a point, in units of the diagonal axis.
+  const pointSize = 0.0005;
+  // Point size maximum, in screen pixels.
+  const pointScreenSizeMax = 10;
+
+  // Point size minimum, in screen pixels.
+  const pointScreenSizeMin = 1 / devicePixelRatio;
+
+  const scaleFactor = 2 ** zoom;
+  const xAxisRange = 2.0 / ((xRange * scaleFactor) / width);
+  const yAxisRange = 2.0 / ((yRange * scaleFactor) / height);
+
+  // The diagonal screen size as a fraction of the current diagonal axis range,
+  // then converted to device pixels.
+  const diagonalScreenSize = Math.sqrt((width ** 2) + (height ** 2));
+  const diagonalAxisRange = Math.sqrt((xAxisRange ** 2) + (yAxisRange ** 2));
+  const diagonalFraction = pointSize / diagonalAxisRange;
+  const deviceSize = diagonalFraction * diagonalScreenSize;
+
+  const pointSizeDevicePixels = clamp(
+    deviceSize,
+    pointScreenSizeMin,
+    pointScreenSizeMax,
+  );
+  return pointSizeDevicePixels;
+}
+
+// Reference: https://observablehq.com/@rreusser/selecting-the-right-opacity-for-2d-point-clouds
+export function getPointOpacity(zoom, xRange, yRange, width, height, numCells, avgFillDensity) {
+  const N = numCells;
+  const [minX, minY, maxX, maxY] = new deck.OrthographicView({ zoom }).makeViewport({
+    height,
+    width,
+    viewState: { zoom, target: [0, 0, 0] },
+  }).getBounds();
+  const X = maxY - minY;
+  const Y = maxX - minX;
+  const X0 = xRange;
+  const Y0 = yRange;
+  const W = width;
+  const H = height;
+
+  let rho = avgFillDensity;
+  if (!rho) {
+    rho = Math.min(1, 1 / (10 ** (Math.log10(N) - 3)));
+  }
+  // p in the calculation is the pixel length/width of a given point, which for us is 1
+  // so it does not factor into our calculation here.
+  const alpha = ((rho * W * H) / N) * (Y0 / Y) * (X0 / X);
+  const pointOpacity = clamp(alpha, 1.01 / 255, 1.0);
+  return pointOpacity;
+}

package/src/shared-spatial-scatterplot/dynamic-opacity.test.js

@@ -0,0 +1,33 @@
+import { getPointSizeDevicePixels, getPointOpacity } from './dynamic-opacity.js';
+
+describe('dynamic-opacity.js', () => {
+  describe('getPointSizeDevicePixels', () => {
+    it('calculates point size', () => {
+      const devicePixelRatio = 2.0;
+      const zoom = null;
+      const xRange = 20;
+      const yRange = 18;
+      const width = 1000;
+      const height = 650;
+      const pointSize = getPointSizeDevicePixels(
+        devicePixelRatio, zoom, xRange, yRange, width, height,
+      );
+      expect(pointSize).toBeCloseTo(0.5);
+    });
+  });
+  describe('getPointOpacity', () => {
+    it('calculates point opacity', () => {
+      const zoom = null;
+      const width = 1000;
+      const height = 650;
+      const xRange = 20;
+      const yRange = 18;
+      const numCells = 500000;
+      const avgFillDensity = undefined;
+      const pointOpacity = getPointOpacity(
+        zoom, xRange, yRange, width, height, numCells, avgFillDensity,
+      );
+      expect(pointOpacity).toBeCloseTo(0.005);
+    });
+  });
+});

package/src/shared-spatial-scatterplot/force-collide-rects.js

@@ -0,0 +1,189 @@
+/* eslint-disable no-plusplus */
+/* eslint-disable no-param-reassign */
+import { quadtree } from 'd3-quadtree';
+
+/**
+ * Returns a closure that returns a constant value.
+ */
+function constant(v) {
+  return (() => v);
+}
+
+/**
+ * Adds a tiny bit of randomness to a number.
+ */
+function jiggle(v) {
+  return v + (Math.random() - 0.5) * 1e-6;
+}
+
+/**
+ * A force function to be used with d3.forceSimulation.
+ * This has been adapted for use here, with comments explaining each part.
+ * Reference: https://bl.ocks.org/cmgiven/547658968d365bcc324f3e62e175709b
+ */
+export function forceCollideRects() {
+  // D3 implements things with function prototypes rather than classes.
+  // Pretend these variables are the "instance members" of a class.
+  // Note that this function actually returns the internal force() function,
+  // but that the force() function is a closure with access to these instance members.
+
+  let nodes;
+  let masses;
+  let strength = 1;
+  let iterations = 1;
+
+  let sizes;
+  let size = constant([0, 0]);
+
+  // Given a node, return the center point along the x-axis.
+  function xCenter(d) {
+    return d.x + d.vx + sizes[d.index][0] / 2;
+  }
+
+  // Given a node, return the center point along the y-axis.
+  function yCenter(d) {
+    return d.y + d.vy + sizes[d.index][1] / 2;
+  }
+
+  // Given a quadtree node, initialize its .size property.
+  function prepare(quad) {
+    if (quad.data) {
+      // This is a leaf node, so we set quad.size to the node's size.
+      // (No need to compute the max of internal nodes,
+      // since leaf nodes do not have any internal nodes).
+      quad.size = sizes[quad.data.index];
+    } else {
+      quad.size = [0, 0];
+      // Internal nodes of the quadtree are represented
+      // as four-element arrays in left-to-right, top-to-bottom order.
+      // Here, we are setting quad.size to [maxWidth, maxHeight]
+      // among the internal nodes of this current `quad` node.
+      for (let i = 0; i < 4; i++) {
+        if (quad[i] && quad[i].size) {
+          quad.size[0] = Math.max(quad.size[0], quad[i].size[0]);
+          quad.size[1] = Math.max(quad.size[1], quad[i].size[1]);
+        }
+      }
+    }
+  }
+
+  function force() {
+    let node;
+    let nodeSize;
+    let nodeMass;
+    let xi;
+    let yi;
+
+    // Create a quadtree based on node center points.
+    // Initialize each quadtree node's .size property by calling
+    // the prepare() function on each quadtree node.
+    const tree = quadtree(nodes, xCenter, yCenter).visitAfter(prepare);
+
+    // Update the .vx and .vy properties of both `node` and `data`
+    // (the current node pair).
+    function apply(quad, x0, y0, x1, y1) {
+      // `quad` is a quadtree node.
+      const { data } = quad;
+      const xSize = (nodeSize[0] + quad.size[0]) / 2;
+      const ySize = (nodeSize[1] + quad.size[1]) / 2;
+
+      if (data && data.index > node.index) {
+        // This is a leaf node because `data` is defined.
+        // `x` is the difference in x centers between `node` and `data`.
+        // `y` is the difference in y centers between `node` and `data`.
+        let x = jiggle(xi - xCenter(data));
+        let y = jiggle(yi - yCenter(data));
+        const xd = Math.abs(x) - xSize;
+        const yd = Math.abs(y) - ySize;
+
+        // If `xd` and `yd` is less than zero,
+        // then there is an overlap between the two nodes.
+        if (xd < 0 && yd < 0) {
+          const l = Math.sqrt(x * x + y * y);
+          const m = masses[data.index] / (nodeMass + masses[data.index]);
+
+          // We move the nodes either in the x or y direction.
+          // Nodes are moved proportionally to:
+          // their distance apart (`l`), their amount of overlap (`xd` or `yd`), their masses (`m`),
+          // and the strength parameter (`strength`).
+          if (Math.abs(xd) < Math.abs(yd)) {
+            node.vx -= (x *= xd / l * strength) * m;
+            data.vx += x * (1 - m);
+          } else {
+            node.vy -= (y *= yd / l * strength) * m;
+            data.vy += y * (1 - m);
+          }
+        }
+        // When the quadtree.visit callback returns _true_ for a node,
+        // then the node's children will _not_ be visited.
+        return x0 > xi + xSize || x1 < xi - xSize || y0 > yi + ySize || y1 < yi - ySize;
+      }
+      return false;
+    }
+
+    function iterate() {
+      // On every iteration, use the `apply` function to visit every node
+      // which has an index greater than the current node's index,
+      // (visiting every node pair).
+      for (let j = 0; j < nodes.length; j++) {
+        node = nodes[j];
+        nodeSize = sizes[j];
+        nodeMass = masses[j];
+        xi = xCenter(node);
+        yi = yCenter(node);
+
+        tree.visit(apply);
+      }
+    }
+
+    // Do the specified number of iterations.
+    for (let i = 0; i < iterations; i++) {
+      iterate();
+    }
+  }
+
+  // The "constructor".
+  // Takes a list of nodes as input.
+  force.initialize = (v) => {
+    nodes = v;
+    // Get the size [w, h] of each node using the size getter function.
+    sizes = nodes.map(size);
+    // Get the mass of each node,
+    // which is the sum of its horizontal and vertical edge lengths.
+    masses = sizes.map(d => d[0] + d[1]);
+  };
+
+  // Set the number of iterations.
+  // If no value is provided as a parameter, this acts as a getter function.
+  force.iterations = (...v) => {
+    if (v.length) {
+      iterations = +v[0];
+      return force;
+    }
+    return iterations;
+  };
+
+  // Set the strength value.
+  // If no value is provided as a parameter, this acts as a getter function.
+  force.strength = (...v) => {
+    if (v.length) {
+      strength = +v[0];
+      return force;
+    }
+    return strength;
+  };
+
+  // Set the size function.
+  // The size function takes a node as a parameter and returns its size.
+  // If no size function is provided as a parameter, this acts as a getter function.
+  force.size = (...v) => {
+    if (v.length) {
+      size = (typeof v[0] === 'function' ? v[0] : constant(v[0]));
+      return force;
+    }
+    return size;
+  };
+
+  // Returns the force closure.
+  return force;
+}

package/src/shared-spatial-scatterplot/force-collide-rects.test.js

@@ -0,0 +1,72 @@
+import { forceSimulation } from 'd3-force';
+import { forceCollideRects } from './force-collide-rects.js';
+
+describe('force-collide-rects.js', () => {
+  describe('forceCollideRects', () => {
+    it('can be initialized with a size function', () => {
+      const collisionForce = forceCollideRects()
+        .size(d => ([d.width, d.height]));
+
+      const size = collisionForce.size();
+      const [w, h] = size({ width: 2, height: 3 });
+      expect(w).toEqual(2);
+      expect(h).toEqual(3);
+    });
+
+    it('cannot prevent a collision of rects after few iterations', () => {
+      const collisionForce = forceCollideRects()
+        .size(d => ([d.width, d.height]));
+
+      const nodes = [
+        {
+          label: 'A', width: 100, height: 100, x: 2, y: 2,
+        },
+        {
+          label: 'B', width: 100, height: 100, x: 3, y: 3,
+        },
+        {
+          label: 'C', width: 100, height: 100, x: 3, y: 2,
+        },
+      ];
+
+      forceSimulation()
+        .nodes(nodes)
+        .force('collision', collisionForce)
+        .tick(2);
+
+      const collisionAB = (
+        Math.abs(nodes[0].x - nodes[1].x) < 100
+            && Math.abs(nodes[0].y - nodes[1].y) < 100
+      );
+      expect(collisionAB).toEqual(true);
+    });
+
+    it('can prevent a collision of rects after many iterations', () => {
+      const collisionForce = forceCollideRects()
+        .size(d => ([d.width, d.height]));
+
+      const nodes = [
+        {
+          label: 'A', width: 100, height: 100, x: 2, y: 2,
+        },
+        {
+          label: 'B', width: 100, height: 100, x: 3, y: 3,
+        },
+        {
+          label: 'C', width: 100, height: 100, x: 3, y: 2,
+        },
+      ];
+
+      forceSimulation()
+        .nodes(nodes)
+        .force('collision', collisionForce)
+        .tick(50);
+
+      const collisionAB = (
+        Math.abs(nodes[0].x - nodes[1].x) < 100
+                && Math.abs(nodes[0].y - nodes[1].y) < 100
+      );
+      expect(collisionAB).toEqual(false);
+    });
+  });
+});

package/src/shared-spatial-scatterplot/index.js

@@ -0,0 +1,8 @@
+export { default as AbstractSpatialOrScatterplot } from './AbstractSpatialOrScatterplot.js';
+export { createQuadTree } from './quadtree.js';
+export { forceCollideRects } from './force-collide-rects.js';
+export { getOnHoverCallback } from './cursor.js';
+export {
+  getPointSizeDevicePixels,
+  getPointOpacity,
+} from './dynamic-opacity.js';

package/src/shared-spatial-scatterplot/quadtree.js

@@ -0,0 +1,27 @@
+import { quadtree } from 'd3-quadtree';
+import { range } from 'lodash-es';
+
+/**
+ * Create a d3-quadtree object for cells data points.
+ * @param {array} cellsEntries Array of [cellId, cell] tuples,
+ * resulting from running Object.entries on the cells object.
+ * @param {function} getCellCoords Given a cell object, return the
+ * spatial/scatterplot coordinates [x, y].
+ * @returns {object} Quadtree instance.
+ */
+export function createQuadTree(obsEmbedding, getCellCoords) {
+  // Use the cellsEntries variable since it is already
+  // an array, converted by Object.entries().
+  // Only use cellsEntries in quadtree calculation if there is
+  // centroid data in the cells (i.e not just ids).
+  // eslint-disable-next-line no-unused-vars
+  if (!obsEmbedding) {
+    // Abort if the cells data is not yet available.
+    return null;
+  }
+  const tree = quadtree()
+    .x(i => getCellCoords(i)[0])
+    .y(i => getCellCoords(i)[1])
+    .addAll(range(obsEmbedding.shape[1]));
+  return tree;
+}

package/dist/shared-spatial-scatterplot/ToolMenu.test.js

@@ -1,16 +0,0 @@
-import { jsx as _jsx } from "react/jsx-runtime";
-import '@testing-library/jest-dom';
-import { cleanup, render } from '@testing-library/react';
-import { afterEach, expect } from 'vitest';
-import { IconButton } from './ToolMenu';
-afterEach(() => {
-    cleanup();
-});
-describe('ToolMenu.js', () => {
-    describe('<IconButton />', () => {
-        it('renders with title attribute', () => {
-            const { container } = render(_jsx(IconButton, { isActive: true, alt: "Lasso" }));
-            expect(container.querySelectorAll('[title="Lasso"]').length).toEqual(1);
-        });
-    });
-});

package/dist/shared-spatial-scatterplot/index.js

@@ -1,5 +0,0 @@
-export { default as AbstractSpatialOrScatterplot } from './AbstractSpatialOrScatterplot';
-export { createQuadTree } from './quadtree';
-export { forceCollideRects } from './force-collide-rects';
-export { getOnHoverCallback } from './cursor';
-export { getPointSizeDevicePixels, getPointOpacity, } from './dynamic-opacity';