Vega Stratify Transform 深度指南:用父子键把扁平数据构建为树形结构
Vega Stratify Transform 深度指南:用父子键把扁平数据构建为树形结构
Stratify 是 Vega 中负责把"扁平表结构"转换为"层级树结构"的数据转换(transform)。当你的分层数据以"每条记录携带父节点标识"的形式存在时(例如 {id, parent} 两列的表),stratify 会依据 key(节点唯一键)与 parentKey(父节点键)字段生成一套树节点对象,供后续 tree、treemap、pack、partition 等布局变换消费。读完本文,你将掌握 stratify 的参数语义、完整用法示例、底层实现原理,以及如何在真实 Vega 规格中把它接入树形可视化管线。
概述:为什么需要 stratify
Vega 的层级布局变换(tree、treemap、pack、partition)处理的并不是普通的数据对象,而是一套特殊的树节点对象。因此,在使用这些布局之前,必须先有一个"把普通数据变成树"的步骤。
数据变成树有两条路径:
- nest:按分组键的取值自动嵌套出层次(数据本身不包含父指针);
- stratify:显式地使用每条记录的父子键,把扁平记录挂接到对应父节点下。
stratify 适合典型的"父子两列表"数据。例如仓库自带的 flare.json 中,每条记录都有 id 与 parent 两个字段,前者是节点唯一标识,后者指向父节点的 id——这正是 stratify 的标准输入形态。仓库中的 tree-layout.vg.json、circle-packing.vg.json、sunburst.vg.json、treemap.vg.json、radial-tree-layout.vg.json、edge-bundling.vg.json 等示例都采用"stratify → 树布局"的管线。
Transform 参数
stratify 只有两个参数,且都是必填项:
| 属性 | 类型 | 描述 |
|---|---|---|
| key | Field(必填) | 包含每个节点唯一键(标识符)的数据字段 |
| parentKey | Field(必填) | 包含层级中每个节点父节点键值的数据字段。若要表示树的根节点,parentKey 的值必须是 null、undefined 或空字符串 '' 三者之一 |
对应的 TypeScript 类型定义(transform.d.ts)也印证了两个字段均为必填:
export interface StratifyTransform {
type: 'stratify';
key: FieldRef;
parentKey: FieldRef;
}
在 Vega 数据流中,这两个参数是"字段访问器"(field accessor):每个输入数据对象会被 key 提取节点身份、被 parentKey 提取父节点身份。它们在定义阶段(Stratify.Definition,见 Stratify.js)声明为 type: 'field' 且 required: true,其中 metadata: {'treesource': true} 标记了该转换的输出是一个树数据源,供下游布局识别。
根节点的判定规则
一棵树有且只能有一个根。根节点的 parentKey 必须满足以下三种取值之一:
nullundefined- 空字符串
''
其余所有非根节点,其 parentKey 必须能在 key 字段中找到对应的父记录,否则无法构成连通树。
用法示例:从父子键构建树
基础配置如下(与原文档 stratify.md 一致):
{
"type": "stratify",
"key": "id",
"parentKey": "parent"
}
该配置会从输入数据对象构建树形数据结构:每个由 key 标识的节点,都会按照其 parentKey 字段的取值,被挂接为对应父节点的子节点。
例如,给定如下输入数据:
[
{"id": "A", "parent": null},
{"id": "B", "parent": "A"},
{"id": "C", "parent": "A"},
{"id": "D", "parent": "C"},
{"id": "E", "parent": "C"}
]
得到的树结构为:
/- B
A
\- C - [D, E]
其中 A 是根节点(parent 为 null),B、C 是 A 的子节点,D、E 是 C 的子节点。
在真实 Vega 规格中,stratify 通常作为数据源 transform 数组中的第一个变换,其后紧跟布局变换。下面是从 tree-layout.vg.json 节选的真实管线:
{
"name": "tree",
"url": "data/flare.json",
"transform": [
{
"type": "stratify",
"key": "id",
"parentKey": "parent"
},
{
"type": "tree",
"method": {"signal": "layout"},
"size": [{"signal": "height"}, {"signal": "width - 100"}],
"separation": {"signal": "separation"},
"as": ["y", "x", "depth", "children"]
}
]
}
先用 stratify 把 flare.json 的扁平记录变成树,再用 tree 变换计算节点坐标。类似的组合还出现在 circle-packing.vg.json(stratify → pack)、treemap.vg.json、sunburst.vg.json(stratify → partition)等示例中。此外 zoomable-circle-packing.vg.json 展示了 stratify 与信号(signal)驱动的数据切换配合的写法:
{"type": "stratify", "key": "id", "parentKey": "parent"}
底层实现:Stratify.js 源码解析
stratify 的实现在 vega-hierarchy 包中,核心文件为 Stratify.js,它是对 d3-hierarchy 的 stratify() 工厂方法的封装。关键逻辑如下:
tree = out.source.length
? lookup(
stratify().id(_.key).parentId(_.parentKey)(out.source),
_.key,
truthy
)
: lookup(stratify()([{}]), _.key, _.key);
从源码结构可以看到几个值得注意的细节:
- 委托给 d3-hierarchy:
stratify().id(_.key).parentId(_.parentKey)(out.source)正是 d3 的 ID 映射写法——id指定节点自身键,parentId指定父节点键。 - 构建 lookup 索引:
lookup函数(见 lookup.js)会遍历树的所有节点,把"数据键 → 树节点实例"的映射挂在tree.lookup上,供其他变换快速查找节点。 - 空数据处理:当输入源为空数组时,走
stratify()([{}])分支,生成一个没有子节点的空根节点,root.lookup为空对象。这样下游变换拿到的是"空树"而非undefined。 - 防止上游数据污染:代码执行
out.source = out.source.slice(),复制一份输入源,避免在树节点上附加root引用时污染上游数据集合。
增量更新机制
transform 方法会评估是否需要重建树,判定条件(run 变量)为:
- 当前还没有缓存树(
!tree); - 参数被修改(
_.modified()); - 上游数据发生了增删(
pulse.changed(pulse.ADD_REM)); key或parentKey字段的数据被修改。
只有当以上任一条件成立时才重新分层;否则直接复用缓存的树并把 out.source.root 指向它。这保证了在静态数据下树节点实例稳定,也解释了为什么在交互式图表中切换数据源时树能正确重建。
输出形态
转换完成后,out.source.root 被设置为生成的树根节点。树节点对象带有 data 字段(指向原始输入数据对象)、children(子节点数组)、depth(深度)等属性;root.lookup 则保存键到节点的映射。后续变换与 mark 编码都可以通过 datum.data 访问原始记录字段,例如 tree-layout.vg.json 中的 {"field": "name"} 与 {"field": "depth"}。
测试验证
vega-hierarchy 包中的测试 stratify-test.js 从数据流(Dataflow)层面验证了核心行为:
- 分层正确性:对
{id, pid}形式的四条记录,断言root.data等于首条根记录、root.children[0].data等子节点关系一一对应,且root.lookup的键数量等于数据条数; - 空数据行为:插入空数组后,
out.value长度为 0,root.children为undefined,root.lookup为空对象——与前述空数据处理分支相互印证。
这些用例同时演示了在 vega-dataflow 中手动装配 Collect → Stratify → Collect 的编程用法,可作为在 Node 环境集成 Vega 变换的参考。
常见问题与注意事项
- 根节点必须唯一且显式标记:根记录的
parentKey必须严格是null、undefined或''。多个根记录或根记录缺失都会破坏树的连通性。 key必须全局唯一:因为key既是节点标识,也是parentKey的查找依据,重复键会导致父子关系歧义,无法构成合法的树。- 注意循环引用:若数据中存在"A 的父是 B、B 的父是 A"这类环,d3-hierarchy 的
stratify会抛出错误(错误来自其底层校验逻辑)。从源码结构可以推断,Vega 的封装并没有额外捕获该异常,因此这类脏数据会导致数据流执行报错。 - 空数据是合法的:如测试所示,空输入会产生一棵空树,而不是报错,下游布局可以安全消费。
- stratify 只负责"建树",不负责"布局":它输出的树节点对象必须继续交给 tree、treemap、pack、partition 等变换计算坐标;若还需要绘制连接线,可再接 treelinks 与 linkpath。
小结
stratify 是 Vega 树形可视化的起点:它以极简的"键 + 父键"配置,把最常见的扁平父子表转换为结构完整的树节点对象,并附带按键查找索引,为后续各类树布局提供统一的数据基础。理解它的参数语义、根节点规则与增量重建机制,是编写健壮的树形图、矩形树图、圆形打包图和旭日图规格的前提。配合 tree-layout.vg.json 等仓库示例动手调试,可以快速验证不同输入数据下的建树行为。
