jbrowse-plugin-msaview 2.7.2 → 2.7.4

package/src/LaunchMsaView/components/OrthologQuery/OrthologPanel.tsx

@@ -0,0 +1,172 @@
+import React, { useMemo, useState } from 'react'
+
+import { Checkbox, FormControlLabel, MenuItem, Typography } from '@mui/material'
+import { observer } from 'mobx-react'
+import { makeStyles } from 'tss-react/mui'
+
+import { orthologLaunchView } from './orthologLaunchView'
+import TextField2 from '../../../components/TextField2'
+import { COMMON_SPECIES } from '../../../utils/ncbiOrthologs'
+import {
+  getGeneDisplayName,
+  getGeneIdentifiers,
+  getLinearGenomeView,
+  getTranscriptDisplayName,
+} from '../../util'
+import LaunchPanelContent from '../LaunchPanelContent'
+import MsaAlgorithmSelect from '../NCBIBlastQuery/MsaAlgorithmSelect'
+import SubmitCancelActions from '../SubmitCancelActions'
+import TranscriptSelector from '../TranscriptSelector'
+import { useTranscriptSelection } from '../useTranscriptSelection'
+
+import type { MsaAlgorithm } from '../NCBIBlastQuery/consts'
+import type { AbstractTrackModel, Feature } from '@jbrowse/core/util'
+
+const useStyles = makeStyles()({
+  selectField: {
+    width: 180,
+  },
+  speciesBox: {
+    display: 'flex',
+    flexWrap: 'wrap',
+    maxWidth: 560,
+    marginTop: 12,
+  },
+  species: {
+    width: 160,
+  },
+  infoText: {
+    marginTop: 20,
+    maxWidth: 620,
+  },
+})
+
+const OrthologPanel = observer(function ({
+  handleClose,
+  feature,
+  model,
+}: {
+  model: AbstractTrackModel
+  feature: Feature
+  handleClose: () => void
+}) {
+  const { classes } = useStyles()
+  const view = getLinearGenomeView(model)
+  const [launchViewError, setLaunchViewError] = useState<unknown>()
+  const [taxId, setTaxId] = useState(9606)
+  const [msaAlgorithm, setMsaAlgorithm] = useState<MsaAlgorithm>('clustalo')
+  const [excluded, setExcluded] = useState<number[]>([])
+
+  const geneCandidates = useMemo(() => getGeneIdentifiers(feature), [feature])
+  const transcriptSelection = useTranscriptSelection({ feature, view })
+  const { selectedTranscript, proteinSequence } = transcriptSelection
+  const e = transcriptSelection.error ?? launchViewError
+
+  const taxa = COMMON_SPECIES.map(s => s.taxId).filter(
+    t => !excluded.includes(t),
+  )
+
+  return (
+    <>
+      <LaunchPanelContent error={e}>
+        <Typography>
+          Builds the alignment from NCBI&apos;s precomputed orthologs — one gene
+          per species — instead of searching. There is no job to wait on: the
+          NCBI lookups take about a second, and only the multiple alignment at
+          EBI costs real time (~10s), against 10+ minutes for BLAST. Rows come
+          out labelled by species rather than by accession, and NCBI&apos;s CDD
+          domains are overlaid automatically.
+        </Typography>
+
+        <div>
+          <TextField2
+            variant="outlined"
+            label="Query species"
+            className={classes.selectField}
+            select
+            value={taxId}
+            onChange={event => {
+              setTaxId(Number(event.target.value))
+            }}
+            helperText="the species this gene is from"
+          >
+            {COMMON_SPECIES.map(s => (
+              <MenuItem value={s.taxId} key={s.taxId}>
+                {s.label}
+              </MenuItem>
+            ))}
+          </TextField2>
+
+          <MsaAlgorithmSelect
+            className={classes.selectField}
+            value={msaAlgorithm}
+            onChange={setMsaAlgorithm}
+          />
+        </div>
+
+        <Typography variant="subtitle2" style={{ marginTop: 12 }}>
+          Species to include (those without an ortholog are skipped)
+        </Typography>
+        <div className={classes.speciesBox}>
+          {COMMON_SPECIES.map(s => (
+            <FormControlLabel
+              className={classes.species}
+              key={s.taxId}
+              control={
+                <Checkbox
+                  checked={!excluded.includes(s.taxId)}
+                  onChange={event => {
+                    setExcluded(
+                      event.target.checked
+                        ? excluded.filter(t => t !== s.taxId)
+                        : [...excluded, s.taxId],
+                    )
+                  }}
+                />
+              }
+              label={s.label}
+            />
+          ))}
+        </div>
+
+        <TranscriptSelector feature={feature} {...transcriptSelection} />
+
+        <Typography className={classes.infoText} variant="body2">
+          The query row is the transcript selected above, not NCBI&apos;s
+          representative protein, so the alignment stays linked to the genome
+          view at codon resolution.
+        </Typography>
+      </LaunchPanelContent>
+      <SubmitCancelActions
+        submitDisabled={!proteinSequence || taxa.length < 2}
+        onSubmit={() => {
+          try {
+            if (selectedTranscript) {
+              setLaunchViewError(undefined)
+              orthologLaunchView({
+                feature: selectedTranscript,
+                view,
+                newViewTitle: `Orthologs - ${getGeneDisplayName(feature)} - ${getTranscriptDisplayName(selectedTranscript)}`,
+                orthologParams: {
+                  taxId,
+                  taxa,
+                  geneCandidates,
+                  msaAlgorithm,
+                  selectedTranscript,
+                  proteinSequence,
+                },
+              })
+              handleClose()
+            }
+          } catch (e) {
+            console.error(e)
+            setLaunchViewError(e)
+          }
+        }}
+        onCancel={handleClose}
+      />
+    </>
+  )
+})
+
+export default OrthologPanel

package/src/LaunchMsaView/components/OrthologQuery/orthologLaunchView.ts

@@ -0,0 +1,28 @@
+import { getSession } from '@jbrowse/core/util'
+
+import type { OrthologParams } from '../../../MsaViewPanel/model'
+import type { Feature } from '@jbrowse/core/util'
+import type { LinearGenomeViewModel } from '@jbrowse/plugin-linear-genome-view'
+
+export function orthologLaunchView({
+  newViewTitle,
+  view,
+  feature,
+  orthologParams,
+}: {
+  newViewTitle: string
+  view: LinearGenomeViewModel
+  feature: Feature
+  orthologParams: OrthologParams
+}) {
+  getSession(view).addView('MsaView', {
+    type: 'MsaView',
+    displayName: newViewTitle,
+    connectedViewId: view.id,
+    connectedFeature: feature.toJSON(),
+    drawNodeBubbles: true,
+    colWidth: 10,
+    rowHeight: 12,
+    orthologParams,
+  })
+}

package/src/MsaViewPanel/afterCreateAutoruns.ts

@@ -1,6 +1,7 @@
 import { getSession } from '@jbrowse/core/util'
 
 import { doLaunchBlast } from './doLaunchBlast'
+import { doLaunchOrthologs } from './doLaunchOrthologs'
 import { fetchIndexedMsa } from './fetchIndexedMsa'
 import { genomeToMSA } from './genomeToMSA'
 import { loadProteinDomains } from './loadProteinDomains'
@@ -78,6 +79,32 @@ export function storeDataToIndexedDB(self: JBrowsePluginMsaViewModel) {
   }
 }
 
+/**
+ * Same shape as launchBlastIfNeeded, for the ortholog path: the params ARE the
+ * request, and clearing them on success is what marks it done. They are left in
+ * place on failure so the error stays attributable to a specific request; the
+ * autorun's only tracked read is orthologParams itself, so nothing refires
+ * until a new request replaces them.
+ */
+export function launchOrthologsIfNeeded(self: JBrowsePluginMsaViewModel) {
+  if (self.orthologParams) {
+    void (async () => {
+      try {
+        self.setProgress('Resolving orthologs')
+        self.setError(undefined)
+        const data = await doLaunchOrthologs({ self })
+        self.setData(data)
+        self.setOrthologParams(undefined)
+      } catch (e) {
+        self.setError(e)
+        console.error(e)
+      } finally {
+        self.setProgress('')
+      }
+    })()
+  }
+}
+
 export function launchBlastIfNeeded(self: JBrowsePluginMsaViewModel) {
   if (self.blastParams) {
     void (async () => {

package/src/MsaViewPanel/doLaunchBlast.ts

@@ -25,36 +25,29 @@ export async function doLaunchBlast({
   } = self.blastParams!
   const cleanedSeq = cleanProteinSequence(proteinSequence)
 
-  let hits
-  let rid: string
+  const onProgress = (arg: string) => {
+    self.setProgress(arg)
+  }
+
   if (existingRid) {
+    // publish it before the first poll so the view can link out to NCBI while
+    // the job is still running
     self.setRid(existingRid)
-    const result = await queryBlastFromRid({
-      rid: existingRid,
-      baseUrl,
-      onProgress: arg => {
-        self.setProgress(arg)
-      },
-    })
-    hits = result.hits
-    rid = result.rid
-  } else {
-    const result = await queryBlast({
-      query: cleanedSeq,
-      blastDatabase,
-      blastProgram,
-      baseUrl,
-      onProgress: arg => {
-        self.setProgress(arg)
-      },
-      onRid: r => {
-        self.setRid(r)
-      },
-    })
-    hits = result.hits
-    rid = result.rid
   }
 
+  const { hits, rid } = existingRid
+    ? await queryBlastFromRid({ rid: existingRid, baseUrl, onProgress })
+    : await queryBlast({
+        query: cleanedSeq,
+        blastDatabase,
+        blastProgram,
+        baseUrl,
+        onProgress,
+        onRid: r => {
+          self.setRid(r)
+        },
+      })
+
   self.setProgress('Fetching species taxonomy info...')
   const taxids = hits
     .map(h => h.description[0]?.taxid)
@@ -80,9 +73,7 @@ export async function doLaunchBlast({
   const result = await launchMSA({
     algorithm: msaAlgorithm,
     sequence: [`>QUERY\n${cleanedSeq}`, ...sequences].join('\n'),
-    onProgress: arg => {
-      self.setProgress(arg)
-    },
+    onProgress,
   })
 
   const treeMetadataJson = JSON.stringify(treeMetadata)

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/genomeToMSA.test.ts

@@ -91,8 +91,9 @@ describe('genomeToMSA', () => {
 
       const result = genomeToMSA({ model })
 
-      // coord 1005 - start 1000 = ungapped position 5
-      expect(mockSeqPosToVisibleCol).toHaveBeenCalledWith('hg38.chr1', 5)
+      // hover coord 1005 is 1-based, so the 0-based genome position is 1004,
+      // which is ungapped position 4 of a region starting at 1000
+      expect(mockSeqPosToVisibleCol).toHaveBeenCalledWith('hg38.chr1', 4)
       expect(result).toBe(5)
     })
 
@@ -125,10 +126,11 @@ describe('genomeToMSA', () => {
     })
 
     test('returns undefined when hover coord is before mafRegion start', () => {
+      // 1-based coord 1000 is the 0-based base 999, one before the region
       mockGetSession.mockReturnValue({
         hovered: {
           hoverFeature: {},
-          hoverPosition: { coord: 999, refName: 'chr1' },
+          hoverPosition: { coord: 1000, refName: 'chr1' },
         },
       } as any)
 
@@ -153,10 +155,11 @@ describe('genomeToMSA', () => {
     })
 
     test('returns undefined when hover coord is at or after mafRegion end', () => {
+      // 1-based coord 1011 is the 0-based base 1010, one past the region
       mockGetSession.mockReturnValue({
         hovered: {
           hoverFeature: {},
-          hoverPosition: { coord: 1010, refName: 'chr1' },
+          hoverPosition: { coord: 1011, refName: 'chr1' },
         },
       } as any)
 
@@ -223,7 +226,9 @@ describe('genomeToMSA', () => {
       const model = {
         querySeqName: 'QUERY',
         transcriptToMsaMap: {
-          g2p: { 1005: 10 },
+          refName: 'chr1',
+          // g2p is keyed by 0-based genome position, the hover coord is 1-based
+          g2p: { 1004: 10 },
         },
         mafRegion: undefined,
         connectedView: { initialized: true },
@@ -236,6 +241,32 @@ describe('genomeToMSA', () => {
       expect(result).toBe(10)
     })
 
+    test('returns undefined when the hover is on another refName', () => {
+      // session.hovered is global, so a hover on an unrelated chromosome can
+      // carry a coordinate that happens to be a g2p key
+      mockGetSession.mockReturnValue({
+        hovered: {
+          hoverFeature: {},
+          hoverPosition: { coord: 1005, refName: 'chr2' },
+        },
+      } as any)
+
+      const mockSeqPosToVisibleCol = vi.fn()
+      const model = {
+        querySeqName: 'QUERY',
+        transcriptToMsaMap: {
+          refName: 'chr1',
+          g2p: { 1004: 10 },
+        },
+        mafRegion: undefined,
+        connectedView: { initialized: true },
+        seqPosToVisibleCol: mockSeqPosToVisibleCol,
+      } as any
+
+      expect(genomeToMSA({ model })).toBeUndefined()
+      expect(mockSeqPosToVisibleCol).not.toHaveBeenCalled()
+    })
+
     test('returns undefined when g2p has no mapping for coord', () => {
       mockGetSession.mockReturnValue({
         hovered: {
@@ -247,7 +278,8 @@ describe('genomeToMSA', () => {
       const model = {
         querySeqName: 'QUERY',
         transcriptToMsaMap: {
-          g2p: { 1000: 0 }, // No entry for 1005
+          refName: 'chr1',
+          g2p: { 1000: 0 }, // No entry for 1004
         },
         mafRegion: undefined,
         connectedView: { initialized: true },

package/src/MsaViewPanel/genomeToMSA.ts

@@ -12,22 +12,30 @@ export function genomeToMSA({ model }: { model: JBrowsePluginMsaViewModel }) {
     return undefined
   }
 
-  const { coord: hoverCoord, refName } = hovered.hoverPosition
+  const { coord, refName } = hovered.hoverPosition
+
+  // hoverPosition.coord is a 1-based display coordinate (core's pxToBp adds the
+  // +1), while g2p and mafRegion are keyed by 0-based genome position
+  const genomePos = coord - 1
 
   if (mafRegion) {
     if (
       refName !== mafRegion.refName ||
       !connectedView.assemblyNames.includes(mafRegion.assemblyName) ||
-      hoverCoord < mafRegion.start ||
-      hoverCoord >= mafRegion.end
+      genomePos < mafRegion.start ||
+      genomePos >= mafRegion.end
     ) {
       return undefined
     }
-    return model.seqPosToVisibleCol(querySeqName, hoverCoord - mafRegion.start)
+    return model.seqPosToVisibleCol(querySeqName, genomePos - mafRegion.start)
   }
 
-  if (transcriptToMsaMap) {
-    const seqPos = transcriptToMsaMap.g2p[hoverCoord]
+  // session.hovered is global -- set by whichever LinearGenomeView the cursor
+  // was last over, on any assembly -- so the refName gate is load bearing:
+  // without it the same numeric coordinate on an unrelated chromosome matches a
+  // g2p key and lights up a column for a different locus
+  if (refName === transcriptToMsaMap?.refName) {
+    const seqPos = transcriptToMsaMap.g2p[genomePos]
     if (seqPos !== undefined) {
       return model.seqPosToVisibleCol(querySeqName, seqPos)
     }

package/src/MsaViewPanel/model.ts

@@ -12,6 +12,7 @@ export type { MSAFormat } from 'msa-parsers'
 import {
   autoLoadProteinDomains,
   launchBlastIfNeeded,
+  launchOrthologsIfNeeded,
   loadStoredData,
   observeProteinHighlights,
   processInit,
@@ -19,7 +20,10 @@ import {
   storeDataToIndexedDB,
   syncGenomeHoverToMsaColumn,
 } from './afterCreateAutoruns'
-import { msaCoordToGenomeCoord } from './msaCoordToGenomeCoord'
+import {
+  msaCoordToGenomeCoord,
+  msaCoordToGenomeRegions,
+} from './msaCoordToGenomeCoord'
 
 import type { MafRegion, MsaViewInitState } from './types'
 import type {
@@ -51,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
@@ -74,6 +90,10 @@ export default function stateModelFactory() {
          * #property
          */
         blastParams: types.frozen<BlastParams | undefined>(),
+        /**
+         * #property
+         */
+        orthologParams: types.frozen<OrthologParams | undefined>(),
         /**
          * #property
          */
@@ -188,35 +208,37 @@ export default function stateModelFactory() {
     .views(self => ({
       /**
        * #getter
-       * Genome region under the current MSA hover column. Suppressed on the LGV
+       * Genome regions under the current MSA hover column. Suppressed on the LGV
        * while it's being hovered (GenomeMouseoverHighlight shows the crisp 1bp
        * marker there instead of this wider codon band).
        */
-      get connectedHoverHighlight(): IRegion | undefined {
+      get connectedHoverHighlights(): IRegion[] {
         const { mouseCol } = self
         return mouseCol === undefined
-          ? undefined
-          : msaCoordToGenomeCoord({ model: self, coord: mouseCol })
+          ? []
+          : msaCoordToGenomeRegions({ model: self, coord: mouseCol })
       },
       /**
        * #getter
-       * Genome region under the persistent MSA click selection. Shown
+       * Genome regions under the persistent MSA click selection. Shown
        * regardless of LGV hover, so hovering the genome doesn't hide it.
        */
-      get connectedClickHighlight(): IRegion | undefined {
+      get connectedClickHighlights(): IRegion[] {
         const { mouseClickCol } = self
         return mouseClickCol === undefined
-          ? undefined
-          : msaCoordToGenomeCoord({ model: self, coord: mouseClickCol })
+          ? []
+          : msaCoordToGenomeRegions({ model: self, coord: mouseClickCol })
       },
       /**
        * #getter
+       * cross-plugin contract: jbrowse-plugin-mafviewer reads this off the view
+       * to draw the same highlights in its own display
        */
       get connectedHighlights(): IRegion[] {
         return [
-          this.connectedHoverHighlight,
-          this.connectedClickHighlight,
-        ].filter((r): r is IRegion => r !== undefined)
+          ...this.connectedHoverHighlights,
+          ...this.connectedClickHighlights,
+        ]
       },
     }))
 
@@ -251,6 +273,12 @@ export default function stateModelFactory() {
       setBlastParams(args?: BlastParams) {
         self.blastParams = args
       },
+      /**
+       * #action
+       */
+      setOrthologParams(args?: OrthologParams) {
+        self.orthologParams = args
+      },
       /**
        * #action
        */
@@ -361,6 +389,7 @@ export default function stateModelFactory() {
           loadStoredData,
           storeDataToIndexedDB,
           launchBlastIfNeeded,
+          launchOrthologsIfNeeded,
           processInit,
           autoLoadProteinDomains,
         ]) {