@vitessce/vit-s 2.0.3-beta.0 → 3.0.0

package/src/data-hooks.js

@@ -0,0 +1,354 @@
+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.js';
+import {
+  LoaderNotFoundError,
+} from './errors/index.js';
+import {
+  warn,
+  useDataType,
+  useDataTypeMulti,
+} from './data-hook-utils.js';
+
+/**
+ * Get the dataset description string.
+ * @param {object} loaders The object mapping
+ * datasets and data types to loader instances.
+ * @param {string} dataset The key for a dataset,
+ * used to identify which loader to use.
+ * @returns {array} [description] where
+ * description is a string.
+ */
+export function useDescription(loaders, dataset) {
+  const [description, setDescription] = useState();
+
+  useEffect(() => {
+    if (!loaders[dataset]) {
+      return;
+    }
+
+    if (loaders[dataset].description) {
+      setDescription(loaders[dataset].description);
+    } else {
+      setDescription(null);
+    }
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [loaders, dataset]);
+
+  return [description];
+}
+
+/**
+ * Get data from a cells data type loader,
+ * updating "ready" and URL state appropriately.
+ * Throw warnings if the data is marked as required.
+ * Subscribe to loader updates.
+ * @param {object} loaders The object mapping
+ * 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
+ * keys are coordination type names with the prefix 'set',
+ * values are coordination setter functions.
+ * @param {object} initialCoordinationValues Object where
+ * keys are coordination type names with the prefix 'initialize',
+ * values are initialization preferences as boolean values.
+ * @returns {array} [cells, cellsCount] where
+ * cells is an object and cellsCount is the
+ * number of items in the cells object.
+ */
+export function useObsEmbeddingData(
+  loaders, dataset, addUrl, isRequired,
+  coordinationSetters, initialCoordinationValues, matchOn,
+) {
+  return useDataType(
+    DataType.OBS_EMBEDDING,
+    loaders, dataset, addUrl, isRequired,
+    coordinationSetters, initialCoordinationValues, matchOn,
+  );
+}
+
+export function useObsLocationsData(
+  loaders, dataset, addUrl, isRequired,
+  coordinationSetters, initialCoordinationValues, matchOn,
+) {
+  return useDataType(
+    DataType.OBS_LOCATIONS,
+    loaders, dataset, addUrl, isRequired,
+    coordinationSetters, initialCoordinationValues, matchOn,
+  );
+}
+
+export function useObsLabelsData(
+  loaders, dataset, addUrl, isRequired,
+  coordinationSetters, initialCoordinationValues, matchOn,
+) {
+  return useDataType(
+    DataType.OBS_LABELS,
+    loaders, dataset, addUrl, isRequired,
+    coordinationSetters, initialCoordinationValues, matchOn,
+  );
+}
+
+export function useObsSegmentationsData(
+  loaders, dataset, addUrl, isRequired,
+  coordinationSetters, initialCoordinationValues, matchOn,
+) {
+  return useDataType(
+    DataType.OBS_SEGMENTATIONS,
+    loaders, dataset, addUrl, isRequired,
+    coordinationSetters, initialCoordinationValues, matchOn,
+  );
+}
+
+export function useObsSetsData(
+  loaders, dataset, addUrl, isRequired,
+  coordinationSetters, initialCoordinationValues, matchOn,
+) {
+  return useDataType(
+    DataType.OBS_SETS,
+    loaders, dataset, addUrl, isRequired,
+    coordinationSetters, initialCoordinationValues, matchOn,
+  );
+}
+
+export function useObsFeatureMatrixData(
+  loaders, dataset, addUrl, isRequired,
+  coordinationSetters, initialCoordinationValues, matchOn,
+) {
+  return useDataType(
+    DataType.OBS_FEATURE_MATRIX,
+    loaders, dataset, addUrl, isRequired,
+    coordinationSetters, initialCoordinationValues, matchOn,
+  );
+}
+
+export function useFeatureLabelsData(
+  loaders, dataset, addUrl, isRequired,
+  coordinationSetters, initialCoordinationValues, matchOn,
+) {
+  return useDataType(
+    DataType.FEATURE_LABELS,
+    loaders, dataset, addUrl, isRequired,
+    coordinationSetters, initialCoordinationValues, matchOn,
+  );
+}
+
+export function useImageData(
+  loaders, dataset, addUrl, isRequired,
+  coordinationSetters, initialCoordinationValues, matchOn,
+) {
+  return useDataType(
+    DataType.IMAGE,
+    loaders, dataset, addUrl, isRequired,
+    coordinationSetters, initialCoordinationValues, matchOn,
+  );
+}
+
+export function useGenomicProfilesData(
+  loaders, dataset, addUrl, isRequired,
+  coordinationSetters, initialCoordinationValues, matchOn,
+) {
+  return useDataType(
+    DataType.GENOMIC_PROFILES,
+    loaders, dataset, addUrl, isRequired,
+    coordinationSetters, initialCoordinationValues, matchOn,
+  );
+}
+
+export function useNeighborhoodsData(
+  loaders, dataset, addUrl, isRequired,
+  coordinationSetters, initialCoordinationValues, matchOn,
+) {
+  return useDataType(
+    DataType.NEIGHBORHOODS,
+    loaders, dataset, addUrl, isRequired,
+    coordinationSetters, initialCoordinationValues, matchOn,
+  );
+}
+
+/**
+ * Get data from the expression matrix data type loader for a given gene selection.
+ * Throw warnings if the data is marked as required.
+ * Subscribe to loader updates.
+ * @param {object} loaders The object mapping
+ * datasets and data types to loader instances.
+ * @param {string} dataset The key for a dataset,
+ * used to identify which loader to use.
+ * @param {boolean} isRequired Should a warning be thrown if
+ * loading is unsuccessful?
+ * @param {boolean} selection A list of gene names to get expression data for.
+ * @returns {array} [geneData] where geneData is an array [Uint8Array, ..., Uint8Array]
+ * for however many genes are in the selection.
+ */
+export function useFeatureSelection(
+  loaders,
+  dataset,
+  isRequired,
+  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 { data } = payload;
+            setGeneData(data);
+            setStatus(STATUS.SUCCESS);
+            setLoadedGeneName(selection);
+          });
+      } else {
+        loader.load().catch(e => warn(e, setWarning)).then((payload) => {
+          if (!payload) return;
+          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 Float32Array(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);
+      }
+    }
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [loader, selection]);
+
+  return [geneData, loadedGeneName, status];
+}
+
+/**
+ * Get the attributes for the expression matrix data type loader,
+ * i.e names of cells and genes.
+ * Throw warnings if the data is marked as required.
+ * Subscribe to loader updates.  Should not be used in conjunction (called in the same component)
+ * with useExpressionMatrixData.
+ * @param {object} loaders The object mapping
+ * 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,
+) {
+  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 { data: payloadData, url } = payload;
+          setData({
+            obsIndex: payloadData.obsIndex,
+            featureIndex: payloadData.featureIndex,
+          });
+          addUrl(url, DataType.OBS_FEATURE_MATRIX);
+          setStatus(STATUS.SUCCESS);
+        });
+      }
+    } else {
+      setData({});
+      if (isRequired) {
+        warn(
+          new LoaderNotFoundError(loaders, dataset, DataType.OBS_FEATURE_MATRIX, matchOn),
+          setWarning,
+        );
+        setStatus(STATUS.ERROR);
+      } else {
+        setStatus(STATUS.SUCCESS);
+      }
+    }
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [loader]);
+
+  return [data, status];
+}
+
+export function useMultiObsLabels(
+  coordinationScopes, obsType, loaders, dataset, addUrl,
+) {
+  const obsLabelsTypes = useMultiCoordinationValues(
+    CoordinationType.OBS_LABELS_TYPE,
+    coordinationScopes,
+  );
+  const obsLabelsMatchOnObj = useMemo(() => fromEntries(
+    Object.entries(obsLabelsTypes).map(([scope, obsLabelsType]) => ([
+      scope,
+      { obsLabelsType, obsType },
+    ])),
+  ), [obsLabelsTypes, obsType]);
+  const [obsLabelsData, obsLabelsDataStatus] = useDataTypeMulti(
+    DataType.OBS_LABELS, loaders, dataset,
+    addUrl, false, {}, {},
+    obsLabelsMatchOnObj,
+  );
+  return [obsLabelsTypes, obsLabelsData, obsLabelsDataStatus];
+}

package/src/errors/AbstractLoaderError.js

@@ -0,0 +1,14 @@
+/**
+ * A loader error ancestor class containing a default constructor
+ * and a stub for the required warnInConsole() method.
+ */
+export default class AbstractLoaderError {
+  constructor(message) {
+    this.message = message;
+  }
+
+  // eslint-disable-next-line class-methods-use-this
+  warnInConsole() {
+    throw new Error('The warnInConsole() method has not been implemented.');
+  }
+}

package/src/errors/DataSourceFetchError.js

@@ -0,0 +1,15 @@
+import AbstractLoaderError from './AbstractLoaderError.js';
+
+export default class DataSourceFetchError extends AbstractLoaderError {
+  constructor(source, url, headers) {
+    super(`${source} Error HTTP Status fetching from ${url}`);
+    this.source = source;
+    this.url = url;
+    this.headers = headers;
+  }
+
+  warnInConsole() {
+    const { source, url, headers } = this;
+    console.warn(`${source} failed to fetch from ${url} with headers ${headers}`);
+  }
+}

package/src/errors/DatasetNotFoundError.js

@@ -0,0 +1,23 @@
+import AbstractLoaderError from './AbstractLoaderError.js';
+
+export default class DatasetNotFoundError extends AbstractLoaderError {
+  constructor(datasetUid) {
+    super(`Error finding dataset for ${datasetUid}. Please check that at least one dataset exists in the view config.`);
+    this.name = 'DatasetNotFoundError';
+
+    this.datasetUid = datasetUid;
+  }
+
+  warnInConsole() {
+    const {
+      datasetUid,
+    } = this;
+    if (datasetUid) {
+      console.warn(
+        `Unable to find dataset for ${datasetUid}`,
+      );
+    } else {
+      console.warn('No dataset uid specified.');
+    }
+  }
+}

package/src/errors/LoaderNotFoundError.js

@@ -0,0 +1,24 @@
+import AbstractLoaderError from './AbstractLoaderError.js';
+
+export default class LoaderNotFoundError extends AbstractLoaderError {
+  constructor(loaders, dataset, fileType, viewCoordinationValues) {
+    super(`Error: unable to find matching ${fileType} file in dataset ${dataset}.`);
+    this.name = 'LoaderNotFoundError';
+
+    this.loaders = loaders;
+    this.dataset = dataset;
+    this.fileType = fileType;
+    this.viewCoordinationValues = viewCoordinationValues;
+  }
+
+  warnInConsole() {
+    const {
+      loaders, viewCoordinationValues,
+    } = this;
+    console.warn(
+      // eslint-disable-next-line prefer-template
+      `Expected to match on { ${Object.entries(viewCoordinationValues).map(([k, v]) => k + ': ' + v).join(', ')} }`,
+      loaders,
+    );
+  }
+}

package/src/errors/LoaderValidationError.js

@@ -0,0 +1,23 @@
+import AbstractLoaderError from './AbstractLoaderError.js';
+
+export default class LoaderValidationError extends AbstractLoaderError {
+  constructor(datasetType, datasetFileType, datasetUrl, reason) {
+    super(`Error while validating ${datasetType}.`);
+    this.name = 'LoaderValidationError';
+
+    this.datasetType = datasetType;
+    this.datasetFileType = datasetFileType;
+    this.datasetUrl = datasetUrl;
+    this.reason = reason;
+  }
+
+  warnInConsole() {
+    const {
+      datasetType, datasetUrl, reason,
+    } = this;
+    console.warn(
+      `${datasetType} from ${datasetUrl}: validation failed`,
+      JSON.stringify(reason, null, 2),
+    );
+  }
+}

package/src/errors/index.js

@@ -0,0 +1,5 @@
+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';