@vitessce/statistical-plots 2.0.3-beta.0 → 3.0.0

package/src/CellSetExpressionPlotSubscriber.js

@@ -0,0 +1,220 @@
+import React, { useMemo } from 'react';
+import {
+  TitleInfo,
+  useCoordination, useLoaders,
+  useUrls, useReady, useGridItemSize,
+  useFeatureSelection, useObsSetsData,
+  useObsFeatureMatrixIndices,
+  useFeatureLabelsData,
+} from '@vitessce/vit-s';
+import { ViewType, COMPONENT_COORDINATION_TYPES } from '@vitessce/constants-internal';
+import { VALUE_TRANSFORM_OPTIONS, capitalize, getValueTransformFunction } from '@vitessce/utils';
+import { treeToObjectsBySetNames, treeToSetSizesBySetNames, mergeObsSets } from '@vitessce/sets-utils';
+import CellSetExpressionPlotOptions from './CellSetExpressionPlotOptions.js';
+import CellSetExpressionPlot from './CellSetExpressionPlot.js';
+import { useStyles } from './styles.js';
+
+/**
+ * Get expression data for the cells
+ * in the selected cell sets.
+ * @param {object} expressionMatrix
+ * @param {string[]} expressionMatrix.rows Cell IDs.
+ * @param {string[]} expressionMatrix.cols Gene names.
+ * @param {Uint8Array} expressionMatrix.matrix The
+ * flattened expression matrix as a typed array.
+ * @param {object} cellSets The cell sets from the dataset.
+ * @param {object} additionalCellSets The user-defined cell sets
+ * from the coordination space.
+ * @param {array} geneSelection Array of selected genes.
+ * @param {array} cellSetSelection Array of selected cell set paths.
+ * @param {object[]} cellSetColor Array of objects with properties
+ * @param {string|null} featureValueTransform The name of the
+ * feature value transform function.
+ * @param {number} featureValueTransformCoefficient A coefficient
+ * to be used in the transform function.
+ * @param {string} theme "light" or "dark" for the vitessce theme
+ * `path` and `color`.
+ */
+function useExpressionByCellSet(
+  expressionData, obsIndex, cellSets, additionalCellSets,
+  geneSelection, cellSetSelection, cellSetColor,
+  featureValueTransform, featureValueTransformCoefficient,
+  theme,
+) {
+  const mergedCellSets = useMemo(
+    () => mergeObsSets(cellSets, additionalCellSets),
+    [cellSets, additionalCellSets],
+  );
+
+  // From the expression matrix and the list of selected genes / cell sets,
+  // generate the array of data points for the plot.
+  const [expressionArr, expressionMax] = useMemo(() => {
+    if (mergedCellSets && cellSetSelection
+        && geneSelection && geneSelection.length >= 1
+        && expressionData
+    ) {
+      const cellObjects = treeToObjectsBySetNames(
+        mergedCellSets, cellSetSelection, cellSetColor, theme,
+      );
+
+      const firstGeneSelected = geneSelection[0];
+      // Create new cellColors map based on the selected gene.
+      let exprMax = -Infinity;
+      const cellIndices = {};
+      for (let i = 0; i < obsIndex.length; i += 1) {
+        cellIndices[obsIndex[i]] = i;
+      }
+      const exprValues = cellObjects.map((cell) => {
+        const cellIndex = cellIndices[cell.obsId];
+        const value = expressionData[0][cellIndex];
+        const transformFunction = getValueTransformFunction(
+          featureValueTransform, featureValueTransformCoefficient,
+        );
+        const transformedValue = transformFunction(value);
+        exprMax = Math.max(transformedValue, exprMax);
+        return { value: transformedValue, gene: firstGeneSelected, set: cell.name };
+      });
+      return [exprValues, exprMax];
+    }
+    return [null, null];
+  }, [expressionData, obsIndex, geneSelection, theme,
+    mergedCellSets, cellSetSelection, cellSetColor,
+    featureValueTransform, featureValueTransformCoefficient,
+  ]);
+
+  // From the cell sets hierarchy and the list of selected cell sets,
+  // generate the array of set sizes data points for the bar plot.
+  const setArr = useMemo(() => (mergedCellSets && cellSetSelection && cellSetColor
+    ? treeToSetSizesBySetNames(
+      mergedCellSets, cellSetSelection, cellSetSelection, cellSetColor, theme,
+    )
+    : []
+  ), [mergedCellSets, cellSetSelection, cellSetColor, theme]);
+
+  return [expressionArr, setArr, expressionMax];
+}
+
+
+/**
+ * A subscriber component for `CellSetExpressionPlot`,
+ * which listens for gene selection updates and
+ * `GRID_RESIZE` events.
+ * @param {object} props
+ * @param {function} props.removeGridComponent The grid component removal function.
+ * @param {object} props.coordinationScopes An object mapping coordination
+ * types to coordination scopes.
+ * @param {string} props.theme The name of the current Vitessce theme.
+ */
+export function CellSetExpressionPlotSubscriber(props) {
+  const {
+    coordinationScopes,
+    removeGridComponent,
+    theme,
+  } = props;
+
+  const classes = useStyles();
+  const loaders = useLoaders();
+
+  // Get "props" from the coordination space.
+  const [{
+    dataset,
+    obsType,
+    featureType,
+    featureValueType,
+    featureSelection: geneSelection,
+    featureValueTransform,
+    featureValueTransformCoefficient,
+    obsSetSelection: cellSetSelection,
+    obsSetColor: cellSetColor,
+    additionalObsSets: additionalCellSets,
+  }, {
+    setFeatureValueTransform,
+    setFeatureValueTransformCoefficient,
+  }] = useCoordination(
+    COMPONENT_COORDINATION_TYPES[ViewType.OBS_SET_FEATURE_VALUE_DISTRIBUTION],
+    coordinationScopes,
+  );
+
+  const [width, height, containerRef] = useGridItemSize();
+  const [urls, addUrl] = useUrls(loaders, dataset);
+
+  const transformOptions = VALUE_TRANSFORM_OPTIONS;
+
+  // Get data from loaders using the data hooks.
+  // eslint-disable-next-line no-unused-vars
+  const [expressionData, loadedFeatureSelection, featureSelectionStatus] = useFeatureSelection(
+    loaders, dataset, false, geneSelection,
+    { obsType, featureType, featureValueType },
+  );
+  // TODO: support multiple feature labels using featureLabelsType coordination values.
+  const [{ featureLabelsMap }, featureLabelsStatus] = useFeatureLabelsData(
+    loaders, dataset, addUrl, false, {}, {},
+    { featureType },
+  );
+  const [{ obsIndex }, matrixIndicesStatus] = useObsFeatureMatrixIndices(
+    loaders, dataset, addUrl, false,
+    { obsType, featureType, featureValueType },
+  );
+  const [{ obsSets: cellSets }, obsSetsStatus] = useObsSetsData(
+    loaders, dataset, addUrl, true, {}, {},
+    { obsType },
+  );
+  const isReady = useReady([
+    featureSelectionStatus,
+    matrixIndicesStatus,
+    obsSetsStatus,
+    featureLabelsStatus,
+  ]);
+
+  const [expressionArr, setArr, expressionMax] = useExpressionByCellSet(
+    expressionData, obsIndex, cellSets, additionalCellSets,
+    geneSelection, cellSetSelection, cellSetColor,
+    featureValueTransform, featureValueTransformCoefficient,
+    theme,
+  );
+
+  const firstGeneSelected = geneSelection && geneSelection.length >= 1
+    ? (featureLabelsMap?.get(geneSelection[0]) || geneSelection[0])
+    : null;
+  const selectedTransformName = transformOptions.find(
+    o => o.value === featureValueTransform,
+  )?.name;
+
+
+  return (
+    <TitleInfo
+      title={`Expression by ${capitalize(obsType)} Set${(firstGeneSelected ? ` (${firstGeneSelected})` : '')}`}
+      removeGridComponent={removeGridComponent}
+      urls={urls}
+      theme={theme}
+      isReady={isReady}
+      options={(
+        <CellSetExpressionPlotOptions
+          featureValueTransform={featureValueTransform}
+          setFeatureValueTransform={setFeatureValueTransform}
+          featureValueTransformCoefficient={featureValueTransformCoefficient}
+          setFeatureValueTransformCoefficient={setFeatureValueTransformCoefficient}
+          transformOptions={transformOptions}
+        />
+      )}
+    >
+      <div ref={containerRef} className={classes.vegaContainer}>
+        {expressionArr ? (
+          <CellSetExpressionPlot
+            domainMax={expressionMax}
+            colors={setArr}
+            data={expressionArr}
+            theme={theme}
+            width={width}
+            height={height}
+            obsType={obsType}
+            featureValueType={featureValueType}
+            featureValueTransformName={selectedTransformName}
+          />
+        ) : (
+          <span>Select a {featureType}.</span>
+        )}
+      </div>
+    </TitleInfo>
+  );
+}

package/src/CellSetSizesPlot.js

@@ -0,0 +1,173 @@
+import React, { useCallback } from 'react';
+import { clamp } from 'lodash-es';
+import { VegaPlot, VEGA_THEMES } from '@vitessce/vega';
+import { colorArrayToString } from '@vitessce/sets-utils';
+import { capitalize, getDefaultColor } from '@vitessce/utils';
+
+/**
+ * Cell set sizes displayed as a bar chart,
+ * implemented with the VegaPlot component.
+ * @param {object} props
+ * @param {object[]} props.data The set size data, an array
+ * of objects with properties `name`, `key`, `color`, and `size`.
+ * @param {string} props.theme The name of the current Vitessce theme.
+ * @param {number} props.width The container width.
+ * @param {number} props.height The container height.
+ * @param {number} props.marginRight The size of the margin
+ * on the right side of the plot, to account for the vega menu button.
+ * By default, 90.
+ * @param {number} props.marginBottom The size of the margin
+ * on the bottom of the plot, to account for long x-axis labels.
+ * By default, 120.
+ * @param {number} props.keyLength The length of the `key` property of
+ * each data point. Assumes all key strings have the same length.
+ * By default, 36.
+ */
+export default function CellSetSizesPlot(props) {
+  const {
+    data: rawData,
+    theme,
+    width,
+    height,
+    marginRight = 90,
+    marginBottom = 120,
+    keyLength = 36,
+    obsType,
+    onBarSelect,
+  } = props;
+
+  // Add a property `keyName` which concatenates the key and the name,
+  // which is both unique and can easily be converted
+  // back to the name by taking a substring.
+  // Add a property `colorString` which contains the `[r, g, b]` color
+  // after converting to a color hex string.
+  const data = rawData.map(d => ({
+    ...d,
+    keyName: d.key + d.name,
+    colorString: colorArrayToString(d.color),
+  }));
+
+  // Get an array of keys for sorting purposes.
+  const keys = data.map(d => d.keyName);
+
+  const colorScale = {
+    // Manually set the color scale so that Vega-Lite does
+    // not choose the colors automatically.
+    domain: data.map(d => d.key),
+    range: data.map((d) => {
+      const [r, g, b] = !d.isGrayedOut ? d.color : getDefaultColor(theme);
+      return `rgba(${r}, ${g}, ${b}, 1)`;
+    }),
+  };
+  const captializedObsType = capitalize(obsType);
+
+  const spec = {
+    mark: { type: 'bar', stroke: 'black', cursor: 'pointer' },
+    params: [
+      {
+        name: 'highlight',
+        select: {
+          type: 'point',
+          on: 'mouseover',
+        },
+      },
+      {
+        name: 'select',
+        select: 'point',
+      },
+      {
+        name: 'bar_select',
+        select: {
+          type: 'point',
+          on: 'click[event.shiftKey === false]',
+          fields: ['setNamePath', 'isGrayedOut'],
+          empty: 'none',
+        },
+      },
+      {
+        name: 'shift_bar_select',
+        select: {
+          type: 'point',
+          on: 'click[event.shiftKey]',
+          fields: ['setNamePath', 'isGrayedOut'],
+          empty: 'none',
+        },
+      },
+    ],
+    encoding: {
+      x: {
+        field: 'keyName',
+        type: 'nominal',
+        axis: { labelExpr: `substring(datum.label, ${keyLength})` },
+        title: 'Cell Set',
+        sort: keys,
+      },
+      y: {
+        field: 'size',
+        type: 'quantitative',
+        title: `${captializedObsType} Set Size`,
+      },
+      color: {
+        field: 'key',
+        type: 'nominal',
+        scale: colorScale,
+        legend: null,
+      },
+      tooltip: {
+        field: 'size',
+        type: 'quantitative',
+      },
+      fillOpacity: {
+        condition: {
+          param: 'select',
+          value: 1,
+        },
+        value: 0.3,
+      },
+      strokeWidth: {
+        condition: [
+          {
+            param: 'select',
+            empty: false,
+            value: 1,
+          },
+          {
+            param: 'highlight',
+            empty: false,
+            value: 2,
+          },
+        ],
+        value: 0,
+      },
+    },
+    width: clamp(width - marginRight, 10, Infinity),
+    height: clamp(height - marginBottom, 10, Infinity),
+    config: VEGA_THEMES[theme],
+  };
+
+  const handleSignal = (name, value) => {
+    if (name === 'bar_select') {
+      onBarSelect(value.setNamePath, value.isGrayedOut[0]);
+    } else if (name === 'shift_bar_select') {
+      const isGrayedOut = false;
+      const selectOnlyEnabled = true;
+      onBarSelect(value.setNamePath, isGrayedOut, selectOnlyEnabled);
+    }
+  };
+
+  const signalListeners = { bar_select: handleSignal, shift_bar_select: handleSignal };
+  const getTooltipText = useCallback(item => ({
+    [`${captializedObsType} Set`]: item.datum.name,
+    [`${captializedObsType} Set Size`]: item.datum.size,
+  }
+  ), [captializedObsType]);
+
+  return (
+    <VegaPlot
+      data={data}
+      spec={spec}
+      signalListeners={signalListeners}
+      getTooltipText={getTooltipText}
+    />
+  );
+}

package/src/CellSetSizesPlotSubscriber.js

@@ -0,0 +1,151 @@
+import React, { useMemo, useState } from 'react';
+import {
+  TitleInfo,
+  useCoordination, useLoaders,
+  useUrls, useReady, useGridItemSize,
+  useObsSetsData,
+} from '@vitessce/vit-s';
+import { isEqual } from 'lodash-es';
+import { ViewType, COMPONENT_COORDINATION_TYPES } from '@vitessce/constants-internal';
+import {
+  mergeObsSets, treeToSetSizesBySetNames, filterPathsByExpansionAndSelection, findChangedHierarchy,
+} from '@vitessce/sets-utils';
+import { capitalize } from '@vitessce/utils';
+import CellSetSizesPlot from './CellSetSizesPlot.js';
+import { useStyles } from './styles.js';
+
+/**
+ * A subscriber component for `CellSetSizePlot`,
+ * which listens for cell sets data updates and
+ * `GRID_RESIZE` events.
+ * @param {object} props
+ * @param {function} props.removeGridComponent The grid component removal function.
+ * @param {function} props.onReady The function to call when the subscriptions
+ * have been made.
+ * @param {string} props.theme The name of the current Vitessce theme.
+ * @param {string} props.title The component title.
+ */
+export function CellSetSizesPlotSubscriber(props) {
+  const {
+    coordinationScopes,
+    removeGridComponent,
+    theme,
+    title: titleOverride,
+  } = props;
+
+  const classes = useStyles();
+
+  const loaders = useLoaders();
+
+  // Get "props" from the coordination space.
+  const [{
+    dataset,
+    obsType,
+    obsSetSelection: cellSetSelection,
+    obsSetColor: cellSetColor,
+    additionalObsSets: additionalCellSets,
+    obsSetExpansion: cellSetExpansion,
+  }, {
+    setObsSetSelection: setCellSetSelection,
+    setObsSetColor: setCellSetColor,
+  }] = useCoordination(COMPONENT_COORDINATION_TYPES[ViewType.OBS_SET_SIZES], coordinationScopes);
+
+  const title = titleOverride || `${capitalize(obsType)} Set Sizes`;
+
+  const [width, height, containerRef] = useGridItemSize();
+  const [urls, addUrl] = useUrls(loaders, dataset);
+
+  // the name of the hierarchy that was clicked on last
+  const [currentHierarchy, setCurrentHierarchy] = useState([]);
+  // the previous cell set that was selected
+  const [prevCellSetSelection, setPrevCellSetSelection] = useState([]);
+
+  // Get data from loaders using the data hooks.
+  const [{ obsSets: cellSets }, obsSetsStatus] = useObsSetsData(
+    loaders, dataset, addUrl, true,
+    { setObsSetSelection: setCellSetSelection, setObsSetColor: setCellSetColor },
+    { obsSetSelection: cellSetSelection, obsSetColor: cellSetColor },
+    { obsType },
+  );
+  const isReady = useReady([
+    obsSetsStatus,
+  ]);
+
+  const mergedCellSets = useMemo(
+    () => mergeObsSets(cellSets, additionalCellSets),
+    [cellSets, additionalCellSets],
+  );
+
+  const data = useMemo(() => {
+    if (cellSetSelection && cellSetColor && mergedCellSets && cellSets) {
+      let newHierarchy = currentHierarchy;
+
+      if (cellSetSelection) {
+        const changedHierarchy = findChangedHierarchy(prevCellSetSelection, cellSetSelection);
+        setPrevCellSetSelection(cellSetSelection);
+
+        if (changedHierarchy) {
+          setCurrentHierarchy(changedHierarchy);
+          newHierarchy = changedHierarchy;
+        }
+      }
+
+      const cellSetPaths = filterPathsByExpansionAndSelection(
+        mergedCellSets,
+        newHierarchy,
+        cellSetExpansion,
+        cellSetSelection,
+      );
+
+      if (mergedCellSets && cellSets && cellSetSelection && cellSetColor) {
+        return treeToSetSizesBySetNames(
+          mergedCellSets,
+          cellSetPaths,
+          cellSetSelection,
+          cellSetColor,
+          theme,
+        );
+      }
+    }
+    return [];
+  }, [
+    mergedCellSets,
+    cellSetSelection,
+    cellSetExpansion,
+    cellSetColor,
+    theme,
+  ]);
+
+  const onBarSelect = (setNamePath, wasGrayedOut, selectOnlyEnabled = false) => {
+    if (selectOnlyEnabled) {
+      setCellSetSelection([setNamePath]);
+      return;
+    }
+    if (!wasGrayedOut) {
+      setCellSetSelection(cellSetSelection.filter(d => !isEqual(d, setNamePath)));
+    } else if (wasGrayedOut) {
+      setCellSetSelection([...cellSetSelection, setNamePath]);
+    }
+  };
+
+  return (
+    <TitleInfo
+      title={title}
+      removeGridComponent={removeGridComponent}
+      urls={urls}
+      theme={theme}
+      isReady={isReady}
+    >
+      <div ref={containerRef} className={classes.vegaContainer}>
+        <CellSetSizesPlot
+          data={data}
+          onBarSelect={onBarSelect}
+          theme={theme}
+          width={width}
+          height={height}
+          obsType={obsType}
+        />
+      </div>
+    </TitleInfo>
+  );
+}

package/src/ExpressionHistogram.js

@@ -0,0 +1,120 @@
+import React, { useState, useEffect, useCallback } from 'react';
+import { clamp, debounce } from 'lodash-es';
+import { VegaPlot, VEGA_THEMES } from '@vitessce/vega';
+
+/**
+ * We use debounce, so that onSelect is called only after the user has finished the selection.
+ * Due to vega-lite limitations, we cannot use the vega-lite signals to implement this.
+ * See this issue: https://github.com/vega/vega-lite/issues/5728
+ * See this for reference on what is supported: https://vega.github.io/vega-lite/docs/selection.html
+ */
+
+/**
+ * Gene expression histogram displayed as a bar chart,
+ * implemented with the VegaPlot component.
+ * @param {object} props
+ * @param {string[]} props.geneSelection The list of genes
+ * currently selected.
+ * @param {object[]} props.data The expression data, an array
+ * of objects with properties `value` and `gene`.
+ * @param {string} props.theme The name of the current Vitessce theme.
+ * @param {number} props.width The container width.
+ * @param {number} props.height The container height.
+ * @param {number} props.marginRight The size of the margin
+ * on the right side of the plot, to account for the vega menu button.
+ * By default, 90.
+ * @param {number} props.marginBottom The size of the margin
+ * on the bottom of the plot, to account for long x-axis labels.
+ * By default, 50.
+ */
+export default function ExpressionHistogram(props) {
+  const {
+    geneSelection,
+    data,
+    theme,
+    width,
+    height,
+    marginRight = 90,
+    marginBottom = 50,
+    onSelect,
+  } = props;
+
+  const [selectedRanges, setSelectedRanges] = useState([]);
+
+  const xTitle = geneSelection && geneSelection.length >= 1
+    ? 'Normalized Expression Value'
+    : 'Total Normalized Transcript Count';
+
+  const spec = {
+    data: { values: data },
+    mark: 'bar',
+    encoding: {
+      x: {
+        field: 'value',
+        type: 'quantitative',
+        bin: { maxbins: 50 },
+        title: xTitle,
+      },
+      y: {
+        type: 'quantitative',
+        aggregate: 'count',
+        title: 'Number of Cells',
+      },
+      color: { value: 'gray' },
+      opacity: {
+        condition: { selection: 'brush', value: 1 },
+        value: 0.7,
+      },
+    },
+    params: [
+      {
+        name: 'brush',
+        select: { type: 'interval', encodings: ['x'] },
+      },
+    ],
+    width: clamp(width - marginRight, 10, Infinity),
+    height: clamp(height - marginBottom, 10, Infinity),
+    config: VEGA_THEMES[theme],
+  };
+
+
+  const handleSignal = (name, value) => {
+    if (name === 'brush') {
+      setSelectedRanges(value.value);
+    }
+  };
+
+
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  const debouncedOnSelect = useCallback(debounce((ranges, latestOnSelect) => {
+    latestOnSelect(ranges);
+    // We set a debounce timer of 1000ms: the assumption here is that the user has
+    // finished the selection when there's been no mouse movement on the histogram for a second.
+    // We do not pass any dependencies for the useCallback
+    // since we only want to define the debounced function once (on the initial render).
+  }, 1000), []);
+
+  useEffect(() => {
+    if (!selectedRanges || selectedRanges.length === 0) return () => {};
+
+    // Call the debounced function instead of directly calling onSelect
+    debouncedOnSelect(selectedRanges, onSelect);
+
+    // Clean up the debounce timer when the component unmounts or the dependency changes
+    return () => {
+      debouncedOnSelect.cancel();
+    };
+  // We only want to call the debounced function when the selectedRanges changes.
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [selectedRanges]);
+
+  const signalListeners = { brush: handleSignal };
+
+  return (
+    <VegaPlot
+      data={data}
+      signalListeners={signalListeners}
+      spec={spec}
+    />
+  );
+}