react-msaview 8.2.0 → 8.3.0

package/dist/model.d.ts

@@ -2,11 +2,13 @@ import type { ColumnStats } from './columnStats.ts';
 import type { ScrollZoomAxis } from './constants.ts';
 import type { HierarchyNode } from './hierarchy.ts';
 import type { ExportSvgOptions } from './renderToSvg.tsx';
-import type { Annotation, Arc, BasicTrack, Cell, Clade, ResidueMappingProblem, ColumnTrackSpec, DomainBand, Encoding, Highlight, Legend, NodeWithIds, NodeWithIdsAndLength, Region, ResidueMapping, ResolvedClade, ResolvedEncoding, ResolvedHighlight, ResolvedRowPanel, RowPanelSpec, RowResidue, StructureResidue, TrackKind, UnshareableData, Viewport } from './types.ts';
+import type { Annotation, Arc, BasicTrack, Cell, Clade, ResidueMappingProblem, ColumnTrackSpec, DomainBand, Encoding, Highlight, Legend, NodeWithIds, Region, ResidueMapping, ResolvedClade, ResolvedEncoding, ResolvedFeaturePanel, ResolvedHighlight, TreeOrder, TreeRoot, ResolvedRowPanel, ResolvedStripPanel, RowPanelSpec, RowResidue, StructureResidue, TrackKind, UnshareableData, Viewport } from './types.ts';
 import type { FileLocation as FileLocationType } from '@jbrowse/core/util/types';
 import type { Instance } from '@jbrowse/mobx-state-tree';
 import type { InterProScanResults } from 'msa-parsers';
 export declare const defaultTrackHeights: Partial<Record<TrackKind, number>>;
+type StripPanelScale = Omit<ResolvedStripPanel, 'id' | 'width' | 'offsetX'>;
+type FeaturePanelScale = Omit<ResolvedFeaturePanel, 'id' | 'width' | 'offsetX' | 'spans'>;
 /**
  * The snapshot properties reset() carries across a return to the import form:
  * display preferences and layout, nothing derived from the loaded file.
@@ -40,12 +42,13 @@ export declare const preservedOnReset: Set<string>;
  * root.view.setData({ msa: '>seq1\nACGT\n>seq2\nACGT' })
  * ```
  */
-declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelType<Omit<Omit<Omit<{}, "autoTreeAreaWidth" | "drawLabels" | "drawNodeBubbles" | "drawNodeLabels" | "drawTree" | "labelsAlignRight" | "overviewHeight" | "showBranchLen" | "showTreeOverview" | "treeAreaWidth" | "treeWidth"> & {
+declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelType<Omit<Omit<Omit<{}, "autoTreeAreaWidth" | "drawLabels" | "drawNodeBubbles" | "drawNodeLabels" | "drawTree" | "labelsAlignRight" | "overviewHeight" | "showBranchLen" | "showTreeOverview" | "treeAreaWidth" | "treeOrder" | "treeWidth"> & {
     drawLabels: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<boolean>, [undefined]>;
     labelsAlignRight: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<boolean>, [undefined]>;
     treeAreaWidth: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<number>, [undefined]>;
     treeWidth: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<number>, [undefined]>;
     showBranchLen: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<boolean>, [undefined]>;
+    treeOrder: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<TreeOrder>, [undefined]>;
     drawTree: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<boolean>, [undefined]>;
     drawNodeBubbles: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<boolean>, [undefined]>;
     drawNodeLabels: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<boolean>, [undefined]>;
@@ -57,7 +60,7 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
     colorSchemeName: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<string>, [undefined]>;
     showColumnStats: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<boolean>, [undefined]>;
     msaFormat: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").ISimpleType<import("msa-parsers").MSAFormat>>;
-}, "allowedGappyness" | "clades" | "colWidth" | "collapsed" | "columnTracks" | "currentAlignment" | "data" | "drawMsaLetters" | "encodings" | "gffFilehandle" | "height" | "hideGaps" | "highlightColumns" | "highlights" | "id" | "msaFilehandle" | "region" | "relativeTo" | "residueMappings" | "rowHeight" | "rowPanels" | "scrollX" | "scrollY" | "scrollZoom" | "scrollZoomAxis" | "showDomainLegend" | "showDomains" | "showOnly" | "subFeatureRows" | "trackHeights" | "treeFilehandle" | "treeMetadataFilehandle" | "turnedOffFeatures" | "turnedOffTracks" | "type"> & {
+}, "allowedGappyness" | "clades" | "colWidth" | "collapsed" | "columnTracks" | "currentAlignment" | "data" | "drawMsaLetters" | "encodings" | "gffFilehandle" | "height" | "hideGaps" | "highlightColumns" | "highlights" | "id" | "msaFilehandle" | "region" | "relativeTo" | "residueMappings" | "rotated" | "rowHeight" | "rowPanels" | "scrollX" | "scrollY" | "scrollZoom" | "scrollZoomAxis" | "showDomainLegend" | "showDomains" | "showOnly" | "subFeatureRows" | "trackHeights" | "treeFilehandle" | "treeMetadataFilehandle" | "treeRoot" | "turnedOffFeatures" | "turnedOffTracks" | "type"> & {
     /**
      * #property
      * id of view, randomly generated if not provided
@@ -533,6 +536,20 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
      * hidden)
      */
     collapsed: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").ISimpleType<string>>, [undefined]>;
+    /**
+     * #property
+     * tree nodes whose children draw in reverse order, which is ggtree's
+     * `rotate`: the same tree, with the clades on either side of the node
+     * swapped
+     */
+    rotated: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").ISimpleType<string>>, [undefined]>;
+    /**
+     * #property
+     * where the tree is rooted: `midpoint` roots it halfway along the
+     * longest path between two tips, `{outgroup}` on the branch above
+     * the tips named, and undefined keeps the file's root
+     */
+    treeRoot: import("@jbrowse/mobx-state-tree").IType<TreeRoot | undefined, TreeRoot | undefined, TreeRoot | undefined>;
     /**
      * #property
      * focus on particular subtree
@@ -629,7 +646,8 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
      * clades of the tree with a mark drawn over them. `mrca` names tips
      * whose common ancestor is the clade, or `range` its first and last
      * tip in display order, and `tips` is the leaf count the producer
-     * measured. `mark` is `highlight`, `bracket`, `collapse` or `focus`.
+     * measured. `mark` is `highlight`, `bracket`, `collapse`, `focus` or
+     * `rotate`.
      * See docs/layers.md
      */
     clades: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").IType<Clade, Clade, Clade>>, [undefined]>;
@@ -664,6 +682,7 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
     setDrawTree(arg: boolean): void;
     setAutoTreeAreaWidth(arg: boolean): void;
     setShowBranchLen(arg: boolean): void;
+    setTreeOrder(order: TreeOrder): void;
     setDrawNodeBubbles(arg: boolean): void;
     setDrawNodeLabels(arg: boolean): void;
     setShowTreeOverview(arg: boolean): void;
@@ -774,9 +793,15 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
      * #volatile
      * non-fatal load problems: an optional layer that failed to load, an
      * overlay that failed to parse. `error` replaces the view and is for the
-     * alignment itself
+     * alignment itself. `warnings` adds the ones derived from the data
      */
-    warnings: string[];
+    loadWarnings: string[];
+    /**
+     * #volatile
+     * derived warnings the user dismissed, which stay hidden while the data
+     * behind them holds
+     */
+    dismissedWarnings: string[];
     /**
      * #volatile
      * bumped by reset(). The error boundary above the view uses it as its key,
@@ -846,10 +871,6 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
      * that failed to parse. A message already on the list is not added again
      */
     addWarning(warning: string): void;
-    /**
-     * #action
-     */
-    clearWarnings(): void;
     /**
      * #action
      * declare that this host restores the loaded documents itself, which
@@ -930,8 +951,9 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
     /**
      * #action
      * switch to another alignment of a multi-alignment file (Stockholm).
-     * Clears the collapsed node ids, the subtree in focus, the reference row
-     * and the scroll position, which all refer to the previous alignment
+     * Clears the collapsed and rotated node ids, the subtree in focus, the
+     * reference row and the scroll position, which all refer to the
+     * previous alignment
      */
     setCurrentAlignment(n: number): void;
     /**
@@ -939,6 +961,21 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
      * collapse or un-collapse the subtree rooted at the given tree node id
      */
     toggleCollapsed(node: string): void;
+    /**
+     * #action
+     * reverse the order of the given node's children, or restore it
+     */
+    toggleRotated(node: string): void;
+    /**
+     * #action
+     */
+    clearRotated(): void;
+    /**
+     * #action
+     * reroot the tree. Clears `collapsed`, `rotated` and `showOnly`, whose
+     * path-derived node ids name other nodes in the rerooted tree
+     */
+    setTreeRoot(treeRoot?: TreeRoot): void;
     /**
      * #action
      * show only the subtree rooted at the given node id (pass undefined to
@@ -1058,12 +1095,13 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
      * from disk or pasted in becomes inline text, and DataModel drops an
      * inline document past `maxInlineSnapshotBytes`.
      *
-     * The header lists these, and the standalone app stops rewriting the
-     * address bar while the list is non-empty, so a copied link does not
-     * open an empty viewer unannounced. A document fetched from a URL never
-     * appears here, since the snapshot keeps its filehandle.
+     * The header lists these, and the standalone app drops `?data=` from
+     * the address bar while the list is non-empty or the encoded link would
+     * pass 8,000 characters, so a copied link never opens an empty viewer
+     * unannounced. A document fetched from a URL never appears here, since
+     * the snapshot keeps its filehandle.
      *
-     * Empty when `hostRestoresData` is true.
+     * Empty when `hostCarriesData` is true.
      */
     readonly unshareableData: UnshareableData[];
     menuItems(): never[];
@@ -1098,6 +1136,14 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
     readonly numColumns: number;
     /**
      * #getter
+     * the tree the file or the alignment gives, before `treeRoot`
+     */
+    readonly inputTree: NodeWithIds;
+    /**
+     * #getter
+     * the tree as the file or the alignment gives it, rerooted where
+     * `treeRoot` asks. Every node id, and so `collapsed`, `rotated` and
+     * `showOnly`, refers to this tree.
      */
     readonly tree: NodeWithIds;
     /**
@@ -1115,8 +1161,8 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
      * `clades` resolved to the rows each one covers. The tip names resolve
      * against `tree` rather than `root`, so a clade whose ancestor the user
      * collapsed keeps its rows. One leaf pass over the tree serves every
-     * clade. A `range` record names no node, so `collapse` and `focus`, which
-     * need one, drop it.
+     * clade. A `range` record names no node, so `collapse`, `focus` and
+     * `rotate`, which need one, drop it.
      */
     readonly resolvedClades: ResolvedClade[];
     /**
@@ -1143,6 +1189,12 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
      * #getter
      */
     readonly root: HierarchyNode<NodeWithIds>;
+    /**
+     * #getter
+     * the tree as Newick in the order and with the root it is drawn, with
+     * every clade, collapsed or out of focus
+     */
+    readonly treeNewick: string;
     /**
      * #getter
      * height of the band the tree overview draws in, zero when it is off
@@ -1308,9 +1360,21 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
     readonly propertyConservation: number[];
     /**
      * #getter
-     * generates a new tree that is clustered with x,y positions
+     * `root` laid out on new nodes in row and branch-length units, read in
+     * pixels through `rowHeight` and `treeWidth`. A zoom leaves it and every
+     * node in it as they are, and an observer reading a node's `x` or `len`
+     * observes the size it scales by.
      */
-    readonly hierarchy: HierarchyNode<NodeWithIdsAndLength>;
+    readonly treeLayout: {
+        root: import("./hierarchy.ts").LaidOutNode<NodeWithIds>;
+        leaves: import("./hierarchy.ts").LaidOutNode<NodeWithIds>[];
+        rootToTipLength: number;
+    };
+    /**
+     * #getter
+     * the laid-out tree, with pixel positions on every node
+     */
+    readonly hierarchy: HierarchyNode<NodeWithIds>;
     /**
      * #getter
      */
@@ -1318,7 +1382,7 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
     /**
      * #getter
      */
-    readonly leaves: HierarchyNode<NodeWithIdsAndLength>[];
+    readonly leaves: HierarchyNode<NodeWithIds>[];
     /**
      * #getter
      * branch-length extent of the displayed tree, root to farthest tip, in
@@ -1411,10 +1475,6 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
      * #getter
      */
     readonly secondaryStructureConsensus: string | undefined;
-    /**
-     * #getter
-     */
-    readonly seqConsensus: string | undefined;
     /**
      * #getter
      * the base pairs of the consensus secondary structure, as arcs, in
@@ -1449,11 +1509,13 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
     readonly showHorizontalScrollbar: boolean;
     /**
      * #method
-     * Return a row-specific letter at a visible column, or undefined if gap.
+     * Return the character a row holds at a visible column: a residue, or
+     * the gap character (`-` or `.`) on a gap. Undefined for a row name the
+     * alignment does not have or a column past the row's end.
      *
      * @param rowName - The name of the row
      * @param visibleCol - The visible column index (what the user sees on screen)
-     * @returns The letter at that position, or undefined if it's a gap
+     * @returns The character at that position
      */
     visibleColToRowLetter(rowName: string, visibleCol: number): string | undefined;
     /**
@@ -1511,6 +1573,16 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
      * @returns The global column index in the full MSA, or undefined
      */
     seqPosToGlobalCol(rowName: string, seqPos: number): number | undefined;
+    /**
+     * #method
+     * the global column of a span's last residue, clamping a position past
+     * the end of the row to its last residue. Undefined for a row name the
+     * alignment does not have, or a row with no residues.
+     *
+     * @param rowName - The name of the row
+     * @param seqPos - The sequence position (0-based, ungapped)
+     */
+    seqEndToGlobalCol(rowName: string, seqPos: number): number | undefined;
     /**
      * #method
      * Convert a sequence position (ungapped) directly to a visible column index.
@@ -1636,6 +1708,22 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
      */
     readonly blocksY: number[];
 } & {
+    /**
+     * #getter
+     */
+    readonly verticalScrollbarWidth: 0 | 20;
+    /**
+     * #getter
+     * width of the alignment canvas: the msa area less the vertical
+     * scrollbar. showHorizontalScrollbar must not read it, since that feeds
+     * msaAreaHeight -> showVerticalScrollbar and would form a cycle
+     */
+    readonly msaCanvasWidth: number;
+    /**
+     * #getter
+     * most-negative allowed scrollX, which keeps the last column in view
+     */
+    readonly maxScrollX: number;
     /**
      * #getter
      */
@@ -1646,8 +1734,16 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
     readonly isLoading: boolean;
     /**
      * #getter
+     * warnings that follow from the loaded data and clear when it changes. A
+     * GFF whose first column names rows of some other alignment parses
+     * without error and draws nothing
      */
-    readonly maxScrollX: number;
+    readonly dataWarnings: string[];
+    /**
+     * #getter
+     * the load warnings and the undismissed data warnings, for the header
+     */
+    readonly warnings: string[];
     /**
      * #getter
      * most-negative allowed scrollY, which keeps the last row in view
@@ -1665,6 +1761,10 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
      * #action
      */
     setDrawMsaLetters(arg: boolean): void;
+    /**
+     * #action
+     */
+    clearWarnings(): void;
     /**
      * #action
      */
@@ -1688,8 +1788,16 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
     calculateNeighborJoiningTreeFromMSA(): void;
     /**
      * #action
-     * swap in a different tree over the same alignment. Clears `collapsed`
-     * and `showOnly`, since path-derived node ids (node-0-0-1) from the old
+     * root the tree on the branch above the given node. The node's tips are
+     * a split of the unrooted tree, and the side of it that is a clade in
+     * the tree as written stands for it as an outgroup, by its first and
+     * last tip, so the root survives the path ids changing under it
+     */
+    rerootAt(nodeId: string): void;
+    /**
+     * #action
+     * swap in a different tree over the same alignment. Clears `collapsed`,
+     * `rotated` and `showOnly`, since path-derived node ids (node-0-0-1) from the old
      * tree would match unrelated nodes in the new one.
      */
     replaceTree(newick: string): void;
@@ -1698,6 +1806,11 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
      * restore the default column width and row height
      */
     resetZoom(): void;
+    /**
+     * #action
+     * zoom by `scaleFactor` about the center of the alignment area
+     */
+    zoomAtCenter(scaleFactor: number, axis?: ScrollZoomAxis): void;
     /**
      * #action
      */
@@ -1805,21 +1918,11 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
         onCancel?: () => void;
     }): void;
 } & {
-    /**
-     * #getter
-     */
-    readonly verticalScrollbarWidth: 0 | 20;
-    /**
-     * #getter
-     * width of the alignment canvas: the msa area less the vertical
-     * scrollbar. showHorizontalScrollbar must not read it, since that feeds
-     * msaAreaHeight -> showVerticalScrollbar and would form a cycle
-     */
-    readonly msaCanvasWidth: number;
     /**
      * #method
      * the cell at a visible column and row index, in the coordinates a host
-     * writes highlights in
+     * writes highlights in. On a gap `residue` is undefined and `letter` is
+     * the gap character
      */
     cellAt(visibleCol: number, rowIndex?: number): Cell;
     /**
@@ -2001,10 +2104,17 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
     readonly resolvedEncodings: ResolvedEncoding[];
     /**
      * #getter
-     * each row panel with its scale resolved against the values its field
-     * takes across the row table, giving the color per row name, the pixel
-     * column it draws in, and the entries its legend lists. Resolved once
-     * per change of that table or the panels, never per block per frame.
+     * each row panel's scale resolved against the values its field takes,
+     * giving the colors, labels and legend entries. Reads no cell size, so
+     * a zoom reuses it and the legends built from it.
+     */
+    readonly rowPanelScales: (StripPanelScale | FeaturePanelScale)[];
+    /**
+     * #getter
+     * each row panel with its scale from `rowPanelScales` and its geometry:
+     * the pixel column it draws in and, for a features panel, the spans per
+     * row. Resolved once per change of those inputs, never per block per
+     * frame.
      */
     readonly resolvedRowPanels: ResolvedRowPanel[];
     /**
@@ -2073,6 +2183,11 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
      * #action
      */
     exportSVG(opts: ExportSvgOptions): Promise<void>;
+    /**
+     * #action
+     * save `treeNewick` as a file
+     */
+    exportNewick(): void;
     /**
      * #action
      * show or hide an annotation type. Only hidden types are recorded; see
@@ -2109,6 +2224,7 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
     treeAreaWidth: number;
     treeWidth: number;
     showBranchLen: boolean;
+    treeOrder: TreeOrder;
     drawTree: boolean;
     drawNodeBubbles: boolean;
     drawNodeLabels: boolean;
@@ -2213,6 +2329,8 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
     } | undefined;
     currentAlignment: number;
     collapsed: string[];
+    rotated: string[];
+    treeRoot: TreeRoot | undefined;
     showOnly: string | undefined;
     turnedOffTracks: import("mobx").IKeyValueMap<boolean>;
     trackHeights: import("mobx").IKeyValueMap<number>;
@@ -2241,6 +2359,7 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
     treeAreaWidth: number;
     treeWidth: number;
     showBranchLen: boolean;
+    treeOrder: TreeOrder;
     drawTree: boolean;
     drawNodeBubbles: boolean;
     drawNodeLabels: boolean;
@@ -2345,6 +2464,8 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
     } | undefined;
     currentAlignment: number;
     collapsed: string[];
+    rotated: string[];
+    treeRoot: TreeRoot | undefined;
     showOnly: string | undefined;
     turnedOffTracks: import("mobx").IKeyValueMap<boolean>;
     trackHeights: import("mobx").IKeyValueMap<number>;