简介MATLAB标准函数库并未内置Sankey图绘制功能drawSankey正是为弥补这一空白而生的自定义函数适用于需要在MATLAB中展示能量流、物质流或信息流单向流动关系的开发者与数据分析人员。该资源压缩包共包含2个文件其中m文件为函数核心实现提供输入参数处理、数据计算和图形绘制逻辑txt文件为许可协议明确使用与分发条件。文件总大小仅4KB轻量易用适合快速集成到现有MATLAB项目中。已有280人学习下载获得了初步验证。通过阅读源码可以掌握利用plot、patch等底层命令构建自定义图表的完整思路也能理解Sankey图节点、流量与连线宽度的映射关系为后续扩展双向或多层Sankey图提供良好起点是学习MATLAB自定义图形编程的实用示例。 做能量系统分析的人应该都遇到过这种场景仿真数据跑了一大堆最终想给同事或领导讲清楚能量从哪来、经过哪些环节、流到哪里去普通的柱状图和折线图根本表达不了这种“带方向的流量关系”。这种时候最合适的就是桑基图Sankey Diagram但MATLAB里偏偏没有内置的sankey函数。网上搜“matlab drawSankey”能找到的不是年代久远的第三方提交就是只能画个静态示意图、一换数据就乱套的半成品。我因为一个数据后处理项目需要反复产出这类图干脆自己用MATLAB写了一个drawSankey工具函数从数据结构、布局算法、流道优化到渲染导出完整跑通。这篇文章直接讲实现思路、核心算法和踩过的坑适合正在用MATLAB做能量流、数据流转、用户转化分析又不想额外引入Web图表库的读者。1. 为什么MATLAB画桑基图这么麻烦问题出在哪1.1 桑基图本质上是一种“布局算法题”不是普通绘图先说清楚桑基图的本质。它和散点图、柱状图有根本区别后者的核心是把数据映射到坐标而桑基图的核心是把有向图转换成一种满足特定约束的空间布局。每一条数据不是孤立的点它同时包含“从哪个节点来”“到哪个节点去”“流量有多大”三层信息而且这些信息之间互相约束。具体到二维平面上桑基图要满足几个硬性条件节点按层级排列从左到右推进不允许出现回流方向混乱。节点的高度要正比于该节点的流量。每层所有节点的高度之和应该等于该层的总流量且层与层之间流量守恒。链接连线的宽度要正比于流量还要在节点之间平滑过渡。这些条件叠加在一起画图就变成了一个带约束的布局优化问题。MATLAB的绘图体系天生是为科学绘图设计的擅长画曲线、曲面和栅格图但并没有提供“布局引擎”这类抽象能力。所以想要在MATLAB里画桑基图真正要解决的不是调用哪个绘图函数而是自己实现布局计算。1.2 现成方案的尴尬要么牵强要么难改我把能想到的现成方案都试过各有各的难受简单列个对比供参考方案主要问题适用场景MATLAB官方内置不存在专门sankey函数相邻的图论工具只提供拓扑布局画不出流量宽度基本不用考虑File Exchange上的旧代码不少实现依赖老工具箱接口固定想调整排序规则或增加自定义样式很痛苦简单示意图Matplotlib的sankey效果不错但意味着数据要先导出成Python能用的格式跨语言传递容易丢字段偏向Python生态用Simulink或Stateflow画能模拟流关系但不是为可视化报告设计的后期排版非常累仿真过程演示自己写前期成本高但数据接口、布局规则、输出格式完全可控需要频繁产出、有定制需求的场景我最终选择自己写一个很现实的理由项目里经常要改节点名称、调整层级顺序、把某条主链路高亮出来这些需求在现成代码里几乎都要动核心逻辑还不如一开始就掌握完整的实现。1.3 自己画的投入产出比取决于你复用多少次如果你的桑基图只画一两次那确实不值得自己造轮子直接用在线工具或者Python更省事。但要是像我一样属于数据分析流程里要反复跑的部分——今天换个数据集明天调整个配色后天又要按新业务口径重新分层——那自研的价值就体现出来了。只需要维护一套脚本后续所有图都能复用同一套数据接口和样式规范。2. 先定数据结构再谈画图这是整个实现里最重要的一步。我刚开始写的时候一上来就研究贝塞尔曲线的控制点应该放在哪结果数据一多就乱了光排查节点对应关系就花了不少时间。后来痛定思痛先把数据接口固定下来后面的问题基本都变成了“代入公式”的事。2.1 节点表和链接表我用两张table作为drawSankey的输入而不是用结构体数组或者Graph对象。原因是table在MATLAB里的可读性最好列名能直接当成字段用而且后续做索引、筛选、join都很方便。节点表每一行代表一个节点字段如下nodeTable table( ... [1; 2; 3], ... {Coal; Power; Electricity}, ... [120; 200; 150], ... [1; 2; 3], ... VariableNames, {ID, Name, Flow, Layer});链接表每一行代表一条有向流量边linkTable table( ... [1; 2], ... [2; 3], ... [120; 150], ... VariableNames, {Source, Target, Flow});这里的关键设计是NodeID。它不一定要从1开始连续但必须在整个节点表中唯一。链接表里的Source和Target引用的就是NodeID而不是行号。这样做的好处是当你在绘图前对节点做排序、筛选时链接关系的引用不会断裂。2.2 Layer字段手工指定还是自动推断Layer字段表示节点在第几层。为什么需要层因为桑基图是有向无环图DAG的可视化从左到右的每一列就是一个层布局时先知道层才能计算x坐标。我建议优先让用户手工指定Layer因为实际情况里层的含义往往是业务给定的。比如能量分析里“供给层—转换层—需求层”就是天然的三层结构手工指定最准确。但为了方便我也在函数里支持自动推断从所有没有入链的节点出发做广度优先遍历逐层给节点打上层级标签。这个逻辑用MATLAB写也不复杂function layer inferLayers(nodeTable, linkTable) layer zeros(height(nodeTable), 1); remaining nodeTable.ID; currentLayer 1; while ~isempty(remaining) noIncoming remaining(~ismember(remaining, linkTable.Target( ... ismember(linkTable.Source, remaining)))); if isempty(noIncoming) error(链接表中检测到环无法自动分层); end layer(ismember(nodeTable.ID, noIncoming)) currentLayer; remaining remaining(~ismember(remaining, noIncoming)); currentLayer currentLayer 1; end end这个函数利用了“在当前剩余节点中所有没有被剩余节点指向的节点就是最外层节点”的性质。每次循环剥掉一层直到所有节点都分层完毕。注意如果数据存在循环依赖这个函数会因为找不到“无入链节点”而无限循环所以我在循环里加了保护。2.3 定义数据校验别让脏数据毁掉整张图我早期吃过一次亏链路表里混入了一个Flow为负值的记录导致某层总流量计算异常所有节点高度直接错乱图长成了乱七八糟的形状。从那以后我习惯在函数开头加一组断言式检查validateattributes(nodeTable, {table}, {nonempty}); validateattributes(linkTable, {table}, {nonempty}); assert(all(nodeTable.Flow 0), 节点流量不能为负); assert(all(linkTable.Flow 0), 链接流量不能为负); assert(all(ismember(linkTable.Source, nodeTable.ID)), 链接表包含不存在的源节点); assert(all(ismember(linkTable.Target, nodeTable.ID)), 链接表包含不存在的目标节点);这段代码看起来不起眼但配合自动布局逻辑时非常有用。很多画图脚本跑出来的结果荒谬根源不在绘图代码而是入口数据没把关。3. 核心绘图算法把“流量”变成“图形”3.1 布局计算确定每个节点的位置和尺寸先规定一个绘图坐标系x轴表示层级从左到右递增y轴表示该层内的流量位置从上到下累计。节点绘制成一个竖直方向的矩形矩形的宽度固定代表一个层高度和该节点的流量成正比。布局计算的第一步是算出绘图区的总高度。我的做法是找出所有层中总流量最大的那一层把它作为标准让该层的节点恰好填满整个绘图高度。这样其他层虽然流量少一些但整体比例不会失真。layers unique(nodeTable.Layer); maxLayerSum 0; for k 1:numel(layers) layerSum sum(nodeTable.Flow(nodeTable.Layer layers(k))); maxLayerSum max(maxLayerSum, layerSum); end totalHeight 6; % 可配置的绘图区高度 hScale totalHeight / maxLayerSum;有了比例尺之后每个节点的矩形高度就是nodeTable.Flow * hScale。接下来按层铺设纵坐标同一层内的节点按当前顺序从上到下依次排列yBottom zeros(height(nodeTable), 1); for k 1:numel(layers) idx find(nodeTable.Layer layers(k)); acc 0; for i idx yBottom(i) acc; acc acc nodeTable.Flow(i) * hScale; end endx坐标就更直接了把层号映射成水平位置layerWidth 1; layerGap 1.2; xLeft (nodeTable.Layer - layers(1)) * (layerWidth layerGap);到这里每个节点的左下角坐标、宽高全部确定。这个阶段不需要任何绘图操作所有的计算都是为了后面绘制服务的。3.2 节点矩形用patch而不是rectangle节点本身是一个矩形但我不推荐用MATLAB的rectangle函数。rectangle虽然参数直观但它的颜色控制和描边控制都比较僵化尤其是后续想给节点做高亮、点击交互时会很受限。用patch更灵活它可以直接用XData、YData定义多边形还能通过FaceVertexCData精确控制每个顶点的颜色。nodeColors [0.30 0.45 0.64]; for i 1:height(nodeTable) x xLeft(i); y yBottom(i); w layerWidth; h nodeTable.Flow(i) * hScale; patch([x xw xw x], [y y yh yh], ... nodeColors, EdgeColor, k, LineWidth, 1); end节点矩形的x坐标是固定的一个值某个层内所以完整的矩形由四个顶点确定顺序是左下、右下、右上、左上。3.3 链接曲线三次贝塞尔是默认答案链接是桑基图的灵魂。它连接源节点的右边界和目标节点的左边界宽度表示流量大小。这里有个核心问题连接线应该用什么曲线我直接用直线试过一次当节点数量和流量条数超过十几条时直线连接会产生大量生硬的折角和重叠观感非常差。换成三次贝塞尔曲线之后视觉质量提升了一个量级。三次贝塞尔曲线由四个控制点决定起点P0、终点P3、以及两个中间控制点P1和P2。它的参数方程是P(t) (1-t)^3 * P0 3*(1-t)^2t * P1 3(1-t)*t^2 * P2 t^3 * P3对于桑基图来说P0取源节点右边界的某个点P3取目标节点左边界的某个点。P1的x坐标取P0.x加上横向距离的一部分y坐标保持和P0相同P2的x坐标取P3.x减去横向距离的一部分y坐标保持和P3相同。这样曲线在起点处是水平的离开源节点后平滑转向目标在终点处也是水平的视觉上最顺滑。直接画一条细线只能表达拓扑关系表达不了流量大小所以真正要画的是“条带”——两条贝塞尔曲线围成的封闭区域。具体做法是分别计算源节点上边缘到目标节点上边缘的顶部曲线、源节点下边缘到目标节点下边缘的底部曲线然后把两条曲线的点合并成多边形用patch填充。给出一段核心绘制代码t linspace(0, 1, 40); for k 1:height(linkTable) s linkTable.Source(k); tg linkTable.Target(k); xStart xLeft(s) layerWidth; xEnd xLeft(tg); yStartC yBottom(s) nodeTable.Flow(s) * hScale / 2; yEndC yBottom(tg) nodeTable.Flow(tg) * hScale / 2; c1x xStart (xEnd - xStart) * 0.45; c2x xEnd - (xEnd - xStart) * 0.45; topY1 yStartC nodeTable.Flow(s) * hScale / 2; topY2 yEndC nodeTable.Flow(tg) * hScale / 2; botY1 yStartC - nodeTable.Flow(s) * hScale / 2; botY2 yEndC - nodeTable.Flow(tg) * hScale / 2; topCurveX (1-t).^3 * xStart 3*(1-t).^2.*t * c1x 3*(1-t).*t.^2 * c2x t.^3 * xEnd; topCurveY (1-t).^3 * topY1 3*(1-t).^2.*t * topY1 3*(1-t).*t.^2 * topY2 t.^3 * topY2; botCurveX (1-t).^3 * xStart 3*(1-t).^2.*t * c1x 3*(1-t).*t.^2 * c2x t.^3 * xEnd; botCurveY (1-t).^3 * botY1 3*(1-t).^2.*t * botY1 3*(1-t).*t.^2 * botY2 t.^3 * botY2; X [topCurveX; flipud(botCurveX)]; Y [topCurveY; flipud(botCurveY)]; patch(X, Y, [0.30 0.45 0.64], FaceAlpha, 0.5, EdgeColor, none); end控制点比例0.45是经验值。太小的话曲线很“急”像被硬拽过去的太大的话曲线会横向拖尾和相邻层级的节点产生不必要的重叠。实测0.4到0.5之间都比较安全。3.4 颜色分配继承源节点而不是每根线单独配色桑基图的信息密度很高如果每条链接的颜色都是独立的那张图会像一盒打翻的彩虹糖核心流动关系反而看不清。我的原则很简单链接颜色继承源节点的颜色只在透明度上和节点本体做区分。这样读者看到某个颜色的条带就能立刻顺着颜色找到它从哪里出发。节点颜色可以用MATLAB内置的colormap按索引生成比如baseColors turbo(height(nodeTable));然后每条链接取源节点颜色的RGB值设置FaceAlpha为0.5左右。透明度的意义在于条带在交叉或重叠时依然能看出底层内容不至于黑色一团。4. 让布局不乱的排序逻辑4.1 交叉是桑基图美观度的最大敌人按照节点表原始的ID顺序铺设纵坐标大概率会出现一个灾难现场第2层的节点顺序和第1层的链接关系完全错位大量条带在中间交叉整个图看起来像一团乱麻。交叉本身不改变数据含义但它严重降低可读性尤其当你要在报告里向别人解释“谁流向了谁”时交叉线条会让理解成本成倍上升。这个问题不解决前面所有布局算法都白搭。4.2 拓扑排序按上游节点的流量加权质心排列我用的优化方法是逐层贪心排序。思路非常朴素对于某一层里的每个节点计算它所有上游链接的“平均来源位置”也就是按流量加权平均的源节点纵坐标。然后在该层内部按照这个平均位置从高到低重新排列节点。换句话说尽量让每个节点的y位置靠近它大部分流量来源的位置从而减少跨层线条的斜向距离。计算每个节点的加权目标位置for li 2:numel(layers) idx find(nodeTable.Layer layers(li)); if numel(idx) 1 continue; end targetY nan(numel(idx), 1); for j 1:numel(idx) curID nodeTable.ID(idx(j)); pred linkTable.Source(linkTable.Target curID); predFlow linkTable.Flow(linkTable.Target curID); if isempty(pred) targetY(j) Inf; else weightedSum 0; totalFlow 0; for p 1:numel(pred) predRow nodeTable.ID pred(p); sourceCenter yBottom(predRow) nodeTable.Flow(predRow) * hScale / 2; weightedSum weightedSum sourceCenter * predFlow(p); totalFlow totalFlow predFlow(p); end targetY(j) weightedSum / totalFlow; end end [~, ord] sort(targetY); reorderedIdx idx(ord); acc 0; for i reorderedIdx yBottom(i) acc; acc acc nodeTable.Flow(i) * hScale; end end这里有个细节没有任何上游入链的节点它的targetY被设为Inf这样会被排到该层最底部。这一步是刻意的因为像“损失”“残余”“出口”这类汇节点在视觉习惯上放在底部最不遮挡主要流动线。4.3 贪心排序的边界和补充技巧需要说明的是这个逐层贪心算法只能保证局部优化不能保证全局无交叉。遇到很多层、很多分支的复杂图第一层排好后第二层的最优顺序可能和第三层又产生冲突。实际使用时可以接受因为桑基图本身很少有数学意义上的完美无交叉解。另一个有效的小技巧是除了层级内排序还要控制条带的绘制顺序。我一般会让流量大的链接后绘制因为大流量条带宽度大后绘制会压在小的条带上方视觉上层次更清晰。实现上只需要在绘图循环前对linkTable按Flow降序排一次序linkTable sortrows(linkTable, Flow, descend);这行代码经常被忽略但它能让图面的层次感提升不少。5. 完整案例一组能量审计数据跑通全流程5.1 模拟数据设计用一组简单的能量审计数据来验证整个drawSankey工具函数。数据描述的是某园区从一次能源到终端用户的能量流动过程包含三个层级层1煤、天然气表示外部输入的原始能量层2发电、热泵表示能量转换环节层3用户电、用户热、损失表示最终去向和损耗数据设计成完全守恒方便验证布局计算是否正确每层总流量都是270个单位。nodeTable table( ... [1; 2; 3; 4; 5; 6; 7], ... {Coal; NaturalGas; Power; HeatPump; Electricity; Heat; Loss}, ... [120; 150; 200; 70; 150; 60; 60], ... [1; 1; 2; 2; 3; 3; 3], ... VariableNames, {ID, Name, Flow, Layer}); linkTable table( ... [1; 2; 2; 3; 3; 4; 4], ... [3; 3; 4; 5; 7; 6; 7], ... [120; 80; 70; 150; 50; 60; 10], ... VariableNames, {Source, Target, Flow});5.2 运行drawSankey并检查输出把前面所有代码块拼装成完整的drawSankey函数后运行drawSankey(nodeTable, linkTable); title(Energy Flow of Demo Campus);建议函数内部在完成布局后做一次断言检查每一层的节点高度之和是否相等for k 1:numel(layers) sumFlow sum(nodeTable.Flow(nodeTable.Layer layers(k))); layerHeight sum(yBottom(nodeTable.Layer layers(k)) ... nodeTable.Flow(nodeTable.Layer layers(k)) * hScale) - ... min(yBottom(nodeTable.Layer layers(k))); assert(abs(layerHeight - sumFlow * hScale) 1e-6, 布局计算疑似错误); end实际运行正常时你会看到三个层分别对齐发电节点是层2中高度最大的矩形左右两边的入链和出链宽度都能对上损失节点被自动排在最底部两条通到损失节点的小流量条带交叉程度也不明显。5.3 调节视觉参数的经验值layerWidth推荐设为1太小会让节点看起来像一条线太大又挤占链接空间。layerGap推荐1到2之间太大浪费画布太小条带汇聚处容易糊在一起。LinkAlpha推荐0.45到0.65之间低于0.3基本看不清颜色高于0.85条带重叠处会不透气。字体大小如果节点名称是中文建议把图幅拉大字体设置在10到12之间不要靠缩小字体硬塞。6. 实测中的几个坑和继续折腾的方向6.1 数据量大时的性能问题当节点数量过百、链接超过两百条时最直接的性能瓶颈是图形对象数量。每个节点是一个patch每条链接也是一个patch几百个对象会让MATLAB的绘图速度肉眼可见地下降鼠标拖动视角时也会卡顿。一个有效的优化是合并同色条带。把同一层内且颜色相同的链接合并到一个大的patch对象里用NaN在顶点数据中分段这样MATLAB只需要维护一个对象而不是几十个。这个优化写起来稍微繁琐但效果非常明显。另一个取巧的办法是减少贝塞尔曲线的采样点数从40降到25肉眼几乎分辨不出区别。6.2 导出图片时务必注意渲染器设置很多人在MATLAB里把图画好后直接点击保存结果导出的矢量图变成了一张分辨率很低的位图。这是因为默认渲染器可能是OpenGL而向量格式导出需要painters渲染器。正确做法是用exportgraphics设置矢量格式exportgraphics(gcf, sankey_output.svg, ContentType, vector, Resolution, 300);导出中文标签时如果系统字体设置不对PDF或EPS打开后会变成方格或者乱码。要么在绘图前设置set(gca, FontName, SimHei)这类中文字体要么干脆在正式产出图里使用英文标签。6.3 静态图之外的扩展方向MATLAB从R2020b开始普及了DataTip功能可以给patch对象添加数据提示。这意味着可以给每条链接挂上源节点、目标节点和流量的数据提示鼠标悬停就能看到具体数值。加上这个功能后drawSankey就不只是展示图了还能当简单的交互分析工具用。如果想把工具变成更正式的内部产品可以考虑用App Designer封装一个界面左边放表格编辑节点和链接右边实时预览桑基图。这个方向不难做核心绘图函数已经定好UI只是调用而已。写这个drawSankey的过程中我最大的感触是第一个版本千万别想着一步到位把曲线画得花里胡哨先把数据结构定死再用最简单的线条把图“跑通”最后才轮到排序和配色。还有一个实操教训——网上很多代码不处理数据校验我也吃过一次流量负值导致布局错乱的亏现在凡是给其他人复用的可视化脚本我都会默认在入口加一层数据检查。希望这份实现和踩坑记录能帮你省下一些不该浪费的调试时间。本文还有配套的精品资源点击获取
