@vitessce/scatterplot-embedding 3.4.6 → 3.4.8

package/dist/index.js

@@ -1,4 +1,4 @@
-import { E } from "./index-0e886311.js";
+import { E } from "./index-773a6157.js";
 import "react";
 import "@vitessce/vit-s";
 import "react-dom";

package/dist/{jpeg-e78923e1.js → jpeg-804eb1f0.js}

@@ -1,4 +1,4 @@
-import { B as BaseDecoder } from "./index-0e886311.js";
+import { B as BaseDecoder } from "./index-773a6157.js";
 import "react";
 import "@vitessce/vit-s";
 import "react-dom";

package/dist/{lerc-6a2fa149.js → lerc-2b14ee6b.js}

@@ -1,5 +1,5 @@
 import { i as inflate_1 } from "./pako.esm-68f84e2a.js";
-import { g as getDefaultExportFromCjs, B as BaseDecoder } from "./index-0e886311.js";
+import { g as getDefaultExportFromCjs, B as BaseDecoder } from "./index-773a6157.js";
 import "react";
 import "@vitessce/vit-s";
 import "react-dom";

package/dist/{lzw-a9b3350a.js → lzw-973ca3f2.js}

@@ -1,4 +1,4 @@
-import { B as BaseDecoder } from "./index-0e886311.js";
+import { B as BaseDecoder } from "./index-773a6157.js";
 import "react";
 import "@vitessce/vit-s";
 import "react-dom";

package/dist/{packbits-1e1b593d.js → packbits-bfe475e6.js}

@@ -1,4 +1,4 @@
-import { B as BaseDecoder } from "./index-0e886311.js";
+import { B as BaseDecoder } from "./index-773a6157.js";
 import "react";
 import "@vitessce/vit-s";
 import "react-dom";

package/dist/{raw-517f7071.js → raw-42ff0533.js}

@@ -1,4 +1,4 @@
-import { B as BaseDecoder } from "./index-0e886311.js";
+import { B as BaseDecoder } from "./index-773a6157.js";
 import "react";
 import "@vitessce/vit-s";
 import "react-dom";

package/dist/{webimage-fd28665b.js → webimage-8445b416.js}

@@ -1,4 +1,4 @@
-import { B as BaseDecoder } from "./index-0e886311.js";
+import { B as BaseDecoder } from "./index-773a6157.js";
 import "react";
 import "@vitessce/vit-s";
 import "react-dom";

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

@@ -1 +1 @@
-{"version":3,"file":"EmbeddingScatterplotSubscriber.d.ts","sourceRoot":"","sources":["../src/EmbeddingScatterplotSubscriber.js"],"names":[],"mappings":"AAoCA;;;;;;;;;;;;GAYG;AACH;IAVyB,IAAI,EAAlB,MAAM;IACQ,KAAK,EAAnB,MAAM;IACQ,kBAAkB,EAAhC,MAAM;IAEU,mBAAmB;IAErB,KAAK,EAAnB,MAAM;IACQ,kBAAkB,EAAhC,MAAM;gBA8WhB"}
+{"version":3,"file":"EmbeddingScatterplotSubscriber.d.ts","sourceRoot":"","sources":["../src/EmbeddingScatterplotSubscriber.js"],"names":[],"mappings":"AAyCA;;;;;;;;;;;;GAYG;AACH,sDAVG;IAAsB,IAAI,EAAlB,MAAM;IACQ,KAAK,EAAnB,MAAM;IACQ,kBAAkB,EAAhC,MAAM;IAEU,mBAAmB;IAErB,KAAK,EAAnB,MAAM;IACQ,kBAAkB,EAAhC,MAAM;CAEhB,eAkgBA"}

package/dist-tsc/EmbeddingScatterplotSubscriber.js

@@ -1,13 +1,14 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import React, { useState, useEffect, useCallback, useMemo, } from 'react';
-import { extent } from 'd3-array';
+import { extent, quantileSorted } from 'd3-array';
 import { isEqual } from 'lodash-es';
-import { TitleInfo, useReady, useUrls, useDeckCanvasSize, useUint8FeatureSelection, useExpressionValueGetter, useGetObsInfo, useObsEmbeddingData, useObsSetsData, useFeatureSelection, useObsFeatureMatrixIndices, useFeatureLabelsData, useMultiObsLabels, useCoordination, useLoaders, useSetComponentHover, useSetComponentViewInfo, useInitialCoordination, } from '@vitessce/vit-s';
-import { setObsSelection, mergeObsSets, getCellSetPolygons, getCellColors, } from '@vitessce/sets-utils';
+import { TitleInfo, useReady, useUrls, useDeckCanvasSize, useUint8FeatureSelection, useExpressionValueGetter, useGetObsInfo, useObsEmbeddingData, useObsSetsData, useFeatureSelection, useObsFeatureMatrixIndices, useFeatureLabelsData, useMultiObsLabels, useSampleSetsData, useSampleEdgesData, useCoordination, useLoaders, useSetComponentHover, useSetComponentViewInfo, useInitialCoordination, } from '@vitessce/vit-s';
+import { setObsSelection, mergeObsSets, getCellSetPolygons, getCellColors, stratifyArrays, } from '@vitessce/sets-utils';
 import { pluralize as plur, commaNumber } from '@vitessce/utils';
 import { Scatterplot, ScatterplotTooltipSubscriber, ScatterplotOptions, getPointSizeDevicePixels, getPointOpacity, } from '@vitessce/scatterplot';
 import { Legend } from '@vitessce/legend';
 import { ViewType, COMPONENT_COORDINATION_TYPES } from '@vitessce/constants-internal';
+import { DEFAULT_CONTOUR_PERCENTILES } from './constants.js';
 /**
  * A subscriber component for the scatterplot.
  * @param {object} props
@@ -29,7 +30,7 @@ export function EmbeddingScatterplotSubscriber(props) {
     const setComponentHover = useSetComponentHover();
     const setComponentViewInfo = useSetComponentViewInfo(uuid);
     // Get "props" from the coordination space.
-    const [{ dataset, obsType, featureType, featureValueType, embeddingZoom: zoom, embeddingTargetX: targetX, embeddingTargetY: targetY, embeddingTargetZ: targetZ, embeddingType: mapping, obsFilter: cellFilter, obsHighlight: cellHighlight, featureSelection: geneSelection, obsSetSelection: cellSetSelection, obsSetColor: cellSetColor, obsColorEncoding: cellColorEncoding, additionalObsSets: additionalCellSets, embeddingObsSetPolygonsVisible: cellSetPolygonsVisible, embeddingObsSetLabelsVisible: cellSetLabelsVisible, embeddingObsSetLabelSize: cellSetLabelSize, embeddingObsRadius: cellRadiusFixed, embeddingObsRadiusMode: cellRadiusMode, embeddingObsOpacity: cellOpacityFixed, embeddingObsOpacityMode: cellOpacityMode, featureValueColormap: geneExpressionColormap, featureValueColormapRange: geneExpressionColormapRange, tooltipsVisible, }, { setEmbeddingZoom: setZoom, setEmbeddingTargetX: setTargetX, setEmbeddingTargetY: setTargetY, setEmbeddingTargetZ: setTargetZ, setObsFilter: setCellFilter, setObsSetSelection: setCellSetSelection, setObsHighlight: setCellHighlight, setObsSetColor: setCellSetColor, setObsColorEncoding: setCellColorEncoding, setAdditionalObsSets: setAdditionalCellSets, setEmbeddingObsSetPolygonsVisible: setCellSetPolygonsVisible, setEmbeddingObsSetLabelsVisible: setCellSetLabelsVisible, setEmbeddingObsSetLabelSize: setCellSetLabelSize, setEmbeddingObsRadius: setCellRadiusFixed, setEmbeddingObsRadiusMode: setCellRadiusMode, setEmbeddingObsOpacity: setCellOpacityFixed, setEmbeddingObsOpacityMode: setCellOpacityMode, setFeatureValueColormap: setGeneExpressionColormap, setFeatureValueColormapRange: setGeneExpressionColormapRange, setTooltipsVisible, }] = useCoordination(COMPONENT_COORDINATION_TYPES[ViewType.SCATTERPLOT], coordinationScopes);
+    const [{ dataset, obsType, featureType, featureValueType, sampleType, embeddingZoom: zoom, embeddingTargetX: targetX, embeddingTargetY: targetY, embeddingTargetZ: targetZ, embeddingType: mapping, obsFilter: cellFilter, obsHighlight: cellHighlight, featureSelection: geneSelection, obsSetSelection: cellSetSelection, obsSetColor: cellSetColor, obsColorEncoding: cellColorEncoding, additionalObsSets: additionalCellSets, embeddingObsSetPolygonsVisible: cellSetPolygonsVisible, embeddingObsSetLabelsVisible: cellSetLabelsVisible, embeddingObsSetLabelSize: cellSetLabelSize, embeddingObsRadius: cellRadiusFixed, embeddingObsRadiusMode: cellRadiusMode, embeddingObsOpacity: cellOpacityFixed, embeddingObsOpacityMode: cellOpacityMode, featureValueColormap: geneExpressionColormap, featureValueColormapRange: geneExpressionColormapRange, tooltipsVisible, sampleSetSelection, sampleSetColor, embeddingPointsVisible, embeddingContoursVisible, embeddingContoursFilled, embeddingContourPercentiles: contourPercentiles, contourColorEncoding, contourColor, }, { setEmbeddingZoom: setZoom, setEmbeddingTargetX: setTargetX, setEmbeddingTargetY: setTargetY, setEmbeddingTargetZ: setTargetZ, setObsFilter: setCellFilter, setObsSetSelection: setCellSetSelection, setObsHighlight: setCellHighlight, setObsSetColor: setCellSetColor, setObsColorEncoding: setCellColorEncoding, setAdditionalObsSets: setAdditionalCellSets, setEmbeddingObsSetPolygonsVisible: setCellSetPolygonsVisible, setEmbeddingObsSetLabelsVisible: setCellSetLabelsVisible, setEmbeddingObsSetLabelSize: setCellSetLabelSize, setEmbeddingObsRadius: setCellRadiusFixed, setEmbeddingObsRadiusMode: setCellRadiusMode, setEmbeddingObsOpacity: setCellOpacityFixed, setEmbeddingObsOpacityMode: setCellOpacityMode, setFeatureValueColormap: setGeneExpressionColormap, setFeatureValueColormapRange: setGeneExpressionColormapRange, setTooltipsVisible, setEmbeddingPointsVisible, setEmbeddingContoursVisible, setEmbeddingContoursFilled, setEmbeddingContourPercentiles: setContourPercentiles, setContourColorEncoding, }] = useCoordination(COMPONENT_COORDINATION_TYPES[ViewType.SCATTERPLOT], coordinationScopes);
     const { embeddingZoom: initialZoom, embeddingTargetX: initialTargetX, embeddingTargetY: initialTargetY, } = useInitialCoordination(COMPONENT_COORDINATION_TYPES[ViewType.SCATTERPLOT], coordinationScopes);
     const observationsLabel = observationsLabelOverride || obsType;
     const [width, height, deckRef] = useDeckCanvasSize();
@@ -43,18 +44,24 @@ export function EmbeddingScatterplotSubscriber(props) {
     const [expressionData, loadedFeatureSelection, featureSelectionStatus] = useFeatureSelection(loaders, dataset, false, geneSelection, { obsType, featureType, featureValueType });
     const [{ obsIndex: matrixObsIndex }, matrixIndicesStatus, matrixIndicesUrls,] = useObsFeatureMatrixIndices(loaders, dataset, false, { obsType, featureType, featureValueType });
     const [{ featureLabelsMap }, featureLabelsStatus, featureLabelsUrls] = useFeatureLabelsData(loaders, dataset, false, {}, {}, { featureType });
+    const [{ sampleSets }, sampleSetsStatus, sampleSetsUrl] = useSampleSetsData(loaders, dataset, false, {}, {}, { sampleType });
+    const [{ sampleEdges }, sampleEdgesStatus, sampleEdgesUrl] = useSampleEdgesData(loaders, dataset, false, {}, {}, { obsType, sampleType });
     const isReady = useReady([
         obsEmbeddingStatus,
         obsSetsStatus,
         featureSelectionStatus,
         featureLabelsStatus,
         matrixIndicesStatus,
+        sampleSetsStatus,
+        sampleEdgesStatus,
     ]);
     const urls = useUrls([
         obsEmbeddingUrls,
         obsSetsUrls,
         matrixIndicesUrls,
         featureLabelsUrls,
+        sampleSetsUrl,
+        sampleEdgesUrl,
     ]);
     const [dynamicCellRadius, setDynamicCellRadius] = useState(cellRadiusFixed);
     const [dynamicCellOpacity, setDynamicCellOpacity] = useState(cellOpacityFixed);
@@ -157,13 +164,101 @@ export function EmbeddingScatterplotSubscriber(props) {
         matrixObsIndex,
         expressionData: uint8ExpressionData,
     });
+    // Sort the expression data array so that we can compute percentiles
+    // using the d3 quantileSorted function for improved performance.
+    const sortedWeights = useMemo(() => {
+        if (uint8ExpressionData?.[0]) {
+            const weights = uint8ExpressionData[0];
+            return weights.toSorted();
+        }
+        return null;
+    }, [uint8ExpressionData]);
+    // Compute contour thresholds based on the entire expression data distribution
+    // (not per-cellSet or per-sampleSet).
+    const contourThresholds = useMemo(() => {
+        if (sortedWeights) {
+            const thresholds = (contourPercentiles || DEFAULT_CONTOUR_PERCENTILES)
+                .map(p => quantileSorted(sortedWeights, p))
+                .map(t => Math.max(t, 1.0));
+            return thresholds;
+        }
+        return null;
+    }, [contourPercentiles, sortedWeights]);
+    // It is possible for the embedding index+data to be out of order
+    // with respect to the matrix index+data. Here, we align the embedding
+    // data so that the rows are ordered the same as the matrix rows.
+    // TODO: refactor this as a hook that can be used elsewhere to align data
+    // from different data types with the expression matrix data.
+    // Need to fallback to the original ordering if no matrix data is present.
+    // TODO: do this everywhere and remove the need for the
+    // useExpressionValueGetter hook and getter function.
+    const [alignedEmbeddingIndex, alignedEmbeddingData] = useMemo(() => {
+        // Sort the embedding data according to the matrix obsIndex.
+        if (obsEmbedding?.data && obsEmbeddingIndex && matrixObsIndex) {
+            const matrixIndexMap = new Map(matrixObsIndex.map((key, i) => ([key, i])));
+            const toMatrixIndex = obsEmbeddingIndex.map(key => matrixIndexMap.get(key));
+            const newEmbeddingIndex = new Array(obsEmbeddingIndex.length);
+            const newEmbeddingData = [
+                new obsEmbedding.data[0].constructor(obsEmbedding.data[0].length),
+                new obsEmbedding.data[1].constructor(obsEmbedding.data[1].length),
+            ];
+            for (let i = 0; i < obsEmbeddingIndex.length; i++) {
+                const matrixRowIndex = toMatrixIndex[i];
+                newEmbeddingData[0][matrixRowIndex] = obsEmbedding.data[0][i];
+                newEmbeddingData[1][matrixRowIndex] = obsEmbedding.data[1][i];
+                newEmbeddingIndex[matrixRowIndex] = obsEmbeddingIndex[i];
+            }
+            return [newEmbeddingIndex, { ...obsEmbedding, data: newEmbeddingData }];
+        }
+        // Fall back to original ordering if no matrix data is present to align with.
+        return [obsEmbeddingIndex, obsEmbedding];
+    }, [matrixObsIndex, obsEmbeddingIndex, obsEmbedding]);
+    const sampleIdToObsIdsMap = useMemo(() => {
+        // sampleEdges maps obsId -> sampleId.
+        // However when we stratify we want to map sampleId -> [obsId1, obsId2, ...].
+        // Here we create this reverse mapping.
+        if (sampleEdges) {
+            const result = new Map();
+            Array.from(sampleEdges.entries()).forEach(([obsId, sampleId]) => {
+                if (!result.has(sampleId)) {
+                    result.set(sampleId, [obsId]);
+                }
+                else {
+                    result.get(sampleId).push(obsId);
+                }
+            });
+            return result;
+        }
+        return null;
+    }, [sampleEdges]);
+    // Stratify multiple arrays: per-cellSet and per-sampleSet.
+    const stratifiedData = useMemo(() => {
+        if (alignedEmbeddingData?.data) {
+            const result = stratifyArrays(sampleEdges, sampleIdToObsIdsMap, sampleSets, sampleSetSelection, alignedEmbeddingIndex, mergedCellSets, cellSetSelection, {
+                obsEmbeddingX: alignedEmbeddingData.data[0],
+                obsEmbeddingY: alignedEmbeddingData.data[1],
+                // TODO: aggregate and transform expression data if needed prior to passing here
+                ...(uint8ExpressionData?.[0] ? { featureValue: uint8ExpressionData?.[0] } : {}),
+            });
+            return result;
+        }
+        return null;
+    }, [alignedEmbeddingIndex, alignedEmbeddingData, uint8ExpressionData,
+        sampleEdges, sampleIdToObsIdsMap, sampleSets, sampleSetSelection,
+        cellSetSelection, mergedCellSets,
+    ]);
     const setViewState = ({ zoom: newZoom, target }) => {
         setZoom(newZoom);
         setTargetX(target[0]);
         setTargetY(target[1]);
         setTargetZ(target[2] || 0);
     };
-    return (_jsxs(TitleInfo, { title: title, info: `${commaNumber(cellsCount)} ${plur(observationsLabel, cellsCount)}`, closeButtonVisible: closeButtonVisible, downloadButtonVisible: downloadButtonVisible, removeGridComponent: removeGridComponent, urls: urls, theme: theme, isReady: isReady, options: (_jsx(ScatterplotOptions, { observationsLabel: observationsLabel, cellRadius: cellRadiusFixed, setCellRadius: setCellRadiusFixed, cellRadiusMode: cellRadiusMode, setCellRadiusMode: setCellRadiusMode, cellOpacity: cellOpacityFixed, setCellOpacity: setCellOpacityFixed, cellOpacityMode: cellOpacityMode, setCellOpacityMode: setCellOpacityMode, cellSetLabelsVisible: cellSetLabelsVisible, setCellSetLabelsVisible: setCellSetLabelsVisible, tooltipsVisible: tooltipsVisible, setTooltipsVisible: setTooltipsVisible, cellSetLabelSize: cellSetLabelSize, setCellSetLabelSize: setCellSetLabelSize, cellSetPolygonsVisible: cellSetPolygonsVisible, setCellSetPolygonsVisible: setCellSetPolygonsVisible, cellColorEncoding: cellColorEncoding, setCellColorEncoding: setCellColorEncoding, geneExpressionColormap: geneExpressionColormap, setGeneExpressionColormap: setGeneExpressionColormap, geneExpressionColormapRange: geneExpressionColormapRange, setGeneExpressionColormapRange: setGeneExpressionColormapRange })), children: [_jsx(Scatterplot, { ref: deckRef, uuid: uuid, theme: theme, viewState: { zoom, target: [targetX, targetY, targetZ] }, setViewState: setViewState, originalViewState: originalViewState, obsEmbeddingIndex: obsEmbeddingIndex, obsEmbedding: obsEmbedding, cellFilter: cellFilter, cellSelection: cellSelection, cellHighlight: cellHighlight, cellColors: cellColors, cellSetPolygons: cellSetPolygons, cellSetLabelSize: cellSetLabelSize, cellSetLabelsVisible: cellSetLabelsVisible, cellSetPolygonsVisible: cellSetPolygonsVisible, setCellFilter: setCellFilter, setCellSelection: setCellSelectionProp, setCellHighlight: setCellHighlight, cellRadius: cellRadius, cellOpacity: cellOpacity, cellColorEncoding: cellColorEncoding, geneExpressionColormap: geneExpressionColormap, geneExpressionColormapRange: geneExpressionColormapRange, setComponentHover: () => {
+    return (_jsxs(TitleInfo, { title: title, info: `${commaNumber(cellsCount)} ${plur(observationsLabel, cellsCount)}`, closeButtonVisible: closeButtonVisible, downloadButtonVisible: downloadButtonVisible, removeGridComponent: removeGridComponent, urls: urls, theme: theme, isReady: isReady, options: (_jsx(ScatterplotOptions, { observationsLabel: observationsLabel, cellRadius: cellRadiusFixed, setCellRadius: setCellRadiusFixed, cellRadiusMode: cellRadiusMode, setCellRadiusMode: setCellRadiusMode, cellOpacity: cellOpacityFixed, setCellOpacity: setCellOpacityFixed, cellOpacityMode: cellOpacityMode, setCellOpacityMode: setCellOpacityMode, cellSetLabelsVisible: cellSetLabelsVisible, setCellSetLabelsVisible: setCellSetLabelsVisible, tooltipsVisible: tooltipsVisible, setTooltipsVisible: setTooltipsVisible, cellSetLabelSize: cellSetLabelSize, setCellSetLabelSize: setCellSetLabelSize, cellSetPolygonsVisible: cellSetPolygonsVisible, setCellSetPolygonsVisible: setCellSetPolygonsVisible, cellColorEncoding: cellColorEncoding, setCellColorEncoding: setCellColorEncoding, geneExpressionColormap: geneExpressionColormap, setGeneExpressionColormap: setGeneExpressionColormap, geneExpressionColormapRange: geneExpressionColormapRange, setGeneExpressionColormapRange: setGeneExpressionColormapRange, embeddingPointsVisible: embeddingPointsVisible, setEmbeddingPointsVisible: setEmbeddingPointsVisible, embeddingContoursVisible: embeddingContoursVisible, setEmbeddingContoursVisible: setEmbeddingContoursVisible, embeddingContoursFilled: embeddingContoursFilled, setEmbeddingContoursFilled: setEmbeddingContoursFilled, contourPercentiles: contourPercentiles, setContourPercentiles: setContourPercentiles, defaultContourPercentiles: DEFAULT_CONTOUR_PERCENTILES, contourColorEncoding: contourColorEncoding, setContourColorEncoding: setContourColorEncoding })), children: [_jsx(Scatterplot, { ref: deckRef, uuid: uuid, theme: theme, viewState: { zoom, target: [targetX, targetY, targetZ] }, setViewState: setViewState, originalViewState: originalViewState, obsEmbeddingIndex: obsEmbeddingIndex, obsEmbedding: obsEmbedding, cellFilter: cellFilter, cellSelection: cellSelection, cellHighlight: cellHighlight, cellColors: cellColors, cellSetPolygons: cellSetPolygons, cellSetLabelSize: cellSetLabelSize, cellSetLabelsVisible: cellSetLabelsVisible, cellSetPolygonsVisible: cellSetPolygonsVisible, setCellFilter: setCellFilter, setCellSelection: setCellSelectionProp, setCellHighlight: setCellHighlight, cellRadius: cellRadius, cellOpacity: cellOpacity, cellColorEncoding: cellColorEncoding, geneExpressionColormap: geneExpressionColormap, geneExpressionColormapRange: geneExpressionColormapRange, setComponentHover: () => {
                     setComponentHover(uuid);
-                }, updateViewInfo: setComponentViewInfo, getExpressionValue: getExpressionValue, getCellIsSelected: getCellIsSelected }), tooltipsVisible && (_jsx(ScatterplotTooltipSubscriber, { parentUuid: uuid, obsHighlight: cellHighlight, width: width, height: height, getObsInfo: getObsInfo })), _jsx(Legend, { visible: true, theme: theme, featureType: featureType, featureValueType: featureValueType, obsColorEncoding: cellColorEncoding, featureSelection: geneSelection, featureLabelsMap: featureLabelsMap, featureValueColormap: geneExpressionColormap, featureValueColormapRange: geneExpressionColormapRange, extent: expressionExtents?.[0] })] }));
+                }, updateViewInfo: setComponentViewInfo, getExpressionValue: getExpressionValue, getCellIsSelected: getCellIsSelected, obsSetSelection: cellSetSelection, sampleSetSelection: sampleSetSelection, 
+                // InternMap data structures where keys are
+                // obsSet -> sampleSet -> arrayKey -> [].
+                stratifiedData: stratifiedData, obsSetColor: cellSetColor, sampleSetColor: sampleSetColor, contourThresholds: contourThresholds, contourColorEncoding: contourColorEncoding, contourColor: contourColor, contoursFilled: embeddingContoursFilled, embeddingPointsVisible: embeddingPointsVisible, embeddingContoursVisible: embeddingContoursVisible }), tooltipsVisible && (_jsx(ScatterplotTooltipSubscriber, { parentUuid: uuid, obsHighlight: cellHighlight, width: width, height: height, getObsInfo: getObsInfo })), _jsx(Legend, { visible: true, theme: theme, featureType: featureType, featureValueType: featureValueType, obsColorEncoding: cellColorEncoding, featureSelection: geneSelection, featureLabelsMap: featureLabelsMap, featureValueColormap: geneExpressionColormap, featureValueColormapRange: geneExpressionColormapRange, extent: expressionExtents?.[0], 
+                // Contour percentile legend
+                pointsVisible: embeddingPointsVisible, contoursVisible: embeddingContoursVisible, contoursFilled: embeddingContoursFilled, contourPercentiles: contourPercentiles || DEFAULT_CONTOUR_PERCENTILES, contourThresholds: contourThresholds })] }));
 }

package/dist-tsc/constants.d.ts

@@ -0,0 +1,2 @@
+export const DEFAULT_CONTOUR_PERCENTILES: number[];
+//# sourceMappingURL=constants.d.ts.map

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

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

package/dist-tsc/constants.js

@@ -0,0 +1 @@
+export const DEFAULT_CONTOUR_PERCENTILES = [0.09, 0.9, 0.99];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vitessce/scatterplot-embedding",
-  "version": "3.4.6",
+  "version": "3.4.8",
   "author": "Gehlenborg Lab",
   "homepage": "http://vitessce.io",
   "repository": {
@@ -20,12 +20,12 @@
     "d3-array": "^2.4.0",
     "lodash-es": "^4.17.21",
     "react-aria": "^3.28.0",
-    "@vitessce/legend": "3.4.6",
-    "@vitessce/utils": "3.4.6",
-    "@vitessce/scatterplot": "3.4.6",
-    "@vitessce/sets-utils": "3.4.6",
-    "@vitessce/vit-s": "3.4.6",
-    "@vitessce/constants-internal": "3.4.6"
+    "@vitessce/constants-internal": "3.4.8",
+    "@vitessce/legend": "3.4.8",
+    "@vitessce/scatterplot": "3.4.8",
+    "@vitessce/sets-utils": "3.4.8",
+    "@vitessce/utils": "3.4.8",
+    "@vitessce/vit-s": "3.4.8"
   },
   "devDependencies": {
     "react": "^18.0.0",

package/src/EmbeddingScatterplotSubscriber.js

@@ -1,7 +1,7 @@
 import React, {
   useState, useEffect, useCallback, useMemo,
 } from 'react';
-import { extent } from 'd3-array';
+import { extent, quantileSorted } from 'd3-array';
 import { isEqual } from 'lodash-es';
 import {
   TitleInfo,
@@ -16,6 +16,8 @@ import {
   useObsFeatureMatrixIndices,
   useFeatureLabelsData,
   useMultiObsLabels,
+  useSampleSetsData,
+  useSampleEdgesData,
   useCoordination,
   useLoaders,
   useSetComponentHover,
@@ -24,6 +26,7 @@ import {
 } from '@vitessce/vit-s';
 import {
   setObsSelection, mergeObsSets, getCellSetPolygons, getCellColors,
+  stratifyArrays,
 } from '@vitessce/sets-utils';
 import { pluralize as plur, commaNumber } from '@vitessce/utils';
 import {
@@ -33,6 +36,8 @@ import {
 } from '@vitessce/scatterplot';
 import { Legend } from '@vitessce/legend';
 import { ViewType, COMPONENT_COORDINATION_TYPES } from '@vitessce/constants-internal';
+import { DEFAULT_CONTOUR_PERCENTILES } from './constants.js';
+
 
 /**
  * A subscriber component for the scatterplot.
@@ -71,6 +76,7 @@ export function EmbeddingScatterplotSubscriber(props) {
     obsType,
     featureType,
     featureValueType,
+    sampleType,
     embeddingZoom: zoom,
     embeddingTargetX: targetX,
     embeddingTargetY: targetY,
@@ -93,6 +99,14 @@ export function EmbeddingScatterplotSubscriber(props) {
     featureValueColormap: geneExpressionColormap,
     featureValueColormapRange: geneExpressionColormapRange,
     tooltipsVisible,
+    sampleSetSelection,
+    sampleSetColor,
+    embeddingPointsVisible,
+    embeddingContoursVisible,
+    embeddingContoursFilled,
+    embeddingContourPercentiles: contourPercentiles,
+    contourColorEncoding,
+    contourColor,
   }, {
     setEmbeddingZoom: setZoom,
     setEmbeddingTargetX: setTargetX,
@@ -114,6 +128,11 @@ export function EmbeddingScatterplotSubscriber(props) {
     setFeatureValueColormap: setGeneExpressionColormap,
     setFeatureValueColormapRange: setGeneExpressionColormapRange,
     setTooltipsVisible,
+    setEmbeddingPointsVisible,
+    setEmbeddingContoursVisible,
+    setEmbeddingContoursFilled,
+    setEmbeddingContourPercentiles: setContourPercentiles,
+    setContourColorEncoding,
   }] = useCoordination(COMPONENT_COORDINATION_TYPES[ViewType.SCATTERPLOT], coordinationScopes);
 
   const {
@@ -164,18 +183,32 @@ export function EmbeddingScatterplotSubscriber(props) {
     { featureType },
   );
 
+  const [{ sampleSets }, sampleSetsStatus, sampleSetsUrl] = useSampleSetsData(
+    loaders, dataset, false, {}, {},
+    { sampleType },
+  );
+
+  const [{ sampleEdges }, sampleEdgesStatus, sampleEdgesUrl] = useSampleEdgesData(
+    loaders, dataset, false, {}, {},
+    { obsType, sampleType },
+  );
+
   const isReady = useReady([
     obsEmbeddingStatus,
     obsSetsStatus,
     featureSelectionStatus,
     featureLabelsStatus,
     matrixIndicesStatus,
+    sampleSetsStatus,
+    sampleEdgesStatus,
   ]);
   const urls = useUrls([
     obsEmbeddingUrls,
     obsSetsUrls,
     matrixIndicesUrls,
     featureLabelsUrls,
+    sampleSetsUrl,
+    sampleEdgesUrl,
   ]);
 
   const [dynamicCellRadius, setDynamicCellRadius] = useState(cellRadiusFixed);
@@ -309,6 +342,98 @@ export function EmbeddingScatterplotSubscriber(props) {
     expressionData: uint8ExpressionData,
   });
 
+  // Sort the expression data array so that we can compute percentiles
+  // using the d3 quantileSorted function for improved performance.
+  const sortedWeights = useMemo(() => {
+    if (uint8ExpressionData?.[0]) {
+      const weights = uint8ExpressionData[0];
+      return weights.toSorted();
+    }
+    return null;
+  }, [uint8ExpressionData]);
+
+  // Compute contour thresholds based on the entire expression data distribution
+  // (not per-cellSet or per-sampleSet).
+  const contourThresholds = useMemo(() => {
+    if (sortedWeights) {
+      const thresholds = (contourPercentiles || DEFAULT_CONTOUR_PERCENTILES)
+        .map(p => quantileSorted(sortedWeights, p))
+        .map(t => Math.max(t, 1.0));
+      return thresholds;
+    }
+    return null;
+  }, [contourPercentiles, sortedWeights]);
+
+  // It is possible for the embedding index+data to be out of order
+  // with respect to the matrix index+data. Here, we align the embedding
+  // data so that the rows are ordered the same as the matrix rows.
+  // TODO: refactor this as a hook that can be used elsewhere to align data
+  // from different data types with the expression matrix data.
+  // Need to fallback to the original ordering if no matrix data is present.
+  // TODO: do this everywhere and remove the need for the
+  // useExpressionValueGetter hook and getter function.
+  const [alignedEmbeddingIndex, alignedEmbeddingData] = useMemo(() => {
+    // Sort the embedding data according to the matrix obsIndex.
+    if (obsEmbedding?.data && obsEmbeddingIndex && matrixObsIndex) {
+      const matrixIndexMap = new Map(matrixObsIndex.map((key, i) => ([key, i])));
+      const toMatrixIndex = obsEmbeddingIndex.map(key => matrixIndexMap.get(key));
+
+      const newEmbeddingIndex = new Array(obsEmbeddingIndex.length);
+      const newEmbeddingData = [
+        new obsEmbedding.data[0].constructor(obsEmbedding.data[0].length),
+        new obsEmbedding.data[1].constructor(obsEmbedding.data[1].length),
+      ];
+      for (let i = 0; i < obsEmbeddingIndex.length; i++) {
+        const matrixRowIndex = toMatrixIndex[i];
+        newEmbeddingData[0][matrixRowIndex] = obsEmbedding.data[0][i];
+        newEmbeddingData[1][matrixRowIndex] = obsEmbedding.data[1][i];
+        newEmbeddingIndex[matrixRowIndex] = obsEmbeddingIndex[i];
+      }
+      return [newEmbeddingIndex, { ...obsEmbedding, data: newEmbeddingData }];
+    }
+    // Fall back to original ordering if no matrix data is present to align with.
+    return [obsEmbeddingIndex, obsEmbedding];
+  }, [matrixObsIndex, obsEmbeddingIndex, obsEmbedding]);
+
+  const sampleIdToObsIdsMap = useMemo(() => {
+    // sampleEdges maps obsId -> sampleId.
+    // However when we stratify we want to map sampleId -> [obsId1, obsId2, ...].
+    // Here we create this reverse mapping.
+    if (sampleEdges) {
+      const result = new Map();
+      Array.from(sampleEdges.entries()).forEach(([obsId, sampleId]) => {
+        if (!result.has(sampleId)) {
+          result.set(sampleId, [obsId]);
+        } else {
+          result.get(sampleId).push(obsId);
+        }
+      });
+      return result;
+    }
+    return null;
+  }, [sampleEdges]);
+
+  // Stratify multiple arrays: per-cellSet and per-sampleSet.
+  const stratifiedData = useMemo(() => {
+    if (alignedEmbeddingData?.data) {
+      const result = stratifyArrays(
+        sampleEdges, sampleIdToObsIdsMap,
+        sampleSets, sampleSetSelection,
+        alignedEmbeddingIndex, mergedCellSets, cellSetSelection, {
+          obsEmbeddingX: alignedEmbeddingData.data[0],
+          obsEmbeddingY: alignedEmbeddingData.data[1],
+          // TODO: aggregate and transform expression data if needed prior to passing here
+          ...(uint8ExpressionData?.[0] ? { featureValue: uint8ExpressionData?.[0] } : {}),
+        },
+      );
+      return result;
+    }
+    return null;
+  }, [alignedEmbeddingIndex, alignedEmbeddingData, uint8ExpressionData,
+    sampleEdges, sampleIdToObsIdsMap, sampleSets, sampleSetSelection,
+    cellSetSelection, mergedCellSets,
+  ]);
+
   const setViewState = ({ zoom: newZoom, target }) => {
     setZoom(newZoom);
     setTargetX(target[0]);
@@ -351,6 +476,17 @@ export function EmbeddingScatterplotSubscriber(props) {
           setGeneExpressionColormap={setGeneExpressionColormap}
           geneExpressionColormapRange={geneExpressionColormapRange}
           setGeneExpressionColormapRange={setGeneExpressionColormapRange}
+          embeddingPointsVisible={embeddingPointsVisible}
+          setEmbeddingPointsVisible={setEmbeddingPointsVisible}
+          embeddingContoursVisible={embeddingContoursVisible}
+          setEmbeddingContoursVisible={setEmbeddingContoursVisible}
+          embeddingContoursFilled={embeddingContoursFilled}
+          setEmbeddingContoursFilled={setEmbeddingContoursFilled}
+          contourPercentiles={contourPercentiles}
+          setContourPercentiles={setContourPercentiles}
+          defaultContourPercentiles={DEFAULT_CONTOUR_PERCENTILES}
+          contourColorEncoding={contourColorEncoding}
+          setContourColorEncoding={setContourColorEncoding}
         />
       )}
     >
@@ -386,6 +522,19 @@ export function EmbeddingScatterplotSubscriber(props) {
         getExpressionValue={getExpressionValue}
         getCellIsSelected={getCellIsSelected}
 
+        obsSetSelection={cellSetSelection}
+        sampleSetSelection={sampleSetSelection}
+        // InternMap data structures where keys are
+        // obsSet -> sampleSet -> arrayKey -> [].
+        stratifiedData={stratifiedData}
+        obsSetColor={cellSetColor}
+        sampleSetColor={sampleSetColor}
+        contourThresholds={contourThresholds}
+        contourColorEncoding={contourColorEncoding}
+        contourColor={contourColor}
+        contoursFilled={embeddingContoursFilled}
+        embeddingPointsVisible={embeddingPointsVisible}
+        embeddingContoursVisible={embeddingContoursVisible}
       />
       {tooltipsVisible && (
       <ScatterplotTooltipSubscriber
@@ -407,6 +556,12 @@ export function EmbeddingScatterplotSubscriber(props) {
         featureValueColormap={geneExpressionColormap}
         featureValueColormapRange={geneExpressionColormapRange}
         extent={expressionExtents?.[0]}
+        // Contour percentile legend
+        pointsVisible={embeddingPointsVisible}
+        contoursVisible={embeddingContoursVisible}
+        contoursFilled={embeddingContoursFilled}
+        contourPercentiles={contourPercentiles || DEFAULT_CONTOUR_PERCENTILES}
+        contourThresholds={contourThresholds}
       />
     </TitleInfo>
   );

package/src/constants.js

@@ -0,0 +1 @@
+export const DEFAULT_CONTOUR_PERCENTILES = [0.09, 0.9, 0.99];