Creates a new volcano trace.
The MAIDR layer carrying the points
Protected ReadonlyobserversProtectedisProtectedisTrue while AbstractTrace.getStateAt computes state at a temporarily moved cursor. Enforces (structurally, not just by documentation) that state getters never notify observers.
Protected ReadonlyidProtected ReadonlytypeProtected ReadonlytitleProtected ReadonlynameWhat this layer is, when the producer named it. See MaidrLayer.name.
Protected ReadonlyxProtected ReadonlyyProtected ReadonlyzProtected ReadonlynavigationProtected ReadonlylayerProtected ReadonlymovableProtected ReadonlysupportsAbstract property that subclasses must implement to indicate extrema support
ProtectedhighlightProtected ReadonlyflatProtected so a subclass can read the points themselves. A volcano plot needs each point's identity and whether it clears a threshold, neither of which is a coordinate.
Protected ReadonlyreadingProtected ReadonlyreadingProtected alongside readingOrder: it is the precomputed inverse of it,
and a subclass filtering the reading order needs O(1) position lookups
rather than a linear scan per keystroke.
ProtectedisProtectedpointProtectedisWhether the cursor has no point to report.
Read from dimension rather than from any one trace's data,
because that is the one shape every trace already answers in. It is also
evaluated at the cursor — LineTrace returns the current series'
length as cols — so this covers a ragged layer, where one series has
points and another has none, and not only a layer that is empty
throughout.
True when there is nothing at (row, col) to describe
Gets the current state of the trace including audio, braille, text, and highlight information.
The current TraceState
ProtectedautoplayThe trace's chart type. Lightweight alternative to reading
state.traceType, which eagerly computes the full audio/braille/text/
highlight state just to expose this one string.
ProtectedhighlightReturns the appropriate highlight elements based on current navigation mode.
SVG elements for X-based or Y-based highlighting depending on mode
ProtectedvaluesProtectedbrailleProtectedaudioProtecteddimensionProtectedhighlightThe points the highlight currently covers, as indices into this layer's
data array.
This is highlight answered in a renderer-neutral currency. highlight
resolves the same five navigation modes into SVGElements, which a canvas
chart has none of — so a canvas adapter is handed back an index into the
data array it supplied, and inverts it against its own extraction walk.
That keeps the binning here, in the model that owns it: the adapter never
learns what a grid cell or an x-bucket is.
Deliberately not gated on SVG availability, where highlight falls back to
out-of-bounds when the binder supplied no elements. A canvas chart has no
elements by definition, and that is exactly the case this exists to serve.
Returns an empty array when nothing is addressed, which a consumer reads as "clear the overlay".
Indices into layer.data, in no particular order.
ProtectedhasProtectedoutReturns out-of-bounds state with the position the active navigation mode is actually on, so the boundary chime pans from where the user is.
Grid, point and intersection mode each keep their own cursor; the base implementation pans by row/col, which in those modes is the stale cursor from before the mode was entered.
ProtectedtextGets the description state for the scatter trace.
The description state containing chart metadata and data table
ProtectedgetGets safe row and column indices to prevent accessing undefined values
Object with safe row and column indices
Registers an observer to receive state updates.
The observer to add
Removes an observer from receiving state updates.
The observer to remove
Notifies all registered observers with the current state.
Notifies observers that an out-of-bounds condition occurred.
Base implementation of navigation in HIGHER and LOWER modes of ROTOR, default is no-op Needs to be implemented in Line, Bar, Heatmap, Candlestick
Utility function to compare point values for rotor functionality
boolean value
Returns the rotor's compare-mode labels and boundary-message nouns. Override to rename the two compare units for a trace-specific semantic (e.g., the candlestick delta layer uses "above line" / "below line").
Get all highlight SVG elements for this trace Used by HighlightService for high contrast mode
Array of all SVG elements, or empty array if none
Get all original (visible) SVG elements for this trace. These are the actual rendered elements, not the hidden clones used for highlighting. Used by HighlightService for high contrast mode color changes.
Array of all original SVG elements, or empty array if none
Resets the trace to initial entry state
ProtectedgetReturns a human-readable label for this trace's chart type (e.g., 'Bar Chart', 'Scatter Plot') for display in the description modal. Falls back to the raw layer type if no mapping is registered.
ProtectedgetBuilds the axes object for the description state, including z only when the layer explicitly provides a z-axis label. Subclasses should call this instead of constructing the axes object inline so charts without a real z dimension don't surface the placeholder default.
Get available extrema targets for the current navigation context
Array of extrema targets that can be navigated to Default implementation returns empty array (no extrema support)
Base implementation for navigateToExtrema Subclasses must override to provide actual implementation
The extrema target to navigate to
ProtectedfinalizeCommon post-navigation cleanup that should be called by subclasses after they update their internal state
ProtectedupdateDefault implementation for updating visual point position Subclasses can override if they need custom positioning logic
Checks if this plot supports extrema navigation.
True if extrema navigation is supported
Base implementation for getting current X value Subclasses can override if they have different data structures
Moves to a specific X value in the trace.
The X value to navigate to
True if the move was successful, false otherwise
Gets the unique identifier for this trace.
The trace ID
Moves the active point to the pointer location and returns directional guidance toward the nearest data geometry in a single call.
Combining both operations avoids running findNearestPoint twice per
pointermove event — important on dense plots where the scan is the
hot path.
Screen-space x position of the pointer/finger
Screen-space y position of the pointer/finger
Guidance state relative to nearest point, or null when unavailable
Checks if the specified coordinates are within bounds of the element.
The x-coordinate
The y-coordinate
Object containing the SVG element and its position
True if the point is in bounds, false otherwise
Cleans up resources and removes all highlight elements from the DOM.
ProtectedgetReturns an empty object to avoid grouping scatter points by audio tone.
Empty object without groupIndex to maintain consistent audio feedback
ProtectedhandleInitializes scatter plot navigation at the origin in column mode.
Checks if movement in the specified direction is possible from current position.
Direction or coordinate to check
True if movement is possible, false otherwise
Returns true if this trace supports compare (lower/higher value) navigation. Override to false for trace types that don't use compare modes (e.g., scatter, which is all we currently have).
Returns the display name for the default data navigation mode. Override to provide a trace-specific name (e.g., "ROW AND COLUMN NAVIGATION" for scatter).
Checks if currently in grid cell mode (navigating points within a cell).
Enters grid cell mode to navigate points within the current cell. Groups cell points by X coordinate (like COL mode) for navigation.
true if entered successfully, false if no points in cell
Exits grid cell mode and returns to grid navigation.
Moves to the previous point within the current grid cell.
true if moved, false if at boundary
Moves to the next X-grouped point within the current grid cell.
true if moved, false if at boundary
Gets the current point index within the cell (0-indexed).
Gets the total number of X-grouped points in the current grid cell.
Gets the current X-grouped point within the grid cell.
Mirrors LineTrace's intersection rule: the mode is offered only when navigating across the data is meaningful. For scatter, that means a stack exists on either axis — either an x with multiple ys (column stack) or a y with multiple xs (row stack). Either base mode (COL / ROW) can enter the rotor and cycle through its corresponding stack, so the capability check is the OR of both.
Called by the rotor service when entering / leaving INTERSECTION_MODE. Preserve the active NavMode: entering from COL cycles through the y-stack at the current x; entering from ROW cycles through the x-stack at the current y. Force-switching modes here would silently re-anchor the user on a different point set — the bug fixed by this commit.
No notifyStateUpdate(): mirrors setPointMode and setGridMode; the rotor announces the mode name and the next arrow press emits the focused state.
Walks one step forward through the current stack — y values at the current x in COL mode, x values at the current y in ROW mode. Returns false at the top of the stack so the rotor can announce the boundary; no chime (consistent with LineTrace's intersection bounds).
Walks one step backward through the current stack.
Returns true if this trace supports point-by-point navigation mode. Opt-in per trace type: override to return true for traces that expose individual data points navigable in reading order (left/right) and column-major order (up/down). Currently only ScatterTrace.
Enters or exits point-by-point navigation mode.
On entry, the current point is seeded from whatever ROW_COL position the user was on so they keep their place in the data. When the previous mode highlighted a group of points (e.g. a column of points sharing an x in COL mode), we pick the first point in reading order from that group — highest y for COL mode, lowest x for ROW mode.
On exit, no state needs to be unwound; the existing row/col indices are untouched while in point mode, so ROW_COL navigation resumes where it left off.
ProtectedmapConverts SVG elements to center coordinates for proximity-based navigation.
Array of center points with coordinates and indices, or null if unavailable
Finds the nearest scatter point to the given screen coordinates.
The x-coordinate in screen space
The y-coordinate in screen space
The nearest point with its element and indices, or null if unavailable
Reads state at an explicit cursor, with the trace-local navigation modes suspended for the duration.
getStateAt moves row/col and reads the state getters, but point and
intersection mode short-circuit those getters onto their own cursor — so a
live-appended point would be announced as whichever point the user happens
to be focused on. Suspending the flags makes the read positional again,
which is what every caller of this method asks for.
Row index to read at
Column index to read at
The trace state at that position
ProtectedmoveMoves the trace to the nearest point when the pointer is within its bounds and the trace is not already focused on that point.
onCurve is intentionally non-optional: the caller has already paid
the cost of isPointInBounds to assemble guidance state, and
forcing subclasses to accept the value makes the contract explicit so a
future override cannot silently recompute (or worse, ignore) it.
Subclasses override this to customise hover-driven navigation:
Offers the significant points when the chart declares a threshold.
Withheld when no threshold is declared -- there is nothing to filter on -- and withheld when one is declared but nothing clears it, since a mode whose only possible answer is "none found" is worse than not offering it. That second case is a real reading of the chart, and the description says so in words.
The significant unit alongside whatever the scatter offers
Moves within an active rotor filter unit along the filtered axis.
Called by RotorNavigationService when the current rotor mode is
one of this trace's getRotorFilterUnits. Filter units navigate a
single axis, so only left/right are dispatched here — the service
announces up/down as unavailable without calling the model (matching
intersection mode). Implementations should move to the nearest point
matching the unit identified by key and notify observers, returning
true; when no such point exists they should call notifyRotorBounds
and return false.
Default is a no-op that reports bounds, so a trace advertising a filter unit but forgetting to implement movement fails safe (announces "no point found") rather than moving unexpectedly.
True if the cursor moved, false otherwise
Trace implementation for volcano and Manhattan plots.
A volcano puts effect size against significance; a Manhattan puts genomic position against it. Both are scatters, so the navigation, the pitch and the braille all transfer -- and both are read almost entirely through a threshold, which is what a scatter has no notion of.
Point-by-point navigation is not a viable path here. These charts routinely carry tens of thousands of points of which a few dozen matter. A reader who has to walk them has not been given access to the chart; they have been given a very long list. So two things carry the weight:
The summary on entry. "43 of 12,000 points above the significance threshold" is the first thing a sighted reader takes from the shape of the cloud, and the last thing a per-point reading would ever assemble.
A rotor filter over the points that clear it, so the few dozen that matter are reachable in a few dozen keystrokes rather than twelve thousand.
Identity is the payload. A reader told "x is 2.3, y is 14.1" has been given the two numbers the axes already describe and withheld the one thing they came for, which is which gene that is. The label travels as an aside, so it survives every one of the scatter's navigation modes and is never run through an axis formatter -- a gene name is not a value on an axis.
The threshold is declared, never guessed. These charts sit on transformed axes whose conventions differ by field and by tool: -log10(p) at 1.3 for p < 0.05, at 7.3 for genome-wide significance, and a raw p axis runs the other way entirely. A guessed line would sort every point on the figure onto the wrong side of it, silently. A layer that declares none gets the scatter's reading and no claim about significance.