jbrowse-plugin-msaview 5.11.0 → 5.12.0

package/dist/MsaViewPanel/model.js

@@ -8,6 +8,7 @@ import { connectedDomains } from './connectedDomains';
 import { domainTrackConf } from './domainTrack';
 import { msaCoordToGenomeCoord, msaCoordToGenomeRegions, } from './msaCoordToGenomeCoord';
 import { resolveConnectedTranscriptIfNeeded } from './resolveConnectedTranscript';
+import { syncSessionHighlights } from './sessionHighlights';
 import { transcriptMap } from './transcriptMap';
 /**
  * Where the homolog set comes from. NCBI's ortholog sets cover vertebrates and
@@ -576,6 +577,7 @@ export default function stateModelFactory() {
             // so they're factories returning the autorun body rather than plain fns
             addDisposer(self, autorun(syncGenomeHoverToMsaColumn(self)));
             addDisposer(self, autorun(observeProteinHighlights(self)));
+            addDisposer(self, autorun(syncSessionHighlights(self)));
         },
     }));
 }

package/dist/MsaViewPanel/sessionHighlights.d.ts

@@ -0,0 +1,57 @@
+import type { JBrowsePluginMsaViewModel } from './model';
+import type { TranscriptMap } from './transcriptMap';
+/** The `transientHighlights` owner the session's highlights draw under */
+export declare const SESSION_HIGHLIGHT_OWNER = "session-highlights";
+/** A session highlight: a genome region, 0-based half-open */
+export interface GenomeHighlight {
+    assemblyName: string;
+    refName: string;
+    start: number;
+    end: number;
+    label?: string;
+    color?: string;
+}
+/** react-msaview's residue-span highlight: residues of `row`, 1-based */
+export interface RowHighlight {
+    row: string;
+    start: number;
+    end: number;
+    label?: string;
+    color?: string;
+}
+/**
+ * Where the query row sits on the genome: through a transcript, each coding
+ * base mapping to its residue, or as the bases of a MAF block
+ */
+export type QueryOnGenome = {
+    kind: 'transcript';
+    map: Pick<TranscriptMap, 'g2p' | 'refName'>;
+} | {
+    kind: 'maf';
+    refName: string;
+    start: number;
+    end: number;
+};
+/**
+ * The session's highlights on the query row, one residue span per run of
+ * consecutive residues a highlight covers, each keeping the highlight's label
+ * and color. A highlight on another assembly or chromosome, or off the
+ * transcript, draws nothing here.
+ */
+export declare function sessionHighlightsOnQueryRow({ highlights, onGenome, querySeqName, querySeqOffset, sameAssembly, sameRefName, labels, }: {
+    highlights: readonly GenomeHighlight[];
+    onGenome: QueryOnGenome;
+    querySeqName: string;
+    querySeqOffset: number;
+    sameAssembly: (assemblyName: string) => boolean;
+    sameRefName: (refName: string) => boolean;
+    /** whether the session writes labels on its highlights */
+    labels: boolean;
+}): RowHighlight[];
+/**
+ * Draw the session's highlights on the query row as react-msaview transient
+ * highlights, so a codon highlighted on the genome lights and labels its
+ * alignment column. They are derived, so the alignment's own snapshot never
+ * holds them.
+ */
+export declare function syncSessionHighlights(self: JBrowsePluginMsaViewModel): () => void;

package/dist/MsaViewPanel/sessionHighlights.js

@@ -0,0 +1,102 @@
+import { getSession } from '@jbrowse/core/util';
+import { hasQueryRow } from './util';
+/** The `transientHighlights` owner the session's highlights draw under */
+export const SESSION_HIGHLIGHT_OWNER = 'session-highlights';
+/**
+ * The 0-based query-row positions a genome region covers. A transcript's
+ * residues count from its start codon, so `querySeqOffset` moves them onto a
+ * query row that holds only part of the protein.
+ */
+function rowPositions({ start, end }, onGenome, querySeqOffset) {
+    const positions = new Set();
+    if (onGenome.kind === 'maf') {
+        for (let base = Math.max(start, onGenome.start); base < Math.min(end, onGenome.end); base++) {
+            positions.add(base - onGenome.start);
+        }
+    }
+    else {
+        for (let base = start; base < end; base++) {
+            const residue = onGenome.map.g2p[base];
+            if (residue !== undefined) {
+                positions.add(residue - querySeqOffset);
+            }
+        }
+    }
+    return [...positions].filter(p => p >= 0).sort((a, b) => a - b);
+}
+/**
+ * The session's highlights on the query row, one residue span per run of
+ * consecutive residues a highlight covers, each keeping the highlight's label
+ * and color. A highlight on another assembly or chromosome, or off the
+ * transcript, draws nothing here.
+ */
+export function sessionHighlightsOnQueryRow({ highlights, onGenome, querySeqName, querySeqOffset, sameAssembly, sameRefName, labels, }) {
+    return highlights.flatMap(h => {
+        if (!sameAssembly(h.assemblyName) || !sameRefName(h.refName)) {
+            return [];
+        }
+        const runs = [];
+        for (const pos of rowPositions(h, onGenome, querySeqOffset)) {
+            const last = runs.at(-1);
+            if (last?.end === pos) {
+                last.end = pos + 1;
+            }
+            else {
+                runs.push({
+                    row: querySeqName,
+                    start: pos + 1,
+                    end: pos + 1,
+                    ...(labels && h.label ? { label: h.label } : {}),
+                    ...(h.color ? { color: h.color } : {}),
+                });
+            }
+        }
+        return runs;
+    });
+}
+// `highlightLabelsVisible` arrived in core after the oldest host this plugin
+// supports, which writes every label
+function labelsVisible(session) {
+    return !('highlightLabelsVisible' in session &&
+        session.highlightLabelsVisible === false);
+}
+/**
+ * Draw the session's highlights on the query row as react-msaview transient
+ * highlights, so a codon highlighted on the genome lights and labels its
+ * alignment column. They are derived, so the alignment's own snapshot never
+ * holds them.
+ */
+export function syncSessionHighlights(self) {
+    return () => {
+        const session = getSession(self);
+        const { connectedView, transcriptToMsaMap, mafRegion } = self;
+        const assemblyName = mafRegion?.assemblyName ?? connectedView?.assemblyNames[0];
+        const { assemblyManager } = session;
+        const assembly = assemblyName
+            ? assemblyManager.get(assemblyName)
+            : undefined;
+        const onGenome = mafRegion
+            ? { kind: 'maf', ...mafRegion }
+            : transcriptToMsaMap
+                ? { kind: 'transcript', map: transcriptToMsaMap }
+                : undefined;
+        if (!session.highlightsVisible ||
+            !session.highlights.length ||
+            !onGenome ||
+            !assembly?.initialized ||
+            !hasQueryRow(self)) {
+            self.clearHighlight(SESSION_HIGHLIGHT_OWNER);
+            return;
+        }
+        const ownRefName = assembly.getCanonicalRefName(onGenome.kind === 'maf' ? onGenome.refName : onGenome.map.refName);
+        self.applyHighlight(SESSION_HIGHLIGHT_OWNER, sessionHighlightsOnQueryRow({
+            highlights: session.highlights,
+            onGenome,
+            querySeqName: self.querySeqName,
+            querySeqOffset: self.querySeqOffset,
+            sameAssembly: name => assemblyManager.get(name) === assembly,
+            sameRefName: refName => assembly.getCanonicalRefName(refName) === ownRefName,
+            labels: labelsVisible(session),
+        }));
+    };
+}

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

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

package/dist/MsaViewPanel/sessionHighlights.test.js

@@ -0,0 +1,60 @@
+import { expect, test } from 'vitest';
+import { sessionHighlightsOnQueryRow } from './sessionHighlights';
+// minus strand: residue 0 on bases 109..107, residue 1 on 106..104, residue 2
+// on 103..101
+const g2p = {};
+for (let base = 101; base < 110; base++) {
+    g2p[base] = Math.floor((109 - base) / 3);
+}
+const transcript = {
+    kind: 'transcript',
+    map: { g2p, refName: 'chr12' },
+};
+function onRow(highlights, { onGenome = transcript, querySeqOffset = 0, labels = true } = {}) {
+    return sessionHighlightsOnQueryRow({
+        highlights,
+        onGenome,
+        querySeqName: 'human_query',
+        querySeqOffset,
+        sameAssembly: name => name === 'hg38',
+        sameRefName: refName => refName.replace(/^chr/, '') === '12',
+        labels,
+    });
+}
+const codon = (start, label) => ({
+    assemblyName: 'hg38',
+    refName: 'chr12',
+    start,
+    end: start + 3,
+    label,
+});
+test('a codon labels the residue it codes, 1-based on the query row', () => {
+    expect(onRow([codon(104, 'G12')])).toEqual([
+        { row: 'human_query', start: 2, end: 2, label: 'G12' },
+    ]);
+});
+test('a query row holding part of the protein shifts by its offset', () => {
+    expect(onRow([codon(101)], { querySeqOffset: 1 })).toEqual([
+        { row: 'human_query', start: 2, end: 2 },
+    ]);
+});
+test('a region over several residues is one span per consecutive run', () => {
+    expect(onRow([{ assemblyName: 'hg38', refName: '12', start: 101, end: 110 }])).toEqual([{ row: 'human_query', start: 1, end: 3 }]);
+});
+test('a highlight on another chromosome, assembly or off the CDS draws nothing', () => {
+    expect(onRow([
+        { ...codon(104), refName: 'chr7' },
+        { ...codon(104), assemblyName: 'mm39' },
+        codon(200),
+    ])).toEqual([]);
+});
+test('a MAF query row counts bases from the block start', () => {
+    expect(onRow([codon(1005, 'site')], {
+        onGenome: { kind: 'maf', refName: 'chr12', start: 1000, end: 1010 },
+    })).toEqual([{ row: 'human_query', start: 6, end: 8, label: 'site' }]);
+});
+test('labels turned off in the session keep the span and drop its text', () => {
+    expect(onRow([codon(104, 'G12')], { labels: false })).toEqual([
+        { row: 'human_query', start: 2, end: 2 },
+    ]);
+});