@vitessce/statistical-plots 3.4.5 → 3.4.7

package/src/expr-hooks.js

@@ -0,0 +1,170 @@
+/* eslint-disable camelcase */
+import { InternMap } from 'internmap';
+import { scaleLinear } from 'd3-scale';
+import {
+  bin,
+  min,
+  max,
+  mean as d3_mean,
+  deviation as d3_deviation,
+  ascending as d3_ascending,
+  quantileSorted,
+} from 'd3-array';
+
+// Reference: https://github.com/d3/d3-array/issues/180#issuecomment-851378012
+function summarize(iterable, keepZeros) {
+  const values = iterable
+    .filter(d => keepZeros || d !== 0.0)
+    .sort(d3_ascending);
+  const minVal = values[0];
+  const maxVal = values[values.length - 1];
+  const q1 = quantileSorted(values, 0.25);
+  const q2 = quantileSorted(values, 0.5);
+  const q3 = quantileSorted(values, 0.75);
+  const iqr = q3 - q1; // interquartile range
+  const r0 = Math.max(minVal, q1 - iqr * 1.5);
+  const r1 = Math.min(maxVal, q3 + iqr * 1.5);
+  let i = -1;
+  while (values[++i] < r0);
+  const w0 = values[i];
+  while (values[++i] <= r1);
+  const w1 = values[i - 1];
+
+  // Chauvenet
+  // Reference: https://en.wikipedia.org/wiki/Chauvenet%27s_criterion
+  const mean = d3_mean(values);
+  const stdv = d3_deviation(values);
+  const c0 = mean - 3 * stdv;
+  const c1 = mean + 3 * stdv;
+
+  return {
+    quartiles: [q1, q2, q3],
+    range: [r0, r1],
+    whiskers: [w0, w1],
+    chauvenetRange: [c0, c1],
+    nonOutliers: values.filter(v => c0 <= v && v <= c1),
+  };
+}
+
+/**
+ * Supports three-level stratified input
+ * (cell set, sample set, gene).
+ * @param {*} stratifiedResult
+ * @param {*} posThreshold
+ * @returns
+ */
+export function dotStratifiedExpressionData(
+  stratifiedResult, posThreshold,
+) {
+  const result = new InternMap([], JSON.stringify);
+  ([...stratifiedResult.keys()]).forEach((cellSetKey) => {
+    result.set(cellSetKey, new InternMap([], JSON.stringify));
+    ([...stratifiedResult.get(cellSetKey).keys()]).forEach((sampleSetKey) => {
+      result.get(cellSetKey).set(sampleSetKey, new InternMap([], JSON.stringify));
+
+      const allGenes = stratifiedResult.get(cellSetKey).get(sampleSetKey);
+
+      ([...allGenes.keys()]).forEach((geneKey) => {
+        const values = allGenes.get(geneKey);
+
+        const exprMean = d3_mean(values);
+        const numPos = values.reduce((acc, val) => (val > posThreshold ? acc + 1 : acc), 0);
+        const fracPos = numPos / values.length;
+
+        const dotSummary = {
+          meanExpInGroup: exprMean,
+          fracPosInGroup: fracPos,
+        };
+
+        result.get(cellSetKey).get(sampleSetKey).set(geneKey, dotSummary);
+      });
+    });
+  });
+  return result;
+}
+
+/**
+ * Supports two-level stratified input
+ * (cell set, sample set).
+ * @param {*} stratifiedResult
+ * @param {*} keepZeros
+ * @returns
+ */
+export function summarizeStratifiedExpressionData(
+  stratifiedResult, keepZeros,
+) {
+  const summarizedResult = new InternMap([], JSON.stringify);
+
+  ([...stratifiedResult.keys()]).forEach((cellSetKey) => {
+    summarizedResult.set(cellSetKey, new InternMap([], JSON.stringify));
+    ([...stratifiedResult.get(cellSetKey).keys()]).forEach((sampleSetKey) => {
+      const values = stratifiedResult.get(cellSetKey).get(sampleSetKey);
+      const summary = summarize(values, keepZeros);
+      summarizedResult.get(cellSetKey).set(sampleSetKey, summary);
+    });
+  });
+
+  return summarizedResult;
+}
+
+/**
+ * Supports two-level summarized input
+ * (cell set, sample set),
+ * the output from summarizeStratifiedExpressionData.
+ * @param {*} summarizedResult
+ * @param {*} binCount
+ * @param {*} yMinProp
+ * @returns
+ */
+export function histogramStratifiedExpressionData(
+  summarizedResult, binCount, yMinProp,
+) {
+  const groupSummaries = ([...summarizedResult.keys()]).map(cellSetKey => ({
+    key: cellSetKey,
+    value: ([...summarizedResult.get(cellSetKey).keys()]).map(sampleSetKey => ({
+      key: sampleSetKey,
+      value: summarizedResult.get(cellSetKey).get(sampleSetKey),
+    })),
+  }));
+
+  const groupData = groupSummaries
+    .map(({ key, value }) => ({
+      key,
+      value: value.map(({ key: subKey, value: subValue }) => (
+        { key: subKey, value: subValue.nonOutliers }
+      )),
+    }));
+  const trimmedData = groupData.map(kv => kv.value.map(subKv => subKv.value).flat()).flat();
+
+  const yMin = (yMinProp === null ? Math.min(0, min(trimmedData)) : yMinProp);
+
+  // For the y domain, use the yMin prop
+  // to support a use case such as 'Aspect Ratio',
+  // where the domain minimum should be 1 rather than 0.
+  const y = scaleLinear()
+    .domain([yMin, max(trimmedData)]);
+
+  const histogram = bin()
+    .thresholds(y.ticks(binCount))
+    .domain(y.domain());
+
+  const groupBins = groupData.map(kv => ({ key: kv.key,
+    value: kv.value.map(subKv => (
+      { key: subKv.key, value: histogram(subKv.value) }
+    )) }));
+  const groupBinsMax = max(groupBins
+    .flatMap(d => d.value.flatMap(subKv => subKv.value.map(v => v.length))));
+
+  return {
+    // Array of [{ key, value: [
+    //   { key, value: {
+    //      quartiles, range, whiskers, chauvenetRange, nonOutliers }
+    //   }
+    // ] }]
+    groupSummaries,
+    groupData, // Array of [{ key, value: [{ key, value: nonOutliers }] }]
+    groupBins, // Array of [{ key, value: [{ key, value: histogram(nonOutliers) }] }]
+    groupBinsMax, // Number
+    y, // d3.scaleLinear without a range set
+  };
+}

package/src/expr-hooks.test.js

@@ -0,0 +1,116 @@
+import { describe, it, expect } from 'vitest';
+import {
+  stratifyExpressionData,
+  aggregateStratifiedExpressionData,
+} from '@vitessce/sets-utils';
+import {
+  summarizeStratifiedExpressionData,
+  histogramStratifiedExpressionData,
+} from './expr-hooks.js';
+
+describe('Utility functions for processing expression data for statistical plots', () => {
+  describe('summarizeStratifiedExpressionData function', () => {
+    it('computes summarized information accurately', () => {
+      const sampleEdges = new Map([
+        ['cell1-1', 'donor1'],
+        ['cell1-2', 'donor1'],
+        ['cell1-3', 'donor1'],
+        ['cell1-4', 'donor1'],
+
+        ['cell2-1', 'donor2'],
+        ['cell2-2', 'donor2'],
+        ['cell2-3', 'donor2'],
+        ['cell2-4', 'donor2'],
+      ]);
+      const sampleSets = {
+        tree: [
+          {
+            name: 'Clinical groups',
+            children: [
+              {
+                name: 'AKI',
+                set: [['donor1', null]],
+              },
+              {
+                name: 'CKD',
+                set: [['donor2', null]],
+              },
+            ],
+          },
+        ],
+      };
+      const sampleSetSelection = [
+        ['Clinical groups', 'AKI'],
+        ['Clinical groups', 'CKD'],
+      ];
+      const expressionData = [
+        // Gene 1
+        [10, 20, 30, 40, 11, 21, 31, 41],
+      ];
+      const obsIndex = ['cell1-1', 'cell1-2', 'cell1-3', 'cell1-4', 'cell2-1', 'cell2-2', 'cell2-3', 'cell2-4'];
+      const mergedCellSets = {
+        tree: [
+          {
+            name: 'Cell type',
+            children: [
+              {
+                name: 'T cell',
+                set: [['cell1-1', null], ['cell1-3', null], ['cell2-1', null], ['cell2-3', null]],
+              },
+              {
+                name: 'B cell',
+                set: [['cell1-2', null], ['cell1-4', null], ['cell2-2', null], ['cell2-4', null]],
+              },
+            ],
+          },
+        ],
+      };
+      const geneSelection = [
+        'Gene 1',
+      ];
+      const cellSetSelection = [
+        ['Cell type', 'T cell'],
+        ['Cell type', 'B cell'],
+      ];
+      const cellSetColor = [
+        { set: ['Cell type', 'T cell'], color: [255, 0, 0] },
+        { set: ['Cell type', 'B cell'], color: [0, 255, 0] },
+      ];
+      const featureValueTransform = null;
+      const featureValueTransformCoefficient = 1;
+
+      const [result] = stratifyExpressionData(
+        sampleEdges, sampleSets, sampleSetSelection,
+        expressionData, obsIndex, mergedCellSets,
+        geneSelection, cellSetSelection, cellSetColor,
+        featureValueTransform, featureValueTransformCoefficient,
+      );
+      const aggregateData = aggregateStratifiedExpressionData(
+        result, geneSelection,
+      );
+      const summaryResult = summarizeStratifiedExpressionData(aggregateData, true);
+
+      expect([...summaryResult.keys()]).toEqual([['Cell type', 'T cell'], ['Cell type', 'B cell']]);
+      expect([...summaryResult.get(['Cell type', 'T cell']).keys()]).toEqual([['Clinical groups', 'AKI'], ['Clinical groups', 'CKD']]);
+      expect(Object.keys(summaryResult.get(['Cell type', 'T cell']).get(['Clinical groups', 'AKI']))).toEqual([
+        'quartiles',
+        'range',
+        'whiskers',
+        'chauvenetRange',
+        'nonOutliers',
+      ]);
+
+      const histogramResult = histogramStratifiedExpressionData(summaryResult, 16, null);
+
+      expect(Object.keys(histogramResult)).toEqual([
+        'groupSummaries',
+        'groupData',
+        'groupBins',
+        'groupBinsMax',
+        'y',
+      ]);
+      expect(histogramResult.groupSummaries.map(d => d.key)).toEqual([['Cell type', 'T cell'], ['Cell type', 'B cell']]);
+      expect(histogramResult.groupBinsMax).toEqual(1);
+    });
+  });
+});

package/src/index.js

@@ -1,7 +1,9 @@
 export { CellSetExpressionPlotSubscriber } from './CellSetExpressionPlotSubscriber.js';
 export { CellSetSizesPlotSubscriber } from './CellSetSizesPlotSubscriber.js';
 export { ExpressionHistogramSubscriber } from './ExpressionHistogramSubscriber.js';
+export { DotPlotSubscriber } from './DotPlotSubscriber.js';
 export { FeatureBarPlotSubscriber } from './FeatureBarPlotSubscriber.js';
 export { default as CellSetSizesPlot } from './CellSetSizesPlot.js';
 export { default as CellSetExpressionPlot } from './CellSetExpressionPlot.js';
 export { default as ExpressionHistogram } from './ExpressionHistogram.js';
+export { default as DotPlot } from './DotPlot.js';