modules.plotters 模块帮助

本章节包含 modules.plotters 包中常用「数据可视化」模块的使用说明和示例，例如：

折线图、柱状图、散点图等基础图表模块
面向工程数据的专业绘图模块

本文档覆盖 gdisdk/modules/plotters.py 中的全部可视化模块：

LineChartPlotter：折线图
BarChartPlotter：柱状图
ScatterChartPlotter：散点图
HistogramPlotter：直方图
PieChartPlotter：饼图 / 环形图
TablePlotter：表格（HTML + PlotData）
PlotMerger：合并多个 PlotData 为复合图表

本页模块共用：上传 GDIM 前检查

适用模块：
- LineChartPlotter / BarChartPlotter / ScatterChartPlotter / HistogramPlotter / PieChartPlotter / TablePlotter / PlotMerger
必须检查：
- 上传后主要会使用 OutputPlotData，请保持 generate_plot_data=True；
- 上传前优先关闭文件输出，避免生成多余的本地 HTML / 图片文件：
  - 大多数图表模块使用 generate_files=False；
  - TablePlotter 使用 generate_file=False。
建议检查：
- PlotMerger 的上游图表模块也应能稳定提供 OutputPlotData，否则合并模块可能拿不到输入；
- 仅在非常明确需要额外保留文件结果时，才重新开启 OutputHtmlFile / OutputImageFile 对应的文件输出。
若遗漏，常见现象：
- 本地测试时能正常生成 HTML / 图片文件，但上传 GDIM 后这些本地文件输出通常不是平台真正需要的结果；
- PlotMerger 在上传后运行时拿不到上游 OutputPlotData，导致复合图为空或不完整。

LineChartPlotter

模块简介与适用场景

LineChartPlotter 用于将 TableData / pandas.DataFrame 绘制为折线图，并输出：
- OutputPlotData：用于 GDIM / Web 前端渲染的 JSON 图表数据；
- OutputHtmlFile / OutputImageFile：可选的本地 HTML / 图片文件（由 generate_files 与 output_formats 控制）。
典型场景：时间序列趋势、监测曲线、多指标对比、预测曲线与实测曲线展示等。

端口说明

输入端口 - InputData：输入表格数据（TableData 或 pandas.DataFrame）
输出端口 - OutputPlotData：图表 JSON 数据（用于 GDIM / Web 前端渲染；当 generate_plot_data=False 时为 None） - OutputHtmlFile：输出交互式 HTML 文件路径（当 generate_files=False 或 output_formats 未包含 "html" 时为 None） - OutputImageFile：输出图片文件路径（PNG/JPEG；当 generate_files=False 或 output_formats 未包含 "image" 时为 None）

快速上手示例

from gdisdk.modules.plotters import LineChartPlotter

plotter = LineChartPlotter(mname="LineChart")
plotter.x_column = "Month"
plotter.y_columns = ["Temperature", "Humidity"]
plotter.chart_title = "月度变化趋势"
plotter.output_name = "monthly_trend"
plotter.generate_files = True          # 同时生成文件输出
plotter.output_formats = ["html"]      # 只生成 HTML（如需图片可加 "image"）
# plotter.InputData = my_table
plotter.execute()
plot_data = plotter.OutputPlotData.data

参数说明

LineChartPlotter 参数一览
参数名	类型	默认值	说明
`x_column`	`str \| None`	`None`	x 轴列名（字段名或标题均可；未指定时会尝试自动选择）。
`y_columns`	`str \| list[str] \| None`	`None`	y 轴列名（单列或多列）。多列时会绘制多条曲线。
`color_column`	`str \| None`	`None`	分组列。用于按类别分色（例如不同测点/工况）。
`chart_title`	`str \| None`	`None`	图标题。支持动态模板：`{列名}`、`{mean(列名)}` 等。
`output_name`	`str`	`"line_chart"`	输出文件基础名（不含扩展名）。
`output_dir`	`str \| Path \| None`	`None`	输出目录；若 Pipeline 设置了 `workspace`，则优先使用 `workspace`。
`output_formats`	`str \| list[str] \| None`	`None`	输出格式：`"html"` / `"image"`。为 `None` 时默认仅生成 HTML。
`generate_files`	`bool`	`True`	是否生成 HTML/图片文件。本地测试时可设置为 `True`，上传 GDIM 时可设置为 `False` 以避免生成文件。
`generate_plot_data`	`bool`	`True`	是否生成 `OutputPlotData` （用于 GDIM / Web 前端渲染的 JSON 图表数据）。
`show_markers`	`bool`	`True`	是否显示点标记（纯曲线可设为 `False`）。
`show_lines`	`bool`	`True`	是否显示连线（只看散点可设为 `False`）。
`xaxis_tickformat`	`str \| None`	`None`	x 轴刻度格式（日期轴常用），例如 `"%Y-%m-%d"`。
`theme`	`str`	`"plotly_white"`	Plotly 主题（如 `plotly_white` / `plotly_dark` / `ggplot2` 等）。

高级参数与典型配置示例（可选）

LineChartPlotter 支持通过 **kwargs 传入 Plotly 的 trace/layout 细粒度配置（内部会自动区分并应用）。

plotter = LineChartPlotter(mname="LineChart")
plotter.x_column = "时间"
plotter.y_columns = "观测累计沉降"
plotter.show_markers = True
plotter.line_style = "dash"
plotter.marker_sizes = {"观测累计沉降": 8}
plotter.marker_symbols = {"观测累计沉降": "diamond"}
# 常见的 layout 选项也可直接传入
plotter.xaxis_tickangle = -45
plotter.hovermode = "x unified"

在 pipeline 中的使用方式

from gdisdk.connectors import log_in
from gdisdk.pipeline import PipeLine
from gdisdk.modules.plotters import LineChartPlotter
from gdisdk.modules.readers import GdimTableReader
from gdisdk.modules.filters import TableSelector

pipeline = PipeLine(app_name="ChartPipeline", app_title="折线图示例")
pipeline.update_gdim_state(token=log_in(), proj_id="你的GDIM项目ID")
pipeline.workspace = "test"

read_tables = GdimTableReader(mname="ReadTables")
read_tables.table_fields = ["累计沉降数据"]

pick_table = TableSelector(mname="PickTable")
pick_table.table_name = "累计沉降数据"

chart = LineChartPlotter(mname="LineChart")
chart.x_column = "时间"
chart.y_columns = "累计沉降"

links = (
    read_tables.OutputTable >> pick_table.InputTables
    | pick_table.OutputTable >> chart.InputData
)
pipeline.add_links(links)

result = pipeline.run()
print(chart.OutputPlotData.data)

更多信息

BarChartPlotter

模块简介与适用场景

BarChartPlotter 用于绘制柱状图（支持单列/多列分组柱状图），常用于 TopN、分类对比、分组统计等场景。
输入端口：InputData``（``TableData / DataFrame）
输出端口：OutputPlotData、OutputHtmlFile、OutputImageFile

端口说明

输入端口 - InputData：输入表格数据（TableData 或 pandas.DataFrame）
输出端口 - OutputPlotData：图表 JSON 数据（当 generate_plot_data=False 时为 None） - OutputHtmlFile：输出交互式 HTML 文件路径（当 generate_files=False 或 output_formats 未包含 "html" 时为 None） - OutputImageFile：输出图片文件路径（PNG/JPEG；当 generate_files=False 或 output_formats 未包含 "image" 时为 None）

快速上手示例

from gdisdk.modules.plotters import BarChartPlotter

plotter = BarChartPlotter(mname="PlotBar")
plotter.x_column = "因子名称"
plotter.y_columns = "因子超标倍数"
plotter.chart_title = "因子超标倍数 Top10"
plotter.output_name = "bar_top10"
plotter.orientation = "vertical"
# plotter.InputData = my_table
plotter.execute()
plot_data = plotter.OutputPlotData.data

参数说明

BarChartPlotter 参数一览
参数名	类型	默认值	说明
`x_column`	`str \| None`	`None`	类别轴列（柱子所属类别）。
`y_columns`	`str \| list[str] \| None`	`None`	值列。多列会生成分组柱状图。
`color_column`	`str \| None`	`None`	分组列（按类别上色）。通常与多 `y_columns` 二选一。
`orientation`	`str`	`"vertical"`	“vertical”（竖向）或 “horizontal”（横向）。
`output_formats`	`str \| list[str] \| None`	`None`	`"html"` / `"image"`，默认仅 HTML。
`generate_files`	`bool`	`True`	是否生成文件输出。本地测试时可设置为 `True`，上传 GDIM 时可设置为 `False` 以避免生成文件。
`generate_plot_data`	`bool`	`True`	是否生成 `OutputPlotData` （用于 GDIM / Web 前端渲染的 JSON 图表数据）。

在 pipeline 中的使用方式

from gdisdk.pipeline.pipeline import PipeLine
from gdisdk.modules.plotters import BarChartPlotter

pipe = PipeLine(app_name="BarDemo", app_title="柱状图示例", version="1.0.0")
plot_bar = BarChartPlotter(mname="PlotBar")
plot_bar.x_column = "类别"
plot_bar.y_columns = "数值"

# links = upstream.OutputTable >> plot_bar.InputData
# pipe.add_links(links)
# pipe.run()

更多信息

ScatterChartPlotter

模块简介与适用场景

ScatterChartPlotter 用于绘制散点图（可选趋势线、按颜色/大小映射），适用于相关性分析、实测点展示、分组对比等。
输入端口：InputData``（``TableData / DataFrame）
输出端口：OutputPlotData、OutputHtmlFile、OutputImageFile

端口说明

输入端口 - InputData：输入表格数据（TableData 或 pandas.DataFrame）
输出端口 - OutputPlotData：图表 JSON 数据（当 generate_plot_data=False 时为 None） - OutputHtmlFile：输出交互式 HTML 文件路径（当 generate_files=False 或 output_formats 未包含 "html" 时为 None） - OutputImageFile：输出图片文件路径（PNG/JPEG；当 generate_files=False 或 output_formats 未包含 "image" 时为 None）

快速上手示例

from gdisdk.modules.plotters import ScatterChartPlotter

plotter = ScatterChartPlotter(mname="PlotScatter")
plotter.x_column = "时间"
plotter.y_columns = "观测累计沉降"
plotter.chart_title = "观测累计沉降散点"
plotter.marker_symbol = "circle"
plotter.marker_size = 8
plotter.show_trendline = False
# plotter.InputData = my_table
plotter.execute()
plot_data = plotter.OutputPlotData.data

参数说明

ScatterChartPlotter 参数一览
参数名	类型	默认值	说明
`x_column`	`str \| None`	`None`	x 轴列名。
`y_columns`	`str \| list[str] \| None`	`None`	y 轴列名（单列或多列）。
`color_column`	`str \| None`	`None`	按类别分色（与多 `y_columns` 同时使用时需谨慎）。
`size_column`	`str \| None`	`None`	点大小映射列。若设置，将忽略 `marker_size`。
`show_trendline`	`bool`	`False`	是否绘制趋势线（用于相关性/回归可视化）。
`marker_symbol`	`str`	`"circle"`	点样式（如 `circle/square/diamond/cross/x` 等）。
`marker_size`	`float \| None`	`None`	点大小（未设置 `size_column` 时生效）。

更多信息

HistogramPlotter

模块简介与适用场景

HistogramPlotter 用于绘制直方图（可叠加分组直方图、可选 rug），适用于分布分析、频数统计、异常值检查等。
输入端口：InputData``（``TableData / DataFrame）
输出端口：OutputPlotData、OutputHtmlFile、OutputImageFile

端口说明

输入端口 - InputData：输入表格数据（TableData 或 pandas.DataFrame）
输出端口 - OutputPlotData：图表 JSON 数据（当 generate_plot_data=False 时为 None） - OutputHtmlFile：输出交互式 HTML 文件路径（当 generate_files=False 或 output_formats 未包含 "html" 时为 None） - OutputImageFile：输出图片文件路径（PNG/JPEG；当 generate_files=False 或 output_formats 未包含 "image" 时为 None）

快速上手示例

from gdisdk.modules.plotters import HistogramPlotter

plotter = HistogramPlotter(mname="Hist")
plotter.column = "孔隙比"
plotter.bins = 30
plotter.bar_mode = "overlay"
plotter.opacity = 0.7
plotter.chart_title = "孔隙比分布"
# plotter.InputData = my_table
plotter.execute()
plot_data = plotter.OutputPlotData.data

参数说明

HistogramPlotter 参数一览
参数名	类型	默认值	说明
`column`	`str \| None`	`None`	要统计分布的数值列。
`color_column`	`str \| None`	`None`	分组列（叠加/分组显示不同类别分布）。
`bins`	`int \| None`	`None`	分箱数。`None` 时自动估计。
`bar_mode`	`str`	`"overlay"`	多组直方图展示方式：`overlay/stack/group`。
`opacity`	`float`	`0.7`	透明度（叠加模式下常用）。
`show_rug`	`bool`	`False`	是否显示 rug（边缘点分布）。

更多信息

PieChartPlotter

模块简介与适用场景

PieChartPlotter 用于绘制饼图/环形图（通过 hole_size 控制），适用于占比结构展示（如类型占比、来源占比等）。
输入端口：InputData``（``TableData / DataFrame）
输出端口：OutputPlotData、OutputHtmlFile、OutputImageFile

端口说明

输入端口 - InputData：输入表格数据（TableData 或 pandas.DataFrame）
输出端口 - OutputPlotData：图表 JSON 数据（当 generate_plot_data=False 时为 None） - OutputHtmlFile：输出交互式 HTML 文件路径（当 generate_files=False 或 output_formats 未包含 "html" 时为 None） - OutputImageFile：输出图片文件路径（PNG/JPEG；当 generate_files=False 或 output_formats 未包含 "image" 时为 None）

快速上手示例

from gdisdk.modules.plotters import PieChartPlotter

plotter = PieChartPlotter(mname="Pie")
plotter.labels_column = "超标因子类型"
plotter.values_column = "超标因子类型占比"
plotter.hole_size = 0.4               # 0=饼图，0.4~0.6 常用环形图
plotter.text_info = "label+percent"
plotter.chart_title = "超标因子类型占比"
plotter.output_name = "factor_type_pie"
# plotter.InputData = my_table
plotter.execute()
plot_data = plotter.OutputPlotData.data

参数说明

PieChartPlotter 参数一览
参数名	类型	默认值	说明
`labels_column`	`str \| None`	`None`	扇区标签列。
`values_column`	`str \| None`	`None`	扇区数值列。
`hole_size`	`float`	`0.0`	中心孔洞比例（0-1），用于环形图。
`text_info`	`str`	`"label+percent"`	文本信息：`label/percent/value` 的组合或 `none`。
`text_position`	`str`	`"outside"`	文本位置：`inside/outside/auto/none`。

更多信息

TablePlotter

模块简介与适用场景

TablePlotter 用于把表格数据渲染为可交互的 HTML 表格，并输出可供前端渲染的 PlotData。
输入端口：InputData``（支持 ``TableData / TableCollection / DataFrame）
输出端口：OutputHtmlFile、OutputPlotData
典型场景：在报告/看板中展示计算结果表；对 TableCollection 的主表/子表进行合并展示；对中文表格做更友好的列宽与自动换行处理。

端口说明

输入端口 - InputData：输入表格数据（TableData / TableCollection / pandas.DataFrame）
输出端口 - OutputPlotData：表格 PlotData（用于 GDIM / Web 前端渲染；当 generate_plot_data=False 时为 None） - OutputHtmlFile：输出 HTML 表格文件路径（当 generate_file=False 时为 None）

快速上手示例

from gdisdk.modules.plotters import TablePlotter

plotter = TablePlotter(mname="Table")
plotter.table_title = "统计结果表"
plotter.max_rows = 200
plotter.numeric_precision = 3
plotter.enable_text_wrapping = True
plotter.generate_file = True
plotter.generate_plot_data = True
plotter.output_name = "result_table"
# plotter.InputData = my_table
plotter.execute()
plot_data = plotter.OutputPlotData.data

参数说明

TablePlotter 参数一览
参数名	类型	默认值	说明
`table_title`	`str \| None`	`None`	表格标题（可配合 `show_title` 居中显示）。
`max_rows`	`int \| None`	`None`	最多展示行数（避免超大表导致输出过大）。
`columns`	`list[str] \| None`	`None`	指定显示列与顺序（字段名或标题均可）。
`numeric_precision`	`int \| dict[str,int]`	`3`	数值精度（可全局或按列配置）。
`show_main_table`	`bool`	`True`	输入为 `TableCollection` 时是否显示主表。
`show_sub_tables`	`bool`	`True`	输入为 `TableCollection` 时是否显示子表。
`merge_related_cells`	`bool`	`True`	合并主/子表相关列的重复单元格（更适合 “分组表” 展示）。
`width_type`	`"relative" \| "absolute"`	`"relative"`	列宽计算方式：相对比例或绝对像素（超宽时可滚动）。
`enable_text_wrapping`	`bool`	`True`	自动换行（更适合中文长文本）。

在 pipeline 中的使用方式

from gdisdk.pipeline.pipeline import PipeLine
from gdisdk.modules.plotters import TablePlotter

pipeline = PipeLine(app_name="TableDemo", app_title="表格展示示例", version="1.0.0")
table = TablePlotter(mname="Table")
table.table_title = "结果表"
table.max_rows = 200

# links = upstream.OutputTable >> table.InputData
# pipeline.add_links(links)
# pipeline.run()

更多信息

PlotMerger

模块简介与适用场景

PlotMerger 用于把多个图表模块输出的 PlotData``（例如 ``LineChartPlotter.OutputPlotData、ScatterChartPlotter.OutputPlotData）合并为一个复合图表。
输入端口为动态端口：通过 add_dynamic_ports_in("InputPlotData1")、add_dynamic_ports_in("InputPlotData2") 等方式添加任意数量的输入端口。
输出端口：OutputPlotData、OutputHtmlFile、OutputImageFile。
典型场景：把预测曲线（Line）与实测点（Scatter）合并到同一张图；多来源指标叠加对比；双 y 轴复合图。

端口说明

输入端口 - InputPlotData1 / InputPlotData2 / …：动态输入端口（需要先通过 add_dynamic_ports_in(...) 创建），输入为 PlotData``（来自其它绘图模块的 ``OutputPlotData）
输出端口 - OutputPlotData：合并后的 PlotData（当 generate_plot_data=False 时为 None） - OutputHtmlFile：输出交互式 HTML 文件路径（当 generate_files=False 或 output_formats 未包含 "html" 时为 None） - OutputImageFile：输出图片文件路径（PNG/JPEG；当 generate_files=False 或 output_formats 未包含 "image" 时为 None）

快速上手示例

from gdisdk.modules.plotters import LineChartPlotter, ScatterChartPlotter, PlotMerger

line_plotter = LineChartPlotter(mname="Line")
line_plotter.generate_files = False
line_plotter.y_columns = "预测累计沉降"

scatter_plotter = ScatterChartPlotter(mname="Scatter")
scatter_plotter.generate_files = False
scatter_plotter.y_columns = "观测累计沉降"

merger = PlotMerger(mname="Merger")
merger.chart_title = "实测 vs 预测"
merger.enable_secondary_y = False
merger.output_name = "merged_chart"
merger.generate_files = True
merger.generate_plot_data = True
merger.add_dynamic_ports_in("InputPlotData1")
merger.add_dynamic_ports_in("InputPlotData2")
# line_plotter.InputData = table1
# scatter_plotter.InputData = table2
line_plotter.execute()
scatter_plotter.execute()
merger.InputPlotData1 = line_plotter.OutputPlotData.data
merger.InputPlotData2 = scatter_plotter.OutputPlotData.data
merger.execute()
plot_data = merger.OutputPlotData.data

参数说明

PlotMerger 参数一览
参数名	类型	默认值	说明
`all_ports_required`	`bool`	`True`	是否要求所有动态端口都有数据后才执行合并。
`chart_title`	`str \| None`	`None`	合并图标题。支持按源引用：`"{InputPlotData1}"` 或 `"{0} vs {1}"`。
`enable_secondary_y`	`bool`	`False`	是否启用双 y 轴。
`secondary_y_sources`	`list[str \| int] \| None`	`None`	右轴来源（端口名或索引）。未指定且启用双轴时，默认除第一源外都放右轴。
`trace_name_prefix`	`dict[str \| int, str] \| None`	`None`	为不同来源的 trace 名称增加前缀（便于图例区分）。
`color_mode`	`"original" \| "manual" \| "auto"`	`"auto"`	颜色策略：保留原色 / 手动覆盖 / 自动分配。
`output_formats`	`str \| list[str] \| None`	`None`	`"html"` / `"image"`，默认仅 HTML。

在 pipeline 中的使用方式

from gdisdk.pipeline.pipeline import PipeLine
from gdisdk.modules.plotters import LineChartPlotter, ScatterChartPlotter, PlotMerger

pipeline = PipeLine(app_name="MergeDemo", app_title="复合图示例", version="1.0.0")

line_plotter = LineChartPlotter(mname="Line")
line_plotter.generate_files = False
line_plotter.y_columns = "预测累计沉降"

scatter_plotter = ScatterChartPlotter(mname="Scatter")
scatter_plotter.generate_files = False
scatter_plotter.y_columns = "观测累计沉降"

merger = PlotMerger(mname="Merger")
merger.generate_files = True
merger.generate_plot_data = True
merger.add_dynamic_ports_in("InputPlotData1")
merger.add_dynamic_ports_in("InputPlotData2")

# links = (
#     upstream1.OutputTable >> line_plotter.InputData
#     | upstream2.OutputTable >> scatter_plotter.InputData
#     | line_plotter.OutputPlotData >> merger.InputPlotData1
#     | scatter_plotter.OutputPlotData >> merger.InputPlotData2
# )
# pipeline.add_links(links)
# pipeline.run()

更多信息