jbrowse-plugin-msaview 2.5.0 → 2.5.2

package/src/MsaViewPanel/loadProteinDomains.ts

@@ -0,0 +1,57 @@
+import { fetchProteinDomains } from '../utils/ncbiDomains'
+
+import type { InterProScanResults } from 'react-msaview'
+
+// structural subset of the MSA model: the full model type can't be used here
+// because it references this very action, creating a self-referential cycle
+interface DomainModel {
+  data: { treeMetadata?: string }
+  setProgress: (arg: string) => void
+  setDomains: (data: Record<string, InterProScanResults>) => void
+}
+
+/**
+ * Overlay protein domains on the alignment using NCBI's pre-computed CDD
+ * annotations. The BLAST workflow stores each hit's accession in treeMetadata,
+ * so we look those up via efetch and key the results by MSA row name (which is
+ * what react-msaview matches domains against).
+ */
+export async function loadProteinDomains(self: DomainModel) {
+  const metadataJson = self.data.treeMetadata
+  if (!metadataJson) {
+    throw new Error('No sequence metadata available to look up domains')
+  }
+  const metadata = JSON.parse(metadataJson) as Record<
+    string,
+    Record<string, string>
+  >
+
+  const rowAccessions = Object.entries(metadata)
+    .map(([rowName, meta]) => ({ rowName, accession: meta.Accession }))
+    .filter((r): r is { rowName: string; accession: string } => !!r.accession)
+
+  if (rowAccessions.length === 0) {
+    throw new Error('No NCBI accessions found in alignment rows')
+  }
+
+  self.setProgress(
+    `Fetching protein domains from NCBI for ${rowAccessions.length} sequences...`,
+  )
+  const byAccession = await fetchProteinDomains(
+    rowAccessions.map(r => r.accession),
+  )
+
+  const annotations: Record<string, InterProScanResults> = {}
+  for (const { rowName, accession } of rowAccessions) {
+    const matches = byAccession.get(accession)
+    if (matches && matches.length > 0) {
+      annotations[rowName] = { matches, xref: [{ id: rowName }] }
+    }
+  }
+
+  if (Object.keys(annotations).length === 0) {
+    throw new Error('No CDD domain annotations found for these proteins')
+  }
+
+  self.setDomains(annotations)
+}

package/src/MsaViewPanel/model.ts

@@ -7,8 +7,13 @@ import { genomeToTranscriptSeqMapping } from 'g2p_mapper'
 import { autorun } from 'mobx'
 import { MSAModelF } from 'react-msaview'
 
+// re-exported so the inferred (composed) state-model type can name MSAFormat
+// from msa-parsers when emitting declarations (avoids TS2883 portability error)
+export type { MSAFormat } from 'msa-parsers'
+
 import {
   autoConnectStructures,
+  autoLoadProteinDomains,
   highlightConnectedStructures,
   launchBlastIfNeeded,
   loadStoredData,
@@ -77,9 +82,6 @@ export default function stateModelFactory() {
          * #property
          */
         connectedFeature: types.frozen(),
-        /**
-         * #property
-         */
         /**
          * #property
          */
@@ -128,6 +130,7 @@ export default function stateModelFactory() {
         error: unknown
         loadingStoredData: boolean
         isStoringData: boolean
+        domainsRequested: boolean
       } => ({
         /**
          * #volatile
@@ -149,6 +152,12 @@ export default function stateModelFactory() {
          * #volatile
          */
         isStoringData: false,
+        /**
+         * #volatile
+         * guards the one-shot auto-fetch of protein domains so it doesn't refire
+         * when NCBI returns no domains (leaving interProAnnotations undefined)
+         */
+        domainsRequested: false,
       }),
     )
 
@@ -295,6 +304,12 @@ export default function stateModelFactory() {
       setIsStoringData(arg: boolean) {
         self.isStoringData = arg
       },
+      /**
+       * #action
+       */
+      setDomainsRequested(arg: boolean) {
+        self.domainsRequested = arg
+      },
       /**
        * #action
        */
@@ -455,7 +470,7 @@ export default function stateModelFactory() {
           processInit,
           highlightConnectedStructures,
           autoConnectStructures,
-          observeProteinHighlights,
+          autoLoadProteinDomains,
         ]) {
           addDisposer(
             self,
@@ -464,7 +479,10 @@ export default function stateModelFactory() {
             }),
           )
         }
+        // these two keep per-reaction state across runs (a "did I set it?" flag),
+        // so they're factories returning the autorun body rather than plain fns
         addDisposer(self, autorun(syncGenomeHoverToMsaColumn(self)))
+        addDisposer(self, autorun(observeProteinHighlights(self)))
       },
     }))
 }

package/src/utils/domainCache.ts

@@ -0,0 +1,43 @@
+import { openDB } from 'idb'
+
+import type { DomainMatch } from './ncbiDomains'
+
+const DB_NAME = 'jbrowse-msaview-domain-cache'
+const STORE_NAME = 'domains'
+const DB_VERSION = 1
+
+interface CachedDomain {
+  accession: string
+  matches: DomainMatch[]
+}
+
+async function getDB() {
+  return openDB(DB_NAME, DB_VERSION, {
+    upgrade(db) {
+      if (!db.objectStoreNames.contains(STORE_NAME)) {
+        db.createObjectStore(STORE_NAME, { keyPath: 'accession' })
+      }
+    },
+  })
+}
+
+export async function getCachedDomains(accessions: string[]) {
+  const db = await getDB()
+  const tx = db.transaction(STORE_NAME, 'readonly')
+  const results = await Promise.all(
+    accessions.map(
+      accession => tx.store.get(accession) as Promise<CachedDomain | undefined>,
+    ),
+  )
+  await tx.done
+  return results
+}
+
+export async function saveDomains(entries: CachedDomain[]) {
+  const db = await getDB()
+  const tx = db.transaction(STORE_NAME, 'readwrite')
+  for (const entry of entries) {
+    await tx.store.put(entry)
+  }
+  await tx.done
+}

package/src/utils/eutils.ts

@@ -0,0 +1,16 @@
+// NCBI asks that programmatic E-utilities requests identify themselves with a
+// tool name and contact email so they can reach out before throttling, rather
+// than silently rate-limiting. https://www.ncbi.nlm.nih.gov/books/NBK25497/
+export const NCBI_TOOL = 'jbrowse-plugin-msaview'
+export const NCBI_EMAIL = 'colin.diesh@gmail.com'
+
+const EUTILS = 'https://eutils.ncbi.nlm.nih.gov/entrez/eutils'
+
+export function efetchUrl(params: Record<string, string>) {
+  const search = new URLSearchParams({
+    ...params,
+    tool: NCBI_TOOL,
+    email: NCBI_EMAIL,
+  })
+  return `${EUTILS}/efetch.fcgi?${search.toString()}`
+}

package/src/utils/msa.ts

@@ -1,4 +1,5 @@
-import { textfetch, timeout } from './fetch'
+import { textfetch } from './fetch'
+import { pollLoop } from './poll'
 
 import type { MsaAlgorithm } from '../LaunchMsaView/components/NCBIBlastQuery/consts'
 
@@ -44,21 +45,22 @@ async function wait({
   algorithm: MsaAlgorithm
   onProgress: (arg: string) => void
 }) {
-  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-  while (true) {
-    const result = await textfetch(`${base}/${algorithm}/status/${jobId}`)
-
-    if (result === 'FINISHED') {
-      break
-    } else if (result.includes('FAILURE')) {
-      throw new Error(`Failed to run: jobId ${jobId}`)
-    }
-
-    for (let i = 0; i < 10; i++) {
-      onProgress(`Re-checking MSA status in... ${10 - i}`)
-      await timeout(1000)
-    }
-  }
+  await pollLoop({
+    intervalSeconds: 10,
+    onCountdown: s => {
+      onProgress(`Re-checking MSA status in... ${s}`)
+    },
+    check: async () => {
+      const result = await textfetch(`${base}/${algorithm}/status/${jobId}`)
+      if (result.includes('FINISHED')) {
+        return true
+      }
+      if (result.includes('FAILURE')) {
+        throw new Error(`Failed to run: jobId ${jobId}`)
+      }
+      return false
+    },
+  })
 }
 
 export async function launchMSA({

package/src/utils/ncbiBlast.ts

@@ -1,4 +1,5 @@
-import { jsonfetch, textfetch, timeout } from './fetch'
+import { jsonfetch, textfetch } from './fetch'
+import { pollLoop } from './poll'
 
 import type { BlastResults } from './types'
 import type {
@@ -110,38 +111,33 @@ async function waitForRid({
   onProgress: (arg: string) => void
   baseUrl: string
 }) {
-  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-  while (true) {
-    const res = await textfetch(
-      `${baseUrl}?CMD=Get&FORMAT_OBJECT=SearchInfo&RID=${rid}`,
-    )
-    const statusMatch = /\s+Status=(\S+)/m.exec(res)
-    const status = statusMatch?.[1]
-    const hasHits = /\s+ThereAreHits=yes/m.test(res)
+  await pollLoop({
+    intervalSeconds: 20,
+    onCountdown: s => {
+      onProgress(`Re-checking BLAST status in... ${s}`)
+    },
+    check: async () => {
+      const res = await textfetch(
+        `${baseUrl}?CMD=Get&FORMAT_OBJECT=SearchInfo&RID=${rid}`,
+      )
+      const status = /\s+Status=(\S+)/m.exec(res)?.[1]
+      const hasHits = /\s+ThereAreHits=yes/m.test(res)
 
-    if (status === 'WAITING') {
-      const iter = 20
-      for (let i = 0; i < iter; i++) {
-        onProgress(`Re-checking BLAST status in... ${iter - i}`)
-        await timeout(1000)
+      if (status === 'WAITING') {
+        return false
       }
-      continue
-    }
-
-    if (status === 'FAILED') {
-      throw new Error(`BLAST ${rid} failed`)
-    }
-
-    if (status === 'READY') {
-      if (hasHits) {
-        return true
-      } else {
+      if (status === 'FAILED') {
+        throw new Error(`BLAST ${rid} failed`)
+      }
+      if (status === 'READY') {
+        if (hasHits) {
+          return true
+        }
         throw new Error('No hits found')
       }
-    }
-
-    throw new Error(
-      `BLAST ${rid} returned unexpected status: ${status ?? 'unknown'}`,
-    )
-  }
+      throw new Error(
+        `BLAST ${rid} returned unexpected status: ${status ?? 'unknown'}`,
+      )
+    },
+  })
 }

package/src/utils/ncbiDomains.ts

@@ -0,0 +1,173 @@
+import { getCachedDomains, saveDomains } from './domainCache'
+import { efetchUrl } from './eutils'
+import { textfetch } from './fetch'
+
+import type { InterProScanResults } from 'react-msaview'
+
+export type DomainMatch = InterProScanResults['matches'][number]
+
+function field(xml: string, tag: string) {
+  return new RegExp(`<${tag}>(.*?)</${tag}>`, 's').exec(xml)?.[1]
+}
+
+function parseQualifiers(featureXml: string) {
+  const quals: Record<string, string> = {}
+  const re = /<GBQualifier>([\s\S]*?)<\/GBQualifier>/g
+  let m
+  while ((m = re.exec(featureXml)) !== null) {
+    const name = field(m[1]!, 'GBQualifier_name')
+    const value = field(m[1]!, 'GBQualifier_value')
+    // keep the first occurrence: NCBI lists the canonical value first
+    if (name && value !== undefined && quals[name] === undefined) {
+      quals[name] = value
+    }
+  }
+  return quals
+}
+
+// A feature can span several intervals: domains are usually one contiguous
+// range, but CDD Sites (e.g. an active site) are a set of scattered residues
+// expressed as multiple GBInterval ranges and single GBInterval_point residues.
+// We collapse those to a single bounding span so a site renders as one box
+// rather than a spray of 1px specks.
+function parseBoundingSpan(featureXml: string) {
+  const starts: number[] = []
+  const ends: number[] = []
+  const re = /<GBInterval>([\s\S]*?)<\/GBInterval>/g
+  let m
+  while ((m = re.exec(featureXml)) !== null) {
+    const block = m[1]!
+    const from = field(block, 'GBInterval_from')
+    const to = field(block, 'GBInterval_to')
+    const point = field(block, 'GBInterval_point')
+    if (from && to) {
+      starts.push(Number(from))
+      ends.push(Number(to))
+    } else if (point) {
+      starts.push(Number(point))
+      ends.push(Number(point))
+    }
+  }
+  return starts.length > 0
+    ? { start: Math.min(...starts), end: Math.max(...ends) }
+    : undefined
+}
+
+// Drop single-residue specks (acetylation/phospho points) but keep every
+// genuine domain and functional site; react-msaview draws longest-first, so
+// smaller features (binding sites, loops) layer on top of the domain they sit
+// inside.
+const MIN_FEATURE_LENGTH = 2
+
+function parseFeature(featureXml: string): DomainMatch | undefined {
+  const key = field(featureXml, 'GBFeature_key')
+  const quals = parseQualifiers(featureXml)
+  const xref = quals.db_xref
+  const span = parseBoundingSpan(featureXml)
+  // only CDD-backed Regions/Sites are conserved-domain annotations; Regions and
+  // Sites without a CDD xref are UniProt-propagated point motifs we don't want
+  if (
+    (key === 'Region' || key === 'Site') &&
+    xref?.startsWith('CDD:') &&
+    span &&
+    span.end - span.start + 1 >= MIN_FEATURE_LENGTH
+  ) {
+    const cddId = xref.replace('CDD:', '')
+    const isDomain = key === 'Region'
+    // a site's note (e.g. "ATP binding site [chemical binding]") is more
+    // specific than its generic site_type ("other"), so prefer it for the name
+    // — that gives each functional site its own color/legend/filter entry
+    const noteName = quals.note?.split(/[[(]/)[0]?.trim()
+    const name = isDomain
+      ? (quals.region_name ?? cddId)
+      : noteName || quals.site_type || 'site'
+    const accession = isDomain ? cddId : `${cddId}:${name}`
+    return {
+      signature: {
+        entry: { name, description: quals.note ?? name, accession },
+      },
+      locations: [span],
+    }
+  }
+  return undefined
+}
+
+/**
+ * Parse a GenPept (efetch db=protein&rettype=gp&retmode=xml) document into CDD
+ * domain and site annotations, keyed by both the versioned and primary
+ * accession so callers can look up by whichever NCBI returned.
+ */
+export function parseCddDomains(xml: string) {
+  const byAccession = new Map<string, DomainMatch[]>()
+  const seqRe = /<GBSeq>([\s\S]*?)<\/GBSeq>/g
+  let seqMatch
+  while ((seqMatch = seqRe.exec(xml)) !== null) {
+    const seqXml = seqMatch[1]!
+    const matches: DomainMatch[] = []
+
+    const featRe = /<GBFeature>([\s\S]*?)<\/GBFeature>/g
+    let featMatch
+    while ((featMatch = featRe.exec(seqXml)) !== null) {
+      const match = parseFeature(featMatch[1]!)
+      if (match) {
+        matches.push(match)
+      }
+    }
+
+    for (const acc of [
+      field(seqXml, 'GBSeq_accession-version'),
+      field(seqXml, 'GBSeq_primary-accession'),
+    ]) {
+      if (acc) {
+        byAccession.set(acc, matches)
+      }
+    }
+  }
+  return byAccession
+}
+
+/**
+ * Fetch pre-computed CDD domain and site annotations for NCBI protein
+ * accessions. These come baked into the GenPept records, so a single batched
+ * efetch returns them with no job submission or polling. Results are cached in
+ * IndexedDB so reopening a view doesn't refetch.
+ */
+export async function fetchProteinDomains(accessions: string[]) {
+  const unique = [...new Set(accessions)].filter(Boolean)
+  const byAccession = new Map<string, DomainMatch[]>()
+
+  const cached = await getCachedDomains(unique)
+  const uncached: string[] = []
+  unique.forEach((acc, i) => {
+    const hit = cached[i]
+    if (hit) {
+      byAccession.set(acc, hit.matches)
+    } else {
+      uncached.push(acc)
+    }
+  })
+
+  const toCache: { accession: string; matches: DomainMatch[] }[] = []
+  const batchSize = 100
+  for (let i = 0; i < uncached.length; i += batchSize) {
+    const batch = uncached.slice(i, i + batchSize)
+    const xml = await textfetch(
+      efetchUrl({
+        db: 'protein',
+        id: batch.join(','),
+        rettype: 'gp',
+        retmode: 'xml',
+      }),
+    )
+    const parsed = parseCddDomains(xml)
+    for (const acc of batch) {
+      const matches = parsed.get(acc) ?? []
+      byAccession.set(acc, matches)
+      toCache.push({ accession: acc, matches })
+    }
+  }
+  if (toCache.length > 0) {
+    await saveDomains(toCache)
+  }
+  return byAccession
+}

package/src/utils/poll.ts

@@ -0,0 +1,28 @@
+import { timeout } from './fetch'
+
+/**
+ * Poll a remote job until it reports done. `check` returns true when finished,
+ * false when still pending, and throws on failure. Between checks it counts down
+ * `intervalSeconds`, calling `onCountdown` each second so the UI can show
+ * progress.
+ */
+export async function pollLoop({
+  check,
+  intervalSeconds,
+  onCountdown,
+}: {
+  check: () => Promise<boolean>
+  intervalSeconds: number
+  onCountdown: (secondsRemaining: number) => void
+}) {
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  while (true) {
+    if (await check()) {
+      return
+    }
+    for (let i = intervalSeconds; i > 0; i--) {
+      onCountdown(i)
+      await timeout(1000)
+    }
+  }
+}

package/src/utils/taxonomyNames.ts

@@ -1,5 +1,7 @@
 import { openDB } from 'idb'
 
+import { efetchUrl } from './eutils'
+
 const DB_NAME = 'jbrowse-msaview-taxonomy-cache'
 const STORE_NAME = 'common-names'
 const DB_VERSION = 2
@@ -80,7 +82,7 @@ export async function fetchTaxonomyInfo(
 
     try {
       const response = await fetch(
-        `https://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi?db=taxonomy&id=${idsParam}&retmode=xml`,
+        efetchUrl({ db: 'taxonomy', id: idsParam, retmode: 'xml' }),
       )
       const text = await response.text()
 

package/src/version.ts

@@ -1 +1 @@
-export const version = '2.5.0'
+export const version = '2.5.2'