任务可视化 echart 数据格式说明

本文档说明如何准备 CSV 或 JSON 数据，以便使用 py_echart 生成各类 ECharts 图表，并在任务流运行结果中以可视化形式展示。 支持的文件格式：.csv（表格类图表）、.json（树形/层级类图表）。

实现源码：myapp/utils/py/py_echart.py（任务流可视化插件版本为 myapp/utils/plugin/plugin_echart.py）。

一、通用说明

• CSV：第一行为表头（列名），从第二行起为数据行；列之间用逗号分隔。
• JSON：仅用于 树图 和 旭日图，需为层级结构。
• 表头（列名）会作为图例名或坐标轴名称使用，请使用有意义的名称。

二、各图表类型的数据格式

1. 折线图 (line)

数据含义：第 1 列为 X 轴类目；其余每一列为一组折线，列名为图例。

CSV 示例：

月份,销售额,成本,利润
1月,120,80,40
2月,200,120,80
3月,150,90,60
4月,280,160,120

• 第 1 列：X 轴（如月份）。
• 第 2～N 列：每条线对应一列，列名为图例（如「销售额」「成本」「利润」）。

2. 柱状图 (bar)

数据含义：第 1 列为类目（如型号/名称）；其余列为不同系列的柱形，列名为图例。

CSV 示例：

型号,分数A,分数B,分数C
模型1,43.3,85.8,93.7
模型2,83.1,73.4,55.1
模型3,86.4,65.2,82.5

• 第 1 列：横轴类目（如型号）。
• 其余列：每个类目下多根柱子，列名为图例。

3. 饼图 (pie)

数据含义：第 1 列为扇区名称；其余每一列对应一张饼图（多列会生成多张饼图并排），列名为该图的标题。

CSV 示例：

类别,占比2023,占比2024
产品A,35,40
产品B,25,30
产品C,40,30

• 第 1 列：扇区名称（如类别）。
• 第 2～N 列：每列数值为一张饼图，列名作为该图标题。

4. 散点图 (scatter)

数据含义：与折线图相同——第 1 列为 X 轴类目，其余列为多组散点，列名为图例。

CSV 示例：

批次,组A,组B,组C
第1批,12,25,18
第2批,30,22,35
第3批,15,40,28

5. 雷达图 (radar)

数据含义：第 1 列为维度名称（雷达各轴）；其余每一列为一组雷达数据（一个多边形），列名为图例。

CSV 示例：

维度,张三,李四,王五
销售,90,70,85
管理,80,85,75
技术,85,90,80
客服,75,80,90
研发,88,82,78

• 第 1 列：雷达轴名称（维度）。
• 第 2～N 列：每个人/实体在各维度上的数值，列名为图例。

6. K 线图 (candlestick)

数据含义：第 1 列为时间或类目；第 2～5 列依次为 开盘、最高、最低、收盘（OHLC）；第 6 列及以后为叠加的折线（可选）。

CSV 示例：

日期,开盘,最高,最低,收盘,成交量
2024-01-02,100,105,98,103,1000
2024-01-03,103,108,102,106,1200
2024-01-04,106,110,104,107,900

• 第 1 列：日期或类目。
• 第 2～5 列：必须为 4 列，顺序为 开盘、最高、最低、收盘。
• 第 6 列起（可选）：叠加的折线，列名为图例。

7. 热力图 (heatmap)

数据含义：第 1 列为 X 轴类目；其余列名为 Y 轴类目；单元格数值为颜色深浅。

CSV 示例：

时段,周一,周二,周三,周四,周五
9-10,23,45,12,34,56
10-11,45,67,34,56,78
11-12,12,34,56,78,23

• 第 1 列：X 轴（如时段）。
• 第 2～N 列：列名为 Y 轴（如周一～周五），数值为热力值。

8. 漏斗图 (funnel)

数据含义：第 1 列为阶段名称；其余每一列为一组漏斗数据，列名为图例。

CSV 示例：

阶段,渠道A,渠道B
访问,1000,800
注册,600,500
下单,300,280
支付,200,220

• 第 1 列：漏斗阶段名称。
• 第 2～N 列：每个渠道在该阶段的数值，列名为图例。

注意：任务流可视化通过 view_workflow.py:1016 调用 myapp/utils/py/py_echart.py 的统一入口 draw()。源码虽定义了 draw_funnel（py_echart.py:417），但 draw() 的分发分支（py_echart.py:520-547）中 没有 funnel，因此当前通过 echart-funnel 暂不会渲染漏斗图（draw('funnel', ...) 返回空）。上方 CSV 数据格式作为约定保留，待 draw() 接入 funnel 分支后即可生效。

9. 平行坐标系 (parallel)

数据含义：每一列为一个坐标轴（维度），每一行为一条线（一个样本）；支持数值列和字符串列（字符串会按类目轴处理）。

CSV 示例：

价格,销量,评分,地区
100,200,4.5,华北
150,180,4.2,华南
80,250,4.8,华东

• 每列：一个维度（轴）。
• 每行：一条折线穿过各轴上的取值。
• 数值列自动按最小/最大缩放；字符串列会作为类目轴。

注意：任务流可视化通过 view_workflow.py:1016 调用 myapp/utils/py/py_echart.py 的 draw()，其中已分发 parallel（py_echart.py:546），平行坐标系可正常生效。另一份 plugin_echart.py 的 draw() 未包含 parallel 分支，但任务可视化并未使用该实现（仓库中无导入方）。

10. 树图 (tree) — 仅 JSON

数据含义：层级结构。每个节点有 name，子节点放在 children 中。若根级是数组，会自动包在一个名为 root 的根节点下。

JSON 示例（单根）：

{
  "name": "根节点",
  "children": [
    {
      "name": "分支A",
      "children": [
        { "name": "叶子A1" },
        { "name": "叶子A2" }
      ]
    },
    {
      "name": "分支B",
      "children": [
        { "name": "叶子B1" }
      ]
    }
  ]
}

JSON 示例（多根，会合并为 root）：

[
  {
    "name": "节点1",
    "children": [
      { "name": "子节点1-1" }
    ]
  },
  {
    "name": "节点2",
    "children": []
  }
]

11. 旭日图 (sunburst) — 仅 JSON

数据含义：与树图类似的层级结构，用于旭日图展示；顶层为内圈，逐层向外。

JSON 示例：

[
  {
    "name": "类别1",
    "value": 100,
    "children": [
      { "name": "子类1-1", "value": 60 },
      { "name": "子类1-2", "value": 40 }
    ]
  },
  {
    "name": "类别2",
    "value": 80,
    "children": [
      { "name": "子类2-1", "value": 50 }
    ]
  }
]

• name：节点名称。
• value：该节点数值（影响扇区大小）。
• children：子节点，结构同上。

三、图表类型与文件格式对照

「draw() 已分发」一列依据 myapp/utils/py/py_echart.py 的 draw() 入口；任务流可视化插件 plugin_echart.py 的支持范围略窄（不含 parallel、funnel）。

四、使用方式简述

在代码中通过 draw(chart_type, file_path) 调用（myapp/utils/py/py_echart.py:520）：

• chart_type：上表中的「英文类型名」，如 'line'、'bar'、'pie'、'tree' 等。
• file_path：CSV 或 JSON 文件的路径（树图、旭日图请使用 JSON）。

按上述格式准备 CSV/JSON 后，即可生成对应类型的 ECharts 图表配置。

五、与任务流 metric.json 的配合

任务/算子在运行目录中写出 metric.json，平台据此在任务流运行结果页渲染 ECharts 图表。metric.json 形如（源码示例见 myapp/utils/py/py_echart.py:566-571）：

{
  "metric_type": "echart-parallel",
  "file_path": "/mnt/admin/pipeline/ray_hyperparams/hyperparams_r_lightgbm.csv"
}

• metric_type：echart-<chart_type>，其中 <chart_type> 取上表英文类型名（如 echart-line、echart-bar、echart-parallel）。
• file_path：上述格式的 CSV/JSON 数据文件路径。

任务流的整体使用见同目录 任务流.md。