jbrowse-plugin-msaview 3.2.0 → 3.4.0

package/src/MsaViewPanel/doLaunchBlast.ts

@@ -2,45 +2,112 @@ import { makeId, strip } from '../LaunchMsaView/components/util'
 import { cleanProteinSequence } from '../LaunchMsaView/util'
 import { saveBlastResult } from '../utils/blastCache'
 import { queryEbiBlast } from '../utils/ebiBlast'
-import { launchMSA } from '../utils/msa'
+import { launchMSA, launchTree } from '../utils/msa'
+import { buildPhmmerMsa, buildRowMetadata } from '../utils/msaRows'
+import { queryPhmmer } from '../utils/phmmer'
 import { fetchTaxonomyInfo } from '../utils/taxonomyNames'
 
+import type {
+  BlastDatabase,
+  MsaAlgorithm,
+  PhmmerDatabase,
+} from '../LaunchMsaView/components/BlastQuery/consts'
 import type { JBrowsePluginMsaViewModel } from './model'
-import type { TaxonomyInfo } from '../utils/taxonomyNames'
-import type { BlastHitDescription } from '../utils/types'
+
+type TreeMetadata = Record<string, Record<string, string>>
 
 export async function doLaunchBlast({
   self,
 }: {
   self: JBrowsePluginMsaViewModel
 }) {
-  const { blastDatabase, msaAlgorithm, proteinSequence, selectedTranscript } =
-    self.blastParams!
-  const cleanedSeq = cleanProteinSequence(proteinSequence)
+  // kept whole rather than destructured: the database's type depends on
+  // searchProgram, and pulling the two apart loses the link between them
+  const params = self.blastParams!
+  const { selectedTranscript } = params
+  const cleanedSeq = cleanProteinSequence(params.proteinSequence)
 
   const onProgress = (arg: string) => {
     self.setProgress(arg)
   }
+  // publish the job id before the first poll so the view can link out while the
+  // job is still running
+  const onRid = (r: string) => {
+    self.setRid(r)
+  }
+
+  const { msa, tree, treeMetadata, rid } =
+    params.searchProgram === 'phmmer'
+      ? await runPhmmer({
+          query: cleanedSeq,
+          database: params.blastDatabase,
+          onProgress,
+          onRid,
+        })
+      : await runBlast({
+          query: cleanedSeq,
+          blastDatabase: params.blastDatabase,
+          msaAlgorithm: params.msaAlgorithm,
+          onProgress,
+          onRid,
+        })
+
+  const treeMetadataJson = JSON.stringify(treeMetadata)
+
+  await saveBlastResult({
+    proteinSequence: cleanedSeq,
+    blastDatabase: params.blastDatabase,
+    msaAlgorithm: params.msaAlgorithm,
+    searchProgram: params.searchProgram,
+    msa,
+    tree,
+    treeMetadata: treeMetadataJson,
+    rid,
+    geneId: selectedTranscript?.get('parentId'),
+    transcriptId: selectedTranscript?.id(),
+    transcriptName:
+      selectedTranscript?.get('name') ?? selectedTranscript?.get('id'),
+    geneName:
+      selectedTranscript?.get('gene_name') ??
+      selectedTranscript?.get('parentId'),
+  })
 
+  return { msa, tree, treeMetadata: treeMetadataJson }
+}
+
+/**
+ * BLAST returns each hit already aligned to the query, but pairwise and one hit
+ * at a time, so the alignments are stripped back off and every hit is realigned
+ * together by a dedicated aligner.
+ */
+async function runBlast({
+  query,
+  blastDatabase,
+  msaAlgorithm,
+  onProgress,
+  onRid,
+}: {
+  query: string
+  blastDatabase: BlastDatabase
+  msaAlgorithm: MsaAlgorithm
+  onProgress: (arg: string) => void
+  onRid: (arg: string) => void
+}) {
   const { hits, rid } = await queryEbiBlast({
-    query: cleanedSeq,
+    query,
     blastDatabase,
     onProgress,
-    // publish the job id before the first poll so the view can link out while
-    // the job is still running
-    onRid: r => {
-      self.setRid(r)
-    },
+    onRid,
   })
 
-  self.setProgress('Fetching species taxonomy info...')
-  const taxids = hits
-    .map(h => h.description[0]?.taxid)
-    .filter((t): t is number => t !== undefined)
-  const taxonomyInfo = await fetchTaxonomyInfo(taxids)
-
-  const treeMetadata: Record<string, Record<string, string>> = {}
+  onProgress('Fetching species taxonomy info...')
+  const taxonomyInfo = await fetchTaxonomyInfo(
+    hits
+      .map(h => h.description[0]?.taxid)
+      .filter((t): t is number => t !== undefined),
+  )
 
+  const treeMetadata: TreeMetadata = {}
   const sequences = hits.map(h => {
     const desc = h.description[0] ?? {
       accession: 'unknown',
@@ -48,66 +115,57 @@ export async function doLaunchBlast({
       sciname: 'unknown',
     }
     const rowName = makeId(desc, taxonomyInfo)
-    const seq = strip(h.hsps[0]?.hseq ?? '')
-
     treeMetadata[rowName] = buildRowMetadata(desc, taxonomyInfo)
-
-    return `>${rowName}\n${seq}`
+    return `>${rowName}\n${strip(h.hsps[0]?.hseq ?? '')}`
   })
 
   const result = await launchMSA({
     algorithm: msaAlgorithm,
-    sequence: [`>QUERY\n${cleanedSeq}`, ...sequences].join('\n'),
+    sequence: [`>QUERY\n${query}`, ...sequences].join('\n'),
     onProgress,
   })
+  return { ...result, treeMetadata, rid }
+}
 
-  const treeMetadataJson = JSON.stringify(treeMetadata)
-
-  await saveBlastResult({
-    proteinSequence: cleanedSeq,
-    blastDatabase,
-    msaAlgorithm,
-    msa: result.msa,
-    tree: result.tree,
-    treeMetadata: treeMetadataJson,
-    rid,
-    geneId: selectedTranscript?.get('parentId'),
-    transcriptId: selectedTranscript?.id(),
-    transcriptName:
-      selectedTranscript?.get('name') ?? selectedTranscript?.get('id'),
-    geneName:
-      selectedTranscript?.get('gene_name') ??
-      selectedTranscript?.get('parentId'),
+/**
+ * phmmer aligns every hit to a profile of the query as it searches, so its own
+ * output is the MSA and there is no realignment step — the hits keep the
+ * placement HMMER gave them, and the query row is derived from the alignment's
+ * match columns rather than being aligned back in afterwards. That leaves no
+ * aligner run to take a tree from, so the tree is built from this alignment.
+ */
+async function runPhmmer({
+  query,
+  database,
+  onProgress,
+  onRid,
+}: {
+  query: string
+  database: PhmmerDatabase
+  onProgress: (arg: string) => void
+  onRid: (arg: string) => void
+}) {
+  const { rows, queryRow, rid } = await queryPhmmer({
+    query,
+    database,
+    onProgress,
+    onRid,
   })
 
-  return {
-    ...result,
-    treeMetadata: treeMetadataJson,
-  }
-}
-
-function buildRowMetadata(
-  desc: BlastHitDescription,
-  taxonomyInfo: Map<number, TaxonomyInfo>,
-) {
-  const metadata: Record<string, string> = {}
-  const taxInfo = desc.taxid ? taxonomyInfo.get(desc.taxid) : undefined
+  onProgress('Fetching species taxonomy info...')
+  const taxonomyInfo = await fetchTaxonomyInfo(
+    rows.map(r => r.taxid).filter((t): t is number => t !== 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
+  const { msa, treeMetadata } = buildPhmmerMsa({
+    rows,
+    queryRow,
+    taxonomyInfo,
+  })
+  return {
+    msa,
+    tree: await launchTree({ alignment: msa, onProgress }),
+    treeMetadata,
+    rid,
   }
-
-  return metadata
 }

package/src/MsaViewPanel/doLaunchOrthologs.test.ts

@@ -1,6 +1,5 @@
 import { beforeEach, describe, expect, test, vi } from 'vitest'
 
-import { doLaunchOrthologs } from './doLaunchOrthologs'
 import { launchMSA } from '../utils/msa'
 import {
   defaultMaxSpecies,
@@ -8,10 +7,12 @@ import {
   fetchProteinForGene,
   resolveGeneId,
 } from '../utils/ncbiOrthologs'
+import { fetchPantherOrthologs } from '../utils/pantherOrthologs'
 import { fetchTaxonomyInfo } from '../utils/taxonomyNames'
+import { doLaunchOrthologs } from './doLaunchOrthologs'
 
-import type { JBrowsePluginMsaViewModel } from './model'
 import type { OrthologRow } from '../utils/ncbiOrthologs'
+import type { JBrowsePluginMsaViewModel } from './model'
 
 // Every network call is mocked and nothing else is. What is under test is the
 // argument shaping either side of those calls -- which species get asked for,
@@ -24,12 +25,16 @@ vi.mock('../utils/ncbiOrthologs', async importOriginal => ({
   fetchProteinForGene: vi.fn(),
   fetchOrthologRows: vi.fn(),
 }))
+vi.mock('../utils/pantherOrthologs', () => ({
+  fetchPantherOrthologs: vi.fn(),
+}))
 vi.mock('../utils/msa', () => ({ launchMSA: vi.fn() }))
 vi.mock('../utils/taxonomyNames', () => ({ fetchTaxonomyInfo: vi.fn() }))
 
 const mockResolveGeneId = vi.mocked(resolveGeneId)
 const mockFetchProtein = vi.mocked(fetchProteinForGene)
 const mockFetchRows = vi.mocked(fetchOrthologRows)
+const mockFetchPanther = vi.mocked(fetchPantherOrthologs)
 const mockLaunchMSA = vi.mocked(launchMSA)
 const mockFetchTaxonomy = vi.mocked(fetchTaxonomyInfo)
 
@@ -245,3 +250,115 @@ describe('the Accession that drives the domain overlay', () => {
     expect(queryMetadata(result).Accession).toBeUndefined()
   })
 })
+
+// The second source. What is under test is the dispatch and what the PANTHER
+// result becomes on the query row -- the rows themselves are shaped upstream,
+// and the tail of the launch (labels, aligner, metadata) is the same code the
+// NCBI tests above already cover.
+describe('the PANTHER source', () => {
+  const YEAST = 559292
+  const found = {
+    matched: 'CDC28',
+    query: {
+      code: 'YEAST',
+      accession: 'P00546',
+      geneRef: 'SGD=S000000364',
+      sequence: 'MSGELANYKRLEKVGEGTYGVVYKA',
+    },
+    rows: [
+      {
+        taxId: HUMAN,
+        label: 'human',
+        scientificName: 'Homo sapiens',
+        commonName: 'human',
+        geneId: 'HGNC=1771',
+        protein: 'P24941',
+        sequence: 'MENFQKVEKIGEGTYGVVYKARNK',
+      },
+    ] as OrthologRow[],
+  }
+
+  beforeEach(() => {
+    mockFetchPanther.mockResolvedValue(found)
+    mockFetchTaxonomy.mockResolvedValue(
+      new Map([[YEAST, { sciname: 'Saccharomyces cerevisiae' }]]),
+    )
+  })
+
+  test('source omitted is NCBI, so an old launch never reaches PANTHER', async () => {
+    await doLaunchOrthologs({ self: makeModel(params()) })
+    expect(mockFetchPanther).not.toHaveBeenCalled()
+    expect(mockResolveGeneId).toHaveBeenCalled()
+  })
+
+  test('source panther asks PANTHER with the same species semantics, and skips NCBI', async () => {
+    await doLaunchOrthologs({
+      self: makeModel({
+        taxId: YEAST,
+        source: 'panther',
+        geneCandidates: ['CDC28'],
+        msaAlgorithm: 'clustalo',
+        taxa: [HUMAN, YEAST],
+        maxSpecies: 7,
+      }),
+    })
+    expect(mockResolveGeneId).not.toHaveBeenCalled()
+    expect(mockFetchRows).not.toHaveBeenCalled()
+    const { candidates, taxId, taxa, exclude, limit } =
+      mockFetchPanther.mock.calls[0]![0]
+    expect(candidates).toEqual(['CDC28'])
+    expect(taxId).toBe(YEAST)
+    expect([...taxa!]).toEqual([HUMAN, YEAST])
+    expect(exclude).toBe(YEAST)
+    expect(limit).toBe(7)
+  })
+
+  test("the query row is PANTHER's own entry for the gene when no sequence was supplied, and carries its UniProt accession for the domain overlay", async () => {
+    const result = await doLaunchOrthologs({
+      self: makeModel({
+        taxId: YEAST,
+        source: 'panther',
+        geneCandidates: ['CDC28'],
+        msaAlgorithm: 'clustalo',
+      }),
+    })
+    expect(queryRowName()).toBe('Saccharomyces_cerevisiae_query')
+    expect(queryRowSent()).toBe(found.query.sequence)
+    expect(queryMetadata(result)).toEqual({
+      'Gene ID': 'SGD=S000000364',
+      Accession: 'P00546',
+    })
+    expect(JSON.parse(result.treeMetadata).human).toMatchObject({
+      Accession: 'P24941',
+      'Gene ID': 'HGNC=1771',
+    })
+  })
+
+  test('a supplied sequence still wins, and a different isoform earns no Accession', async () => {
+    const result = await doLaunchOrthologs({
+      self: makeModel({
+        taxId: YEAST,
+        source: 'panther',
+        geneCandidates: ['CDC28'],
+        msaAlgorithm: 'clustalo',
+        proteinSequence: 'MDIFFERENTISOFORM',
+      }),
+    })
+    expect(queryRowSent()).toBe('MDIFFERENTISOFORM')
+    expect(queryMetadata(result).Accession).toBeUndefined()
+  })
+
+  test('names PANTHER when it has no protein for the query row', async () => {
+    mockFetchPanther.mockResolvedValue({ ...found, query: undefined })
+    await expect(
+      doLaunchOrthologs({
+        self: makeModel({
+          taxId: YEAST,
+          source: 'panther',
+          geneCandidates: ['CDC28'],
+          msaAlgorithm: 'clustalo',
+        }),
+      }),
+    ).rejects.toThrow(/PANTHER returned no representative protein/)
+  })
+})

package/src/MsaViewPanel/doLaunchOrthologs.ts

@@ -6,21 +6,37 @@ import {
   fetchProteinForGene,
   resolveGeneId,
 } from '../utils/ncbiOrthologs'
+import { fetchPantherOrthologs } from '../utils/pantherOrthologs'
 import { fetchTaxonomyInfo } from '../utils/taxonomyNames'
 
-import type { JBrowsePluginMsaViewModel } from './model'
 import type { OrthologRow } from '../utils/ncbiOrthologs'
+import type { JBrowsePluginMsaViewModel } from './model'
+
+interface Representative {
+  accession: string
+  sequence: string
+}
+
+/** What either source hands the shared tail of the launch. */
+interface FoundOrthologs {
+  /** the query gene's id at the source: an NCBI GeneID, or PANTHER's gene xref */
+  geneId: string
+  representative: Representative | undefined
+  rows: OrthologRow[]
+}
 
 /**
  * The no-search-job alternative to doLaunchBlast.
  *
  * BLAST spends 10+ minutes answering "what looks like this sequence" and
- * returns a redundant, accession-labelled hit list. This asks NCBI the question
- * the alignment actually wants — "what is this gene's ortholog in each species"
- * — which NCBI has already computed, so the whole NCBI half returns in about a
- * second and only the EBI alignment (~10s) costs real time.
+ * returns a redundant, accession-labelled hit list. This asks the question the
+ * alignment actually wants — "what is this gene's ortholog in each species" —
+ * which NCBI and PANTHER have already computed, so the lookup returns in
+ * seconds and only the EBI alignment (~10s) costs real time. `source` picks
+ * which of the two answers: NCBI for vertebrates and insects, PANTHER for
+ * everything else (yeast, worm, plants, and a fly gene's vertebrate relatives).
  *
- * The query row is the user's OWN selected transcript, not NCBI's
+ * The query row is the user's OWN selected transcript, not the source's
  * representative protein for the query species, because `connectedFeature`
  * maps genome coordinates through that row — swapping in a different isoform
  * would silently break the genome<->MSA linkage. The query species is therefore
@@ -38,49 +54,43 @@ export async function doLaunchOrthologs({
     geneCandidates,
     msaAlgorithm,
     proteinSequence,
+    source = 'ncbi',
   } = self.orthologParams!
 
   const onProgress = (arg: string) => {
     self.setProgress(arg)
   }
 
-  onProgress('Resolving gene at NCBI...')
-  const resolved = await resolveGeneId(geneCandidates, taxId)
-  if (!resolved) {
-    throw new Error(
-      `Could not resolve any of ${geneCandidates.join(', ')} to an NCBI gene in taxon ${taxId}. Try the NCBI BLAST tab, which needs no gene identifier.`,
-    )
+  const request = {
+    taxId,
+    geneCandidates,
+    taxa: taxa ? new Set(taxa) : undefined,
+    // the query species is represented by the query row below
+    exclude: taxId,
+    limit: maxSpecies,
+    onProgress,
   }
+  const { geneId, representative, rows } =
+    source === 'panther'
+      ? await findPantherOrthologs(request)
+      : await findNcbiOrthologs(request)
 
   // The query row. The dialog always supplies it — it is the user's OWN
   // selected transcript, which is what makes `connectedFeature` map genome
   // coordinates through this row. A launch that has no transcript to translate
-  // (a session spec naming only a gene) falls back to NCBI's representative
-  // protein for the resolved gene, which is the same choice made for every
-  // other row, so the alignment is the one NCBI would build for that gene.
-  const representative = await fetchRepresentativeQueryProtein(resolved.geneId)
+  // (a session spec naming only a gene) falls back to the source's
+  // representative protein for the resolved gene, which is the same choice
+  // made for every other row, so the alignment is the one the source would
+  // build for that gene.
   const cleanedSeq = proteinSequence
     ? cleanProteinSequence(proteinSequence)
     : representative?.sequence
   if (!cleanedSeq) {
     throw new Error(
-      `No query protein: none was supplied and NCBI returned no representative protein for gene ${resolved.geneId}.`,
+      `No query protein: none was supplied and ${source === 'panther' ? 'PANTHER' : 'NCBI'} returned no representative protein for gene ${geneId}.`,
     )
   }
 
-  // Every species NCBI has an ortholog for, when a launch names none, capped at
-  // maxSpecies. A launch that wants specific species lists them; one that just
-  // wants "this gene across species" gets NCBI's own order, which leads with the
-  // reference organisms.
-  const rows = await fetchOrthologRows({
-    geneId: resolved.geneId,
-    taxa: taxa ? new Set(taxa) : undefined,
-    // the query species is represented by the query row above
-    exclude: taxId,
-    limit: maxSpecies,
-    onProgress,
-  })
-
   // The query row is named for its species like every other row, with a suffix
   // marking it as the one the genome view is linked to. A bare `QUERY` among
   // ninety-nine named species reads as a row whose species failed to resolve,
@@ -96,12 +106,7 @@ export async function doLaunchOrthologs({
   self.setQuerySeqName(queryLabel)
 
   const treeMetadata: Record<string, Record<string, string>> = {
-    [queryLabel]: buildQueryMetadata(
-      self,
-      resolved.geneId,
-      cleanedSeq,
-      representative,
-    ),
+    [queryLabel]: buildQueryMetadata(self, geneId, cleanedSeq, representative),
   }
   for (const row of rows) {
     treeMetadata[row.label] = buildRowMetadata(row)
@@ -122,6 +127,63 @@ export async function doLaunchOrthologs({
   }
 }
 
+interface OrthologRequest {
+  taxId: number
+  geneCandidates: string[]
+  taxa: Set<number> | undefined
+  exclude: number
+  limit: number | undefined
+  onProgress: (arg: string) => void
+}
+
+/**
+ * Every species NCBI has an ortholog for, when a launch names none, capped at
+ * `limit`. A launch that wants specific species lists them; one that just
+ * wants "this gene across species" gets NCBI's own order, which leads with the
+ * reference organisms.
+ */
+async function findNcbiOrthologs({
+  taxId,
+  geneCandidates,
+  onProgress,
+  ...rest
+}: OrthologRequest): Promise<FoundOrthologs> {
+  onProgress('Resolving gene at NCBI...')
+  const resolved = await resolveGeneId(geneCandidates, taxId)
+  if (!resolved) {
+    throw new Error(
+      `Could not resolve any of ${geneCandidates.join(', ')} to an NCBI gene in taxon ${taxId}. Try the NCBI BLAST tab, which needs no gene identifier.`,
+    )
+  }
+  const representative = await fetchRepresentativeQueryProtein(resolved.geneId)
+  const rows = await fetchOrthologRows({
+    geneId: resolved.geneId,
+    onProgress,
+    ...rest,
+  })
+  return { geneId: resolved.geneId, representative, rows }
+}
+
+/**
+ * One `matchortho` call resolves the gene, names its own UniProt entry and
+ * lists an ortholog per genome, so the representative protein needs no second
+ * lookup here.
+ */
+async function findPantherOrthologs({
+  geneCandidates,
+  ...rest
+}: OrthologRequest): Promise<FoundOrthologs> {
+  const found = await fetchPantherOrthologs({
+    candidates: geneCandidates,
+    ...rest,
+  })
+  return {
+    geneId: found.query?.geneRef ?? found.matched,
+    representative: found.query,
+    rows: found.rows,
+  }
+}
+
 /**
  * `<species>_query`, unique against the ortholog labels. Falls back to the bare
  * marker when NCBI cannot name the taxon, which is a naming failure and must not
@@ -158,7 +220,7 @@ async function fetchRepresentativeQueryProtein(geneId: string) {
 /**
  * The query row carries an Accession — which is what drives the automatic CDD
  * overlay (afterCreateAutoruns.autoLoadProteinDomains -> loadProteinDomains) —
- * ONLY when its sequence is byte-identical to the RefSeq protein that accession
+ * ONLY when its sequence is byte-identical to the protein that accession
  * names. Attaching it unconditionally would put every domain box at an offset
  * whenever the user picked a non-representative isoform, which is a silently
  * wrong figure rather than a missing one. A launch that took the representative
@@ -168,7 +230,7 @@ function buildQueryMetadata(
   self: JBrowsePluginMsaViewModel,
   geneId: string,
   proteinSequence: string,
-  representative: { accession: string; sequence: string } | undefined,
+  representative: Representative | undefined,
 ): Record<string, string> {
   const transcript = self.orthologParams?.selectedTranscript
   const metadata: Record<string, string> = { 'Gene ID': geneId }