@vitessce/statistical-plots 2.0.2 → 2.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vitessce/statistical-plots",
-  "version": "2.0.2",
+  "version": "2.0.3",
   "author": "Gehlenborg Lab",
   "homepage": "http://vitessce.io",
   "repository": {
@@ -8,19 +8,20 @@
     "url": "git+https://github.com/vitessce/vitessce.git"
   },
   "license": "MIT",
-  "main": "dist/index.js",
+  "main": "dist/index.mjs",
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "dependencies": {
     "@material-ui/core": "~4.12.3",
     "d3-array": "^2.4.0",
     "lodash": "^4.17.21",
-    "@vitessce/constants-internal": "2.0.2",
-    "@vitessce/sets-utils": "2.0.2",
-    "@vitessce/utils": "2.0.2",
-    "@vitessce/vega": "2.0.2",
-    "@vitessce/vit-s": "2.0.2"
+    "@vitessce/constants-internal": "2.0.3",
+    "@vitessce/sets-utils": "2.0.3",
+    "@vitessce/utils": "2.0.3",
+    "@vitessce/vega": "2.0.3",
+    "@vitessce/vit-s": "2.0.3"
   },
   "devDependencies": {
     "react": "^18.0.0",
@@ -31,8 +32,7 @@
     "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 ."
   }
 }

package/src/CellSetExpressionPlot.js

@@ -0,0 +1,278 @@
+import React from 'react';
+import clamp from 'lodash/clamp';
+import { VegaPlot, VEGA_THEMES, DATASET_NAME } from '@vitessce/vega';
+import { colorArrayToString } from '@vitessce/sets-utils';
+import { capitalize } from '@vitessce/utils';
+
+/**
+ * Gene expression histogram displayed as a bar chart,
+ * 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 {number} props.domainMax The maximum gene expression value.
+ * @param {object[]} props.colors An object for each
+ * cell set, with properties `name` and `color`.
+ * @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 CellSetExpressionPlot(props) {
+  const {
+    domainMax = 100,
+    colors,
+    data,
+    theme,
+    width,
+    height,
+    marginRight = 90,
+    marginBottom,
+    obsType,
+    featureValueType,
+    featureValueTransformName,
+  } = props;
+  // Get the max characters in an axis label for autsizing the bottom margin.
+  const maxCharactersForLabel = data.reduce((acc, val) => {
+    // eslint-disable-next-line no-param-reassign
+    acc = acc === undefined || val.set.length > acc ? val.set.length : acc;
+    return acc;
+  }, 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 autoMarginBottom = marginBottom
+    || 30 + Math.sqrt(maxCharactersForLabel / 2) * 30;
+  // Manually set the color scale so that Vega-Lite does
+  // not choose the colors automatically.
+  const colorScale = {
+    domain: colors.map(d => d.name),
+    range: colors.map(d => colorArrayToString(d.color)),
+  };
+
+  const plotWidth = clamp(width - marginRight, 10, Infinity);
+  const plotHeight = clamp(height - autoMarginBottom, 10, Infinity);
+
+  const numBands = colors.length;
+  const bandWidth = plotWidth / numBands;
+
+  const rectColor = (theme === 'dark' ? 'white' : 'black');
+
+  const spec = {
+    $schema: 'https://vega.github.io/schema/vega/v5.json',
+    description: `A violin plot showing distributions of expression levels for selected ${obsType} sets.`,
+    width: plotWidth,
+    height: plotHeight,
+    config: {
+      ...VEGA_THEMES[theme],
+      axisBand: {
+        bandPosition: 1,
+        tickExtra: true,
+        tickOffset: 0,
+      },
+    },
+
+    signals: [
+      { name: 'bandWidth', value: bandWidth },
+      { name: 'width', value: plotWidth },
+      { name: 'height', value: plotHeight },
+      { name: 'trim', value: true },
+    ],
+
+    data: [
+      {
+        name: 'density',
+        source: DATASET_NAME,
+        transform: [
+          {
+            type: 'kde',
+            field: 'value',
+            groupby: ['set'],
+            bandwidth: 0,
+            extent: [0, domainMax],
+          },
+        ],
+      },
+      {
+        name: 'stats',
+        source: DATASET_NAME,
+        transform: [
+          {
+            type: 'aggregate',
+            groupby: ['set'],
+            fields: ['value', 'value', 'value'],
+            ops: ['q1', 'median', 'q3'],
+            as: ['q1', 'median', 'q3'],
+          },
+        ],
+      },
+    ],
+
+    scales: [
+      {
+        name: 'layout',
+        type: 'band',
+        range: 'width',
+        domain: { data: DATASET_NAME, field: 'set' },
+      },
+      {
+        name: 'yscale',
+        type: 'linear',
+        range: 'height',
+        domain: [0, domainMax],
+      },
+      {
+        name: 'wscale',
+        type: 'linear',
+        range: [0, { signal: 'bandWidth' }],
+        domain: { data: 'density', field: 'density' },
+      },
+      {
+        name: 'wscaleReversed',
+        type: 'linear',
+        reverse: true,
+        range: [0, { signal: 'bandWidth' }],
+        domain: { data: 'density', field: 'density' },
+      },
+      {
+        name: 'color',
+        type: 'ordinal',
+        ...colorScale,
+      },
+    ],
+
+    axes: [
+      {
+        orient: 'left',
+        scale: 'yscale',
+        zindex: 1,
+        title: (featureValueTransformName && featureValueTransformName !== 'None')
+          ? [`${featureValueTransformName}-Transformed`, `Normalized ${capitalize(featureValueType)} Values`]
+          : `Normalized ${capitalize(featureValueType)} Values`,
+      },
+      {
+        orient: 'bottom',
+        scale: 'layout',
+        tickCount: 5,
+        zindex: 1,
+        title: `${capitalize(obsType)} Set`,
+        labelAngle: -45,
+        labelAlign: 'right',
+      },
+    ],
+
+    marks: [
+      {
+        type: 'group',
+        from: {
+          facet: {
+            data: 'density',
+            name: 'violin',
+            groupby: 'set',
+          },
+        },
+
+        encode: {
+          enter: {
+            xc: { scale: 'layout', field: 'set', band: 0.5 },
+            width: { signal: 'bandWidth' },
+            height: { signal: 'height' },
+          },
+        },
+
+        data: [
+          {
+            name: 'summary',
+            source: 'stats',
+            transform: [
+              {
+                type: 'filter',
+                expr: 'datum.set === parent.set',
+              },
+            ],
+          },
+        ],
+
+        marks: [
+          {
+            type: 'area',
+            orient: 'vertical',
+            from: { data: 'violin' },
+            encode: {
+              enter: {
+                fill: { scale: 'color', field: { parent: 'set' } },
+              },
+              update: {
+                width: { scale: 'wscale', field: 'density' },
+                xc: { signal: 'bandWidth / 2' },
+                y2: { scale: 'yscale', field: 'value' },
+                y: { scale: 'yscale', value: 0 },
+              },
+            },
+          },
+          {
+            type: 'area',
+            orient: 'vertical',
+            from: { data: 'violin' },
+            encode: {
+              enter: {
+                fill: { scale: 'color', field: { parent: 'set' } },
+              },
+              update: {
+                width: { scale: 'wscaleReversed', field: 'density' },
+                xc: { signal: 'bandWidth' },
+                y2: { scale: 'yscale', field: 'value' },
+                y: { scale: 'yscale', value: 0 },
+              },
+            },
+          },
+          {
+            type: 'rect',
+            from: { data: 'summary' },
+            encode: {
+              enter: {
+                fill: { value: rectColor },
+                width: { value: 2 },
+              },
+              update: {
+                y: { scale: 'yscale', field: 'q1' },
+                y2: { scale: 'yscale', field: 'q3' },
+                xc: { signal: 'bandWidth / 2' },
+              },
+            },
+          },
+          {
+            type: 'rect',
+            from: { data: 'summary' },
+            encode: {
+              enter: {
+                fill: { value: rectColor },
+                height: { value: 2 },
+                width: { value: 8 },
+              },
+              update: {
+                y: { scale: 'yscale', field: 'median' },
+                xc: { signal: 'bandWidth / 2' },
+              },
+            },
+          },
+        ],
+      },
+    ],
+  };
+
+  return (
+    <VegaPlot
+      data={data}
+      spec={spec}
+    />
+  );
+}

package/src/CellSetExpressionPlotOptions.js

@@ -0,0 +1,75 @@
+import React from 'react';
+import TableCell from '@material-ui/core/TableCell';
+import TableRow from '@material-ui/core/TableRow';
+import TextField from '@material-ui/core/TextField';
+import { usePlotOptionsStyles, OptionsContainer, OptionSelect } from '@vitessce/vit-s';
+
+export default function CellSetExpressionPlotOptions(props) {
+  const {
+    featureValueTransform,
+    setFeatureValueTransform,
+    featureValueTransformCoefficient,
+    setFeatureValueTransformCoefficient,
+    transformOptions,
+  } = props;
+  const classes = usePlotOptionsStyles();
+
+  const handleTransformChange = (event) => {
+    setFeatureValueTransform(event.target.value === '' ? null : event.target.value);
+  };
+
+  // Feels a little hacky, but I think this is the best way to handle
+  // the limitations of the v4 material-ui number input.
+  const handleTransformCoefficientChange = (event) => {
+    const { value } = event.target;
+    if (!value) {
+      setFeatureValueTransformCoefficient(value);
+    } else {
+      const newCoefficient = Number(value);
+      if (!Number.isNaN(newCoefficient) && newCoefficient >= 0) {
+        setFeatureValueTransformCoefficient(value);
+      }
+    }
+  };
+
+  return (
+    <OptionsContainer>
+      <TableRow>
+        <TableCell className={classes.labelCell}>Transform</TableCell>
+        <TableCell className={classes.inputCell}>
+          <OptionSelect
+            key="gating-transform-select"
+            className={classes.select}
+            value={featureValueTransform === null ? '' : featureValueTransform}
+            onChange={handleTransformChange}
+            inputProps={{
+              id: 'scatterplot-transform-select',
+            }}
+          >
+            {transformOptions.map(opt => (
+              <option key={opt.name} value={opt.value === null ? '' : opt.value}>
+                {opt.name}
+              </option>
+            ))}
+          </OptionSelect>
+        </TableCell>
+      </TableRow>
+      <TableRow key="transform-coefficient-option-row">
+        <TableCell className={classes.labelCell}>
+          Transform Coefficient
+        </TableCell>
+        <TableCell className={classes.inputCell}>
+          <TextField
+            label="Number"
+            type="number"
+            onChange={handleTransformCoefficientChange}
+            value={featureValueTransformCoefficient}
+            InputLabelProps={{
+              shrink: true,
+            }}
+          />
+        </TableCell>
+      </TableRow>
+    </OptionsContainer>
+  );
+}

package/src/CellSetExpressionPlotSubscriber.js

@@ -0,0 +1,228 @@
+import React, { useMemo } from 'react';
+import {
+  TitleInfo,
+  useCoordination, useLoaders,
+  useUrls, useReady, useGridItemSize,
+  useFeatureSelection, useObsSetsData,
+  useObsFeatureMatrixIndices,
+  useFeatureLabelsData,
+  registerPluginViewType,
+} 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';
+import CellSetExpressionPlot from './CellSetExpressionPlot';
+import { useStyles } from './styles';
+
+/**
+ * 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 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 normValue = value * 100 / 255;
+        const transformFunction = getValueTransformFunction(
+          featureValueTransform, featureValueTransformCoefficient,
+        );
+        const transformedValue = transformFunction(normValue);
+        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, 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>
+  );
+}
+
+export function register() {
+  registerPluginViewType(
+    ViewType.OBS_SET_FEATURE_VALUE_DISTRIBUTION,
+    CellSetExpressionPlotSubscriber,
+    COMPONENT_COORDINATION_TYPES[ViewType.OBS_SET_FEATURE_VALUE_DISTRIBUTION],
+  );
+}