@vitessce/statistical-plots 3.4.6 → 3.4.7

package/dist-tsc/DotPlot.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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: {
+    data: object[];
+    theme: string;
+    width: number;
+    height: number;
+    marginRight: number;
+    marginBottom: number;
+    featureValueTransformName: string | null;
+}): JSX.Element;
+//# sourceMappingURL=DotPlot.d.ts.map

package/dist-tsc/DotPlot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DotPlot.d.ts","sourceRoot":"","sources":["../src/DotPlot.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;GAiBG;AACH,uCAdG;IAAwB,IAAI,EAApB,MAAM,EAAE;IAEM,KAAK,EAAnB,MAAM;IACQ,KAAK,EAAnB,MAAM;IACQ,MAAM,EAApB,MAAM;IACQ,WAAW,EAAzB,MAAM;IAGQ,YAAY,EAA1B,MAAM;IAGa,yBAAyB,EAA5C,MAAM,GAAC,IAAI;CAErB,eAwJA"}

package/dist-tsc/DotPlot.js

@@ -0,0 +1,144 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+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 (_jsx(VegaPlot, { data: data, spec: spec }));
+}

package/dist-tsc/DotPlotSubscriber.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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: {
+    removeGridComponent: Function;
+    coordinationScopes: object;
+    theme: string;
+}): JSX.Element;
+//# sourceMappingURL=DotPlotSubscriber.d.ts.map

package/dist-tsc/DotPlotSubscriber.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DotPlotSubscriber.d.ts","sourceRoot":"","sources":["../src/DotPlotSubscriber.js"],"names":[],"mappings":"AAmBA;;;;;;;GAOG;AACH,yCALG;IAAwB,mBAAmB;IACrB,kBAAkB,EAAhC,MAAM;IAEQ,KAAK,EAAnB,MAAM;CAChB,eAkJA"}

package/dist-tsc/DotPlotSubscriber.js

@@ -0,0 +1,54 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+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 (_jsx(TitleInfo, { title: title, removeGridComponent: removeGridComponent, urls: urls, theme: theme, isReady: isReady, options: (_jsx(CellSetExpressionPlotOptions, { featureValueTransform: featureValueTransform, setFeatureValueTransform: setFeatureValueTransform, featureValueTransformCoefficient: featureValueTransformCoefficient, setFeatureValueTransformCoefficient: setFeatureValueTransformCoefficient, transformOptions: transformOptions, featureValuePositivityThreshold: posThreshold, setFeatureValuePositivityThreshold: setPosThreshold, featureValueColormap: featureValueColormap, setFeatureValueColormap: setFeatureValueColormap })), children: _jsx("div", { ref: containerRef, className: classes.vegaContainer, children: resultArr ? (_jsx(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 })) : (_jsxs("span", { children: ["Select at least one ", featureType, "."] })) }) }));
+}

package/dist-tsc/ExpressionHistogram.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ExpressionHistogram.d.ts","sourceRoot":"","sources":["../src/ExpressionHistogram.js"],"names":[],"mappings":"AAKA;;;;;GAKG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH;IAd2B,aAAa,EAA7B,MAAM,EAAE;IAEQ,IAAI,EAApB,MAAM,EAAE;IAEM,KAAK,EAAnB,MAAM;IACQ,KAAK,EAAnB,MAAM;IACQ,MAAM,EAApB,MAAM;IACQ,WAAW,EAAzB,MAAM;IAGQ,YAAY,EAA1B,MAAM;gBAqGhB"}
+{"version":3,"file":"ExpressionHistogram.d.ts","sourceRoot":"","sources":["../src/ExpressionHistogram.js"],"names":[],"mappings":"AAKA;;;;;GAKG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,mDAdG;IAAwB,aAAa,EAA7B,MAAM,EAAE;IAEQ,IAAI,EAApB,MAAM,EAAE;IAEM,KAAK,EAAnB,MAAM;IACQ,KAAK,EAAnB,MAAM;IACQ,MAAM,EAApB,MAAM;IACQ,WAAW,EAAzB,MAAM;IAGQ,YAAY,EAA1B,MAAM;CAGhB,eAkGA"}

package/dist-tsc/ExpressionHistogramSubscriber.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ExpressionHistogramSubscriber.d.ts","sourceRoot":"","sources":["../src/ExpressionHistogramSubscriber.js"],"names":[],"mappings":"AAcA;;;;;;;;;GASG;AACH;IAL2B,mBAAmB;IACrB,kBAAkB,EAAhC,MAAM;IAEQ,KAAK,EAAnB,MAAM;gBA2HhB"}
+{"version":3,"file":"ExpressionHistogramSubscriber.d.ts","sourceRoot":"","sources":["../src/ExpressionHistogramSubscriber.js"],"names":[],"mappings":"AAcA;;;;;;;;;GASG;AACH,qDALG;IAAwB,mBAAmB;IACrB,kBAAkB,EAAhC,MAAM;IAEQ,KAAK,EAAnB,MAAM;CAChB,eA0HA"}

package/dist-tsc/dot-plot-hook.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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: any, sampleSets: any, sampleSetSelection: any, expressionData: any, obsIndex: any, cellSets: object, additionalCellSets: object, geneSelection: array, cellSetSelection: array, cellSetColor: object[], featureValueTransform: string | null, featureValueTransformCoefficient: number, posThreshold: any, featureLabelsMap: any): any[];
+//# sourceMappingURL=dot-plot-hook.d.ts.map

package/dist-tsc/dot-plot-hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dot-plot-hook.d.ts","sourceRoot":"","sources":["../src/dot-plot-hook.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,iJAbW,MAAM,sBACN,MAAM,iBAEN,KAAK,oBACL,KAAK,gBACL,MAAM,EAAE,yBACR,MAAM,GAAC,IAAI,oCAEX,MAAM,mDA8EhB"}

package/dist-tsc/dot-plot-hook.js

@@ -0,0 +1,69 @@
+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];
+}

package/dist-tsc/expr-hooks.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Supports three-level stratified input
+ * (cell set, sample set, gene).
+ * @param {*} stratifiedResult
+ * @param {*} posThreshold
+ * @returns
+ */
+export function dotStratifiedExpressionData(stratifiedResult: any, posThreshold: any): any;
+/**
+ * Supports two-level stratified input
+ * (cell set, sample set).
+ * @param {*} stratifiedResult
+ * @param {*} keepZeros
+ * @returns
+ */
+export function summarizeStratifiedExpressionData(stratifiedResult: any, keepZeros: any): any;
+/**
+ * Supports two-level summarized input
+ * (cell set, sample set),
+ * the output from summarizeStratifiedExpressionData.
+ * @param {*} summarizedResult
+ * @param {*} binCount
+ * @param {*} yMinProp
+ * @returns
+ */
+export function histogramStratifiedExpressionData(summarizedResult: any, binCount: any, yMinProp: any): {
+    groupSummaries: {
+        key: any;
+        value: {
+            key: any;
+            value: any;
+        }[];
+    }[];
+    groupData: {
+        key: any;
+        value: {
+            key: any;
+            value: any;
+        }[];
+    }[];
+    groupBins: {
+        key: any;
+        value: {
+            key: any;
+            value: any;
+        }[];
+    }[];
+    groupBinsMax: any;
+    y: any;
+};
+//# sourceMappingURL=expr-hooks.d.ts.map

package/dist-tsc/expr-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expr-hooks.d.ts","sourceRoot":"","sources":["../src/expr-hooks.js"],"names":[],"mappings":"AAgDA;;;;;;GAMG;AACH,8DAJW,GAAC,gBACD,GAAC,OA+BX;AAED;;;;;;GAMG;AACH,oEAJW,GAAC,aACD,GAAC,OAkBX;AAED;;;;;;;;GAQG;AACH,oEALW,GAAC,YACD,GAAC,YACD,GAAC;;;;;;;;;;;;;;;;;;;;;;;;EAsDX"}

package/dist-tsc/expr-hooks.js

@@ -0,0 +1,135 @@
+/* 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/dist-tsc/expr-hooks.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=expr-hooks.test.d.ts.map

package/dist-tsc/expr-hooks.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expr-hooks.test.d.ts","sourceRoot":"","sources":["../src/expr-hooks.test.js"],"names":[],"mappings":""}

package/dist-tsc/expr-hooks.test.js

@@ -0,0 +1,97 @@
+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);
+        });
+    });
+});