From 55b2fd310d16454e1e8d180b13d652e83dfe1948 Mon Sep 17 00:00:00 2001 From: Kkkakania <200867803+Kkkakania@users.noreply.github.com> Date: Fri, 19 Jun 2026 17:30:49 +0800 Subject: [PATCH] Add beginner gallery sample pack --- README.md | 17 +++++++ docs/beginner_20_plots.md | 53 ++++++++++++++++++++ examples/sample-pack/README.md | 50 ++++++++++++++++++ examples/sample-pack/sample_measurements.csv | 13 +++++ 4 files changed, 133 insertions(+) create mode 100644 docs/beginner_20_plots.md create mode 100644 examples/sample-pack/README.md create mode 100644 examples/sample-pack/sample_measurements.csv diff --git a/README.md b/README.md index 07245d4..7234449 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,19 @@ English repository name: `scientific-plotting-function-library`. 适用对象：电气工程及其自动化、信号处理、控制工程方向的本科 / 研究生 / 论文作者。 +## 30 秒新手路径 + +如果你第一次打开这个仓库，先不要从 1000 个模板里硬找。按下面三条路径走： + +| 你现在想做什么 | 入口 | 结果 | +|---|---|---| +| 先跑通几张最常用的论文图 | [`examples/sample-pack/`](examples/sample-pack/) | 用 3 个免费样例理解目录、合成数据和导出方式 | +| 已经有 CSV，想走完整导出自查流程 | [`examples/csv-workflow/`](examples/csv-workflow/) | Python/MATLAB 双语从 CSV 导出 PNG/PDF，并填写投稿前检查报告 | +| 从常见科研场景选图 | [`docs/beginner_20_plots.md`](docs/beginner_20_plots.md) | 20 个入门模板，覆盖折线、散点、误差、热力图、控制、电气等场景 | +| 已经知道图型名称 | [`catalog.md`](catalog.md) 或 `gallery/index.html` | 按名称、类别、tag 找到 Python/MATLAB 对照实现 | + +所有公开样例都使用合成数据和可审计代码生成，不包含论文截图、课程资料、私有数据或商业模板。 + ## 项目关系 这个仓库是“大型绘图函数库 / gallery 层”，负责沉淀大量可复用模板、配色和跨语言参考实现。 @@ -39,10 +52,14 @@ English repository name: `scientific-plotting-function-library`. ├── gallery/ 1000 张模板 PNG + index.html（搜索+分类+语言筛选） ├── docs/ 完整文档集（docs/learning/ 资料精读笔记 ×6） │ ├── quick_start.md 5 分钟上手 +│ ├── beginner_20_plots.md 新手 20 图路径 │ ├── chart_selection.md 图型决策指南 │ ├── api_reference.md API 参考 │ ├── style_guide.md 模板风格规范 │ └── provenance_policy.md clean-room 发布边界 +├── examples/ +│ ├── sample-pack/ 免费 sample pack：3 个样例入口 + 合成 CSV +│ └── csv-workflow/ CSV 到投稿前图件自查工作流 ├── scripts/ 辅助脚本 │ ├── merge_batch_manifests.py 批次账本合并为 manifest 源 │ ├── build_manifest.py 重生成 manifest.json + catalog.md diff --git a/docs/beginner_20_plots.md b/docs/beginner_20_plots.md new file mode 100644 index 0000000..f5dd695 --- /dev/null +++ b/docs/beginner_20_plots.md @@ -0,0 +1,53 @@ +# 新手 20 图路径 + +这个页面只放最常用、最容易复用的 20 个入口。每个条目都对应现有的 Python/MATLAB 对照模板，适合先跑通，再替换成自己的实验数据。 + +## 怎么使用 + +```bash +# Python：先跑一个模板 +python templates/python/line_basic.py + +# MATLAB：在仓库根目录运行 +addpath(genpath('templates/matlab')); +addpath(genpath('_utils/matlab')); +fig = line_basic(); +``` + +如果你还不知道该选哪个图，先看“想表达什么”，再打开对应模板源码。所有模板默认使用合成数据；替换数据时保留模板的主题、配色和导出方式即可。 + +## 20 个推荐入口 + +| 场景 | 推荐模板 | 适合表达 | Python | MATLAB | +|---|---|---|---|---| +| 单个变量随时间变化 | `line_basic` | 趋势、衰减、响应曲线 | [`templates/python/line_basic.py`](../templates/python/line_basic.py) | [`templates/matlab/line_basic.m`](../templates/matlab/line_basic.m) | +| 多组曲线对比 | `line_multi` | 多算法、多工况、多传感器 | [`templates/python/line_multi.py`](../templates/python/line_multi.py) | [`templates/matlab/line_multi.m`](../templates/matlab/line_multi.m) | +| 两个变量相关性 | `scatter_regression` | 实测值与拟合关系 | [`templates/python/scatter_regression.py`](../templates/python/scatter_regression.py) | [`templates/matlab/scatter_regression.m`](../templates/matlab/scatter_regression.m) | +| 均值和误差 | `bar_error` | 组间均值、标准差、标准误 | [`templates/python/bar_error.py`](../templates/python/bar_error.py) | [`templates/matlab/bar_error.m`](../templates/matlab/bar_error.m) | +| 分组柱状对比 | `bar_grouped` | 多组指标横向比较 | [`templates/python/bar_grouped.py`](../templates/python/bar_grouped.py) | [`templates/matlab/bar_grouped.m`](../templates/matlab/bar_grouped.m) | +| 组成占比 | `bar_stacked` | 构成、累计贡献、能量分解 | [`templates/python/bar_stacked.py`](../templates/python/bar_stacked.py) | [`templates/matlab/bar_stacked.m`](../templates/matlab/bar_stacked.m) | +| 二维矩阵 | `heatmap_basic` | 参数扫描、混淆矩阵、相关强度 | [`templates/python/heatmap_basic.py`](../templates/python/heatmap_basic.py) | [`templates/matlab/heatmap_basic.m`](../templates/matlab/heatmap_basic.m) | +| 带数值标注的矩阵 | `heatmap_annotated` | 小尺寸热力图、表格型结果 | [`templates/python/heatmap_annotated.py`](../templates/python/heatmap_annotated.py) | [`templates/matlab/heatmap_annotated.m`](../templates/matlab/heatmap_annotated.m) | +| 分布形状 | `histogram_basic` | 误差分布、残差、测量噪声 | [`templates/python/histogram_basic.py`](../templates/python/histogram_basic.py) | [`templates/matlab/histogram_basic.m`](../templates/matlab/histogram_basic.m) | +| 分组分布 | `box_basic` | 不同条件下的离散程度 | [`templates/python/box_basic.py`](../templates/python/box_basic.py) | [`templates/matlab/box_basic.m`](../templates/matlab/box_basic.m) | +| 分布密度 | `violin_basic` | 小样本分布形态对比 | [`templates/python/violin_basic.py`](../templates/python/violin_basic.py) | [`templates/matlab/violin_basic.m`](../templates/matlab/violin_basic.m) | +| 均值和置信带 | `confidence_band` | 重复实验均值、时序不确定性 | [`templates/python/confidence_band.py`](../templates/python/confidence_band.py) | [`templates/matlab/confidence_band.m`](../templates/matlab/confidence_band.m) | +| 单点误差棒 | `errorbar_basic` | 测量误差、估计置信区间 | [`templates/python/errorbar_basic.py`](../templates/python/errorbar_basic.py) | [`templates/matlab/errorbar_basic.m`](../templates/matlab/errorbar_basic.m) | +| 控制系统频响 | `bode_diagram` | 幅频/相频特性 | [`templates/python/bode_diagram.py`](../templates/python/bode_diagram.py) | [`templates/matlab/bode_diagram.m`](../templates/matlab/bode_diagram.m) | +| 状态轨迹 | `phase_portrait` | 非线性系统、动态行为 | [`templates/python/phase_portrait.py`](../templates/python/phase_portrait.py) | [`templates/matlab/phase_portrait.m`](../templates/matlab/phase_portrait.m) | +| 角度/方向数据 | `polar_basic` | 方向响应、周期信号 | [`templates/python/polar_basic.py`](../templates/python/polar_basic.py) | [`templates/matlab/polar_basic.m`](../templates/matlab/polar_basic.m) | +| 等值线 | `contour_lines` | 二维函数、参数面投影 | [`templates/python/contour_lines.py`](../templates/python/contour_lines.py) | [`templates/matlab/contour_lines.m`](../templates/matlab/contour_lines.m) | +| 三维曲面 | `surface_3d` | 响应面、空间场、优化结果 | [`templates/python/surface_3d.py`](../templates/python/surface_3d.py) | [`templates/matlab/surface_3d.m`](../templates/matlab/surface_3d.m) | +| 多变量降维 | `biplot_pca` | PCA 载荷和样本关系 | [`templates/python/biplot_pca.py`](../templates/python/biplot_pca.py) | [`templates/matlab/biplot_pca.m`](../templates/matlab/biplot_pca.m) | +| 日历型数据 | `calendar_heatmap` | 每日负荷、活跃度、实验批次 | [`templates/python/calendar_heatmap.py`](../templates/python/calendar_heatmap.py) | [`templates/matlab/calendar_heatmap.m`](../templates/matlab/calendar_heatmap.m) | + +## 替换数据的顺序 + +1. 先运行模板默认的合成数据版本。 +2. 再把自己的数据整理成简单数组、CSV 或矩阵。 +3. 只替换模板开头的数据构造部分，先不要改主题和导出逻辑。 +4. 导出前检查字号、线宽、单位、图例和目标期刊尺寸。 + +## 边界 + +这个页面是选图导航，不是论文结果保证。模板只帮助你把已有数据表达得更清楚；科学结论、实验设计和投稿结果仍需要你自己负责。 diff --git a/examples/sample-pack/README.md b/examples/sample-pack/README.md new file mode 100644 index 0000000..cbfeddd --- /dev/null +++ b/examples/sample-pack/README.md @@ -0,0 +1,50 @@ +# 免费 sample pack + +这个目录是仓库的轻量入口，用来快速理解“公开样例、合成数据、模板源码、导出结果”之间的关系。它不是完整资料包，也不包含任何论文截图、课程资料、私有数据或商业模板。 + +## 包含什么 + +| 文件或模板 | 用途 | +|---|---| +| [`sample_measurements.csv`](sample_measurements.csv) | 一份很小的合成测量数据，字段为 `time`、`voltage`、`current`、`temperature` | +| [`templates/python/line_basic.py`](../../templates/python/line_basic.py) | 单条趋势线样例 | +| [`templates/python/scatter_regression.py`](../../templates/python/scatter_regression.py) | 散点 + 拟合样例 | +| [`templates/python/bar_error.py`](../../templates/python/bar_error.py) | 柱状 + 误差棒样例 | +| [`docs/beginner_20_plots.md`](../../docs/beginner_20_plots.md) | 继续扩展到 20 个常用图 | +| [`examples/csv-workflow/`](../csv-workflow/) | 从合成 CSV 到 PNG/PDF 导出和投稿前检查报告的完整流程 | + +## 快速运行 + +在仓库根目录运行： + +```bash +python templates/python/line_basic.py +python templates/python/scatter_regression.py +python templates/python/bar_error.py +``` + +这些命令会使用模板内置的合成数据，并在模板目录旁边生成 PNG。生成图仅用于本地预览，不需要提交回仓库。 + +## 用 sample CSV 跑一张图 + +```python +from _utils.python.data_loader import load_xy +from templates.python.line_basic import make_figure + +x, y = load_xy('examples/sample-pack/sample_measurements.csv', + x_col='time', + y_col='voltage') +fig = make_figure(x=x, y=y, title='Synthetic voltage response') +fig.savefig('sample_voltage_response.png', dpi=300) +``` + +如果要换成自己的数据，先把字段整理成简单 CSV，再替换 `x_col` 和 `y_col`。建议先导出 PNG 预览，最终投稿或报告再导出 PDF/SVG。 + +如果你想同时看 Python/MATLAB 双语脚本、PNG/PDF 导出和检查报告模板，继续看 +[`examples/csv-workflow/`](../csv-workflow/)。 + +## 公开发布边界 + +- 可以公开：原创模板、合成数据、生成脚本、可审计文档。 +- 不要提交：真实学生/实验室数据、论文截图、付费课程图、`.fig`、`.mat`、Office 文件、压缩包或本地生成的大量预览图。 +- 不承诺：论文录用、审稿通过、比赛结果或商业收益。 diff --git a/examples/sample-pack/sample_measurements.csv b/examples/sample-pack/sample_measurements.csv new file mode 100644 index 0000000..dd27e3b --- /dev/null +++ b/examples/sample-pack/sample_measurements.csv @@ -0,0 +1,13 @@ +time,voltage,current,temperature +0.0,0.12,0.015,25.0 +0.5,0.34,0.019,25.2 +1.0,0.58,0.024,25.5 +1.5,0.77,0.028,25.8 +2.0,0.91,0.031,26.0 +2.5,0.98,0.033,26.3 +3.0,1.01,0.034,26.5 +3.5,0.96,0.032,26.7 +4.0,0.86,0.029,26.8 +4.5,0.71,0.025,26.7 +5.0,0.52,0.021,26.5 +5.5,0.31,0.018,26.3