paperplotter 0.1.4__tar.gz → 0.1.6__tar.gz

{paperplotter-0.1.4/paperplotter.egg-info → paperplotter-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: paperplotter
-Version: 0.1.4
+Version: 0.1.6
 Summary: 一个为科研论文设计的声明式 Matplotlib 封装库，让复杂图表的创建变得简单直观。
 Author-email: VerNe <yuu_seeing@foxmail.com>
 License-Expression: MIT
@@ -33,13 +33,15 @@ Dynamic: license-file
 
 ## 核心理念与特性
 
-*   **🎨 声明式链式调用**: 像写句子一样构建你的图表，例如 `plotter.add_line(...).set_title(...).set_xlabel(...)`。
+*   **🎨 声明式链式调用**: 像写句子一样构建你的图表，例如 `plotter.add_line(...).set_title(...).set_xlabel(...)`。绘图后，后续修饰器会自动作用于最后一个活动的子图，无需重复指定目标。
 *   **🏷️ 基于标签的控制**: 给每个子图一个独一无二的 `tag`，之后就可以随时通过 `tag` 对其进行任何修改，告别混乱的 `axes[i][j]` 索引。
 *   **🧩 强大的布局系统**: 无论是简单的 `(行, 列)` 网格，还是使用 `mosaic` 实现的跨行跨列复杂布局，都能轻松定义。
 *   **🧱 声明式嵌套布局**: 通过一个字典即可一次性定义包含子网格的复杂层级布局，并使用 `'容器.子图'` 这样的直观路径进行引用，完美实现“图中图”。
-*   **📐 灵活的尺寸控制**: 除了传统的 `figsize`，还可以通过 `subplot_aspect` 指定子图单元格的宽高比，让 `PaperPlot` 自动计算最合适的画布尺寸。
-*   **✨ 内置科研主题**: 提供多种专业美观的内置样式，如 `publication`, `presentation` 等，一键切换图表风格。
+*   **📐 数据驱动的尺寸控制**: 除了传统的 `figsize`，还可以通过 `subplot_aspect` 指定子图单元格的宽高比，让 `PaperPlot` 自动计算最合适的画布尺寸，确保图表比例的专业性。
+*   **✨ 内置科研主题与调色板**: 提供多种专业美观的内置样式（如 `publication`）和调色板（如 `seaborn_deep`），一键切换图表风格和颜色方案，保证全局一致性。
 *   **🌐 全局图层级标注**: 提供了在整个画布（Figure）上添加文本、线条、方框和标签的 API，非常适合添加全局注释或高亮一组图表。
+*   **🔢 子图自动编号**: 通过 `add_subplot_labels()` 方法，可以一键为所有子图添加 `(a)`, `(b)`, `(c)`... 等学术论文中常见的编号，并支持高度定制化。
+*   **🔗 优雅的双Y轴（Twin-Axis）**: 彻底解决了 Matplotlib 双Y轴操作繁琐的问题。通过 `add_twinx()` 进入孪生轴上下文，然后可以继续使用链式调用进行绘图和修饰，最后通过 `target_primary()` 切回主轴。
 *   **🔬 丰富的领域专用图表**: 内置了科研中常用的图表类型，如光谱图、混淆矩阵、ROC 曲线、学习曲线、分岔图、相量图等。
 *   **🔧 智能美化工具**: `cleanup()` 方法可以智能地共享坐标轴、对齐标签；`cleanup_heatmaps()` 可以为多个热图创建共享的颜色条。
 
@@ -68,30 +70,31 @@ df_scatter = pd.DataFrame({
     'y': np.random.rand(50) * 10
 })
 
-# 2. 初始化 Plotter 并绘图
-# 对于简单布局，可以直接使用元组 (rows, cols)
-plotter = pp.Plotter(layout=(1, 2), figsize=(10, 4))
-
-# 3. 顺序添加图表，Plotter会自动填充网格
-# 第一次调用 add_line 会画在左边
-plotter.add_line(data=df_line, x='time', y='signal', tag='time_series')
-# 第二次调用 add_scatter 会画在右边
-plotter.add_scatter(data=df_scatter, x='x', y='y', tag='scatter_plot')
-
-# 4. 通过 tag 设置标题和标签
-plotter.set_title('time_series', 'Time Series Data')
-plotter.set_xlabel('time_series', 'Time (s)')
-plotter.set_ylabel('time_series', 'Signal')
-
-plotter.set_title('scatter_plot', 'Scatter Plot')
-plotter.set_xlabel('scatter_plot', 'X Value')
-plotter.set_ylabel('scatter_plot', 'Y Value')
-
-# 5. 保存图像
-plotter.save("quick_start_figure.png")
+# 2. 初始化 Plotter 并通过链式调用绘图和修饰
+(
+    pp.Plotter(layout=(1, 2), figsize=(10, 4))
+    
+    # --- 绘制并修饰左图 ---
+    # add_line 将 'time_series' 设为活动tag
+    .add_line(data=df_line, x='time', y='signal', tag='time_series')
+    # 后续的修饰器会自动应用到 'time_series' 上
+    .set_title('Time Series Data')
+    .set_xlabel('Time (s)')
+    .set_ylabel('Signal')
+    
+    # --- 绘制并修饰右图 ---
+    # add_scatter 将 'scatter_plot' 设为新的活动tag
+    .add_scatter(data=df_scatter, x='x', y='y', tag='scatter_plot')
+    # 后续的修饰器会自动应用到 'scatter_plot' 上
+    .set_title('Scatter Plot')
+    .set_xlabel('X Value')
+    .set_ylabel('Y Value')
+    
+    # --- 保存图像 ---
+    .save("quick_start_figure.png")
+)
 ```
 
-
 ## 通过示例学习 (Learn from Examples)
 
 掌握 `PaperPlot` 最好的方法就是探索我们提供的丰富示例。每个示例都专注于一个核心功能，并附有详细的代码和注释。
@@ -101,56 +104,59 @@ plotter.save("quick_start_figure.png")
 | 示例 | 描述 | 关键功能 |
 | :--- | :--- | :--- |
 | **声明式嵌套布局**<br/> `Layout/declarative_nested_layout_example.py` | 使用字典来声明式地定义一个包含子网格的复杂、多层级布局，实现“图中图”的效果。 | `layout={...}`<br/> `tag='容器.子图'` |
-| **高级布局**<br/> `Layout/advanced_layout_example.py` | 展示如何使用列表定义一个跨列的复杂布局。 | `layout=[['A', 'B', 'B'], ...]` |
-| **行跨越**<br/> `Layout/row_span_example.py` | 创建一个图表，其中某个子图跨越多行。 | `layout=[['A', 'B'], ['A', 'C']]` |
-| **块跨越**<br/> `Layout/block_span_example.py` | 创建一个图表，其中某个子图同时跨越多行和多列。 | `layout=[['A', 'A', 'B'], ['A', 'A', 'C']]` |
-| **固定子图宽高比**<br/> `Layout/aspect_ratio_example.py` | 在不指定 `figsize` 的情况下，通过 `subplot_aspect` 保证每个子图单元格的宽高比，Plotter 会自动计算画布大小。 | `subplot_aspect=(16, 9)` |
+| **高级布局 (跨列)**<br/> `Layout/advanced_layout_example.py` | 展示如何使用列表定义一个跨列的复杂布局。 | `layout=[['A', 'B', 'B'], ...]`<br/>`get_ax_by_name()` |
+| **高级布局 (跨行)**<br/> `Layout/row_span_example.py` | 创建一个图表，其中某个子图跨越多行。 | `layout=[['A', 'B'], ['A', 'C']]` |
+| **高级布局 (块跨越)**<br/> `Layout/block_span_example.py` | 创建一个图表，其中某个子图同时跨越多行和多列。 | `layout=[['A', 'A', 'B'], ['A', 'A', 'C']]` |
+| **固定子图宽高比**<br/> `Layout/aspect_ratio_example.py` | 通过 `subplot_aspect` 保证每个子图单元格的宽高比，Plotter 会自动计算画布大小，无需指定 `figsize`。 | `subplot_aspect=(16, 9)` |
+| **组合图与内嵌图**<br/> `Features_Customization/composite_figure_example.py` | 创建一个 L 型的复杂图表（使用 `.` 作为空白占位符），并在其中一个子图内部嵌入一张图片。 | `layout=[['A', 'A'], ['B', '.']]`<br/>`add_inset_image()` |
 
 ### 功能与定制化 (Features & Customization)
 
 | 示例 | 描述 | 关键功能 |
 | :--- | :--- | :--- |
 | **多图网格**<br/> `Features_Customization/multi_plot_grid.py` | 在一个网格中通过链式调用混合绘制不同类型的图表。 | `plotter.add_...().add_...()` |
-| **高级定制**<br/> `Features_Customization/advanced_customization.py` | 演示如何使用 `get_ax()` "逃生舱口" 来获取原生的 Matplotlib `Axes` 对象，并添加任意 `Patch`（如椭圆）。 | `get_ax()`, `ax.add_patch()` |
-| **全局控制**<br/> `Features_Customization/global_controls_example.py` | 展示如何设置全局标题 (`suptitle`) 和创建全局图例。 | `set_suptitle()`, `add_global_legend()` |
+| **双Y轴 (Twin-Axis)**<br/> `Features_Customization/feature_expansion_example.py` | 演示如何通过上下文切换，流畅地在主轴和孪生轴上进行绘图和修饰。 | `add_twinx()`, `target_primary()`, `target_twin()` |
+| **缩放嵌入图 (Zoom Inset)**<br/> `Features_Customization/zoom_inset_example.py` | 在主图上创建一个放大特定区域的嵌入式子图，并自动添加连接线。 | `add_zoom_inset()` |
 | **共享颜色条**<br/> `Features_Customization/heatmap_colorbar_example.py` | 为多个热图创建一个共享的、能反映全局数据范围的颜色条。 | `add_heatmap(cbar=False)`, `cleanup_heatmaps()` |
+| **高级定制**<br/> `Features_Customization/advanced_customization.py` | 演示如何使用 `get_ax()` "逃生舱口" 来获取原生的 Matplotlib `Axes` 对象，并添加任意 `Patch`（如椭圆）。 | `get_ax()`, `add_patch()` |
+| **全局控制**<br/> `Features_Customization/global_controls_example.py` | 展示如何设置全局标题 (`suptitle`) 和创建全局图例。 | `set_suptitle()`, `add_global_legend()` |
 | **智能清理**<br/> `Features_Customization/cleanup_demonstration.py` | 演示 `cleanup()` 函数如何动态地为指定行/列的子图共享 X/Y 轴，并自动隐藏多余的刻度标签。 | `cleanup(auto_share=True)` |
-| **组合图与内嵌图**<br/> `Features_Customization/composite_figure_example.py` | 创建一个 L 型的复杂图表，并在其中一个子图内部嵌入一张图片。 | `layout=[['A', 'A'], ['B', '.']]`, `add_inset_image()` |
-| **功能扩展**<br/> `Features_Customization/feature_expansion_example.py` | 演示双Y轴 (`add_twinx`)、回归图 (`add_regplot`)、参考线 (`add_hline`) 和文本标注 (`add_text`) 等高级功能。 | `add_twinx()`, `add_regplot()`, `add_hline()`, `add_text()` |
 | **错误处理**<br/> `Features_Customization/error_handling_test.py` | 展示 `PaperPlot` 的自定义异常，如 `DuplicateTagError`, `TagNotFoundError`, `PlottingSpaceError`。 | `try...except pp.PaperPlotError` |
 
 ### 标注与高亮 (Annotation & Highlighting)
 
 | 示例 | 描述 | 关键功能 |
 | :--- | :--- | :--- |
-| **图层级标注**<br/>`Features_Customization/fig_annotation_example.py`| 演示添加跨越多个子图的画布级注解，如方框、标签和线条。| `fig_add_box()`, `fig_add_label()`, `fig_add_line()`, `fig_add_text()`|
+| **画布级标注**<br/>`Features_Customization/fig_annotation_example.py`| 演示添加跨越多个子图的画布级注解，如方框、标签和线条。| `fig_add_box()`, `fig_add_label()`, `fig_add_line()`, `fig_add_text()`|
 | **区域高亮**<br/>`Features_Customization/highlighting_example.py` | 展示如何在子图内部高亮特定的数据区域，并为整个图表添加边框。| `add_highlight_box()`, `fig_add_boundary_box()` |
+| **通用工具函数**<br/> `Data_Analysis_Utils/utility_functions_example.py` | 展示更多通用的修饰函数，如在高光谱上高亮特征峰和在时间序列上标记事件。 | `add_peak_highlights()`, `add_event_markers()` |
 
 ### 风格与美化 (Styles & Aesthetics)
 
 | 示例 | 描述 | 关键功能 |
 | :--- | :--- | :--- |
 | **风格画廊**<br/> `Styles_Aesthetics/style_gallery_example.py` | 循环遍历所有内置的绘图风格，并为每种风格生成一个示例图。 | `Plotter(style='...')` |
-| **统计标注**<br/> `Styles_Aesthetics/statistical_annotation_example.py` | 在箱线图上自动进行多组成对统计检验（如 t-test），并智能堆叠显著性标记。 | `add_box()`, `utils.add_pairwise_tests()` |
-| **美学与处理**<br/> `Styles_Aesthetics/aesthetic_and_processing_example.py` | 使用 `utils` 模块中的函数对数据进行平滑处理或根据条件高亮特定数据点。 | `utils.moving_average()`, `utils.highlight_points()` |
+| **统计标注**<br/> `Styles_Aesthetics/statistical_annotation_example.py` | 在箱线图上自动进行多组成对统计检验（如 t-test），并智能堆叠显著性标记。 | `add_box()`, `add_pairwise_tests()` |
+| **美学与处理**<br/> `Styles_Aesthetics/aesthetic_and_processing_example.py` | 对数据进行平滑处理或根据条件高亮特定数据点。 | `utils.moving_average()`, `add_conditional_scatter()` |
+| **统计图组合**<br/> `Features_Customization/statistical_plots_example.py` | 演示如何组合小提琴图和蜂群图，以及在箱线图上添加统计检验。 | `add_violin()`, `add_swarm()`, `add_box()`, `add_stat_test()` |
 
 ### 领域专用图 (Domain-Specific Plots)
 
 | 示例 | 描述 | 关键功能 |
 | :--- | :--- | :--- |
 | **领域专用图合集**<br/> `Domain_Specific_Plots/domain_specific_plots_example.py` | 一站式展示多种领域专用图，包括 SERS 光谱图、混淆矩阵、ROC 曲线和 PCA 散点图。 | `add_spectra()`, `add_confusion_matrix()`, `add_roc_curve()`, `add_pca_scatter()` |
-| **学习曲线**<br/> `Domain_Specific_Plots/learning_curve_example.py` | 绘制机器学习模型的学习曲线，帮助诊断过拟合或欠拟合问题。 | `utils.plot_learning_curve()` |
+| **3D 绘图**<br/> `Domain_Specific_Plots/3d_plots_example.py` | 展示如何创建 3D 线图和表面图。 | `ax_configs={'...': {'projection': '3d'}}`, `add_line3d()`, `add_surface()` |
+| **学习曲线**<br/> `Domain_Specific_Plots/learning_curve_example.py` | 绘制机器学习模型的学习曲线，帮助诊断过拟合或欠拟合问题。 | `add_learning_curve()` |
 | **SERS 浓度图**<br/> `Domain_Specific_Plots/concentration_map_example.py` | 绘制 SERS Mapping 浓度图，本质上是带有专业美化的热图。 | `add_concentration_map()` |
 | **电力系统时间序列**<br/> `Domain_Specific_Plots/power_timeseries_example.py` | 绘制电力系统动态仿真结果，并自动标记故障、切除等事件。 | `add_power_timeseries()` |
 | **相量图**<br/> `Domain_Specific_Plots/phasor_diagram_example.py` | 在极坐标上绘制电气工程中的相量图。 | `add_phasor_diagram()` |
-| **分岔图**<br/> `Domain_Specific_Plots/bifurcation_diagram_example.py` | 绘制常用于非线性系统和稳定性分析的分岔图。 | `add_scatter(rasterized=True)` |
+| **分岔图**<br/> `Domain_Specific_Plots/bifurcation_diagram_example.py` | 绘制常用于非线性系统和稳定性分析的分岔图。 | `add_bifurcation_diagram()` |
 
 ### 数据分析工具 (Data Analysis Utils)
 
 | 示例 | 描述 | 关键功能 |
 | :--- | :--- | :--- |
-| **数据分析工具集**<br/> `Data_Analysis_Utils/data_analysis_utils_example.py` | 演示如何对数据进行分布拟合 (`fit_and_plot_distribution`) 和数据分箱 (`bin_data`)。 | `utils.fit_and_plot_distribution()`, `utils.bin_data()` |
-| **通用工具函数**<br/> `Data_Analysis_Utils/utility_functions_example.py` | 展示更多通用的 `utils` 函数，如在高光谱上高亮特征峰 (`highlight_peaks`) 和在时间序列上标记事件 (`add_event_markers`)。 | `utils.highlight_peaks()`, `utils.add_event_markers()` |
+| **数据分析工具集**<br/> `Data_Analysis_Utils/data_analysis_utils_example.py` | 演示如何对数据进行分布拟合和数据分箱绘图。 | `add_distribution_fit()`, `add_binned_plot()` |
 
 ---
 

{paperplotter-0.1.4 → paperplotter-0.1.6}/README.md

@@ -9,13 +9,15 @@
 
 ## 核心理念与特性
 
-*   **🎨 声明式链式调用**: 像写句子一样构建你的图表，例如 `plotter.add_line(...).set_title(...).set_xlabel(...)`。
+*   **🎨 声明式链式调用**: 像写句子一样构建你的图表，例如 `plotter.add_line(...).set_title(...).set_xlabel(...)`。绘图后，后续修饰器会自动作用于最后一个活动的子图，无需重复指定目标。
 *   **🏷️ 基于标签的控制**: 给每个子图一个独一无二的 `tag`，之后就可以随时通过 `tag` 对其进行任何修改，告别混乱的 `axes[i][j]` 索引。
 *   **🧩 强大的布局系统**: 无论是简单的 `(行, 列)` 网格，还是使用 `mosaic` 实现的跨行跨列复杂布局，都能轻松定义。
 *   **🧱 声明式嵌套布局**: 通过一个字典即可一次性定义包含子网格的复杂层级布局，并使用 `'容器.子图'` 这样的直观路径进行引用，完美实现“图中图”。
-*   **📐 灵活的尺寸控制**: 除了传统的 `figsize`，还可以通过 `subplot_aspect` 指定子图单元格的宽高比，让 `PaperPlot` 自动计算最合适的画布尺寸。
-*   **✨ 内置科研主题**: 提供多种专业美观的内置样式，如 `publication`, `presentation` 等，一键切换图表风格。
+*   **📐 数据驱动的尺寸控制**: 除了传统的 `figsize`，还可以通过 `subplot_aspect` 指定子图单元格的宽高比，让 `PaperPlot` 自动计算最合适的画布尺寸，确保图表比例的专业性。
+*   **✨ 内置科研主题与调色板**: 提供多种专业美观的内置样式（如 `publication`）和调色板（如 `seaborn_deep`），一键切换图表风格和颜色方案，保证全局一致性。
 *   **🌐 全局图层级标注**: 提供了在整个画布（Figure）上添加文本、线条、方框和标签的 API，非常适合添加全局注释或高亮一组图表。
+*   **🔢 子图自动编号**: 通过 `add_subplot_labels()` 方法，可以一键为所有子图添加 `(a)`, `(b)`, `(c)`... 等学术论文中常见的编号，并支持高度定制化。
+*   **🔗 优雅的双Y轴（Twin-Axis）**: 彻底解决了 Matplotlib 双Y轴操作繁琐的问题。通过 `add_twinx()` 进入孪生轴上下文，然后可以继续使用链式调用进行绘图和修饰，最后通过 `target_primary()` 切回主轴。
 *   **🔬 丰富的领域专用图表**: 内置了科研中常用的图表类型，如光谱图、混淆矩阵、ROC 曲线、学习曲线、分岔图、相量图等。
 *   **🔧 智能美化工具**: `cleanup()` 方法可以智能地共享坐标轴、对齐标签；`cleanup_heatmaps()` 可以为多个热图创建共享的颜色条。
 
@@ -44,30 +46,31 @@ df_scatter = pd.DataFrame({
     'y': np.random.rand(50) * 10
 })
 
-# 2. 初始化 Plotter 并绘图
-# 对于简单布局，可以直接使用元组 (rows, cols)
-plotter = pp.Plotter(layout=(1, 2), figsize=(10, 4))
-
-# 3. 顺序添加图表，Plotter会自动填充网格
-# 第一次调用 add_line 会画在左边
-plotter.add_line(data=df_line, x='time', y='signal', tag='time_series')
-# 第二次调用 add_scatter 会画在右边
-plotter.add_scatter(data=df_scatter, x='x', y='y', tag='scatter_plot')
-
-# 4. 通过 tag 设置标题和标签
-plotter.set_title('time_series', 'Time Series Data')
-plotter.set_xlabel('time_series', 'Time (s)')
-plotter.set_ylabel('time_series', 'Signal')
-
-plotter.set_title('scatter_plot', 'Scatter Plot')
-plotter.set_xlabel('scatter_plot', 'X Value')
-plotter.set_ylabel('scatter_plot', 'Y Value')
-
-# 5. 保存图像
-plotter.save("quick_start_figure.png")
+# 2. 初始化 Plotter 并通过链式调用绘图和修饰
+(
+    pp.Plotter(layout=(1, 2), figsize=(10, 4))
+    
+    # --- 绘制并修饰左图 ---
+    # add_line 将 'time_series' 设为活动tag
+    .add_line(data=df_line, x='time', y='signal', tag='time_series')
+    # 后续的修饰器会自动应用到 'time_series' 上
+    .set_title('Time Series Data')
+    .set_xlabel('Time (s)')
+    .set_ylabel('Signal')
+    
+    # --- 绘制并修饰右图 ---
+    # add_scatter 将 'scatter_plot' 设为新的活动tag
+    .add_scatter(data=df_scatter, x='x', y='y', tag='scatter_plot')
+    # 后续的修饰器会自动应用到 'scatter_plot' 上
+    .set_title('Scatter Plot')
+    .set_xlabel('X Value')
+    .set_ylabel('Y Value')
+    
+    # --- 保存图像 ---
+    .save("quick_start_figure.png")
+)
 ```
 
-
 ## 通过示例学习 (Learn from Examples)
 
 掌握 `PaperPlot` 最好的方法就是探索我们提供的丰富示例。每个示例都专注于一个核心功能，并附有详细的代码和注释。
@@ -77,56 +80,59 @@ plotter.save("quick_start_figure.png")
 | 示例 | 描述 | 关键功能 |
 | :--- | :--- | :--- |
 | **声明式嵌套布局**<br/> `Layout/declarative_nested_layout_example.py` | 使用字典来声明式地定义一个包含子网格的复杂、多层级布局，实现“图中图”的效果。 | `layout={...}`<br/> `tag='容器.子图'` |
-| **高级布局**<br/> `Layout/advanced_layout_example.py` | 展示如何使用列表定义一个跨列的复杂布局。 | `layout=[['A', 'B', 'B'], ...]` |
-| **行跨越**<br/> `Layout/row_span_example.py` | 创建一个图表，其中某个子图跨越多行。 | `layout=[['A', 'B'], ['A', 'C']]` |
-| **块跨越**<br/> `Layout/block_span_example.py` | 创建一个图表，其中某个子图同时跨越多行和多列。 | `layout=[['A', 'A', 'B'], ['A', 'A', 'C']]` |
-| **固定子图宽高比**<br/> `Layout/aspect_ratio_example.py` | 在不指定 `figsize` 的情况下，通过 `subplot_aspect` 保证每个子图单元格的宽高比，Plotter 会自动计算画布大小。 | `subplot_aspect=(16, 9)` |
+| **高级布局 (跨列)**<br/> `Layout/advanced_layout_example.py` | 展示如何使用列表定义一个跨列的复杂布局。 | `layout=[['A', 'B', 'B'], ...]`<br/>`get_ax_by_name()` |
+| **高级布局 (跨行)**<br/> `Layout/row_span_example.py` | 创建一个图表，其中某个子图跨越多行。 | `layout=[['A', 'B'], ['A', 'C']]` |
+| **高级布局 (块跨越)**<br/> `Layout/block_span_example.py` | 创建一个图表，其中某个子图同时跨越多行和多列。 | `layout=[['A', 'A', 'B'], ['A', 'A', 'C']]` |
+| **固定子图宽高比**<br/> `Layout/aspect_ratio_example.py` | 通过 `subplot_aspect` 保证每个子图单元格的宽高比，Plotter 会自动计算画布大小，无需指定 `figsize`。 | `subplot_aspect=(16, 9)` |
+| **组合图与内嵌图**<br/> `Features_Customization/composite_figure_example.py` | 创建一个 L 型的复杂图表（使用 `.` 作为空白占位符），并在其中一个子图内部嵌入一张图片。 | `layout=[['A', 'A'], ['B', '.']]`<br/>`add_inset_image()` |
 
 ### 功能与定制化 (Features & Customization)
 
 | 示例 | 描述 | 关键功能 |
 | :--- | :--- | :--- |
 | **多图网格**<br/> `Features_Customization/multi_plot_grid.py` | 在一个网格中通过链式调用混合绘制不同类型的图表。 | `plotter.add_...().add_...()` |
-| **高级定制**<br/> `Features_Customization/advanced_customization.py` | 演示如何使用 `get_ax()` "逃生舱口" 来获取原生的 Matplotlib `Axes` 对象，并添加任意 `Patch`（如椭圆）。 | `get_ax()`, `ax.add_patch()` |
-| **全局控制**<br/> `Features_Customization/global_controls_example.py` | 展示如何设置全局标题 (`suptitle`) 和创建全局图例。 | `set_suptitle()`, `add_global_legend()` |
+| **双Y轴 (Twin-Axis)**<br/> `Features_Customization/feature_expansion_example.py` | 演示如何通过上下文切换，流畅地在主轴和孪生轴上进行绘图和修饰。 | `add_twinx()`, `target_primary()`, `target_twin()` |
+| **缩放嵌入图 (Zoom Inset)**<br/> `Features_Customization/zoom_inset_example.py` | 在主图上创建一个放大特定区域的嵌入式子图，并自动添加连接线。 | `add_zoom_inset()` |
 | **共享颜色条**<br/> `Features_Customization/heatmap_colorbar_example.py` | 为多个热图创建一个共享的、能反映全局数据范围的颜色条。 | `add_heatmap(cbar=False)`, `cleanup_heatmaps()` |
+| **高级定制**<br/> `Features_Customization/advanced_customization.py` | 演示如何使用 `get_ax()` "逃生舱口" 来获取原生的 Matplotlib `Axes` 对象，并添加任意 `Patch`（如椭圆）。 | `get_ax()`, `add_patch()` |
+| **全局控制**<br/> `Features_Customization/global_controls_example.py` | 展示如何设置全局标题 (`suptitle`) 和创建全局图例。 | `set_suptitle()`, `add_global_legend()` |
 | **智能清理**<br/> `Features_Customization/cleanup_demonstration.py` | 演示 `cleanup()` 函数如何动态地为指定行/列的子图共享 X/Y 轴，并自动隐藏多余的刻度标签。 | `cleanup(auto_share=True)` |
-| **组合图与内嵌图**<br/> `Features_Customization/composite_figure_example.py` | 创建一个 L 型的复杂图表，并在其中一个子图内部嵌入一张图片。 | `layout=[['A', 'A'], ['B', '.']]`, `add_inset_image()` |
-| **功能扩展**<br/> `Features_Customization/feature_expansion_example.py` | 演示双Y轴 (`add_twinx`)、回归图 (`add_regplot`)、参考线 (`add_hline`) 和文本标注 (`add_text`) 等高级功能。 | `add_twinx()`, `add_regplot()`, `add_hline()`, `add_text()` |
 | **错误处理**<br/> `Features_Customization/error_handling_test.py` | 展示 `PaperPlot` 的自定义异常，如 `DuplicateTagError`, `TagNotFoundError`, `PlottingSpaceError`。 | `try...except pp.PaperPlotError` |
 
 ### 标注与高亮 (Annotation & Highlighting)
 
 | 示例 | 描述 | 关键功能 |
 | :--- | :--- | :--- |
-| **图层级标注**<br/>`Features_Customization/fig_annotation_example.py`| 演示添加跨越多个子图的画布级注解，如方框、标签和线条。| `fig_add_box()`, `fig_add_label()`, `fig_add_line()`, `fig_add_text()`|
+| **画布级标注**<br/>`Features_Customization/fig_annotation_example.py`| 演示添加跨越多个子图的画布级注解，如方框、标签和线条。| `fig_add_box()`, `fig_add_label()`, `fig_add_line()`, `fig_add_text()`|
 | **区域高亮**<br/>`Features_Customization/highlighting_example.py` | 展示如何在子图内部高亮特定的数据区域，并为整个图表添加边框。| `add_highlight_box()`, `fig_add_boundary_box()` |
+| **通用工具函数**<br/> `Data_Analysis_Utils/utility_functions_example.py` | 展示更多通用的修饰函数，如在高光谱上高亮特征峰和在时间序列上标记事件。 | `add_peak_highlights()`, `add_event_markers()` |
 
 ### 风格与美化 (Styles & Aesthetics)
 
 | 示例 | 描述 | 关键功能 |
 | :--- | :--- | :--- |
 | **风格画廊**<br/> `Styles_Aesthetics/style_gallery_example.py` | 循环遍历所有内置的绘图风格，并为每种风格生成一个示例图。 | `Plotter(style='...')` |
-| **统计标注**<br/> `Styles_Aesthetics/statistical_annotation_example.py` | 在箱线图上自动进行多组成对统计检验（如 t-test），并智能堆叠显著性标记。 | `add_box()`, `utils.add_pairwise_tests()` |
-| **美学与处理**<br/> `Styles_Aesthetics/aesthetic_and_processing_example.py` | 使用 `utils` 模块中的函数对数据进行平滑处理或根据条件高亮特定数据点。 | `utils.moving_average()`, `utils.highlight_points()` |
+| **统计标注**<br/> `Styles_Aesthetics/statistical_annotation_example.py` | 在箱线图上自动进行多组成对统计检验（如 t-test），并智能堆叠显著性标记。 | `add_box()`, `add_pairwise_tests()` |
+| **美学与处理**<br/> `Styles_Aesthetics/aesthetic_and_processing_example.py` | 对数据进行平滑处理或根据条件高亮特定数据点。 | `utils.moving_average()`, `add_conditional_scatter()` |
+| **统计图组合**<br/> `Features_Customization/statistical_plots_example.py` | 演示如何组合小提琴图和蜂群图，以及在箱线图上添加统计检验。 | `add_violin()`, `add_swarm()`, `add_box()`, `add_stat_test()` |
 
 ### 领域专用图 (Domain-Specific Plots)
 
 | 示例 | 描述 | 关键功能 |
 | :--- | :--- | :--- |
 | **领域专用图合集**<br/> `Domain_Specific_Plots/domain_specific_plots_example.py` | 一站式展示多种领域专用图，包括 SERS 光谱图、混淆矩阵、ROC 曲线和 PCA 散点图。 | `add_spectra()`, `add_confusion_matrix()`, `add_roc_curve()`, `add_pca_scatter()` |
-| **学习曲线**<br/> `Domain_Specific_Plots/learning_curve_example.py` | 绘制机器学习模型的学习曲线，帮助诊断过拟合或欠拟合问题。 | `utils.plot_learning_curve()` |
+| **3D 绘图**<br/> `Domain_Specific_Plots/3d_plots_example.py` | 展示如何创建 3D 线图和表面图。 | `ax_configs={'...': {'projection': '3d'}}`, `add_line3d()`, `add_surface()` |
+| **学习曲线**<br/> `Domain_Specific_Plots/learning_curve_example.py` | 绘制机器学习模型的学习曲线，帮助诊断过拟合或欠拟合问题。 | `add_learning_curve()` |
 | **SERS 浓度图**<br/> `Domain_Specific_Plots/concentration_map_example.py` | 绘制 SERS Mapping 浓度图，本质上是带有专业美化的热图。 | `add_concentration_map()` |
 | **电力系统时间序列**<br/> `Domain_Specific_Plots/power_timeseries_example.py` | 绘制电力系统动态仿真结果，并自动标记故障、切除等事件。 | `add_power_timeseries()` |
 | **相量图**<br/> `Domain_Specific_Plots/phasor_diagram_example.py` | 在极坐标上绘制电气工程中的相量图。 | `add_phasor_diagram()` |
-| **分岔图**<br/> `Domain_Specific_Plots/bifurcation_diagram_example.py` | 绘制常用于非线性系统和稳定性分析的分岔图。 | `add_scatter(rasterized=True)` |
+| **分岔图**<br/> `Domain_Specific_Plots/bifurcation_diagram_example.py` | 绘制常用于非线性系统和稳定性分析的分岔图。 | `add_bifurcation_diagram()` |
 
 ### 数据分析工具 (Data Analysis Utils)
 
 | 示例 | 描述 | 关键功能 |
 | :--- | :--- | :--- |
-| **数据分析工具集**<br/> `Data_Analysis_Utils/data_analysis_utils_example.py` | 演示如何对数据进行分布拟合 (`fit_and_plot_distribution`) 和数据分箱 (`bin_data`)。 | `utils.fit_and_plot_distribution()`, `utils.bin_data()` |
-| **通用工具函数**<br/> `Data_Analysis_Utils/utility_functions_example.py` | 展示更多通用的 `utils` 函数，如在高光谱上高亮特征峰 (`highlight_peaks`) 和在时间序列上标记事件 (`add_event_markers`)。 | `utils.highlight_peaks()`, `utils.add_event_markers()` |
+| **数据分析工具集**<br/> `Data_Analysis_Utils/data_analysis_utils_example.py` | 演示如何对数据进行分布拟合和数据分箱绘图。 | `add_distribution_fit()`, `add_binned_plot()` |
 
 ---
 

paperplotter-0.1.6/examples/Data_Analysis_Utils/data_analysis_utils_example.py

@@ -0,0 +1,60 @@
+# examples/data_analysis_utils_example.py
+
+import paperplot as pp
+import pandas as pd
+import numpy as np
+import matplotlib.pyplot as plt
+
+print(f"--- Running Example: {__file__} ---")
+
+# --- 1. 准备数据 ---
+# 分布拟合示例数据
+np.random.seed(42)
+normal_data = np.random.normal(loc=0, scale=1, size=1000)
+df_dist = pd.DataFrame({'value': normal_data})
+
+# 数据分箱示例数据
+x_bin = np.linspace(0, 10, 200)
+y_bin = 2 * x_bin + np.random.normal(loc=0, scale=2, size=200)
+df_bin = pd.DataFrame({'x': x_bin, 'y': y_bin})
+
+
+# --- 2. 创建绘图 ---
+try:
+    # 使用新的 API 进行绘图和修饰
+    (
+        pp.Plotter(layout=(1, 2), figsize=(12, 5))
+        .set_suptitle("Data Analysis Utilities (New API)", fontsize=16, weight='bold')
+
+        # --- 左图: 分布拟合 ---
+        .add_hist(data=df_dist, x='value', tag='dist', bins=30, density=True, alpha=0.6, color='skyblue', label='Data Histogram')
+        .add_distribution_fit(data=df_dist, x='value', dist_name='norm', color='red', linestyle='--', lw=2, tag='dist')
+        .set_title("add_distribution_fit() Example", tag='dist')
+        .set_xlabel("Value", tag='dist')
+        .set_ylabel("Density", tag='dist')
+        .set_legend(tag='dist')
+
+        # --- 右图: 数据分箱 ---
+        .add_scatter(data=df_bin, x='x', y='y', tag='bin', alpha=0.3, label='Raw Data')
+        .add_binned_plot(data=df_bin, x='x', y='y', bins=5, plot_type='errorbar',
+                         color='green', fmt='-o', capsize=5, label='Binned Data (Mean ± Std)', tag='bin')
+        .set_title("add_binned_plot() Example", tag='bin')
+        .set_xlabel("X Value", tag='bin')
+        .set_ylabel("Y Value", tag='bin')
+        .set_legend(tag='bin')
+
+        # --- 清理和保存 ---
+        .cleanup()
+        .save("data_analysis_utils_example.png")
+    )
+
+except Exception as e:
+    print(f"An unexpected error occurred: {e}")
+    # 在调试时，取消下面的注释可以打印更详细的错误信息
+    # import traceback
+    # traceback.print_exc()
+finally:
+    plt.close('all')
+
+print(f"\n--- Finished Example: {__file__} ---")
+print("A new file 'data_analysis_utils_example.png' was generated with the new API.")

paperplotter-0.1.6/examples/Data_Analysis_Utils/utility_functions_example.py

@@ -0,0 +1,74 @@
+# examples/utility_functions_example.py
+
+import paperplot as pp
+import pandas as pd
+import numpy as np
+import matplotlib.pyplot as plt
+
+print(f"--- Running Example: {__file__} ---")
+
+# --- 1. 准备数据 ---
+
+# SERS 光谱数据
+x_spec = np.linspace(400, 1800, 1000)
+y_spec = (0.8 * np.exp(-((x_spec - 600)**2) / (2 * 30**2)) + 
+          0.6 * np.exp(-((x_spec - 1200)**2) / (2 * 50**2)) +
+          np.random.rand(1000) * 0.1)
+spectra_df = pd.DataFrame({'wavenumber': x_spec, 'intensity': y_spec})
+peaks_to_highlight = [600, 1200]
+
+
+# 时间序列数据
+time = np.linspace(0, 100, 200)
+signal = np.sin(time / 10) * np.exp(time / 50) + np.random.randn(200) * 0.1
+timeseries_df = pd.DataFrame({'time': time, 'signal': signal})
+event_points = [25, 50, 80]
+event_labels = ['Fault', 'Clear', 'Load Shed']
+
+
+# --- 2. 创建一个 1x2 的布局并使用新API绘图 ---
+try:
+    (
+        pp.Plotter(layout=(1, 2), figsize=(12, 5))
+        .set_suptitle("Utility Functions Demonstration (New API)", fontsize=16, weight='bold')
+
+        # --- 左侧子图: 高亮光谱峰 ---
+        .add_line(data=spectra_df, x='wavenumber', y='intensity', tag='spectra')
+        .add_peak_highlights(
+            peaks_x=peaks_to_highlight,
+            x_col='wavenumber',
+            y_col='intensity',
+            label_positions={1200: (1250, 0.4)}, # 手动将1200峰的标签移动到右下方
+            ha='center' # 水平居中
+        )
+        .set_title('add_peak_highlights() Example')
+        .set_xlabel('Wavenumber (cm⁻¹)')
+        .set_ylabel('Intensity (a.u.)')
+
+        # --- 右侧子图: 标记时间序列事件 ---
+        .add_line(data=timeseries_df, x='time', y='signal', tag='timeseries', color='navy')
+        .add_event_markers(
+            event_dates=event_points,
+            labels=event_labels,
+            label_positions={25: (15, 2.5)} # 手动移动 'Fault' 标签
+        )
+        .set_title('add_event_markers() Example')
+        .set_xlabel('Time (s)')
+        .set_ylabel('Signal Value')
+
+        # --- 清理和保存 ---
+        .cleanup(align_labels=True)
+        .save("utility_functions_example.png")
+    )
+
+except (pp.PaperPlotError, ValueError) as e:
+    print(f"\nAn error occurred:\n{e}")
+except Exception as e:
+    print(f"An unexpected error occurred: {e}")
+    # import traceback
+    # traceback.print_exc()
+finally:
+    plt.close('all')
+
+print(f"\n--- Finished Example: {__file__} ---")
+print("A new file 'utility_functions_example.png' was generated with the new API.")

paperplotter-0.1.6/examples/Domain_Specific_Plots/3d_plots_example.py

@@ -0,0 +1,78 @@
+# examples/Domain_Specific_Plots/3d_plots_example.py
+
+import paperplot as pp
+import pandas as pd
+import numpy as np
+import matplotlib.pyplot as plt
+
+print(f"--- Running Example: {__file__} ---")
+
+# --- 1. 准备数据 ---
+
+# 3D散点图数据 (Lorenz Attractor)
+def lorenz(xyz, *, s=10, r=28, b=2.667):
+    x, y, z = xyz
+    dxdt = s * (y - x)
+    dydt = r * x - y - x * z
+    dzdt = x * y - b * z
+    return np.array([dxdt, dydt, dzdt])
+
+dt = 0.01
+num_steps = 10000
+xyzs = np.empty((num_steps + 1, 3))
+xyzs[0] = (0., 1., 1.05)
+for i in range(num_steps):
+    xyzs[i + 1] = xyzs[i] + lorenz(xyzs[i]) * dt
+df_lorenz = pd.DataFrame(xyzs, columns=['x', 'y', 'z'])
+
+# 3D表面图数据
+X = np.arange(-5, 5, 0.25)
+Y = np.arange(-5, 5, 0.25)
+X, Y = np.meshgrid(X, Y)
+R = np.sqrt(X**2 + Y**2)
+Z = np.sin(R)
+
+# --- 2. 创建绘图 ---
+try:
+    # 创建一个包含两个3D子图的布局
+    # 注意: 必须在 ax_configs 中指定 projection='3d'
+    (
+        pp.Plotter(
+            layout=(1, 2), 
+            figsize=(14, 6),
+            ax_configs={
+                'ax00': {'projection': '3d'},
+                'ax01': {'projection': '3d'}
+            }
+        )
+        .set_suptitle("3D Plotting Demonstration", fontsize=16, weight='bold')
+
+        # --- 左图: 3D线图 ---
+        .add_line3d(data=df_lorenz, x='x', y='y', z='z', tag='lorenz', alpha=0.7)
+        .set_title("3D Line Plot (Lorenz Attractor)")
+        .set_xlabel("X Axis")
+        .set_ylabel("Y Axis")
+        .set_zlabel("Z Axis")
+        .view_init(elev=20, azim=-60) # 设置观察角度
+
+        # --- 右图: 3D表面图 ---
+        .add_surface(X=X, Y=Y, Z=Z, tag='surface', cmap='viridis')
+        .set_title("3D Surface Plot")
+        .set_xlabel("X")
+        .set_ylabel("Y")
+        .set_zlabel("Z")
+        .view_init(elev=45, azim=45)
+
+        # --- 保存 ---
+        .save("3d_plots_example.png")
+    )
+
+except Exception as e:
+    print(f"An unexpected error occurred: {e}")
+    import traceback
+    traceback.print_exc()
+finally:
+    plt.close('all')
+
+print(f"\n--- Finished Example: {__file__} ---")
+print("A new file '3d_plots_example.png' was generated.")

{paperplotter-0.1.4 → paperplotter-0.1.6}/examples/Domain_Specific_Plots/bifurcation_diagram_example.py

@@ -35,31 +35,22 @@ df_bifurcation = pd.DataFrame({
 })
 
 
-# --- 2. 创建绘图 ---
+# --- 2. 创建绘图 (使用新API) ---
 try:
-    plotter = pp.Plotter(layout=(1, 1), figsize=(8, 6))
-    # 使用 plotter.add_scatter 直接绘图，并指定 tag=1
-    # 这会自动处理坐标轴的获取和标签的注册
-    plotter.add_scatter(
-        data=df_bifurcation,
-        x='r',
-        y='x',
-        tag=1,  # 显式指定 tag
-        s=0.001,
-        alpha=0.2,
-        marker='.',
-        rasterized=True  # 对于有大量数据点的图，设为True可以提高渲染性能
+    (
+        pp.Plotter(layout=(1, 1), figsize=(8, 6))
+        .add_bifurcation_diagram(
+            data=df_bifurcation,
+            x='r',
+            y='x',
+            s=0.001, # 调小点的大小以获得更好的视觉效果
+            alpha=0.2
+        )
+        .set_title('Bifurcation Diagram of the Logistic Map')
+        .set_xlabel('Parameter r')
+        .set_ylabel('State x')
+        .save("bifurcation_diagram_example.png")
     )
-    
-    # --- 3. 设置标题和标签 ---
-    # 现在 tag=1 已经被正确注册，可以安全使用
-    plotter.set_title(1, 'Bifurcation Diagram of the Logistic Map')
-    plotter.set_xlabel(1, 'Parameter r')
-    plotter.set_ylabel(1, 'State x')
-
-    # --- 4. 清理和保存 ---
-    plotter.cleanup()
-    plotter.save("bifurcation_diagram_example.png")
 
 except Exception as e:
     print(f"An unexpected error occurred: {e}")

{paperplotter-0.1.4 → paperplotter-0.1.6}/examples/Domain_Specific_Plots/concentration_map_example.py

@@ -28,15 +28,16 @@ df_concentration = pd.DataFrame(concentration, index=y_coords, columns=x_coords)
 try:
     plotter = pp.Plotter(layout=(1, 1), figsize=(7, 6))
     
-    # 使用新的 add_concentration_map 方法
-    plotter.add_concentration_map(
-        data=df_concentration,
-        tag='sers_map',
-        cbar_kws={'label': 'Concentration (a.u.)'} # 自定义颜色条标签
+    # 使用新的 add_concentration_map 方法，并链式调用 set_title
+    (
+        plotter.add_concentration_map(
+            data=df_concentration,
+            tag='sers_map',
+            cbar_kws={'label': 'Concentration (a.u.)'} # 自定义颜色条标签
+        )
+        .set_title('SERS Concentration Map Example')
     )
     
-    # --- 3. 设置标题和标签 ---
-    plotter.set_title('sers_map', 'SERS Concentration Map Example')
     # X, Y 轴标签已由 add_concentration_map 默认设置，但可以覆盖
     # plotter.set_xlabel('sers_map', 'Position X (µm)')
     # plotter.set_ylabel('sers_map', 'Position Y (µm)')