paperplotter 0.1.3__tar.gz → 0.1.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: paperplotter
-Version: 0.1.3
+Version: 0.1.4
 Summary: 一个为科研论文设计的声明式 Matplotlib 封装库，让复杂图表的创建变得简单直观。
 Author-email: VerNe <yuu_seeing@foxmail.com>
 License-Expression: MIT
@@ -36,6 +36,7 @@ Dynamic: license-file
 *   **🎨 声明式链式调用**: 像写句子一样构建你的图表，例如 `plotter.add_line(...).set_title(...).set_xlabel(...)`。
 *   **🏷️ 基于标签的控制**: 给每个子图一个独一无二的 `tag`，之后就可以随时通过 `tag` 对其进行任何修改，告别混乱的 `axes[i][j]` 索引。
 *   **🧩 强大的布局系统**: 无论是简单的 `(行, 列)` 网格，还是使用 `mosaic` 实现的跨行跨列复杂布局，都能轻松定义。
+*   **🧱 声明式嵌套布局**: 通过一个字典即可一次性定义包含子网格的复杂层级布局，并使用 `'容器.子图'` 这样的直观路径进行引用，完美实现“图中图”。
 *   **📐 灵活的尺寸控制**: 除了传统的 `figsize`，还可以通过 `subplot_aspect` 指定子图单元格的宽高比，让 `PaperPlot` 自动计算最合适的画布尺寸。
 *   **✨ 内置科研主题**: 提供多种专业美观的内置样式，如 `publication`, `presentation` 等，一键切换图表风格。
 *   **🌐 全局图层级标注**: 提供了在整个画布（Figure）上添加文本、线条、方框和标签的 API，非常适合添加全局注释或高亮一组图表。
@@ -68,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 设置标题和标签
@@ -96,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)` |
@@ -105,7 +110,7 @@ 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()` |

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

@@ -12,6 +12,7 @@
 *   **🎨 声明式链式调用**: 像写句子一样构建你的图表，例如 `plotter.add_line(...).set_title(...).set_xlabel(...)`。
 *   **🏷️ 基于标签的控制**: 给每个子图一个独一无二的 `tag`，之后就可以随时通过 `tag` 对其进行任何修改，告别混乱的 `axes[i][j]` 索引。
 *   **🧩 强大的布局系统**: 无论是简单的 `(行, 列)` 网格，还是使用 `mosaic` 实现的跨行跨列复杂布局，都能轻松定义。
+*   **🧱 声明式嵌套布局**: 通过一个字典即可一次性定义包含子网格的复杂层级布局，并使用 `'容器.子图'` 这样的直观路径进行引用，完美实现“图中图”。
 *   **📐 灵活的尺寸控制**: 除了传统的 `figsize`，还可以通过 `subplot_aspect` 指定子图单元格的宽高比，让 `PaperPlot` 自动计算最合适的画布尺寸。
 *   **✨ 内置科研主题**: 提供多种专业美观的内置样式，如 `publication`, `presentation` 等，一键切换图表风格。
 *   **🌐 全局图层级标注**: 提供了在整个画布（Figure）上添加文本、线条、方框和标签的 API，非常适合添加全局注释或高亮一组图表。
@@ -44,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 设置标题和标签
@@ -72,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)` |
@@ -81,7 +86,7 @@ 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()` |
@@ -131,4 +136,4 @@ plotter.save("quick_start_figure.png")
 
 ## 许可证
 
-本项目采用 [MIT License](LICENSE)授权。
+本项目采用 [MIT License](LICENSE)授权。

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.")

{paperplotter-0.1.3 → paperplotter-0.1.4}/paperplot/core.py

@@ -1,4 +1,7 @@
 import logging
+
+from matplotlib.gridspec import GridSpecFromSubplotSpec
+
 logger = logging.getLogger(__name__)
 from typing import Optional, Union, List, Tuple, Callable, Dict
 import matplotlib.pyplot as plt
@@ -91,7 +94,9 @@ class Plotter(GenericPlotsMixin, ModifiersMixin, DomainSpecificPlotsMixin):
         self.axes_dict: Dict[Union[str, int], plt.Axes] = {}
         self.axes: List[plt.Axes] = []
 
-        if isinstance(layout, tuple) and len(layout) == 2:
+        if isinstance(layout, dict):
+            self._create_nested_layout(layout)
+        elif isinstance(layout, tuple) and len(layout) == 2:
             n_rows, n_cols = layout
             for r in range(n_rows):
                 for c in range(n_cols):
@@ -114,11 +119,58 @@ class Plotter(GenericPlotsMixin, ModifiersMixin, DomainSpecificPlotsMixin):
         else:
             raise ValueError("Invalid layout format. Must be (rows, cols) tuple or list of lists for mosaic.")
 
-        self.tag_to_ax: Dict[Union[str, int], plt.Axes] = {} # This will store user-assigned tags to actual axes
+        # self.tag_to_ax: Dict[Union[str, int], plt.Axes] = {} # This will store user-assigned tags to actual axes
+        self.tag_to_ax = self.axes_dict.copy()
+
         self.tag_to_mappable: Dict[Union[str, int], plt.cm.ScalarMappable] = {}
         self.current_ax_index: int = 0
         self.next_default_tag: int = 1
 
+    def _create_nested_layout(self, layout_def: Dict):
+        """
+        [私有] 根据声明式定义，递归创建嵌套布局。
+        """
+        main_layout_list = layout_def['main']
+        subgrids_def = layout_def.get('subgrids', {})
+
+        # 1. 创建主网格
+        parsed_main_layout, (n_rows, n_cols) = utils.parse_mosaic_layout(main_layout_list)
+        main_gs = self.fig.add_gridspec(n_rows, n_cols)
+
+        # 2. 遍历主网格中的所有命名区域
+        for name, spec in parsed_main_layout.items():
+
+            # 检查这个区域是否需要被进一步划分为子网格
+            if name in subgrids_def:
+                # --- 是一个容器，需要创建子网格 ---
+                subgrid_info = subgrids_def[name]
+                sub_layout_list = subgrid_info['layout']
+                subgrid_kwargs = {k: v for k, v in subgrid_info.items() if k != 'layout'}
+
+                # 创建 GridSpecFromSubplotSpec
+                main_subplot_spec = main_gs[spec['row_start']:spec['row_start'] + spec['row_span'],
+                                    spec['col_start']:spec['col_start'] + spec['col_span']]
+
+                parsed_sub_layout, (sub_rows, sub_cols) = utils.parse_mosaic_layout(sub_layout_list)
+                sub_gs = GridSpecFromSubplotSpec(sub_rows, sub_cols, subplot_spec=main_subplot_spec, **subgrid_kwargs)
+
+                # 在子网格中创建最终的 Axes
+                for sub_name, sub_spec in parsed_sub_layout.items():
+                    # 生成层级名称，例如：'heatmap_container.nh2_map'
+                    hierarchical_name = f"{name}.{sub_name}"
+
+                    ax = self.fig.add_subplot(sub_gs[sub_spec['row_start']:sub_spec['row_start'] + sub_spec['row_span'],
+                                              sub_spec['col_start']:sub_spec['col_start'] + sub_spec['col_span']])
+
+                    self.axes_dict[hierarchical_name] = ax
+                    self.axes.append(ax)
+
+            else:
+                ax = self.fig.add_subplot(main_gs[spec['row_start']:spec['row_start'] + spec['row_span'],
+                                          spec['col_start']:spec['col_start'] + spec['col_span']])
+                self.axes_dict[name] = ax
+                self.axes.append(ax)
+
     def _get_ax_by_tag(self, tag: Union[str, int]) -> plt.Axes:
         """
         通过tag获取对应的Axes对象。
@@ -139,29 +191,32 @@ class Plotter(GenericPlotsMixin, ModifiersMixin, DomainSpecificPlotsMixin):
     def _get_next_ax_and_assign_tag(self, tag: Optional[Union[str, int]] = None) -> Tuple[plt.Axes, Union[str, int]]:
         """
         获取下一个可用的Axes对象，并为其分配一个tag。
+        此方法用于顺序绘图模式。
         """
-        claimed_axes = set(self.tag_to_ax.values())
-
-        ax_to_use = None
-        while self.current_ax_index < len(self.axes):
-            potential_ax = self.axes[self.current_ax_index]
-            if potential_ax not in claimed_axes:
-                ax_to_use = potential_ax
-                break
-            self.current_ax_index += 1
-
-        if ax_to_use is None:
+        # 步骤 1: 检查索引是否已经超出了可用 Axes 的范围。
+        if self.current_ax_index >= len(self.axes):
             raise PlottingSpaceError(len(self.axes))
 
+        # 步骤 2: 根据当前索引直接获取下一个 Axes。
+        # 我们不再检查它是否已被“认领”，因为我们就是要覆盖或赋予它新标签。
+        ax_to_use = self.axes[self.current_ax_index]
+
+        # 步骤 3: 处理并检查新标签是否重复。
         current_tag = tag if tag is not None else self.next_default_tag
         if current_tag in self.tag_to_ax:
+            # 顺序绘图模式下，一个已经存在的标签意味着重复，这是不允许的。
+            # 声明式模式会在 _resolve_ax 中被提前捕获，不会进入此方法。
             raise DuplicateTagError(current_tag)
-            
+
         if tag is None:
             self.next_default_tag += 1
-            
+
+        # 步骤 4: 将新标签与选定的 Axes 关联起来。
         self.tag_to_ax[current_tag] = ax_to_use
+
+        # 步骤 5: 将索引向前移动，为下一次调用做准备。
         self.current_ax_index += 1
+
         return ax_to_use, current_tag
 
     def get_ax(self, tag: Union[str, int]) -> plt.Axes:
@@ -178,3 +233,22 @@ class Plotter(GenericPlotsMixin, ModifiersMixin, DomainSpecificPlotsMixin):
             available_names = list(self.axes_dict.keys()) if isinstance(self.axes_dict, dict) else []
             raise ValueError(f"Name '{name}' not found in layout. Available names are: {available_names}")
         return self.axes_dict[name]
+
+    def _resolve_ax(self, tag: Optional[Union[str, int]] = None, ax: Optional[plt.Axes] = None) -> plt.Axes:
+        """[私有] 智能解析并返回正确的 Axes 对象。"""
+        _ax: plt.Axes
+        if ax is not None:
+            _ax = ax
+            # 如果用户同时提供了 ax 和 tag，需要注册这个关联
+            if tag is not None:
+                # 检查是否存在冲突
+                if tag in self.tag_to_ax and self.tag_to_ax[tag] is not _ax:
+                    raise DuplicateTagError(tag)
+                self.tag_to_ax[tag] = _ax
+        elif tag is not None and tag in self.tag_to_ax:
+            # tag 在布局时已定义，直接使用
+            _ax = self.tag_to_ax[tag]
+        else:
+            # ax 未提供，tag 也是新的或 None，按顺序分配
+            _ax, _ = self._get_next_ax_and_assign_tag(tag)
+        return _ax

{paperplotter-0.1.3 → paperplotter-0.1.4}/paperplot/mixins/domain.py

@@ -31,16 +31,11 @@ class DomainSpecificPlotsMixin:
         Returns:
             Plotter: 返回Plotter实例以支持链式调用。
         """
-        if ax is None:
-            ax, _ = self._get_next_ax_and_assign_tag(tag)
-        elif tag is not None:
-            if tag in self.tag_to_ax:
-                raise DuplicateTagError(tag)
-            self.tag_to_ax[tag] = ax
+        _ax = self._resolve_ax(tag, ax)
 
         for i, y_col in enumerate(y_cols):
             label = kwargs.pop('label', y_col) # 如果用户没有提供label，则使用列名
-            ax.plot(data[x], data[y_col] + i * offset, label=label, **kwargs)
+            _ax.plot(data[x], data[y_col] + i * offset, label=label, **kwargs)
         
         return self
 
@@ -61,24 +56,19 @@ class DomainSpecificPlotsMixin:
         Returns:
             Plotter: 返回Plotter实例以支持链式调用。
         """
-        if ax is None:
-            ax, tag = self._get_next_ax_and_assign_tag(tag)
-        elif tag is not None:
-            if tag in self.tag_to_ax:
-                raise DuplicateTagError(tag)
-            self.tag_to_ax[tag] = ax
+        _ax = self._resolve_ax(tag, ax)
         
         create_cbar = kwargs.pop('cbar', True)
         kwargs.setdefault('cmap', 'inferno') # 默认使用 inferno 颜色映射
         
         import seaborn as sns
-        sns.heatmap(data, ax=ax, cbar=create_cbar, **kwargs)
+        sns.heatmap(data, ax=_ax, cbar=create_cbar, **kwargs)
         
-        if tag and ax.collections:
-            self.tag_to_mappable[tag] = ax.collections[0]
+        if tag and _ax.collections:
+            self.tag_to_mappable[tag] = _ax.collections[0]
 
-        ax.set_xlabel(kwargs.pop('xlabel', 'X (μm)'))
-        ax.set_ylabel(kwargs.pop('ylabel', 'Y (μm)'))
+        _ax.set_xlabel(kwargs.pop('xlabel', 'X (μm)'))
+        _ax.set_ylabel(kwargs.pop('ylabel', 'Y (μm)'))
 
         return self
 
@@ -101,12 +91,7 @@ class DomainSpecificPlotsMixin:
         Returns:
             Plotter: 返回Plotter实例以支持链式调用。
         """
-        if ax is None:
-            ax, _ = self._get_next_ax_and_assign_tag(tag)
-        elif tag is not None:
-            if tag in self.tag_to_ax:
-                raise DuplicateTagError(tag)
-            self.tag_to_ax[tag] = ax
+        _ax = self._resolve_ax(tag, ax)
 
         if normalize:
             matrix = matrix.astype('float') / matrix.sum(axis=1)[:, np.newaxis]
@@ -121,10 +106,10 @@ class DomainSpecificPlotsMixin:
         kwargs.setdefault('fmt', fmt)
         kwargs.setdefault('cmap', 'Blues')
         
-        sns.heatmap(df_cm, ax=ax, **kwargs)
+        sns.heatmap(df_cm, ax=_ax, **kwargs)
 
-        ax.set_xlabel('Predicted Label')
-        ax.set_ylabel('True Label')
+        _ax.set_xlabel('Predicted Label')
+        _ax.set_ylabel('True Label')
         
         return self
 
@@ -145,27 +130,22 @@ class DomainSpecificPlotsMixin:
         Returns:
             Plotter: 返回Plotter实例以支持链式调用。
         """
-        if ax is None:
-            ax, _ = self._get_next_ax_and_assign_tag(tag)
-        elif tag is not None:
-            if tag in self.tag_to_ax:
-                raise DuplicateTagError(tag)
-            self.tag_to_ax[tag] = ax
+        _ax = self._resolve_ax(tag, ax)
 
         # 绘制每个类别的ROC曲线
         for key in fpr.keys():
             label = f'{key} (AUC = {roc_auc[key]:.2f})'
-            ax.plot(fpr[key], tpr[key], label=label, **kwargs)
+            _ax.plot(fpr[key], tpr[key], label=label, **kwargs)
 
         # 绘制对角参考线
-        ax.plot([0, 1], [0, 1], 'k--', lw=2)
+        _ax.plot([0, 1], [0, 1], 'k--', lw=2)
         
-        ax.set_xlim([0.0, 1.0])
-        ax.set_ylim([0.0, 1.05])
-        ax.set_xlabel('False Positive Rate')
-        ax.set_ylabel('True Positive Rate')
-        ax.set_title('Receiver Operating Characteristic (ROC) Curve')
-        ax.legend(loc="lower right")
+        _ax.set_xlim([0.0, 1.0])
+        _ax.set_ylim([0.0, 1.05])
+        _ax.set_xlabel('False Positive Rate')
+        _ax.set_ylabel('True Positive Rate')
+        _ax.set_title('Receiver Operating Characteristic (ROC) Curve')
+        _ax.legend(loc="lower right")
         
         return self
 
@@ -188,15 +168,10 @@ class DomainSpecificPlotsMixin:
         Returns:
             Plotter: 返回Plotter实例以支持链式调用。
         """
-        if ax is None:
-            ax, _ = self._get_next_ax_and_assign_tag(tag)
-        elif tag is not None:
-            if tag in self.tag_to_ax:
-                raise DuplicateTagError(tag)
-            self.tag_to_ax[tag] = ax
+        _ax = self._resolve_ax(tag, ax)
         
         import seaborn as sns
-        sns.scatterplot(data=data, x=x_pc, y=y_pc, hue=hue, ax=ax, **kwargs)
+        sns.scatterplot(data=data, x=x_pc, y=y_pc, hue=hue, ax=_ax, **kwargs)
         
         return self
 
@@ -221,31 +196,26 @@ class DomainSpecificPlotsMixin:
         Returns:
             Plotter: 返回Plotter实例以支持链式调用。
         """
-        if ax is None:
-            ax, _ = self._get_next_ax_and_assign_tag(tag)
-        elif tag is not None:
-            if tag in self.tag_to_ax:
-                raise DuplicateTagError(tag)
-            self.tag_to_ax[tag] = ax
+        _ax = self._resolve_ax(tag, ax)
 
         # 绘制时间序列线
         for y_col in y_cols:
             label = kwargs.pop('label', y_col)
-            ax.plot(data[x], data[y_col], label=label, **kwargs)
+            _ax.plot(data[x], data[y_col], label=label, **kwargs)
 
         # 标记事件
         if events and isinstance(events, dict):
             utils.add_event_markers(
-                ax=ax,
+                ax=_ax,
                 event_dates=list(events.values()),
                 labels=list(events.keys())
             )
         
         # 设置默认标签和图例
-        ax.set_xlabel(kwargs.pop('xlabel', 'Time (s)'))
-        ax.set_ylabel(kwargs.pop('ylabel', 'Value'))
-        if any(ax.get_legend_handles_labels()):
-             ax.legend()
+        _ax.set_xlabel(kwargs.pop('xlabel', 'Time (s)'))
+        _ax.set_ylabel(kwargs.pop('ylabel', 'Value'))
+        if any(_ax.get_legend_handles_labels()):
+             _ax.legend()
 
         return self
 
@@ -276,21 +246,23 @@ class DomainSpecificPlotsMixin:
             DuplicateTagError: 如果尝试使用一个已经存在的tag。
             TagNotFoundError: 如果指定的tag未找到。
         """
+        _ax = self._resolve_ax(tag, ax)
+
         if len(magnitudes) != len(angles):
             raise ValueError("Magnitudes and angles lists must have the same length.")
 
         _target_ax: plt.Axes
         _assigned_tag: Union[str, int]
 
-        if ax is None:
+        if _ax is None:
             _target_ax, _assigned_tag = self._get_next_ax_and_assign_tag(tag)
         else:
             if tag is None:
                 raise ValueError("When 'ax' is explicitly provided, a 'tag' must also be provided.")
-            if tag in self.tag_to_ax and self.tag_to_ax[tag] != ax:
+            if tag in self.tag_to_ax and self.tag_to_ax[tag] != _ax:
                 raise DuplicateTagError(tag)
-            self.tag_to_ax[tag] = ax
-            _target_ax = ax
+            self.tag_to_ax[tag] = _ax
+            _target_ax = _ax
             _assigned_tag = tag
 
         # 检查轴是否为极坐标投影

paperplotter-0.1.4/paperplot/mixins/generic.py

@@ -0,0 +1,95 @@
+# paperplot/mixins/generic.py
+
+from typing import Optional, Union, List, Callable
+import pandas as pd
+import matplotlib.pyplot as plt
+from ..exceptions import DuplicateTagError
+
+class GenericPlotsMixin:
+    """
+    包含通用绘图方法的 Mixin 类。
+    这些方法是常见图表类型（如线图、散点图、柱状图等）的直接封装。
+    """
+
+    def add_line(self, data: pd.DataFrame, x: str, y: str, tag: Optional[Union[str, int]] = None,
+                 ax: Optional[plt.Axes] = None, **kwargs) -> 'Plotter':
+        """在子图上绘制线图。"""
+        _ax = self._resolve_ax(tag, ax)
+        _ax.plot(data[x], data[y], **kwargs)
+        return self
+
+    def add_bar(self, data: pd.DataFrame, x: str, y: str, y_err: Optional[str] = None,
+                tag: Optional[Union[str, int]] = None, ax: Optional[plt.Axes] = None, **kwargs) -> 'Plotter':
+        """在子图上绘制柱状图。"""
+        _ax = self._resolve_ax(tag, ax)
+        y_error_values = data[y_err] if y_err and y_err in data else None
+        _ax.bar(data[x], data[y], yerr=y_error_values, **kwargs)
+        return self
+
+    def add_scatter(self, data: pd.DataFrame, x: str, y: str, tag: Optional[Union[str, int]] = None,
+                    ax: Optional[plt.Axes] = None, **kwargs) -> 'Plotter':
+        """在子图上绘制散点图。"""
+        _ax = self._resolve_ax(tag, ax)
+
+        resolved_kwargs = kwargs.copy()
+        for param in ['s', 'c']:
+            if param in resolved_kwargs and isinstance(resolved_kwargs[param], str):
+                column_name = resolved_kwargs[param]
+                if column_name in data.columns:
+                    resolved_kwargs[param] = data[column_name]
+
+        _ax.scatter(data[x], data[y], **resolved_kwargs)
+        return self
+
+    def add_hist(self, data: pd.DataFrame, x: str, tag: Optional[Union[str, int]] = None, ax: Optional[plt.Axes] = None,
+                 **kwargs) -> 'Plotter':
+        """在子图上绘制直方图。"""
+        _ax = self._resolve_ax(tag, ax)
+        _ax.hist(data[x], **kwargs)
+        return self
+
+    def add_box(self, data: pd.DataFrame, tag: Optional[Union[str, int]] = None, ax: Optional[plt.Axes] = None,
+                **kwargs) -> 'Plotter':
+        """在子图上绘制箱线图。"""
+        _ax = self._resolve_ax(tag, ax)
+        import seaborn as sns
+        sns.boxplot(data=data, ax=_ax, **kwargs)
+        return self
+
+    def add_heatmap(self, data: pd.DataFrame, tag: Optional[Union[str, int]] = None, ax: Optional[plt.Axes] = None,
+                    **kwargs) -> 'Plotter':
+        """在子图上绘制热图。"""
+        _ax = self._resolve_ax(tag, ax)
+
+        create_cbar = kwargs.pop('cbar', True)
+        import seaborn as sns
+        sns.heatmap(data, ax=_ax, cbar=create_cbar, **kwargs)
+
+        # 确保 tag 被正确赋值以便后续使用
+        resolved_tag = tag if tag is not None else [k for k, v in self.tag_to_ax.items() if v is _ax][-1]
+
+        if resolved_tag and hasattr(_ax, 'collections') and _ax.collections:
+            self.tag_to_mappable[resolved_tag] = _ax.collections[0]
+
+        return self
+
+    def add_seaborn(self, plot_func: Callable, tag: Optional[Union[str, int]] = None, ax: Optional[plt.Axes] = None,
+                    **kwargs) -> 'Plotter':
+        """在子图上绘制Seaborn图。"""
+        _ax = self._resolve_ax(tag, ax)
+        plot_func(ax=_ax, **kwargs)
+        return self
+
+    def add_blank(self, tag: Optional[Union[str, int]] = None) -> 'Plotter':
+        """在下一个可用的子图位置创建一个空白区域。"""
+        _ax = self._resolve_ax(tag)
+        _ax.axis('off')
+        return self
+
+    def add_regplot(self, data: pd.DataFrame, x: str, y: str, tag: Optional[str] = None, ax: Optional[plt.Axes] = None,
+                    **kwargs) -> 'Plotter':
+        """绘制散点图和线性回归趋势线。"""
+        _ax = self._resolve_ax(tag, ax)
+        import seaborn as sns
+        sns.regplot(data=data, x=x, y=y, ax=_ax, **kwargs)
+        return self

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: paperplotter
-Version: 0.1.3
+Version: 0.1.4
 Summary: 一个为科研论文设计的声明式 Matplotlib 封装库，让复杂图表的创建变得简单直观。
 Author-email: VerNe <yuu_seeing@foxmail.com>
 License-Expression: MIT
@@ -36,6 +36,7 @@ Dynamic: license-file
 *   **🎨 声明式链式调用**: 像写句子一样构建你的图表，例如 `plotter.add_line(...).set_title(...).set_xlabel(...)`。
 *   **🏷️ 基于标签的控制**: 给每个子图一个独一无二的 `tag`，之后就可以随时通过 `tag` 对其进行任何修改，告别混乱的 `axes[i][j]` 索引。
 *   **🧩 强大的布局系统**: 无论是简单的 `(行, 列)` 网格，还是使用 `mosaic` 实现的跨行跨列复杂布局，都能轻松定义。
+*   **🧱 声明式嵌套布局**: 通过一个字典即可一次性定义包含子网格的复杂层级布局，并使用 `'容器.子图'` 这样的直观路径进行引用，完美实现“图中图”。
 *   **📐 灵活的尺寸控制**: 除了传统的 `figsize`，还可以通过 `subplot_aspect` 指定子图单元格的宽高比，让 `PaperPlot` 自动计算最合适的画布尺寸。
 *   **✨ 内置科研主题**: 提供多种专业美观的内置样式，如 `publication`, `presentation` 等，一键切换图表风格。
 *   **🌐 全局图层级标注**: 提供了在整个画布（Figure）上添加文本、线条、方框和标签的 API，非常适合添加全局注释或高亮一组图表。
@@ -68,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 设置标题和标签
@@ -96,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)` |
@@ -105,7 +110,7 @@ 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()` |

{paperplotter-0.1.3 → paperplotter-0.1.4}/paperplotter.egg-info/SOURCES.txt

@@ -48,6 +48,8 @@ examples/Layout/aspect_ratio_mosaic.png
 examples/Layout/aspect_ratio_simple_grid.png
 examples/Layout/block_span_example.py
 examples/Layout/block_span_figure.png
+examples/Layout/declarative_nested_layout.png
+examples/Layout/declarative_nested_layout_example.py
 examples/Layout/row_span_example.py
 examples/Layout/row_span_figure.png
 examples/Styles_Aesthetics/aesthetic_and_processing_example.png

{paperplotter-0.1.3 → paperplotter-0.1.4}/paperplotter.egg-info/top_level.txt

@@ -1,3 +1,4 @@
 dist
 examples
 paperplot
+修改指导

{paperplotter-0.1.3 → paperplotter-0.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "paperplotter"
-version = "0.1.3"
+version = "0.1.4"
 authors = [
   { name="VerNe", email="yuu_seeing@foxmail.com" },
 ]

paperplotter-0.1.3/paperplot/mixins/generic.py

@@ -1,144 +0,0 @@
-# paperplot/mixins/generic.py
-
-from typing import Optional, Union, List, Callable
-import pandas as pd
-import matplotlib.pyplot as plt
-from ..exceptions import DuplicateTagError
-
-class GenericPlotsMixin:
-    """
-    包含通用绘图方法的 Mixin 类。
-    这些方法是常见图表类型（如线图、散点图、柱状图等）的直接封装。
-    """
-    def add_line(self, data: pd.DataFrame, x: str, y: str, tag: Optional[Union[str, int]] = None, ax: Optional[plt.Axes] = None, **kwargs) -> 'Plotter':
-        """
-        在子图上绘制线图。
-        """
-        if ax is None:
-            ax, _ = self._get_next_ax_and_assign_tag(tag)
-        elif tag is not None:
-            if tag in self.tag_to_ax:
-                raise DuplicateTagError(tag)
-            self.tag_to_ax[tag] = ax
-        ax.plot(data[x], data[y], **kwargs)
-        return self
-
-    def add_bar(self, data: pd.DataFrame, x: str, y: str, y_err: Optional[str] = None, tag: Optional[Union[str, int]] = None, ax: Optional[plt.Axes] = None, **kwargs) -> 'Plotter':
-        """
-        在子图上绘制柱状图。
-        """
-        if ax is None:
-            ax, _ = self._get_next_ax_and_assign_tag(tag)
-        elif tag is not None:
-            if tag in self.tag_to_ax:
-                raise DuplicateTagError(tag)
-            self.tag_to_ax[tag] = ax
-        y_error_values = data[y_err] if y_err and y_err in data else None
-        ax.bar(data[x], data[y], yerr=y_error_values, **kwargs)
-        return self
-        
-    def add_scatter(self, data: pd.DataFrame, x: str, y: str, tag: Optional[Union[str, int]] = None, ax: Optional[plt.Axes] = None, **kwargs) -> 'Plotter':
-        """
-        在子图上绘制散点图。
-        """
-        if ax is None:
-            ax, _ = self._get_next_ax_and_assign_tag(tag)
-        elif tag is not None:
-            if tag in self.tag_to_ax:
-                raise DuplicateTagError(tag)
-            self.tag_to_ax[tag] = ax
-        
-        resolved_kwargs = kwargs.copy()
-        for param in ['s', 'c']:
-            if param in resolved_kwargs and isinstance(resolved_kwargs[param], str):
-                column_name = resolved_kwargs[param]
-                if column_name in data.columns:
-                    resolved_kwargs[param] = data[column_name]
-
-        ax.scatter(data[x], data[y], **resolved_kwargs)
-        return self
-
-    def add_hist(self, data: pd.DataFrame, x: str, tag: Optional[Union[str, int]] = None, ax: Optional[plt.Axes] = None, **kwargs) -> 'Plotter':
-        """
-        在子图上绘制直方图。
-        """
-        if ax is None:
-            ax, _ = self._get_next_ax_and_assign_tag(tag)
-        elif tag is not None:
-            if tag in self.tag_to_ax:
-                raise DuplicateTagError(tag)
-            self.tag_to_ax[tag] = ax
-        ax.hist(data[x], **kwargs)
-        return self
-
-    def add_box(self, data: pd.DataFrame, tag: Optional[Union[str, int]] = None, ax: Optional[plt.Axes] = None, **kwargs) -> 'Plotter':
-        """
-        在子图上绘制箱线图。
-        """
-        if ax is None:
-            ax, _ = self._get_next_ax_and_assign_tag(tag)
-        elif tag is not None:
-            if tag in self.tag_to_ax:
-                raise DuplicateTagError(tag)
-            self.tag_to_ax[tag] = ax
-        
-        import seaborn as sns
-        sns.boxplot(data=data, ax=ax, **kwargs)
-        return self
-
-    def add_heatmap(self, data: pd.DataFrame, tag: Optional[Union[str, int]] = None, ax: Optional[plt.Axes] = None, **kwargs) -> 'Plotter':
-        """
-        在子图上绘制热图。
-        """
-        if ax is None:
-            ax, tag = self._get_next_ax_and_assign_tag(tag)
-        elif tag is not None:
-            if tag in self.tag_to_ax:
-                raise DuplicateTagError(tag)
-            self.tag_to_ax[tag] = ax
-        
-        create_cbar = kwargs.pop('cbar', True)
-        
-        import seaborn as sns
-        sns.heatmap(data, ax=ax, cbar=create_cbar, **kwargs)
-        
-        if tag and hasattr(ax, 'collections') and ax.collections:
-            self.tag_to_mappable[tag] = ax.collections[0]
-
-        return self
-
-    def add_seaborn(self, plot_func: Callable, tag: Optional[Union[str, int]] = None, ax: Optional[plt.Axes] = None, **kwargs) -> 'Plotter':
-        """
-        在子图上绘制Seaborn图。
-        """
-        if ax is None:
-            ax, _ = self._get_next_ax_and_assign_tag(tag)
-        elif tag is not None:
-            if tag in self.tag_to_ax:
-                raise DuplicateTagError(tag)
-            self.tag_to_ax[tag] = ax
-        plot_func(ax=ax, **kwargs)
-        return self
-
-    def add_blank(self, tag: Optional[Union[str, int]] = None) -> 'Plotter':
-        """
-        在下一个可用的子图位置创建一个空白区域。
-        """
-        ax, _ = self._get_next_ax_and_assign_tag(tag)
-        ax.axis('off')
-        return self
-
-    def add_regplot(self, data: pd.DataFrame, x: str, y: str, tag: Optional[str] = None, ax: Optional[plt.Axes] = None, **kwargs) -> 'Plotter':
-        """
-        绘制散点图和线性回归趋势线。
-        """
-        if ax is None:
-            ax, _ = self._get_next_ax_and_assign_tag(tag)
-        elif tag is not None:
-            if tag in self.tag_to_ax:
-                raise DuplicateTagError(tag)
-            self.tag_to_ax[tag] = ax
-        
-        import seaborn as sns
-        sns.regplot(data=data, x=x, y=y, ax=ax, **kwargs)
-        return self