react-msaview 5.4.0 → 5.5.0

package/dist/model.d.ts

@@ -6,6 +6,14 @@ import type { Instance } from '@jbrowse/mobx-state-tree';
 import type { Theme } from '@mui/material';
 /**
  * #stateModel MsaView
+ *
+ * The main MSAView state model. Holds the loaded alignment, tree, and optional
+ * InterProScan domain annotations, plus all display state (color scheme, zoom,
+ * scroll, collapsed clades). It composes in members from `DialogQueueSessionMixin`,
+ * `Tree`, and `MSAModel` (see Inherited members below). Data is loaded reactively
+ * from the `msaFilehandle` / `treeFilehandle` / `gffFilehandle` properties, or set
+ * directly with `setData`. Most state is persisted into the shareable URL.
+ *
  * #example
  * ```js
  * import { MSAModelF } from 'react-msaview'
@@ -28,7 +36,7 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
     bgColor: import("@jbrowse/mobx-state-tree").IType<boolean | undefined, boolean, boolean>;
     colorSchemeName: import("@jbrowse/mobx-state-tree").IType<string | undefined, string, string>;
     msaFormat: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").ISimpleType<import("msa-parsers").MSAFormat>>;
-}, "type" | "id" | "data" | "showDomains" | "hideGaps" | "allowedGappyness" | "subFeatureRows" | "drawMsaLetters" | "scrollZoom" | "rowHeight" | "scrollY" | "scrollX" | "colWidth" | "currentAlignment" | "height" | "treeFilehandle" | "msaFilehandle" | "treeMetadataFilehandle" | "gffFilehandle" | "collapsed" | "showOnly" | "turnedOffTracks" | "featureFilters" | "relativeTo"> & {
+}, "type" | "id" | "data" | "showDomains" | "hideGaps" | "allowedGappyness" | "subFeatureRows" | "drawMsaLetters" | "scrollZoom" | "rowHeight" | "scrollY" | "scrollX" | "colWidth" | "currentAlignment" | "height" | "treeFilehandle" | "msaFilehandle" | "treeMetadataFilehandle" | "gffFilehandle" | "collapsed" | "showOnly" | "turnedOffTracks" | "featureFilters" | "relativeTo" | "highlightColumns"> & {
     id: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<string>, [undefined]>;
     showDomains: import("@jbrowse/mobx-state-tree").IType<boolean | undefined, boolean, boolean>;
     hideGaps: import("@jbrowse/mobx-state-tree").IType<boolean | undefined, boolean, boolean>;
@@ -144,6 +152,7 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
     }>, [undefined]>;
     featureFilters: import("@jbrowse/mobx-state-tree").IMapType<import("@jbrowse/mobx-state-tree").ISimpleType<boolean>>;
     relativeTo: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
+    highlightColumns: import("@jbrowse/mobx-state-tree").IType<number[] | undefined, number[] | undefined, number[] | undefined>;
 }, {
     queueOfDialogs: [import("@jbrowse/core/util").DialogComponentType, any][];
 } & {
@@ -262,10 +271,13 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
 } & {
     /**
      * #action
+     * draw the alignment with positions numbered relative to the given row's
+     * sequence (its node id), instead of in raw MSA-column coordinates
      */
     drawRelativeTo(id: string | undefined): void;
     /**
      * #action
+     * hide columns that are entirely (or mostly, see allowedGappyness) gaps
      */
     setHideGaps(arg: boolean): void;
     /**
@@ -320,6 +332,7 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
     setHighlightedColumns(columns?: number[]): void;
     /**
      * #action
+     * toggle the InterProScan protein-domain overlay on the alignment
      */
     setShowDomains(arg: boolean): void;
     /**
@@ -353,14 +366,19 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
     setCurrentAlignment(n: number): void;
     /**
      * #action
+     * collapse or un-collapse the subtree rooted at the given tree node id
      */
     toggleCollapsed(node: string): void;
     /**
      * #action
+     * show only the subtree rooted at the given node id (pass undefined to
+     * show the whole tree again)
      */
     setShowOnly(node?: string): void;
     /**
      * #action
+     * set the alignment/tree/metadata/domain data directly from strings,
+     * bypassing the filehandle loaders
      */
     setData(data: {
         msa?: string;
@@ -674,6 +692,7 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
     calculateNeighborJoiningTreeFromMSA(): void;
     /**
      * #action
+     * restore the default column width and row height
      */
     resetZoom(): void;
     /**
@@ -852,32 +871,40 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
         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;
     }[]>;
 } & {
     /**
@@ -889,12 +916,81 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
      * #getter
      */
     readonly verticalScrollbarWidth: 0 | 20;
+    /**
+     * #getter
+     * ordinal segment types (exons etc.), ordered by sequence position so
+     * exon-1..exon-14 read left-to-right; colored by alternating shade and
+     * labeled by number rather than each getting a distinct hue + legend row
+     */
+    readonly segmentDomainTypes: {
+        id: string;
+        name: string;
+        accession: string;
+        description: string;
+        featureType: string | undefined;
+        start: number;
+        end: number;
+        strand: number | undefined;
+    }[];
+    /**
+     * #getter
+     * categorical feature types (InterPro domains and the like) that each get
+     * their own color and a legend entry
+     */
+    readonly categoricalDomainTypes: {
+        id: string;
+        name: string;
+        accession: string;
+        description: string;
+        featureType: string | undefined;
+        start: number;
+        end: number;
+        strand: number | undefined;
+    }[];
     readonly fillPalette: {
-        [k: string]: string;
+        [x: string]: string;
     };
     readonly strokePalette: {
         [k: string]: string;
     };
+    /**
+     * #getter
+     * accession -> number drawn on each segment band: the trailing number of
+     * the feature name ("exon-3" -> "3"), else its 1-based position
+     */
+    readonly segmentLabels: Map<string, string>;
+    /**
+     * #getter
+     * the domain types currently drawn on the alignment (filtered-on), shared
+     * by the on-screen legend and the SVG export legend. Ordinal segments
+     * (exons) are excluded — they read as a numbered gene model, not a color
+     * key — so this is the categorical types ordered by sequence position
+     */
+    readonly visibleDomainTypes: {
+        id: string;
+        name: string;
+        accession: string;
+        description: string;
+        featureType: string | undefined;
+        start: number;
+        end: number;
+        strand: number | undefined;
+    }[];
+    /**
+     * #getter
+     * domain annotations under the mouse, hit-tested against the exact visible
+     * column span each box is drawn at (so it matches the overlay across gaps)
+     */
+    readonly mouseOverDomains: {
+        id: string;
+        name: string;
+        accession: string;
+        description: string;
+        featureType: string | undefined;
+        start: number;
+        end: number;
+        strand: number | undefined;
+    }[];
     /**
      * #method
      */
@@ -955,7 +1051,7 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
     bgColor: import("@jbrowse/mobx-state-tree").IType<boolean | undefined, boolean, boolean>;
     colorSchemeName: import("@jbrowse/mobx-state-tree").IType<string | undefined, string, string>;
     msaFormat: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").ISimpleType<import("msa-parsers").MSAFormat>>;
-}, "type" | "id" | "data" | "showDomains" | "hideGaps" | "allowedGappyness" | "subFeatureRows" | "drawMsaLetters" | "scrollZoom" | "rowHeight" | "scrollY" | "scrollX" | "colWidth" | "currentAlignment" | "height" | "treeFilehandle" | "msaFilehandle" | "treeMetadataFilehandle" | "gffFilehandle" | "collapsed" | "showOnly" | "turnedOffTracks" | "featureFilters" | "relativeTo"> & {
+}, "type" | "id" | "data" | "showDomains" | "hideGaps" | "allowedGappyness" | "subFeatureRows" | "drawMsaLetters" | "scrollZoom" | "rowHeight" | "scrollY" | "scrollX" | "colWidth" | "currentAlignment" | "height" | "treeFilehandle" | "msaFilehandle" | "treeMetadataFilehandle" | "gffFilehandle" | "collapsed" | "showOnly" | "turnedOffTracks" | "featureFilters" | "relativeTo" | "highlightColumns"> & {
     id: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<string>, [undefined]>;
     showDomains: import("@jbrowse/mobx-state-tree").IType<boolean | undefined, boolean, boolean>;
     hideGaps: import("@jbrowse/mobx-state-tree").IType<boolean | undefined, boolean, boolean>;
@@ -1071,6 +1167,7 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
     }>, [undefined]>;
     featureFilters: import("@jbrowse/mobx-state-tree").IMapType<import("@jbrowse/mobx-state-tree").ISimpleType<boolean>>;
     relativeTo: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
+    highlightColumns: import("@jbrowse/mobx-state-tree").IType<number[] | undefined, number[] | undefined, number[] | undefined>;
 }>, symbol>>;
 export default stateModelFactory;
 export type MsaViewStateModel = ReturnType<typeof stateModelFactory>;

package/dist/model.js

@@ -10,7 +10,7 @@ import { clustalXColumnColors } from "./clustalX.js";
 import colorSchemes from "./colorSchemes.js";
 import ConservationTrack from "./components/ConservationTrack.js";
 import TextTrack from "./components/TextTrack.js";
-import { defaultAllowedGappyness, defaultBgColor, defaultColWidth, defaultColorSchemeName, defaultCurrentAlignment, defaultDrawLabels, defaultDrawMsaLetters, defaultDrawNodeBubbles, defaultDrawTree, defaultHeight, defaultHideGaps, defaultLabelsAlignRight, defaultRowHeight, defaultScrollX, defaultScrollY, defaultScrollZoom, defaultShowBranchLen, defaultShowDomains, defaultSubFeatureRows, defaultTreeAreaWidth, defaultTreeWidth, maxCellSize, minColWidth, minRowHeight, } from "./constants.js";
+import { defaultAllowedGappyness, defaultBgColor, defaultColWidth, defaultColorSchemeName, defaultCurrentAlignment, defaultDrawLabels, defaultDrawMsaLetters, defaultDrawNodeBubbles, defaultDrawTree, defaultHeight, defaultHideGaps, defaultLabelsAlignRight, defaultRowHeight, defaultScrollX, defaultScrollY, defaultScrollZoom, defaultShowBranchLen, defaultShowDomains, defaultSubFeatureRows, defaultTreeAreaWidth, defaultTreeWidth, maxCellSize, minColWidth, minRowHeight, segmentFeatureTypes, segmentShades, } from "./constants.js";
 import { createPaletteMap } from "./createPaletteMap.js";
 import { fetchTextWithProgress, isAbortError } from "./fetchUtils.js";
 import { flatToTree } from "./flatToTree.js";
@@ -34,6 +34,14 @@ function parseTreeText(text) {
 }
 /**
  * #stateModel MsaView
+ *
+ * The main MSAView state model. Holds the loaded alignment, tree, and optional
+ * InterProScan domain annotations, plus all display state (color scheme, zoom,
+ * scroll, collapsed clades). It composes in members from `DialogQueueSessionMixin`,
+ * `Tree`, and `MSAModel` (see Inherited members below). Data is loaded reactively
+ * from the `msaFilehandle` / `treeFilehandle` / `gffFilehandle` properties, or set
+ * directly with `setData`. Most state is persisted into the shareable URL.
+ *
  * #example
  * ```js
  * import { MSAModelF } from 'react-msaview'
@@ -166,6 +174,15 @@ function stateModelFactory() {
          * #property
          */
         relativeTo: types.maybe(types.string),
+        /**
+         * #property
+         * declarative seed for the highlighted-columns overlay (visible column
+         * indices). Unlike the volatile `highlightedColumns` (driven by
+         * transient genome-hover sync), this persists in the snapshot/URL so a
+         * shared link can open with specific columns highlighted. Applied once
+         * in afterCreate.
+         */
+        highlightColumns: types.frozen(),
     }))
         .volatile(() => ({
         /**
@@ -260,12 +277,15 @@ function stateModelFactory() {
         .actions(self => ({
         /**
          * #action
+         * draw the alignment with positions numbered relative to the given row's
+         * sequence (its node id), instead of in raw MSA-column coordinates
          */
         drawRelativeTo(id) {
             self.relativeTo = id;
         },
         /**
          * #action
+         * hide columns that are entirely (or mostly, see allowedGappyness) gaps
          */
         setHideGaps(arg) {
             self.hideGaps = arg;
@@ -341,6 +361,7 @@ function stateModelFactory() {
         },
         /**
          * #action
+         * toggle the InterProScan protein-domain overlay on the alignment
          */
         setShowDomains(arg) {
             self.showDomains = arg;
@@ -389,6 +410,7 @@ function stateModelFactory() {
         },
         /**
          * #action
+         * collapse or un-collapse the subtree rooted at the given tree node id
          */
         toggleCollapsed(node) {
             if (self.collapsed.includes(node)) {
@@ -400,12 +422,16 @@ function stateModelFactory() {
         },
         /**
          * #action
+         * show only the subtree rooted at the given node id (pass undefined to
+         * show the whole tree again)
          */
         setShowOnly(node) {
             self.showOnly = node;
         },
         /**
          * #action
+         * set the alignment/tree/metadata/domain data directly from strings,
+         * bypassing the filehandle loaders
          */
         setData(data) {
             self.data = cast(data);
@@ -794,6 +820,9 @@ function stateModelFactory() {
             const { colStats, colStatsSums } = this;
             return colStats.map((stats, i) => {
                 const total = colStatsSums[i];
+                if (!total) {
+                    return { letter: '', color: undefined };
+                }
                 let maxCount = 0;
                 let letter = '';
                 for (const [key, val] of Object.entries(stats)) {
@@ -1044,6 +1073,7 @@ function stateModelFactory() {
         },
         /**
          * #action
+         * restore the default column width and row height
          */
         resetZoom() {
             self.setColWidth(defaultColWidth);
@@ -1080,9 +1110,8 @@ function stateModelFactory() {
          */
         zoomIn() {
             transaction(() => {
-                self.colWidth = Math.min(maxCellSize, Math.ceil(self.colWidth * 1.5));
-                self.rowHeight = Math.min(maxCellSize, Math.ceil(self.rowHeight * 1.5));
-                self.scrollX = clamp(self.scrollX, self.maxScrollX, 0);
+                this.zoomInHorizontal();
+                this.zoomInVertical();
             });
         },
         /**
@@ -1090,9 +1119,8 @@ function stateModelFactory() {
          */
         zoomOut() {
             transaction(() => {
-                self.colWidth = Math.max(minColWidth, Math.floor(self.colWidth * 0.75));
-                self.rowHeight = Math.max(minRowHeight, Math.floor(self.rowHeight * 0.75));
-                self.scrollX = clamp(self.scrollX, self.maxScrollX, 0);
+                this.zoomOutHorizontal();
+                this.zoomOutVertical();
             });
         },
         /**
@@ -1113,8 +1141,12 @@ function stateModelFactory() {
                 self.rowHeight = clamp(self.rowHeight * scaleFactor, minRowHeight, maxCellSize);
                 self.scrollX = clamp(offsetX - colInView * self.colWidth, self.maxScrollX, 0);
                 const anchoredScrollY = offsetY - rowInView * self.rowHeight;
-                const overflow = Math.max(0, self.totalHeight - self.height);
-                const topBias = self.height > 0 ? clamp(1 - overflow / self.height, 0, 1) : 0;
+                // maxScrollY is -(totalHeight - visibleMsaHeight) when the alignment
+                // overflows, so -maxScrollY is exactly that overflow past the
+                // scrollable MSA viewport (0 when it fits)
+                const overflow = Math.max(0, -self.maxScrollY);
+                const visibleHeight = self.totalHeight - overflow;
+                const topBias = visibleHeight > 0 ? clamp(1 - overflow / visibleHeight, 0, 1) : 1;
                 self.scrollY = clamp(anchoredScrollY * (1 - topBias), self.maxScrollY, 0);
             });
         },
@@ -1356,13 +1388,15 @@ function stateModelFactory() {
                     .flatMap(([id, val]) => val.matches.flatMap(({ signature, locations }) => {
                     const { entry } = signature;
                     return entry
-                        ? locations.map(({ start, end }) => ({
+                        ? locations.map(({ start, end, strand }) => ({
                             id,
                             name: entry.name,
                             accession: entry.accession,
                             description: entry.description,
+                            featureType: entry.featureType,
                             start,
                             end,
+                            strand,
                         }))
                         : [];
                 }))
@@ -1391,8 +1425,32 @@ function stateModelFactory() {
         get verticalScrollbarWidth() {
             return self.showVerticalScrollbar ? 20 : 0;
         },
+        /**
+         * #getter
+         * ordinal segment types (exons etc.), ordered by sequence position so
+         * exon-1..exon-14 read left-to-right; colored by alternating shade and
+         * labeled by number rather than each getting a distinct hue + legend row
+         */
+        get segmentDomainTypes() {
+            return [...self.tidyInterProAnnotationTypes.values()]
+                .filter(d => segmentFeatureTypes.has(d.featureType ?? ''))
+                .toSorted((a, b) => a.start - b.start);
+        },
+        /**
+         * #getter
+         * categorical feature types (InterPro domains and the like) that each get
+         * their own color and a legend entry
+         */
+        get categoricalDomainTypes() {
+            return [...self.tidyInterProAnnotationTypes.values()].filter(d => !segmentFeatureTypes.has(d.featureType ?? ''));
+        },
         get fillPalette() {
-            return createPaletteMap([...self.tidyInterProAnnotationTypes.keys()]);
+            const segments = Object.fromEntries(this.segmentDomainTypes.map((d, i) => [
+                d.accession,
+                segmentShades[i % segmentShades.length],
+            ]));
+            const categorical = createPaletteMap(this.categoricalDomainTypes.map(d => d.accession));
+            return { ...segments, ...categorical };
         },
         get strokePalette() {
             return transform(this.fillPalette, ([key, val]) => [
@@ -1400,6 +1458,50 @@ function stateModelFactory() {
                 colord(val).darken(0.1).toHex(),
             ]);
         },
+        /**
+         * #getter
+         * accession -> number drawn on each segment band: the trailing number of
+         * the feature name ("exon-3" -> "3"), else its 1-based position
+         */
+        get segmentLabels() {
+            return new Map(this.segmentDomainTypes.map((d, i) => {
+                const m = /(\d+)\s*$/.exec(d.name);
+                return [d.accession, m ? m[1] : `${i + 1}`];
+            }));
+        },
+        /**
+         * #getter
+         * the domain types currently drawn on the alignment (filtered-on), shared
+         * by the on-screen legend and the SVG export legend. Ordinal segments
+         * (exons) are excluded — they read as a numbered gene model, not a color
+         * key — so this is the categorical types ordered by sequence position
+         */
+        get visibleDomainTypes() {
+            return this.categoricalDomainTypes
+                .filter(d => self.featureFilters.get(d.accession))
+                .toSorted((a, b) => a.start - b.start);
+        },
+        /**
+         * #getter
+         * domain annotations under the mouse, hit-tested against the exact visible
+         * column span each box is drawn at (so it matches the overlay across gaps)
+         */
+        get mouseOverDomains() {
+            const { mouseCol } = self;
+            const name = self.mouseOverRowName;
+            if (name !== undefined && mouseCol !== undefined) {
+                const entry = self.tidyFilteredGatheredInterProAnnotations[name] ?? [];
+                return entry.filter(d => {
+                    const m1 = self.seqPosToVisibleCol(name, d.start - 1);
+                    const m2 = self.seqPosToVisibleCol(name, d.end);
+                    return (m1 !== undefined &&
+                        m2 !== undefined &&
+                        mouseCol >= m1 &&
+                        mouseCol < m2);
+                });
+            }
+            return [];
+        },
         /**
          * #method
          */
@@ -1462,14 +1564,8 @@ function stateModelFactory() {
          * #action
          */
         fit() {
-            if (self.numRows > 0) {
-                self.rowHeight = clamp(self.msaAreaHeight / self.numRows, minRowHeight, maxCellSize);
-            }
-            if (self.numColumns > 0) {
-                self.colWidth = clamp(self.msaAreaWidth / self.numColumns, minColWidth, maxCellSize);
-            }
-            self.scrollX = 0;
-            self.scrollY = 0;
+            this.fitVertically();
+            this.fitHorizontally();
         },
         /**
          * #action
@@ -1490,6 +1586,12 @@ function stateModelFactory() {
             self.scrollX = 0;
         },
         afterCreate() {
+            // seed the highlighted-columns overlay from the declarative property so
+            // a shared snapshot/URL opens with those columns highlighted (the
+            // volatile highlightedColumns can later be driven by genome-hover sync)
+            if (self.highlightColumns?.length) {
+                self.setHighlightedColumns(self.highlightColumns);
+            }
             addDisposer(self, autorun(() => {
                 for (const key of self.tidyInterProAnnotationTypes.keys()) {
                     this.initFilter(key);