jbrowse-plugin-msaview 2.10.2 → 3.1.0

package/dist/MsaViewPanel/afterCreateAutoruns.js

@@ -121,14 +121,14 @@ export function launchBlastIfNeeded(self) {
  * Once an accession-bearing alignment is present (fresh from BLAST or restored
  * from cache), fetch NCBI CDD domains for those accessions and overlay them.
  * Runs once per view; the domainsRequested guard prevents refiring when NCBI
- * returns no domains (which leaves interProAnnotations undefined).
+ * returns no domains (which leaves the annotation list empty).
  */
 export function autoLoadProteinDomains(self) {
-    const { rows, domainsRequested, interProAnnotations } = self;
+    const { rows, domainsRequested, annotations } = self;
     const hasAccessions = self.data.treeMetadata?.includes('"Accession"') ?? false;
     if (rows.length > 0 &&
         hasAccessions &&
-        !interProAnnotations &&
+        annotations.length === 0 &&
         !domainsRequested) {
         self.setDomainsRequested(true);
         void (async () => {
@@ -212,60 +212,109 @@ export function syncGenomeHoverToMsaColumn(self) {
     };
 }
 /**
- * Mirror a connected 3D protein view's hovered residue onto the MSA's
- * highlighted columns. Returns the autorun body and keeps a flag tracking
- * whether the current highlight was set by THIS sync: when a protein hover ends
- * we restore the declarative highlightColumns seed (or clear) rather than
- * blindly wiping it.
+ * Translate genome regions published by a 3D protein view into this MSA's
+ * visible columns. The genome is the only coordinate space the two plugins
+ * share, so the hops are genome coord -> protein position (the transcript's g2p
+ * map) -> global alignment column -> visible column.
+ */
+function genomeHighlightsToVisibleColumns(self, field) {
+    const { connectedViewId, transcriptToMsaMap, querySeqName } = self;
+    if (!transcriptToMsaMap) {
+        return [];
+    }
+    const { g2p } = transcriptToMsaMap;
+    const columns = new Set();
+    for (const view of getProteinViews(getSession(self).views)) {
+        for (const structure of view.structures) {
+            if (structure.connectedViewId !== connectedViewId) {
+                continue;
+            }
+            for (const highlight of structure[field] ?? []) {
+                for (let coord = highlight.start; coord < highlight.end; coord++) {
+                    const proteinPos = g2p[coord];
+                    if (proteinPos !== undefined) {
+                        columns.add(self.seqPosToGlobalCol(querySeqName, proteinPos));
+                    }
+                }
+            }
+        }
+    }
+    return [...columns]
+        .map(col => self.globalColToVisibleCol(col))
+        .filter((col) => col !== undefined);
+}
+function sameColumns(a, b) {
+    if (!a || !b) {
+        return a === b;
+    }
+    return a.length === b.length && a.every((col, i) => col === b[i]);
+}
+/**
+ * Mirror a connected 3D protein view's highlights onto the MSA's highlighted
+ * columns, from either of the two channels protein3d publishes:
+ *
+ * - `hoverGenomeHighlights` — the residue under the pointer, transient.
+ * - `clickGenomeHighlights` — the domain the user clicked, persistent. Also
+ *   what protein3d's declarative `initialSelection` lights on load, so a session
+ *   spec that pre-selects a domain in the structure now lands in the alignment
+ *   too, instead of the caller having to author the same range a second time as
+ *   the MSA's own `highlightColumns`.
+ *
+ * Highest-priority non-empty source wins: a hover reads as a transient probe on
+ * top of the standing selection, and letting it win means moving the pointer
+ * over the structure previews a residue without destroying what was selected.
+ * Releasing the hover falls back to the click selection, then to the declarative
+ * `highlightColumns` seed.
  *
- * Without the flag this autorun fires once on creation — with the view connected
- * to a *genome* LGV but no 3D protein structure attached — computes zero columns,
- * and calls setHighlightedColumns(undefined), clobbering the seed that
- * MSAModelF.afterCreate just set from the declarative `highlightColumns`. That is
- * the bug that made the BRAF/TP53 genome-browser links open with no V600/R248
- * column lit (SRC has no highlightColumns, so nothing was there to wipe).
+ * Resolving the seed as the last rung of that stack is what replaced a
+ * `proteinDriven` flag this function used to carry. The flag existed because the
+ * body could not otherwise tell "no protein highlight, leave the seed alone"
+ * from "the protein highlight ended, restore the seed", and getting that wrong
+ * wiped the seed on the very first run — the bug that made the BRAF/TP53
+ * genome-browser links open with no V600/R248 column lit. Now every source is in
+ * one expression, so the result depends only on what the sources currently say
+ * and there is no ordering to get wrong.
+ *
+ * A closure remains, but it decides nothing: `written` only suppresses a
+ * redundant redraw. Delete it and the highlight is identical, just recomputed
+ * more often — where deleting the old flag changed which columns lit.
  */
 export function observeProteinHighlights(self) {
-    let proteinDriven = false;
+    // The columns this reaction last wrote, kept to skip a write that would not
+    // change anything: protein3d recomputes hoverGenomeHighlights on every mouse
+    // move over the structure, and moving within one codon yields a fresh array of
+    // the same columns, which would redraw the overlay canvas for nothing.
+    //
+    // Deliberately a closure rather than a read of `self.highlightedColumns` --
+    // reading it would put this reaction's own output in its dependency set, so
+    // every write would re-trigger it. It converges, but the dependencies should be
+    // the sources the highlight derives FROM, not the highlight itself.
+    let written;
     return () => {
-        const { connectedViewId, transcriptToMsaMap, querySeqName } = self;
+        const { connectedViewId, transcriptToMsaMap } = self;
         if (!connectedViewId || !transcriptToMsaMap) {
             return;
         }
-        const columns = new Set();
-        for (const view of getProteinViews(getSession(self).views)) {
-            for (const structure of view.structures) {
-                if (structure.connectedViewId !== connectedViewId) {
-                    continue;
-                }
-                const highlights = structure.hoverGenomeHighlights;
-                if (!highlights || highlights.length === 0) {
-                    continue;
-                }
-                const { g2p } = transcriptToMsaMap;
-                for (const highlight of highlights) {
-                    for (let coord = highlight.start; coord < highlight.end; coord++) {
-                        const proteinPos = g2p[coord];
-                        if (proteinPos !== undefined) {
-                            const col = self.seqPosToGlobalCol(querySeqName, proteinPos);
-                            columns.add(col);
-                        }
-                    }
-                }
-            }
-        }
-        const visibleColumns = Array.from(columns)
-            .map(col => self.globalColToVisibleCol(col))
-            .filter((col) => col !== undefined);
-        if (visibleColumns.length > 0) {
-            self.setHighlightedColumns(visibleColumns);
-            proteinDriven = true;
-        }
-        else if (proteinDriven) {
-            // our protein-hover highlight ended — fall back to the declarative seed
-            // instead of wiping a column the URL/user asked to keep lit
-            self.setHighlightedColumns(self.highlightColumns?.length ? self.highlightColumns : undefined);
-            proteinDriven = false;
+        const hover = genomeHighlightsToVisibleColumns(self, 'hoverGenomeHighlights');
+        // Skipping the click channel while hovering is worth the subtlety it costs:
+        // a hover recomputes on every mouse move, and a clicked domain can be
+        // hundreds of residues, so translating a selection that cannot win would
+        // walk thousands of genome coordinates per pointer move.
+        //
+        // The subtlety is that not reading clickGenomeHighlights leaves it out of
+        // this reaction's dependencies until the hover clears. Changing the
+        // selection mid-hover therefore does not re-run us -- which is harmless,
+        // because the hover would have outranked it anyway, and releasing the hover
+        // re-runs and picks up whatever the selection now says.
+        const click = hover.length
+            ? []
+            : genomeHighlightsToVisibleColumns(self, 'clickGenomeHighlights');
+        const seed = self.highlightColumns ?? [];
+        const winner = hover.length ? hover : click.length ? click : seed;
+        const next = winner.length > 0 ? winner : undefined;
+        if (!sameColumns(written, next)) {
+            written = next;
+            self.setHighlightedColumns(next);
         }
     };
 }

package/dist/MsaViewPanel/model.d.ts

@@ -552,7 +552,7 @@ export default function stateModelFactory(): import("@jbrowse/mobx-state-tree").
     conservationTrackHeight: number;
     marginLeft: number;
     error: unknown;
-    interProAnnotations: undefined | Record<string, import("react-msaview").InterProScanResults>;
+    annotations: import("msa-parsers").Annotation[];
 } & {
     drawRelativeTo(id: string | undefined): void;
     setHideGaps(arg: boolean): void;
@@ -571,7 +571,6 @@ export default function stateModelFactory(): import("@jbrowse/mobx-state-tree").
     setMouseClickPos(col?: number, row?: number): void;
     setRowHeight(n: number): void;
     setColWidth(n: number): void;
-    setScrollY(n: number): void;
     setCurrentAlignment(n: number): void;
     toggleCollapsed(node: string): void;
     setShowOnly(node?: string): void;
@@ -628,7 +627,6 @@ export default function stateModelFactory(): import("@jbrowse/mobx-state-tree").
     readonly msaAreaWidth: number;
     readonly treeAreaWidthMinusMargin: number;
     readonly blanks: number[];
-    readonly blanksSet: Set<number>;
     readonly insertionPositions: Map<string, {
         pos: number;
         letters: string;
@@ -641,7 +639,6 @@ export default function stateModelFactory(): import("@jbrowse/mobx-state-tree").
     readonly columns2d: string[];
     readonly fontSize: number;
     readonly colStats: import("react-msaview").ColumnCounts;
-    readonly colStatsSums: Uint32Array<ArrayBufferLike>;
     readonly sequenceType: "dna" | "rna" | "amino";
     readonly colConsensus: {
         letter: string;
@@ -684,7 +681,9 @@ export default function stateModelFactory(): import("@jbrowse/mobx-state-tree").
     zoomOut(): void;
     zoomToPos(scaleFactor: number, offsetX: number, offsetY: number): void;
     doScrollY(deltaY: number): void;
-    setDomains(data?: Record<string, import("react-msaview").InterProScanResults>): void;
+    setScrollY(n: number): void;
+    setAnnotations(annotations: import("msa-parsers").Annotation[]): void;
+    setDomains(data?: Record<string, import("msa-parsers").InterProScanResults>): void;
     applyGFFText(gffText: string): void;
     doScrollX(deltaX: number): void;
     setScrollX(n: number): void;
@@ -712,70 +711,16 @@ export default function stateModelFactory(): import("@jbrowse/mobx-state-tree").
 } & {
     readonly msaAreaHeight: number;
     readonly totalTrackAreaHeight: number;
-    readonly tidyInterProAnnotationTypes: Map<string, {
-        id: string;
-        name: string;
-        accession: string;
-        description: string;
-        featureType: string | undefined;
-        start: number;
-        end: number;
-        strand: number | undefined;
-    }>;
-    readonly tidyInterProAnnotations: {
-        id: string;
-        name: string;
-        accession: string;
-        description: string;
-        featureType: string | undefined;
-        start: number;
-        end: number;
-        strand: number | undefined;
-    }[];
-    readonly tidyFilteredInterProAnnotations: {
-        id: string;
-        name: string;
-        accession: string;
-        description: string;
-        featureType: string | undefined;
-        start: number;
-        end: number;
-        strand: number | undefined;
-    }[];
-    readonly tidyFilteredGatheredInterProAnnotations: Record<string, {
-        id: string;
-        name: string;
-        accession: string;
-        description: string;
-        featureType: string | undefined;
-        start: number;
-        end: number;
-        strand: number | undefined;
-    }[]>;
+    readonly annotationTypes: Map<string, import("msa-parsers").Annotation>;
+    readonly filteredAnnotations: import("msa-parsers").Annotation[];
+    readonly annotationsByRow: Record<string, import("msa-parsers").Annotation[]>;
 } & {
     readonly showVerticalScrollbar: boolean;
 } & {
     readonly verticalScrollbarWidth: 0 | 20;
-    readonly segmentDomainTypes: {
-        id: string;
-        name: string;
-        accession: string;
-        description: string;
-        featureType: string | undefined;
-        start: number;
-        end: number;
-        strand: number | undefined;
-    }[];
-    readonly categoricalDomainTypes: {
-        id: string;
-        name: string;
-        accession: string;
-        description: string;
-        featureType: string | undefined;
-        start: number;
-        end: number;
-        strand: number | undefined;
-    }[];
+    readonly msaCanvasWidth: number;
+    readonly segmentDomainTypes: import("msa-parsers").Annotation[];
+    readonly categoricalDomainTypes: import("msa-parsers").Annotation[];
     readonly fillPalette: {
         [x: string]: string;
     };
@@ -783,19 +728,10 @@ export default function stateModelFactory(): import("@jbrowse/mobx-state-tree").
         [k: string]: string;
     };
     readonly segmentLabels: Map<string, string>;
-    readonly visibleDomainTypes: {
-        id: string;
-        name: string;
-        accession: string;
-        description: string;
-        featureType: string | undefined;
-        start: number;
-        end: number;
-        strand: number | undefined;
-    }[];
+    readonly visibleDomainTypes: import("msa-parsers").Annotation[];
     readonly domainBands: Map<string, import("react-msaview").DomainBand[]>;
     readonly domainBandsByStart: Map<string, import("react-msaview").DomainBand[]>;
-    readonly mouseOverDomains: import("react-msaview").TidyDomainAnnotation[];
+    readonly mouseOverDomains: import("msa-parsers").Annotation[];
     readonly referenceRowIndex: number | undefined;
     readonly hoveredRowIndices: number[];
     readonly highlightedColumnRuns: {

package/dist/MsaViewPanel/model.js

@@ -85,7 +85,7 @@ export default function stateModelFactory() {
         /**
          * #volatile
          * guards the one-shot auto-fetch of protein domains so it doesn't refire
-         * when NCBI returns no domains (leaving interProAnnotations undefined)
+         * when NCBI returns no domains (leaving the annotation list empty)
          */
         domainsRequested: false,
     }))

package/dist/MsaViewPanel/observeProteinHighlights.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/MsaViewPanel/observeProteinHighlights.test.js

@@ -0,0 +1,209 @@
+import { getSession } from '@jbrowse/core/util';
+import { beforeEach, describe, expect, test, vi } from 'vitest';
+import { observeProteinHighlights } from './afterCreateAutoruns';
+// Mock only getSession; keep the rest of the util module real so the
+// afterCreateAutoruns import graph still loads.
+vi.mock('@jbrowse/core/util', async (importOriginal) => ({
+    ...(await importOriginal()),
+    getSession: vi.fn(),
+}));
+const mockGetSession = vi.mocked(getSession);
+const CONNECTED = 'lgv-1';
+/**
+ * A model with an identity genome->protein->column mapping, so an asserted
+ * column equals the genome coordinate that produced it and the test reads as
+ * "these genome coords lit these columns".
+ */
+function makeModel({ highlightColumns } = {}) {
+    const calls = [];
+    const model = {
+        querySeqName: 'query',
+        connectedViewId: CONNECTED,
+        // g2p is indexed by genome coord; identity keeps the arithmetic out of the way
+        transcriptToMsaMap: {
+            g2p: Object.fromEntries([...Array(200).keys()].map(i => [i, i])),
+        },
+        highlightColumns,
+        highlightedColumns: undefined,
+        seqPosToGlobalCol: (_name, pos) => pos,
+        globalColToVisibleCol: (col) => col,
+        setHighlightedColumns: (cols) => {
+            calls.push(cols);
+            model.highlightedColumns = cols;
+        },
+    };
+    return { model, calls };
+}
+/** publish highlight channels on a ProteinView structure in the session */
+function session({ hover, click, connectedViewId = CONNECTED, }) {
+    mockGetSession.mockReturnValue({
+        views: [
+            {
+                type: 'ProteinView',
+                id: 'pv-1',
+                structures: [
+                    {
+                        connectedViewId,
+                        hoverGenomeHighlights: hover,
+                        clickGenomeHighlights: click,
+                    },
+                ],
+            },
+        ],
+    });
+}
+function noProteinView() {
+    mockGetSession.mockReturnValue({
+        views: [{ type: 'LinearGenomeView', id: CONNECTED }],
+    });
+}
+beforeEach(() => {
+    vi.clearAllMocks();
+});
+describe('the hover channel', () => {
+    test('a hovered residue lights its column', () => {
+        const { model, calls } = makeModel();
+        const run = observeProteinHighlights(model);
+        session({ hover: [{ start: 10, end: 13 }] });
+        run();
+        expect(calls).toEqual([[10, 11, 12]]);
+    });
+    test('releasing the hover clears the highlight', () => {
+        const { model, calls } = makeModel();
+        const run = observeProteinHighlights(model);
+        session({ hover: [{ start: 10, end: 12 }] });
+        run();
+        session({ hover: [] });
+        run();
+        expect(calls).toEqual([[10, 11], undefined]);
+    });
+});
+describe('the click channel', () => {
+    test('a clicked domain lights its columns', () => {
+        const { model, calls } = makeModel();
+        const run = observeProteinHighlights(model);
+        session({ click: [{ start: 30, end: 34 }] });
+        run();
+        expect(calls).toEqual([[30, 31, 32, 33]]);
+    });
+    test('a hover wins over the standing click selection', () => {
+        const { model, calls } = makeModel();
+        const run = observeProteinHighlights(model);
+        session({ click: [{ start: 30, end: 32 }], hover: [{ start: 5, end: 6 }] });
+        run();
+        expect(calls).toEqual([[5]]);
+    });
+    test('a selection changed during a hover is picked up when the hover releases', () => {
+        const { model, calls } = makeModel();
+        const run = observeProteinHighlights(model);
+        // the reaction skips the click channel while hovering, so it is not watching
+        // it; this pins that releasing the hover still lands on the CURRENT selection
+        // rather than on the one that was standing when the hover began
+        session({ click: [{ start: 30, end: 32 }], hover: [{ start: 5, end: 6 }] });
+        run();
+        session({ click: [{ start: 60, end: 62 }], hover: [{ start: 5, end: 6 }] });
+        run();
+        session({ click: [{ start: 60, end: 62 }] });
+        run();
+        expect(calls).toEqual([[5], [60, 61]]);
+    });
+    test('releasing the hover falls back to the click selection, not to nothing', () => {
+        const { model, calls } = makeModel();
+        const run = observeProteinHighlights(model);
+        // this is the whole point of the two channels: previewing a residue must not
+        // destroy the domain the user selected
+        session({ click: [{ start: 30, end: 32 }] });
+        run();
+        session({ click: [{ start: 30, end: 32 }], hover: [{ start: 5, end: 6 }] });
+        run();
+        session({ click: [{ start: 30, end: 32 }] });
+        run();
+        expect(calls).toEqual([[30, 31], [5], [30, 31]]);
+    });
+});
+describe('the declarative highlightColumns seed', () => {
+    // the regression these guard: the observer used to compute zero columns on its
+    // first run and wipe the seed MSAModelF.afterCreate had just applied, which is
+    // what made the BRAF/TP53 links open with no V600/R248 column lit
+    test('a first run with no protein view leaves the seed alone', () => {
+        const { model, calls } = makeModel({ highlightColumns: [77] });
+        const run = observeProteinHighlights(model);
+        noProteinView();
+        run();
+        expect(calls).toEqual([[77]]);
+        expect(model.highlightedColumns).toEqual([77]);
+    });
+    test('repeated runs never clobber the seed', () => {
+        const { model } = makeModel({ highlightColumns: [77] });
+        const run = observeProteinHighlights(model);
+        noProteinView();
+        run();
+        run();
+        run();
+        expect(model.highlightedColumns).toEqual([77]);
+    });
+    test('a hover overrides the seed, and releasing it restores the seed', () => {
+        const { model, calls } = makeModel({ highlightColumns: [77] });
+        const run = observeProteinHighlights(model);
+        session({ hover: [{ start: 1, end: 2 }] });
+        run();
+        session({ hover: [] });
+        run();
+        expect(calls).toEqual([[1], [77]]);
+    });
+    test('a click selection outranks the seed', () => {
+        const { model, calls } = makeModel({ highlightColumns: [77] });
+        const run = observeProteinHighlights(model);
+        session({ click: [{ start: 40, end: 42 }] });
+        run();
+        expect(calls).toEqual([[40, 41]]);
+    });
+    test('with no seed and no protein highlight, nothing is written at all', () => {
+        const { model, calls } = makeModel();
+        const run = observeProteinHighlights(model);
+        noProteinView();
+        run();
+        run();
+        expect(calls).toEqual([]);
+    });
+});
+describe('scope and redundant writes', () => {
+    test('a structure connected to a different view is ignored', () => {
+        const { model, calls } = makeModel();
+        const run = observeProteinHighlights(model);
+        session({
+            hover: [{ start: 10, end: 12 }],
+            connectedViewId: 'some-other-view',
+        });
+        run();
+        expect(calls).toEqual([]);
+    });
+    test('an unchanged highlight is not rewritten, so the overlay does not redraw', () => {
+        const { model, calls } = makeModel();
+        const run = observeProteinHighlights(model);
+        session({ hover: [{ start: 10, end: 12 }] });
+        run();
+        run();
+        run();
+        expect(calls).toEqual([[10, 11]]);
+    });
+    test('a genome coord with no protein position contributes no column', () => {
+        const { model, calls } = makeModel();
+        const run = observeProteinHighlights(model);
+        // 500 is past the end of the identity g2p map built above
+        session({ hover: [{ start: 500, end: 503 }] });
+        run();
+        expect(calls).toEqual([]);
+    });
+    test('nothing happens until the view is connected and mapped', () => {
+        const { calls } = makeModel();
+        const bare = {
+            connectedViewId: undefined,
+            transcriptToMsaMap: undefined,
+        };
+        const run = observeProteinHighlights(bare);
+        session({ hover: [{ start: 10, end: 12 }] });
+        run();
+        expect(calls).toEqual([]);
+    });
+});

package/dist/MsaViewPanel/structureConnection.d.ts

@@ -3,10 +3,16 @@ export interface ProteinViewStructure {
     connectedViewId?: string;
     uniprotId?: string;
     structureSequences?: string[];
+    /** the residue under the pointer, transient */
     hoverGenomeHighlights?: {
         start: number;
         end: number;
     }[];
+    /** the clicked domain, persistent; also what `initialSelection` lights */
+    clickGenomeHighlights?: {
+        start: number;
+        end: number;
+    }[];
 }
 export interface ProteinView {
     type: 'ProteinView';