Tkakar/cat 946 map ensemble ids (#1970)

Co-authored-by: Mark Keller <7525285+keller-mark@users.noreply.github.com>
vitessce · Dec 19, 2024 · ffa8d5f · ffa8d5f
1 parent 5503589
commit ffa8d5f
Show file tree

Hide file tree

Showing 29 changed files with 336 additions and 31 deletions.
diff --git a/.changeset/kind-eagles-live.md b/.changeset/kind-eagles-live.md
@@ -0,0 +1,8 @@
+---
+"@vitessce/feature-list": patch
+"@vitessce/heatmap": patch
+"@vitessce/tooltip": patch
+"@vitessce/vit-s": patch
+---
+
+Added support for mapping ensemble gene ids to gene symbols.
diff --git a/examples/configs/src/index.js b/examples/configs/src/index.js
@@ -51,7 +51,6 @@ import { alignedVisiumXeniumSpatialdata } from './view-configs/spatial-beta/spat
 import { exemplarSmall2024, exemplarSmallPartialInit } from './view-configs/spatial-beta/exemplar-small.js';
 import { lake2023, lake2023component } from './view-configs/lake-2023.js';
 import { salcher2022 } from './view-configs/salcher_2022.js';
-
 // TODO(spatialBeta):
 import { kpmpOop2023 } from './view-configs/spatial-beta/kpmp-oop.js';
 import { kpmpAutoInit2023 } from './view-configs/spatial-beta/kpmp-auto-init.js';

diff --git a/packages/constants-internal/src/constants.ts b/packages/constants-internal/src/constants.ts
@@ -45,6 +45,8 @@ export const DataType = {
 export const AsyncFunctionType = {
   // String input (rather than Node input)
   AUTOCOMPLETE_FEATURE: 'autocompleteFeature', // (partial: string, targetModality: null | 'gene' | 'protein' | 'genomic-region' | 'cell-type') -> list of feature nodes
+  GET_ALTERNATIVE_TERMS: 'getAlternativeTerms', // (curieString) -> list of alternative curie strings
+  GET_TERM_MAPPING: 'getTermMapping', // (keyCuriePrefix, valueCuriePrefix) -> Record<curieString, curieString> for key to value
 
   TRANSFORM_FEATURE: 'transformFeature', // (featureNode, targetModality) -> list of feature nodes from target modality
   RELATED_FEATURES: 'relatedFeatures', // (featureNode) -> list of related feature nodes

diff --git a/packages/legend/src/Legend.js b/packages/legend/src/Legend.js
@@ -1,7 +1,7 @@
 import React, { useRef, useEffect, useMemo } from 'react';
 import clsx from 'clsx';
 import { makeStyles } from '@material-ui/core';
-import { capitalize, getDefaultColor } from '@vitessce/utils';
+import { capitalize, getDefaultColor, cleanFeatureId } from '@vitessce/utils';
 import { select } from 'd3-selection';
 import { scaleLinear } from 'd3-scale';
 import { axisBottom } from 'd3-axis';
@@ -320,7 +320,11 @@ export default function Legend(props) {
       && featureSelection.length >= 1
       && !isStaticColor
     )
-      ? (featureLabelsMap?.get(featureSelection[0]) || featureSelection[0])
+      ? (
+        featureLabelsMap?.get(featureSelection[0])
+        || featureLabelsMap?.get(cleanFeatureId(featureSelection[0]))
+        || featureSelection[0]
+      )
       : null;
     // if there are missing values, mention them in the label
     const featureSelectionLabel = missing ? `${featureSelectionLabelRaw} (${Math.round(missing * 100)}% NaN)` : featureSelectionLabelRaw;

diff --git a/packages/main/all/src/base-plugins.ts b/packages/main/all/src/base-plugins.ts
@@ -168,6 +168,8 @@ import {
   BiomarkerSelectSubscriber,
   autocompleteFeature,
   transformFeature,
+  getAlternativeTerms,
+  getTermMapping,
 } from '@vitessce/biomarker-select';
 import {
   expandAnndataZarr,
@@ -533,4 +535,6 @@ export const baseCoordinationTypes = [
 export const baseAsyncFunctions = [
   new PluginAsyncFunction(AsyncFunctionType.AUTOCOMPLETE_FEATURE, autocompleteFeature),
   new PluginAsyncFunction(AsyncFunctionType.TRANSFORM_FEATURE, transformFeature),
+  new PluginAsyncFunction(AsyncFunctionType.GET_ALTERNATIVE_TERMS, getAlternativeTerms),
+  new PluginAsyncFunction(AsyncFunctionType.GET_TERM_MAPPING, getTermMapping),
 ];
diff --git a/packages/tooltip/package.json b/packages/tooltip/package.json
@@ -31,7 +31,8 @@
   },
   "dependencies": {
     "@material-ui/core": "catalog:",
-    "@vitessce/vit-s": "workspace:*"
+    "@vitessce/vit-s": "workspace:*",
+    "@vitessce/utils": "workspace:*"
   },
   "devDependencies": {
     "react": "catalog:",

diff --git a/packages/tooltip/src/TooltipContent.js b/packages/tooltip/src/TooltipContent.js
@@ -1,14 +1,24 @@
-import React from 'react';
+import React, { useMemo } from 'react';
+import { transformInfoValues } from './utils.js';
 
 export default function TooltipContent(props) {
   const {
     info,
+    featureType,
+    featureLabelsMap,
   } = props;
 
+  const mappedInfo = useMemo(() => {
+    if (!featureType || !featureLabelsMap) {
+      return info;
+    }
+    return transformInfoValues(info, featureType, featureLabelsMap);
+  }, [info, featureType, featureLabelsMap]);
+
   return (
     <table>
       <tbody>
-        {Object.entries(info).map(([key, value]) => (
+        {Object.entries(mappedInfo).map(([key, value]) => (
           <tr key={key}>
             <th>{key}</th>
             <td>{value}</td>

diff --git a/packages/tooltip/src/utils.js b/packages/tooltip/src/utils.js
@@ -0,0 +1,31 @@
+import { cleanFeatureId } from '@vitessce/utils';
+
+/**
+ * Use the featureLabelsMap to transform the values in the info object.
+ * For example, there are cases where the info object looks like
+ * { "Marker Gene ID": "ENSG00000123456.1" }
+ * And we want to transform the values into Gene Symbols instead of Ensembl IDs.
+ * @param {object} info
+ * @param {string} featureType
+ * @param {Map<string,string>} featureLabelsMap
+ * @returns
+ */
+export function transformInfoValues(info, featureType, featureLabelsMap) {
+  if (info) {
+    const newInfo = Object.fromEntries(
+      Object.entries(info).map(([key, value]) => {
+        if (key.toLowerCase().includes(featureType.toLowerCase())) {
+          const newValue = (
+            featureLabelsMap?.get(value)
+                        || featureLabelsMap?.get(cleanFeatureId(value))
+                        || value
+          );
+          return [key, newValue];
+        }
+        return [key, value];
+      }),
+    );
+    return newInfo;
+  }
+  return info;
+}
diff --git a/packages/types/src/biomarkers.ts b/packages/types/src/biomarkers.ts
@@ -72,3 +72,7 @@ export type FeatureToIntervalFunc = (node: KgNode, assembly: string) => Promise<
 // TODO: should the node types be more precise?
 export type ObsSetToFeaturesFunc = (node: KgNode) => Promise<KgNode[]>;
 export type FeaturesToObsSetFunc = (nodes: KgNode[]) => Promise<KgNode>;
+
+// Other async function types.
+export type GetAlternativeTermsFunc = (curie: string) => Promise<string[]>;
+export type GetTermMappingFunc = (keyCuriePrefix: string, valCuriePrefix: string) => Promise<Map<string, string>>;
diff --git a/packages/types/src/index.ts b/packages/types/src/index.ts
@@ -48,6 +48,8 @@ export type {
   FeatureToIntervalFunc,
   ObsSetToFeaturesFunc,
   FeaturesToObsSetFunc,
+  GetAlternativeTermsFunc,
+  GetTermMappingFunc,
 } from './biomarkers.js';
 
 // This is a types-only package.

diff --git a/packages/utils/other-utils/src/index.ts b/packages/utils/other-utils/src/index.ts
@@ -3,6 +3,7 @@ export {
   commaNumber,
   capitalize,
   pluralize,
+  cleanFeatureId,
   getLongestString,
   getNextScope,
   getNextScopeNumeric,

diff --git a/packages/utils/other-utils/src/root.ts b/packages/utils/other-utils/src/root.ts
@@ -41,6 +41,20 @@ export function getLongestString(strings: string[]) {
   );
 }
 
+/**
+ * Try to clean up a gene ID.
+ * For example, remove the version number from an ENSG ID.
+ * @param {string} featureName A gene ID.
+ * @returns {string} The cleaned gene ID.
+ */
+export function cleanFeatureId(featureName: string) {
+  if (featureName.startsWith('ENSG')) {
+    // Strip the version number from the ENSG ID.
+    return featureName.split('.')[0];
+  }
+  return featureName;
+}
+
 /**
  * Generate a new scope name which does not
  * conflict / overlap with a previous scope name.

diff --git a/packages/view-types/biomarker-select/src/default-async-functions.js b/packages/view-types/biomarker-select/src/default-async-functions.js
@@ -5,10 +5,11 @@ import { csvParse } from 'd3-dsv';
 // eslint-disable-next-line import/no-unresolved
 import Fuse from 'fuse.js/basic';
 
-/** @import { KgNode, KgEdge, TargetModalityType, AutocompleteFeatureFunc, TransformFeatureFunc } from '@vitessce/types' */
+/** @import { KgNode, KgEdge, TargetModalityType, AutocompleteFeatureFunc, TransformFeatureFunc, GetAlternativeTermsFunc, GetTermMappingFunc } from '@vitessce/types' */
 /** @import { QueryClient, QueryFunctionContext } from '@tanstack/react-query' */
 
 const KG_BASE_URL = 'https://storage.googleapis.com/vitessce-demo-data/enrichr-kg-september-2023';
+const ENSG_TO_GENE_SYMBOL_URL = 'https://vitessce-resources.s3.us-east-2.amazonaws.com/genes_filtered.json';
 
 /**
  * @returns {Promise<KgNode[]>}
@@ -61,6 +62,14 @@ function loadPathwayNodes() {
     });
 }
 
+/**
+ * @returns {Promise<Record<string,string>>}
+ */
+function loadEnsgToGeneSymbolMapping() {
+  return fetch(ENSG_TO_GENE_SYMBOL_URL)
+    .then(res => res.json());
+}
+
 // Parent app can pass in queryClient
 // (to every async function) so that functions can call .fetchQuery
 // Reference: https://tanstack.com/query/latest/docs/reference/QueryClient#queryclientfetchquery
@@ -185,3 +194,65 @@ export async function transformFeature({ queryClient }, node, targetModality) {
   // TODO: handle other target modalities
   return [];
 }
+
+/**
+ * @satisfies {GetAlternativeTermsFunc}
+ * @param {object} ctx
+ * @param {QueryClient} ctx.queryClient
+ * @param {string} curie
+ * @returns {Promise<string[]>} A list of curie strings.
+ */
+export async function getAlternativeTerms({ queryClient }, curie) {
+  // Reference: https://registry.identifiers.org/registry/ensembl
+  // Currently, we only map Ensembl gene IDs to gene symbols,
+  // using our own JSON file.
+  // In the future, we can expand this functionality.
+  const inputIsEnsemblGeneId = curie.toUpperCase().startsWith('ENSEMBL:ENSG');
+
+  if (inputIsEnsemblGeneId) {
+    const idMapping = await queryClient.fetchQuery({
+      queryKey: ['ensgToGeneSymbolMapping'],
+      staleTime: Infinity,
+      queryFn: loadEnsgToGeneSymbolMapping,
+    });
+    // In our current JSON file, the ENSG IDs are not prefixed with 'ENSEMBL:'.
+    const ensemblId = curie.split(':')[1];
+    let geneSymbol = idMapping?.[ensemblId];
+    if (geneSymbol) {
+      if (!geneSymbol.toUpperCase().startsWith('HGNC:')) {
+        // In our current JSON file, the gene symbols are not prefixed with 'HGNC:'.
+        geneSymbol = `HGNC:${geneSymbol}`;
+      }
+      return [geneSymbol];
+    }
+  }
+  return [];
+}
+
+/**
+ * @satisfies {GetTermMappingFunc}
+ * @param {object} ctx
+ * @param {QueryClient} ctx.queryClient
+ * @param {string} keyCuriePrefix
+ * @param {string} valCuriePrefix
+ * @returns {Promise<Map<string, string>>} A mapping between curie strings.
+ */
+export async function getTermMapping({ queryClient }, keyCuriePrefix, valCuriePrefix) {
+  if (
+    (keyCuriePrefix.toUpperCase() === 'ENSEMBL' && valCuriePrefix.toUpperCase() === 'HGNC')
+    || (keyCuriePrefix.toUpperCase() === 'HGNC' && valCuriePrefix.toUpperCase() === 'ENSEMBL')
+  ) {
+    const idMapping = await queryClient.fetchQuery({
+      queryKey: ['ensgToGeneSymbolMapping'],
+      staleTime: Infinity,
+      queryFn: loadEnsgToGeneSymbolMapping,
+    });
+    const isReversed = (keyCuriePrefix.toUpperCase() === 'HGNC');
+    return new Map(Object.entries(idMapping).map(([key, value]) => (
+      isReversed
+        ? ([`HGNC:${value}`, `ENSEMBL:${key}`])
+        : ([`ENSEMBL:${key}`, `HGNC:${value}`])
+    )));
+  }
+  throw new Error(`Mapping between ${keyCuriePrefix} and ${valCuriePrefix} is not yet implemented.`);
+}
diff --git a/packages/view-types/biomarker-select/src/index.js b/packages/view-types/biomarker-select/src/index.js
@@ -2,4 +2,6 @@ export { BiomarkerSelectSubscriber } from './BiomarkerSelectSubscriber.js';
 export {
   autocompleteFeature,
   transformFeature,
+  getAlternativeTerms,
+  getTermMapping,
 } from './default-async-functions.js';
diff --git a/packages/view-types/feature-list/src/FeatureList.js b/packages/view-types/feature-list/src/FeatureList.js
@@ -1,6 +1,7 @@
 import React, { useEffect, useState, useMemo } from 'react';
 import { every } from 'lodash-es';
 import { makeStyles } from '@material-ui/core';
+import { cleanFeatureId } from '@vitessce/utils';
 import { SelectableTable } from './selectable-table/index.js';
 import { ALT_COLNAME } from './constants.js';
 
@@ -39,12 +40,14 @@ export default function FeatureList(props) {
   // passing to the SelectableTable component.
   const selectableTableSortKey = (featureListSortKey === 'featureIndex' ? 'key' : 'name');
 
-
   useEffect(() => {
     const results = geneList
       .filter(gene => (
         gene.toLowerCase().includes(searchTerm.toLowerCase())
-        || featureLabelsMap?.get(gene)?.toLowerCase().includes(searchTerm.toLowerCase())
+        || featureLabelsMap?.get(gene)
+          ?.toLowerCase().includes(searchTerm.toLowerCase())
+        || featureLabelsMap?.get(cleanFeatureId(gene))
+          ?.toLowerCase().includes(searchTerm.toLowerCase())
       ));
     setSearchResults(results);
   }, [searchTerm, geneList, featureLabelsMap]);
@@ -69,7 +72,11 @@ export default function FeatureList(props) {
       .map(
         gene => ({
           key: gene,
-          name: featureLabelsMap?.get(gene) || gene,
+          name: (
+            featureLabelsMap?.get(gene)
+            || featureLabelsMap?.get(cleanFeatureId(gene))
+            || gene
+          ),
           value: (geneSelection ? geneSelection.includes(gene) : false),
         }),
       );

diff --git a/packages/view-types/feature-list/src/FeatureListSubscriber.js b/packages/view-types/feature-list/src/FeatureListSubscriber.js
@@ -5,6 +5,7 @@ import {
   useReady, useUrls,
   useFeatureLabelsData, useObsFeatureMatrixIndices,
   useCoordination, useLoaders,
+  useExpandedFeatureLabelsMap,
 } from '@vitessce/vit-s';
 import { ViewType, COMPONENT_COORDINATION_TYPES, ViewHelpMapping } from '@vitessce/constants-internal';
 import FeatureList from './FeatureList.js';
@@ -75,21 +76,26 @@ export function FeatureListSubscriber(props) {
     loaders, dataset, false, {}, {},
     { featureType },
   );
+  const [expandedFeatureLabelsMap, expandedFeatureLabelsStatus] = useExpandedFeatureLabelsMap(
+    featureType, featureLabelsMap, { stripCuriePrefixes: true },
+  );
   const [{ featureIndex }, matrixIndicesStatus, obsFeatureMatrixUrls] = useObsFeatureMatrixIndices(
     loaders, dataset, true,
     { obsType, featureType },
   );
   const isReady = useReady([
     featureLabelsStatus,
+    expandedFeatureLabelsStatus,
     matrixIndicesStatus,
   ]);
   const urls = useUrls([
     featureLabelsUrls,
     obsFeatureMatrixUrls,
   ]);
+
   const geneList = featureIndex || [];
   const numGenes = geneList.length;
-  const hasFeatureLabels = Boolean(featureLabelsMap);
+  const hasFeatureLabels = Boolean(expandedFeatureLabelsMap);
 
   function setGeneSelectionAndColorEncoding(newSelection) {
     setGeneSelection(newSelection);
@@ -125,7 +131,7 @@ export function FeatureListSubscriber(props) {
           setFeatureListSortKey={setFeatureListSortKey}
           showFeatureTable={showFeatureTable}
           setShowFeatureTable={setShowFeatureTable}
-          hasFeatureLabels={Boolean(featureLabelsMap)}
+          hasFeatureLabels={hasFeatureLabels}
           primaryColumnName={primaryColumnName}
         />
       )}
@@ -136,15 +142,15 @@ export function FeatureListSubscriber(props) {
         geneList={geneList}
         featureListSort={featureListSort}
         featureListSortKey={featureListSortKey || initialSortKey}
-        featureLabelsMap={featureLabelsMap}
+        featureLabelsMap={expandedFeatureLabelsMap}
         featureType={featureType}
         geneSelection={geneSelection}
         geneFilter={geneFilter}
         setGeneSelection={setGeneSelectionAndColorEncoding}
         setGeneFilter={setGeneFilter}
         setGeneHighlight={setGeneHighlight}
         enableMultiSelect={enableMultiSelect}
-        hasFeatureLabels={Boolean(featureLabelsMap)}
+        hasFeatureLabels={hasFeatureLabels}
         primaryColumnName={primaryColumnName}
       />
     </TitleInfo>