jbrowse-plugin-msaview 2.8.1 → 2.9.0

package/src/MsaViewPanel/doLaunchOrthologs.ts

@@ -1,6 +1,7 @@
 import { cleanProteinSequence } from '../LaunchMsaView/util'
 import { launchMSA } from '../utils/msa'
 import {
+  COMMON_SPECIES,
   fetchOrthologRows,
   fetchProteinForGene,
   resolveGeneId,
@@ -31,7 +32,6 @@ export async function doLaunchOrthologs({
 }) {
   const { taxId, taxa, geneCandidates, msaAlgorithm, proteinSequence } =
     self.orthologParams!
-  const cleanedSeq = cleanProteinSequence(proteinSequence)
 
   const onProgress = (arg: string) => {
     self.setProgress(arg)
@@ -45,8 +45,29 @@ export async function doLaunchOrthologs({
     )
   }
 
-  // the query species is represented by the user's own transcript below
-  const wanted = new Set(taxa.filter(t => t !== taxId))
+  // 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)
+  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}.`,
+    )
+  }
+
+  // Every species the panel offers, when a launch names none. A spec that wants
+  // a narrower comparison says so; one that just wants "this gene across
+  // species" should not have to enumerate the list the dialog would have
+  // checked for it.
+  const wantedTaxa = taxa ?? COMMON_SPECIES.map(s => s.taxId as number)
+  // the query species is represented by the query row above
+  const wanted = new Set(wantedTaxa.filter(t => t !== taxId))
   const rows = await fetchOrthologRows({
     geneId: resolved.geneId,
     taxa: wanted,
@@ -54,7 +75,7 @@ export async function doLaunchOrthologs({
   })
 
   const treeMetadata: Record<string, Record<string, string>> = {
-    QUERY: await buildQueryMetadata(self, resolved.geneId, cleanedSeq),
+    QUERY: buildQueryMetadata(self, resolved.geneId, cleanedSeq, representative),
   }
   for (const row of rows) {
     treeMetadata[row.label] = buildRowMetadata(row)
@@ -76,34 +97,42 @@ export async function doLaunchOrthologs({
 }
 
 /**
- * The query row is the user's own translated transcript, so it 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
+ * A failed lookup only costs the query row its domain overlay and, for a launch
+ * that supplied no sequence of its own, the alignment — so it is reported by
+ * returning nothing rather than by throwing here.
+ */
+async function fetchRepresentativeQueryProtein(geneId: string) {
+  try {
+    return await fetchProteinForGene(geneId)
+  } catch (e) {
+    console.warn('[msaview-orthologs] query protein lookup failed:', e)
+    return undefined
+  }
+}
+
+/**
+ * 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
  * 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.
+ * wrong figure rather than a missing one. A launch that took the representative
+ * protein as its query row passes that test by construction.
  */
-async function buildQueryMetadata(
+function buildQueryMetadata(
   self: JBrowsePluginMsaViewModel,
   geneId: string,
   proteinSequence: string,
-): Promise<Record<string, string>> {
+  representative: { accession: string; sequence: string } | undefined,
+): Record<string, string> {
   const transcript = self.orthologParams?.selectedTranscript
   const metadata: Record<string, string> = { 'Gene ID': geneId }
   const name = transcript?.get('name') ?? transcript?.get('id')
   if (name) {
     metadata.Transcript = name
   }
-  try {
-    const representative = await fetchProteinForGene(geneId)
-    if (representative?.sequence === proteinSequence) {
-      metadata.Accession = representative.accession
-    }
-  } catch (e) {
-    // a failed lookup only costs the query row its domain overlay, so it must
-    // not take down an alignment that is otherwise complete
-    console.warn('[msaview-orthologs] query protein lookup failed:', e)
+  if (representative?.sequence === proteinSequence) {
+    metadata.Accession = representative.accession
   }
   return metadata
 }

package/src/MsaViewPanel/model.ts

@@ -28,9 +28,8 @@ import {
 import type { MafRegion, MsaViewInitState } from './types'
 import type {
   BlastDatabase,
-  BlastProgram,
   MsaAlgorithm,
-} from '../LaunchMsaView/components/NCBIBlastQuery/consts'
+} from '../LaunchMsaView/components/BlastQuery/consts'
 import type { Feature } from '@jbrowse/core/util'
 import type { Instance } from '@jbrowse/mobx-state-tree'
 import type { LinearGenomeViewModel } from '@jbrowse/plugin-linear-genome-view'
@@ -46,25 +45,33 @@ export interface IRegion {
 }
 
 export interface BlastParams {
-  baseUrl: string
   blastDatabase: BlastDatabase
   msaAlgorithm: MsaAlgorithm
-  blastProgram: BlastProgram
   selectedTranscript?: Feature
   proteinSequence: string
-  rid?: string
 }
 
 export interface OrthologParams {
   /** NCBI taxon id of the assembly the query gene came from */
   taxId: number
-  /** taxon ids to include as rows (the query taxon is represented by QUERY) */
-  taxa: number[]
+  /**
+   * taxon ids to include as rows (the query taxon is represented by QUERY).
+   * Omitted means every species the launch dialog offers, which is what a
+   * launch that just wants "this gene across species" wants.
+   */
+  taxa?: number[]
   /** candidate gene identifiers off the feature, tried in order */
   geneCandidates: string[]
   msaAlgorithm: MsaAlgorithm
   selectedTranscript?: Feature
-  proteinSequence: string
+  /**
+   * The QUERY row. The launch dialog always supplies it, translated from the
+   * transcript the user picked, which is what `connectedFeature` maps genome
+   * coordinates through. Omitted — a session spec naming a gene and nothing
+   * else — the query row becomes NCBI's representative protein for the resolved
+   * gene, the same choice every other row makes.
+   */
+  proteinSequence?: string
 }
 
 /**

package/src/utils/blastCache.ts

@@ -2,9 +2,8 @@ import { createDbOpener } from './idb'
 
 import type {
   BlastDatabase,
-  BlastProgram,
   MsaAlgorithm,
-} from '../LaunchMsaView/components/NCBIBlastQuery/consts'
+} from '../LaunchMsaView/components/BlastQuery/consts'
 import type { DBSchema } from 'idb'
 
 const DB_NAME = 'jbrowse-msaview-blast-cache'
@@ -15,7 +14,12 @@ export interface CachedBlastResult {
   id: string
   proteinSequence: string
   blastDatabase: BlastDatabase
-  blastProgram: BlastProgram
+  /**
+   * 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
   msa: string
   tree: string
@@ -51,7 +55,6 @@ const getDB = createDbOpener<BlastCacheDB>(
 function createCacheKey(
   proteinSequence: string,
   blastDatabase: BlastDatabase,
-  blastProgram: BlastProgram,
   msaAlgorithm: MsaAlgorithm,
   transcriptId?: string,
 ) {
@@ -59,13 +62,12 @@ function createCacheKey(
   // 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
-  return `${blastDatabase}:${blastProgram}:${msaAlgorithm}${idPart}:${proteinSequence}`
+  return `${blastDatabase}:${msaAlgorithm}${idPart}:${proteinSequence}`
 }
 
 export async function saveBlastResult({
   proteinSequence,
   blastDatabase,
-  blastProgram,
   msaAlgorithm,
   msa,
   tree,
@@ -78,7 +80,6 @@ export async function saveBlastResult({
 }: {
   proteinSequence: string
   blastDatabase: BlastDatabase
-  blastProgram: BlastProgram
   msaAlgorithm: MsaAlgorithm
   msa: string
   tree: string
@@ -93,7 +94,6 @@ export async function saveBlastResult({
   const id = createCacheKey(
     proteinSequence,
     blastDatabase,
-    blastProgram,
     msaAlgorithm,
     transcriptId,
   )
@@ -101,7 +101,6 @@ export async function saveBlastResult({
     id,
     proteinSequence,
     blastDatabase,
-    blastProgram,
     msaAlgorithm,
     msa,
     tree,

package/src/utils/ebiBlast.ts

@@ -0,0 +1,114 @@
+import { fetchEbiResult, submitEbiJob, waitForEbiJob } from './ebiJobDispatcher'
+
+import type { BlastHit } from './types'
+import type { BlastDatabase } from '../LaunchMsaView/components/BlastQuery/consts'
+
+const TOOL = 'ncbiblast'
+
+/**
+ * The subset of EBI's ncbiblast JSON result this plugin reads. The service
+ * returns a great deal more per hit (urls, bit scores, e-values, the match
+ * string); only what the MSA rows are built from is typed here.
+ */
+interface EbiBlastJson {
+  hits?: {
+    hit_acc?: string
+    hit_id?: string
+    hit_desc?: string
+    /** the UniProt fields are absent on hits from non-UniProt databases */
+    hit_os?: string
+    hit_uni_de?: string
+    hit_uni_os?: string
+    /** NCBI taxon id, delivered as a string */
+    hit_uni_ox?: string
+    hit_hsps?: { hsp_hseq?: string }[]
+  }[]
+}
+
+/**
+ * Map EBI's hit shape onto the normalized one. Exported for testing against a
+ * captured response — the field names are the whole risk here, and nothing else
+ * in CI would notice if EBI renamed one.
+ */
+export function normalizeEbiBlastHits(result: EbiBlastJson): BlastHit[] {
+  return (result.hits ?? []).map(hit => {
+    const taxid = Number.parseInt(hit.hit_uni_ox ?? '', 10)
+    return {
+      description: [
+        {
+          accession: hit.hit_acc ?? 'unknown',
+          id: hit.hit_id ?? hit.hit_acc ?? 'unknown',
+          sciname: hit.hit_uni_os ?? hit.hit_os ?? 'unknown',
+          taxid: Number.isNaN(taxid) ? undefined : taxid,
+          // hit_uni_de is the bare protein name; hit_desc repeats it with the
+          // OS=/OX=/GN= suffix that makeId already covers with real columns
+          title: hit.hit_uni_de ?? hit.hit_desc,
+        },
+      ],
+      hsps: (hit.hit_hsps ?? []).flatMap(hsp =>
+        hsp.hsp_hseq ? [{ hseq: hsp.hsp_hseq }] : [],
+      ),
+    }
+  })
+}
+
+/**
+ * Human-facing link to a job, shown while it runs and on error — so it has to
+ * be EBI's own results UI, not the REST result endpoint, which does not exist
+ * yet at the moment the link is on screen.
+ */
+export function ebiBlastResultUrl(jobId: string) {
+  return `https://www.ebi.ac.uk/jdispatcher/sss/${TOOL}/summary?jobId=${jobId}`
+}
+
+export async function queryEbiBlastFromJobId({
+  jobId,
+  onProgress,
+}: {
+  jobId: string
+  onProgress: (arg: string) => void
+}) {
+  onProgress(`Checking BLAST status for job: ${jobId}...`)
+  await waitForEbiJob({
+    tool: TOOL,
+    jobId,
+    onCountdown: s => {
+      onProgress(`Re-checking BLAST status in... ${s}`)
+    },
+  })
+
+  const hits = normalizeEbiBlastHits(
+    JSON.parse(
+      await fetchEbiResult({ tool: TOOL, jobId, type: 'json' }),
+    ) as EbiBlastJson,
+  )
+  if (hits.length === 0) {
+    throw new Error('No hits found')
+  }
+  return { rid: jobId, hits }
+}
+
+export async function queryEbiBlast({
+  query,
+  blastDatabase,
+  onProgress,
+  onRid,
+}: {
+  query: string
+  blastDatabase: BlastDatabase
+  onProgress: (arg: string) => void
+  onRid: (arg: string) => void
+}) {
+  onProgress('Submitting to EBI BLAST...')
+  const jobId = await submitEbiJob({
+    tool: TOOL,
+    params: {
+      program: 'blastp',
+      stype: 'protein',
+      database: blastDatabase,
+      sequence: query,
+    },
+  })
+  onRid(jobId)
+  return queryEbiBlastFromJobId({ jobId, onProgress })
+}

package/src/utils/ebiJobDispatcher.ts

@@ -0,0 +1,91 @@
+import { textfetch } from './fetch'
+import { pollLoop } from './poll'
+import { readLocalStorage } from './useLocalStorage'
+
+/**
+ * EBI's Job Dispatcher REST services (clustalo, muscle, ncbiblast, ...) all
+ * speak the same run/status/result protocol, so the transport lives here and
+ * each tool only supplies its own parameters and result types.
+ *
+ * Unlike NCBI's Blast.cgi these endpoints send `Access-Control-Allow-Origin: *`,
+ * which is why the BLAST backend moved here — see docs/blast.md.
+ */
+export const EBI_BASE = 'https://www.ebi.ac.uk/Tools/services/rest'
+
+/**
+ * EBI asks for a contact address on every submission so they can reach whoever
+ * is generating the load. A deployment that sends real volume should point this
+ * at its own maintainer via the BLAST settings dialog — otherwise every
+ * msaview job in the world is attributed to one person.
+ */
+export const EBI_EMAIL_STORAGE_KEY = 'msa-ebiContactEmail'
+export const DEFAULT_EBI_EMAIL = 'colin.diesh@gmail.com'
+
+export function getEbiEmail() {
+  const configured = readLocalStorage(
+    EBI_EMAIL_STORAGE_KEY,
+    DEFAULT_EBI_EMAIL,
+  ).trim()
+  return configured || DEFAULT_EBI_EMAIL
+}
+
+/** Statuses that mean the job is over and produced no result. */
+const FAILED_STATUSES = new Set(['ERROR', 'FAILURE', 'NOT_FOUND'])
+
+export async function submitEbiJob({
+  tool,
+  params,
+}: {
+  tool: string
+  params: Record<string, string>
+}) {
+  const jobId = await textfetch(`${EBI_BASE}/${tool}/run`, {
+    method: 'POST',
+    body: new URLSearchParams({ email: getEbiEmail(), ...params }),
+  })
+  return jobId.trim()
+}
+
+export async function waitForEbiJob({
+  tool,
+  jobId,
+  intervalSeconds = 10,
+  onCountdown,
+}: {
+  tool: string
+  jobId: string
+  intervalSeconds?: number
+  onCountdown: (secondsRemaining: number) => void
+}) {
+  await pollLoop({
+    intervalSeconds,
+    onCountdown,
+    check: async () => {
+      // exact match, not includes(): a job whose status is ERROR must not be
+      // able to poll forever waiting for a FINISHED that will never arrive
+      const status = (
+        await textfetch(`${EBI_BASE}/${tool}/status/${jobId}`)
+      ).trim()
+      if (status === 'FINISHED') {
+        return true
+      }
+      if (FAILED_STATUSES.has(status)) {
+        throw new Error(`EBI ${tool} job ${jobId} returned status ${status}`)
+      }
+      // RUNNING, QUEUED, PENDING and anything else EBI adds later
+      return false
+    },
+  })
+}
+
+export async function fetchEbiResult({
+  tool,
+  jobId,
+  type,
+}: {
+  tool: string
+  jobId: string
+  type: string
+}) {
+  return textfetch(`${EBI_BASE}/${tool}/result/${jobId}/${type}`)
+}

package/src/utils/fetch.ts

@@ -1,5 +1,30 @@
+function hostOf(url: string) {
+  try {
+    return new URL(url).host
+  } catch {
+    // a relative url, e.g. a same-origin proxy path
+    return url
+  }
+}
+
 export async function handleFetch(url: string, args?: RequestInit) {
-  const response = await fetch(url, args)
+  let response: Response
+  try {
+    response = await fetch(url, args)
+  } catch (e) {
+    // fetch rejects with a bare "TypeError: Failed to fetch" for every network
+    // level failure, including a cross-origin response the browser refused to
+    // hand over. That is not a hypothetical: NCBI's Blast.cgi stopped sending
+    // Access-Control-Allow-Origin to third-party origins, and the raw TypeError
+    // told users nothing at all about why. See docs/blast.md.
+    if (e instanceof TypeError) {
+      throw new Error(
+        `Could not reach ${hostOf(url)} — the request failed at the network level. This is usually a CORS restriction (the server refused to let this site read the response), an offline connection, or a blocked request.`,
+        { cause: e },
+      )
+    }
+    throw e
+  }
 
   if (!response.ok) {
     throw new Error(

package/src/utils/msa.ts

@@ -1,10 +1,6 @@
-import { textfetch } from './fetch'
-import { pollLoop } from './poll'
+import { fetchEbiResult, submitEbiJob, waitForEbiJob } from './ebiJobDispatcher'
 
-import type { MsaAlgorithm } from '../LaunchMsaView/components/NCBIBlastQuery/consts'
-
-const base = `https://www.ebi.ac.uk/Tools/services/rest`
-const email = 'colin.diesh@gmail.com'
+import type { MsaAlgorithm } from '../LaunchMsaView/components/BlastQuery/consts'
 
 const algorithms: Record<
   MsaAlgorithm,
@@ -15,54 +11,27 @@ const algorithms: Record<
   }
 > = {
   clustalo: {
-    params: { email },
+    params: {},
     msaResult: 'aln-clustal_num',
     treeResult: 'phylotree',
   },
   muscle: {
-    params: { email, format: 'clw', tree: 'tree1' },
+    params: { format: 'clw', tree: 'tree1' },
     msaResult: 'fa',
     treeResult: 'phylotree',
   },
   kalign: {
-    params: { email, stype: 'protein' },
+    params: { stype: 'protein' },
     msaResult: 'fa',
     treeResult: 'phylotree',
   },
   mafft: {
-    params: { email, stype: 'protein' },
+    params: { stype: 'protein' },
     msaResult: 'fa',
     treeResult: 'phylotree',
   },
 }
 
-async function wait({
-  onProgress,
-  jobId,
-  algorithm,
-}: {
-  jobId: string
-  algorithm: MsaAlgorithm
-  onProgress: (arg: string) => void
-}) {
-  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({
   algorithm,
   sequence,
@@ -76,17 +45,27 @@ export async function launchMSA({
 
   onProgress(`Launching ${algorithm} MSA...`)
 
-  const jobId = await textfetch(`${base}/${algorithm}/run`, {
-    method: 'POST',
-    body: new URLSearchParams({ ...config.params, sequence }),
+  const jobId = await submitEbiJob({
+    tool: algorithm,
+    params: { ...config.params, sequence },
+  })
+  await waitForEbiJob({
+    tool: algorithm,
+    jobId,
+    onCountdown: s => {
+      onProgress(`Re-checking MSA status in... ${s}`)
+    },
   })
-  await wait({ jobId, algorithm, onProgress })
   return {
-    msa: await textfetch(
-      `${base}/${algorithm}/result/${jobId}/${config.msaResult}`,
-    ),
-    tree: await textfetch(
-      `${base}/${algorithm}/result/${jobId}/${config.treeResult}`,
-    ),
+    msa: await fetchEbiResult({
+      tool: algorithm,
+      jobId,
+      type: config.msaResult,
+    }),
+    tree: await fetchEbiResult({
+      tool: algorithm,
+      jobId,
+      type: config.treeResult,
+    }),
   }
 }

package/src/utils/types.ts

@@ -6,17 +6,12 @@ export interface BlastHitDescription {
   title?: string
 }
 
-export interface BlastResults {
-  BlastOutput2: {
-    report: {
-      results: {
-        search: {
-          hits: {
-            description: BlastHitDescription[]
-            hsps: { hseq: string }[]
-          }[]
-        }
-      }
-    }
-  }[]
+/**
+ * The shape utils/ebiBlast.ts normalizes EBI's hits into. It keeps the field
+ * names NCBI's JSON2 used, so everything downstream of the search — row naming,
+ * taxonomy lookup, the MSA — was left untouched when the backend moved.
+ */
+export interface BlastHit {
+  description: BlastHitDescription[]
+  hsps: { hseq: string }[]
 }

package/src/utils/useLocalStorage.ts

@@ -5,7 +5,7 @@ import { useState } from 'react'
 // throw "(0, PR.useLocalStorage) is not a function" on hosts built during that
 // window. Same failure mode as `defaultCodonTable`; keeping our own copy takes
 // this plugin out of the whack-a-mole.
-function readLocalStorage<T>(key: string, initialValue: T): T {
+export function readLocalStorage<T>(key: string, initialValue: T): T {
   try {
     const item = globalThis.localStorage.getItem(key)
     return item === null ? initialValue : (JSON.parse(item) as T)

package/src/version.ts

@@ -1 +1 @@
-export const version = '2.8.1'
+export const version = '2.9.0'

package/dist/LaunchMsaView/components/NCBIBlastQuery/NCBIBlastAutomaticPanel.d.ts

@@ -1,10 +0,0 @@
-import React from 'react';
-import type { AbstractTrackModel, Feature } from '@jbrowse/core/util';
-declare const NCBIBlastAutomaticPanel: ({ handleClose, feature, model, children, baseUrl, }: {
-    model: AbstractTrackModel;
-    feature: Feature;
-    baseUrl: string;
-    handleClose: () => void;
-    children: React.ReactNode;
-}) => React.JSX.Element;
-export default NCBIBlastAutomaticPanel;