jbrowse-plugin-msaview 3.4.1 → 3.6.0

package/dist/MsaViewPanel/model.js

@@ -6,12 +6,17 @@ import { autorun } from 'mobx';
 import { MSAModelF } from 'react-msaview';
 import { autoLoadProteinDomains, launchBlastIfNeeded, launchOrthologsIfNeeded, loadStoredData, observeProteinHighlights, processInit, runCleanup, storeDataToIndexedDB, syncGenomeHoverToMsaColumn, } from './afterCreateAutoruns';
 import { msaCoordToGenomeCoord, msaCoordToGenomeRegions, } from './msaCoordToGenomeCoord';
+import { deleteMsaData } from './msaDataStore';
+import { resolveConnectedTranscriptIfNeeded } from './resolveConnectedTranscript';
 /**
- * Where the ortholog set comes from. NCBI's sets cover vertebrates and
+ * Where the homolog set comes from. NCBI's ortholog sets cover vertebrates and
  * insects; PANTHER's span its 144 reference proteomes, human to yeast to
- * Arabidopsis, so a gene from outside NCBI's scope aligns only through it.
+ * Arabidopsis; a UniRef cluster is every UniProtKB entry within 50% (or 90%)
+ * identity of the query, one per species, from any organism at all -- and the
+ * one source of the three whose rows need no ortholog call, only UniProt's
+ * REST api (see utils/unirefHomologs.ts).
  */
-export const orthologSources = ['ncbi', 'panther'];
+export const orthologSources = ['ncbi', 'panther', 'uniref'];
 /**
  * #stateModel MsaViewPlugin
  * extends
@@ -28,6 +33,14 @@ export default function stateModelFactory() {
          * #property
          */
         connectedFeature: types.frozen(),
+        /**
+         * #property
+         * the short form of `connectedFeature`: a transcript id (NM_000546.6)
+         * looked up in the connected genome view's tracks at launch, so a
+         * session spec can name the transcript instead of carrying its whole
+         * exon model. Resolved once into `connectedFeature` and left in place.
+         */
+        connectedTranscript: types.maybe(types.string),
         /**
          * #property
          */
@@ -45,6 +58,17 @@ export default function stateModelFactory() {
         // error-pages the whole app rather than just this view. Restore
         // stripDefault once a release ships it.
         querySeqName: 'QUERY',
+        /**
+         * #property
+         * transcript residues before the query row's first residue, so a
+         * transcript position is a row position plus this. A pasted alignment
+         * often carries only the aligned region of the query -- BLAST reports
+         * what it aligned -- and mapping that row's first residue to the
+         * transcript's first residue put every click off by the trimmed
+         * amount. Negative when the row runs past the transcript's start.
+         */
+        // see querySeqName above re: types.stripDefault
+        querySeqOffset: 0,
         /**
          * #property
          */
@@ -62,6 +86,23 @@ export default function stateModelFactory() {
          * #property
          */
         dataStoreId: types.maybe(types.string),
+        /**
+         * #property
+         * whether the request above has already produced this view's alignment.
+         *
+         * The params used to be cleared to mark that, which threw away the only
+         * statement of what the view is: browser storage expires an alignment
+         * after 7 days, and the view could then only tell the user to start
+         * over from the gene. A flag says the same thing and duplicates
+         * nothing, where a kept copy of the request put a second protein
+         * sequence and a second exon model in every saved session.
+         *
+         * A snapshot property rather than a volatile, because the case it
+         * exists for is by construction a later session: expiry is discovered
+         * by `loadStoredData` on restore, and a volatile would be false there
+         * and refire the whole search unasked.
+         */
+        launchCompleted: false,
         /**
          * #property
          */
@@ -76,10 +117,6 @@ export default function stateModelFactory() {
          * #volatile
          */
         progress: '',
-        /**
-         * #volatile
-         */
-        error: undefined,
         /**
          * #volatile
          */
@@ -109,20 +146,6 @@ export default function stateModelFactory() {
          * when NCBI returns no domains (leaving the annotation list empty)
          */
         domainsRequested: false,
-    }))
-        .views(self => ({
-        /**
-         * #method
-         */
-        getRowByName(rowName) {
-            return self.rows.find(r => r[0] === rowName);
-        },
-        /**
-         * #method
-         */
-        getSequenceByRowName(rowName) {
-            return this.getRowByName(rowName)?.[1];
-        },
     }))
         .views(self => ({
         /**
@@ -176,6 +199,26 @@ export default function stateModelFactory() {
                 ...this.connectedClickHighlights,
             ];
         },
+    }))
+        .views(self => ({
+        /**
+         * #getter
+         * overrides base
+         *
+         * react-msaview drops any snapshot document over 50kb and warns that a
+         * link to the view opens without it. True for an alignment this browser
+         * is holding in IndexedDB; wrong for an indexed view, whose kept `init`
+         * names a bgzip block over HTTP that processInit refetches wherever the
+         * session is opened -- so that one showed "Not in the link" about an
+         * alignment the link does carry.
+         */
+        get hostRestoresData() {
+            const { msaIndexedLocation, msaName } = self.init ?? {};
+            // `hostCarriesData` first: it is the base answer, the volatile a simple
+            // host flips, and overriding the getter without it threw that switch
+            // away for every view this one does not speak for
+            return self.hostCarriesData || !!(msaIndexedLocation && msaName);
+        },
     }))
         .actions(self => ({
         /**
@@ -184,12 +227,6 @@ export default function stateModelFactory() {
         setZoomToBaseLevel(arg) {
             self.zoomToBaseLevel = arg;
         },
-        /**
-         * #action
-         */
-        setError(e) {
-            self.error = e;
-        },
         /**
          * #action
          */
@@ -208,6 +245,12 @@ export default function stateModelFactory() {
         setBlastParams(args) {
             self.blastParams = args;
         },
+        /**
+         * #action
+         */
+        setConnectedFeature(arg) {
+            self.connectedFeature = arg;
+        },
         /**
          * #action
          */
@@ -226,6 +269,12 @@ export default function stateModelFactory() {
         setQuerySeqName(arg) {
             self.querySeqName = arg;
         },
+        /**
+         * #action
+         */
+        setQuerySeqOffset(arg) {
+            self.querySeqOffset = arg;
+        },
         /**
          * #action
          */
@@ -238,6 +287,12 @@ export default function stateModelFactory() {
         setDataStoreId(arg) {
             self.dataStoreId = arg;
         },
+        /**
+         * #action
+         */
+        setLaunchCompleted(arg) {
+            self.launchCompleted = arg;
+        },
         /**
          * #action
          */
@@ -270,21 +325,51 @@ export default function stateModelFactory() {
         },
         /**
          * #action
-         * Abandon the launch in flight. The EBI job keeps running on their side —
-         * nothing here can recall it, and its JobLink stays valid — so this only
-         * stops the polling and the writes it would make. Dropping the params is
-         * what keeps the request from refiring; the view falls back to the import
-         * form, which is where react-msaview's own cancel leaves it too.
+         * Abandon the launch, in flight or failed. The EBI job keeps running on
+         * their side — nothing here can recall it, and its JobLink stays valid —
+         * so this only stops the polling and the writes it would make. Dropping
+         * the request (the params, or the init) is what keeps it from refiring on
+         * the next reload; the view falls back to the import form, which is where
+         * react-msaview's own cancel leaves it too.
          */
         cancelLaunch() {
             self.launchController?.abort();
             self.launchController = undefined;
             self.blastParams = undefined;
             self.orthologParams = undefined;
+            self.init = undefined;
+            self.launchCompleted = false;
             self.progress = '';
             self.rid = undefined;
             self.error = undefined;
         },
+        /**
+         * #action
+         * Run the request again. The request IS the params, so re-stating them is
+         * the whole retry: each is a frozen property, and a fresh object is a
+         * change the launch autoruns wake on.
+         *
+         * A launch that already succeeded keeps its params and is marked
+         * `launchCompleted`, so clearing that mark is the whole retry for a view
+         * whose stored alignment expired.
+         */
+        retryLaunch() {
+            self.launchController?.abort();
+            self.launchController = undefined;
+            self.progress = '';
+            self.rid = undefined;
+            self.error = undefined;
+            self.launchCompleted = false;
+            if (self.blastParams) {
+                self.blastParams = { ...self.blastParams };
+            }
+            if (self.orthologParams) {
+                self.orthologParams = { ...self.orthologParams };
+            }
+            if (self.init) {
+                self.init = { ...self.init };
+            }
+        },
         /**
          * #action
          */
@@ -325,23 +410,63 @@ export default function stateModelFactory() {
             },
         };
     })
-        .views(self => ({
-        /**
-         * #method
-         */
-        extraViewMenuItems() {
-            return [
-                {
-                    label: 'Zoom to base level on click?',
-                    checked: self.zoomToBaseLevel,
-                    type: 'checkbox',
-                    onClick: () => {
-                        self.setZoomToBaseLevel(!self.zoomToBaseLevel);
+        .actions(self => {
+        const superReset = self.reset.bind(self);
+        return {
+            /**
+             * #action
+             * overrides base
+             *
+             * react-msaview's reset applies a snapshot filtered to its own
+             * `preservedOnReset` list, and a downstream property is never on it:
+             * returning to the import form dropped the view's name, un-minimized
+             * it, and forgot the zoom-on-click preference. The volatiles fail the
+             * other way -- applySnapshot cannot reach them, so the last file's
+             * state carried into the next one and the domain auto-load, which fires
+             * once per view, never fired again.
+             */
+            reset() {
+                const { displayName, minimized, zoomToBaseLevel, dataStoreId } = self;
+                superReset();
+                if (displayName !== undefined) {
+                    self.setDisplayName(displayName);
+                }
+                self.setMinimized(minimized);
+                self.setZoomToBaseLevel(zoomToBaseLevel);
+                self.setDomainsRequested(false);
+                self.setLastStoredData(undefined);
+                if (dataStoreId) {
+                    // nothing points at that row now
+                    void deleteMsaData(dataStoreId);
+                }
+            },
+        };
+    })
+        .views(self => {
+        // react-msaview's extraViewMenuItems() has had no caller since v5.6.0, in
+        // that package or in JBrowse; the view hamburger renders menuItems(), so
+        // extend that
+        const superMenuItems = self.menuItems.bind(self);
+        return {
+            /**
+             * #method
+             * overrides base
+             */
+            menuItems() {
+                return [
+                    ...superMenuItems(),
+                    {
+                        label: 'Zoom to base level on click?',
+                        type: 'checkbox',
+                        checked: self.zoomToBaseLevel,
+                        onClick: () => {
+                            self.setZoomToBaseLevel(!self.zoomToBaseLevel);
+                        },
                     },
-                },
-            ];
-        },
-    }))
+                ];
+            },
+        };
+    })
         .actions(self => ({
         afterCreate() {
             runCleanup();
@@ -354,6 +479,7 @@ export default function stateModelFactory() {
             for (const fn of [
                 loadStoredData,
                 storeDataToIndexedDB,
+                resolveConnectedTranscriptIfNeeded,
                 launchBlastIfNeeded,
                 launchOrthologsIfNeeded,
                 processInit,

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

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

package/dist/MsaViewPanel/model.test.js

@@ -0,0 +1,166 @@
+import { beforeEach, describe, expect, test, vi } from 'vitest';
+import { doLaunchBlast } from './doLaunchBlast';
+import stateModelFactory from './model';
+import { deleteMsaData } from './msaDataStore';
+// the launch autoruns are live on a real model, and a blastParams write is what
+// wakes them -- so the search is mocked rather than sent to EBI. The session is
+// mocked for the same reason: the hover and highlight autoruns reach for one on
+// every change, and there is no session around a bare model.
+vi.mock('@jbrowse/core/util', async (importOriginal) => ({
+    ...(await importOriginal()),
+    getSession: () => ({ views: [], hovered: undefined }),
+}));
+vi.mock('./doLaunchBlast', () => ({ doLaunchBlast: vi.fn() }));
+vi.mock('./msaDataStore', () => ({
+    cleanupOldData: vi.fn(async () => { }),
+    deleteMsaData: vi.fn(async () => { }),
+    generateDataStoreId: vi.fn(),
+    retrieveMsaData: vi.fn(),
+    storeMsaData: vi.fn(),
+}));
+const BLAST_PARAMS = {
+    searchProgram: 'blastp',
+    blastDatabase: 'uniprotkb_swissprot',
+    msaAlgorithm: 'clustalo',
+    proteinSequence: 'MKV',
+};
+beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(doLaunchBlast).mockReturnValue(new Promise(() => { }));
+});
+function view() {
+    return stateModelFactory().create({ type: 'MsaView', id: 'msaview1' });
+}
+// The item lived in extraViewMenuItems(), which react-msaview stopped calling
+// in v5.6.0 and is deleting: the view hamburger renders menuItems(), so a
+// checkbox nobody can reach is a feature that silently left.
+describe('view menu', () => {
+    test('offers the zoom-to-base-level toggle', () => {
+        expect(view()
+            .menuItems()
+            .map(f => ('label' in f ? f.label : ''))).toContain('Zoom to base level on click?');
+    });
+    test('the toggle drives zoomToBaseLevel', () => {
+        const model = view();
+        const item = model.menuItems().at(-1);
+        expect(item.checked).toBe(false);
+        item.onClick();
+        expect(model.zoomToBaseLevel).toBe(true);
+    });
+});
+// the params ARE the request, and they outlive the failure: a view that only
+// drew the error resubmitted the job on every reload and offered no way out
+describe('a failed launch', () => {
+    test('retries by re-stating the request', () => {
+        const model = view();
+        model.setBlastParams({ ...BLAST_PARAMS });
+        expect(doLaunchBlast).toHaveBeenCalledTimes(1);
+        model.setError(new Error('EBI said no'));
+        model.retryLaunch();
+        expect(model.error).toBeUndefined();
+        expect(model.blastParams).toEqual(BLAST_PARAMS);
+        expect(doLaunchBlast).toHaveBeenCalledTimes(2);
+    });
+    // the params used to be cleared on success to mark the request done, which
+    // threw away the only durable statement of what the view is: a stored
+    // alignment expires after 7 days and there was nothing left to run again
+    test('a successful launch keeps its request and is not run twice', async () => {
+        vi.mocked(doLaunchBlast).mockResolvedValue({
+            msa: '>a\nMK\n>b\nMK',
+            tree: '(a,b);',
+            treeMetadata: '{}',
+        });
+        const model = view();
+        model.setBlastParams({ ...BLAST_PARAMS });
+        await new Promise(res => setTimeout(res, 0));
+        expect(model.blastParams).toEqual(BLAST_PARAMS);
+        expect(model.launchCompleted).toBe(true);
+        expect(doLaunchBlast).toHaveBeenCalledTimes(1);
+        vi.mocked(doLaunchBlast).mockReturnValue(new Promise(() => { }));
+        model.setError(new Error('alignment is no longer in browser storage'));
+        model.retryLaunch();
+        expect(model.error).toBeUndefined();
+        expect(model.launchCompleted).toBe(false);
+        expect(doLaunchBlast).toHaveBeenCalledTimes(2);
+    });
+    // a session reopens with the request still on it, so the mark is what stops
+    // the whole search running again unasked
+    test('a restored session does not rerun a request it already ran', () => {
+        stateModelFactory().create({
+            type: 'MsaView',
+            id: 'msaview2',
+            blastParams: { ...BLAST_PARAMS },
+            launchCompleted: true,
+        });
+        expect(doLaunchBlast).not.toHaveBeenCalled();
+    });
+    test('dismisses by dropping it', () => {
+        const model = view();
+        model.setBlastParams({ ...BLAST_PARAMS });
+        model.setError(new Error('EBI said no'));
+        model.cancelLaunch();
+        expect(model.blastParams).toBeUndefined();
+        expect(model.error).toBeUndefined();
+    });
+});
+// react-msaview drops a snapshot document past 50kb and reports it through
+// `unshareableData`, which the header renders as "Not in the link". An indexed
+// view's alignment IS in the link -- its init names the block and processInit
+// refetches it -- so that view answers the question itself.
+describe('what the snapshot cannot carry', () => {
+    const big = `>a\n${'M'.repeat(60_000)}`;
+    test('an indexed view says the host brings its alignment back', () => {
+        const model = view();
+        model.setInit({
+            msaIndexedLocation: { uri: 'msa.fa.gz' },
+            msaName: 'ENST1',
+        });
+        model.setMSA(big);
+        expect(model.hostRestoresData).toBe(true);
+        expect(model.unshareableData).toEqual([]);
+    });
+    // the base getter reads a volatile a host flips to say it brings the data
+    // back by its own means; overriding without it threw that switch away
+    test('a host that says it carries the data is still believed', () => {
+        const model = view();
+        model.setMSA(big);
+        expect(model.unshareableData).not.toEqual([]);
+        model.setHostCarriesData(true);
+        expect(model.hostRestoresData).toBe(true);
+        expect(model.unshareableData).toEqual([]);
+    });
+    test('a pasted alignment is reported, because a link really does lose it', () => {
+        const model = view();
+        model.setMSA(big);
+        expect(model.hostRestoresData).toBe(false);
+        expect(model.unshareableData.map(d => d.what)).toEqual(['alignment']);
+    });
+});
+// react-msaview's reset keeps only what is on its own preservedOnReset list,
+// and a downstream property is never on it; its volatiles survive instead,
+// which is the direction that carries the last file's state into the next one
+describe('returning to the import form', () => {
+    test('keeps what is about the view, not about the file', () => {
+        const model = view();
+        model.setDisplayName('BLAST - TP53');
+        model.setMinimized(true);
+        model.setZoomToBaseLevel(true);
+        model.setMSA('>a\nMK');
+        model.reset();
+        expect(model.displayName).toBe('BLAST - TP53');
+        expect(model.minimized).toBe(true);
+        expect(model.zoomToBaseLevel).toBe(true);
+        expect(model.dataInitialized).toBe(false);
+    });
+    test('clears the volatiles applySnapshot cannot reach, and the stored row', () => {
+        const model = view();
+        model.setDomainsRequested(true);
+        model.setLastStoredData({ msa: '>a\nMK' });
+        model.setDataStoreId('msa-1');
+        model.reset();
+        expect(model.domainsRequested).toBe(false);
+        expect(model.lastStoredData).toBeUndefined();
+        expect(model.dataStoreId).toBeUndefined();
+        expect(deleteMsaData).toHaveBeenCalledWith('msa-1');
+    });
+});

package/dist/MsaViewPanel/msaCoordToGenomeCoord.d.ts

@@ -11,12 +11,23 @@ interface CoordModel {
         p2gCodon: Record<number, number[]>;
     } | undefined;
     mafRegion?: MafRegion;
-    rows: string[][];
+    /** transcript residues before the query row's first residue */
+    querySeqOffset?: number;
+    /**
+     * react-msaview's converter, which is the only thing that knows which columns
+     * are on screen. `rows` carries the whole gapped alignment, so counting
+     * residues along one of them answers for a column index the user cannot
+     * produce once `hideGaps` drops columns -- and it drops them as soon as a
+     * clade collapses or allowedGappyness falls below 100.
+     */
+    visibleColToSeqPos: (rowName: string, visibleCol: number) => number | undefined;
 }
 /**
  * The genome regions covered by MSA column `coord` of the query row, in 0-based
  * half-open coordinates (what bpToPx and navTo take).
  *
+ * `coord` is a VISIBLE column -- what mouseCol and mouseClickCol carry.
+ *
  * Usually one region -- one codon, or one base in a MAF alignment -- but a
  * codon split across an exon boundary yields one region per contiguous piece,
  * which is why this returns a list.

package/dist/MsaViewPanel/msaCoordToGenomeCoord.js

@@ -1,20 +1,17 @@
 import { getCodonRanges } from 'g2p_mapper';
-import { gappedToUngappedPosition } from './structureConnection';
 /**
  * The genome regions covered by MSA column `coord` of the query row, in 0-based
  * half-open coordinates (what bpToPx and navTo take).
  *
+ * `coord` is a VISIBLE column -- what mouseCol and mouseClickCol carry.
+ *
  * Usually one region -- one codon, or one base in a MAF alignment -- but a
  * codon split across an exon boundary yields one region per contiguous piece,
  * which is why this returns a list.
  */
 export function msaCoordToGenomeRegions({ model, coord: mouseCol, }) {
-    const { querySeqName, transcriptToMsaMap, mafRegion, rows } = model;
-    const querySeq = rows.find(f => f[0] === querySeqName)?.[1];
-    if (!querySeq) {
-        return [];
-    }
-    const ungappedPos = gappedToUngappedPosition(querySeq, mouseCol);
+    const { querySeqName, transcriptToMsaMap, mafRegion } = model;
+    const ungappedPos = model.visibleColToSeqPos(querySeqName, mouseCol);
     if (ungappedPos === undefined) {
         return [];
     }
@@ -26,13 +23,16 @@ export function msaCoordToGenomeRegions({ model, coord: mouseCol, }) {
     }
     if (transcriptToMsaMap) {
         const { refName, p2gCodon } = transcriptToMsaMap;
+        // the row is often only the aligned region of the transcript's protein, so
+        // its residues are the transcript's shifted by querySeqOffset
+        const proteinPos = ungappedPos + (model.querySeqOffset ?? 0);
         // p2gCodon holds every genomic base of the codon, so the range is exact on
         // either strand. Deriving it from consecutive p2g entries instead
         // (p2g[pos]..p2g[pos+1]) was off by one base on the reverse strand -- where
         // p2g stores the codon's *highest* coordinate -- dropped the final residue,
         // whose successor has no p2g entry, and spanned the whole intron for a
         // codon split across an exon boundary.
-        return (getCodonRanges(p2gCodon, ungappedPos)?.map(([start, end]) => ({
+        return (getCodonRanges(p2gCodon, proteinPos)?.map(([start, end]) => ({
             refName,
             start,
             end,