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",
    x_column="Month",
    y_columns=["Temperature", "Humidity"],
    chart_title="月度变化趋势",
    output_name="monthly_trend",
    generate_files=True,          # 同时生成文件输出
    output_formats=["html"],      # 只生成 HTML（如需图片可加 "image"）
)

# 将 plotter.InputData 连接到上游表格输出端口后运行（见下方 pipeline 示例）
# 运行完成后，可从以下端口读取结果：
#   plotter.OutputPlotData.data / plotter.OutputHtmlFile.data / plotter.OutputImageFile.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(
    x_column="时间",
    y_columns="观测累计沉降",
    show_markers=True,
    line_style="dash",
    marker_sizes={"观测累计沉降": 8},
    marker_symbols={"观测累计沉降": "diamond"},
    # 常见的 layout 选项也可直接传入
    xaxis_tickangle=-45,
    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("ReadTables", table_fields=["累计沉降数据"])
pick_table = TableSelector("PickTable")
pick_table.table_name = "累计沉降数据"

chart = LineChartPlotter(mname="LineChart", x_column="时间", 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",
    x_column="因子名称",
    y_columns="因子超标倍数",
    chart_title="因子超标倍数 Top10",
    output_name="bar_top10",
    orientation="vertical",
)

参数说明

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", x_column="类别", 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",
    x_column="时间",
    y_columns="观测累计沉降",
    chart_title="观测累计沉降散点",
    marker_symbol="circle",
    marker_size=8,
    show_trendline=False,
)

参数说明

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",
    column="孔隙比",
    bins=30,
    bar_mode="overlay",
    opacity=0.7,
    chart_title="孔隙比分布",
)

参数说明

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",
    labels_column="超标因子类型",
    values_column="超标因子类型占比",
    hole_size=0.4,               # 0=饼图，0.4~0.6 常用环形图
    text_info="label+percent",
    chart_title="超标因子类型占比",
    output_name="factor_type_pie",
)

参数说明

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",
    table_title="统计结果表",
    max_rows=200,
    numeric_precision=3,
    enable_text_wrapping=True,
    generate_file=True,
    generate_plot_data=True,
    output_name="result_table",
)

参数说明

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_title="结果表", 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", generate_files=False, y_columns="预测累计沉降")
scatter_plotter = ScatterChartPlotter(mname="Scatter", generate_files=False, y_columns="观测累计沉降")

merger = PlotMerger(
    mname="Merger",
    chart_title="实测 vs 预测",
    enable_secondary_y=False,
    output_name="merged_chart",
    generate_files=True,
    generate_plot_data=True,
)
merger.add_dynamic_ports_in("InputPlotData1")
merger.add_dynamic_ports_in("InputPlotData2")

# 在 pipeline 中连接：
#   line_plotter.OutputPlotData >> merger.InputPlotData1
#   scatter_plotter.OutputPlotData >> merger.InputPlotData2

参数说明

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("Line", generate_files=False, y_columns="预测累计沉降")
scatter_plotter = ScatterChartPlotter("Scatter", generate_files=False, y_columns="观测累计沉降")

merger = PlotMerger("Merger", generate_files=True, 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()

更多信息