jbrowse-plugin-msaview 3.2.0 → 3.3.0

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

package/src/MsaViewPanel/model.ts

@@ -51,9 +51,19 @@ export interface BlastParams {
   proteinSequence: string
 }
 
+/**
+ * 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/utils/pantherOrthologs.ts

@@ -0,0 +1,399 @@
+// The second ortholog source, for the genes NCBI's ortholog sets leave out.
+//
+// NCBI Datasets computes orthologs for vertebrates and insects, so a yeast,
+// worm or plant gene comes back with orthologs only in its own clade, and a fly
+// gene gets insects and nothing else. PANTHER's ortholog sets span its 144
+// reference proteomes, human to yeast to Arabidopsis, and one `matchortho` call
+// answers "this gene's ortholog in every genome" with a UniProt accession per
+// target. Sequences come from one UniProt batch call. Both hosts send
+// `Access-Control-Allow-Origin: *`. The measurements that picked PANTHER over
+// OMA, OrthoDB and Ensembl are in react-msaview's
+// agent-docs/ideas/ortholog-sources-beyond-ncbi.md.
+//
+// Rows come out in the same shape as ncbiOrthologs.ts's, so the launch, the
+// labels, the aligner and the CDD overlay do not know which source ran.
+// `protein` is the UniProt accession; efetch serves UniProt accessions as
+// GenPept records with CDD Region features, so the overlay attaches as it does
+// to a RefSeq accession.
+
+import { jsonfetch } from './fetch'
+import { dedupeLabels, defaultMaxSpecies } from './ncbiOrthologs'
+import { fetchTaxonomyInfo } from './taxonomyNames'
+
+import type { OrthologRow } from './ncbiOrthologs'
+
+const PANTHER = 'https://pantherdb.org/services/oai/pantherdb'
+const UNIPROT = 'https://rest.uniprot.org/uniprotkb'
+
+export interface PantherGenome {
+  /** PANTHER's organism code, e.g. HUMAN, DROME */
+  code: string
+  taxId: number
+  /** short common name, e.g. fruit_fly */
+  name: string
+  /** scientific name */
+  longName: string
+}
+
+interface GenomesResponse {
+  search?: {
+    output?: {
+      genomes?: {
+        genome?: {
+          short_name?: string
+          taxon_id?: number
+          name?: string
+          long_name?: string
+        }[]
+      }
+    }
+  }
+}
+
+/**
+ * `supportedgenomes` -> the code<->taxon map every other parse needs. PANTHER
+ * names organisms by code only in ortholog results.
+ */
+export function parseGenomes(json: unknown): PantherGenome[] {
+  const list = (json as GenomesResponse).search?.output?.genomes?.genome ?? []
+  return list.flatMap(g =>
+    g.short_name && g.taxon_id
+      ? [
+          {
+            code: g.short_name,
+            taxId: g.taxon_id,
+            name: g.name ?? g.short_name,
+            longName: g.long_name ?? g.short_name,
+          },
+        ]
+      : [],
+  )
+}
+
+export interface PantherGene {
+  code: string
+  /** UniProt accession */
+  accession: string
+  /** the source database's own id, e.g. HGNC=1773, FlyBase=FBgn0016131 */
+  geneRef: string
+}
+
+export interface PantherHit extends PantherGene {
+  symbol?: string
+  /**
+   * LDO = least diverged ortholog, PANTHER's pick of the one-to-one; O = any
+   * other ortholog in a one-to-many or many-to-many family
+   */
+  type: 'LDO' | 'O'
+}
+
+interface Mapping {
+  id?: string
+  gene?: string
+  target_gene?: string
+  target_gene_symbol?: string | number
+  ortholog?: string
+}
+
+interface MatchResponse {
+  search?: {
+    mapping?: {
+      /** one object for a single (or empty) match, an array otherwise */
+      mapped?: Mapping | Mapping[]
+      unmapped_ids?: unknown
+    }
+  }
+}
+
+// "HUMAN|HGNC=1773|UniProtKB=P11802" -> { code, geneRef, accession }
+function parseGeneRef(ref: string | undefined): PantherGene | undefined {
+  const [code, ...xrefs] = (ref ?? '').split('|')
+  const accession = xrefs
+    .find(x => x.startsWith('UniProtKB='))
+    ?.slice('UniProtKB='.length)
+  const geneRef = xrefs.find(x => !x.startsWith('UniProtKB=')) ?? accession
+  return code && accession && geneRef ? { code, accession, geneRef } : undefined
+}
+
+/**
+ * `matchortho` -> the query gene (PANTHER names it in every row) and one hit
+ * per target gene. An unknown gene comes back under `unmapped_ids`; a gene with
+ * no ortholog in the target set comes back as a bare `{ id }`.
+ */
+export function parseMatches(json: unknown): {
+  unmapped: boolean
+  query?: PantherGene
+  hits: PantherHit[]
+} {
+  const mapping = (json as MatchResponse).search?.mapping
+  const mapped = mapping?.mapped
+  const rows = Array.isArray(mapped) ? mapped : mapped ? [mapped] : []
+  const hits: PantherHit[] = []
+  let query: PantherGene | undefined
+  for (const row of rows) {
+    query ??= parseGeneRef(row.gene)
+    const target = parseGeneRef(row.target_gene)
+    if (target && (row.ortholog === 'LDO' || row.ortholog === 'O')) {
+      hits.push({
+        ...target,
+        symbol:
+          row.target_gene_symbol === undefined
+            ? undefined
+            : String(row.target_gene_symbol),
+        type: row.ortholog,
+      })
+    }
+  }
+  return { unmapped: !!mapping?.unmapped_ids, query, hits }
+}
+
+/**
+ * One hit per organism, in first-seen order: the LDO where PANTHER named one,
+ * else the first other ortholog it listed. A many-to-many family (the Hox
+ * genes) has no LDO at all, so dropping to "first O" is what keeps those
+ * species in the alignment.
+ */
+export function pickOnePerGenome(hits: PantherHit[]): PantherHit[] {
+  const byCode = new Map<string, PantherHit>()
+  for (const hit of hits) {
+    const current = byCode.get(hit.code)
+    if (!current || (current.type === 'O' && hit.type === 'LDO')) {
+      byCode.set(hit.code, hit)
+    }
+  }
+  return [...byCode.values()]
+}
+
+interface UniProtResponse {
+  results?: {
+    primaryAccession?: string
+    sequence?: { value?: string }
+  }[]
+}
+
+/** `uniprotkb/accessions` -> accession -> sequence */
+export function parseSequences(json: unknown): Map<string, string> {
+  const map = new Map<string, string>()
+  for (const r of (json as UniProtResponse).results ?? []) {
+    if (r.primaryAccession && r.sequence?.value) {
+      map.set(r.primaryAccession, r.sequence.value)
+    }
+  }
+  return map
+}
+
+let genomes: Promise<PantherGenome[]> | undefined
+
+/** The proteome list, fetched once per page and forgotten on failure. */
+export function fetchGenomes() {
+  genomes ??= jsonfetch(`${PANTHER}/supportedgenomes`)
+    .then(parseGenomes)
+    .catch((e: unknown) => {
+      genomes = undefined
+      throw e
+    })
+  return genomes
+}
+
+// UniProt caps one `accessions` call at 100 ids
+const UNIPROT_CHUNK = 100
+
+async function fetchSequences(accessions: string[]) {
+  const map = new Map<string, string>()
+  for (let i = 0; i < accessions.length; i += UNIPROT_CHUNK) {
+    const chunk = accessions.slice(i, i + UNIPROT_CHUNK)
+    const json = await jsonfetch(
+      `${UNIPROT}/accessions?accessions=${chunk.join(',')}&fields=accession,sequence&format=json`,
+    )
+    for (const [acc, seq] of parseSequences(json)) {
+      map.set(acc, seq)
+    }
+  }
+  return map
+}
+
+// strip a version suffix (NM_000546.6) and any GFF ID prefix (gene:TP53), as
+// resolveGeneId does for NCBI
+function cleanCandidate(raw: string) {
+  return raw
+    .trim()
+    .replace(/^\w+:/, '')
+    .replace(/\.\d+$/, '')
+}
+
+/**
+ * One `matchortho` per candidate until PANTHER maps one. A JBrowse feature
+ * carries whatever its GFF/BigBed had — `id()`, `name`, `gene_name` — and only
+ * some of those are names PANTHER knows. `targets` omitted asks for every
+ * genome PANTHER has, which is one call rather than one per genome.
+ */
+async function matchOrthologs(
+  candidates: string[],
+  taxId: number,
+  targets: PantherGenome[] | undefined,
+) {
+  let matched: string | undefined
+  for (const raw of candidates) {
+    const query = cleanCandidate(raw)
+    if (!query) {
+      continue
+    }
+    const params = new URLSearchParams({
+      geneInputList: query,
+      organism: String(taxId),
+      orthologType: 'all',
+    })
+    if (targets) {
+      params.set('targetOrganism', targets.map(t => t.taxId).join(','))
+    }
+    const parsed = parseMatches(
+      await jsonfetch(`${PANTHER}/ortholog/matchortho?${params.toString()}`),
+    )
+    if (!parsed.unmapped) {
+      matched ??= query
+      if (parsed.query) {
+        return { ...parsed, matched: query }
+      }
+    }
+  }
+  return matched === undefined
+    ? undefined
+    : { matched, hits: [], query: undefined }
+}
+
+export interface PantherOrthologs {
+  /** the candidate PANTHER recognised */
+  matched: string
+  /** the query gene as PANTHER knows it, with its UniProt sequence */
+  query?: PantherGene & { sequence: string }
+  rows: OrthologRow[]
+}
+
+/**
+ * The whole PANTHER half of the pipeline: gene -> ortholog rows carrying
+ * labels, accessions and sequences, plus the query gene's own protein for the
+ * query row. Two lookups (genomes, orthologs), one taxonomy batch for the
+ * labels, one UniProt batch for the sequences.
+ *
+ * `taxa`, `exclude` and `limit` mean what they mean for fetchOrthologRows:
+ * `taxa` narrows the targets (omitted, every genome PANTHER has, in its order),
+ * `exclude` drops the query taxon, `limit` caps the rows before their
+ * sequences are fetched.
+ */
+export async function fetchPantherOrthologs({
+  candidates,
+  taxId,
+  taxa,
+  exclude,
+  limit = defaultMaxSpecies,
+  onProgress,
+}: {
+  candidates: string[]
+  taxId: number
+  taxa?: Set<number>
+  exclude?: number
+  limit?: number
+  onProgress: (arg: string) => void
+}): Promise<PantherOrthologs> {
+  const all = await fetchGenomes()
+  const byTaxId = new Map(all.map(g => [g.taxId, g]))
+  const byCode = new Map(all.map(g => [g.code, g]))
+  const queryGenome = byTaxId.get(taxId)
+  if (!queryGenome) {
+    throw new Error(
+      `PANTHER has no reference proteome for taxon ${taxId}. NCBI orthologs cover vertebrates and insects; try that source.`,
+    )
+  }
+  const targets = taxa
+    ? [...taxa].flatMap(t => {
+        const g = byTaxId.get(t)
+        return g && t !== exclude ? [g] : []
+      })
+    : undefined
+
+  onProgress('Matching orthologs at PANTHER...')
+  const match = await matchOrthologs(candidates, taxId, targets)
+  if (!match) {
+    throw new Error(
+      `PANTHER has no entry for ${candidates.join(', ')} in ${queryGenome.longName}. Try the NCBI BLAST tab, which needs no gene identifier.`,
+    )
+  }
+
+  const rank = new Map(targets?.map((t, i) => [t.taxId, i]))
+  const picks = pickOnePerGenome(match.hits)
+    .map(hit => ({ hit, genome: byCode.get(hit.code) }))
+    .filter(
+      (p): p is { hit: PantherHit; genome: PantherGenome } =>
+        !!p.genome &&
+        p.genome.taxId !== exclude &&
+        (targets ? rank.has(p.genome.taxId) : true),
+    )
+    .sort((a, b) =>
+      targets ? rank.get(a.genome.taxId)! - rank.get(b.genome.taxId)! : 0,
+    )
+    .slice(0, limit)
+  if (picks.length < 2) {
+    throw new Error(
+      `Only ${picks.length} PANTHER ortholog(s) found for ${match.matched} — not enough to align`,
+    )
+  }
+
+  onProgress(`Fetching ${picks.length} protein sequences from UniProt...`)
+  const [names, sequences] = await Promise.all([
+    taxonomyNames(picks.map(p => p.genome.taxId)),
+    fetchSequences([
+      ...(match.query ? [match.query.accession] : []),
+      ...picks.map(p => p.hit.accession),
+    ]),
+  ])
+
+  const described = picks.map(({ hit, genome }) => {
+    const info = names.get(genome.taxId)
+    return {
+      hit,
+      genome,
+      name: info ? (info.commonName ?? info.sciname) : genome.name,
+      scientificName: info?.sciname || genome.longName,
+      commonName: info?.commonName,
+    }
+  })
+  const labels = dedupeLabels(described.map(d => d.name))
+  const rows = described
+    .map(({ hit, genome, scientificName, commonName }, i) => ({
+      taxId: genome.taxId,
+      label: labels[i]!,
+      scientificName,
+      commonName,
+      geneId: hit.geneRef,
+      protein: hit.accession,
+      sequence: sequences.get(hit.accession) ?? '',
+    }))
+    .filter(r => r.sequence)
+  if (rows.length < 2) {
+    throw new Error('Could not fetch protein sequences for the orthologs')
+  }
+
+  const querySequence = match.query && sequences.get(match.query.accession)
+  return {
+    matched: match.matched,
+    query:
+      match.query && querySequence
+        ? { ...match.query, sequence: querySequence }
+        : undefined,
+    rows,
+  }
+}
+
+/**
+ * NCBI's names for the taxa, so PANTHER rows are labelled exactly as NCBI rows
+ * are. A failed lookup only costs the labels, which fall back to PANTHER's own
+ * short names, so it is logged rather than thrown.
+ */
+async function taxonomyNames(taxIds: number[]) {
+  try {
+    return await fetchTaxonomyInfo(taxIds)
+  } catch (e) {
+    console.warn('[msaview-orthologs] taxonomy name lookup failed:', e)
+    return new Map<number, { sciname: string; commonName?: string }>()
+  }
+}

package/src/version.ts

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