@vitessce/statistical-plots 3.4.5 → 3.4.7

package/src/CellSetExpressionPlotSubscriber.js

@@ -10,11 +10,20 @@ import {
   useSampleEdgesData,
 } 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 { VALUE_TRANSFORM_OPTIONS, capitalize } from '@vitessce/utils';
+import {
+  treeToSetSizesBySetNames,
+  mergeObsSets,
+  stratifyExpressionData,
+  aggregateStratifiedExpressionData,
+} from '@vitessce/sets-utils';
 import CellSetExpressionPlotOptions from './CellSetExpressionPlotOptions.js';
 import CellSetExpressionPlot from './CellSetExpressionPlot.js';
 import { useStyles } from './styles.js';
+import {
+  summarizeStratifiedExpressionData,
+  histogramStratifiedExpressionData,
+} from './expr-hooks.js';
 
 /**
  * Get expression data for the cells
@@ -34,14 +43,13 @@ import { useStyles } from './styles.js';
  * 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(
+  sampleEdges, sampleSets, sampleSetSelection,
   expressionData, obsIndex, cellSets, additionalCellSets,
   geneSelection, cellSetSelection, cellSetColor,
   featureValueTransform, featureValueTransformCoefficient,
-  theme,
+  theme, yMinProp,
 ) {
   const mergedCellSets = useMemo(
     () => mergeObsSets(cellSets, additionalCellSets),
@@ -51,37 +59,29 @@ function useExpressionByCellSet(
   // 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 [stratifiedData, exprMax] = stratifyExpressionData(
+      sampleEdges, sampleSets, sampleSetSelection,
+      expressionData, obsIndex, mergedCellSets,
+      geneSelection, cellSetSelection, cellSetColor,
+      featureValueTransform, featureValueTransformCoefficient,
+    );
+    if (stratifiedData) {
+      const aggregateData = aggregateStratifiedExpressionData(
+        stratifiedData, geneSelection,
       );
-
-      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];
+      const summarizedData = summarizeStratifiedExpressionData(
+        aggregateData, true,
+      );
+      const histogramData = histogramStratifiedExpressionData(
+        summarizedData, 16, yMinProp,
+      );
+      return [histogramData, exprMax];
     }
     return [null, null];
   }, [expressionData, obsIndex, geneSelection, theme,
     mergedCellSets, cellSetSelection, cellSetColor,
     featureValueTransform, featureValueTransformCoefficient,
+    yMinProp, sampleEdges, sampleSets, sampleSetSelection,
   ]);
 
   // From the cell sets hierarchy and the list of selected cell sets,
@@ -96,7 +96,6 @@ function useExpressionByCellSet(
   return [expressionArr, setArr, expressionMax];
 }
 
-
 /**
  * A subscriber component for `CellSetExpressionPlot`,
  * which listens for gene selection updates and
@@ -135,9 +134,12 @@ export function CellSetExpressionPlotSubscriber(props) {
     obsSetColor: cellSetColor,
     additionalObsSets: additionalCellSets,
     sampleType,
+    sampleSetSelection,
+    sampleSetColor,
   }, {
     setFeatureValueTransform,
     setFeatureValueTransformCoefficient,
+    setSampleSetColor,
   }] = useCoordination(
     COMPONENT_COORDINATION_TYPES[ViewType.OBS_SET_FEATURE_VALUE_DISTRIBUTION],
     coordinationScopes,
@@ -167,13 +169,13 @@ export function CellSetExpressionPlotSubscriber(props) {
     { obsType },
   );
 
-  // eslint-disable-next-line no-unused-vars
   const [{ sampleSets }, sampleSetsStatus, sampleSetsUrls] = useSampleSetsData(
-    loaders, dataset, false, {}, {},
+    loaders, dataset, false,
+    { setSampleSetColor },
+    { sampleSetColor },
     { sampleType },
   );
 
-  // eslint-disable-next-line no-unused-vars
   const [{ sampleEdges }, sampleEdgesStatus, sampleEdgesUrls] = useSampleEdgesData(
     loaders, dataset, false, {}, {},
     { obsType, sampleType },
@@ -195,11 +197,12 @@ export function CellSetExpressionPlotSubscriber(props) {
     sampleEdgesUrls,
   ]);
 
-  const [expressionArr, setArr] = useExpressionByCellSet(
+  const [histogramData, setArr, exprMax] = useExpressionByCellSet(
+    sampleEdges, sampleSets, sampleSetSelection,
     expressionData, obsIndex, cellSets, additionalCellSets,
     geneSelection, cellSetSelection, cellSetColor,
     featureValueTransform, featureValueTransformCoefficient,
-    theme,
+    theme, yMin,
   );
 
   const firstGeneSelected = geneSelection && geneSelection.length >= 1
@@ -230,13 +233,17 @@ export function CellSetExpressionPlotSubscriber(props) {
       )}
     >
       <div ref={containerRef} className={classes.vegaContainer}>
-        {expressionArr ? (
+        {histogramData ? (
           <CellSetExpressionPlot
             yMin={yMin}
             yUnits={yUnits}
             jitter={jitter}
+            cellSetSelection={cellSetSelection}
+            sampleSetSelection={sampleSetSelection}
+            sampleSetColor={sampleSetColor}
             colors={setArr}
-            data={expressionArr}
+            data={histogramData}
+            exprMax={exprMax}
             theme={theme}
             width={width}
             height={height}

package/src/DotPlot.js

@@ -0,0 +1,175 @@
+import React from 'react';
+import { clamp } from 'lodash-es';
+import { VegaPlot, VEGA_THEMES } from '@vitessce/vega';
+import { capitalize, pluralize as plur } from '@vitessce/utils';
+
+/**
+ * Gene expression dot plot,
+ * implemented with the VegaPlot component.
+ * @param {object} props
+ * @param {object[]} props.data The expression data, an array
+ * of objects with properties `value`, `gene`, and `set`.
+ * @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.
+ * Default is allowing the component to automatically determine the margin.
+ * @param {string|null} props.featureValueTransformName A name
+ * for the feature value transformation function.
+ */
+export default function DotPlot(props) {
+  const {
+    isStratified,
+    transpose,
+    data: rawData,
+    theme,
+    width,
+    height,
+    marginRight,
+    marginBottom,
+    obsType,
+    keyLength = 36,
+    featureType,
+    featureValueType,
+    featureValueTransformName,
+    featureValueColormap,
+    cellSetSelection,
+  } = props;
+
+  // Add a property `keyGroup` and `keyFeature` which concatenates the key and the name,
+  // which is both unique and can easily be converted
+  // back to the name by taking a substring.
+  const data = rawData.map(d => ({
+    ...d,
+    keyGroup: d.groupKey + d.group,
+    keyFeature: d.featureKey + d.feature,
+    keyGroupSecondary: d.secondaryGroupKey + d.secondaryGroup,
+  }));
+
+  // Get the max characters in an axis label for autsizing the bottom margin.
+  const maxCharactersForGroup = data.reduce((acc, val) => {
+    // eslint-disable-next-line no-param-reassign
+    acc = acc === undefined || val.group?.length > acc ? val.group?.length : acc;
+    return acc;
+  }, 0);
+  const maxCharactersForFeature = data.reduce((acc, val) => {
+    // eslint-disable-next-line no-param-reassign
+    acc = acc === undefined || val.feature.length > acc ? val.feature.length : acc;
+    return acc;
+  }, 0);
+  const maxCharactersForSampleSet = isStratified ? data.reduce((acc, val) => {
+    // eslint-disable-next-line no-param-reassign
+    acc = acc === undefined || val.secondaryGroup.length > acc ? val.secondaryGroup.length : acc;
+    return acc;
+  }, 0) : 0;
+
+
+  // Use a square-root term because the angle of the labels is 45 degrees (see below)
+  // so the perpendicular distance to the bottom of the labels is proportional to the
+  // square root of the length of the labels along the imaginary hypotenuse.
+  // 30 is an estimate of the pixel size of a given character and seems to work well.
+  const autoMarginForFeature = marginBottom
+    || 30 + Math.sqrt(maxCharactersForFeature / 2) * 30;
+  const autoMarginForGroup = marginRight
+    || 30 + Math.sqrt(maxCharactersForGroup / 2) * 30;
+  const autoMarginForSampleSet = marginRight
+    || 30 + Math.sqrt(maxCharactersForSampleSet / 2) * 30;
+
+  const plotWidth = transpose
+    ? clamp(width - autoMarginForFeature - 180, 10, Infinity) / (cellSetSelection?.length || 1)
+    : clamp(width - autoMarginForGroup - autoMarginForSampleSet - 200, 10, Infinity);
+  const plotHeight = transpose
+    ? clamp((height - autoMarginForGroup - autoMarginForSampleSet - 50), 10, Infinity)
+    : clamp((height - autoMarginForFeature - 80), 10, Infinity) / (cellSetSelection?.length || 1);
+
+  // Get an array of keys for sorting purposes.
+  const groupKeys = data.map(d => d.keyGroup);
+  const featureKeys = data.map(d => d.keyFeature);
+  const groupSecondaryKeys = data.map(d => d.keyGroupSecondary);
+
+
+  const meanTransform = (featureValueTransformName && featureValueTransformName !== 'None')
+    // Mean Log-Transformed Normalized Expression
+    ? [`Mean ${featureValueTransformName}-transformed`, `normalized ${featureValueType}`, 'in set']
+    // Mean Normalized Expression
+    : ['Mean normalized', `${featureValueType} in set`];
+
+  const spec = {
+    mark: {
+      type: 'circle',
+      // The Vega-Lite default opacity is 0.7 for point, tick, circle,
+      // or square marks.
+      // Reference: https://vega.github.io/vega-lite/docs/mark.html
+      opacity: 1.0,
+    },
+    encoding: {
+      [(transpose ? 'y' : 'x')]: {
+        field: 'keyFeature',
+        type: 'nominal',
+        axis: { labelExpr: `substring(datum.label, ${keyLength})` },
+        title: capitalize(featureType),
+        sort: featureKeys,
+      },
+      [(transpose ? 'column' : 'row')]: {
+        field: 'keyGroup',
+        type: 'nominal',
+        header: transpose
+          ? { labelExpr: `substring(datum.label, ${keyLength})`, labelAngle: -60, labelAlign: 'right', titleOrient: 'bottom', labelOrient: 'bottom' }
+          : { labelExpr: `substring(datum.label, ${keyLength})`, labelAngle: 0, labelAlign: 'left' },
+        title: `${capitalize(obsType)} Set`,
+        sort: groupKeys,
+        spacing: 0,
+      },
+      color: {
+        field: 'meanExpInGroup',
+        type: 'quantitative',
+        title: meanTransform,
+        scale: {
+          scheme: featureValueColormap,
+        },
+        legend: {
+          direction: 'horizontal',
+          tickCount: 2,
+        },
+      },
+      [(transpose ? 'x' : 'y')]: {
+        field: 'keyGroupSecondary',
+        type: 'nominal',
+        axis: { labelExpr: `substring(datum.label, ${keyLength})` },
+        title: null, // TODO: use sampleType
+        sort: groupSecondaryKeys,
+      },
+      size: {
+        field: 'pctPosInGroup',
+        type: 'quantitative',
+        title: [`Percentage of ${plur(obsType, 2)}`, 'in set'],
+        legend: {
+          symbolFillColor: 'white',
+        },
+      },
+    },
+    width: plotWidth,
+    height: plotHeight,
+    config: {
+      ...VEGA_THEMES[theme],
+      ...(!isStratified ? {
+        // Remove the row/column outlines when
+        // not stratified by sample set.
+        view: {
+          stroke: 'transparent',
+        },
+      } : {}),
+    },
+  };
+
+  return (
+    <VegaPlot
+      data={data}
+      spec={spec}
+    />
+  );
+}

package/src/DotPlotSubscriber.js

@@ -0,0 +1,173 @@
+import React from 'react';
+import {
+  TitleInfo,
+  useCoordination, useLoaders,
+  useUrls, useReady, useGridItemSize,
+  useFeatureSelection, useObsSetsData,
+  useObsFeatureMatrixIndices,
+  useFeatureLabelsData,
+  useSampleSetsData,
+  useSampleEdgesData,
+} from '@vitessce/vit-s';
+import { ViewType, COMPONENT_COORDINATION_TYPES } from '@vitessce/constants-internal';
+import { VALUE_TRANSFORM_OPTIONS } from '@vitessce/utils';
+import CellSetExpressionPlotOptions from './CellSetExpressionPlotOptions.js';
+import DotPlot from './DotPlot.js';
+import { useStyles } from './styles.js';
+import { useExpressionSummaries } from './dot-plot-hook.js';
+
+
+/**
+ * A subscriber component for DotPlot.
+ * @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 DotPlotSubscriber(props) {
+  const {
+    coordinationScopes,
+    removeGridComponent,
+    theme,
+    title = 'Dot Plot',
+    transpose = true,
+  } = props;
+
+  const classes = useStyles();
+  const loaders = useLoaders();
+
+  // Get "props" from the coordination space.
+  const [{
+    dataset,
+    obsType,
+    featureType,
+    featureValueType,
+    featureSelection: geneSelection,
+    featureValueTransform,
+    featureValueTransformCoefficient,
+    featureValuePositivityThreshold: posThreshold,
+    featureValueColormap,
+    obsSetSelection: cellSetSelection,
+    obsSetColor: cellSetColor,
+    additionalObsSets: additionalCellSets,
+    sampleType,
+    sampleSetSelection,
+  }, {
+    setFeatureValueTransform,
+    setFeatureValueTransformCoefficient,
+    setFeatureValuePositivityThreshold: setPosThreshold,
+    setFeatureValueColormap,
+  }] = useCoordination(
+    COMPONENT_COORDINATION_TYPES[ViewType.DOT_PLOT],
+    coordinationScopes,
+  );
+
+  const [width, height, containerRef] = useGridItemSize();
+
+  const transformOptions = VALUE_TRANSFORM_OPTIONS;
+  const isStratified = Array.isArray(sampleSetSelection) && sampleSetSelection.length > 1;
+
+  // 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, featureLabelsUrl] = useFeatureLabelsData(
+    loaders, dataset, false, {}, {},
+    { featureType },
+  );
+  const [{ obsIndex }, matrixIndicesStatus, matrixIndicesUrl] = useObsFeatureMatrixIndices(
+    loaders, dataset, false,
+    { obsType, featureType, featureValueType },
+  );
+  const [{ obsSets: cellSets }, obsSetsStatus, obsSetsUrl] = useObsSetsData(
+    loaders, dataset, true, {}, {},
+    { obsType },
+  );
+
+  const [{ sampleSets }, sampleSetsStatus, sampleSetsUrl] = useSampleSetsData(
+    loaders, dataset, false, {}, {},
+    { sampleType },
+  );
+
+  const [{ sampleEdges }, sampleEdgesStatus, sampleEdgesUrl] = useSampleEdgesData(
+    loaders, dataset, false, {}, {},
+    { obsType, sampleType },
+  );
+
+  const isReady = useReady([
+    featureSelectionStatus,
+    matrixIndicesStatus,
+    obsSetsStatus,
+    featureLabelsStatus,
+    sampleSetsStatus,
+    sampleEdgesStatus,
+  ]);
+  const urls = useUrls([
+    featureLabelsUrl,
+    matrixIndicesUrl,
+    obsSetsUrl,
+    sampleSetsUrl,
+    sampleEdgesUrl,
+  ]);
+
+  const [resultArr, meanExpressionMax] = useExpressionSummaries(
+    sampleEdges, sampleSets, sampleSetSelection,
+    expressionData, obsIndex, cellSets, additionalCellSets,
+    geneSelection, cellSetSelection, cellSetColor,
+    featureValueTransform, featureValueTransformCoefficient,
+    posThreshold, featureLabelsMap,
+
+  );
+  const selectedTransformName = transformOptions.find(
+    o => o.value === featureValueTransform,
+  )?.name;
+
+  return (
+    <TitleInfo
+      title={title}
+      removeGridComponent={removeGridComponent}
+      urls={urls}
+      theme={theme}
+      isReady={isReady}
+      options={(
+        <CellSetExpressionPlotOptions
+          featureValueTransform={featureValueTransform}
+          setFeatureValueTransform={setFeatureValueTransform}
+          featureValueTransformCoefficient={featureValueTransformCoefficient}
+          setFeatureValueTransformCoefficient={setFeatureValueTransformCoefficient}
+          transformOptions={transformOptions}
+          featureValuePositivityThreshold={posThreshold}
+          setFeatureValuePositivityThreshold={setPosThreshold}
+          featureValueColormap={featureValueColormap}
+          setFeatureValueColormap={setFeatureValueColormap}
+        />
+      )}
+    >
+      <div ref={containerRef} className={classes.vegaContainer}>
+        {resultArr ? (
+          <DotPlot
+            isStratified={isStratified}
+            transpose={transpose}
+            domainMax={meanExpressionMax}
+            data={resultArr}
+            theme={theme}
+            width={width}
+            height={height}
+            obsType={obsType}
+            featureType={featureType}
+            featureValueType={featureValueType}
+            featureValueTransformName={selectedTransformName}
+            featureValueColormap={featureValueColormap}
+            cellSetSelection={cellSetSelection}
+          />
+        ) : (
+          <span>Select at least one {featureType}.</span>
+        )}
+      </div>
+    </TitleInfo>
+  );
+}

package/src/dot-plot-hook.js

@@ -0,0 +1,107 @@
+
+import { useMemo } from 'react';
+import { InternMap } from 'internmap';
+import { v4 as uuidv4 } from 'uuid';
+import {
+  mergeObsSets,
+  stratifyExpressionData,
+} from '@vitessce/sets-utils';
+import {
+  dotStratifiedExpressionData,
+} from './expr-hooks.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`.
+ */
+export function useExpressionSummaries(
+  sampleEdges, sampleSets, sampleSetSelection,
+  expressionData, obsIndex, cellSets, additionalCellSets,
+  geneSelection, cellSetSelection, cellSetColor,
+  featureValueTransform, featureValueTransformCoefficient,
+  posThreshold, featureLabelsMap,
+) {
+  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 [resultArr, meanExpressionMax] = useMemo(() => {
+    const [stratifiedData, exprMax] = stratifyExpressionData(
+      sampleEdges, sampleSets, sampleSetSelection,
+      expressionData, obsIndex, mergedCellSets,
+      geneSelection, cellSetSelection, cellSetColor,
+      featureValueTransform, featureValueTransformCoefficient,
+    );
+    if (stratifiedData) {
+      const dotData = dotStratifiedExpressionData(
+        stratifiedData, posThreshold,
+      );
+
+      const geneToUuid = new Map(geneSelection?.map(gene => [gene, uuidv4()]));
+      const cellSetToUuid = new InternMap(
+        cellSetSelection?.map(sampleSet => ([sampleSet, uuidv4()])),
+        JSON.stringify,
+      );
+      const sampleSetToUuid = new InternMap(
+        sampleSetSelection?.map(sampleSet => ([sampleSet, uuidv4()])),
+        JSON.stringify,
+      );
+
+      const result = [];
+      ([...dotData.keys()]).forEach((cellSetKey) => {
+        ([...dotData.get(cellSetKey).keys()]).forEach((sampleSetKey) => {
+          ([...dotData.get(cellSetKey).get(sampleSetKey).keys()]).forEach((geneKey) => {
+            const dotObj = dotData.get(cellSetKey).get(sampleSetKey).get(geneKey);
+            const featureName = geneKey;
+            result.push({
+              key: uuidv4(), // Unique key for this dot.
+
+              featureKey: geneToUuid.get(geneKey),
+              feature: featureLabelsMap?.get(featureName) || featureName,
+
+              groupKey: cellSetToUuid.get(cellSetKey),
+              group: cellSetKey?.at(-1),
+
+              secondaryGroup: sampleSetKey?.at(-1),
+              secondaryGroupKey: sampleSetToUuid.get(sampleSetKey),
+
+              meanExpInGroup: dotObj.meanExpInGroup,
+              fracPosInGroup: dotObj.fracPosInGroup,
+              pctPosInGroup: dotObj.fracPosInGroup * 100.0,
+            });
+          });
+        });
+      });
+
+      return [result, exprMax];
+    }
+    return [null, null];
+  }, [expressionData, obsIndex, geneSelection,
+    mergedCellSets, cellSetSelection,
+    featureValueTransform, featureValueTransformCoefficient,
+    posThreshold, featureLabelsMap,
+    sampleEdges, sampleSets, sampleSetSelection,
+  ]);
+
+  return [resultArr, meanExpressionMax];
+}