Read the map
A Mantis map is a two-dimensional picture of a high-dimensional embedding. Every row of your data becomes a point, similar rows land near each other, and a hierarchy of clusters is drawn on top with generated labels. This page explains what each mark on the canvas actually means, and ends with the one caveat that changes how you should read all of it.
Points
One point is one record: a CSV row, a document, a molecule, a cell. It carries a title, its original metadata, and a pair of coordinates produced by the projection step. Hover a point and its title appears in a small label with a thin leader line back to the point.
Large maps are not drawn in full. The map renders a representative sample sized to a per-viewport budget that the server sets, and you can raise or lower it under Settings > Viewport sampling. If a rare point seems to be missing from a dense region, raise the budget before concluding it is not there.
Clusters, labels and depth
Clustering runs on the embeddings during synthesis and produces a tree, not a flat partition. Each cluster has a parent, a depth, a center, a color and a label. Labels are written by a language model from a sample of the cluster’s points, and the prompt is given the parent’s label and the children’s labels, so a child label is deliberately more specific than its parent and a parent label generalizes over its children.
The map shows one horizontal slice of that tree at a time. Zooming in moves the slice deeper, so labels get more specific as you go in and coarser as you pull out. The Cluster Depth slider in Settings offsets that slice: raise it to see finer clusters at the same zoom. Clusters shallower than the current slice that have no descendants at that depth stay on screen, so leaf clusters never disappear just because you zoomed past them.
Click a cluster label to take its whole subtree as your selection. Double-click it to focus: everything outside that subtree dims and the camera moves to fit it. If a lasso, path or magic lasso tool is active instead of Select, clicking a label turns that subtree into a bag rather than a selection.
Local Labels in Settings adds up to 20 individual point titles inside dense areas. It is 0 by default.
Boundaries
The Boundaries control (bottom-left on the default Map panel) has three settings:
- Hull draws a concave hull around each visible cluster’s points. This is the default, and it is the honest one: the outline follows where the points are.
- Territory draws Voronoi cells around cluster centers instead. Every part of the canvas gets assigned to some cluster, including empty space, so a large territory does not mean a large cluster.
- Off stops building outlines entirely, including the background worker.
Boundaries turn themselves off by default on maps over 100,000 points, and on spatial single-cell maps, to keep interaction responsive. Show Cluster Boundaries and Show Cluster Counters in Settings toggle boundaries and labels back on.
Color
The Color control sets what point color encodes. Clusters is the default: each point takes its leaf cluster’s color, so color and spatial grouping agree and color tells you nothing new.
Pick a categorical column instead and each distinct value gets its own swatch, listed under the picker. Pick a numeric or date column and points are mapped onto a continuous gradient with the minimum and maximum printed under the bar. This is where color starts doing work: coloring by a metadata field you did not embed tells you whether that field lines up with semantic structure.
Two other things also write point color, and they override the strategy while active: the Heatmap tool and the Localized Error panel, both described below.
Bags on the map
Points that belong to a highlighted bag get concentric colored rings. A point in several highlighted bags shows several rings, up to three. Bags that are not highlighted in the Bags panel draw nothing, which is why saving a bag can look like nothing happened. See Selections and bags.
2D and 2.5D
The View control switches between 2D and 2.5D. There is no 3D mode; the toggle for it is commented out in the source.
- 2D is a flat orthographic view. Left-drag pans, the wheel zooms toward the cursor.
- 2.5D tilts the same plane and adds depth sorting. Left-drag still pans; right-drag orbits the camera.
2.5D does not add a third data dimension. Point height stays at zero unless a gradient field is active, in which case height samples that field. Without a gradient, 2.5D is the same two coordinates seen from an angle.
The minimap
The minimap sits bottom-right by default. It draws the whole map, using cluster boundaries when they are on and a subsampled point cloud when they are not, plus a rectangle for your current viewport. Click or drag inside it to recenter the main view. Drag the widget itself to move it, and hide it with Show minimap in Settings.
The one caveat: 2D distance is a projection
Heads up
Two points sitting next to each other on screen are not necessarily neighbors in the embedding. UMAP, t-SNE and PCA all compress hundreds or thousands of dimensions into two, and that compression has to break something. Read position as a strong hint, never as a measurement.
Mantis ships tools that give you the real number instead of the visual one. All of them compute on the server against the raw high-dimensional vectors.
- Semantic Ruler (R) measures two points. Click one point, then a second, and the map draws a dashed line with the cosine similarity of their raw embeddings printed at the midpoint. The ruler is currently implemented on Map (Legacy) only.
- Heatmap (H) measures one point against everything. Click an anchor and every other point is recolored by its cosine similarity to that anchor. Two visually adjacent regions that come back in very different colors are not actually adjacent. This tool works on the default Map panel.
- The Localized Error panel measures the projection itself, in three modes: Aggregate error recolors points by how much their high-dimensional distances disagree with their 2D distances; False neighbors draws edges between points placed close in 2D but far in high dimensions; Missing neighbors takes your selection and links out to the true neighbors the projection scattered away.
If a cluster boundary or an apparent gap is about to drive a conclusion, spend thirty seconds with the ruler or the heatmap first.
Limits
- A lasso, magic lasso or path commit is capped at 25,000 points. The excess is dropped silently, with only a console warning.
- Cluster outlines are built from at most 4,000 sampled points per cluster.
- The Semantic Ruler, Waypoint, Journey and hand-gesture control have not been ported to the default Map panel yet; open Map (Legacy) from View > Exploration for those.