Skip to content

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.

  1. 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.
  2. A nested grid. The spatialGrid option 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 right

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 ​

Chart

Text chat (works on touch screens)

Inspector (tree view)

Current node: none

How it is built ​

js
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' }
    }
});
js
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: [] }
    }
});
js
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 ​

OptionWhat it does
type: 'numerical'Bins the field by value.
createNumericalSubdivisions: 4Four 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 ​

OptionWhat it does
xKey, yKeyThe two numerical fields.
xExtent, yExtentThe full range to split. Defaults to the data's min and max.
levelsCells 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.
skipEmptytrue (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.

js
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 ​

ChartData pointGroups
Scatter (ranges)Circle on the dotA vertical band for an x range, a horizontal band for a y range
Heatmap (nested grid)Box around the cellA box around each region, smaller at each zoom level
Scatter (nested grid)Circle on the dotA 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.

js
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.

Released under the MIT License.