jbrowse-plugin-msaview 3.3.0 → 3.4.0

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,
+  }
+}

package/src/utils/phmmer.ts

@@ -0,0 +1,174 @@
+import { StockholmMSA } from 'msa-parsers'
+
+import { fetchEbiResult, submitEbiJob, waitForEbiJob } from './ebiJobDispatcher'
+
+import type { PhmmerDatabase } from '../LaunchMsaView/components/BlastQuery/consts'
+
+const TOOL = 'hmmer3_phmmer'
+
+export interface PhmmerRow {
+  accession: string
+  id: string
+  sciname: string
+  taxid?: number
+  title?: string
+  /** the matched envelope on the target, e.g. '503-912', absent if unparseable */
+  range?: string
+  /** the row as phmmer aligned it, uppercased with '.' inserts turned into '-' */
+  aligned: string
+}
+
+export interface PhmmerAlignment {
+  rows: PhmmerRow[]
+  /**
+   * the query, placed into the same columns. phmmer does not put the query in
+   * its own output, so this is derived — see buildQueryRow.
+   */
+  queryRow: string
+}
+
+/**
+ * Human-facing link to a job, shown while it runs and on error.
+ *
+ * The category has to be sss: jdispatcher serves its shell with a 200 for any
+ * category, so /pfa/ and /psa/ look fine to a fetch and render "Page Not Found"
+ * in a browser.
+ */
+export function phmmerResultUrl(jobId: string) {
+  return `https://www.ebi.ac.uk/jdispatcher/sss/${TOOL}/summary?jobId=${jobId}`
+}
+
+/** EBI job ids are prefixed with the tool that made them */
+export function isPhmmerJobId(jobId: string) {
+  return jobId.startsWith(`${TOOL}-`)
+}
+
+/**
+ * phmmer aligns every hit to a profile built from the query, one match state
+ * per query residue, and marks those columns 'x' in #=GC RF. So the query's own
+ * row is exactly recoverable: walk RF, consume a query residue at each match
+ * column, gap everywhere else.
+ *
+ * This is the one piece of real logic here rather than a library call, and it
+ * is checked hard: if the match columns do not account for the query exactly,
+ * the columns and the query have drifted apart, and a query row that is off by
+ * even one residue would silently mis-map every column to the genome. Throwing
+ * is much better than drawing that.
+ */
+function buildQueryRow({ rf, query }: { rf: string; query: string }) {
+  let consumed = 0
+  const row = Array.from(rf, c =>
+    c === 'x' ? (query[consumed++] ?? '-') : '-',
+  ).join('')
+  if (consumed !== query.length) {
+    throw new Error(
+      `phmmer alignment has ${consumed} match columns for a query of ${query.length} residues, so the query row cannot be placed`,
+    )
+  }
+  return row
+}
+
+/**
+ * '[subseq from] Albumin OS=Homo sapiens OX=9606 GN=ALB PE=1 SV=2' is what a
+ * UniProt target's #=GS DE looks like. Hits from the non-UniProt databases
+ * phmmer also offers (PDB, AlphaFold, MEROPS...) carry no OS=/OX= at all, so
+ * every field here is optional.
+ */
+function parseDescription(de: string | undefined) {
+  const text = (de ?? '').replace('[subseq from] ', '')
+  const sciname = /OS=(.*?)\s+(?:OX|GN|PE|SV)=/.exec(text)?.[1]
+  const ox = /OX=(\d+)/.exec(text)?.[1]
+  return {
+    sciname: sciname ?? 'unknown',
+    taxid: ox ? Number.parseInt(ox, 10) : undefined,
+    title: text.split(' OS=')[0] || undefined,
+  }
+}
+
+/**
+ * Target names look like 'sp|P02768|ALBU_HUMAN/1-609' for UniProt databases and
+ * like anything at all for the others, so an unrecognized name becomes its own
+ * accession rather than being dropped.
+ */
+function parseName(name: string) {
+  const slash = name.lastIndexOf('/')
+  const range =
+    slash === -1 ? undefined : /^\d+-\d+$/.exec(name.slice(slash + 1))?.[0]
+  const bare = range === undefined ? name : name.slice(0, slash)
+  const parts = bare.split('|')
+  return parts.length === 3
+    ? { accession: parts[1]!, id: parts[2]!, range }
+    : { accession: bare, id: bare, range }
+}
+
+/**
+ * Exported for testing against a captured .sto — the annotation names (RF, the
+ * DE line's OS=/OX=) are the whole risk in this mapping, and nothing else in CI
+ * would notice if HMMER or EBI changed one.
+ */
+export function parsePhmmerAlignment({
+  stockholm,
+  query,
+}: {
+  stockholm: string
+  query: string
+}): PhmmerAlignment {
+  const { gc, gs, seqdata, seqname } = new StockholmMSA(stockholm, 0).getMSA()
+  const rf = gc.RF
+  if (!rf) {
+    throw new Error('phmmer alignment has no #=GC RF line')
+  }
+
+  return {
+    queryRow: buildQueryRow({ rf, query }),
+    rows: seqname.map(name => ({
+      ...parseName(name),
+      ...parseDescription(gs.DE?.[name]?.[0]),
+      // insert columns come back lowercase with '.' for gaps; the MSA renderer
+      // looks colors up by the literal letter, so lowercase would draw
+      // uncolored. The insert columns stay visible as gaps in the query row.
+      aligned: (seqdata[name] ?? '').replaceAll('.', '-').toUpperCase(),
+    })),
+  }
+}
+
+export async function queryPhmmer({
+  query,
+  database,
+  onProgress,
+  onRid,
+}: {
+  query: string
+  database: PhmmerDatabase
+  onProgress: (arg: string) => void
+  onRid: (arg: string) => void
+}) {
+  onProgress('Submitting to EBI phmmer...')
+  const jobId = await submitEbiJob({
+    tool: TOOL,
+    params: {
+      database,
+      sequence: query,
+      // the alignment is the whole point of using phmmer here
+      alignView: 'true',
+    },
+  })
+  onRid(jobId)
+
+  await waitForEbiJob({
+    tool: TOOL,
+    jobId,
+    onCountdown: s => {
+      onProgress(`Re-checking phmmer status in... ${s}`)
+    },
+  })
+
+  const alignment = parsePhmmerAlignment({
+    stockholm: await fetchEbiResult({ tool: TOOL, jobId, type: 'sto' }),
+    query,
+  })
+  if (alignment.rows.length === 0) {
+    throw new Error('No hits found')
+  }
+  return { rid: jobId, ...alignment }
+}

package/src/utils/taxonomyNames.ts

@@ -51,8 +51,13 @@ export interface TaxonomyInfo {
 }
 
 export async function fetchTaxonomyInfo(
-  taxids: number[],
+  taxidsWithRepeats: number[],
 ): Promise<Map<number, TaxonomyInfo>> {
+  // callers pass one taxid per alignment row, and a BLAST hit list is several
+  // rows per species: 100 albumin hits are maybe 50 taxa, and asking as they
+  // came did 100 IndexedDB reads and sent eutils 100 ids for 50 answers. The
+  // result is keyed by taxid, so no caller can tell the difference
+  const taxids = [...new Set(taxidsWithRepeats)]
   const result = new Map<number, TaxonomyInfo>()
   const uncachedTaxids: number[] = []
   const cachedResults = await getCachedTaxonomies(taxids)

package/src/version.ts

@@ -1 +1 @@
-export const version = '3.3.0'
+export const version = '3.4.0'

package/dist/MsaViewPanel/components/LoadingBLAST.d.ts

@@ -1,6 +0,0 @@
-import React from 'react';
-import type { JBrowsePluginMsaViewModel } from '../model';
-declare const LoadingBLAST: ({ model, }: {
-    model: JBrowsePluginMsaViewModel;
-}) => React.JSX.Element;
-export default LoadingBLAST;

package/dist/MsaViewPanel/components/LoadingBLAST.js

@@ -1,26 +0,0 @@
-import React from 'react';
-import { ErrorMessage, LoadingEllipses } from '@jbrowse/core/ui';
-import { Typography } from '@mui/material';
-import { observer } from 'mobx-react';
-import { makeStyles } from 'tss-react/mui';
-import JobLink from './JobLink';
-const useStyles = makeStyles()(theme => ({
-    margin: {
-        padding: 20,
-    },
-    loading: {
-        background: theme.palette.background.paper,
-    },
-}));
-const LoadingBLAST = observer(function LoadingBLAST2({ model, }) {
-    const { progress, rid, error } = model;
-    const { classes } = useStyles();
-    return (React.createElement("div", { className: classes.margin },
-        React.createElement(LoadingEllipses, { message: "Running EBI BLAST", variant: "h5" }),
-        error ? (React.createElement("div", null,
-            rid ? React.createElement(JobLink, { jobId: rid }) : null,
-            React.createElement(ErrorMessage, { error: error }))) : rid ? (React.createElement("div", { className: classes.loading },
-            React.createElement(JobLink, { jobId: rid }),
-            React.createElement(Typography, null, progress))) : (React.createElement(Typography, null, progress || 'Initializing BLAST query'))));
-});
-export default LoadingBLAST;

package/src/MsaViewPanel/components/LoadingBLAST.tsx

@@ -1,48 +0,0 @@
-import React from 'react'
-
-import { ErrorMessage, LoadingEllipses } from '@jbrowse/core/ui'
-import { Typography } from '@mui/material'
-import { observer } from 'mobx-react'
-import { makeStyles } from 'tss-react/mui'
-
-import JobLink from './JobLink'
-
-import type { JBrowsePluginMsaViewModel } from '../model'
-
-const useStyles = makeStyles()(theme => ({
-  margin: {
-    padding: 20,
-  },
-  loading: {
-    background: theme.palette.background.paper,
-  },
-}))
-
-const LoadingBLAST = observer(function LoadingBLAST2({
-  model,
-}: {
-  model: JBrowsePluginMsaViewModel
-}) {
-  const { progress, rid, error } = model
-  const { classes } = useStyles()
-  return (
-    <div className={classes.margin}>
-      <LoadingEllipses message="Running EBI BLAST" variant="h5" />
-      {error ? (
-        <div>
-          {rid ? <JobLink jobId={rid} /> : null}
-          <ErrorMessage error={error} />
-        </div>
-      ) : rid ? (
-        <div className={classes.loading}>
-          <JobLink jobId={rid} />
-          <Typography>{progress}</Typography>
-        </div>
-      ) : (
-        <Typography>{progress || 'Initializing BLAST query'}</Typography>
-      )}
-    </div>
-  )
-})
-
-export default LoadingBLAST