jbrowse-plugin-msaview 3.4.1 → 3.6.0

package/dist/MsaViewPanel/genomeToMSA.js

@@ -1,7 +1,7 @@
 import { getSession } from '@jbrowse/core/util';
-import { hasHoverPosition, hasQueryRow } from './util';
+import { hasHoverPosition, hasQueryRow, transcriptPosToVisibleCol, } from './util';
 export function genomeToMSA({ model }) {
-    const { hovered } = getSession(model);
+    const { assemblyManager, hovered } = getSession(model);
     const { querySeqName, transcriptToMsaMap, connectedView, mafRegion } = model;
     if (!connectedView?.initialized ||
         !hasHoverPosition(hovered) ||
@@ -12,8 +12,25 @@ export function genomeToMSA({ model }) {
     // hoverPosition.coord is a 1-based display coordinate (core's pxToBp adds the
     // +1), while g2p and mafRegion are keyed by 0-based genome position
     const genomePos = coord - 1;
+    // The two sides name the chromosome differently. A hover carries the
+    // assembly's canonical name -- `1` on jbrowse.org's hg38 -- while mafRegion
+    // and the transcript's g2p map carry the feature's, straight out of the
+    // annotation file, which is `chr1` in GENCODE. Compared raw they agree only
+    // where a config happens to pair files that agree, and everywhere else
+    // hovering a codon lit nothing at all, with no throw and no console line.
+    //
+    // `initialized` is the gate rather than a try/catch: getCanonicalRefName
+    // throws until the assembly's aliases load, and this runs from a hover
+    // autorun over an assembly nothing here waited for -- mafRegion names its own
+    // on a frozen spec, which need not be one the connected view loaded. Until
+    // the aliases arrive the raw name is the whole answer, and the hover lights
+    // nothing for those frames rather than throwing out of the autorun.
+    const assembly = assemblyManager.get(mafRegion?.assemblyName ?? connectedView.assemblyNames[0] ?? '');
+    const canonical = (name) => (assembly?.initialized ? assembly.getCanonicalRefName(name) : undefined) ??
+        name;
+    const hoveredRefName = canonical(refName);
     if (mafRegion) {
-        if (refName !== mafRegion.refName ||
+        if (hoveredRefName !== canonical(mafRegion.refName) ||
             !connectedView.assemblyNames.includes(mafRegion.assemblyName) ||
             genomePos < mafRegion.start ||
             genomePos >= mafRegion.end) {
@@ -25,10 +42,11 @@ export function genomeToMSA({ model }) {
     // was last over, on any assembly -- so the refName gate is load bearing:
     // without it the same numeric coordinate on an unrelated chromosome matches a
     // g2p key and lights up a column for a different locus
-    if (refName === transcriptToMsaMap?.refName) {
-        const seqPos = transcriptToMsaMap.g2p[genomePos];
-        if (seqPos !== undefined) {
-            return model.seqPosToVisibleCol(querySeqName, seqPos);
+    if (transcriptToMsaMap &&
+        hoveredRefName === canonical(transcriptToMsaMap.refName)) {
+        const proteinPos = transcriptToMsaMap.g2p[genomePos];
+        if (proteinPos !== undefined) {
+            return transcriptPosToVisibleCol(model, proteinPos);
         }
     }
     return undefined;

package/dist/MsaViewPanel/genomeToMSA.test.js

@@ -6,12 +6,40 @@ vi.mock('@jbrowse/core/util', () => ({
     getSession: vi.fn(),
 }));
 const mockGetSession = vi.mocked(getSession);
+// What the assembly calls each chromosome. Empty means every name is already
+// canonical, which is the config where the raw comparison this replaced
+// happened to work.
+let aliases = {};
+// core's assembly throws from getCanonicalRefName until its aliases load, and
+// answers `initialized` false until then -- so the stand-in throws too, or the
+// guard is asserted against a method that never had the failure mode
+let assemblyInitialized = true;
+function mockSession(session) {
+    mockGetSession.mockReturnValue({
+        assemblyManager: {
+            get: () => ({
+                get initialized() {
+                    return assemblyInitialized;
+                },
+                getCanonicalRefName: (refName) => {
+                    if (!assemblyInitialized) {
+                        throw new Error('aliases not loaded');
+                    }
+                    return aliases[refName] ?? refName;
+                },
+            }),
+        },
+        ...session,
+    });
+}
 describe('genomeToMSA', () => {
     beforeEach(() => {
         vi.clearAllMocks();
+        aliases = {};
+        assemblyInitialized = true;
     });
     test('returns undefined when connectedView is not initialized', () => {
-        mockGetSession.mockReturnValue({
+        mockSession({
             hovered: {
                 hoverFeature: {},
                 hoverPosition: { coord: 1005, refName: 'chr1' },
@@ -27,14 +55,14 @@ describe('genomeToMSA', () => {
                 end: 1010,
                 assemblyName: 'hg38',
             },
-            connectedView: { initialized: false },
+            connectedView: { initialized: false, assemblyNames: ['hg38'] },
             seqPosToVisibleCol: vi.fn(),
         };
         const result = genomeToMSA({ model });
         expect(result).toBeUndefined();
     });
     test('returns undefined when hovered is not valid', () => {
-        mockGetSession.mockReturnValue({
+        mockSession({
             hovered: null,
         });
         const model = {
@@ -47,7 +75,7 @@ describe('genomeToMSA', () => {
                 end: 1010,
                 assemblyName: 'hg38',
             },
-            connectedView: { initialized: true },
+            connectedView: { initialized: true, assemblyNames: ['hg38'] },
             seqPosToVisibleCol: vi.fn(),
         };
         const result = genomeToMSA({ model });
@@ -55,7 +83,7 @@ describe('genomeToMSA', () => {
     });
     describe('mafRegion mapping', () => {
         test('returns visible column for valid hover within mafRegion', () => {
-            mockGetSession.mockReturnValue({
+            mockSession({
                 hovered: {
                     hoverFeature: {},
                     hoverPosition: { coord: 1005, refName: 'chr1' },
@@ -85,7 +113,7 @@ describe('genomeToMSA', () => {
             expect(result).toBe(5);
         });
         test('returns undefined when hover refName does not match mafRegion', () => {
-            mockGetSession.mockReturnValue({
+            mockSession({
                 hovered: {
                     hoverFeature: {},
                     hoverPosition: { coord: 1005, refName: 'chr2' },
@@ -112,7 +140,7 @@ describe('genomeToMSA', () => {
         });
         test('returns undefined when hover coord is before mafRegion start', () => {
             // 1-based coord 1000 is the 0-based base 999, one before the region
-            mockGetSession.mockReturnValue({
+            mockSession({
                 hovered: {
                     hoverFeature: {},
                     hoverPosition: { coord: 1000, refName: 'chr1' },
@@ -139,7 +167,7 @@ describe('genomeToMSA', () => {
         });
         test('returns undefined when hover coord is at or after mafRegion end', () => {
             // 1-based coord 1011 is the 0-based base 1010, one past the region
-            mockGetSession.mockReturnValue({
+            mockSession({
                 hovered: {
                     hoverFeature: {},
                     hoverPosition: { coord: 1011, refName: 'chr1' },
@@ -165,7 +193,7 @@ describe('genomeToMSA', () => {
             expect(result).toBeUndefined();
         });
         test('returns undefined when assembly does not match', () => {
-            mockGetSession.mockReturnValue({
+            mockSession({
                 hovered: {
                     hoverFeature: {},
                     hoverPosition: { coord: 1005, refName: 'chr1' },
@@ -193,7 +221,7 @@ describe('genomeToMSA', () => {
     });
     describe('transcriptToMsaMap mapping (original behavior)', () => {
         test('returns visible column using g2p mapping', () => {
-            mockGetSession.mockReturnValue({
+            mockSession({
                 hovered: {
                     hoverFeature: {},
                     hoverPosition: { coord: 1005, refName: 'chr1' },
@@ -202,6 +230,7 @@ describe('genomeToMSA', () => {
             const mockSeqPosToVisibleCol = vi.fn().mockReturnValue(10);
             const model = {
                 querySeqName: 'QUERY',
+                querySeqOffset: 0,
                 rows: [['QUERY', 'MKVLTAEEK']],
                 transcriptToMsaMap: {
                     refName: 'chr1',
@@ -209,8 +238,9 @@ describe('genomeToMSA', () => {
                     g2p: { 1004: 10 },
                 },
                 mafRegion: undefined,
-                connectedView: { initialized: true },
+                connectedView: { initialized: true, assemblyNames: ['hg38'] },
                 seqPosToVisibleCol: mockSeqPosToVisibleCol,
+                visibleColToSeqPos: (_name, col) => col,
             };
             const result = genomeToMSA({ model });
             expect(mockSeqPosToVisibleCol).toHaveBeenCalledWith('QUERY', 10);
@@ -219,7 +249,7 @@ describe('genomeToMSA', () => {
         test('returns undefined when the hover is on another refName', () => {
             // session.hovered is global, so a hover on an unrelated chromosome can
             // carry a coordinate that happens to be a g2p key
-            mockGetSession.mockReturnValue({
+            mockSession({
                 hovered: {
                     hoverFeature: {},
                     hoverPosition: { coord: 1005, refName: 'chr2' },
@@ -234,14 +264,79 @@ describe('genomeToMSA', () => {
                     g2p: { 1004: 10 },
                 },
                 mafRegion: undefined,
-                connectedView: { initialized: true },
+                connectedView: { initialized: true, assemblyNames: ['hg38'] },
                 seqPosToVisibleCol: mockSeqPosToVisibleCol,
             };
             expect(genomeToMSA({ model })).toBeUndefined();
             expect(mockSeqPosToVisibleCol).not.toHaveBeenCalled();
         });
+        // a pasted alignment often carries only the region BLAST aligned, and
+        // querySeqOffset says how much of the protein comes before it
+        test('shifts a trimmed query row by querySeqOffset', () => {
+            mockSession({
+                hovered: {
+                    hoverFeature: {},
+                    hoverPosition: { coord: 1005, refName: 'chr1' },
+                },
+            });
+            const seqPosToVisibleCol = vi.fn((_name, pos) => pos);
+            const model = {
+                querySeqName: 'QUERY',
+                querySeqOffset: 4,
+                rows: [['QUERY', 'MKVLTAEEK']],
+                transcriptToMsaMap: { refName: 'chr1', g2p: { 1004: 10 } },
+                mafRegion: undefined,
+                connectedView: { initialized: true, assemblyNames: ['hg38'] },
+                seqPosToVisibleCol,
+                visibleColToSeqPos: (_name, col) => col,
+            };
+            expect(genomeToMSA({ model })).toBe(6);
+            expect(seqPosToVisibleCol).toHaveBeenCalledWith('QUERY', 6);
+        });
+        test('maps nothing for a residue before the trimmed row starts', () => {
+            mockSession({
+                hovered: {
+                    hoverFeature: {},
+                    hoverPosition: { coord: 1005, refName: 'chr1' },
+                },
+            });
+            const seqPosToVisibleCol = vi.fn((_name, pos) => pos);
+            const model = {
+                querySeqName: 'QUERY',
+                querySeqOffset: 20,
+                rows: [['QUERY', 'MKVLTAEEK']],
+                transcriptToMsaMap: { refName: 'chr1', g2p: { 1004: 10 } },
+                mafRegion: undefined,
+                connectedView: { initialized: true, assemblyNames: ['hg38'] },
+                seqPosToVisibleCol,
+                visibleColToSeqPos: (_name, col) => col,
+            };
+            expect(genomeToMSA({ model })).toBeUndefined();
+            expect(seqPosToVisibleCol).not.toHaveBeenCalled();
+        });
+        // react-msaview answers one column past the end for a residue the row does
+        // not have, which would light the last column for everything beyond it
+        test('maps nothing for a residue the row stops short of', () => {
+            mockSession({
+                hovered: {
+                    hoverFeature: {},
+                    hoverPosition: { coord: 1005, refName: 'chr1' },
+                },
+            });
+            const model = {
+                querySeqName: 'QUERY',
+                querySeqOffset: 0,
+                rows: [['QUERY', 'MKV']],
+                transcriptToMsaMap: { refName: 'chr1', g2p: { 1004: 10 } },
+                mafRegion: undefined,
+                connectedView: { initialized: true, assemblyNames: ['hg38'] },
+                seqPosToVisibleCol: () => 3,
+                visibleColToSeqPos: () => undefined,
+            };
+            expect(genomeToMSA({ model })).toBeUndefined();
+        });
         test('returns undefined when g2p has no mapping for coord', () => {
-            mockGetSession.mockReturnValue({
+            mockSession({
                 hovered: {
                     hoverFeature: {},
                     hoverPosition: { coord: 1005, refName: 'chr1' },
@@ -255,7 +350,7 @@ describe('genomeToMSA', () => {
                     g2p: { 1000: 0 }, // No entry for 1004
                 },
                 mafRegion: undefined,
-                connectedView: { initialized: true },
+                connectedView: { initialized: true, assemblyNames: ['hg38'] },
                 seqPosToVisibleCol: vi.fn(),
             };
             const result = genomeToMSA({ model });
@@ -263,7 +358,7 @@ describe('genomeToMSA', () => {
         });
     });
     test('returns undefined when neither mafRegion nor transcriptToMsaMap is set', () => {
-        mockGetSession.mockReturnValue({
+        mockSession({
             hovered: {
                 hoverFeature: {},
                 hoverPosition: { coord: 1005, refName: 'chr1' },
@@ -274,7 +369,7 @@ describe('genomeToMSA', () => {
             rows: [['QUERY', 'MKVLTAEEK']],
             transcriptToMsaMap: undefined,
             mafRegion: undefined,
-            connectedView: { initialized: true },
+            connectedView: { initialized: true, assemblyNames: ['hg38'] },
             seqPosToVisibleCol: vi.fn(),
         };
         const result = genomeToMSA({ model });
@@ -285,7 +380,7 @@ describe('genomeToMSA', () => {
     // uploaded file, or the empty name the manual panel leaves when it matches
     // nothing -- lights column 0 on every genome hover
     test('returns undefined when querySeqName names no row here', () => {
-        mockGetSession.mockReturnValue({
+        mockSession({
             hovered: {
                 hoverFeature: {},
                 hoverPosition: { coord: 1005, refName: 'chr1' },
@@ -297,10 +392,110 @@ describe('genomeToMSA', () => {
             rows: [['some_other_row', 'MKVLTAEEK']],
             transcriptToMsaMap: { refName: 'chr1', g2p: { 1004: 3 } },
             mafRegion: undefined,
-            connectedView: { initialized: true },
+            connectedView: { initialized: true, assemblyNames: ['hg38'] },
             seqPosToVisibleCol,
         };
         expect(genomeToMSA({ model })).toBeUndefined();
         expect(seqPosToVisibleCol).not.toHaveBeenCalled();
     });
+    // A hover names the chromosome the assembly's way and the transcript names it
+    // the annotation file's way, so on GENCODE-on-hg38 -- jbrowse.org's own
+    // config -- the two are '1' and 'chr1' and pointing at a codon lit nothing.
+    describe('a config whose assembly and annotation spell the refName apart', () => {
+        beforeEach(() => {
+            aliases = { chr1: '1', chr2: '2' };
+        });
+        test('maps a hover named 1 onto a transcript named chr1', () => {
+            mockSession({
+                hovered: {
+                    hoverFeature: {},
+                    hoverPosition: { coord: 1005, refName: '1' },
+                },
+            });
+            const seqPosToVisibleCol = vi.fn().mockReturnValue(10);
+            const model = {
+                querySeqName: 'QUERY',
+                querySeqOffset: 0,
+                rows: [['QUERY', 'MKVLTAEEK']],
+                transcriptToMsaMap: { refName: 'chr1', g2p: { 1004: 10 } },
+                mafRegion: undefined,
+                connectedView: { initialized: true, assemblyNames: ['hg38'] },
+                seqPosToVisibleCol,
+                visibleColToSeqPos: (_name, col) => col,
+            };
+            expect(genomeToMSA({ model })).toBe(10);
+            expect(seqPosToVisibleCol).toHaveBeenCalledWith('QUERY', 10);
+        });
+        // the gate still has to reject another chromosome, which is the whole
+        // reason it is there
+        test('still rejects a hover on another chromosome', () => {
+            mockSession({
+                hovered: {
+                    hoverFeature: {},
+                    hoverPosition: { coord: 1005, refName: '2' },
+                },
+            });
+            const seqPosToVisibleCol = vi.fn();
+            const model = {
+                querySeqName: 'QUERY',
+                rows: [['QUERY', 'MKVLTAEEK']],
+                transcriptToMsaMap: { refName: 'chr1', g2p: { 1004: 10 } },
+                mafRegion: undefined,
+                connectedView: { initialized: true, assemblyNames: ['hg38'] },
+                seqPosToVisibleCol,
+            };
+            expect(genomeToMSA({ model })).toBeUndefined();
+            expect(seqPosToVisibleCol).not.toHaveBeenCalled();
+        });
+        // this runs from a hover autorun, and mafRegion names an assembly off a
+        // frozen spec that nothing here waited for -- so the aliases may not be
+        // loaded, and asking for them throws
+        test('falls back to the raw name while the aliases are still loading', () => {
+            assemblyInitialized = false;
+            mockSession({
+                hovered: {
+                    hoverFeature: {},
+                    hoverPosition: { coord: 1005, refName: 'chr1' },
+                },
+            });
+            const seqPosToVisibleCol = vi.fn().mockReturnValue(10);
+            const model = {
+                querySeqName: 'QUERY',
+                querySeqOffset: 0,
+                rows: [['QUERY', 'MKVLTAEEK']],
+                transcriptToMsaMap: { refName: 'chr1', g2p: { 1004: 10 } },
+                mafRegion: undefined,
+                connectedView: { initialized: true, assemblyNames: ['hg38'] },
+                seqPosToVisibleCol,
+                visibleColToSeqPos: (_name, col) => col,
+            };
+            expect(() => genomeToMSA({ model })).not.toThrow();
+            // both sides spell it 'chr1' here, so the raw comparison still answers
+            expect(genomeToMSA({ model })).toBe(10);
+        });
+        test('maps a hover named 1 into a mafRegion named chr1', () => {
+            mockSession({
+                hovered: {
+                    hoverFeature: {},
+                    hoverPosition: { coord: 1005, refName: '1' },
+                },
+            });
+            const seqPosToVisibleCol = vi.fn().mockReturnValue(5);
+            const model = {
+                querySeqName: 'hg38.chr1',
+                rows: [['hg38.chr1', 'ACGTACGTAC']],
+                transcriptToMsaMap: undefined,
+                mafRegion: {
+                    refName: 'chr1',
+                    start: 1000,
+                    end: 1010,
+                    assemblyName: 'hg38',
+                },
+                connectedView: { initialized: true, assemblyNames: ['hg38'] },
+                seqPosToVisibleCol,
+            };
+            expect(genomeToMSA({ model })).toBe(5);
+            expect(seqPosToVisibleCol).toHaveBeenCalledWith('hg38.chr1', 4);
+        });
+    });
 });

package/dist/MsaViewPanel/loadProteinDomains.d.ts

@@ -1,16 +1,22 @@
-import type { InterProScanResults } from 'react-msaview';
+import type { Annotation } from 'react-msaview';
 interface DomainModel {
     data: {
         treeMetadata?: string;
     };
     setProgress: (arg: string) => void;
-    setDomains: (data: Record<string, InterProScanResults>) => void;
+    setAnnotations: (annotations: Annotation[]) => void;
 }
 /**
  * Overlay protein domains on the alignment using NCBI's pre-computed CDD
  * annotations. The BLAST workflow stores each hit's accession in treeMetadata,
  * so we look those up via efetch and key the results by MSA row name (which is
  * what react-msaview matches domains against).
+ *
+ * The overlay is handed over as `Annotation[]`, the shape every source flattens
+ * to. It used to be dressed up as an InterProScan response — an `xref` invented
+ * to carry the row name — so that `setDomains` could unwrap it again; that entry
+ * point exists for plugins holding the actual EBI wire format, which this is
+ * not.
  */
 export declare function loadProteinDomains(self: DomainModel): Promise<void>;
 export {};

package/dist/MsaViewPanel/loadProteinDomains.js

@@ -4,6 +4,12 @@ import { fetchProteinDomains } from '../utils/ncbiDomains';
  * annotations. The BLAST workflow stores each hit's accession in treeMetadata,
  * so we look those up via efetch and key the results by MSA row name (which is
  * what react-msaview matches domains against).
+ *
+ * The overlay is handed over as `Annotation[]`, the shape every source flattens
+ * to. It used to be dressed up as an InterProScan response — an `xref` invented
+ * to carry the row name — so that `setDomains` could unwrap it again; that entry
+ * point exists for plugins holding the actual EBI wire format, which this is
+ * not.
  */
 export async function loadProteinDomains(self) {
     const metadataJson = self.data.treeMetadata;
@@ -19,15 +25,18 @@ export async function loadProteinDomains(self) {
     }
     self.setProgress(`Fetching protein domains from NCBI for ${rowAccessions.length} sequences...`);
     const byAccession = await fetchProteinDomains(rowAccessions.map(r => r.accession));
-    const annotations = {};
-    for (const { rowName, accession } of rowAccessions) {
-        const matches = byAccession.get(accession);
-        if (matches && matches.length > 0) {
-            annotations[rowName] = { matches, xref: [{ id: rowName }] };
-        }
-    }
-    if (Object.keys(annotations).length === 0) {
+    const annotations = rowAccessions.flatMap(({ rowName, accession }) => (byAccession.get(accession) ?? []).flatMap(({ signature, locations }) => signature.entry
+        ? locations.map(({ start, end }) => ({
+            id: rowName,
+            accession: signature.entry.accession,
+            name: signature.entry.name,
+            description: signature.entry.description,
+            start,
+            end,
+        }))
+        : []));
+    if (annotations.length === 0) {
         throw new Error('No CDD domain annotations found for these proteins');
     }
-    self.setDomains(annotations);
+    self.setAnnotations(annotations);
 }

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

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

package/dist/MsaViewPanel/loadProteinDomains.test.js

@@ -0,0 +1,41 @@
+import { expect, test, vi } from 'vitest';
+import { fetchProteinDomains } from '../utils/ncbiDomains';
+import { loadProteinDomains } from './loadProteinDomains';
+vi.mock('../utils/ncbiDomains', () => ({ fetchProteinDomains: vi.fn() }));
+const MATCH = {
+    signature: {
+        entry: { accession: 'cd00093', name: 'HTH_XRE', description: 'a domain' },
+    },
+    locations: [{ start: 5, end: 40 }],
+};
+function model(treeMetadata) {
+    return {
+        data: { treeMetadata: JSON.stringify(treeMetadata) },
+        setProgress: vi.fn(),
+        setAnnotations: vi.fn(),
+    };
+}
+test('an accession row becomes one annotation per location, keyed by row name', async () => {
+    vi.mocked(fetchProteinDomains).mockResolvedValue(new Map([['NP_1', [MATCH]]]));
+    const self = model({
+        QUERY: { Accession: 'NP_1' },
+        other: { 'Scientific name': 'Mus musculus' },
+    });
+    await loadProteinDomains(self);
+    expect(self.setAnnotations).toHaveBeenCalledWith([
+        {
+            id: 'QUERY',
+            accession: 'cd00093',
+            name: 'HTH_XRE',
+            description: 'a domain',
+            start: 5,
+            end: 40,
+        },
+    ]);
+});
+test('says so rather than clearing the overlay when NCBI has nothing', async () => {
+    vi.mocked(fetchProteinDomains).mockResolvedValue(new Map());
+    const self = model({ QUERY: { Accession: 'NP_1' } });
+    await expect(loadProteinDomains(self)).rejects.toThrow('No CDD domain annotations found');
+    expect(self.setAnnotations).not.toHaveBeenCalled();
+});