Vega Stratify Transform 深度指南:用父子键把扁平数据构建为树形结构

原创2026-09-22 17:04:051,629 阅读
文章标签:数据可视化

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 必须满足以下三种取值之一:

  • null
  • undefined
  • 空字符串 ''

其余所有非根节点,其 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);

从源码结构可以看到几个值得注意的细节:

  1. 委托给 d3-hierarchy:stratify().id(_.key).parentId(_.parentKey)(out.source) 正是 d3 的 ID 映射写法——id 指定节点自身键,parentId 指定父节点键。
  2. 构建 lookup 索引:lookup 函数(见 lookup.js)会遍历树的所有节点,把"数据键 → 树节点实例"的映射挂在 tree.lookup 上,供其他变换快速查找节点。
  3. 空数据处理:当输入源为空数组时,走 stratify()([{}]) 分支,生成一个没有子节点的空根节点,root.lookup 为空对象。这样下游变换拿到的是"空树"而非 undefined。
  4. 防止上游数据污染:代码执行 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 变换的参考。

常见问题与注意事项

  1. 根节点必须唯一且显式标记:根记录的 parentKey 必须严格是 null、undefined 或 ''。多个根记录或根记录缺失都会破坏树的连通性。
  2. key 必须全局唯一:因为 key 既是节点标识,也是 parentKey 的查找依据,重复键会导致父子关系歧义,无法构成合法的树。
  3. 注意循环引用:若数据中存在"A 的父是 B、B 的父是 A"这类环,d3-hierarchy 的 stratify 会抛出错误(错误来自其底层校验逻辑)。从源码结构可以推断,Vega 的封装并没有额外捕获该异常,因此这类脏数据会导致数据流执行报错。
  4. 空数据是合法的:如测试所示,空输入会产生一棵空树,而不是报错,下游布局可以安全消费。
  5. stratify 只负责"建树",不负责"布局":它输出的树节点对象必须继续交给 tree、treemap、pack、partition 等变换计算坐标;若还需要绘制连接线,可再接 treelinks 与 linkpath。

小结

stratify 是 Vega 树形可视化的起点:它以极简的"键 + 父键"配置,把最常见的扁平父子表转换为结构完整的树节点对象,并附带按键查找索引,为后续各类树布局提供统一的数据基础。理解它的参数语义、根节点规则与增量重建机制,是编写健壮的树形图、矩形树图、圆形打包图和旭日图规格的前提。配合 tree-layout.vg.json 等仓库示例动手调试,可以快速验证不同输入数据下的建树行为。

Vega tree-layout 示例:stratify 与 tree 变换组合后的节点链接图输出

登录后查看全文
vega