jbrowse-plugin-msaview 2.4.5 → 2.5.1

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,
@@ -16,14 +21,11 @@ import {
   processInit,
   runCleanup,
   storeDataToIndexedDB,
+  syncGenomeHoverToMsaColumn,
 } from './afterCreateAutoruns'
-import { genomeToMSA } from './genomeToMSA'
 import { msaCoordToGenomeCoord } from './msaCoordToGenomeCoord'
 import { buildAlignmentMaps, runPairwiseAlignment } from './pairwiseAlignment'
-import {
-  getProteinViews,
-  ungappedToGappedPosition,
-} from './structureConnection'
+import { getProteinViews } from './structureConnection'
 import { getCanonicalRefName } from './util'
 
 import type { ProteinView, StructureConnection } from './structureConnection'
@@ -80,9 +82,6 @@ export default function stateModelFactory() {
          * #property
          */
         connectedFeature: types.frozen(),
-        /**
-         * #property
-         */
         /**
          * #property
          */
@@ -131,6 +130,7 @@ export default function stateModelFactory() {
         error: unknown
         loadingStoredData: boolean
         isStoringData: boolean
+        domainsRequested: boolean
       } => ({
         /**
          * #volatile
@@ -152,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,
       }),
     )
 
@@ -209,41 +215,6 @@ export default function stateModelFactory() {
     }))
 
     .views(self => ({
-      /**
-       * #getter
-       */
-      get structureHoverCol(): number | undefined {
-        for (const conn of self.connectedProteinViews) {
-          const structure = conn.proteinView.structures[conn.structureIdx]
-          const structurePos = structure?.hoverPosition?.structureSeqPos
-          if (structurePos !== undefined) {
-            const msaUngapped = conn.structureToMsa[structurePos]
-            if (msaUngapped !== undefined) {
-              const seq = self.getSequenceByRowName(conn.msaRowName)
-              if (seq) {
-                const globalCol = ungappedToGappedPosition(seq, msaUngapped)
-                if (globalCol !== undefined) {
-                  return self.globalColToVisibleCol(globalCol)
-                }
-              }
-            }
-          }
-        }
-        return undefined
-      },
-    }))
-
-    .views(self => ({
-      /**
-       * #getter
-       */
-      get mouseCol2(): number | undefined {
-        return (
-          self.structureHoverCol ??
-          genomeToMSA({ model: self as JBrowsePluginMsaViewModel })
-        )
-      },
-
       /**
        * #getter
        */
@@ -333,6 +304,12 @@ export default function stateModelFactory() {
       setIsStoringData(arg: boolean) {
         self.isStoringData = arg
       },
+      /**
+       * #action
+       */
+      setDomainsRequested(arg: boolean) {
+        self.domainsRequested = arg
+      },
       /**
        * #action
        */
@@ -394,14 +371,13 @@ export default function stateModelFactory() {
           ungappedMsaSequence,
           structureSequence,
         )
-        const { seq1ToSeq2, seq2ToSeq1 } = buildAlignmentMaps(alignment)
+        const { seq1ToSeq2 } = buildAlignmentMaps(alignment)
 
         const connection: StructureConnection = {
           proteinViewId,
           structureIdx,
           msaRowName: rowName,
           msaToStructure: Object.fromEntries(seq1ToSeq2),
-          structureToMsa: Object.fromEntries(seq2ToSeq1),
         }
 
         self.connectedStructures.push(connection)
@@ -494,6 +470,7 @@ export default function stateModelFactory() {
           processInit,
           highlightConnectedStructures,
           autoConnectStructures,
+          autoLoadProteinDomains,
           observeProteinHighlights,
         ]) {
           addDisposer(
@@ -503,6 +480,7 @@ export default function stateModelFactory() {
             }),
           )
         }
+        addDisposer(self, autorun(syncGenomeHoverToMsaColumn(self)))
       },
     }))
 }

package/src/MsaViewPanel/pairwiseAlignment.ts

@@ -128,13 +128,8 @@ function buildConsensus(alignedSeq1: string, alignedSeq2: string) {
   for (let i = 0; i < alignedSeq1.length; i++) {
     const a = alignedSeq1[i]!
     const b = alignedSeq2[i]!
-    if (a === '-' || b === '-') {
-      consensus += ' '
-    } else if (a.toUpperCase() === b.toUpperCase()) {
-      consensus += '|'
-    } else {
-      consensus += ' '
-    }
+    const match = a !== '-' && b !== '-' && a.toUpperCase() === b.toUpperCase()
+    consensus += match ? '|' : ' '
   }
   return consensus
 }

package/src/MsaViewPanel/structureConnection.test.ts

@@ -1,9 +1,6 @@
 import { describe, expect, test } from 'vitest'
 
-import {
-  gappedToUngappedPosition,
-  ungappedToGappedPosition,
-} from './structureConnection'
+import { gappedToUngappedPosition } from './structureConnection'
 
 describe('gappedToUngappedPosition', () => {
   test('returns correct ungapped position for non-gap character', () => {
@@ -63,60 +60,3 @@ describe('gappedToUngappedPosition', () => {
     expect(gappedToUngappedPosition(seq, 2)).toBeUndefined()
   })
 })
-
-describe('ungappedToGappedPosition', () => {
-  test('returns correct gapped position', () => {
-    const seq = 'M-KA-A'
-    //           0 12 34  (gapped)
-    //           0  1  23 (ungapped)
-    expect(ungappedToGappedPosition(seq, 0)).toBe(0) // M
-    expect(ungappedToGappedPosition(seq, 1)).toBe(2) // K
-    expect(ungappedToGappedPosition(seq, 2)).toBe(3) // A
-    expect(ungappedToGappedPosition(seq, 3)).toBe(5) // A
-  })
-
-  test('returns undefined for out-of-bounds ungapped position', () => {
-    const seq = 'M-KA'
-    expect(ungappedToGappedPosition(seq, 4)).toBeUndefined()
-    expect(ungappedToGappedPosition(seq, 100)).toBeUndefined()
-  })
-
-  test('handles sequence with no gaps', () => {
-    const seq = 'MKAA'
-    expect(ungappedToGappedPosition(seq, 0)).toBe(0)
-    expect(ungappedToGappedPosition(seq, 1)).toBe(1)
-    expect(ungappedToGappedPosition(seq, 2)).toBe(2)
-    expect(ungappedToGappedPosition(seq, 3)).toBe(3)
-  })
-
-  test('handles sequence with leading gaps', () => {
-    const seq = '--MKA'
-    expect(ungappedToGappedPosition(seq, 0)).toBe(2) // M
-    expect(ungappedToGappedPosition(seq, 1)).toBe(3) // K
-    expect(ungappedToGappedPosition(seq, 2)).toBe(4) // A
-  })
-
-  test('handles empty sequence', () => {
-    expect(ungappedToGappedPosition('', 0)).toBeUndefined()
-  })
-
-  test('handles all-gap sequence', () => {
-    const seq = '---'
-    expect(ungappedToGappedPosition(seq, 0)).toBeUndefined()
-  })
-})
-
-describe('gappedToUngappedPosition and ungappedToGappedPosition are inverses', () => {
-  test('round-trip conversion works', () => {
-    const seq = 'M-KA--YL-S'
-    // For each non-gap position, converting to ungapped and back should return original
-    for (let i = 0; i < seq.length; i++) {
-      if (seq[i] !== '-') {
-        const ungapped = gappedToUngappedPosition(seq, i)
-        expect(ungapped).toBeDefined()
-        const backToGapped = ungappedToGappedPosition(seq, ungapped!)
-        expect(backToGapped).toBe(i)
-      }
-    }
-  })
-})

package/src/MsaViewPanel/structureConnection.ts

@@ -40,8 +40,6 @@ export interface StructureConnection {
   msaRowName: string
   /** Map from MSA ungapped position to structure sequence position */
   msaToStructure: Record<number, number>
-  /** Map from structure sequence position to MSA ungapped position */
-  structureToMsa: Record<number, number>
 }
 
 /**
@@ -69,23 +67,3 @@ export function gappedToUngappedPosition(
 
   return ungapped
 }
-
-/**
- * Helper to convert ungapped position to gapped MSA column for a specific row
- */
-export function ungappedToGappedPosition(
-  sequence: string,
-  ungappedPosition: number,
-): number | undefined {
-  let ungapped = 0
-  for (let i = 0; i < sequence.length; i++) {
-    const element = sequence[i]
-    if (element !== '-') {
-      if (ungapped === ungappedPosition) {
-        return i
-      }
-      ungapped++
-    }
-  }
-  return undefined
-}

package/src/MsaViewPanel/syncGenomeHoverToMsaColumn.test.ts

@@ -0,0 +1,112 @@
+import { getSession } from '@jbrowse/core/util'
+import { beforeEach, describe, expect, test, vi } from 'vitest'
+
+import { syncGenomeHoverToMsaColumn } from './afterCreateAutoruns'
+
+import type { JBrowsePluginMsaViewModel } from './model'
+
+// Mock only getSession; keep the rest of the util module real so the
+// afterCreateAutoruns import graph still loads.
+vi.mock('@jbrowse/core/util', async importOriginal => ({
+  ...(await importOriginal<Record<string, unknown>>()),
+  getSession: vi.fn(),
+}))
+
+const mockGetSession = vi.mocked(getSession)
+
+const mafRegion = {
+  refName: 'chr1',
+  start: 1000,
+  end: 1010,
+  assemblyName: 'hg38',
+}
+
+// A model wired through the real genomeToMSA path: a connected genome view
+// over a maf region, with seqPosToVisibleCol as identity so the asserted
+// column equals the ungapped offset into the region.
+function makeModel() {
+  const calls: (number | undefined)[] = []
+  const model = {
+    querySeqName: 'hg38.chr1',
+    transcriptToMsaMap: undefined,
+    mafRegion,
+    connectedView: { initialized: true, assemblyNames: ['hg38'] },
+    seqPosToVisibleCol: (_name: string, pos: number) => pos,
+    setMousePos: (col?: number) => {
+      calls.push(col)
+    },
+  } as unknown as JBrowsePluginMsaViewModel
+  return { model, calls }
+}
+
+function hoverGenome(coord: number) {
+  mockGetSession.mockReturnValue({
+    hovered: { hoverFeature: {}, hoverPosition: { coord, refName: 'chr1' } },
+  } as unknown as ReturnType<typeof getSession>)
+}
+
+function clearGenomeHover() {
+  mockGetSession.mockReturnValue({
+    hovered: null,
+  } as unknown as ReturnType<typeof getSession>)
+}
+
+describe('syncGenomeHoverToMsaColumn (real genomeToMSA mapping)', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  test('genome hover at coord 1005 highlights MSA column 5', () => {
+    const { model, calls } = makeModel()
+    const run = syncGenomeHoverToMsaColumn(model)
+
+    hoverGenome(1005) // 1005 - mafRegion.start(1000) = ungapped 5
+    run()
+    expect(calls).toEqual([5])
+  })
+
+  test('moving the genome hover moves the highlighted column', () => {
+    const { model, calls } = makeModel()
+    const run = syncGenomeHoverToMsaColumn(model)
+
+    hoverGenome(1002)
+    run()
+    hoverGenome(1007)
+    run()
+    expect(calls).toEqual([2, 7])
+  })
+
+  test('leaving the genome clears the column it set', () => {
+    const { model, calls } = makeModel()
+    const run = syncGenomeHoverToMsaColumn(model)
+
+    hoverGenome(1004)
+    run()
+    clearGenomeHover()
+    run()
+    expect(calls).toEqual([4, undefined])
+  })
+
+  test('a hover outside the maf region clears a previously-set column once', () => {
+    const { model, calls } = makeModel()
+    const run = syncGenomeHoverToMsaColumn(model)
+
+    hoverGenome(1004)
+    run()
+    hoverGenome(5000) // outside [1000,1010) -> genomeToMSA returns undefined
+    run()
+    run()
+    expect(calls).toEqual([4, undefined])
+  })
+
+  test('never touches mouseCol when the genome never provides a column, so a direct MSA hover survives unrelated session hovers', () => {
+    const { model, calls } = makeModel()
+    const run = syncGenomeHoverToMsaColumn(model)
+
+    clearGenomeHover()
+    run()
+    hoverGenome(9999) // unrelated/out-of-range hover elsewhere
+    run()
+    expect(calls).toEqual([])
+  })
+})

package/src/utils/domainCache.ts

@@ -0,0 +1,44 @@
+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,8 +1,10 @@
-import { textfetch, timeout } from './fetch'
+import { textfetch } from './fetch'
+import { pollLoop } from './poll'
 
 import type { MsaAlgorithm } from '../LaunchMsaView/components/NCBIBlastQuery/consts'
 
 const base = `https://www.ebi.ac.uk/Tools/services/rest`
+const email = 'colin.diesh@gmail.com'
 
 const algorithms: Record<
   MsaAlgorithm,
@@ -13,22 +15,22 @@ const algorithms: Record<
   }
 > = {
   clustalo: {
-    params: { email: 'colin.diesh@gmail.com' },
+    params: { email },
     msaResult: 'aln-clustal_num',
     treeResult: 'phylotree',
   },
   muscle: {
-    params: { email: 'colin.diesh@gmail.com', format: 'clw', tree: 'tree1' },
+    params: { email, format: 'clw', tree: 'tree1' },
     msaResult: 'fa',
     treeResult: 'phylotree',
   },
   kalign: {
-    params: { email: 'colin.diesh@gmail.com', stype: 'protein' },
+    params: { email, stype: 'protein' },
     msaResult: 'fa',
     treeResult: 'phylotree',
   },
   mafft: {
-    params: { email: 'colin.diesh@gmail.com', stype: 'protein' },
+    params: { email, stype: 'protein' },
     msaResult: 'fa',
     treeResult: 'phylotree',
   },
@@ -43,20 +45,22 @@ async function wait({
   algorithm: MsaAlgorithm
   onProgress: (arg: string) => void
 }) {
-  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-  while (true) {
-    for (let i = 0; i < 10; i++) {
-      await timeout(1000)
-      onProgress(`Re-checking MSA status in... ${10 - i}`)
-    }
-    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}`)
-    }
-  }
+  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,39 +111,33 @@ async function waitForRid({
   onProgress: (arg: string) => void
   baseUrl: string
 }) {
-  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-  while (true) {
-    const iter = 20
-    for (let i = 0; i < iter; i++) {
-      await timeout(1000)
-      onProgress(`Re-checking BLAST status in... ${iter - i}`)
-    }
+  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)
 
-    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)
-
-    if (status === 'WAITING') {
-      continue
-    }
-
-    if (status === 'FAILED') {
-      throw new Error(`BLAST ${rid} failed`)
-    }
-
-    if (status === 'READY') {
-      if (hasHits) {
-        return true
-      } else {
+      if (status === 'WAITING') {
+        return false
+      }
+      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'}`,
+      )
+    },
+  })
 }