Skip to content

Tree ​

A tree groups data points under parents, and parents under their own parents. Each node has exactly one parent.

Use it when the data has one grouping (lines in a multi-line chart) or when the data is a hierarchy itself (a circle packing, a treemap, an org chart).

Shape ​

Cities                         flare
├── New York                   ├── analytics
│   ├── 0 degrees, Jan         │   ├── cluster
│   ├── 2 degrees, Feb         │   │   ├── 3,938 bytes, AgglomerativeCluster
│   └── ...                    │   │   └── ...
├── London                     │   └── graph
└── Sydney                     ├── animate
                               └── display
  • Enter goes down a level. Backspace goes back up.
  • Left and Right move between siblings, nodes with the same parent.
  • A one-grouping tree, like the multi-line chart, has three levels. A hierarchy can be as deep as the data.

Try it ​

Chart

Text chat (works on touch screens)

Inspector (tree view)

Current node: none

How it is built ​

One grouping: the dimensions API ​

The multi-line chart is one categorical dimension, city. Each city becomes a division, and each division holds its points. childmostNavigation: 'within' keeps Left and Right on one line.

js
const structure = dataNavigator.structure({
    data: cities,
    idKey: 'id',
    dimensions: {
        values: [
            {
                dimensionKey: 'city',
                nodeId: 'cities',
                type: 'categorical',
                divisionOptions: { divisionNodeIds: (key, value) => `city-${slug(value)}` },
                // 'within' keeps Left and Right on one line at the data point level
                behavior: { extents: 'circular', childmostNavigation: 'within' },
                navigationRules: {
                    sibling_sibling: ['left', 'right'],
                    parent_child: ['drill-out', 'drill-in']
                }
            }
        ]
    }
});

Any depth: the hierarchy option ​

The dimensions API stops at three levels. For deeper data, pass rows that each name their parent, the same shape d3.stratify reads. Every row becomes a node, including the packages, so you can stop on analytics and hear its total.

js
const structure = dataNavigator.structure({
    data: rows,
    idKey: 'id',
    hierarchy: {
        parentKey: 'parent',
        // biggest first, the same order the packing uses
        sortFunction: (a, b) => b.value - a.value,
        levelNavigation: 'within',
        extents: 'circular',
        navigationRules: {
            sibling_sibling: ['left', 'right'],
            parent_child: ['drill-out', 'drill-in']
        }
    }
});
js
const structure = dataNavigator.structure({
    data: flare,
    idKey: 'id',
    hierarchy: {
        parentKey: 'parent',
        // 'across' links every node at the same depth, even across branches
        levelNavigation: 'across',
        extents: 'terminal',
        // the tree grows to the right, so Left and Right move between parent and child
        navigationRules: {
            sibling_sibling: ['up', 'down'],
            parent_child: ['left', 'right']
        }
    }
});
OptionWhat it does
parentKeyThe field that names each row's parent. The row with an empty parent is the root.
sortFunctionOrders siblings. The circle packing sorts biggest first, like the layout.
levelNavigation'within' (default): sibling keys stay inside one parent. 'across': they reach every node at the same depth.
extents'circular' (default) wraps around. 'terminal' stops at the ends.
navigationRulesKey names for siblings and for parent and child.

Two choices worth copying ​

Level-wide navigation. The tree diagram uses levelNavigation: 'across'. From MergeEdge, the last class in cluster, Down goes straight to BetweennessCentrality in graph. You can read every class without going up and down the tree. Use it when people want to compare all nodes at one depth.

Keys that follow the layout. The tree diagram grows to the right, so Left goes to the parent and Right goes to the first child. Siblings are stacked, so Up and Down move between them. The circle packing has no direction, so it keeps Enter and Backspace.

Labels ​

A leaf leads with its value: 3,938 bytes, AgglomerativeCluster. A parent names itself and sums up what is inside: cluster. 4 items, 15,207 bytes.

js
rows.forEach(d => {
    const node = structure.nodes[d.id];
    node.semantics = {
        label: d.size
            ? `${fmt(d.size)} bytes, ${d.name}`
            : `${d.name}. ${node.childCount} items, ${fmt(d.value)} bytes.`
    };
});

Focus indicators ​

ChartData pointParent
Multi-lineCircle on the pointBand along the line
Circle packingCircle around the circleCircle around the parent's circle
Tree diagramBox around the dot and nameHull around the whole branch

The tree diagram's hull uses convexHullOfCircles over every dot in the branch:

js
const byId = {};
root.descendants().forEach(node => (byId[node.id] = node));
flare.forEach(d => {
    const node = byId[d.id];
    if (node.children) {
        const branch = node.descendants().map(k => dots[k.id]);
        const box = unionBox(branch.map(c => ({ x: c.x - 12, y: c.y - 12, width: 24, height: 24 })));
        structure.nodes[d.id].spatialProperties = spatial(box, convexHullOfCircles(branch, 6));
    } else {
        const c = dots[d.id];
        structure.nodes[d.id].spatialProperties = rectSpatial(
            unionBox({ x: c.x - 4, y: c.y - 4, width: 8, height: 8 }, labels[d.id]),
            3
        );
    }
});

Credits ​

The circle packing and tree diagram follow the D3 gallery's circle packing and tidy tree examples. The data is a trimmed part of the flare class hierarchy those examples use.

Released under the MIT License.