jbrowse-plugin-msaview 5.3.0 → 5.5.0

package/dist/MsaViewPanel/afterCreateAutoruns.d.ts

@@ -57,3 +57,4 @@ export declare function syncGenomeHoverToMsaColumn(self: JBrowsePluginMsaViewMod
  */
 export declare function observeProteinHighlights(self: JBrowsePluginMsaViewModel): () => void;
 export declare function runCleanup(): void;
+export declare function showDomainsOnGenomeIfAsked(self: JBrowsePluginMsaViewModel): void;

package/dist/MsaViewPanel/afterCreateAutoruns.js

@@ -390,3 +390,11 @@ export function runCleanup() {
         console.error('Failed to cleanup old MSA data:', e);
     });
 }
+export function showDomainsOnGenomeIfAsked(self) {
+    if (self.domainsOnGenome &&
+        self.connectedView &&
+        self.connectedDomains.length > 0) {
+        self.showDomainsOnGenome();
+        self.setDomainsOnGenome(false);
+    }
+}

package/dist/MsaViewPanel/connectedDomains.d.ts

@@ -0,0 +1,40 @@
+import type { GenomeRegion, SeqPosModel } from './msaCoordToGenomeCoord';
+import type { Annotation } from 'react-msaview';
+/**
+ * One accession the alignment draws on the query row, on the genome. A
+ * cross-plugin contract: jbrowse-plugin-protein3d reads it off the view.
+ */
+export interface ConnectedDomain {
+    /** the label the alignment's legend shows for the domain's accession */
+    name: string;
+    accession: string;
+    /** the fill the alignment draws the domain in */
+    color: string;
+    /**
+     * 0-based half-open, ascending, contiguous bases merged: one region per exon
+     * piece of a domain, or per run of a site's scattered residues, in the
+     * transcript's refName spelling
+     */
+    regions: GenomeRegion[];
+}
+export interface DomainSource extends SeqPosModel {
+    showDomains: boolean;
+    querySeqName: string;
+    annotationsByRow: Record<string, Annotation[]>;
+    annotationTypes: Map<string, Annotation>;
+    featureColors: Map<Annotation, {
+        fill: string;
+    }>;
+}
+/**
+ * The genome regions under the query row's residues `positions`, 0-based
+ * ungapped.
+ */
+export declare function residuesToGenomeRegions(model: SeqPosModel, positions: Iterable<number>): GenomeRegion[];
+/**
+ * The query row's domains as the alignment shows them, one per accession, so
+ * a CDD site's scattered residues are one entry. Largest first by residues
+ * covered, so a site painted later lands on the domain it sits in. Empty
+ * while the domain overlay is off.
+ */
+export declare function connectedDomains(model: DomainSource): ConnectedDomain[];

package/dist/MsaViewPanel/connectedDomains.js

@@ -0,0 +1,74 @@
+import { seqPosToGenomeRegions } from './msaCoordToGenomeCoord';
+function mergeAdjacent(regions) {
+    const merged = [];
+    for (const region of regions.toSorted((a, b) => a.start - b.start)) {
+        const last = merged.at(-1);
+        if (last && last.refName === region.refName && region.start <= last.end) {
+            last.end = Math.max(last.end, region.end);
+        }
+        else {
+            merged.push({ ...region });
+        }
+    }
+    return merged;
+}
+/**
+ * The genome regions under the query row's residues `positions`, 0-based
+ * ungapped.
+ */
+export function residuesToGenomeRegions(model, positions) {
+    const pieces = [];
+    for (const pos of positions) {
+        pieces.push(...seqPosToGenomeRegions(model, pos));
+    }
+    return mergeAdjacent(pieces);
+}
+/**
+ * The query row's domains as the alignment shows them, one per accession, so
+ * a CDD site's scattered residues are one entry. Largest first by residues
+ * covered, so a site painted later lands on the domain it sits in. Empty
+ * while the domain overlay is off.
+ */
+export function connectedDomains(model) {
+    if (!model.showDomains) {
+        return [];
+    }
+    const byAccession = new Map();
+    for (const annotation of model.annotationsByRow[model.querySeqName] ?? []) {
+        const list = byAccession.get(annotation.accession);
+        if (list) {
+            list.push(annotation);
+        }
+        else {
+            byAccession.set(annotation.accession, [annotation]);
+        }
+    }
+    return [...byAccession]
+        .flatMap(([accession, annotations]) => {
+        // annotations count residues 1-based inclusive
+        const positions = new Set();
+        for (const { start, end } of annotations) {
+            for (let pos = start - 1; pos < end; pos++) {
+                positions.add(pos);
+            }
+        }
+        const first = annotations[0];
+        const color = model.featureColors.get(first)?.fill;
+        const regions = residuesToGenomeRegions(model, positions);
+        return color && regions.length > 0
+            ? [
+                {
+                    domain: {
+                        name: model.annotationTypes.get(accession)?.name ?? first.name,
+                        accession,
+                        color,
+                        regions,
+                    },
+                    residues: positions.size,
+                },
+            ]
+            : [];
+    })
+        .toSorted((a, b) => b.residues - a.residues)
+        .map(({ domain }) => domain);
+}

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

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

package/dist/MsaViewPanel/connectedDomains.test.js

@@ -0,0 +1,108 @@
+import { genomeToTranscriptSeqMapping } from 'g2p_mapper';
+import { describe, expect, test } from 'vitest';
+import { connectedDomains } from './connectedDomains';
+// five codons read from 207 down: 207-205, 204-202, 201-200 then 106 across
+// the intron, 105-103, 102-100
+const reverseTranscript = genomeToTranscriptSeqMapping({
+    refName: 'chr1',
+    strand: -1,
+    start: 100,
+    end: 208,
+    subfeatures: [
+        { refName: 'chr1', type: 'CDS', start: 100, end: 107, phase: 0 },
+        { refName: 'chr1', type: 'CDS', start: 200, end: 208, phase: 0 },
+    ],
+});
+function annotation(accession, start, end, id = 'QUERY') {
+    return {
+        id,
+        accession,
+        name: `name ${accession}`,
+        description: '',
+        start,
+        end,
+    };
+}
+function source(annotations, overrides = {}) {
+    return {
+        showDomains: true,
+        querySeqName: 'QUERY',
+        transcriptToMsaMap: reverseTranscript,
+        annotationsByRow: Object.groupBy(annotations, a => a.id),
+        annotationTypes: new Map(annotations.map(a => [
+            a.accession,
+            { ...a, name: `legend ${a.accession}` },
+        ])),
+        featureColors: new Map(annotations.map(a => [a, { fill: `fill-${a.accession}` }])),
+        ...overrides,
+    };
+}
+describe('connectedDomains on a reverse-strand transcript', () => {
+    test('a domain crossing the exon boundary is one region per exon piece', () => {
+        expect(connectedDomains(source([annotation('site', 2, 4)]))).toEqual([
+            {
+                name: 'legend site',
+                accession: 'site',
+                color: 'fill-site',
+                regions: [
+                    { refName: 'chr1', start: 103, end: 107 },
+                    { refName: 'chr1', start: 200, end: 205 },
+                ],
+            },
+        ]);
+    });
+    test('the longest comes first, so a nested site paints over it', () => {
+        const domains = connectedDomains(source([annotation('site', 2, 4), annotation('domain', 1, 5)]));
+        expect(domains.map(d => d.accession)).toEqual(['domain', 'site']);
+        expect(domains[0].regions).toEqual([
+            { refName: 'chr1', start: 100, end: 107 },
+            { refName: 'chr1', start: 200, end: 208 },
+        ]);
+    });
+    test('a scattered site is one entry, its residues merged where they touch', () => {
+        const domains = connectedDomains(source([
+            annotation('small', 4, 5),
+            annotation('heme', 1, 1),
+            annotation('heme', 3, 3),
+            annotation('heme', 4, 4),
+        ]));
+        expect(domains.map(d => d.accession)).toEqual(['heme', 'small']);
+        expect(domains[0]).toEqual({
+            name: 'legend heme',
+            accession: 'heme',
+            color: 'fill-heme',
+            regions: [
+                { refName: 'chr1', start: 103, end: 107 },
+                { refName: 'chr1', start: 200, end: 202 },
+                { refName: 'chr1', start: 205, end: 208 },
+            ],
+        });
+    });
+    test('a trimmed query row shifts by querySeqOffset', () => {
+        const [domain] = connectedDomains(source([annotation('site', 1, 2)], { querySeqOffset: 1 }));
+        expect(domain.regions).toEqual([
+            { refName: 'chr1', start: 106, end: 107 },
+            { refName: 'chr1', start: 200, end: 205 },
+        ]);
+    });
+    test('residues past the transcript drop out, and a domain with none left', () => {
+        expect(connectedDomains(source([annotation('tail', 5, 9), annotation('off', 7, 9)]))).toEqual([
+            expect.objectContaining({
+                accession: 'tail',
+                regions: [{ refName: 'chr1', start: 100, end: 103 }],
+            }),
+        ]);
+    });
+    test('only the query row, and nothing while the overlay is off', () => {
+        const annotations = [annotation('other', 1, 5, 'Mouse')];
+        expect(connectedDomains(source(annotations))).toEqual([]);
+        expect(connectedDomains(source([annotation('domain', 1, 5)], { showDomains: false }))).toEqual([]);
+    });
+});
+test('a MAF row maps one base per residue', () => {
+    const [domain] = connectedDomains(source([annotation('d', 3, 6)], {
+        transcriptToMsaMap: undefined,
+        mafRegion: { refName: 'chr2', start: 50, end: 100, assemblyName: 'hg38' },
+    }));
+    expect(domain.regions).toEqual([{ refName: 'chr2', start: 52, end: 56 }]);
+});

package/dist/MsaViewPanel/domainTrack.d.ts

@@ -0,0 +1,85 @@
+import type { ConnectedDomain } from './connectedDomains';
+export declare function domainTrackId(viewId: string): string;
+/**
+ * A session FeatureTrack drawing `domains` on the genome: one feature per
+ * domain, one subfeature per region, so a domain spanning exons draws as boxes
+ * joined across the intron. Each feature paints the `color` it carries, and
+ * the key names each color with its domain.
+ */
+export declare function domainTrackConf({ viewId, assemblyName, name, strand, domains, }: {
+    viewId: string;
+    assemblyName: string;
+    name: string;
+    strand?: number;
+    domains: ConnectedDomain[];
+}): {
+    type: string;
+    trackId: string;
+    name: string;
+    assemblyNames: string[];
+    adapter: {
+        type: string;
+        features: ({
+            type: string;
+            name: string;
+            accession: string;
+            color: string;
+            subfeatures: ({
+                type: string;
+                strand?: undefined;
+                uniqueId: string;
+                refName: string;
+                start: number;
+                end: number;
+            } | {
+                type: string;
+                strand: number;
+                uniqueId: string;
+                refName: string;
+                start: number;
+                end: number;
+            })[];
+            strand?: undefined;
+            uniqueId: string;
+            refName: string;
+            start: number;
+            end: number;
+        } | {
+            type: string;
+            name: string;
+            accession: string;
+            color: string;
+            subfeatures: ({
+                type: string;
+                strand?: undefined;
+                uniqueId: string;
+                refName: string;
+                start: number;
+                end: number;
+            } | {
+                type: string;
+                strand: number;
+                uniqueId: string;
+                refName: string;
+                start: number;
+                end: number;
+            })[];
+            strand: number;
+            uniqueId: string;
+            refName: string;
+            start: number;
+            end: number;
+        })[];
+    };
+    displays: {
+        type: string;
+        displayId: string;
+        color: {
+            field: string;
+            domain: string[];
+            range: string[];
+            labels: string[];
+            title: string;
+        };
+    }[];
+};

package/dist/MsaViewPanel/domainTrack.js

@@ -0,0 +1,64 @@
+export function domainTrackId(viewId) {
+    return `msaview-domains-${viewId}`;
+}
+/**
+ * A session FeatureTrack drawing `domains` on the genome: one feature per
+ * domain, one subfeature per region, so a domain spanning exons draws as boxes
+ * joined across the intron. Each feature paints the `color` it carries, and
+ * the key names each color with its domain.
+ */
+export function domainTrackConf({ viewId, assemblyName, name, strand, domains, }) {
+    const trackId = domainTrackId(viewId);
+    const labelOf = new Map();
+    for (const { color, name } of domains) {
+        if (!labelOf.has(color)) {
+            labelOf.set(color, name);
+        }
+    }
+    const colors = [...labelOf.keys()];
+    const stranded = strand === undefined ? {} : { strand };
+    return {
+        type: 'FeatureTrack',
+        trackId,
+        name,
+        assemblyNames: [assemblyName],
+        adapter: {
+            type: 'FromConfigAdapter',
+            features: domains.map(({ name, accession, color, regions }, i) => {
+                const uniqueId = `${trackId}-${i}`;
+                return {
+                    uniqueId,
+                    refName: regions[0].refName,
+                    start: Math.min(...regions.map(r => r.start)),
+                    end: Math.max(...regions.map(r => r.end)),
+                    ...stranded,
+                    type: 'protein_domain',
+                    name,
+                    accession,
+                    color,
+                    subfeatures: regions.map((r, j) => ({
+                        uniqueId: `${uniqueId}-${j}`,
+                        refName: r.refName,
+                        start: r.start,
+                        end: r.end,
+                        ...stranded,
+                        type: 'protein_domain_part',
+                    })),
+                };
+            }),
+        },
+        displays: [
+            {
+                type: 'LinearBasicDisplay',
+                displayId: `${trackId}-LinearBasicDisplay`,
+                color: {
+                    field: 'color',
+                    domain: colors,
+                    range: colors,
+                    labels: colors.map(c => labelOf.get(c)),
+                    title: 'Domains',
+                },
+            },
+        ],
+    };
+}

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

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

package/dist/MsaViewPanel/domainTrack.test.js

@@ -0,0 +1,67 @@
+import { expect, test } from 'vitest';
+import { domainTrackConf } from './domainTrack';
+const domains = [
+    {
+        name: 'Hb beta-like',
+        accession: 'cd1',
+        color: '#1b9e77',
+        regions: [
+            { refName: 'chr11', start: 100, end: 107 },
+            { refName: 'chr11', start: 200, end: 208 },
+        ],
+    },
+    {
+        name: 'heme binding site',
+        accession: 'cd2',
+        color: '#d95f02',
+        regions: [{ refName: 'chr11', start: 103, end: 107 }],
+    },
+    {
+        name: 'Hb beta-like',
+        accession: 'cd1',
+        color: '#1b9e77',
+        regions: [{ refName: 'chr11', start: 300, end: 330 }],
+    },
+];
+const conf = domainTrackConf({
+    viewId: 'msa1',
+    assemblyName: 'hg38',
+    name: 'HBB domains (from the alignment)',
+    strand: -1,
+    domains,
+});
+test('one feature per domain, one subfeature per region, spanning them all', () => {
+    const [first] = conf.adapter.features;
+    expect(conf.trackId).toBe('msaview-domains-msa1');
+    expect(conf.adapter.features).toHaveLength(3);
+    expect(first).toMatchObject({
+        refName: 'chr11',
+        start: 100,
+        end: 208,
+        strand: -1,
+        name: 'Hb beta-like',
+        color: '#1b9e77',
+    });
+    expect(first.subfeatures.map(s => [s.start, s.end])).toEqual([
+        [100, 107],
+        [200, 208],
+    ]);
+});
+test('the display paints each feature its own color and names it in the key', () => {
+    expect(conf.displays[0].color).toEqual({
+        field: 'color',
+        domain: ['#1b9e77', '#d95f02'],
+        range: ['#1b9e77', '#d95f02'],
+        labels: ['Hb beta-like', 'heme binding site'],
+        title: 'Domains',
+    });
+});
+test('a MAF view knows no strand, and the features carry none', () => {
+    const unstranded = domainTrackConf({
+        viewId: 'msa1',
+        assemblyName: 'hg38',
+        name: 'x',
+        domains,
+    });
+    expect('strand' in unstranded.adapter.features[0]).toBe(false);
+});