@vitessce/vit-s 2.0.3 → 3.0.1

package/src/data-hooks.js

@@ -1,15 +1,20 @@
 import { useState, useEffect, useMemo } from 'react';
 import { CoordinationType, DataType, STATUS } from '@vitessce/constants-internal';
 import { fromEntries } from '@vitessce/utils';
-import { useMatchingLoader, useMultiCoordinationValues, useSetWarning } from './state/hooks';
+import { useQuery, useQueries } from '@tanstack/react-query';
+import {
+  getMatchingLoader,
+  useMultiCoordinationValues,
+  useSetWarning,
+} from './state/hooks.js';
 import {
   LoaderNotFoundError,
-} from './errors/index';
+} from './errors/index.js';
 import {
   warn,
   useDataType,
   useDataTypeMulti,
-} from './data-hook-utils';
+} from './data-hook-utils.js';
 
 /**
  * Get the dataset description string.
@@ -48,8 +53,6 @@ export function useDescription(loaders, dataset) {
  * datasets and data types to loader instances.
  * @param {string} dataset The key for a dataset,
  * used to identify which loader to use.
- * @param {function} addUrl A function to call to update
- * the URL list.
  * @param {boolean} isRequired Should a warning be thrown if
  * loading is unsuccessful?
  * @param {object} coordinationSetters Object where
@@ -63,111 +66,111 @@ export function useDescription(loaders, dataset) {
  * number of items in the cells object.
  */
 export function useObsEmbeddingData(
-  loaders, dataset, addUrl, isRequired,
+  loaders, dataset, isRequired,
   coordinationSetters, initialCoordinationValues, matchOn,
 ) {
   return useDataType(
     DataType.OBS_EMBEDDING,
-    loaders, dataset, addUrl, isRequired,
+    loaders, dataset, isRequired,
     coordinationSetters, initialCoordinationValues, matchOn,
   );
 }
 
 export function useObsLocationsData(
-  loaders, dataset, addUrl, isRequired,
+  loaders, dataset, isRequired,
   coordinationSetters, initialCoordinationValues, matchOn,
 ) {
   return useDataType(
     DataType.OBS_LOCATIONS,
-    loaders, dataset, addUrl, isRequired,
+    loaders, dataset, isRequired,
     coordinationSetters, initialCoordinationValues, matchOn,
   );
 }
 
 export function useObsLabelsData(
-  loaders, dataset, addUrl, isRequired,
+  loaders, dataset, isRequired,
   coordinationSetters, initialCoordinationValues, matchOn,
 ) {
   return useDataType(
     DataType.OBS_LABELS,
-    loaders, dataset, addUrl, isRequired,
+    loaders, dataset, isRequired,
     coordinationSetters, initialCoordinationValues, matchOn,
   );
 }
 
 export function useObsSegmentationsData(
-  loaders, dataset, addUrl, isRequired,
+  loaders, dataset, isRequired,
   coordinationSetters, initialCoordinationValues, matchOn,
 ) {
   return useDataType(
     DataType.OBS_SEGMENTATIONS,
-    loaders, dataset, addUrl, isRequired,
+    loaders, dataset, isRequired,
     coordinationSetters, initialCoordinationValues, matchOn,
   );
 }
 
 export function useObsSetsData(
-  loaders, dataset, addUrl, isRequired,
+  loaders, dataset, isRequired,
   coordinationSetters, initialCoordinationValues, matchOn,
 ) {
   return useDataType(
     DataType.OBS_SETS,
-    loaders, dataset, addUrl, isRequired,
+    loaders, dataset, isRequired,
     coordinationSetters, initialCoordinationValues, matchOn,
   );
 }
 
 export function useObsFeatureMatrixData(
-  loaders, dataset, addUrl, isRequired,
+  loaders, dataset, isRequired,
   coordinationSetters, initialCoordinationValues, matchOn,
 ) {
   return useDataType(
     DataType.OBS_FEATURE_MATRIX,
-    loaders, dataset, addUrl, isRequired,
+    loaders, dataset, isRequired,
     coordinationSetters, initialCoordinationValues, matchOn,
   );
 }
 
 export function useFeatureLabelsData(
-  loaders, dataset, addUrl, isRequired,
+  loaders, dataset, isRequired,
   coordinationSetters, initialCoordinationValues, matchOn,
 ) {
   return useDataType(
     DataType.FEATURE_LABELS,
-    loaders, dataset, addUrl, isRequired,
+    loaders, dataset, isRequired,
     coordinationSetters, initialCoordinationValues, matchOn,
   );
 }
 
 export function useImageData(
-  loaders, dataset, addUrl, isRequired,
+  loaders, dataset, isRequired,
   coordinationSetters, initialCoordinationValues, matchOn,
 ) {
   return useDataType(
     DataType.IMAGE,
-    loaders, dataset, addUrl, isRequired,
+    loaders, dataset, isRequired,
     coordinationSetters, initialCoordinationValues, matchOn,
   );
 }
 
 export function useGenomicProfilesData(
-  loaders, dataset, addUrl, isRequired,
+  loaders, dataset, isRequired,
   coordinationSetters, initialCoordinationValues, matchOn,
 ) {
   return useDataType(
     DataType.GENOMIC_PROFILES,
-    loaders, dataset, addUrl, isRequired,
+    loaders, dataset, isRequired,
     coordinationSetters, initialCoordinationValues, matchOn,
   );
 }
 
 export function useNeighborhoodsData(
-  loaders, dataset, addUrl, isRequired,
+  loaders, dataset, isRequired,
   coordinationSetters, initialCoordinationValues, matchOn,
 ) {
   return useDataType(
     DataType.NEIGHBORHOODS,
-    loaders, dataset, addUrl, isRequired,
+    loaders, dataset, isRequired,
     coordinationSetters, initialCoordinationValues, matchOn,
   );
 }
@@ -193,73 +196,71 @@ export function useFeatureSelection(
   selection,
   matchOn,
 ) {
-  const [geneData, setGeneData] = useState();
-  const [status, setStatus] = useState(STATUS.LOADING);
-  const [loadedGeneName, setLoadedGeneName] = useState(null);
-
   const setWarning = useSetWarning();
-  const loader = useMatchingLoader(loaders, dataset, DataType.OBS_FEATURE_MATRIX, matchOn);
-
-  useEffect(() => {
-    if (!selection) {
-      setGeneData(null);
-      setLoadedGeneName(null);
-      setStatus(STATUS.SUCCESS);
-      return;
-    }
-    if (loader) {
-      setGeneData(null);
-      setLoadedGeneName(null);
-      setStatus(STATUS.LOADING);
-      const implementsGeneSelection = typeof loader.loadGeneSelection === 'function';
-      if (implementsGeneSelection) {
-        loader
-          .loadGeneSelection({ selection })
-          .catch(e => warn(e, setWarning))
-          .then((payload) => {
-            if (!payload) return;
+  const featureQueries = useQueries({
+    queries: selection?.map(featureId => ({
+      structuralSharing: false,
+      placeholderData: null,
+      queryKey: [dataset, DataType.OBS_FEATURE_MATRIX, matchOn, featureId, 'useFeatureSelection'],
+      // Query function should return an object
+      // { data, dataKey } where dataKey is the loaded gene selection.
+      queryFn: async (ctx) => {
+        const loader = getMatchingLoader(
+          ctx.meta.loaders, ctx.queryKey[0], ctx.queryKey[1], ctx.queryKey[2],
+        );
+        if (loader) {
+          const implementsGeneSelection = typeof loader.loadGeneSelection === 'function';
+          if (implementsGeneSelection) {
+            const payload = await loader.loadGeneSelection({ selection: [featureId] });
+            if (!payload) return null;
             const { data } = payload;
-            setGeneData(data);
-            setStatus(STATUS.SUCCESS);
-            setLoadedGeneName(selection);
-          });
-      } else {
-        loader.load().catch(e => warn(e, setWarning)).then((payload) => {
-          if (!payload) return;
+            return { data: data[0], dataKey: selection };
+          }
+          // Loader does not implement loadGeneSelection.
+          const payload = await loader.load();
+          if (!payload) return null;
           const { data } = payload;
           const { obsIndex, featureIndex, obsFeatureMatrix } = data;
-          const expressionDataForSelection = selection.map((sel) => {
-            const geneIndex = featureIndex.indexOf(sel);
-            const numGenes = featureIndex.length;
-            const numCells = obsIndex.length;
-            const expressionData = new Uint8Array(numCells);
-            for (let cellIndex = 0; cellIndex < numCells; cellIndex += 1) {
-              expressionData[cellIndex] = obsFeatureMatrix.data[cellIndex * numGenes + geneIndex];
-            }
-            return expressionData;
-          });
-          setGeneData(expressionDataForSelection);
-          setStatus(STATUS.SUCCESS);
-          setLoadedGeneName(selection);
-        });
-      }
-    } else {
-      setGeneData(null);
-      setLoadedGeneName(null);
-      if (isRequired) {
-        warn(
-          new LoaderNotFoundError(loaders, dataset, DataType.OBS_FEATURE_MATRIX, matchOn),
-          setWarning,
-        );
-        setStatus(STATUS.ERROR);
-      } else {
-        setStatus(STATUS.SUCCESS);
-      }
-    }
+          // Compute expressionData
+          const geneIndex = featureIndex.indexOf(featureId);
+          const numGenes = featureIndex.length;
+          const numCells = obsIndex.length;
+          const expressionData = new Float32Array(numCells);
+          for (let cellIndex = 0; cellIndex < numCells; cellIndex += 1) {
+            expressionData[cellIndex] = obsFeatureMatrix.data[cellIndex * numGenes + geneIndex];
+          }
+          return { data: expressionData, dataKey: featureId };
+        }
+        // No loader was found.
+        if (isRequired) {
+          throw new LoaderNotFoundError(loaders, dataset, DataType.OBS_FEATURE_MATRIX, matchOn);
+        } else {
+          return { data: null, dataKey: null };
+        }
+      },
+      meta: { loaders },
+    })) || [],
+  });
+  const anyLoading = featureQueries.some(q => q.isFetching);
+  const anyError = featureQueries.some(q => q.isError);
+  // eslint-disable-next-line no-nested-ternary
+  const dataStatus = anyLoading ? STATUS.LOADING : (anyError ? STATUS.ERROR : STATUS.SUCCESS);
+  const isSuccess = dataStatus === STATUS.SUCCESS;
+  const geneData = isSuccess ? featureQueries.map(q => q.data?.data || null) : null;
+  const loadedGeneName = isSuccess ? featureQueries.map(q => q.data?.dataKey || null) : null;
+
+  useEffect(() => {
+    featureQueries
+      .map(q => q.error)
+      .filter(e => Boolean(e))
+      .forEach((error) => {
+        warn(error, setWarning);
+      });
+  // Deliberate dependency omissions: use indirect dependencies for efficiency.
   // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [loader, selection]);
+  }, [anyError, setWarning]);
 
-  return [geneData, loadedGeneName, status];
+  return [geneData, loadedGeneName, dataStatus];
 }
 
 /**
@@ -272,68 +273,85 @@ export function useFeatureSelection(
  * datasets and data types to loader instances.
  * @param {string} dataset The key for a dataset,
  * used to identify which loader to use.
- * @param {function} addUrl A function to call to update
- * the URL list.
  * @param {boolean} isRequired Should a warning be thrown if
  * loading is unsuccessful?
  * @returns {object} [attrs] { rows, cols } object containing cell and gene names.
  */
 export function useObsFeatureMatrixIndices(
-  loaders, dataset, addUrl, isRequired, matchOn,
+  loaders, dataset, isRequired, matchOn,
 ) {
-  const [data, setData] = useState({});
-  const [status, setStatus] = useState(STATUS.LOADING);
-
   const setWarning = useSetWarning();
-  const loader = useMatchingLoader(loaders, dataset, DataType.OBS_FEATURE_MATRIX, matchOn);
-
-  useEffect(() => {
-    if (loader) {
-      setStatus(STATUS.LOADING);
-      const implementsLoadAttrs = typeof loader.loadAttrs === 'function';
-      if (implementsLoadAttrs) {
-        loader.loadAttrs().catch(e => warn(e, setWarning)).then((payload) => {
-          if (!payload) return;
-          const { data: payloadData, url } = payload;
-          setData({
-            obsIndex: payloadData.rows,
-            featureIndex: payloadData.cols,
-          });
-          addUrl(url, DataType.OBS_FEATURE_MATRIX);
-          setStatus(STATUS.SUCCESS);
-        });
-      } else {
-        loader.load().catch(e => warn(e, setWarning)).then((payload) => {
-          if (!payload) return;
+  const placeholderObject = useMemo(() => ({}), []);
+  const indicesQuery = useQuery({
+    // TODO: only enable once `loaders` is available?
+    structuralSharing: false,
+    placeholderData: placeholderObject,
+    // Include the hook name in the queryKey to prevent the case in which an identical queryKey
+    // in a different hook would cause an accidental cache hit.
+    queryKey: [dataset, DataType.OBS_FEATURE_MATRIX, matchOn, 'useObsFeatureMatrixIndices'],
+    // Query function should return an object
+    // { data, dataKey } where dataKey is the loaded gene selection.
+    // TODO: use TypeScript to type the return value?
+    queryFn: async (ctx) => {
+      const loader = getMatchingLoader(
+        ctx.meta.loaders, ctx.queryKey[0], ctx.queryKey[1], ctx.queryKey[2],
+      );
+      if (loader) {
+        const implementsLoadAttrs = typeof loader.loadAttrs === 'function';
+        if (implementsLoadAttrs) {
+          // Has loadAttrs function.
+          const payload = await loader.loadAttrs();
+          if (!payload) return placeholderObject;
           const { data: payloadData, url } = payload;
-          setData({
+
+          return {
+            data: {
+              obsIndex: payloadData.rows,
+              featureIndex: payloadData.cols,
+            },
+            urls: [{ url, name: DataType.OBS_FEATURE_MATRIX }],
+          };
+        }
+        // No loadAttrs function.
+        const payload = await loader.load();
+        if (!payload) return placeholderObject;
+        const { data: payloadData, url } = payload;
+        return {
+          data: {
             obsIndex: payloadData.obsIndex,
             featureIndex: payloadData.featureIndex,
-          });
-          addUrl(url, DataType.OBS_FEATURE_MATRIX);
-          setStatus(STATUS.SUCCESS);
-        });
+          },
+          urls: [{ url, name: DataType.OBS_FEATURE_MATRIX }],
+        };
       }
-    } else {
-      setData({});
+      // No loader was found.
       if (isRequired) {
-        warn(
-          new LoaderNotFoundError(loaders, dataset, DataType.OBS_FEATURE_MATRIX, matchOn),
-          setWarning,
-        );
-        setStatus(STATUS.ERROR);
+        // Status: error
+        throw new LoaderNotFoundError(loaders, dataset, DataType.OBS_FEATURE_MATRIX, matchOn);
       } else {
-        setStatus(STATUS.SUCCESS);
+        // Status: success
+        return { data: placeholderObject, dataKey: null };
       }
+    },
+    meta: { loaders },
+  });
+  const { data, status, isFetching, error } = indicesQuery;
+  const loadedData = data?.data || placeholderObject;
+
+  const dataStatus = isFetching ? STATUS.LOADING : status;
+  const urls = data?.urls;
+
+  useEffect(() => {
+    if (error) {
+      setWarning(error.message);
     }
-  // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [loader]);
+  }, [error, setWarning]);
 
-  return [data, status];
+  return [loadedData, dataStatus, urls];
 }
 
 export function useMultiObsLabels(
-  coordinationScopes, obsType, loaders, dataset, addUrl,
+  coordinationScopes, obsType, loaders, dataset,
 ) {
   const obsLabelsTypes = useMultiCoordinationValues(
     CoordinationType.OBS_LABELS_TYPE,
@@ -347,8 +365,9 @@ export function useMultiObsLabels(
   ), [obsLabelsTypes, obsType]);
   const [obsLabelsData, obsLabelsDataStatus] = useDataTypeMulti(
     DataType.OBS_LABELS, loaders, dataset,
-    addUrl, false, {}, {},
+    false, {}, {},
     obsLabelsMatchOnObj,
   );
-  return [obsLabelsTypes, obsLabelsData, obsLabelsDataStatus];
+  const urls = null; // TODO?
+  return [obsLabelsTypes, obsLabelsData, obsLabelsDataStatus, urls];
 }

package/src/errors/DataSourceFetchError.js

@@ -1,4 +1,4 @@
-import AbstractLoaderError from './AbstractLoaderError';
+import AbstractLoaderError from './AbstractLoaderError.js';
 
 export default class DataSourceFetchError extends AbstractLoaderError {
   constructor(source, url, headers) {
@@ -10,6 +10,6 @@ export default class DataSourceFetchError extends AbstractLoaderError {
 
   warnInConsole() {
     const { source, url, headers } = this;
-    console.warn(`${source} failed to fetch from ${url} with headers ${headers}`);
+    console.warn(`${source} failed to fetch from ${url} with headers ${JSON.stringify(headers)}`);
   }
 }

package/src/errors/DatasetNotFoundError.js

@@ -1,4 +1,4 @@
-import AbstractLoaderError from './AbstractLoaderError';
+import AbstractLoaderError from './AbstractLoaderError.js';
 
 export default class DatasetNotFoundError extends AbstractLoaderError {
   constructor(datasetUid) {

package/src/errors/LoaderNotFoundError.js

@@ -1,4 +1,4 @@
-import AbstractLoaderError from './AbstractLoaderError';
+import AbstractLoaderError from './AbstractLoaderError.js';
 
 export default class LoaderNotFoundError extends AbstractLoaderError {
   constructor(loaders, dataset, fileType, viewCoordinationValues) {

package/src/errors/LoaderValidationError.js

@@ -1,4 +1,4 @@
-import AbstractLoaderError from './AbstractLoaderError';
+import AbstractLoaderError from './AbstractLoaderError.js';
 
 export default class LoaderValidationError extends AbstractLoaderError {
   constructor(datasetType, datasetFileType, datasetUrl, reason) {

package/src/errors/index.js

@@ -1,6 +1,5 @@
-export { default as AbstractLoaderError } from './AbstractLoaderError';
-export { default as LoaderValidationError } from './LoaderValidationError';
-export { default as OptionsValidationError } from './OptionsValidationError';
-export { default as LoaderNotFoundError } from './LoaderNotFoundError';
-export { default as DatasetNotFoundError } from './DatasetNotFoundError';
-export { default as DataSourceFetchError } from './DataSourceFetchError';
+export { default as AbstractLoaderError } from './AbstractLoaderError.js';
+export { default as LoaderValidationError } from './LoaderValidationError.js';
+export { default as LoaderNotFoundError } from './LoaderNotFoundError.js';
+export { default as DatasetNotFoundError } from './DatasetNotFoundError.js';
+export { default as DataSourceFetchError } from './DataSourceFetchError.js';

package/src/hooks.js

@@ -1,11 +1,12 @@
 import {
   useRef, useState, useEffect, useCallback, useMemo,
 } from 'react';
-import debounce from 'lodash/debounce';
-import every from 'lodash/every';
+import { debounce, every } from 'lodash-es';
+import { extent } from 'd3-array';
 import { capitalize, fromEntries } from '@vitessce/utils';
-import { useGridResize, useEmitGridResize } from './state/hooks';
-import { VITESSCE_CONTAINER } from './classNames';
+import { STATUS } from '@vitessce/constants-internal';
+import { useGridResize, useEmitGridResize } from './state/hooks.js';
+import { VITESSCE_CONTAINER } from './classNames.js';
 
 function getWindowDimensions() {
   const { innerWidth: width, innerHeight: height } = window;
@@ -137,34 +138,23 @@ export function useDeckCanvasSize() {
  */
 export function useReady(statusValues) {
   return useMemo(() => every(
-    statusValues, val => val === 'success',
+    statusValues, val => val !== STATUS.LOADING,
   // eslint-disable-next-line react-hooks/exhaustive-deps
   ), statusValues);
 }
 
 /**
  * This hook helps manage a list of URLs.
- * @param {object} loaders The loaders dependency.
- * @param {string} dataset The dataset UID dependency.
- * @returns {array} An array
- * [urls, addUrl]
- * where urls is the array of URL objects,
- * and addUrl is a function for adding a URL to the array.
+ * @param {(null|object[])[]} urls Array of (null or array of { url, name }).
+ * @returns {array} An array of { url, name } objects (flattened from the input).
  */
-export function useUrls(loaders, dataset) {
-  const [urls, setUrls] = useState([]);
-
-  const addUrl = useCallback((url, name) => {
-    if (url) {
-      setUrls(prev => ([...prev, { url, name }]));
-    }
-  }, [setUrls]);
-
-  useEffect(() => {
-    setUrls([]);
-  }, [loaders, dataset]);
-
-  return [urls, addUrl];
+export function useUrls(urls) {
+  const mergedUrls = useMemo(
+    () => urls.filter(a => Array.isArray(a)).flat(),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    urls,
+  );
+  return mergedUrls;
 }
 
 /**
@@ -199,7 +189,63 @@ export function useClosestVitessceContainerSize(ref) {
   return [width, height];
 }
 
-export function useExpressionValueGetter({ instanceObsIndex, matrixObsIndex, expressionData }) {
+/**
+ * Normalize an obsFeatureMatrix to a Uint8Array.
+ * @param {object} params
+ * @param {object} params.obsFeatureMatrix The obsFeatureMatrix
+ * returned by the useObsFeatureMatrix hook.
+ * @returns {array} A tuple [obsFeatureMatrix, dataExtent]
+ * where obsFeatureMatrix
+ * is a Uint8Array with the same shape as
+ * params.obsFeatureMatrix.data, and dataExtent is the
+ * [min, max] of the original data.
+ */
+export function useUint8ObsFeatureMatrix({ obsFeatureMatrix }) {
+  return useMemo(() => {
+    if (obsFeatureMatrix && obsFeatureMatrix.data) {
+      const dataExtent = extent(obsFeatureMatrix.data);
+      const [min, max] = dataExtent;
+      const ratio = 255 / (max - min);
+      const data = new Uint8Array(
+        obsFeatureMatrix.data.map(i => Math.floor((i - min) * ratio)),
+      );
+      return [{ data }, dataExtent];
+    }
+    return [null, null];
+  }, [obsFeatureMatrix]);
+}
+
+/**
+ * Normalize a feature selection (data for selected
+ * columns of an obsFeatureMatrix) to a Uint8Array.
+ * @param {array|null} expressionData The expressionData
+ * returned by the useFeatureSelection hook,
+ * where each element corresponds to an
+ * array of values for a selected feature.
+ * @returns {array} A tuple [normData, extents] where
+ * normData is an array of Uint8Arrays (or null), and extents is
+ * an array of [min, max] values for each feature (or null).
+ */
+export function useUint8FeatureSelection(expressionData) {
+  return useMemo(() => {
+    if (expressionData && expressionData[0]) {
+      const extents = expressionData.map(arr => extent(arr));
+      const normData = expressionData.map((arr, i) => {
+        const [min, max] = extents[i];
+        const ratio = 255 / (max - min);
+        return new Uint8Array(
+          arr.map(j => Math.floor((j - min) * ratio)),
+        );
+      });
+      return [normData, extents];
+    }
+    return [null, null];
+  }, [expressionData]);
+}
+
+export function useExpressionValueGetter(
+  { instanceObsIndex, matrixObsIndex, expressionData },
+) {
   // Get a mapping from cell ID to row index in the gene expression matrix.
   // Since the two obsIndices (instanceObsIndex = the obsIndex from obsEmbedding)
   // may be ordered differently (matrixObsIndex = the obsIndex from obsFeatureMatrix),
@@ -226,6 +272,15 @@ export function useExpressionValueGetter({ instanceObsIndex, matrixObsIndex, exp
   return getExpressionValue;
 }
 
+export function useGetObsMembership(obsSetsMembership) {
+  return useCallback((obsId) => {
+    if (obsId) {
+      return obsSetsMembership?.get(obsId) || [];
+    }
+    return [];
+  }, [obsSetsMembership]);
+}
+
 export function useGetObsInfo(obsType, obsLabelsTypes, obsLabelsData, obsSetsMembership) {
   return useCallback((obsId) => {
     if (obsId) {