jbrowse-plugin-msaview 3.0.0 → 3.1.0

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const version = "3.0.0";
+export declare const version = "3.1.0";

package/dist/version.js

@@ -1 +1 @@
-export const version = '3.0.0';
+export const version = '3.1.0';

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.0.0",
+  "version": "3.1.0",
   "license": "MIT",
   "name": "jbrowse-plugin-msaview",
   "repository": {
@@ -68,6 +68,8 @@
     "prebuild": "pnpm clean",
     "lint": "eslint src --report-unused-disable-directives --max-warnings 0",
     "check-text-source": "node scripts/check-text-source.mjs",
+    "check-ebi-params": "node scripts/check-ebi-params.mjs",
+    "check-mui-imports": "node scripts/check-mui-imports.mjs",
     "pretest": "rm -rf .test-jbrowse && npx @jbrowse/cli create .test-jbrowse --nightly",
     "test": "vitest run",
     "test:watch": "vitest",

package/src/LaunchMsaView/components/BlastQuery/BlastManualPanel.tsx

@@ -1,14 +1,23 @@
-import React from 'react'
+import React, { useState } from 'react'
 
 import { shorten2 } from '@jbrowse/core/util'
-import { Button, DialogActions, Typography } from '@mui/material'
+import { Alert, Typography } from '@mui/material'
 import { observer } from 'mobx-react'
 import { makeStyles } from 'tss-react/mui'
 
 import { BASE_BLAST_URL } from './consts'
 import ExternalLink from '../../../components/ExternalLink'
-import { cleanProteinSequence, getLinearGenomeView } from '../../util'
+import TextField2 from '../../../components/TextField2'
+import { useQueryRowName } from '../../useQueryRowName'
+import {
+  cleanProteinSequence,
+  getGeneDisplayName,
+  getLinearGenomeView,
+} from '../../util'
 import LaunchPanelContent from '../LaunchPanelContent'
+import { launchView } from '../ManualMSALoader/launchView'
+import QueryRowSelector from '../QueryRowSelector'
+import SubmitCancelActions from '../SubmitCancelActions'
 import TranscriptSelector from '../TranscriptSelector'
 import { useTranscriptSelection } from '../useTranscriptSelection'
 
@@ -17,14 +26,33 @@ import type { AbstractTrackModel, Feature } from '@jbrowse/core/util'
 const useStyles = makeStyles()({
   ncbiLink: {
     wordBreak: 'break-all',
-    margin: 30,
-    maxWidth: 600,
   },
-  infoText: {
+  textAreaFont: {
+    fontFamily: 'Courier New',
+  },
+  msaInput: {
+    marginBottom: 20,
+  },
+  step: {
     marginTop: 20,
   },
+  stepBody: {
+    marginLeft: 20,
+    marginTop: 8,
+  },
 })
 
+/**
+ * The route to NCBI's `nr`, which no plugin version can query directly: NCBI
+ * stopped sending Access-Control-Allow-Origin to third-party origins, so the
+ * browser cannot read Blast.cgi at all (see docs/blast.md).
+ *
+ * That makes the round trip through NCBI's own site the whole feature rather
+ * than a fallback, so the panel walks it end to end. It used to hand the user a
+ * link, tell them to "paste the results into JBrowse", and offer only a Close
+ * button -- leaving them to find the Manual upload tab, re-pick the transcript
+ * they had already chosen here, and hand-type the row name.
+ */
 const BlastManualPanel = observer(function ({
   handleClose,
   feature,
@@ -38,8 +66,13 @@ const BlastManualPanel = observer(function ({
 }) {
   const { classes } = useStyles()
   const view = getLinearGenomeView(model)
+  const [launchViewError, setLaunchViewError] = useState<unknown>()
+  const [msaText, setMsaText] = useState('')
+  const [treeText, setTreeText] = useState('')
+
   const transcriptSelection = useTranscriptSelection({ feature, view })
-  const { proteinSequence, error } = transcriptSelection
+  const { proteinSequence, selectedTranscript, error } = transcriptSelection
+  const queryRow = useQueryRowName(msaText, proteinSequence)
 
   const s2 = cleanProteinSequence(proteinSequence)
   // a link the user follows to NCBI's own site, not something we fetch — which
@@ -49,37 +82,100 @@ const BlastManualPanel = observer(function ({
 
   return (
     <>
-      <LaunchPanelContent error={error}>
+      <LaunchPanelContent error={launchViewError ?? error}>
         {children}
 
         <TranscriptSelector feature={feature} {...transcriptSelection} />
 
-        {proteinSequence ? (
-          <div className={classes.ncbiLink}>
-            Link to NCBI BLAST: <ExternalLink href={link}>{link2}</ExternalLink>
+        <div className={classes.step}>
+          <Typography variant="subtitle2">1. Run the search at NCBI</Typography>
+          <div className={classes.stepBody}>
+            {proteinSequence ? (
+              <div className={classes.ncbiLink}>
+                <ExternalLink href={link}>{link2}</ExternalLink>
+              </div>
+            ) : (
+              <Alert severity="info">
+                Pick a transcript above to get a link carrying its protein
+                sequence.
+              </Alert>
+            )}
           </div>
-        ) : null}
+        </div>
 
-        <Typography className={classes.infoText}>
-          Click the link above and run your BLAST query, and once you have
-          results, click "Multiple Alignment" at the top of the results page to
-          be redirected to COBALT, NCBI's multiple sequence aligner. Once COBALT
-          completes, you can download an MSA (.aln file) and optionally a Newick
-          tree (.nh) and paste the results into JBrowse
-        </Typography>
+        <div className={classes.step}>
+          <Typography variant="subtitle2">2. Align the hits</Typography>
+          <div className={classes.stepBody}>
+            <Typography>
+              On the results page click "Multiple Alignment" to run COBALT,
+              NCBI's aligner. Download the alignment (.aln) and, if you want the
+              tree drawn, the Newick tree (.nh).
+            </Typography>
+          </div>
+        </div>
+
+        <div className={classes.step}>
+          <Typography variant="subtitle2">
+            3. Paste the results back here
+          </Typography>
+          <div className={classes.stepBody}>
+            <TextField2
+              variant="outlined"
+              label="Alignment"
+              multiline
+              minRows={5}
+              maxRows={10}
+              fullWidth
+              className={classes.msaInput}
+              slotProps={{ input: { className: classes.textAreaFont } }}
+              placeholder="Paste the .aln contents here"
+              value={msaText}
+              onChange={event => {
+                setMsaText(event.target.value)
+              }}
+            />
+            <TextField2
+              variant="outlined"
+              label="Tree (optional)"
+              multiline
+              minRows={3}
+              maxRows={10}
+              fullWidth
+              slotProps={{ input: { className: classes.textAreaFont } }}
+              placeholder="Paste the .nh Newick tree here"
+              value={treeText}
+              onChange={event => {
+                setTreeText(event.target.value)
+              }}
+            />
+
+            <QueryRowSelector {...queryRow} />
+          </div>
+        </div>
       </LaunchPanelContent>
 
-      <DialogActions>
-        <Button
-          color="primary"
-          variant="contained"
-          onClick={() => {
-            handleClose()
-          }}
-        >
-          Close
-        </Button>
-      </DialogActions>
+      <SubmitCancelActions
+        submitDisabled={!selectedTranscript || !msaText.trim()}
+        onSubmit={() => {
+          try {
+            if (selectedTranscript) {
+              setLaunchViewError(undefined)
+              launchView({
+                newViewTitle: getGeneDisplayName(selectedTranscript),
+                view,
+                feature: selectedTranscript,
+                querySeqName: queryRow.querySeqName,
+                data: { msa: msaText, tree: treeText },
+              })
+              handleClose()
+            }
+          } catch (e) {
+            console.error(e)
+            setLaunchViewError(e)
+          }
+        }}
+        onCancel={handleClose}
+      />
     </>
   )
 })

package/src/LaunchMsaView/components/BlastQuery/consts.ts

@@ -9,10 +9,17 @@ export const BASE_BLAST_URL = 'https://blast.ncbi.nlm.nih.gov/Blast.cgi'
 export const msaAlgorithms = ['clustalo', 'muscle', 'kalign', 'mafft'] as const
 export type MsaAlgorithm = (typeof msaAlgorithms)[number]
 
+/**
+ * EBI rejects a submission naming a database outside its own list with a 400,
+ * so every value here has to appear in
+ * https://www.ebi.ac.uk/Tools/services/rest/ncbiblast/parameterdetails/database
+ * -- `uniprotkb_reference_proteomes` did not, and 3.0.0 shipped it as a dead
+ * menu entry.
+ */
 export const blastDatabaseOptions = [
   'uniprotkb_swissprot',
   'uniprotkb',
-  'uniprotkb_reference_proteomes',
+  'pan_proteomes',
   'uniprotkb_trembl',
 ] as const
 export type BlastDatabase = (typeof blastDatabaseOptions)[number]

package/src/LaunchMsaView/components/ManualMSALoader/ManualMSALoader.tsx

@@ -1,20 +1,16 @@
 import React, { useState } from 'react'
 
 import { FileSelector } from '@jbrowse/core/ui'
-import {
-  Alert,
-  FormControl,
-  FormControlLabel,
-  Radio,
-  RadioGroup,
-} from '@mui/material'
+import { FormControl, FormControlLabel, Radio, RadioGroup } from '@mui/material'
 import { observer } from 'mobx-react'
 import { makeStyles } from 'tss-react/mui'
 
 import { launchView } from './launchView'
 import TextField2 from '../../../components/TextField2'
+import { useQueryRowName } from '../../useQueryRowName'
 import { getGeneDisplayName, getLinearGenomeView } from '../../util'
 import LaunchPanelContent from '../LaunchPanelContent'
+import QueryRowSelector from '../QueryRowSelector'
 import SubmitCancelActions from '../SubmitCancelActions'
 import TranscriptSelector from '../TranscriptSelector'
 import { useTranscriptSelection } from '../useTranscriptSelection'
@@ -38,12 +34,6 @@ const useStyles = makeStyles()({
   msaInput: {
     marginBottom: 20,
   },
-  queryNameInput: {
-    marginTop: 20,
-  },
-  warningAlert: {
-    marginTop: 10,
-  },
 })
 
 const ManualMSALoader = observer(function PreLoadedMSA2({
@@ -63,9 +53,9 @@ const ManualMSALoader = observer(function PreLoadedMSA2({
   const [treeText, setTreeText] = useState('')
   const [msaFileLocation, setMsaFileLocation] = useState<FileLocation>()
   const [treeFileLocation, setTreeFileLocation] = useState<FileLocation>()
-  const [querySeqName, setQuerySeqName] = useState('')
   const transcriptSelection = useTranscriptSelection({ feature, view })
-  const { selectedTranscript, error } = transcriptSelection
+  const { selectedTranscript, proteinSequence, error } = transcriptSelection
+  const queryRow = useQueryRowName(msaText, proteinSequence)
 
   const e = launchViewError ?? error
   return (
@@ -143,27 +133,7 @@ const ManualMSALoader = observer(function PreLoadedMSA2({
 
         <TranscriptSelector feature={feature} {...transcriptSelection} />
 
-        <TextField2
-          variant="outlined"
-          name="MSA row name"
-          fullWidth
-          required
-          className={classes.queryNameInput}
-          placeholder="Row name in MSA that corresponds to the selected transcript"
-          helperText="Required: Specify the name of the row in your MSA that should be aligned with the selected transcript"
-          value={querySeqName}
-          onChange={event => {
-            setQuerySeqName(event.target.value)
-          }}
-        />
-
-        {!querySeqName.trim() ? (
-          <Alert severity="warning" className={classes.warningAlert}>
-            Without specifying the MSA row name, clicking on the MSA will not
-            navigate to the corresponding genome position, and hovering
-            highlights will not work.
-          </Alert>
-        ) : null}
+        <QueryRowSelector {...queryRow} />
       </LaunchPanelContent>
 
       <SubmitCancelActions
@@ -180,7 +150,7 @@ const ManualMSALoader = observer(function PreLoadedMSA2({
                 newViewTitle: getGeneDisplayName(selectedTranscript),
                 view,
                 feature: selectedTranscript,
-                querySeqName: querySeqName.trim(),
+                querySeqName: queryRow.querySeqName,
                 ...(inputMethod === 'file'
                   ? {
                       msaFilehandle: msaFileLocation,

package/src/LaunchMsaView/components/QueryRowSelector.tsx

@@ -0,0 +1,93 @@
+import React from 'react'
+
+import { Alert, MenuItem } from '@mui/material'
+import { makeStyles } from 'tss-react/mui'
+
+import TextField2 from '../../components/TextField2'
+
+import type { QueryRowMatch } from '../detectQueryRow'
+
+const useStyles = makeStyles()({
+  field: {
+    marginTop: 20,
+  },
+  alert: {
+    marginTop: 10,
+  },
+})
+
+/**
+ * Which MSA row corresponds to the selected transcript. Clicking and hovering in
+ * the alignment reach the genome only through this name, and a wrong one fails
+ * silently -- the view opens, renders, and never navigates -- so the field fills
+ * itself in from the pasted alignment and offers that alignment's own row names
+ * rather than a free text box the user can typo.
+ */
+export default function QueryRowSelector({
+  names,
+  detected,
+  querySeqName,
+  setQuerySeqName,
+  isAutoDetected,
+}: {
+  names: string[]
+  detected?: QueryRowMatch
+  querySeqName: string
+  setQuerySeqName: (arg: string) => void
+  isAutoDetected: boolean
+}) {
+  const { classes } = useStyles()
+
+  return (
+    <>
+      {names.length > 0 ? (
+        <TextField2
+          variant="outlined"
+          label="MSA row matching the selected transcript"
+          select
+          fullWidth
+          className={classes.field}
+          value={names.includes(querySeqName) ? querySeqName : ''}
+          onChange={event => {
+            setQuerySeqName(event.target.value)
+          }}
+        >
+          {names.map(name => (
+            <MenuItem value={name} key={name}>
+              {name}
+              {detected?.name === name ? ' — matches your protein' : ''}
+            </MenuItem>
+          ))}
+        </TextField2>
+      ) : (
+        <TextField2
+          variant="outlined"
+          label="MSA row matching the selected transcript"
+          fullWidth
+          className={classes.field}
+          helperText="Paste an alignment above and this fills in on its own"
+          value={querySeqName}
+          onChange={event => {
+            setQuerySeqName(event.target.value)
+          }}
+        />
+      )}
+
+      {isAutoDetected && detected ? (
+        <Alert severity="success" className={classes.alert}>
+          Matched <strong>{detected.name}</strong> to your protein sequence
+          {detected.quality === 'exact'
+            ? ''
+            : `, covering ${Math.round(detected.identity * 100)}% of it`}
+          . Clicking the alignment will navigate the genome view.
+        </Alert>
+      ) : names.length > 0 && !querySeqName ? (
+        <Alert severity="warning" className={classes.alert}>
+          No row matched your protein sequence — pick the one for your gene
+          above. Without it the alignment still renders, but clicking it will
+          not navigate the genome view.
+        </Alert>
+      ) : null}
+    </>
+  )
+}

package/src/LaunchMsaView/detectQueryRow.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, test } from 'vitest'
+
+import { detectQueryRow, getMsaRowNames } from './detectQueryRow'
+
+const protein = 'MKWVTFISLLLLFSSAYSRGVFRRDTHKSEIAHRFKDLGEEHFKGLVLIAFSQYLQQCPFD'
+
+// COBALT renames the query `Query_1`, so only the residues identify it
+const clustal = `CLUSTAL W (1.81) multiple sequence alignment
+
+Query_1         MKWVTFISLLLLFSSAYSRGVFRRDTHKSEIAHRFKDLGEEHFKGLVLIAFSQYLQQCPFD
+sp|P02769|ALBU  MKWVTFISLLLLFSSAYSRGVFRRDTHKSEIAHRFKDLGEEHFKGLVLIAFSQYLQQCPYD
+sp|Q5XLE4|OTHE  MKWVTFISLLLLFSSAYSRGVFRRDTHKSEIAHRFKDLGEEHFKGLVLIAFSQYLWWCPFD
+`
+
+const fasta = `>Query_1
+MKWVTFISLLLLFSSAYSRGVFRRDTHKSEIAHRFKDLGEEHFKGLVLIAFSQYLQQCPFD
+>sp|P02769|ALBU_BOVIN
+MKWVTFISLLLLFSSAYSRG--RRDTHKSEIAHRFKDLGEEHFKGLVLIAFSQYLQQCPYD
+`
+
+describe('detectQueryRow', () => {
+  test('finds the query by sequence when the aligner renamed it', () => {
+    expect(detectQueryRow(clustal, protein)).toMatchObject({
+      name: 'Query_1',
+      quality: 'exact',
+    })
+  })
+
+  test('ignores gaps in the aligned row', () => {
+    expect(detectQueryRow(fasta, protein)?.name).toBe('Query_1')
+  })
+
+  test('tolerates the trailing stop codon the translation carries', () => {
+    expect(detectQueryRow(clustal, `${protein}*`)?.name).toBe('Query_1')
+  })
+
+  test('matches a row that is the query trimmed to the aligned region', () => {
+    const trimmed = `>hit_one\nWRONGWRONGWRONGWRONG\n>aligned_query\n${protein.slice(5, 40)}\n`
+    expect(detectQueryRow(trimmed, protein)).toMatchObject({
+      name: 'aligned_query',
+      quality: 'partial',
+    })
+  })
+
+  // the failure that matters: silently wiring the view to a homolog would look
+  // like it worked, and every navigation afterwards would land in the wrong place
+  test('returns nothing when only diverged homologs are present', () => {
+    const homologsOnly = `>hit_one
+MKWVTFISLLLLFSSAYSRGVFRRDTHKSEIAHRFKDLGEEHFKGLVLIAFSQYLQQCPFD
+>hit_two
+MKWVTFISLLLLFSSAYSRGVFRRDTHKSEIAHRFKDLGEEHFKGLVLIAFSQYLQQCPFD
+`
+    expect(
+      detectQueryRow(homologsOnly, 'WWWWWWWWWWWWWWWWWWWWWWWWWWWWWW'),
+    ).toBeUndefined()
+  })
+
+  test('returns nothing rather than throwing on a half-pasted alignment', () => {
+    expect(detectQueryRow('>partial\nMKWV', protein)).toBeUndefined()
+    expect(detectQueryRow('not an alignment at all', protein)).toBeUndefined()
+    expect(detectQueryRow('', protein)).toBeUndefined()
+    expect(detectQueryRow(clustal, '')).toBeUndefined()
+  })
+})
+
+describe('getMsaRowNames', () => {
+  test('lists the rows for the override dropdown', () => {
+    expect(getMsaRowNames(clustal)).toEqual([
+      'Query_1',
+      'sp|P02769|ALBU',
+      'sp|Q5XLE4|OTHE',
+    ])
+  })
+
+  test('is empty rather than throwing while the user is still pasting', () => {
+    expect(getMsaRowNames('CLUSTAL W')).toEqual([])
+    expect(getMsaRowNames('')).toEqual([])
+  })
+})

package/src/LaunchMsaView/detectQueryRow.ts

@@ -0,0 +1,132 @@
+import { getUngappedSequence, parseMSA } from 'msa-parsers'
+
+/**
+ * Which row of a pasted alignment is the gene the user launched from.
+ *
+ * The MsaView needs that row name to tie alignment columns back to genome
+ * coordinates, and until now the user typed it. Nothing validates a typo: the
+ * view opens, renders, and simply never navigates or highlights, which reads as
+ * a broken feature rather than a wrong field. Meanwhile the plugin already
+ * knows the protein sequence it sent to BLAST, so it can find the row by
+ * sequence instead of asking.
+ *
+ * NCBI and EBI both rename the query on the way through -- COBALT emits
+ * `Query_1`, EBI's aligners carry the accession -- so the name is no help. The
+ * residues are, and they survive every rename.
+ */
+
+export type MatchQuality = 'exact' | 'partial' | 'similar'
+
+export interface QueryRowMatch {
+  name: string
+  quality: MatchQuality
+  /** identity over the compared region, 0-1 */
+  identity: number
+}
+
+/**
+ * A stop codon is present in the transcript's translation and absent from
+ * anything an aligner returns, and case is not meaningful in either.
+ */
+function normalize(seq: string) {
+  return seq
+    .replaceAll('*', '')
+    .replaceAll('-', '')
+    .replaceAll('.', '')
+    .toUpperCase()
+}
+
+function identityOverOverlap(a: string, b: string) {
+  const len = Math.min(a.length, b.length)
+  if (len === 0) {
+    return 0
+  }
+  let same = 0
+  for (let i = 0; i < len; i++) {
+    if (a[i] === b[i]) {
+      same++
+    }
+  }
+  return same / len
+}
+
+/**
+ * Below this, a "best" row is not a match at all -- an alignment of homologs is
+ * full of rows in the 40-70% range, and picking the top one would silently wire
+ * the view to a paralog from another species.
+ */
+const SIMILARITY_FLOOR = 0.9
+
+/**
+ * How much of the query a contained row has to cover. A short fragment is a
+ * substring of almost any protein, so without a floor the first few residues of
+ * a half-pasted alignment match the query and the field fills in with a row the
+ * user is still typing.
+ */
+const PARTIAL_COVERAGE_FLOOR = 0.5
+
+export function detectQueryRow(
+  msaText: string,
+  proteinSequence: string,
+): QueryRowMatch | undefined {
+  const query = normalize(proteinSequence)
+  if (!query || !msaText.trim()) {
+    return undefined
+  }
+
+  let names: string[]
+  let parsed: { getRow: (name: string) => string }
+  try {
+    const msa = parseMSA(msaText)
+    names = msa.getNames()
+    parsed = msa
+  } catch {
+    // a half-pasted alignment throws here on every keystroke; the caller shows
+    // the field rather than an error
+    return undefined
+  }
+
+  const candidates: QueryRowMatch[] = []
+  for (const name of names) {
+    const row = normalize(getUngappedSequence(parsed.getRow(name)))
+    if (!row) {
+      continue
+    }
+    if (row === query) {
+      // nothing beats an exact match, and a second one would be a duplicate row
+      return { name, quality: 'exact', identity: 1 }
+    }
+    // BLAST reports the aligned region, so the row is often the query trimmed
+    // at one or both ends rather than the whole protein
+    if (query.includes(row) || row.includes(query)) {
+      const coverage =
+        Math.min(row.length, query.length) / Math.max(row.length, query.length)
+      if (coverage >= PARTIAL_COVERAGE_FLOOR) {
+        candidates.push({ name, quality: 'partial', identity: coverage })
+      }
+      continue
+    }
+    const identity = identityOverOverlap(row, query)
+    if (identity >= SIMILARITY_FLOOR) {
+      candidates.push({ name, quality: 'similar', identity })
+    }
+  }
+
+  const order: MatchQuality[] = ['exact', 'partial', 'similar']
+  return candidates.sort(
+    (a, b) =>
+      order.indexOf(a.quality) - order.indexOf(b.quality) ||
+      b.identity - a.identity,
+  )[0]
+}
+
+export function getMsaRowNames(msaText: string): string[] {
+  if (!msaText.trim()) {
+    return []
+  }
+  try {
+    return parseMSA(msaText).getNames()
+  } catch {
+    return []
+  }
+}

package/src/LaunchMsaView/useQueryRowName.ts

@@ -0,0 +1,33 @@
+import { useMemo, useState } from 'react'
+
+import { detectQueryRow, getMsaRowNames } from './detectQueryRow'
+
+/**
+ * The MSA row name to launch with, found by sequence rather than typed.
+ *
+ * Only the user's override is state. The detected name is derived from the
+ * pasted text during render, so pasting a new alignment re-detects without an
+ * effect writing back into state, and an override survives later edits to the
+ * alignment because it is the one thing actually stored.
+ */
+export function useQueryRowName(msaText: string, proteinSequence: string) {
+  const [override, setOverride] = useState<string>()
+
+  // parsing runs on every keystroke in the paste box otherwise, and an
+  // alignment of a few hundred rows is not free
+  const { detected, names } = useMemo(
+    () => ({
+      detected: detectQueryRow(msaText, proteinSequence),
+      names: getMsaRowNames(msaText),
+    }),
+    [msaText, proteinSequence],
+  )
+
+  return {
+    detected,
+    names,
+    querySeqName: override ?? detected?.name ?? '',
+    setQuerySeqName: setOverride,
+    isAutoDetected: override === undefined && !!detected,
+  }
+}