jbrowse-plugin-msaview 3.0.0 → 3.2.0

package/src/LaunchMsaView/components/ManualMSALoader/launchView.ts

@@ -1,5 +1,8 @@
 import { getSession } from '@jbrowse/core/util'
 
+import { launchMsaView } from '../../../utils/launchMsaView'
+import { readLaunchPlacement } from '../../../utils/workspaces'
+
 import type { Feature, FileLocation } from '@jbrowse/core/util'
 import type { LinearGenomeViewModel } from '@jbrowse/plugin-linear-genome-view'
 
@@ -23,8 +26,8 @@ export function launchView({
     tree?: string
   }
 }) {
-  getSession(view).addView('MsaView', {
-    type: 'MsaView',
+  launchMsaView(getSession(view), {
+    placement: readLaunchPlacement(),
     displayName: newViewTitle,
     connectedViewId: view.id,
     connectedFeature: feature.toJSON(),

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

@@ -98,9 +98,9 @@ const OrthologPanel = observer(function ({
         </div>
 
         <TranscriptSelector feature={feature} {...transcriptSelection} />
-
       </LaunchPanelContent>
       <SubmitCancelActions
+        model={model}
         submitDisabled={!proteinSequence || !rowCountValid}
         onSubmit={() => {
           try {

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

@@ -1,5 +1,8 @@
 import { getSession } from '@jbrowse/core/util'
 
+import { launchMsaView } from '../../../utils/launchMsaView'
+import { readLaunchPlacement } from '../../../utils/workspaces'
+
 import type { OrthologParams } from '../../../MsaViewPanel/model'
 import type { Feature } from '@jbrowse/core/util'
 import type { LinearGenomeViewModel } from '@jbrowse/plugin-linear-genome-view'
@@ -15,8 +18,8 @@ export function orthologLaunchView({
   feature: Feature
   orthologParams: OrthologParams
 }) {
-  getSession(view).addView('MsaView', {
-    type: 'MsaView',
+  launchMsaView(getSession(view), {
+    placement: readLaunchPlacement(),
     displayName: newViewTitle,
     connectedViewId: view.id,
     connectedFeature: feature.toJSON(),

package/src/LaunchMsaView/components/PreLoadedMSA/PreLoadedMSADataPanel.tsx

@@ -130,6 +130,7 @@ const PreLoadedMSA = observer(function ({
       </LaunchPanelContent>
 
       <SubmitCancelActions
+        model={model}
         submitDisabled={!selectedTranscript || !msaData?.length}
         onSubmit={() => {
           try {

package/src/LaunchMsaView/components/PreLoadedMSA/preCalculatedLaunchView.ts

@@ -1,5 +1,8 @@
 import { getSession } from '@jbrowse/core/util'
 
+import { launchMsaView } from '../../../utils/launchMsaView'
+import { readLaunchPlacement } from '../../../utils/workspaces'
+
 import type { Feature } from '@jbrowse/core/util'
 import type { LinearGenomeViewModel } from '@jbrowse/plugin-linear-genome-view'
 
@@ -16,8 +19,8 @@ export function preCalculatedLaunchView({
   feature: Feature
   querySeqName: string
 }) {
-  getSession(view).addView('MsaView', {
-    type: 'MsaView',
+  launchMsaView(getSession(view), {
+    placement: readLaunchPlacement(),
     displayName: newViewTitle,
     treeAreaWidth: 200,
     querySeqName,

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/components/SubmitCancelActions.test.tsx

@@ -0,0 +1,95 @@
+// @vitest-environment jsdom
+import React from 'react'
+
+import { cleanup, render, screen } from '@testing-library/react'
+import { afterEach, beforeEach, expect, test, vi } from 'vitest'
+
+import SubmitCancelActions from './SubmitCancelActions'
+import { LAUNCH_PLACEMENT_KEY } from '../../utils/workspaces'
+
+import type { AbstractTrackModel } from '@jbrowse/core/util'
+
+// getSession walks the MST tree, and this component only wants the two actions
+// off the far end of that walk
+vi.mock('@jbrowse/core/util', () => ({
+  getSession: (model: { session: unknown }) => model.session,
+}))
+
+function trackModel(session: Record<string, unknown>) {
+  return { session } as unknown as AbstractTrackModel
+}
+
+const tiling = { setUseWorkspaces() {}, setPendingMove() {} }
+
+beforeEach(() => {
+  localStorage.clear()
+})
+
+afterEach(() => {
+  cleanup()
+})
+
+function toggle() {
+  return screen.queryByRole('checkbox')
+}
+
+test('a host that can tile offers the choice, checked by default', () => {
+  render(
+    <SubmitCancelActions
+      model={trackModel(tiling)}
+      onSubmit={() => {}}
+      onCancel={() => {}}
+    />,
+  )
+  expect(toggle()).toBeTruthy()
+  expect((toggle() as HTMLInputElement).checked).toBe(true)
+  expect(localStorage.getItem(LAUNCH_PLACEMENT_KEY)).toBeNull()
+})
+
+// the box would do nothing on an embedded session, and a control that silently
+// does nothing is worse than one that is not there
+test('a host that cannot tile does not offer it', () => {
+  render(
+    <SubmitCancelActions
+      model={trackModel({})}
+      onSubmit={() => {}}
+      onCancel={() => {}}
+    />,
+  )
+  expect(toggle()).toBeNull()
+  expect(screen.getByText('Submit')).toBeTruthy()
+})
+
+test('a panel that launches nothing passes no model, and gets no box', () => {
+  render(<SubmitCancelActions onSubmit={() => {}} onCancel={() => {}} />)
+  expect(toggle()).toBeNull()
+})
+
+test('clicking it writes the placement the next launch will read', () => {
+  render(
+    <SubmitCancelActions
+      model={trackModel(tiling)}
+      onSubmit={() => {}}
+      onCancel={() => {}}
+    />,
+  )
+  toggle()!.click()
+  expect(localStorage.getItem(LAUNCH_PLACEMENT_KEY)).toBe('stack')
+  expect((toggle() as HTMLInputElement).checked).toBe(false)
+
+  toggle()!.click()
+  expect(localStorage.getItem(LAUNCH_PLACEMENT_KEY)).toBe('splitRight')
+  expect((toggle() as HTMLInputElement).checked).toBe(true)
+})
+
+test('a stored choice is what the box opens on', () => {
+  localStorage.setItem(LAUNCH_PLACEMENT_KEY, 'stack')
+  render(
+    <SubmitCancelActions
+      model={trackModel(tiling)}
+      onSubmit={() => {}}
+      onCancel={() => {}}
+    />,
+  )
+  expect((toggle() as HTMLInputElement).checked).toBe(false)
+})

package/src/LaunchMsaView/components/SubmitCancelActions.tsx

@@ -1,6 +1,53 @@
-import React from 'react'
+import React, { useState } from 'react'
 
-import { Button, DialogActions } from '@mui/material'
+import { getSession } from '@jbrowse/core/util'
+import {
+  Button,
+  Checkbox,
+  DialogActions,
+  FormControlLabel,
+} from '@mui/material'
+
+import {
+  readLaunchPlacement,
+  sessionSupportsPlacement,
+  writeLaunchPlacement,
+} from '../../utils/workspaces'
+
+import type { AbstractTrackModel } from '@jbrowse/core/util'
+
+/**
+ * Where the launch puts the view, offered wherever a launch is submitted.
+ *
+ * A checkbox rather than a menu of the three placements: the choice a reader
+ * has at this point is "beside the genome view or under it", and `newTab` is a
+ * spec's to state, not a thing to pick before you have seen the alignment.
+ *
+ * Absent entirely on a host that cannot tile — an embedded session, or a
+ * release that places views its own way — because the box would do nothing
+ * there and every launch would quietly ignore it.
+ */
+function PlacementToggle({ model }: { model: AbstractTrackModel }) {
+  const session = getSession(model)
+  const [sideBySide, setSideBySide] = useState(
+    () => readLaunchPlacement() === 'splitRight',
+  )
+  return sessionSupportsPlacement(session) ? (
+    <FormControlLabel
+      label="Open beside the genome view"
+      control={
+        <Checkbox
+          checked={sideBySide}
+          onChange={event => {
+            const { checked } = event.target
+            setSideBySide(checked)
+            writeLaunchPlacement(checked ? 'splitRight' : 'stack')
+          }}
+        />
+      }
+    />
+  ) : null
+}
 
 export default function SubmitCancelActions({
   onSubmit,
@@ -8,34 +55,45 @@ export default function SubmitCancelActions({
   submitDisabled,
   submitLabel = 'Submit',
   cancelLabel = 'Cancel',
+  model,
 }: {
   onSubmit: () => void
   onCancel: () => void
   submitDisabled?: boolean
   submitLabel?: string
   cancelLabel?: string
+  /** omitted by a panel that submits something other than a view launch */
+  model?: AbstractTrackModel
 }) {
   return (
-    <DialogActions>
-      <Button
-        color="primary"
-        variant="contained"
-        disabled={submitDisabled}
-        onClick={() => {
-          onSubmit()
-        }}
-      >
-        {submitLabel}
-      </Button>
-      <Button
-        color="secondary"
-        variant="contained"
-        onClick={() => {
-          onCancel()
-        }}
-      >
-        {cancelLabel}
-      </Button>
+    // The buttons are one child rather than two, so a dialog too narrow for
+    // the whole row wraps them together underneath the option instead of
+    // breaking Cancel away from Submit or shrinking both out of shape.
+    <DialogActions sx={{ flexWrap: 'wrap', rowGap: 1 }}>
+      {model ? <PlacementToggle model={model} /> : null}
+      <div style={{ display: 'flex', gap: 8, marginLeft: 'auto' }}>
+        <Button
+          sx={{ flexShrink: 0 }}
+          color="primary"
+          variant="contained"
+          disabled={submitDisabled}
+          onClick={() => {
+            onSubmit()
+          }}
+        >
+          {submitLabel}
+        </Button>
+        <Button
+          sx={{ flexShrink: 0 }}
+          color="secondary"
+          variant="contained"
+          onClick={() => {
+            onCancel()
+          }}
+        >
+          {cancelLabel}
+        </Button>
+      </div>
     </DialogActions>
   )
 }

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

package/src/LaunchMsaViewExtensionPoint/index.ts

@@ -1,4 +1,7 @@
+import { launchMsaView } from '../utils/launchMsaView'
+
 import type { OrthologParams } from '../MsaViewPanel/model'
+import type { MsaViewPlacement } from '../utils/workspaces'
 import type PluginManager from '@jbrowse/core/PluginManager'
 import type { AbstractSessionModel } from '@jbrowse/core/util'
 
@@ -39,6 +42,23 @@ interface LaunchMsaViewArgs {
    * snapshot property passes through the same way.
    */
   allowedGappyness?: number
+  /**
+   * Where the view lands: `stack` (default), `splitRight` or `newTab`. The
+   * declarative half of the launch — a link states the arrangement it wants
+   * instead of the reader dragging the view into place.
+   *
+   * The default is `stack` and has to stay `stack`: it is what every link
+   * written before this key existed already does, and the only thing an
+   * embedded session can do. The launch DIALOG defaults to `splitRight`
+   * instead (see `DEFAULT_LAUNCH_PLACEMENT`), because a launch from a gene
+   * feature is a connected pair and reads as a split.
+   *
+   * A spec that arranges more than these two views should use the host's own
+   * `layout` key instead, which states the whole tree and is applied after
+   * every view in the spec has launched. Both may be given; `layout` wins,
+   * being the later and more specific statement.
+   */
+  placement?: MsaViewPlacement
 }
 
 export default function LaunchMsaViewExtensionPointF(
@@ -76,8 +96,7 @@ export default function LaunchMsaViewExtensionPointF(
       // directly, and so is orthologParams (the model's own autorun picks it up).
       // Only sources needing launch-time resolution go through `init`: msaUrl
       // (AlphaFold sniff) and the name-indexed bgzip block (no native loader).
-      session.addView('MsaView', {
-        type: 'MsaView',
+      launchMsaView(session, {
         ...rest,
         data,
         ...(treeFileLocation