2D Spatial
2D spatial navigation cuts the plot into pieces by position. Use it when both axes are numbers: scatterplots, heatmaps, and maps.
There are two ways to cut the space, and this page shows both.
- Ranges on each axis. The dimensions API bins x into ranges and y into ranges. A point belongs to one x range and one y range. This is a dual tree whose groups are numbers.
- A nested grid. The
spatialGridoption cuts the plot into 4 regions, then each region into 4 more, and so on. A point belongs to one cell at each zoom level.
Shape
Ranges on each axis Nested grid (levels: [2, 4])
Chart Grid
├── Horsepower ├── top left (2x2)
│ ├── 46 to 92 │ ├── 4 cells (4x4)
│ │ └── cars... │ │ └── cars or cells
│ └── ... │ └── ...
└── MPG ├── top right
├── 11 to 20 ├── bottom left
└── ... └── bottom rightNavigate across a whole zoom level
In a nested grid, the arrow keys move to the next box of the same size, even when it sits in a different parent. From the top-right small box of the top-left region, Right goes to the top-left small box of the top-right region. You never have to zoom out to cross a border.
This is levelNavigation: 'across', the default. It is the grid version of extents: 'bridgedCousins' in the dimensions API, where Left and Right at a data point walk every point in x order, across all ranges.
Use 'within' instead if the regions mean something on their own, like countries on a map, and crossing them would be confusing.
Try it
Text chat (works on touch screens)
Inspector (tree view)
Current node: none
How it is built
const structure = dataNavigator.structure({
data: cars,
idKey: 'id',
dimensions: {
parentOptions: { addLevel0: { id: 'chart', edges: [] } },
values: [
{
dimensionKey: 'horsepower',
nodeId: 'horsepower',
type: 'numerical',
operations: { createNumericalSubdivisions: 4 },
divisionOptions: { divisionNodeIds: (key, value) => `hp-${Math.round(value)}` },
// bridgedCousins: Left and Right walk every car in x order, across ranges
behavior: { extents: 'bridgedCousins', childmostNavigation: 'within' },
navigationRules: {
sibling_sibling: ['left', 'right'],
parent_child: ['to-horsepower', 'drill-in']
}
},
{
dimensionKey: 'mpg',
nodeId: 'mpg',
type: 'numerical',
operations: { createNumericalSubdivisions: 4 },
divisionOptions: { divisionNodeIds: (key, value) => `mpg-${Math.round(value)}` },
behavior: { extents: 'bridgedCousins', childmostNavigation: 'within' },
navigationRules: { sibling_sibling: ['down', 'up'], parent_child: ['to-mpg', 'drill-in'] }
}
]
},
// ranges run low to high, so Up moves toward the target (higher MPG)
navigationRules: {
left: { key: 'ArrowLeft', direction: 'source' },
right: { key: 'ArrowRight', direction: 'target' },
down: { key: 'ArrowDown', direction: 'source' },
up: { key: 'ArrowUp', direction: 'target' },
'drill-in': { key: 'Enter', direction: 'target' },
'drill-out': { key: 'Backspace', direction: 'source' },
'to-horsepower': { key: 'KeyW', direction: 'source' },
'to-mpg': { key: 'KeyJ', direction: 'source' }
}
});const structure = dataNavigator.structure({
data: seattleHeat,
idKey: 'id',
spatialGrid: {
xKey: 'highBin',
yKey: 'lowBin',
xExtent: [0, 8],
yExtent: [0, 8],
levels: [2, 4], // 2x2 regions, then 4x4, then the 8x8 cells
leaves: 'cells', // each row is already a heatmap cell
levelNavigation: 'across', // arrows cross region borders at every zoom level
root: { id: 'grid', edges: [] }
}
});const structure = dataNavigator.structure({
data: cars,
idKey: 'id',
spatialGrid: {
xKey: 'horsepower',
yKey: 'mpg',
xExtent: [40, 240],
yExtent: [10, 50],
levels: [2, 4], // 4 regions, then 16 smaller ones, then the cars
leaves: 'points',
levelNavigation: 'across',
skipEmpty: true, // empty regions are skipped
root: { id: 'grid', edges: [] }
}
});Ranges on each axis
| Option | What it does |
|---|---|
type: 'numerical' | Bins the field by value. |
createNumericalSubdivisions: 4 | Four equal ranges per axis. |
extents: 'bridgedCousins' | At a point, sibling keys continue into the next range instead of stopping. |
childmostNavigation: 'within' | Points are ordered by value inside each range. |
navigationRules (top level) | Ranges run low to high, so up points at the target to mean "higher MPG". |
Nested grid
| Option | What it does |
|---|---|
xKey, yKey | The two numerical fields. |
xExtent, yExtent | The full range to split. Defaults to the data's min and max. |
levels | Cells per axis at each zoom level. [2, 4] makes a 2x2 grid, then a 4x4 grid. |
leaves | 'points': rows sit inside the smallest cells (scatterplots). 'cells': each row is a cell (heatmaps). |
levelNavigation | 'across' (default): arrows reach every box at a zoom level. 'within': arrows stay in the parent. |
skipEmpty | true (default): empty boxes are left out, and arrows jump over the gap. |
extents | 'terminal' (default) stops at the plot edge. 'circular' wraps around. |
Up means higher values in a nested grid by default, so you do not need to set the rules yourself.
Labels
A data point names both values. Keys help here, since two bare numbers are easy to mix up: Horsepower 130, MPG 18, chevrolet chevelle malibu. Regions lead with their count and give both ranges: 14 cars, horsepower 40 to 90, MPG 30 to 40. Region.
const n = structure.nodes;
n.grid.semantics = {
label: `All days. ${seattleHeat.length} filled cells in ${structure.spatialGrid.cellsByLevel[0].length} regions.`
};
structure.spatialGrid.cellsByLevel.flat().forEach(id => {
const d = n[id].data;
const [h0, h1] = d.xExtent.map(HIGH);
const [l0, l1] = d.yExtent.map(LOW);
n[id].semantics = {
label: `${d.count} day${d.count === 1 ? '' : 's'}, highs ${deg(h0)} to ${deg(h1)}, lows ${deg(l0)} to ${deg(l1)}. Region.`
};
});
seattleHeat.forEach(d => {
n[d.id].semantics = {
label: `${d.days} day${d.days === 1 ? '' : 's'}, high ${deg(d.highFrom)} to ${deg(d.highTo)}, low ${deg(d.lowFrom)} to ${deg(d.lowTo)}`
};
});Focus indicators
| Chart | Data point | Groups |
|---|---|---|
| Scatter (ranges) | Circle on the dot | A vertical band for an x range, a horizontal band for a y range |
| Heatmap (nested grid) | Box around the cell | A box around each region, smaller at each zoom level |
| Scatter (nested grid) | Circle on the dot | A box around each region |
The bands make the difference between the two approaches easy to see. A range covers a whole strip of the chart. A grid region covers one patch.
n.grid.spatialProperties = rectSpatial(boxes.plot, 4);
structure.spatialGrid.cellsByLevel.flat().forEach(id => {
const { xExtent, yExtent } = n[id].data;
const box = {
x: x(xExtent[0]),
y: y(yExtent[1]),
width: x(xExtent[1]) - x(xExtent[0]),
height: y(yExtent[0]) - y(yExtent[1])
};
n[id].spatialProperties = rectSpatial(box, 0);
});
cars.forEach(d => {
n[d.id].spatialProperties = circleSpatial(dots[d.id].x, dots[d.id].y, dots[d.id].r);
});Need a category too?
Add it as a third dimension. See spatial plus.