jbrowse-plugin-msaview 3.5.0 → 3.7.0

package/src/MsaViewPanel/resolveConnectedTranscript.ts

@@ -1,11 +1,17 @@
 import { getConf } from '@jbrowse/core/configuration'
 import { getSession } from '@jbrowse/core/util'
+import { isAlive } from '@jbrowse/mobx-state-tree'
+import { transaction, untracked } from 'mobx'
 
 import { getProteinSequenceFromFeature } from '../LaunchMsaView/components/calculateProteinSequence'
 import { fetchSeq } from '../LaunchMsaView/components/fetchSeq'
 import { getTranscriptFeatures } from '../LaunchMsaView/util'
 
-import type { JBrowsePluginMsaViewModel } from './model'
+import type {
+  BlastParams,
+  JBrowsePluginMsaViewModel,
+  OrthologParams,
+} from './model'
 import type { Feature } from '@jbrowse/core/util'
 
 // The short form of a connected launch. A spec that says
@@ -14,15 +20,26 @@ import type { Feature } from '@jbrowse/core/util'
 //
 // gets its `connectedFeature` -- the exon model every genome<->column mapping
 // runs through -- looked up here, from the gene tracks the connected genome
-// view has open, and its query row translated from that transcript. Before
-// this the spec had to carry the transcript's CDS list itself, ~1.5kB of
-// coordinates a person cannot type and a tutorial cannot show.
+// view has open, and its query row translated from that transcript.
 //
 // jbrowse-plugin-protein3d does the same for its `transcriptId` shorthand,
 // against a `connectedView` spec of its own; here the genome view already
 // exists (the spec pinned its id), so its tracks and regions are read off the
 // live model instead.
 
+interface Region {
+  assemblyName: string
+  refName: string
+  start: number
+  end: number
+}
+
+interface GenomeView {
+  tracks: { type: string }[]
+  displayedRegions: Region[]
+  dynamicBlocks?: { contentBlocks?: Region[] }
+}
+
 function stripVersion(id: string) {
   return id.replace(/\.\d+$/, '')
 }
@@ -37,6 +54,35 @@ function transcriptMatches(transcript: Feature, id: string) {
   ].some(c => typeof c === 'string' && (c === id || stripVersion(c) === target))
 }
 
+function plainRegions(regions: Region[]) {
+  return regions.map(r => ({
+    assemblyName: r.assemblyName,
+    refName: r.refName,
+    start: Math.floor(r.start),
+    end: Math.ceil(r.end),
+  }))
+}
+
+/**
+ * The part of the genome on screen, then everything the view can scroll to.
+ * `displayedRegions` is usually whole chromosomes -- navigating to a locus
+ * displays its parent region -- so it is the fallback, not the first ask.
+ */
+export function searchWindows(view: GenomeView) {
+  const visible = plainRegions(view.dynamicBlocks?.contentBlocks ?? [])
+  const displayed = plainRegions(view.displayedRegions)
+  return visible.length > 0 ? [visible, displayed] : [displayed]
+}
+
+/**
+ * Gene models live on feature tracks. Asking an alignments, variant or
+ * quantitative track for a chromosome's worth of features to look for a
+ * transcript among them is the slowest possible way to find nothing.
+ */
+export function transcriptTracks<T extends { type: string }>(tracks: T[]) {
+  return tracks.filter(t => t.type === 'FeatureTrack')
+}
+
 async function findTranscript(
   self: JBrowsePluginMsaViewModel,
   transcriptId: string,
@@ -44,24 +90,27 @@ async function findTranscript(
   const view = self.connectedView!
   const session = getSession(self)
   const sessionId = 'msaview-connectedTranscript'
-  const regions = view.displayedRegions.map(r => ({
-    assemblyName: r.assemblyName,
-    refName: r.refName,
-    start: r.start,
-    end: r.end,
-  }))
-  for (const track of view.tracks) {
-    const feats = (await session.rpcManager.call(sessionId, 'CoreGetFeatures', {
-      adapterConfig: getConf(track, 'adapter'),
-      sessionId,
-      regions,
-    })) as Feature[]
-    for (const feat of feats) {
-      const hit = getTranscriptFeatures(feat).find(t =>
-        transcriptMatches(t, transcriptId),
+  const tracks = transcriptTracks(view.tracks)
+  for (const regions of searchWindows(view)) {
+    for (const track of tracks) {
+      // a named object keeps sessionId, which v4 hosts read from the args
+      const args = {
+        adapterConfig: getConf(track, 'adapter'),
+        sessionId,
+        regions,
+      }
+      const feats = await session.rpcManager.call(
+        sessionId,
+        'CoreGetFeatures',
+        args,
       )
-      if (hit) {
-        return hit
+      for (const feat of feats) {
+        const hit = getTranscriptFeatures(feat).find(t =>
+          transcriptMatches(t, transcriptId),
+        )
+        if (hit) {
+          return hit
+        }
       }
     }
   }
@@ -75,57 +124,59 @@ async function translate(self: JBrowsePluginMsaViewModel, transcript: Feature) {
     refName: string
   }
   const assemblyName = self.connectedView!.assemblyNames[0]!
-  const seq = await fetchSeq({
+  const { seq, assemblyGeneticCodeId } = await fetchSeq({
     start,
     end,
     refName,
     assemblyName,
     session: getSession(self),
   })
-  return getProteinSequenceFromFeature({ seq, feature: transcript })
+  return getProteinSequenceFromFeature({
+    seq,
+    feature: transcript,
+    assemblyGeneticCodeId,
+  })
 }
 
-/**
- * Resolve `connectedTranscript` into `connectedFeature` once the connected
- * genome view has its assembly, regions and tracks, then hand the translation
- * to whichever launch is waiting for a query. Left in place on failure so the
- * error stays attributable; the autorun's tracked reads are the view's
- * readiness, so nothing refires until that changes.
- */
-export function resolveConnectedTranscriptIfNeeded(
-  self: JBrowsePluginMsaViewModel,
-) {
-  const { connectedTranscript, connectedFeature, connectedView } = self
-  if (
-    !connectedTranscript ||
-    connectedFeature ||
-    !connectedView?.initialized ||
-    connectedView.tracks.length === 0
-  ) {
-    return
-  }
-  const trackCount = connectedView.tracks.length
-  void (async () => {
-    try {
-      self.setProgress(
-        `Looking up ${connectedTranscript} in the genome view...`,
+/** the latest lookup per view; an older one finishing late writes nothing */
+const latestLookup = new WeakMap<object, number>()
+
+async function lookUp({
+  self,
+  transcriptId,
+  blastParams,
+  orthologParams,
+  isCurrent,
+}: {
+  self: JBrowsePluginMsaViewModel
+  transcriptId: string
+  blastParams: BlastParams | undefined
+  orthologParams: OrthologParams | undefined
+  isCurrent: () => boolean
+}) {
+  const trackCount = transcriptTracks(self.connectedView!.tracks).length
+  try {
+    self.setProgress(`Looking up ${transcriptId} in the genome view...`)
+    const transcript = await findTranscript(self, transcriptId)
+    if (!transcript) {
+      throw new Error(
+        `Transcript "${transcriptId}" was not found in the ${trackCount} feature track(s) open in the connected genome view. Open the gene track that carries it, and make sure the view is on its locus.`,
       )
-      const transcript = await findTranscript(self, connectedTranscript)
-      if (!transcript) {
-        throw new Error(
-          `Transcript "${connectedTranscript}" was not found in the ${trackCount} track(s) open in the connected genome view. Open the gene track that carries it, and make sure the view is on its locus.`,
-        )
-      }
-      const proteinSequence = await translate(self, transcript)
-      if (!proteinSequence) {
-        throw new Error(
-          `Transcript "${connectedTranscript}" has no CDS to translate`,
-        )
-      }
-      // toJSON, not the Feature: the params are frozen snapshot properties, so
-      // an instance in one is gone the moment the session reloads
-      const transcriptJson = transcript.toJSON()
-      const { blastParams, orthologParams } = self
+    }
+    const proteinSequence = await translate(self, transcript)
+    if (!proteinSequence) {
+      throw new Error(`Transcript "${transcriptId}" has no CDS to translate`)
+    }
+    if (!isCurrent()) {
+      return
+    }
+    // toJSON, not the Feature: the params are frozen snapshot properties, so
+    // an instance in one is gone the moment the session reloads
+    const transcriptJson = transcript.toJSON()
+    // one transaction, so the launchers wake once, on a request that already
+    // carries its query
+    transaction(() => {
+      self.setProgress('')
       if (blastParams && !blastParams.proteinSequence) {
         self.setBlastParams({
           ...blastParams,
@@ -140,11 +191,53 @@ export function resolveConnectedTranscriptIfNeeded(
           proteinSequence,
         })
       }
-      // last, because the launchers wake on it
       self.setConnectedFeature(transcriptJson)
-    } catch (e) {
-      console.error(e)
+    })
+  } catch (e) {
+    console.error(e)
+    if (isCurrent()) {
+      self.setProgress('')
       self.setError(e)
     }
-  })()
+  }
+}
+
+/**
+ * Resolve `connectedTranscript` into `connectedFeature` once the connected
+ * genome view has its assembly and tracks, then hand the translation to
+ * whichever launch is waiting for a query.
+ *
+ * The autorun re-fires on the view's readiness (a track opened after a miss)
+ * and on the request itself, which is what `retryLaunch` re-states. The lookup
+ * runs untracked, so scrolling the genome view is not a reason to look again.
+ */
+export function resolveConnectedTranscriptIfNeeded(
+  self: JBrowsePluginMsaViewModel,
+) {
+  const {
+    connectedTranscript,
+    connectedFeature,
+    connectedView,
+    blastParams,
+    orthologParams,
+  } = self
+  if (
+    !connectedTranscript ||
+    connectedFeature ||
+    !connectedView?.initialized ||
+    connectedView.tracks.length === 0
+  ) {
+    return
+  }
+  const lookup = (latestLookup.get(self) ?? 0) + 1
+  latestLookup.set(self, lookup)
+  untracked(() => {
+    void lookUp({
+      self,
+      transcriptId: connectedTranscript,
+      blastParams,
+      orthologParams,
+      isCurrent: () => isAlive(self) && latestLookup.get(self) === lookup,
+    })
+  })
 }

package/src/MsaViewPanel/runLaunch.test.ts

@@ -137,6 +137,25 @@ describe('a launch that is abandoned', () => {
   })
 })
 
+describe('a launch started while another holds the controller', () => {
+  test('aborts the first, so nothing is left polling that Cancel cannot reach', async () => {
+    const { model } = makeModel()
+    const signals: AbortSignal[] = []
+    const launch = (scope: LaunchScope) => {
+      signals.push(scope.signal)
+      return new Promise<typeof DATA>(() => {})
+    }
+
+    runLaunch({ self: model, message: 'a', onLaunched: () => {}, launch })
+    runLaunch({ self: model, message: 'b', onLaunched: () => {}, launch })
+    await settle()
+
+    expect(signals.map(s => s.aborted)).toEqual([true, false])
+    model.launchController!.abort()
+    expect(signals[1]!.aborted).toBe(true)
+  })
+})
+
 describe('a launch that fails', () => {
   test('records the error and stops the spinner', async () => {
     vi.spyOn(console, 'error').mockImplementation(() => {})

package/src/MsaViewPanel/runLaunch.ts

@@ -1,4 +1,5 @@
 import { getSession } from '@jbrowse/core/util'
+import { untracked } from 'mobx'
 
 import { isAbortError } from '../utils/fetch'
 
@@ -64,11 +65,26 @@ interface LaunchedData {
  * Run one launch attempt, owning the AbortController that ties it to the view.
  *
  * The controller lives on the model because two things end a launch and neither
- * is here: the Cancel button, and the disposer `afterCreate` registers. Before
- * it existed, closing a view mid-BLAST left the poller checking EBI for the
- * job's lifetime and then writing to a node that was gone.
+ * is here: the Cancel button, and the disposer `afterCreate` registers. A launch
+ * already holding it is aborted first, so a re-fired autorun replaces the
+ * attempt rather than orphaning one that nothing can cancel.
+ *
+ * Runs untracked: it is called from the launch autoruns, and whatever the
+ * launch body reads before its first await would otherwise become a reason to
+ * launch again.
  */
-export function runLaunch({
+export function runLaunch(args: {
+  self: JBrowsePluginMsaViewModel
+  message: string
+  launch: (scope: LaunchScope) => Promise<LaunchedData>
+  onLaunched: () => void
+}) {
+  untracked(() => {
+    startLaunch(args)
+  })
+}
+
+function startLaunch({
   self,
   message,
   launch,
@@ -79,6 +95,7 @@ export function runLaunch({
   launch: (scope: LaunchScope) => Promise<LaunchedData>
   onLaunched: () => void
 }) {
+  self.launchController?.abort()
   const controller = new AbortController()
   const { signal } = controller
   self.setLaunchController(controller)

package/src/MsaViewPanel/storedData.test.ts

@@ -61,6 +61,9 @@ function makeModel(over: Record<string, unknown> = {}) {
     setTreeMetadata(arg: string) {
       model.data.treeMetadata = arg
     },
+    setGFF(arg: string) {
+      model.data.gff = arg
+    },
     ...over,
   }
   return model as typeof model & JBrowsePluginMsaViewModel
@@ -100,6 +103,17 @@ describe('restoring a view from IndexedDB', () => {
     expect(mockStore).not.toHaveBeenCalled()
   })
 
+  // react-msaview drops a GFF over 50kB from the snapshot too
+  test('a stored GFF comes back with the alignment', async () => {
+    mockRetrieve.mockResolvedValue({ msa: MSA, gff: 'a\t.\tdomain\t1\t2' })
+    const model = makeModel({ dataStoreId: 'msa-1' })
+
+    loadStoredData(model)
+    await settle()
+
+    expect(model.data.gff).toBe('a\t.\tdomain\t1\t2')
+  })
+
   // the row expires or the user clears site data, and the view used to reopen as
   // a blank import form with no hint that anything had been lost
   test('a row that is gone says so, in words that name the policy', async () => {
@@ -115,6 +129,32 @@ describe('restoring a view from IndexedDB', () => {
     // to import form" lands straight back on this error
     expect(model.dataStoreId).toBeUndefined()
   })
+
+  // the request that built the alignment is kept past the launch, so the view
+  // can offer to run it again instead of sending the user back to the gene
+  test('a row that is gone points at Retry when the search is still known', async () => {
+    mockRetrieve.mockResolvedValue(undefined)
+    const model = makeModel({
+      dataStoreId: 'msa-1',
+      blastParams: { blastDatabase: 'uniprotkb_swissprot' },
+    })
+
+    loadStoredData(model)
+    await settle()
+
+    expect((model.error as Error).message).toMatch(/Retry/)
+    expect(model.blastParams).toBeDefined()
+  })
+
+  test('a row that is gone with no search behind it says to relaunch', async () => {
+    mockRetrieve.mockResolvedValue(undefined)
+    const model = makeModel({ dataStoreId: 'msa-1' })
+
+    loadStoredData(model)
+    await settle()
+
+    expect((model.error as Error).message).toMatch(/Relaunch it from the gene/)
+  })
 })
 
 describe('keeping IndexedDB up to date', () => {
@@ -155,6 +195,24 @@ describe('keeping IndexedDB up to date', () => {
     expect(model.dataStoreId).toBe('msa-1')
   })
 
+  test('a GFF loaded after the first write updates the row', async () => {
+    const model = makeModel({
+      dataStoreId: 'msa-1',
+      rows: [['a', 'MK']],
+      data: { msa: MSA },
+      lastStoredData: { msa: MSA },
+    })
+
+    model.data.gff = 'a\t.\tdomain\t1\t2'
+    storeDataToIndexedDB(model)
+    await settle()
+
+    expect(mockStore).toHaveBeenCalledWith(
+      'msa-1',
+      expect.objectContaining({ gff: 'a\t.\tdomain\t1\t2' }),
+    )
+  })
+
   // a browser that refuses IndexedDB (private mode) answers every write the same
   // way, and the autorun reruns on its own isStoringData flag -- so a write that
   // is not recorded as attempted is a write that retries forever

package/src/MsaViewPanel/syncGenomeHoverToMsaColumn.test.ts

@@ -22,17 +22,18 @@ const mafRegion = {
 }
 
 // A model wired through the real genomeToMSA path: a connected genome view
-// over a maf region, with seqPosToVisibleCol as identity so the asserted
+// over a maf region, with the column converters as identity so the asserted
 // column equals the ungapped offset into the region.
 function makeModel() {
   const calls: (number | undefined)[] = []
   const model = {
     querySeqName: 'hg38.chr1',
-    rows: [['hg38.chr1', 'ACGTACGTAC']],
+    rowMap: new Map([['hg38.chr1', 'ACGTACGTAC']]),
     transcriptToMsaMap: undefined,
     mafRegion,
     connectedView: { initialized: true, assemblyNames: ['hg38'] },
     seqPosToVisibleCol: (_name: string, pos: number) => pos,
+    visibleColToSeqPos: (_name: string, col: number) => col,
     setMousePos: (col?: number) => {
       calls.push(col)
     },
@@ -40,16 +41,25 @@ function makeModel() {
   return { model, calls }
 }
 
-function hoverGenome(coord: number) {
+// this config spells the refName the same way on both sides, so the assembly
+// hands every name straight back
+const assemblyManager = {
+  get: () => ({ getCanonicalRefName: (refName: string) => refName }),
+}
+
+function mockSession(hovered: unknown) {
   mockGetSession.mockReturnValue({
-    hovered: { hoverFeature: {}, hoverPosition: { coord, refName: 'chr1' } },
+    assemblyManager,
+    hovered,
   } as unknown as ReturnType<typeof getSession>)
 }
 
+function hoverGenome(coord: number) {
+  mockSession({ hoverFeature: {}, hoverPosition: { coord, refName: 'chr1' } })
+}
+
 function clearGenomeHover() {
-  mockGetSession.mockReturnValue({
-    hovered: null,
-  } as unknown as ReturnType<typeof getSession>)
+  mockSession(null)
 }
 
 describe('syncGenomeHoverToMsaColumn (real genomeToMSA mapping)', () => {

package/src/MsaViewPanel/util.ts

@@ -1,19 +1,17 @@
 /**
- * Whether `querySeqName` names a row this alignment actually has.
+ * Whether `querySeqName` names a row this alignment actually has. The name
+ * defaults to `QUERY`, which an uploaded alignment has no reason to carry, so
+ * the genome and structure hovers ask this before mapping anything.
  *
- * react-msaview's `seqPosToGlobalCol` answers 0 for a name it does not know, so
- * without this every genome position maps to the first column and hovering the
- * genome — or a connected structure — lights column 0 of an unrelated row. The
- * name is wrong more often than it looks: it defaults to `QUERY`, which an
- * uploaded alignment has no reason to carry, and the manual panel leaves it
- * empty when it cannot match the protein to a row.
- *
- * The other direction has no such hole: msaCoordToGenomeRegions needs the query
- * row's sequence to map a column at all, so a missing row is already nothing
- * there.
+ * `rowMap`, not `rows`: `rows` is what is on screen, and a query row folded
+ * into a collapsed clade is still in the alignment, still has its columns, and
+ * still maps.
  */
-export function hasQueryRow(model: { rows: string[][]; querySeqName: string }) {
-  return model.rows.some(r => r[0] === model.querySeqName)
+export function hasQueryRow(model: {
+  rowMap: ReadonlyMap<string, string>
+  querySeqName: string
+}) {
+  return model.rowMap.has(model.querySeqName)
 }
 
 /**
@@ -53,9 +51,8 @@ export function transcriptName(transcript?: TranscriptRef) {
   return str(fields.name) ?? str(fields.id)
 }
 
-export interface QueryRowModel {
+interface QueryRowColumns {
   querySeqName: string
-  querySeqOffset: number
   seqPosToVisibleCol: (rowName: string, seqPos: number) => number | undefined
   visibleColToSeqPos: (
     rowName: string,
@@ -63,24 +60,24 @@ export interface QueryRowModel {
   ) => number | undefined
 }
 
+export interface QueryRowModel extends QueryRowColumns {
+  querySeqOffset: number
+}
+
 /**
- * The visible column showing residue `proteinPos` (0-based) of the transcript,
- * or undefined when the query row does not carry that residue or react-msaview
- * is hiding its column.
+ * The visible column showing residue `seqPos` (0-based) of the query row, or
+ * undefined when the row does not carry that residue or react-msaview is
+ * hiding its column.
  *
- * Two things separate the transcript from the row. `querySeqOffset` is the
- * trimming — a pasted BLAST alignment carries the aligned region, not the whole
- * protein. And the row can simply stop short: react-msaview answers one column
- * past the end for a position it does not have, which would light the last
- * column for every residue beyond the row, so the round trip back through
- * visibleColToSeqPos is what rejects those.
+ * react-msaview answers one column past the end for a position the row does not
+ * have, which would light the last column for every residue beyond the row, so
+ * the round trip back through visibleColToSeqPos is what rejects those.
  */
-export function transcriptPosToVisibleCol(
-  model: QueryRowModel,
-  proteinPos: number,
+export function querySeqPosToVisibleCol(
+  model: QueryRowColumns,
+  seqPos: number,
 ) {
-  const { querySeqName, querySeqOffset } = model
-  const seqPos = proteinPos - querySeqOffset
+  const { querySeqName } = model
   if (seqPos < 0) {
     return undefined
   }
@@ -91,6 +88,18 @@ export function transcriptPosToVisibleCol(
     : undefined
 }
 
+/**
+ * The visible column showing residue `proteinPos` (0-based) of the transcript.
+ * `querySeqOffset` is what separates the two: a pasted BLAST alignment carries
+ * the aligned region, not the whole protein.
+ */
+export function transcriptPosToVisibleCol(
+  model: QueryRowModel,
+  proteinPos: number,
+) {
+  return querySeqPosToVisibleCol(model, proteinPos - model.querySeqOffset)
+}
+
 export function hasHoverPosition(
   hovered: unknown,
 ): hovered is { hoverPosition: { coord: number; refName: string } } {

package/src/index.ts

@@ -28,16 +28,25 @@ export default class MsaViewPlugin extends Plugin {
   }
 
   configure(pluginManager: PluginManager) {
-    if (isAbstractMenuManager(pluginManager.rootModel)) {
-      pluginManager.rootModel.appendToSubMenu(['Add'], {
-        label: 'Multiple sequence alignment view',
-        icon: GridOn,
-        onClick: (session: AbstractSessionModel) => {
-          // stacked, by default: nothing was launched from, so there is no
-          // connected view for it to sit beside
-          launchMsaView(session, {})
-        },
-      })
+    // a throw here error-pages the whole app, and a menu entry is not worth a
+    // session: every released host's File menu already throws on append
+    try {
+      if (isAbstractMenuManager(pluginManager.rootModel)) {
+        pluginManager.rootModel.appendToSubMenu(['Add'], {
+          label: 'Multiple sequence alignment view',
+          icon: GridOn,
+          onClick: (session: AbstractSessionModel) => {
+            // stacked, by default: nothing was launched from, so there is no
+            // connected view for it to sit beside
+            launchMsaView(session, {})
+          },
+        })
+      }
+    } catch (e) {
+      console.error(
+        'jbrowse-plugin-msaview: could not add the Add menu item',
+        e,
+      )
     }
   }