@vitessce/vit-s 2.0.2 → 2.0.3

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';
+import {
+  LoaderNotFoundError,
+} from './errors/index';
+import {
+  warn,
+  useDataType,
+  useDataTypeMulti,
+} from './data-hook-utils';
+
+/**
+ * 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 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);
+      }
+    }
+  // 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';
+
+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';
+
+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';
+
+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';
+
+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/OptionsValidationError.js

@@ -0,0 +1,25 @@
+import AbstractLoaderError from './AbstractLoaderError';
+
+export default class OptionsValidationError extends AbstractLoaderError {
+  constructor(fileType, url, options, reason) {
+    super(`Error while validating file definition options: ${fileType} from ${url}.`);
+    this.name = 'OptionsValidationError';
+
+    this.fileType = fileType;
+    this.url = url;
+    this.options = options;
+    this.reason = reason;
+  }
+
+  warnInConsole() {
+    const {
+      options, reason,
+    } = this;
+    console.warn(
+      'Received options\n',
+      JSON.stringify(options, null, 2),
+      'JSON schema validation failure reason\n',
+      JSON.stringify(reason, null, 2),
+    );
+  }
+}

package/src/file-options-schemas-legacy.js

@@ -0,0 +1,139 @@
+export const cellsJsonSchema = {
+  $schema: 'http://json-schema.org/draft-07/schema#',
+  $id: 'https://github.com/vitessce/vitessce/#cells-json-options',
+  title: 'cells.json options',
+  oneOf: [
+    { type: 'null' },
+    {
+      type: 'object',
+      additionalProperties: false,
+      required: [],
+      properties: {
+        obsLabelsTypes: {
+          type: 'array',
+          items: { type: 'string' },
+        },
+        embeddingTypes: {
+          type: 'array',
+          items: { type: 'string' },
+        },
+      },
+    },
+  ],
+};
+
+export const anndataCellsZarrSchema = {
+  $schema: 'http://json-schema.org/draft-07/schema#',
+  $id: 'https://github.com/vitessce/vitessce/#anndata-cells-zarr-options',
+  title: 'anndata-cells.zarr options',
+  type: 'object',
+  minProperties: 1,
+  additionalProperties: false,
+  required: [],
+  properties: {
+    xy: {
+      type: 'string',
+      description: "The location in the AnnData store of cell centroids, like 'obsm/X_centroids.'",
+    },
+    poly: {
+      type: 'string',
+      description: "The location in the AnnData store of cell polygon outlines, like 'obsm/X_polygons.'",
+    },
+    factors: {
+      type: 'array',
+      description: "List of locations in the AnnData store of cell sets, like 'obs/louvain'",
+      items: {
+        type: 'string',
+      },
+    },
+    mappings: {
+      patternProperties: {
+        '.': {
+          type: 'object',
+          description: "An object containing key-values for mappings like { UMAP: { key: 'obsm/X_umap', dims: [0, 1] } }.",
+          additionalProperties: false,
+          required: ['key'],
+          properties: {
+            key: {
+              type: 'string',
+              description: "Where to look in the AnnData store for this mapping, like 'obsm/X_umap.'",
+            },
+            dims: {
+              type: 'array',
+              description: 'Which indices of the obsm object to take for a scatterplot, allowing for, for example, different PCs from obsm/X_pca',
+              minItems: 2,
+              maxItems: 2,
+              items: { type: 'number' },
+            },
+          },
+        },
+      },
+    },
+  },
+};
+
+export const anndataCellSetsZarrSchema = {
+  $schema: 'http://json-schema.org/draft-07/schema#',
+  $id: 'https://github.com/vitessce/vitessce/#anndata-cell-sets-zarr-options',
+  title: 'anndata-cell-sets.zarr options',
+  type: 'array',
+  items: {
+    type: 'object',
+    additionalProperties: false,
+    required: ['groupName', 'setName'],
+    properties: {
+      groupName: {
+        type: 'string',
+        description: "The display name for the set, like 'Cell Type' or 'Louvain.'",
+      },
+      setName: {
+        oneOf: [
+          {
+            type: 'string',
+            description: "The location in the AnnData store for the set, like 'obs/louvain' or 'obs/celltype.'",
+          },
+          {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'An array of locations in the AnnData store for a hierarchy of set names, from coarse to fine levels.',
+          },
+        ],
+      },
+      scoreName: {
+        oneOf: [
+          {
+            type: 'string',
+            description: "The location in the AnnData store for the set confidence scores, like 'obs/celltype_prediction_score.'",
+          },
+        ],
+      },
+    },
+  },
+};
+
+export const anndataExpressionMatrixZarrSchema = {
+  $schema: 'http://json-schema.org/draft-07/schema#',
+  $id: 'https://github.com/vitessce/vitessce/#anndata-expression-matrix-zarr-options',
+  title: 'anndata-expression-matrix.zarr options',
+  type: 'object',
+  additionalProperties: false,
+  required: ['matrix'],
+  properties: {
+    matrix: {
+      type: 'string',
+      description: "The location in the AnnData store of the cell x gene matrix, like 'obsm/hvg_subset.' or 'X'",
+    },
+    geneFilter: {
+      type: 'string',
+      description: "The location in the AnnData store of a filter for the genes if using a subset of the data, like 'var.highly_variable.' if the matrix comes from 'obsm/hvg_subset.'",
+    },
+    matrixGeneFilter: {
+      type: 'string',
+      description: "The location in the AnnData store of a filter for the matrix data (used in heatmap and histogram), like 'var.highly_variable.''",
+    },
+    geneAlias: {
+      type: 'string',
+      description: 'The location in the AnnData store of a different list of names for gene list component, other than the `var` index',
+    },
+  },
+};