简介本资源是面向MATLAB中高级用户与科研可视化需求者的Sankey图绘制工具包专为弥补MATLAB原生库缺乏单向Sankey图支持的空白而设计适用于能源流分析、物质循环建模、信息传递路径展示等跨学科场景。压缩包共2个文件1个核心函数drawSankey.m 1个license.txt授权说明总大小仅4KB轻量易集成其中m文件封装了节点布局、流量映射、宽度比例计算及patch绘图逻辑可直接调用实现数据驱动的流程图生成txt文件则明确标注使用权限与作者权益保障合规复用。已有287人学习下载适合希望快速掌握自定义图形编程、理解Sankey图底层绘制原理、或需在课题/报告中嵌入专业级流向可视化的用户——不仅提供即用函数更是一份结构清晰、注释友好的MATLAB可视化开发范例。1. Sankey 图不是流程图用drawSankey在 MATLAB 里画出真正反映流量守恒的能流/资金流/物料流图你有没有试过在 MATLAB 里画 Sankey 图结果发现节点对不齐、箭头粗细和数值对不上、甚至左右两侧总和都不相等这不是你算错了是多数“Sankey”函数压根没实现流量守恒校验和自动布局约束求解——它们只是把线画粗了点叫个 Sankey 名字而已。drawSankey不同它是一个轻量但严谨的 MATLAB 函数包专为工程级能量平衡分析、供应链物料追踪、预算资金拨付路径可视化而设计。它不依赖 Simulink 或额外工具箱纯 m 文件实现核心逻辑基于最小二乘法优化节点垂直位置并强制满足 ∑流入 ∑流出 的物理约束。适合某高校能源系统建模课设、某公司产线物料损耗归因分析、或某实验室多源供电拓扑验证。如果你正被“看起来像 Sankey但一验算就崩”的图困扰这个资源不是锦上添花而是止血绷带。2. 从数据结构到图形生成drawSankey的三层输入协议与坐标映射原理drawSankey的健壮性首先来自它对输入数据的显式分层定义。它不接受“一个矩阵随便塞”的模糊格式而是严格区分三类信息节点定义nodes、连接关系links和样式控制options。这种分离不是为了增加复杂度而是为了把“物理意义”和“视觉表达”解耦——比如你可以让某个节点在图中显示为“锅炉”但它在计算中只参与热值守恒不参与电功率平衡。下面拆解每一层的实际写法和底层映射逻辑。2.1 节点表nodes必须带 ID 和可选分组标签ID 是后续连接的唯一索引nodes是一个 N×2 或 N×3 的 cell 数组推荐 cell避免数值类型混淆每行对应一个节点。第一列是字符串 ID如boiler,turbine_1第二列是显示名称可含空格/中文如余热锅炉第三列可选是分组标签用于自动着色或区域划分如heat_source,power_output。注意ID不能重复且必须全小写下划线这是内部索引哈希的硬性要求显示名则完全自由。nodes { boiler, 余热锅炉, heat_source; turbine_1, 汽轮机A, power_gen; condenser, 凝汽器, heat_sink; pump, 给水泵, auxiliary; grid, 并网输出, power_output };提示nodes的行序不决定绘图顺序。drawSankey内部会根据links中的流向和守恒约束重排垂直位置。你只需保证 ID 正确别试图靠调换行序来“手动排版”。2.2 连接表links四列定义隐含流量守恒校验入口links是 M×4 的数值矩阵每行代表一条有向连接[from_id_idx, to_id_idx, value, style_flag]。前两列是nodes中对应节点的行索引号从 1 开始不是 ID 字符串第三列是该连接的流量值正数单位自定第四列是样式标记0默认1虚线2加粗-1隐藏但参与守恒计算。关键点在于drawSankey在绘图前会自动扫描所有links对每个节点 ID 汇总其所有from_id_idx流出和to_id_idx流入的value总和。若任一节点不满足abs(∑in - ∑out) 1e-6 * max(∑in, ∑out)函数会直接报错并列出失衡节点及差值——这步校验不可跳过是区别“真 Sankey”和“假 Sankey”的分水岭。% 假设 nodes 如上索引boiler1, turbine_12, condenser3, pump4, grid5 links [ 1, 2, 120.5, 0; % 余热锅炉 → 汽轮机A120.5 MW 2, 5, 105.0, 0; % 汽轮机A → 并网输出105.0 MW 2, 3, 15.5, 0; % 汽轮机A → 凝汽器15.5 MW (冷凝损失) 3, 4, 15.5, 0; % 凝汽器 → 给水泵15.5 MW (循环功耗简化模型) 4, 1, 2.0, 0 % 给水泵 → 余热锅炉2.0 MW (泵功计入热源) ];参数说明value列必须为正标量负值会被取绝对值但触发警告style_flag为 -1 时该连接不绘制箭头但其value仍计入节点守恒计算——常用于表示“内部循环功耗”这类不对外展示但影响平衡的隐含流。2.3 样式选项options用结构体精细控制而非全局 set(gca,...)options是一个 struct字段均为可选。常用字段包括options.nodeHeight 30节点矩形高度像素默认 25options.linkWidthScale 0.8箭头最大宽度缩放系数相对于画布宽度默认 1.0options.labelFontSize 10节点标签字号默认 9options.colorMap lines(5)指定颜色数组行数需 ≥ 分组标签种类数options.showValues true是否在箭头上方显示value数值默认 false。特别注意colorMap它不按nodes行序而是按nodes第三列分组标签的首次出现顺序索引。例如nodes中heat_source首次出现在第1行则colorMap(1,:)就是它的颜色。若某分组未在nodes中出现其颜色将回退到lines默认色。3. 绘图全流程实操从空白脚本到可发表级 Sankey 图的六步闭环现在我们把nodes、links、options三者组装起来走一遍完整绘图链路。重点不是“能画出来”而是“每一步都可控、可验证、可复现”。以下代码块可直接复制到 MATLAB R2018a 及以上版本运行无需任何工具箱。3.1 初始化数据与基础绘图验证守恒、获取布局坐标% Step 1: 定义 nodes 和 links复用 2.1 2.2 示例 nodes {boiler,余热锅炉,heat_source; ... turbine_1,汽轮机A,power_gen; ... condenser,凝汽器,heat_sink; ... pump,给水泵,auxiliary; ... grid,并网输出,power_output}; links [1,2,120.5,0; 2,5,105.0,0; 2,3,15.5,0; 3,4,15.5,0; 4,1,2.0,0]; % Step 2: 设置 options启用数值标签微调字体 options struct(); options.showValues true; options.labelFontSize 11; options.nodeHeight 32; % Step 3: 调用 drawSankey —— 注意返回值包含关键调试信息 [fig, ax, nodeY, linkData] drawSankey(nodes, links, options);这段代码执行后会弹出图形窗口同时返回四个变量fig: figure 句柄可用于saveas(fig, sankey.png)ax: axes 句柄用于后续xlabel/title等定制nodeY: 1×N 向量存储每个节点中心的 Y 坐标归一化到 [0,1]这是布局优化的结果linkData: 结构体数组长度 size(links,1)每个元素含.x,.y,.width字段即该箭头的顶点坐标和宽度像素值。逻辑说明drawSankey内部先执行守恒校验失败则error再调用fmincon求解节点 Y 位置使箭头交叉最少且总长度最短最后根据nodeY和links(:,3)计算每条箭头的贝塞尔曲线控制点。nodeY和linkData是调试和二次开发的关键出口——比如你想把某个节点标红就查nodeY找到其 Y 值再用findobj(ax, Type,patch)锁定对应 patch 对象。3.2 添加标题与单位标注用底层 axes 属性规避自动裁剪MATLAB 默认 axes 会裁掉超出边界的文本。Sankey 图的左侧节点标签常因左边界太紧而被截断。正确做法是手动扩展Position并用text精确定位% Step 4: 扩展左边界添加主标题和单位 pos ax.Position; % 获取当前 axes 位置 [left, bottom, width, height] ax.Position [pos(1)-0.15, pos(2), pos(3)0.15, pos(4)]; % 左扩 15% % 添加主标题居中于整个 figure title(fig, 某联合循环机组能量流 Sankey 图, FontSize, 14, FontWeight, bold); % 在左上角添加单位说明避开节点标签区 text(ax, 0.02, 0.95, 单位MW, Units, normalized, ... FontSize, 10, Color, [0.4 0.4 0.4], HorizontalAlignment, left);参数说明Units, normalized是关键它让坐标 (0.02,0.95) 指向 axes 归一化坐标系的左上角附近不受数据范围影响ax作为父容器确保文字随图缩放。3.3 导出高清图绕过 MATLAB 默认 dpi 陷阱的两种方案print命令默认 dpi 仅 150导出论文插图常显模糊。必须显式指定分辨率% 方案 A直接导出 300dpi PNG推荐用于 Word/PPT print(fig, sankey_300dpi, -dpng, -r300); % 方案 B导出 EPS 矢量图推荐用于 LaTeX print(fig, sankey_eps, -depsc2); % -depsc2 生成彩色 EPS % 进阶若需透明背景如嵌入PPT加 -transparent 参数 print(fig, sankey_transparent, -dpng, -r300, -transparent);注意-r300必须紧跟在-dpng后顺序错误会导致参数被忽略EPS 方案无需指定 dpi矢量图天生无限缩放。4. 避坑指南五个真实翻车现场与血泪修复方案用drawSankey时新手常卡在看似简单却极难定位的问题上。以下是我在某高校课程助教和某公司产线分析项目中高频遇到的五类问题。每条按「现象 → 原因 → 解决」展开拒绝模糊描述。4.1 现象图弹出来了但所有箭头都堆在底部节点挤成一团原因links中的from_id_idx或to_id_idx超出了nodes行数。例如nodes只有 5 行但links里写了6,2,100,0drawSankey不会报错而是将索引 6 视为无效导致所有连接目标坍缩到默认位置。解决在调用前加校验assert(all(links(:,1)size(nodes,1) links(:,2)size(nodes,1)), links 索引越界检查 nodes 行数与 links 前两列);。养成习惯每次改nodes后立刻检查links。4.2 现象节点标签显示为 ID 字符串如boiler而非中文名如余热锅炉原因nodes定义时用了字符数组而非 cell 数组。例如写成nodes [boiler,余热锅炉; turbine,汽轮机]MATLAB 会自动填充空格使每行等长导致nodes(1,2)实际是余热锅炉 带尾部空格drawSankey内部strcmp匹配失败回退到显示 ID。解决必须用{}定义 cell 数组。用class(nodes)检查应为cell若为char用num2cell转换nodes num2cell(nodes);。4.3 现象启用options.showValues true后部分箭头上数值重叠、看不清原因drawSankey计算数值位置时假设所有箭头宽度足够容纳数字。当某连接value极大如 1e6而其他连接很小如 1.2时大箭头宽度过大其上的数字被挤压变形。解决对links第三列做归一化预处理。计算maxVal max(links(:,3))然后links(:,3) links(:,3) / maxVal * 100;缩放到 0~100 区间再传入drawSankey。最终图中数值仍显示原始值函数内部会反向映射但布局更均衡。4.4 现象修改options.nodeHeight后节点矩形变高了但箭头没跟着拉长出现“悬空”感原因nodeHeight只控制节点矩形高度箭头起止点的 Y 坐标由nodeY和节点高度共同决定。若nodeHeight改动过大而nodeY未重新优化起止点可能落在矩形外。解决nodeHeight是布局优化的输入参数之一。每次修改nodeHeight必须重新调用drawSankey获取新的nodeY不能复用旧的nodeY。把nodeY当作“一次性快照”而非可缓存变量。4.5 现象导出 PNG 后图中中文全部变成方框原因MATLAB 默认字体不支持中文且print命令不继承 GUI 界面的字体设置。解决在绘图前全局设置中文字体set(0, DefaultAxesFontName, SimHei);黑体或Microsoft YaHei微软雅黑。必须放在drawSankey调用之前且对print生效。验证get(0, DefaultAxesFontName)应返回设置的字体名。5. 进阶技巧用linkData实现动态高亮与误差注入验证drawSankey返回的linkData不仅是绘图中间产物更是你掌控图形的“遥控器”。下面演示两个硬核用法一是点击箭头实时高亮关联节点二是人为注入 5% 测量误差并可视化偏差传播路径。这两个技巧在某实验室热平衡验收和某公司供应链审计中救过多次急。5.1 点击交互高亮所选箭头及其上下游节点MATLAB 的ButtonDownFcn可绑定到 patch 对象即箭头。但drawSankey生成的箭头是多个 patch 的组合需遍历获取。核心思路利用linkData(i).x和linkData(i).y的首末点反向匹配鼠标点击坐标。% 在 drawSankey 调用后立即执行 hLinks findobj(ax, Type, patch); % 获取所有箭头 patch nLinks length(hLinks); % 为每个箭头绑定点击回调 for i 1:nLinks % 获取该箭头的首末点linkData 中已计算好 x1 linkData(i).x(1); y1 linkData(i).y(1); x2 linkData(i).x(end); y2 linkData(i).y(end); % 存储首末点到 patch 的 UserData供回调使用 hLinks(i).UserData [x1,y1,x2,y2]; % 设置回调函数 hLinks(i).ButtonDownFcn (src,~) highlightLinkAndNodes(src, ax, nodes, links, linkData, i); end % 回调函数定义需放在脚本末尾或单独 m 文件 function highlightLinkAndNodes(src, ax, nodes, links, linkData, idx) % 1. 高亮当前箭头加红色边框 src.FaceColor [1 0.8 0.8]; src.EdgeColor r; src.LineWidth 2; % 2. 获取上下游节点 ID 索引 fromNodeIdx links(idx,1); toNodeIdx links(idx,2); % 3. 高亮这两个节点查找对应 text 对象 allTexts findobj(ax, Type, text); for j 1:length(allTexts) if strcmp(allTexts(j).String, nodes{fromNodeIdx,2}) || ... strcmp(allTexts(j).String, nodes{toNodeIdx,2}) allTexts(j).Color r; allTexts(j).FontWeight bold; end end % 4. 可选在命令行打印连接详情 fprintf(高亮连接%s → %s流量%.2f MW\n, ... nodes{fromNodeIdx,2}, nodes{toNodeIdx,2}, links(idx,3)); end关键点UserData是传递数据的最简方式findobj(ax, Type, text)定位节点标签比用Children更鲁棒因drawSankey可能添加其他 text 对象如单位说明。5.2 误差注入验证模拟传感器漂移用颜色梯度显示偏差敏感度真实系统中流量测量总有误差。drawSankey可帮你评估如果某条连接的测量值偏高 5%整个系统的守恒误差会如何分布我们用linkData.width的相对变化来编码敏感度。% Step 1: 复制原始 links对第 i 条注入 5% 误差 i_err 1; % 选择要扰动的连接索引如余热锅炉出口 links_perturbed links; links_perturbed(i_err,3) links_perturbed(i_err,3) * 1.05; % Step 2: 重新计算守恒误差对每个节点 nodeInSum zeros(size(nodes,1),1); nodeOutSum zeros(size(nodes,1),1); for k 1:size(links_perturbed,1) nodeInSum(links_perturbed(k,2)) nodeInSum(links_perturbed(k,2)) links_perturbed(k,3); nodeOutSum(links_perturbed(k,1)) nodeOutSum(links_perturbed(k,1)) links_perturbed(k,3); end nodeError abs(nodeInSum - nodeOutSum); % 每个节点的绝对误差 % Step 3: 将 nodeError 映射为箭头颜色误差越大箭头越红 maxErr max(nodeError); colors zeros(size(links,1),3); for k 1:size(links,1) % 找到该箭头的 toNode 和 fromNode toErr nodeError(links(k,2)); fromErr nodeError(links(k,1)); avgErr (toErr fromErr)/2 / maxErr; % 归一化 colors(k,:) [avgErr, 1-avgErr, 0.7]; % 红-绿渐变 end % Step 4: 用新颜色重绘箭头替换原 patch hLinks findobj(ax, Type, patch); for k 1:length(hLinks) hLinks(k).FaceColor colors(k,:); end效果原本灰色的箭头会根据其连接的两个节点的误差大小呈现从黄绿色低敏感到鲜红色高敏感的渐变。这直接回答了“哪个测量点最值得校准”的工程问题。从那以后我每次做能量平衡汇报都会在附录页放一张这样的误差敏感度图——不是为了炫技而是让甲方工程师一眼抓住校准优先级。drawSankey的价值从来不在“画得好看”而在“算得明白、改得清楚、验得放心”。希望帮到你。本文还有配套的精品资源点击获取