jbrowse-plugin-graphgenomeviewer 1.0.0 → 3.0.3

package/src/launchSubgraph/linearViewMenuItems.test.ts

@@ -0,0 +1,176 @@
+// LAUNCH_LABEL rather than the literal: the host renamed this submenu from
+// "Launch view" to "Launch" (packages/core/src/ui/launchViewMenu.ts says why),
+// and a hardcoded copy here fails as "the item was never added" rather than as
+// "the submenu is called something else".
+import { LAUNCH_LABEL } from '@jbrowse/core/ui'
+
+import { createTestEnvironment } from './testEnv'
+import { MAX_GRAPH_REGION_BP } from '../GraphGenomeView/model'
+
+import type { MenuItem } from '@jbrowse/core/ui'
+
+const LABEL_VISIBLE = 'Graph genome view (this region)'
+const LABEL_SELECTION = 'Graph genome view (this selection)'
+const LABEL_FEATURE = 'Graph genome view (this feature)'
+
+function launchItems(items: MenuItem[]) {
+  const item = items.find(i => 'label' in i && i.label === LAUNCH_LABEL)
+  return item && 'subMenu' in item ? item.subMenu : []
+}
+
+function find(items: MenuItem[], label: string) {
+  return items.find(i => 'label' in i && i.label === label)
+}
+
+function click(item: MenuItem | undefined) {
+  if (item && 'onClick' in item) {
+    item.onClick(undefined)
+  } else {
+    throw new Error('menu item has no onClick')
+  }
+}
+
+// A rubberband selection is the entry point that works at the zoom people
+// actually browse at: the visible region is routinely wider than the cap, and
+// selecting a range needs no navigating first.
+test('the rubberband menu launches the selected range', () => {
+  const { createDisplay } = createTestEnvironment()
+  const { session, view } = createDisplay()
+  view.setOffsets(
+    { refName: 'ctgA', index: 0, offset: 1000, start: 0, end: 50_000 },
+    { refName: 'ctgA', index: 0, offset: 2000, start: 0, end: 50_000 },
+  )
+
+  const item = find(view.rubberBandMenuItems(), LABEL_SELECTION)
+  expect(item).toBeDefined()
+  click(item)
+
+  const [type, snapshot] = session.addedViews[0]!
+  expect(type).toBe('GraphGenomeView')
+  expect(snapshot.loadedTrackId).toBe('graph_track')
+  expect(snapshot.connectedViewId).toBe(view.id)
+  expect(snapshot.loadedRegion).toMatchObject({ refName: 'ctgA' })
+})
+
+test('the rubberband menu keeps the items it already had', () => {
+  const { createDisplay } = createTestEnvironment()
+  const { view } = createDisplay()
+  view.setOffsets(
+    { refName: 'ctgA', index: 0, offset: 1000, start: 0, end: 50_000 },
+    { refName: 'ctgA', index: 0, offset: 2000, start: 0, end: 50_000 },
+  )
+  const labels = view
+    .rubberBandMenuItems()
+    .flatMap((i: MenuItem) => ('label' in i ? [i.label] : []))
+  expect(labels).toContain('Zoom to region')
+  expect(labels).toContain(LABEL_SELECTION)
+})
+
+// Nothing selected is not a launchable region, so the item stays out of the menu
+// rather than appearing dead.
+test('no rubberband selection adds no item', () => {
+  const { createDisplay } = createTestEnvironment()
+  const { view } = createDisplay()
+  expect(find(view.rubberBandMenuItems(), LABEL_SELECTION)).toBeUndefined()
+})
+
+// The point of the view-level item: the graph track need not be the one whose
+// menu you opened, or be open at all.
+test('the view menu launches the visible region', () => {
+  const { createDisplay } = createTestEnvironment()
+  const { session, view } = createDisplay({ trackId: 'bubble_track' })
+
+  const item = find(launchItems(view.menuItems()), LABEL_VISIBLE)
+  expect(item).toBeDefined()
+  click(item)
+
+  expect(session.addedViews[0]![1].loadedTrackId).toBe('graph_track')
+})
+
+// A vanishing item teaches nothing; a greyed-out one with the size in its
+// tooltip says what to do about it.
+test('an over-cap region disables the item instead of hiding it', () => {
+  const { createDisplay } = createTestEnvironment()
+  const { session, view } = createDisplay()
+  view.setDisplayedRegions([
+    {
+      assemblyName: 'volvox',
+      refName: 'ctgA',
+      start: 0,
+      end: MAX_GRAPH_REGION_BP * 3,
+    },
+  ])
+  // the *visible* span is what's cut, so it has to be zoomed out past the cap,
+  // not merely have a large region loaded
+  view.showAllRegions()
+  expect(view.dynamicBlocks.totalBp).toBeGreaterThan(MAX_GRAPH_REGION_BP)
+
+  const item = find(launchItems(view.menuItems()), LABEL_VISIBLE)
+  expect(item).toMatchObject({ disabled: true })
+  expect(item && 'disabledHelpText' in item && item.disabledHelpText).toMatch(
+    /zoom in or select a smaller range/i,
+  )
+  expect(session.addedViews).toHaveLength(0)
+})
+
+// A graph is cut on its reference, the first assembly its track names, so a
+// view of another one gets the reason rather than a cut in the wrong frame.
+test('a view of a non-reference assembly disables the item and names the reference', () => {
+  const { createDisplay } = createTestEnvironment({
+    graphAssemblyNames: ['hg38', 'volvox'],
+  })
+  const { session, view } = createDisplay()
+  const item = find(launchItems(view.menuItems()), LABEL_VISIBLE)
+  expect(item).toMatchObject({ disabled: true })
+  expect(item && 'disabledHelpText' in item && item.disabledHelpText).toMatch(
+    /cut on its reference, hg38/,
+  )
+  expect(session.addedViews).toHaveLength(0)
+})
+
+// The bubble track marks exactly where haplotypes diverge, which is the most
+// natural thing to right-click — but its adapter reads a summary index and
+// cannot cut a graph, so the launch has to come from the graph track instead.
+test('right-clicking a feature on a non-graph track cuts from the graph track', () => {
+  const { createDisplay } = createTestEnvironment()
+  const { session, display, view } = createDisplay({ trackId: 'bubble_track' })
+  display.openContextMenu({
+    item: { featureId: 'bubble1', startBp: 2000, endBp: 2400, name: 'bubble1' },
+    displayedRegionIndex: 0,
+    clientX: 0,
+    clientY: 0,
+  })
+
+  const item = find(launchItems(display.contextMenuItems()), LABEL_FEATURE)
+  expect(item).toBeDefined()
+  click(item)
+
+  const [, snapshot] = session.addedViews[0]!
+  expect(snapshot.loadedTrackId).toBe('graph_track')
+  expect(snapshot.connectedViewId).toBe(view.id)
+  // padded by half the feature's length on each side
+  expect(snapshot.loadedRegion).toEqual({
+    refName: 'ctgA',
+    assemblyName: 'volvox',
+    start: 1800,
+    end: 2600,
+  })
+})
+
+// No graph data in the session means no menu clutter anywhere.
+test('no graph track in the session adds no items', () => {
+  const { createDisplay } = createTestEnvironment({ subgraphCapable: false })
+  const { view, display } = createDisplay({ trackId: 'bubble_track' })
+  display.openContextMenu({
+    item: { featureId: 'bubble1', startBp: 2000, endBp: 2400, name: 'bubble1' },
+    displayedRegionIndex: 0,
+    clientX: 0,
+    clientY: 0,
+  })
+
+  expect(find(launchItems(view.menuItems()), LABEL_VISIBLE)).toBeUndefined()
+  expect(find(view.rubberBandMenuItems(), LABEL_SELECTION)).toBeUndefined()
+  expect(
+    find(launchItems(display.contextMenuItems()), LABEL_FEATURE),
+  ).toBeUndefined()
+})

package/src/launchSubgraph/linearViewMenuItems.ts

@@ -0,0 +1,107 @@
+import { pushLaunchViewMenuItem } from '@jbrowse/core/ui'
+import { getSession } from '@jbrowse/core/util'
+
+import { SUBGRAPH_REGION_LABEL, regionFromViewport } from './launchSubgraphView'
+import { subgraphMenuItems } from './subgraphMenuItems'
+import { subgraphTracks } from './subgraphTracks'
+
+import type PluginManager from '@jbrowse/core/PluginManager'
+import type { PluggableElementType } from '@jbrowse/core/pluggableElementTypes'
+import type ViewType from '@jbrowse/core/pluggableElementTypes/ViewType'
+import type { LinearGenomeViewModel } from '@jbrowse/plugin-linear-genome-view'
+
+const SELECTION_LABEL = 'Graph genome view (this selection)'
+
+function isLinearGenomeView(elt: { name: string }): elt is ViewType {
+  return elt.name === 'LinearGenomeView'
+}
+
+// Launch entry points on the linear view itself, rather than on a graph track's
+// menu. Two reasons this is where they belong:
+//
+//   - The graph track need not be in the view, or even turned on. Scanning the
+//     session for a subgraph-capable track gives a user browsing genes a way in;
+//     before, the only entry point was the menu of a track they might never have
+//     opened.
+//   - A rubberband selection picks a window directly, with no navigating first,
+//     and is the only way to ask about a range narrower than what is on screen.
+export default function LinearViewMenuItemsF(pluginManager: PluginManager) {
+  pluginManager.addToExtensionPoint(
+    'Core-extendPluggableElement',
+    (pluggableElement: PluggableElementType) => {
+      if (isLinearGenomeView(pluggableElement)) {
+        // extendStateModel, NOT `stateModel = stateModel.extend(...)`: see
+        // launchSubgraph/index.ts for what a synchronous read costs now that the
+        // host registers state models as lazy loaders.
+        pluggableElement.extendStateModel(stateModel =>
+          stateModel.extend(
+            // Annotated rather than cast: the extension point hands over an
+            // IAnyModelType, and stating the model shape here is what types
+            // `getSelectedRegions`/`dynamicBlocks` below without an `as`.
+            (self: LinearGenomeViewModel) => {
+              const superMenuItems = self.menuItems
+              const superRubberBandMenuItems = self.rubberBandMenuItems
+
+              // Graph tracks for this view's assembly. Empty means every item
+              // below is empty too, so a session with no graph data gains no menu
+              // clutter.
+              function tracks() {
+                const assemblyName = self.assemblyNames[0]
+                return assemblyName
+                  ? subgraphTracks(
+                      pluginManager,
+                      getSession(self),
+                      assemblyName,
+                      self,
+                    )
+                  : []
+              }
+
+              return {
+                views: {
+                  menuItems() {
+                    const items = superMenuItems()
+                    for (const item of subgraphMenuItems({
+                      label: SUBGRAPH_REGION_LABEL,
+                      region: regionFromViewport(
+                        self.dynamicBlocks.contentBlocks,
+                      ),
+                      tracks: tracks(),
+                      session: getSession(self),
+                      connectedViewId: self.id,
+                    })) {
+                      pushLaunchViewMenuItem(items, item)
+                    }
+                    return items
+                  },
+
+                  // The rubberband menu is short and contextual, so these go in
+                  // flat rather than under a "Launch view" submenu — that grouping
+                  // earns its keep in the long track and view menus, not here.
+                  rubberBandMenuItems() {
+                    return [
+                      ...superRubberBandMenuItems(),
+                      ...subgraphMenuItems({
+                        label: SELECTION_LABEL,
+                        region: regionFromViewport(
+                          self.getSelectedRegions(
+                            self.leftOffset,
+                            self.rightOffset,
+                          ),
+                        ),
+                        tracks: tracks(),
+                        session: getSession(self),
+                        connectedViewId: self.id,
+                      }),
+                    ]
+                  },
+                },
+              }
+            },
+          ),
+        )
+      }
+      return pluggableElement
+    },
+  )
+}

package/src/launchSubgraph/multiWayLaunch.test.ts

@@ -0,0 +1,289 @@
+import PluginManager from '@jbrowse/core/PluginManager'
+import {
+  ConfigurationReference,
+  ConfigurationSchema,
+  getConf,
+} from '@jbrowse/core/configuration'
+import AdapterType from '@jbrowse/core/pluggableElementTypes/AdapterType'
+import DisplayType from '@jbrowse/core/pluggableElementTypes/DisplayType'
+import TrackType from '@jbrowse/core/pluggableElementTypes/TrackType'
+import ViewType from '@jbrowse/core/pluggableElementTypes/ViewType'
+import {
+  BaseDisplay,
+  createBaseTrackConfig,
+  createBaseTrackModel,
+} from '@jbrowse/core/pluggableElementTypes/models'
+import { LAUNCH_LABEL } from '@jbrowse/core/ui'
+import { getContainingTrack } from '@jbrowse/core/util'
+import { types } from '@jbrowse/mobx-state-tree'
+import { linearGenomeViewStateModelFactory } from '@jbrowse/plugin-linear-genome-view'
+
+import LaunchSubgraphMenuItemF from './index'
+import LinearViewMenuItemsF from './linearViewMenuItems'
+
+import type { MenuItem } from '@jbrowse/core/ui'
+import type { Instance } from '@jbrowse/mobx-state-tree'
+
+const LABEL = 'Graph genome view (this region)'
+
+// A stand-in for core's MultiWaySyntenyDisplay with the four members the
+// launch reads by duck type (subgraphTracks.ts): the lanes in force are the
+// picker's choice, else the track's own lanes, and a hidden lane stays in
+// force.
+function laneDisplayType() {
+  const configSchema = ConfigurationSchema(
+    'MultiWaySyntenyDisplay',
+    {},
+    { explicitIdentifier: 'displayId', explicitlyTyped: true },
+  )
+  const stateModel = types
+    .compose(
+      'MultiWaySyntenyDisplay',
+      BaseDisplay,
+      types.model({
+        type: types.literal('MultiWaySyntenyDisplay'),
+        configuration: ConfigurationReference(configSchema),
+      }),
+    )
+    .volatile(() => ({
+      picked: undefined as string[] | undefined,
+      hidden: [] as string[],
+    }))
+    .views(self => ({
+      get laneSelection(): readonly string[] | undefined {
+        const configured = getConf(
+          getContainingTrack(self),
+          'assemblyNames',
+        ).slice(1)
+        return self.picked ?? (configured.length ? configured : undefined)
+      },
+      get hiddenLanes(): readonly string[] {
+        return self.hidden
+      },
+      trackMenuItems(): MenuItem[] {
+        return []
+      },
+    }))
+    .actions(self => ({
+      setSelectedLanes(names: string[] | undefined) {
+        self.picked = names
+      },
+      hideLane(name: string) {
+        self.hidden = [...self.hidden, name]
+      },
+    }))
+  return new DisplayType({
+    name: 'MultiWaySyntenyDisplay',
+    configSchema,
+    stateModel,
+    trackType: 'SyntenyTrack',
+    viewType: 'LinearGenomeView',
+    ReactComponent: () => null,
+  })
+}
+
+function createEnv(trackLanes: string[] = []) {
+  console.warn = vi.fn()
+  console.error = vi.fn()
+  const pluginManager = new PluginManager()
+  pluginManager.addAdapterType(
+    () =>
+      new AdapterType({
+        name: 'GbzBaseSyntenyAdapter',
+        configSchema: ConfigurationSchema(
+          'GbzBaseSyntenyAdapter',
+          {},
+          { explicitlyTyped: true },
+        ),
+        adapterCapabilities: ['getSubgraph', 'headerLanes'],
+        getAdapterClass: () => {
+          throw new Error('config-only')
+        },
+      }),
+  )
+  pluginManager.addTrackType(() => {
+    const schema = ConfigurationSchema(
+      'SyntenyTrack',
+      {},
+      {
+        baseConfiguration: createBaseTrackConfig(pluginManager),
+        explicitIdentifier: 'trackId',
+      },
+    )
+    return new TrackType({
+      name: 'SyntenyTrack',
+      configSchema: schema,
+      stateModel: createBaseTrackModel(pluginManager, 'SyntenyTrack', schema),
+    })
+  })
+  pluginManager.addDisplayType(() => laneDisplayType())
+  pluginManager.addViewType(
+    () =>
+      new ViewType({
+        name: 'LinearGenomeView',
+        stateModel: linearGenomeViewStateModelFactory(pluginManager),
+        ReactComponent: () => null,
+      }),
+  )
+  LaunchSubgraphMenuItemF(pluginManager)
+  LinearViewMenuItemsF(pluginManager)
+  pluginManager.createPluggableElements()
+  pluginManager.configure()
+
+  const track = pluginManager.pluggableConfigSchemaType('track').create(
+    {
+      type: 'SyntenyTrack',
+      trackId: 'gbz_lanes',
+      name: 'GBZ lanes',
+      assemblyNames: ['volvox', ...trackLanes],
+      adapter: { type: 'GbzBaseSyntenyAdapter' },
+      displays: [
+        {
+          type: 'MultiWaySyntenyDisplay',
+          displayId: 'gbz_lanes-MultiWaySyntenyDisplay',
+        },
+      ],
+    },
+    { pluginManager },
+  )
+  const assemblyRegions = [
+    { refName: 'ctgA', start: 0, end: 50_000, assemblyName: 'volvox' },
+  ]
+  const assembly = {
+    initialized: true,
+    regions: assemblyRegions,
+    getCanonicalRefName: (refName: string) => refName,
+    getGeneticCodeId: () => undefined,
+    getRegionForRefName: (refName: string) =>
+      assemblyRegions.find(r => r.refName === refName),
+    configuration: { sequence: undefined },
+  }
+  const LGV = pluginManager.getViewType('LinearGenomeView').stateModel
+  const Session = types
+    .model({
+      name: 'testSession',
+      view: types.maybe(LGV),
+      configuration: types.map(types.frozen()),
+    })
+    .volatile(() => ({
+      tracks: [track],
+      connectionInstances: [],
+      addedViews: [] as [string, Record<string, unknown>][],
+      rpcManager: { call: vi.fn() },
+      assemblyManager: {
+        get: (name: string) => (name === 'volvox' ? assembly : undefined),
+        waitForAssembly: () => Promise.resolve(assembly),
+        isValidRefName: (refName: string) => refName === 'ctgA',
+      },
+    }))
+    .views(self => ({
+      getTrackById: (id: string) => (id === 'gbz_lanes' ? track : undefined),
+      get assemblies() {
+        return []
+      },
+      get views() {
+        return self.view ? [self.view] : []
+      },
+      getDisplayTypeDefault() {
+        return undefined
+      },
+    }))
+    .actions(self => ({
+      setView(view: Instance<typeof LGV>) {
+        self.view = view
+        return view
+      },
+      addView(type: string, snapshot: Record<string, unknown>) {
+        self.addedViews.push([type, snapshot])
+        return snapshot
+      },
+      notify() {},
+      notifyError() {},
+    }))
+  const session = Session.create({ configuration: {} }, { pluginManager })
+  const view = session.setView(
+    LGV.create({
+      type: 'LinearGenomeView',
+      tracks: [
+        {
+          type: 'SyntenyTrack',
+          configuration: 'gbz_lanes',
+          displays: [
+            {
+              type: 'MultiWaySyntenyDisplay',
+              configuration: 'gbz_lanes-MultiWaySyntenyDisplay',
+            },
+          ],
+        },
+      ],
+    }),
+  )
+  view.setWidth(800)
+  view.setDisplayedRegions([
+    { refName: 'ctgA', start: 0, end: 1000, assemblyName: 'volvox' },
+  ])
+  const display = view.tracks[0]!.displays[0]!
+  return { session, view, display }
+}
+
+function allLabels(items: MenuItem[]): string[] {
+  return items.flatMap(item => [
+    ...('label' in item ? [item.label] : []),
+    ...('subMenu' in item && Array.isArray(item.subMenu)
+      ? allLabels(item.subMenu)
+      : []),
+  ])
+}
+
+function launchRegion(view: { menuItems: () => MenuItem[] }) {
+  const launch = view
+    .menuItems()
+    .find(i => 'label' in i && i.label === LAUNCH_LABEL)
+  const item =
+    launch && 'subMenu' in launch
+      ? launch.subMenu.find(i => 'label' in i && i.label === LABEL)
+      : undefined
+  if (item && 'onClick' in item) {
+    item.onClick(undefined)
+  } else {
+    throw new Error(`no ${LABEL} in the view menu`)
+  }
+}
+
+// pangenome_hprc_part3 sends readers to the linear view's menu for this, since
+// the lane track's own menu is core's and carries no graph launch.
+test("the GBZ cut is on the linear view's menu, not the lane track's", () => {
+  const { view, display } = createEnv()
+  expect(allLabels(view.menuItems())).toContain(LABEL)
+  expect(allLabels(display.trackMenuItems())).not.toContain(LABEL)
+})
+
+test("a launch cuts for the lanes the reader picked over the track's lanes", () => {
+  const { session, view, display } = createEnv(['HG00097.1', 'HG00099.1'])
+  display.setSelectedLanes(['HG00128.1'])
+  launchRegion(view)
+  expect(session.addedViews[0]![1].subgraphHaplotypes).toEqual(['HG00128.1'])
+})
+
+test('a launch cuts for the pick where the track names no lanes', () => {
+  const { session, view, display } = createEnv()
+  display.setSelectedLanes(['HG00128.1'])
+  launchRegion(view)
+  expect(session.addedViews[0]![1].subgraphHaplotypes).toEqual(['HG00128.1'])
+})
+
+test('a lane hidden on the track is left out of the cut', () => {
+  const { session, view, display } = createEnv(['HG00097.1', 'HG00099.1'])
+  display.hideLane('HG00097.1')
+  launchRegion(view)
+  expect(session.addedViews[0]![1].subgraphHaplotypes).toEqual(['HG00099.1'])
+})
+
+test("with no pick a launch cuts for the track's lanes", () => {
+  const { session, view } = createEnv(['HG00097.1', 'HG00099.1'])
+  launchRegion(view)
+  expect(session.addedViews[0]![1].subgraphHaplotypes).toEqual([
+    'HG00097.1',
+    'HG00099.1',
+  ])
+})

package/src/launchSubgraph/subgraphMenuItems.ts

@@ -0,0 +1,73 @@
+import BubbleChartIcon from '@mui/icons-material/BubbleChart'
+
+import { launchSubgraphView, subgraphRegionProblem } from './launchSubgraphView'
+import { offReferenceProblem } from './subgraphTracks'
+
+import type {
+  SubgraphLaunchSession,
+  SubgraphRegion,
+} from './launchSubgraphView'
+import type { SubgraphTrack } from './subgraphTracks'
+import type { MenuItem } from '@jbrowse/core/ui'
+
+// Menu items that cut `region` out of each graph track that can supply it.
+//
+// One capable track is the common case and gets a single flat item — a submenu
+// of one is a needless extra click. Several become a submenu naming each track,
+// since which graph the subgraph comes from is then a real choice.
+//
+// A region a track can't be cut at, past the cap or off the graph's reference,
+// yields a *disabled* item rather than none: an item that vanishes teaches the
+// user nothing, while one greyed out with the reason in its tooltip says what
+// to do about it.
+export function subgraphMenuItems({
+  label,
+  region,
+  tracks,
+  session,
+  connectedViewId,
+}: {
+  label: string
+  region: SubgraphRegion | undefined
+  tracks: SubgraphTrack[]
+  session: SubgraphLaunchSession
+  connectedViewId?: string
+}): MenuItem[] {
+  let items: MenuItem[] = []
+  if (region && tracks.length > 0) {
+    const sizeProblem = subgraphRegionProblem(region)
+    const entry = (track: SubgraphTrack) => {
+      const problem =
+        offReferenceProblem(track.referenceAssembly, region.assemblyName) ??
+        sizeProblem
+      return {
+        disabled: problem !== undefined,
+        disabledHelpText: problem,
+        onClick: () => {
+          launchSubgraphView({
+            session,
+            region,
+            trackId: track.trackId,
+            connectedViewId,
+            haplotypes: track.haplotypes,
+          })
+        },
+      }
+    }
+    items =
+      tracks.length === 1
+        ? [{ label, icon: BubbleChartIcon, ...entry(tracks[0]!) }]
+        : [
+            {
+              label,
+              icon: BubbleChartIcon,
+              type: 'subMenu',
+              subMenu: tracks.map(track => ({
+                label: track.name,
+                ...entry(track),
+              })),
+            },
+          ]
+  }
+  return items
+}