jbrowse-plugin-msaview 3.2.0 → 3.4.0

package/src/MsaViewPanel/genomeToMSA.test.ts

@@ -25,6 +25,7 @@ describe('genomeToMSA', () => {
 
     const model = {
       querySeqName: 'hg38.chr1',
+      rows: [['hg38.chr1', 'ACGTACGTAC']],
       transcriptToMsaMap: undefined,
       mafRegion: {
         refName: 'chr1',
@@ -47,6 +48,7 @@ describe('genomeToMSA', () => {
 
     const model = {
       querySeqName: 'hg38.chr1',
+      rows: [['hg38.chr1', 'ACGTACGTAC']],
       transcriptToMsaMap: undefined,
       mafRegion: {
         refName: 'chr1',
@@ -75,6 +77,7 @@ describe('genomeToMSA', () => {
 
       const model = {
         querySeqName: 'hg38.chr1',
+        rows: [['hg38.chr1', 'ACGTACGTAC']],
         transcriptToMsaMap: undefined,
         mafRegion: {
           refName: 'chr1',
@@ -107,6 +110,7 @@ describe('genomeToMSA', () => {
 
       const model = {
         querySeqName: 'hg38.chr1',
+        rows: [['hg38.chr1', 'ACGTACGTAC']],
         transcriptToMsaMap: undefined,
         mafRegion: {
           refName: 'chr1',
@@ -136,6 +140,7 @@ describe('genomeToMSA', () => {
 
       const model = {
         querySeqName: 'hg38.chr1',
+        rows: [['hg38.chr1', 'ACGTACGTAC']],
         transcriptToMsaMap: undefined,
         mafRegion: {
           refName: 'chr1',
@@ -165,6 +170,7 @@ describe('genomeToMSA', () => {
 
       const model = {
         querySeqName: 'hg38.chr1',
+        rows: [['hg38.chr1', 'ACGTACGTAC']],
         transcriptToMsaMap: undefined,
         mafRegion: {
           refName: 'chr1',
@@ -193,6 +199,7 @@ describe('genomeToMSA', () => {
 
       const model = {
         querySeqName: 'hg38.chr1',
+        rows: [['hg38.chr1', 'ACGTACGTAC']],
         transcriptToMsaMap: undefined,
         mafRegion: {
           refName: 'chr1',
@@ -225,6 +232,7 @@ describe('genomeToMSA', () => {
 
       const model = {
         querySeqName: 'QUERY',
+        rows: [['QUERY', 'MKVLTAEEK']],
         transcriptToMsaMap: {
           refName: 'chr1',
           // g2p is keyed by 0-based genome position, the hover coord is 1-based
@@ -254,6 +262,7 @@ describe('genomeToMSA', () => {
       const mockSeqPosToVisibleCol = vi.fn()
       const model = {
         querySeqName: 'QUERY',
+        rows: [['QUERY', 'MKVLTAEEK']],
         transcriptToMsaMap: {
           refName: 'chr1',
           g2p: { 1004: 10 },
@@ -277,6 +286,7 @@ describe('genomeToMSA', () => {
 
       const model = {
         querySeqName: 'QUERY',
+        rows: [['QUERY', 'MKVLTAEEK']],
         transcriptToMsaMap: {
           refName: 'chr1',
           g2p: { 1000: 0 }, // No entry for 1004
@@ -301,6 +311,7 @@ describe('genomeToMSA', () => {
 
     const model = {
       querySeqName: 'QUERY',
+      rows: [['QUERY', 'MKVLTAEEK']],
       transcriptToMsaMap: undefined,
       mafRegion: undefined,
       connectedView: { initialized: true },
@@ -310,4 +321,30 @@ describe('genomeToMSA', () => {
     const result = genomeToMSA({ model })
     expect(result).toBeUndefined()
   })
+
+  // seqPosToVisibleCol answers 0 for a row name it does not know, so without a
+  // guard an alignment whose query row is missing -- the default 'QUERY' on an
+  // uploaded file, or the empty name the manual panel leaves when it matches
+  // nothing -- lights column 0 on every genome hover
+  test('returns undefined when querySeqName names no row here', () => {
+    mockGetSession.mockReturnValue({
+      hovered: {
+        hoverFeature: {},
+        hoverPosition: { coord: 1005, refName: 'chr1' },
+      },
+    } as any)
+
+    const seqPosToVisibleCol = vi.fn(() => 0)
+    const model = {
+      querySeqName: 'QUERY',
+      rows: [['some_other_row', 'MKVLTAEEK']],
+      transcriptToMsaMap: { refName: 'chr1', g2p: { 1004: 3 } },
+      mafRegion: undefined,
+      connectedView: { initialized: true },
+      seqPosToVisibleCol,
+    } as any
+
+    expect(genomeToMSA({ model })).toBeUndefined()
+    expect(seqPosToVisibleCol).not.toHaveBeenCalled()
+  })
 })

package/src/MsaViewPanel/genomeToMSA.ts

@@ -1,6 +1,6 @@
 import { getSession } from '@jbrowse/core/util'
 
-import { hasHoverPosition } from './util'
+import { hasHoverPosition, hasQueryRow } from './util'
 
 import type { JBrowsePluginMsaViewModel } from './model'
 
@@ -8,7 +8,11 @@ export function genomeToMSA({ model }: { model: JBrowsePluginMsaViewModel }) {
   const { hovered } = getSession(model)
   const { querySeqName, transcriptToMsaMap, connectedView, mafRegion } = model
 
-  if (!connectedView?.initialized || !hasHoverPosition(hovered)) {
+  if (
+    !connectedView?.initialized ||
+    !hasHoverPosition(hovered) ||
+    !hasQueryRow(model)
+  ) {
     return undefined
   }
 

package/src/MsaViewPanel/model.ts

@@ -25,11 +25,12 @@ import {
   msaCoordToGenomeRegions,
 } from './msaCoordToGenomeCoord'
 
-import type { MafRegion, MsaViewInitState } from './types'
 import type {
   BlastDatabase,
   MsaAlgorithm,
+  PhmmerDatabase,
 } from '../LaunchMsaView/components/BlastQuery/consts'
+import type { MafRegion, MsaViewInitState } from './types'
 import type { Feature } from '@jbrowse/core/util'
 import type { Instance } from '@jbrowse/mobx-state-tree'
 import type { LinearGenomeViewModel } from '@jbrowse/plugin-linear-genome-view'
@@ -44,16 +45,48 @@ export interface IRegion {
   end: number
 }
 
-export interface BlastParams {
-  blastDatabase: BlastDatabase
-  msaAlgorithm: MsaAlgorithm
+/**
+ * A search to run, discriminated by the program that runs it: the two arms
+ * differ in which databases they name and in whether an aligner runs at all, so
+ * splitting them is what lets doLaunchBlast read the database without asserting
+ * whose it is.
+ *
+ * The field is still `blastDatabase` rather than `database`: it is persisted in
+ * session snapshots and in the IndexedDB result cache, so renaming it would
+ * orphan every row already written.
+ */
+export type BlastParams = {
   selectedTranscript?: Feature
   proteinSequence: string
-}
+} & (
+  | {
+      /** absent on params written before phmmer existed, which were all blastp */
+      searchProgram?: 'blastp'
+      blastDatabase: BlastDatabase
+      msaAlgorithm: MsaAlgorithm
+    }
+  | {
+      searchProgram: 'phmmer'
+      /** phmmer names its databases its own way: `swissprot`, not `uniprotkb_swissprot` */
+      blastDatabase: PhmmerDatabase
+      /** phmmer aligns as it searches, so there is no aligner to choose */
+      msaAlgorithm?: undefined
+    }
+)
+
+/**
+ * Where the ortholog set comes from. NCBI's sets cover vertebrates and
+ * insects; PANTHER's span its 144 reference proteomes, human to yeast to
+ * Arabidopsis, so a gene from outside NCBI's scope aligns only through it.
+ */
+export const orthologSources = ['ncbi', 'panther'] as const
+export type OrthologSource = (typeof orthologSources)[number]
 
 export interface OrthologParams {
   /** NCBI taxon id of the assembly the query gene came from */
   taxId: number
+  /** `ncbi` when omitted, so every launch written before this key keeps its meaning */
+  source?: OrthologSource
   /**
    * taxon ids to include as rows. The query taxon has its own row already, so
    * it is excluded from this set whether or not it is named.

package/src/MsaViewPanel/observeProteinHighlights.test.ts

@@ -30,6 +30,7 @@ function makeModel({ highlightColumns }: { highlightColumns?: number[] } = {}) {
   const calls: (number[] | undefined)[] = []
   const model = {
     querySeqName: 'query',
+    rows: [['query', 'MKVLTAEEK']],
     connectedViewId: CONNECTED,
     // g2p is indexed by genome coord; identity keeps the arithmetic out of the way
     transcriptToMsaMap: {
@@ -249,6 +250,18 @@ describe('scope and redundant writes', () => {
     expect(calls).toEqual([])
   })
 
+  // seqPosToGlobalCol answers 0 for a row name it does not know, so without a
+  // guard a structure hover would light column 0 of whatever row is first
+  test('a query row this alignment does not have contributes no column', () => {
+    const { model, calls } = makeModel()
+    Object.assign(model, { rows: [['some_other_row', 'MKVLTAEEK']] })
+    const run = observeProteinHighlights(model)
+
+    session({ hover: [{ start: 10, end: 12 }] })
+    run()
+    expect(calls).toEqual([])
+  })
+
   test('nothing happens until the view is connected and mapped', () => {
     const { calls } = makeModel()
     const bare = {

package/src/MsaViewPanel/syncGenomeHoverToMsaColumn.test.ts

@@ -28,6 +28,7 @@ function makeModel() {
   const calls: (number | undefined)[] = []
   const model = {
     querySeqName: 'hg38.chr1',
+    rows: [['hg38.chr1', 'ACGTACGTAC']],
     transcriptToMsaMap: undefined,
     mafRegion,
     connectedView: { initialized: true, assemblyNames: ['hg38'] },

package/src/MsaViewPanel/util.ts

@@ -1,3 +1,21 @@
+/**
+ * Whether `querySeqName` names a row this alignment actually has.
+ *
+ * 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.
+ */
+export function hasQueryRow(model: { rows: string[][]; querySeqName: string }) {
+  return model.rows.some(r => r[0] === model.querySeqName)
+}
+
 export function hasHoverPosition(
   hovered: unknown,
 ): hovered is { hoverPosition: { coord: number; refName: string } } {

package/src/utils/blastCache.ts

@@ -3,6 +3,8 @@ import { createDbOpener } from './idb'
 import type {
   BlastDatabase,
   MsaAlgorithm,
+  PhmmerDatabase,
+  SearchProgram,
 } from '../LaunchMsaView/components/BlastQuery/consts'
 import type { DBSchema } from 'idb'
 
@@ -13,14 +15,17 @@ const DB_VERSION = 2
 export interface CachedBlastResult {
   id: string
   proteinSequence: string
-  blastDatabase: BlastDatabase
+  blastDatabase: BlastDatabase | PhmmerDatabase
   /**
    * Only ever set on rows cached by a version that still queried NCBI, where
    * the choice between blastp and quick-blastp was real. Kept so those rows
    * still display; never written now.
    */
   blastProgram?: string
-  msaAlgorithm: MsaAlgorithm
+  /** absent on rows cached before phmmer existed, which were all blastp */
+  searchProgram?: SearchProgram
+  /** absent on phmmer rows, which are aligned by the search itself */
+  msaAlgorithm?: MsaAlgorithm
   msa: string
   tree: string
   treeMetadata: string
@@ -52,13 +57,25 @@ const getDB = createDbOpener<BlastCacheDB>(
   },
 )
 
-function createCacheKey(
-  proteinSequence: string,
-  blastDatabase: BlastDatabase,
-  msaAlgorithm: MsaAlgorithm,
-  transcriptId?: string,
-) {
+function createCacheKey({
+  proteinSequence,
+  blastDatabase,
+  msaAlgorithm,
+  searchProgram,
+  transcriptId,
+}: {
+  proteinSequence: string
+  blastDatabase: BlastDatabase | PhmmerDatabase
+  msaAlgorithm?: MsaAlgorithm
+  searchProgram?: SearchProgram
+  transcriptId?: string
+}) {
   const idPart = transcriptId ? `:${transcriptId}` : ''
+  // phmmer keys are prefixed and blastp keys are left exactly as they were, so
+  // results cached before phmmer existed still resolve
+  if (searchProgram === 'phmmer') {
+    return `phmmer:${blastDatabase}${idPart}:${proteinSequence}`
+  }
   // msaAlgorithm is part of the key because the stored msa/tree are produced by
   // it — without it, re-running the same query under a different algorithm
   // overwrites the earlier result and drops it from the history list
@@ -69,6 +86,7 @@ export async function saveBlastResult({
   proteinSequence,
   blastDatabase,
   msaAlgorithm,
+  searchProgram,
   msa,
   tree,
   treeMetadata,
@@ -79,8 +97,9 @@ export async function saveBlastResult({
   geneName,
 }: {
   proteinSequence: string
-  blastDatabase: BlastDatabase
-  msaAlgorithm: MsaAlgorithm
+  blastDatabase: BlastDatabase | PhmmerDatabase
+  msaAlgorithm?: MsaAlgorithm
+  searchProgram?: SearchProgram
   msa: string
   tree: string
   treeMetadata: string
@@ -91,17 +110,19 @@ export async function saveBlastResult({
   geneName?: string
 }) {
   const db = await getDB()
-  const id = createCacheKey(
+  const id = createCacheKey({
     proteinSequence,
     blastDatabase,
     msaAlgorithm,
+    searchProgram,
     transcriptId,
-  )
+  })
   const entry: CachedBlastResult = {
     id,
     proteinSequence,
     blastDatabase,
     msaAlgorithm,
+    searchProgram,
     msa,
     tree,
     treeMetadata,

package/src/utils/ebiBlast.ts

@@ -1,7 +1,7 @@
 import { fetchEbiResult, submitEbiJob, waitForEbiJob } from './ebiJobDispatcher'
 
-import type { BlastHit } from './types'
 import type { BlastDatabase } from '../LaunchMsaView/components/BlastQuery/consts'
+import type { BlastHit } from './types'
 
 const TOOL = 'ncbiblast'
 

package/src/utils/msa.ts

@@ -32,6 +32,43 @@ const algorithms: Record<
   },
 }
 
+/**
+ * Build a tree from an alignment that already exists, which is what the phmmer
+ * path needs: phmmer produces the alignment itself, so there is no aligner run
+ * to take a guide tree from — and a guide tree is a byproduct of deciding
+ * progressive alignment order, not a phylogeny, so it is not what we would want
+ * even if there were one. simple_phylogeny is clustalw2's neighbour-joining on
+ * a real distance matrix, Kimura-corrected for protein distances.
+ */
+export async function launchTree({
+  alignment,
+  onProgress,
+}: {
+  alignment: string
+  onProgress: (arg: string) => void
+}) {
+  const tool = 'simple_phylogeny'
+  onProgress('Building tree...')
+
+  const jobId = await submitEbiJob({
+    tool,
+    params: {
+      sequence: alignment,
+      tree: 'phylip',
+      clustering: 'Neighbour-joining',
+      kimura: 'true',
+    },
+  })
+  await waitForEbiJob({
+    tool,
+    jobId,
+    onCountdown: s => {
+      onProgress(`Re-checking tree status in... ${s}`)
+    },
+  })
+  return fetchEbiResult({ tool, jobId, type: 'tree' })
+}
+
 export async function launchMSA({
   algorithm,
   sequence,
@@ -56,16 +93,10 @@ export async function launchMSA({
       onProgress(`Re-checking MSA status in... ${s}`)
     },
   })
-  return {
-    msa: await fetchEbiResult({
-      tool: algorithm,
-      jobId,
-      type: config.msaResult,
-    }),
-    tree: await fetchEbiResult({
-      tool: algorithm,
-      jobId,
-      type: config.treeResult,
-    }),
-  }
+  // one finished job, two result files, neither derived from the other
+  const [msa, tree] = await Promise.all([
+    fetchEbiResult({ tool: algorithm, jobId, type: config.msaResult }),
+    fetchEbiResult({ tool: algorithm, jobId, type: config.treeResult }),
+  ])
+  return { msa, tree }
 }

package/src/utils/msaRows.ts

@@ -0,0 +1,95 @@
+import { makeId } from '../LaunchMsaView/components/util'
+
+import type { PhmmerRow } from './phmmer'
+import type { TaxonomyInfo } from './taxonomyNames'
+import type { BlastHitDescription } from './types'
+
+/**
+ * Turning search results into the rows the view is given, kept free of any
+ * jbrowse or network import so the whole assembly can be run and checked
+ * outside a browser — see test/phmmerLive.test.ts.
+ */
+export function buildRowMetadata(
+  desc: BlastHitDescription,
+  taxonomyInfo: Map<number, TaxonomyInfo>,
+) {
+  const metadata: Record<string, string> = {}
+  const taxInfo = desc.taxid ? taxonomyInfo.get(desc.taxid) : undefined
+
+  if (taxInfo?.sciname) {
+    metadata['Scientific name'] = taxInfo.sciname
+  }
+  if (taxInfo?.commonName) {
+    metadata['Common name'] = taxInfo.commonName
+  }
+  if (desc.accession) {
+    metadata.Accession = desc.accession
+  }
+  if (desc.id) {
+    metadata.ID = desc.id
+  }
+  if (desc.title) {
+    metadata.Description = desc.title
+  }
+
+  return metadata
+}
+
+/**
+ * One target can match the query in several places and phmmer emits a row per
+ * matched envelope — four for lamprey albumin against human albumin, which has
+ * three domains. Those rows share an accession and so would share a name, and
+ * duplicate names silently collapse rows in both the MSA and the tree, so the
+ * envelope disambiguates them.
+ */
+export function makeRowNames(
+  rows: PhmmerRow[],
+  taxonomyInfo: Map<number, TaxonomyInfo>,
+) {
+  const baseNames = rows.map(row => makeId(row, taxonomyInfo))
+  const counts = new Map<string, number>()
+  for (const name of baseNames) {
+    counts.set(name, (counts.get(name) ?? 0) + 1)
+  }
+
+  const used = new Set<string>()
+  return baseNames.map((base, i) => {
+    let name =
+      counts.get(base)! > 1 ? `${base}_${rows[i]!.range ?? i + 1}` : base
+    while (used.has(name)) {
+      name = `${name}_${i + 1}`
+    }
+    used.add(name)
+    return name
+  })
+}
+
+/**
+ * The phmmer alignment as the view receives it: aligned FASTA whose first row
+ * is the query, plus the per-row metadata keyed by the same names, which are
+ * also what the tree's leaves are labelled with.
+ */
+export function buildPhmmerMsa({
+  rows,
+  queryRow,
+  taxonomyInfo,
+  querySeqName = 'QUERY',
+}: {
+  rows: PhmmerRow[]
+  queryRow: string
+  taxonomyInfo: Map<number, TaxonomyInfo>
+  querySeqName?: string
+}) {
+  const treeMetadata: Record<string, Record<string, string>> = {}
+  const rowNames = makeRowNames(rows, taxonomyInfo)
+  const sequences = rows.map((row, i) => {
+    const rowName = rowNames[i]!
+    treeMetadata[rowName] = buildRowMetadata(row, taxonomyInfo)
+    return `>${rowName}\n${row.aligned}`
+  })
+
+  return {
+    msa: [`>${querySeqName}\n${queryRow}`, ...sequences].join('\n'),
+    treeMetadata,
+  }
+}