paperplotter 0.1.2__tar.gz → 0.1.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: paperplotter
-Version: 0.1.2
+Version: 0.1.4
 Summary: 一个为科研论文设计的声明式 Matplotlib 封装库，让复杂图表的创建变得简单直观。
 Author-email: VerNe <yuu_seeing@foxmail.com>
 License-Expression: MIT
@@ -35,8 +35,11 @@ Dynamic: license-file
 
 *   **🎨 声明式链式调用**: 像写句子一样构建你的图表，例如 `plotter.add_line(...).set_title(...).set_xlabel(...)`。
 *   **🏷️ 基于标签的控制**: 给每个子图一个独一无二的 `tag`，之后就可以随时通过 `tag` 对其进行任何修改，告别混乱的 `axes[i][j]` 索引。
-*   **🧩 强大的布局系统**: 无论是简单的 `(行, 列)` 网格，还是使用 `subplot_mosaic` 实现的跨行跨列复杂布局，都能轻松定义。
+*   **🧩 强大的布局系统**: 无论是简单的 `(行, 列)` 网格，还是使用 `mosaic` 实现的跨行跨列复杂布局，都能轻松定义。
+*   **🧱 声明式嵌套布局**: 通过一个字典即可一次性定义包含子网格的复杂层级布局，并使用 `'容器.子图'` 这样的直观路径进行引用，完美实现“图中图”。
+*   **📐 灵活的尺寸控制**: 除了传统的 `figsize`，还可以通过 `subplot_aspect` 指定子图单元格的宽高比，让 `PaperPlot` 自动计算最合适的画布尺寸。
 *   **✨ 内置科研主题**: 提供多种专业美观的内置样式，如 `publication`, `presentation` 等，一键切换图表风格。
+*   **🌐 全局图层级标注**: 提供了在整个画布（Figure）上添加文本、线条、方框和标签的 API，非常适合添加全局注释或高亮一组图表。
 *   **🔬 丰富的领域专用图表**: 内置了科研中常用的图表类型，如光谱图、混淆矩阵、ROC 曲线、学习曲线、分岔图、相量图等。
 *   **🔧 智能美化工具**: `cleanup()` 方法可以智能地共享坐标轴、对齐标签；`cleanup_heatmaps()` 可以为多个热图创建共享的颜色条。
 
@@ -66,10 +69,13 @@ df_scatter = pd.DataFrame({
 })
 
 # 2. 初始化 Plotter 并绘图
+# 对于简单布局，可以直接使用元组 (rows, cols)
 plotter = pp.Plotter(layout=(1, 2), figsize=(10, 4))
 
-# 3. 添加图表并使用 tag 标记
+# 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 设置标题和标签
@@ -94,7 +100,8 @@ plotter.save("quick_start_figure.png")
 
 | 示例 | 描述 | 关键功能 |
 | :--- | :--- | :--- |
-| **高级布局**<br/> `Layout/advanced_layout_example.py` | 展示如何使用列表定义一个跨列的复杂布局。 | `layout=[['A', 'B', 'B'], ...]`<br/>`get_ax_by_name()` |
+| **声明式嵌套布局**<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)` |
@@ -103,15 +110,22 @@ plotter.save("quick_start_figure.png")
 
 | 示例 | 描述 | 关键功能 |
 | :--- | :--- | :--- |
-| **多图网格**<br/> `Features_Customization/multi_plot_grid.py` | 在一个网格中混合绘制不同类型的图表（线图、柱状图、散点图、热图）。 | `add_line()`, `add_bar()`, `add_scatter()`, `add_heatmap()` |
+| **多图网格**<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()` |
 | **共享颜色条**<br/> `Features_Customization/heatmap_colorbar_example.py` | 为多个热图创建一个共享的、能反映全局数据范围的颜色条。 | `add_heatmap(cbar=False)`, `cleanup_heatmaps()` |
-| **智能清理**<br/> `Features_Customization/cleanup_demonstration.py` | 演示 `cleanup()` 函数如何动态地为指定行/列的子图共享 X/Y 轴，并自动隐藏多余的刻度标签。 | `cleanup(share_y_on_rows=...)`, `cleanup(share_x_on_cols=...)` |
+| **智能清理**<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/highlighting_example.py` | 展示如何在子图内部高亮特定的数据区域，并为整个图表添加边框。| `add_highlight_box()`, `fig_add_boundary_box()` |
+
 ### 风格与美化 (Styles & Aesthetics)
 
 | 示例 | 描述 | 关键功能 |
@@ -129,7 +143,7 @@ plotter.save("quick_start_figure.png")
 | **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` | 绘制常用于非线性系统和稳定性分析的分岔图。 | `utils.plot_bifurcation_diagram()` |
+| **分岔图**<br/> `Domain_Specific_Plots/bifurcation_diagram_example.py` | 绘制常用于非线性系统和稳定性分析的分岔图。 | `add_scatter(rasterized=True)` |
 
 ### 数据分析工具 (Data Analysis Utils)
 

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

@@ -11,8 +11,11 @@
 
 *   **🎨 声明式链式调用**: 像写句子一样构建你的图表，例如 `plotter.add_line(...).set_title(...).set_xlabel(...)`。
 *   **🏷️ 基于标签的控制**: 给每个子图一个独一无二的 `tag`，之后就可以随时通过 `tag` 对其进行任何修改，告别混乱的 `axes[i][j]` 索引。
-*   **🧩 强大的布局系统**: 无论是简单的 `(行, 列)` 网格，还是使用 `subplot_mosaic` 实现的跨行跨列复杂布局，都能轻松定义。
+*   **🧩 强大的布局系统**: 无论是简单的 `(行, 列)` 网格，还是使用 `mosaic` 实现的跨行跨列复杂布局，都能轻松定义。
+*   **🧱 声明式嵌套布局**: 通过一个字典即可一次性定义包含子网格的复杂层级布局，并使用 `'容器.子图'` 这样的直观路径进行引用，完美实现“图中图”。
+*   **📐 灵活的尺寸控制**: 除了传统的 `figsize`，还可以通过 `subplot_aspect` 指定子图单元格的宽高比，让 `PaperPlot` 自动计算最合适的画布尺寸。
 *   **✨ 内置科研主题**: 提供多种专业美观的内置样式，如 `publication`, `presentation` 等，一键切换图表风格。
+*   **🌐 全局图层级标注**: 提供了在整个画布（Figure）上添加文本、线条、方框和标签的 API，非常适合添加全局注释或高亮一组图表。
 *   **🔬 丰富的领域专用图表**: 内置了科研中常用的图表类型，如光谱图、混淆矩阵、ROC 曲线、学习曲线、分岔图、相量图等。
 *   **🔧 智能美化工具**: `cleanup()` 方法可以智能地共享坐标轴、对齐标签；`cleanup_heatmaps()` 可以为多个热图创建共享的颜色条。
 
@@ -42,10 +45,13 @@ df_scatter = pd.DataFrame({
 })
 
 # 2. 初始化 Plotter 并绘图
+# 对于简单布局，可以直接使用元组 (rows, cols)
 plotter = pp.Plotter(layout=(1, 2), figsize=(10, 4))
 
-# 3. 添加图表并使用 tag 标记
+# 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 设置标题和标签
@@ -70,7 +76,8 @@ plotter.save("quick_start_figure.png")
 
 | 示例 | 描述 | 关键功能 |
 | :--- | :--- | :--- |
-| **高级布局**<br/> `Layout/advanced_layout_example.py` | 展示如何使用列表定义一个跨列的复杂布局。 | `layout=[['A', 'B', 'B'], ...]`<br/>`get_ax_by_name()` |
+| **声明式嵌套布局**<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)` |
@@ -79,15 +86,22 @@ plotter.save("quick_start_figure.png")
 
 | 示例 | 描述 | 关键功能 |
 | :--- | :--- | :--- |
-| **多图网格**<br/> `Features_Customization/multi_plot_grid.py` | 在一个网格中混合绘制不同类型的图表（线图、柱状图、散点图、热图）。 | `add_line()`, `add_bar()`, `add_scatter()`, `add_heatmap()` |
+| **多图网格**<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()` |
 | **共享颜色条**<br/> `Features_Customization/heatmap_colorbar_example.py` | 为多个热图创建一个共享的、能反映全局数据范围的颜色条。 | `add_heatmap(cbar=False)`, `cleanup_heatmaps()` |
-| **智能清理**<br/> `Features_Customization/cleanup_demonstration.py` | 演示 `cleanup()` 函数如何动态地为指定行/列的子图共享 X/Y 轴，并自动隐藏多余的刻度标签。 | `cleanup(share_y_on_rows=...)`, `cleanup(share_x_on_cols=...)` |
+| **智能清理**<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/highlighting_example.py` | 展示如何在子图内部高亮特定的数据区域，并为整个图表添加边框。| `add_highlight_box()`, `fig_add_boundary_box()` |
+
 ### 风格与美化 (Styles & Aesthetics)
 
 | 示例 | 描述 | 关键功能 |
@@ -105,7 +119,7 @@ plotter.save("quick_start_figure.png")
 | **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` | 绘制常用于非线性系统和稳定性分析的分岔图。 | `utils.plot_bifurcation_diagram()` |
+| **分岔图**<br/> `Domain_Specific_Plots/bifurcation_diagram_example.py` | 绘制常用于非线性系统和稳定性分析的分岔图。 | `add_scatter(rasterized=True)` |
 
 ### 数据分析工具 (Data Analysis Utils)
 

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

@@ -38,18 +38,21 @@ df_bifurcation = pd.DataFrame({
 # --- 2. 创建绘图 ---
 try:
     plotter = pp.Plotter(layout=(1, 1), figsize=(8, 6))
-    ax = plotter.get_ax(1) # 获取第一个ax
-
-    # 使用新的 plot_bifurcation_diagram 函数
-    pp.utils.plot_bifurcation_diagram(
-        ax=ax,
+    # 使用 plotter.add_scatter 直接绘图，并指定 tag=1
+    # 这会自动处理坐标轴的获取和标签的注册
+    plotter.add_scatter(
         data=df_bifurcation,
         x='r',
-        y='x'
+        y='x',
+        tag=1,  # 显式指定 tag
+        s=0.001,
+        alpha=0.2,
+        marker='.',
+        rasterized=True  # 对于有大量数据点的图，设为True可以提高渲染性能
     )
     
     # --- 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')

{paperplotter-0.1.2 → paperplotter-0.1.4}/examples/Domain_Specific_Plots/phasor_diagram_example.py

@@ -17,19 +17,23 @@ labels = ['V_ref', 'I_load', 'V_bus']
 try:
     # 初始化Plotter，创建一个普通的笛卡尔轴
     # add_phasor_diagram 会自动将其转换为极坐标
-    plotter = pp.Plotter(layout=(1, 1), figsize=(8, 8))
+    plotter = pp.Plotter(
+        layout=(1, 1), 
+        figsize=(8, 8),
+        ax_configs={'ax00': {'projection': 'polar'}} # 明确指定ax00为极坐标轴
+    )
     
     # 添加相量图
     plotter.add_phasor_diagram(
         magnitudes=[1.0, 0.8, 1.2],
         angles=[0, 90, -45],
         labels=['V_ref', 'I_load', 'V_bus'],
-        tag='phasor_ax',
+        tag='ax00', # 使用布局中定义的tag
         angle_unit='degrees'
     )
     
     # 获取极坐标轴并设置标题
-    ax = plotter.get_ax('phasor_ax')
+    ax = plotter.get_ax('ax00')
     ax.set_title('Phasor Diagram Example', va='bottom')
 
     # --- 3. 清理和保存 ---

{paperplotter-0.1.2 → paperplotter-0.1.4}/examples/Features_Customization/cleanup_demonstration.py

@@ -5,6 +5,8 @@ import pandas as pd
 import numpy as np
 import matplotlib.pyplot as plt
 
+from paperplot import Plotter
+
 print(f"--- Running Example: {__file__} ---")
 
 # --- 1. 准备一组适合共享坐标轴的数据 ---
@@ -24,7 +26,7 @@ df4 = generate_data(offset=1)
 # 目的是为了后续演示 cleanup 函数如何动态地创建共享关系
 try:
     print("Creating a 2x2 plot with INDEPENDENT axes...")
-    plotter = pp.Plotter(n_rows=2, n_cols=2, figsize=(10, 8), sharex=False, sharey=False)
+    plotter = Plotter(layout=(2, 2), figsize=(10, 8), style='flat')
 
     # --- 3. 填充图表 ---
     plotter.add_line(data=df1, x='time', y='signal', tag='cond1')
@@ -44,7 +46,7 @@ try:
     # 我们指令cleanup函数：
     # - 对第0行和第1行的Y轴进行共享和清理
     # - 对第0列和第1列的X轴进行共享和清理
-    plotter.cleanup(share_y_on_rows=[0, 1], share_x_on_cols=[0, 1])
+    plotter.cleanup(auto_share=True)
 
     # --- 6. 保存图像 ---
     plotter.save("cleanup_demonstration_figure.png")

{paperplotter-0.1.2 → paperplotter-0.1.4}/examples/Features_Customization/composite_figure_example.py

@@ -51,7 +51,7 @@ try:
     print("Adding an inset image to the 'SERS_Spectra' plot...")
     plotter.add_inset_image(
         host_tag='spectra_A', 
-        image_path='./resources/placeholder_image.png',
+        image_path='./examples/Features_Customization/resources/placeholder_image.png',
         rect=[0.7, 0.65, 0.28, 0.28] # [x, y, width, height] in relative coordinates
     )
 

paperplotter-0.1.4/examples/Features_Customization/fig_annotation_example.py

@@ -0,0 +1,72 @@
+# examples/Features_Customization/fig_annotation_example.py
+
+import paperplot as pp
+import pandas as pd
+import numpy as np
+import matplotlib.pyplot as plt
+
+print(f"--- Running Example: {__file__} ---")
+
+try:
+    # 1. Create a Plotter instance with a 2x2 layout
+    plotter = pp.Plotter(layout=(2, 2), figsize=(12, 10), style='publication')
+
+    # 2. Add some plots to the subplots
+    df = pd.DataFrame({
+        'x': np.linspace(0, 10, 50),
+        'y1': np.sin(np.linspace(0, 10, 50)),
+        'y2': np.cos(np.linspace(0, 10, 50)),
+        'y3': np.random.rand(50) * 5
+    })
+
+    plotter.add_line(data=df, x='x', y='y1', tag='ax00', label='Sine')
+    plotter.set_title('ax00', 'Top-Left Plot')
+    plotter.set_legend('ax00')
+
+    plotter.add_scatter(data=df, x='x', y='y2', tag='ax01', label='Cosine', marker='o')
+    plotter.set_title('ax01', 'Top-Right Plot')
+    plotter.set_legend('ax01')
+
+    plotter.add_hist(data=df, x='y3', tag='ax10', bins=10, color='skyblue')
+    plotter.set_title('ax10', 'Bottom-Left Plot')
+
+    plotter.add_bar(data=pd.DataFrame({'cat': ['A', 'B', 'C'], 'val': [1, 3, 2]}), x='cat', y='val', tag='ax11')
+    plotter.set_title('ax11', 'Bottom-Right Plot')
+
+    # Apply cleanup for shared axes
+    plotter.cleanup(auto_share=True)
+
+    # 3. Use the new global figure-level annotation APIs
+
+    # fig_add_text
+    plotter.fig_add_text(0.5, 0.96, 'Comprehensive Figure Analysis', ha='center', va='top', fontsize=16, weight='bold', color='darkblue')
+    plotter.fig_add_text(0.02, 0.02, 'Generated by PaperPlot', ha='left', va='bottom', fontsize=8, style='italic')
+
+    # fig_add_line - draw a line across the figure
+    plotter.fig_add_line([0.1, 0.9], [0.5, 0.5], color='red', linestyle=':', linewidth=2)
+    plotter.fig_add_text(0.5, 0.51, 'Mid-Figure Separator', ha='center', va='bottom', color='red', fontsize=10)
+
+    # fig_add_box - box around top row plots
+    plotter.fig_add_box(tags=['ax00', 'ax01'], padding=0.01, edgecolor='green', linewidth=2, linestyle='-')
+    plotter.fig_add_label(tags=['ax00', 'ax01'], text='Top Row Insights', position='top_center', padding=0.02, fontsize=12, color='green')
+
+    # fig_add_box - box around bottom-left plot
+    plotter.fig_add_box(tags='ax10', padding=0.005, edgecolor='purple', linewidth=1, linestyle='-.')
+    plotter.fig_add_label(tags='ax10', text='Distribution', position='bottom_right', padding=0.01, fontsize=10, color='purple')
+
+    # fig_add_label - label for the entire figure (relative to all axes)
+    plotter.fig_add_label(tags=['ax00', 'ax01', 'ax10', 'ax11'], text='Overall Study Results', position='right_center', padding=0.05, rotation=-90, fontsize=14, color='gray')
+
+
+    # 4. Save the figure
+    plotter.save("fig_annotation_example.png")
+
+except pp.PaperPlotError as e:
+    print(f"\nA PaperPlot error occurred:\n{e}")
+except Exception as e:
+    print(f"An unexpected error occurred: {e}")
+finally:
+    plt.close('all')
+
+print(f"--- Finished Example: {__file__} ---")
+print("A new file 'fig_annotation_example.png' was generated.")

paperplotter-0.1.4/examples/Features_Customization/fig_text_example.py

@@ -0,0 +1,51 @@
+# examples/Features_Customization/fig_text_example.py
+
+import paperplot as pp
+import pandas as pd
+import numpy as np
+import matplotlib.pyplot as plt
+
+print(f"--- Running Example: {__file__} ---")
+
+try:
+    # 1. Create a Plotter instance with a 1x2 layout
+    plotter = pp.Plotter(layout=(1, 2), figsize=(10, 5), style='publication')
+
+    # 2. Add some plots to the subplots
+    df = pd.DataFrame({
+        'x': np.linspace(0, 10, 100),
+        'y1': np.sin(np.linspace(0, 10, 100)),
+        'y2': np.cos(np.linspace(0, 10, 100))
+    })
+
+    plotter.add_line(data=df, x='x', y='y1', tag='ax00', label='Sine Wave')
+    plotter.set_title('ax00', 'Left Subplot')
+    plotter.set_xlabel('ax00', 'X-axis')
+    plotter.set_ylabel('ax00', 'Y-axis')
+    plotter.set_legend('ax00')
+
+    plotter.add_scatter(data=df, x='x', y='y2', tag='ax01', label='Cosine Points', marker='o', s=20)
+    plotter.set_title('ax01', 'Right Subplot')
+    plotter.set_xlabel('ax01', 'X-axis')
+    plotter.set_ylabel('ax01', 'Y-axis')
+    plotter.set_legend('ax01')
+
+    # 3. Add figure-level text using fig_text
+    plotter.fig_add_text(0.5, 0.96, 'Overall Figure Title (using fig_add_text)', ha='center', va='top', fontsize=14, weight='bold')
+    plotter.fig_add_text(0.02, 0.5, 'Left Side Annotation', rotation=90, va='center', ha='left', fontsize=10, color='gray')
+    plotter.fig_add_text(0.98, 0.5, 'Right Side Annotation', rotation=-90, va='center', ha='right', fontsize=10, color='gray')
+    plotter.fig_add_text(0.5, 0.02, 'Figure Footer - Source: Example Data', ha='center', va='bottom', fontsize=8, style='italic')
+
+    # 4. Apply cleanup and save the figure
+    plotter.cleanup(auto_share=True) # Auto-share for demonstration
+    plotter.save("fig_text_example.png")
+
+except pp.PaperPlotError as e:
+    print(f"\nA PaperPlot error occurred:\n{e}")
+except Exception as e:
+    print(f"An unexpected error occurred: {e}")
+finally:
+    plt.close('all')
+
+print(f"--- Finished Example: {__file__} ---")
+print("A new file 'fig_text_example.png' was generated.")

{paperplotter-0.1.2 → paperplotter-0.1.4}/examples/Features_Customization/heatmap_colorbar_example.py

@@ -18,7 +18,7 @@ df3 = generate_heatmap_data(-5, 5)
 # --- 2. 演示共享颜色条功能 ---
 try:
     print("Creating 3 heatmaps with a shared colorbar...")
-    plotter = pp.Plotter(n_rows=1, n_cols=3, figsize=(12, 4))
+    plotter = pp.Plotter(layout=(1, 3), figsize=(12, 4))
 
     # --- 3. 添加热图，并明确指定 cbar=False ---
     # 这是关键一步：我们告诉plotter不要为每个热图单独创建颜色条
@@ -52,7 +52,7 @@ finally:
 # --- 7. 作为对比，创建一个带独立颜色条的热图 ---
 try:
     print("\nCreating a single heatmap with its own colorbar (default behavior)...")
-    plotter_single = pp.Plotter(n_rows=1, n_cols=1)
+    plotter_single = pp.Plotter(layout=(1, 1))
     # 默认调用，不加 cbar 参数，会自动创建颜色条
     plotter_single.add_heatmap(data=df1, tag='single')
     plotter_single.set_title('single', 'Default Behavior with cbar=True')

paperplotter-0.1.4/examples/Features_Customization/highlighting_example.py

@@ -0,0 +1,62 @@
+# examples/Features_Customization/highlighting_example.py
+
+import paperplot as pp
+import pandas as pd
+import numpy as np
+import matplotlib.pyplot as plt
+
+print(f"--- Running Example: {__file__} ---")
+
+try:
+    # 1. Create a Plotter instance
+    plotter = pp.Plotter(layout=(1, 1), figsize=(8, 6), style='publication')
+
+    # 2. Add a plot with some interesting features
+    x = np.linspace(0, 2 * np.pi, 200)
+    y = np.sin(x) * np.exp(-x / 4)
+    df = pd.DataFrame({'x': x, 'y': y})
+
+    plotter.add_line(data=df, x='x', y='y', tag='main_plot', label='Damped Sine Wave')
+    plotter.set_title('main_plot', 'Highlighting Data Regions and Figure Boundary')
+    plotter.set_xlabel('main_plot', 'Time')
+    plotter.set_ylabel('main_plot', 'Amplitude')
+    plotter.set_legend('main_plot')
+
+    # 3. Use add_highlight_box to highlight a specific data region
+    # Highlight the first peak of the wave
+    plotter.add_highlight_box(
+        tag='main_plot',
+        x_range=(0.5, 2.5),
+        y_range=(0.4, 0.8),
+        facecolor='orange',
+        alpha=0.3,
+        label='First Peak Region' # Note: label won't show by default, but can be used with legends
+    )
+    plotter.add_text('main_plot', 1.5, 0.6, 'First Peak', ha='center', va='center', fontsize=10)
+
+    # Highlight the region where the wave decays
+    plotter.add_highlight_box(
+        tag='main_plot',
+        x_range=(4, 6),
+        y_range=(-0.2, 0.2),
+        facecolor='lightblue',
+        alpha=0.4
+    )
+    plotter.add_text('main_plot', 5, 0, 'Decay Region', ha='center', va='center', fontsize=10)
+
+    # 4. Use fig_add_boundary_box to draw a border around the axes area
+
+    # plotter.fig_add_text(0.5, 0.98, 'Figure with Smart Boundary Box', ha='center', va='top', fontsize=12)
+    plotter.fig_add_boundary_box(padding=0.08, edgecolor='darkgray', linewidth=2)
+    # 5. Save the figure
+    plotter.save("highlighting_example.png")
+
+except pp.PaperPlotError as e:
+    print(f"\nA PaperPlot error occurred:\n{e}")
+except Exception as e:
+    print(f"An unexpected error occurred: {e}")
+finally:
+    plt.close('all')
+
+print(f"--- Finished Example: {__file__} ---")
+print("A new file 'highlighting_example.png' was generated.")

{paperplotter-0.1.2 → paperplotter-0.1.4}/examples/Features_Customization/multi_plot_grid.py

@@ -5,6 +5,8 @@ import pandas as pd
 import numpy as np
 import matplotlib.pyplot as plt
 
+from paperplot import Plotter
+
 print(f"--- Running Example: {__file__} ---")
 
 # --- 1. 准备多样化的数据 ---
@@ -36,7 +38,7 @@ df_heatmap = pd.DataFrame(heatmap_data, columns=[f'col_{i}' for i in range(10)])
 try:
     print("Creating a 2x2 plot with shared axes...")
     # sharex=True, sharey=True 是关键
-    plotter = pp.Plotter(n_rows=2, n_cols=2, figsize=(10, 8), sharex=False, sharey=False)
+    plotter = Plotter(layout=(2, 2), figsize=(10, 8), style='flat')
 
     # --- 3. 在网格中填充不同的图表 ---
     print("Populating the grid with different plot types...")
@@ -74,6 +76,8 @@ try:
     plotter.tick_params('heatmap', axis='x', rotation=90)
 
     # --- 5. 应用默认美化并保存 ---
+    # print("Applying cleanup for shared axes and saving...")
+    # plotter.cleanup(auto_share=True)
     plotter.save("multi_plot_grid_figure.png")
 
 except pp.PaperPlotError as e:

{paperplotter-0.1.2 → paperplotter-0.1.4}/examples/Layout/advanced_layout_example.py

@@ -54,7 +54,7 @@ try:
     # --- 6. 演示 hide_axes() 功能 ---
     # 为了让布局更紧凑，我们隐藏所有X轴
     print("Hiding all X-axes using hide_axes(x=True)...")
-    plotter.hide_axes(x=True)
+    plotter.hide_axes(x=True, y=True)
 
     # --- 7. 保存图像 ---
     plotter.save("advanced_layout_figure.png")

paperplotter-0.1.4/examples/Layout/declarative_nested_layout_example.py

@@ -0,0 +1,91 @@
+# examples/Layout/declarative_nested_layout_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. 准备数据 ---
+# 主图数据
+df_line = pd.DataFrame({
+    'x': np.linspace(0, 2 * np.pi, 100),
+    'y': np.sin(np.linspace(0, 2 * np.pi, 100))
+})
+# 子网格的热图数据
+heatmap_data_1 = pd.DataFrame(np.random.rand(8, 50))
+heatmap_data_2 = pd.DataFrame(np.random.rand(8, 50))
+heatmap_data_3 = pd.DataFrame(np.random.rand(8, 50))
+# Y轴标签
+y_labels = ['~NH₂', 'v(C-N-C)', 'v(C-C)ring']
+all_heatmap_data = [heatmap_data_1, heatmap_data_2, heatmap_data_3]
+
+try:
+    # --- 2. 使用字典声明式地定义整个嵌套布局 ---
+    # 这是新API的核心：一个字典描述了所有层级和结构
+    nested_layout = {
+        # 'main' 定义了顶层 1x2 布局
+        'main': [
+            ['main_plot', 'heatmap_group']
+        ],
+        # 'subgrids' 定义了 'heatmap_group' 区域如何被再次划分
+        'subgrids': {
+            'heatmap_group': {
+                # 'layout' 定义了 3x1 的内部网格，并为每个单元命名
+                'layout': [
+                    ['nh2_map'],
+                    ['cnc_map'],
+                    ['ring_map']
+                ],
+                # 'hspace' 控制这个子网格内部的垂直间距，使其紧凑
+                'hspace': 0.05
+            }
+        }
+    }
+
+    # --- 3. 初始化 Plotter ---
+    # 直接将定义好的字典传给 layout 参数
+    # layout_engine=None 确保我们可以手动控制间距
+    plotter = pp.Plotter(layout=nested_layout, figsize=(12, 6), layout_engine=None)
+    plotter.set_suptitle("Declarative Nested Layout Example", fontsize=16, weight='bold')
+
+    # --- 4. 填充主图区域 ---
+    # 直接使用顶层布局中定义的名字 'main_plot' 作为 tag
+    plotter.add_line(data=df_line, x='x', y='y', tag='main_plot')
+    plotter.set_title('main_plot', 'Standard Plot')
+    plotter.set_xlabel('main_plot', 'X-axis')
+    plotter.set_ylabel('main_plot', 'Y-axis')
+
+    # --- 5. 填充子网格区域 ---
+    # 使用 '容器名.子图名' 的层级结构来直接引用嵌套的子图
+    subgrid_names = ['nh2_map', 'cnc_map', 'ring_map']
+    for i, sub_name in enumerate(subgrid_names):
+        # 构造层级 tag, e.g., 'heatmap_group.nh2_map'
+        hierarchical_tag = f"heatmap_group.{sub_name}"
+
+        plotter.add_heatmap(data=all_heatmap_data[i], tag=hierarchical_tag)
+        plotter.set_ylabel(hierarchical_tag, y_labels[i], fontsize=14, weight='bold')
+
+    # --- 6. 对子网格进行精细化设置 ---
+    # a. 只在最顶部的子图上添加标题
+    plotter.set_title('heatmap_group.nh2_map', 'Nested Heatmap Group', fontsize=14)
+
+    # b. 隐藏不需要的 X 轴刻度标签，实现共享X轴的效果
+    #    (这里我们假设您已经实现了更精细的 hide_axes 或 tick_params)
+    plotter.tick_params('heatmap_group.nh2_map', axis='x', labelbottom=False)
+    plotter.tick_params('heatmap_group.cnc_map', axis='x', labelbottom=False)
+
+    # c. 只在最底部的子图上添加 X 轴标签
+    plotter.set_xlabel('heatmap_group.ring_map', 'Time (min)', fontsize=14, weight='bold')
+
+    # --- 7. 保存图像 ---
+    plotter.save("declarative_nested_layout.png")
+
+except (pp.PaperPlotError, ValueError, KeyError) as e:
+    print(f"\nAn error occurred:\n{e}")
+finally:
+    plt.close('all')
+
+print(f"\n--- Finished Example: {__file__} ---")
+print("A new file 'declarative_nested_layout.png' was generated.")