jbrowse-plugin-msaview 2.7.3 → 2.7.4

package/src/MsaViewPanel/doLaunchOrthologs.ts

@@ -0,0 +1,123 @@
+import { cleanProteinSequence } from '../LaunchMsaView/util'
+import { launchMSA } from '../utils/msa'
+import {
+  fetchOrthologRows,
+  fetchProteinForGene,
+  resolveGeneId,
+} from '../utils/ncbiOrthologs'
+
+import type { JBrowsePluginMsaViewModel } from './model'
+import type { OrthologRow } from '../utils/ncbiOrthologs'
+
+/**
+ * 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.
+ *
+ * The query row is the user's OWN selected transcript, not NCBI'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
+ * excluded from the ortholog set rather than appearing twice.
+ */
+export async function doLaunchOrthologs({
+  self,
+}: {
+  self: JBrowsePluginMsaViewModel
+}) {
+  const { taxId, taxa, geneCandidates, msaAlgorithm, proteinSequence } =
+    self.orthologParams!
+  const cleanedSeq = cleanProteinSequence(proteinSequence)
+
+  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.`,
+    )
+  }
+
+  // the query species is represented by the user's own transcript below
+  const wanted = new Set(taxa.filter(t => t !== taxId))
+  const rows = await fetchOrthologRows({
+    geneId: resolved.geneId,
+    taxa: wanted,
+    onProgress,
+  })
+
+  const treeMetadata: Record<string, Record<string, string>> = {
+    QUERY: await buildQueryMetadata(self, resolved.geneId, cleanedSeq),
+  }
+  for (const row of rows) {
+    treeMetadata[row.label] = buildRowMetadata(row)
+  }
+
+  const result = await launchMSA({
+    algorithm: msaAlgorithm,
+    sequence: [
+      `>QUERY\n${cleanedSeq}`,
+      ...rows.map(r => `>${r.label}\n${r.sequence}`),
+    ].join('\n'),
+    onProgress,
+  })
+
+  return {
+    ...result,
+    treeMetadata: JSON.stringify(treeMetadata),
+  }
+}
+
+/**
+ * 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
+ * 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.
+ */
+async function buildQueryMetadata(
+  self: JBrowsePluginMsaViewModel,
+  geneId: string,
+  proteinSequence: string,
+): Promise<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)
+  }
+  return metadata
+}
+
+function buildRowMetadata(row: OrthologRow): Record<string, string> {
+  const metadata: Record<string, string> = {
+    'Scientific name': row.scientificName,
+    // Accession drives the automatic CDD domain overlay
+    // (afterCreateAutoruns.autoLoadProteinDomains -> loadProteinDomains)
+    Accession: row.protein,
+    'Gene ID': row.geneId,
+  }
+  if (row.commonName) {
+    metadata['Common name'] = row.commonName
+  }
+  return metadata
+}

package/src/MsaViewPanel/model.ts

@@ -12,6 +12,7 @@ export type { MSAFormat } from 'msa-parsers'
 import {
   autoLoadProteinDomains,
   launchBlastIfNeeded,
+  launchOrthologsIfNeeded,
   loadStoredData,
   observeProteinHighlights,
   processInit,
@@ -54,6 +55,18 @@ export interface BlastParams {
   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[]
+  /** candidate gene identifiers off the feature, tried in order */
+  geneCandidates: string[]
+  msaAlgorithm: MsaAlgorithm
+  selectedTranscript?: Feature
+  proteinSequence: string
+}
+
 /**
  * #stateModel MsaViewPlugin
  * extends
@@ -77,6 +90,10 @@ export default function stateModelFactory() {
          * #property
          */
         blastParams: types.frozen<BlastParams | undefined>(),
+        /**
+         * #property
+         */
+        orthologParams: types.frozen<OrthologParams | undefined>(),
         /**
          * #property
          */
@@ -256,6 +273,12 @@ export default function stateModelFactory() {
       setBlastParams(args?: BlastParams) {
         self.blastParams = args
       },
+      /**
+       * #action
+       */
+      setOrthologParams(args?: OrthologParams) {
+        self.orthologParams = args
+      },
       /**
        * #action
        */
@@ -366,6 +389,7 @@ export default function stateModelFactory() {
           loadStoredData,
           storeDataToIndexedDB,
           launchBlastIfNeeded,
+          launchOrthologsIfNeeded,
           processInit,
           autoLoadProteinDomains,
         ]) {

package/src/utils/ncbiOrthologs.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, test } from 'vitest'
+
+import { dedupeLabels, parseFasta } from './ncbiOrthologs'
+
+describe('dedupeLabels', () => {
+  test('sanitizes to single tokens', () => {
+    // labels are used identically as FASTA headers, Newick leaf names and GFF
+    // seq_ids, so anything that would need quoting in one of those is stripped
+    expect(dedupeLabels(['house mouse', 'Norway rat'])).toEqual([
+      'house_mouse',
+      'Norway_rat',
+    ])
+    expect(dedupeLabels(['Frog (X. tropicalis)'])).toEqual([
+      'Frog_X_tropicalis',
+    ])
+  })
+
+  test('suffixes collisions rather than overwriting a row', () => {
+    expect(dedupeLabels(['a b', 'a-b', 'a_b'])).toEqual([
+      'a_b',
+      'a_b_2',
+      'a_b_3',
+    ])
+  })
+
+  test('falls back for a name with no usable characters', () => {
+    expect(dedupeLabels(['...', '...'])).toEqual(['row', 'row_2'])
+  })
+})
+
+describe('parseFasta', () => {
+  test('keys by the first header token and joins wrapped lines', () => {
+    const map = parseFasta(
+      ['>NP_000537.3 cellular tumor antigen p53', 'MEEP', 'QSDP', ''].join(
+        '\n',
+      ),
+    )
+    expect(map.get('NP_000537.3')).toBe('MEEPQSDP')
+  })
+
+  test('reads every record of a multi-FASTA', () => {
+    const map = parseFasta(
+      ['>A one', 'MMM', '>B two', 'KKK', '>C three', 'LLL'].join('\n'),
+    )
+    expect([...map.keys()]).toEqual(['A', 'B', 'C'])
+    expect(map.get('C')).toBe('LLL')
+  })
+
+  test('returns nothing for a response that carried no records', () => {
+    // efetch answers an unknown accession with an error body, not a 4xx, so a
+    // caller that assumed "text back = sequences" would build empty rows
+    expect(parseFasta('Error: CEFetchPApplication::proxy_stream()').size).toBe(
+      0,
+    )
+  })
+})

package/src/utils/ncbiOrthologs.ts

@@ -0,0 +1,320 @@
+// Homolog discovery WITHOUT a search job.
+//
+// The BLAST path answers "what looks like this sequence", which is not the
+// question an MSA row set wants — it wants "what is homologous to this gene,
+// one per species, labelled by species". BLAST then costs 10+ minutes to
+// return a redundant, accession-labelled hit list that has to be deduplicated
+// before it reads. NCBI has already computed the answer: the Datasets
+// orthologs endpoint returns one ortholog gene per species, instantly.
+//
+// gene symbol -> gene id -> orthologs -> a representative protein each ->
+// sequences, all from NCBI, in a handful of requests. The caller aligns them
+// (EBI Clustal Omega, ~10s) and overlays CDD domains, which are already baked
+// into the GenPept records (see ncbiDomains.ts).
+//
+// Mirrors jb2hubs' website/src/components/proteinMsa.ts assembler, trimmed to
+// what the launch dialog needs and using this plugin's fetch/eutils helpers.
+
+import { NCBI_EMAIL, NCBI_TOOL } from './eutils'
+import { jsonfetch, textfetch } from './fetch'
+
+// v2, not v2alpha: the alpha path still answers /orthologs but 404s
+// /product_report, so an assembler pointed at it silently resolves zero
+// representative proteins and reports "no orthologs" for every gene.
+const DATASETS = 'https://api.ncbi.nlm.nih.gov/datasets/v2'
+const EUTILS = 'https://eutils.ncbi.nlm.nih.gov/entrez/eutils'
+
+// The species panel offered in the launch dialog, ordered from the reference
+// outward so a run that finds only close relatives still reads as a ladder.
+// Orthologs absent for a given gene are skipped rather than erroring.
+export const COMMON_SPECIES = [
+  { label: 'Human', taxId: 9606 },
+  { label: 'Mouse', taxId: 10090 },
+  { label: 'Rat', taxId: 10116 },
+  { label: 'Cow', taxId: 9913 },
+  { label: 'Pig', taxId: 9823 },
+  { label: 'Dog', taxId: 9615 },
+  { label: 'Chicken', taxId: 9031 },
+  { label: 'Frog', taxId: 8364 },
+  { label: 'Zebrafish', taxId: 7955 },
+  { label: 'Fruitfly', taxId: 7227 },
+  { label: 'C. elegans', taxId: 6239 },
+  { label: 'Yeast', taxId: 4932 },
+  { label: 'Arabidopsis', taxId: 3702 },
+] as const
+
+export const COMMON_TAX_RANK = new Map(
+  COMMON_SPECIES.map((s, i) => [s.taxId as number, i]),
+)
+
+export interface OrthologRow {
+  taxId: number
+  /** single-token id used identically in the FASTA, the tree and the domain GFF */
+  label: string
+  scientificName: string
+  commonName?: string
+  geneId: string
+  /** accession.version */
+  protein: string
+  sequence: string
+}
+
+function ncbiUrl(url: string) {
+  const sep = url.includes('?') ? '&' : '?'
+  return `${url}${sep}tool=${NCBI_TOOL}&email=${encodeURIComponent(NCBI_EMAIL)}`
+}
+
+/**
+ * A free-text gene reference -> NCBI gene id. A bare number is taken as the id
+ * itself; anything else is searched as a gene name within the query taxon.
+ * Several candidate identifiers are tried in order, because a JBrowse feature
+ * carries whatever its GFF/BigBed had — `id()`, `name`, `gene_name` — and only
+ * some of those are real symbols.
+ */
+export async function resolveGeneId(
+  candidates: string[],
+  taxId: number,
+): Promise<{ geneId: string; matched: string } | undefined> {
+  for (const raw of candidates) {
+    const query = raw.trim()
+    if (!query) {
+      continue
+    }
+    if (/^\d+$/.test(query)) {
+      return { geneId: query, matched: query }
+    }
+    // strip a version suffix (NM_000546.6) and any GFF ID prefix (gene:TP53)
+    const cleaned = query.replace(/^\w+:/, '').replace(/\.\d+$/, '')
+    const term = `${cleaned}[Gene Name] AND ${taxId}[taxid]`
+    const json = await jsonfetch<{
+      esearchresult?: { idlist?: string[] }
+    }>(
+      ncbiUrl(
+        `${EUTILS}/esearch.fcgi?db=gene&term=${encodeURIComponent(term)}&retmode=json&retmax=1`,
+      ),
+    )
+    const geneId = json.esearchresult?.idlist?.[0]
+    if (geneId) {
+      return { geneId, matched: cleaned }
+    }
+  }
+  return undefined
+}
+
+interface OrthologReport {
+  reports?: {
+    gene?: {
+      gene_id?: string
+      tax_id?: string | number
+      taxname?: string
+      common_name?: string
+    }
+  }[]
+}
+
+/** One ortholog gene per species, restricted to the requested taxa. */
+export async function fetchOrthologGenes(geneId: string, taxa: Set<number>) {
+  const json = await jsonfetch<OrthologReport>(
+    ncbiUrl(
+      `${DATASETS}/gene/id/${geneId}/orthologs?returned_content=COMPLETE`,
+    ),
+  )
+  const byTaxon = new Map<
+    number,
+    {
+      taxId: number
+      geneId: string
+      scientificName: string
+      commonName?: string
+    }
+  >()
+  for (const { gene } of json.reports ?? []) {
+    const taxId = Number(gene?.tax_id)
+    if (gene?.gene_id && taxa.has(taxId) && !byTaxon.has(taxId)) {
+      byTaxon.set(taxId, {
+        taxId,
+        geneId: gene.gene_id,
+        scientificName: gene.taxname ?? String(taxId),
+        commonName: gene.common_name,
+      })
+    }
+  }
+  return [...byTaxon.values()].sort(
+    (a, b) =>
+      (COMMON_TAX_RANK.get(a.taxId) ?? Infinity) -
+      (COMMON_TAX_RANK.get(b.taxId) ?? Infinity),
+  )
+}
+
+interface ProductReport {
+  reports?: {
+    product?: {
+      gene_id?: string
+      transcripts?: {
+        select_category?: string
+        protein?: { accession_version?: string; length?: number }
+      }[]
+    }
+  }[]
+}
+
+/**
+ * geneId -> representative protein accession: MANE Select where flagged, else
+ * the longest isoform. A stable, comparable choice across species — picking
+ * "the first" would silently vary with NCBI's ordering.
+ */
+export async function fetchRepresentativeProteins(geneIds: string[]) {
+  const byGene = new Map<string, string>()
+  if (geneIds.length > 0) {
+    const json = await jsonfetch<ProductReport>(
+      ncbiUrl(`${DATASETS}/gene/id/${geneIds.join(',')}/product_report`),
+    )
+    for (const { product } of json.reports ?? []) {
+      const candidates = (product?.transcripts ?? [])
+        .map(t => ({
+          acc: t.protein?.accession_version,
+          len: t.protein?.length ?? 0,
+          mane: /select/i.test(t.select_category ?? ''),
+        }))
+        .filter(
+          (c): c is { acc: string; len: number; mane: boolean } => !!c.acc,
+        )
+      const best =
+        candidates.find(c => c.mane) ??
+        [...candidates].sort((a, b) => b.len - a.len).at(0)
+      if (product?.gene_id && best) {
+        byGene.set(product.gene_id, best.acc)
+      }
+    }
+  }
+  return byGene
+}
+
+/** accession (first header token) -> ungapped sequence, from a multi-FASTA. */
+export function parseFasta(text: string) {
+  const map = new Map<string, string>()
+  let acc: string | undefined
+  let buf: string[] = []
+  for (const line of text.split('\n')) {
+    if (line.startsWith('>')) {
+      if (acc) {
+        map.set(acc, buf.join(''))
+      }
+      acc = line.slice(1).split(/\s+/)[0]
+      buf = []
+    } else {
+      buf.push(line.trim())
+    }
+  }
+  if (acc) {
+    map.set(acc, buf.join(''))
+  }
+  return map
+}
+
+function sanitize(name: string) {
+  return name.replace(/[^A-Za-z0-9]+/g, '_').replace(/^_+|_+$/g, '')
+}
+
+/**
+ * Sanitized, unique single-token labels used identically in the FASTA headers,
+ * the tree leaf names and the domain GFF seq_ids — that identity is how the
+ * viewer pairs a tree leaf to its alignment row to its domain track. Collisions
+ * get a numeric suffix rather than silently overwriting a row.
+ */
+export function dedupeLabels(names: string[]) {
+  const seen = new Map<string, number>()
+  return names.map(name => {
+    const base = sanitize(name) || 'row'
+    const n = seen.get(base) ?? 0
+    seen.set(base, n + 1)
+    return n === 0 ? base : `${base}_${n + 1}`
+  })
+}
+
+/**
+ * The representative protein for a single gene, with its sequence. Used to
+ * decide whether the user's own translated transcript is byte-identical to the
+ * RefSeq protein — if it is, that accession's precomputed CDD domains apply to
+ * the query row exactly, and if it isn't, they would land at an offset.
+ */
+export async function fetchProteinForGene(geneId: string) {
+  const acc = (await fetchRepresentativeProteins([geneId])).get(geneId)
+  if (!acc) {
+    return undefined
+  }
+  const seq = parseFasta(
+    await textfetch(
+      ncbiUrl(
+        `${EUTILS}/efetch.fcgi?db=protein&id=${acc}&rettype=fasta&retmode=text`,
+      ),
+    ),
+  ).get(acc)
+  return seq ? { accession: acc, sequence: seq } : undefined
+}
+
+/**
+ * The whole NCBI half of the pipeline: gene -> ortholog rows carrying labels,
+ * accessions and sequences. Everything here is a precomputed lookup, so this
+ * returns in seconds rather than the 10+ minutes a BLAST submission costs.
+ */
+export async function fetchOrthologRows({
+  geneId,
+  taxa,
+  onProgress,
+}: {
+  geneId: string
+  taxa: Set<number>
+  onProgress: (arg: string) => void
+}): Promise<OrthologRow[]> {
+  onProgress('Finding orthologs across species...')
+  const genes = await fetchOrthologGenes(geneId, taxa)
+  if (genes.length < 2) {
+    throw new Error(
+      `Only ${genes.length} ortholog(s) found among the selected species — not enough to align`,
+    )
+  }
+
+  onProgress('Selecting a representative protein per species...')
+  const proteinByGene = await fetchRepresentativeProteins(
+    genes.map(g => g.geneId),
+  )
+  const withProtein = genes.filter(g => proteinByGene.has(g.geneId))
+  if (withProtein.length < 2) {
+    throw new Error(
+      'Could not resolve representative proteins for the orthologs',
+    )
+  }
+
+  onProgress(`Fetching ${withProtein.length} protein sequences...`)
+  const accessions = withProtein.map(g => proteinByGene.get(g.geneId)!)
+  const seqByAcc = parseFasta(
+    await textfetch(
+      ncbiUrl(
+        `${EUTILS}/efetch.fcgi?db=protein&id=${accessions.join(',')}&rettype=fasta&retmode=text`,
+      ),
+    ),
+  )
+
+  const labels = dedupeLabels(
+    withProtein.map(g => g.commonName ?? g.scientificName),
+  )
+  const rows = withProtein
+    .map((g, i) => {
+      const protein = proteinByGene.get(g.geneId)!
+      return {
+        taxId: g.taxId,
+        label: labels[i]!,
+        scientificName: g.scientificName,
+        commonName: g.commonName,
+        geneId: g.geneId,
+        protein,
+        sequence: seqByAcc.get(protein) ?? '',
+      }
+    })
+    .filter(r => r.sequence)
+  if (rows.length < 2) {
+    throw new Error('Could not fetch protein sequences for the orthologs')
+  }
+  return rows
+}

package/src/version.ts

@@ -1 +1 @@
-export const version = '2.7.3'
+export const version = '2.7.4'