paperplotter 0.1.4__py3-none-any.whl

examples/Features_Customization/cleanup_demonstration.py

@@ -0,0 +1,62 @@
+# examples/cleanup_demonstration.py
+
+import paperplot as pp
+import pandas as pd
+import numpy as np
+import matplotlib.pyplot as plt
+
+from paperplot import Plotter
+
+print(f"--- Running Example: {__file__} ---")
+
+# --- 1. 准备一组适合共享坐标轴的数据 ---
+# 假设我们有4个实验条件，每个条件下都有一条相似的时间序列数据
+def generate_data(offset):
+    time = np.linspace(0, 10, 50)
+    signal = np.sin(time) + np.random.randn(50) * 0.3 + offset
+    return pd.DataFrame({'time': time, 'signal': signal})
+
+df1 = generate_data(offset=0)
+df2 = generate_data(offset=0.5)
+df3 = generate_data(offset=-0.5)
+df4 = generate_data(offset=1)
+
+# --- 2. 初始化一个 2x2 的独立坐标轴画布 ---
+# 注意：这里我们特意将 sharex 和 sharey 设置为 False
+# 目的是为了后续演示 cleanup 函数如何动态地创建共享关系
+try:
+    print("Creating a 2x2 plot with INDEPENDENT axes...")
+    plotter = Plotter(layout=(2, 2), figsize=(10, 8), style='flat')
+
+    # --- 3. 填充图表 ---
+    plotter.add_line(data=df1, x='time', y='signal', tag='cond1')
+    plotter.add_line(data=df2, x='time', y='signal', tag='cond2')
+    plotter.add_line(data=df3, x='time', y='signal', tag='cond3')
+    plotter.add_line(data=df4, x='time', y='signal', tag='cond4')
+
+    # --- 4. 为每个图表设置标签 ---
+    # 在不使用cleanup时，每个图表都需要自己的标签
+    plotter.set_title('cond1', 'Condition 1').set_ylabel('cond1', 'Signal')
+    plotter.set_title('cond2', 'Condition 2')
+    plotter.set_title('cond3', 'Condition 3').set_xlabel('cond3', 'Time (s)').set_ylabel('cond3', 'Signal')
+    plotter.set_title('cond4', 'Condition 4').set_xlabel('cond4', 'Time (s)')
+    
+    # --- 5. 使用 cleanup 函数进行智能清理 ---
+    print("\nApplying cleanup() to dynamically share axes...")
+    # 我们指令cleanup函数：
+    # - 对第0行和第1行的Y轴进行共享和清理
+    # - 对第0列和第1列的X轴进行共享和清理
+    plotter.cleanup(auto_share=True)
+
+    # --- 6. 保存图像 ---
+    plotter.save("cleanup_demonstration_figure.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 'cleanup_demonstration_figure.png' was generated.")

examples/Features_Customization/composite_figure_example.py

@@ -0,0 +1,88 @@
+# examples/composite_figure_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. 准备数据 ---
+def generate_spectra_data(label):
+    x = np.linspace(400, 1800, 200)
+    peak_pos = np.random.uniform(600, 1600)
+    peak_width = np.random.uniform(50, 150)
+    peak_intensity = np.random.uniform(0.5, 1)
+    y = peak_intensity * np.exp(-((x - peak_pos)**2) / (2 * peak_width**2)) + np.random.rand(200) * 0.1
+    return pd.DataFrame({'wavenumber': x, 'intensity': y, 'label': label})
+
+df1 = generate_spectra_data('Sample A')
+df2 = generate_spectra_data('Sample B')
+
+df_pca = pd.DataFrame({
+    'PC1': np.random.randn(50),
+    'PC2': np.random.randn(50),
+    'cluster': np.random.choice(['Group 1', 'Group 2', 'Group 3'], 50)
+})
+
+# --- 2. 定义一个带空白占位符的复杂布局 ---
+# 我们创建一个 L 型布局，右下角是空白的
+layout = [
+    ['SERS_Spectra', 'SERS_Spectra'],
+    ['PCA_Result', '.']  # '.' 代表空白区域
+]
+
+try:
+    plotter = pp.Plotter(layout=layout, figsize=(10, 8))
+    plotter.set_suptitle("Composite Figure with Inset Image", fontsize=16, weight='bold')
+
+    # --- 3. 在 SERS 图区域绘图 ---
+    # 由于 'SERS_Spectra' 占据了两个单元格，我们通过 get_ax_by_name 获取合并后的 Axes
+    ax_sers = plotter.get_ax_by_name('SERS_Spectra')
+    # 在同一个 Axes 上绘制两条光谱
+    plotter.add_line(data=df1, x='wavenumber', y='intensity', ax=ax_sers, tag='spectra_A', label='Sample A')
+    plotter.add_line(data=df2, x='wavenumber', y='intensity', ax=ax_sers, tag='spectra_B', label='Sample B')
+    plotter.set_title('spectra_A', 'SERS Spectra of Samples') # tag 'spectra_A' 和 'spectra_B' 都指向同一个 ax
+    plotter.set_xlabel('spectra_A', 'Wavenumber (cm⁻¹)')
+    plotter.set_ylabel('spectra_A', 'Intensity (a.u.)')
+    plotter.set_legend('spectra_A')
+
+    # --- 4. 在 SERS 图上嵌入占位符图片 ---
+    print("Adding an inset image to the 'SERS_Spectra' plot...")
+    plotter.add_inset_image(
+        host_tag='spectra_A', 
+        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
+    )
+
+    # --- 5. 在 PCA 图区域绘图 ---
+    ax_pca = plotter.get_ax_by_name('PCA_Result')
+    # 使用 add_seaborn 绘制分组散点图
+    import seaborn as sns
+    plotter.add_seaborn(
+        plot_func=sns.scatterplot, 
+        data=df_pca, 
+        x='PC1', 
+        y='PC2', 
+        hue='cluster',
+        ax=ax_pca, 
+        tag='pca'
+    )
+    plotter.set_title('pca', 'PCA of Spectral Data')
+    plotter.set_xlabel('pca', 'Principal Component 1')
+    plotter.set_ylabel('pca', 'Principal Component 2')
+
+    # --- 6. 清理和保存 ---
+    plotter.cleanup(align_labels=True)
+    plotter.save("composite_figure.png")
+
+except (pp.PaperPlotError, FileNotFoundError, ValueError) as e:
+    print(f"\nAn error occurred:\n{e}")
+except Exception as e:
+    print(f"An unexpected error occurred: {e}")
+finally:
+    plt.close('all')
+
+print(f"\n--- Finished Example: {__file__} ---")
+print("A new file 'composite_figure.png' was generated.")
+print("Check for the L-shaped layout and the inset image in the top-right plot.")

examples/Features_Customization/error_handling_test.py

@@ -0,0 +1,75 @@
+# examples/error_handling_test.py
+
+import paperplot as pp
+import pandas as pd
+import numpy as np
+import matplotlib.pyplot as plt
+
+print(f"--- Running Example: {__file__} ---")
+
+# --- 1. 测试 DuplicateTagError ---
+print("\n--- Test 1: Catching DuplicateTagError ---")
+try:
+    plotter = pp.Plotter(layout=(2, 1))
+    df = pd.DataFrame({'x': [1], 'y': [1]})
+    
+    plotter.add_bar(data=df, x='x', y='y', tag='my_tag')
+    print("First plot with tag 'my_tag' added successfully.")
+    
+    # 故意再次使用同一个tag
+    print("Attempting to add another plot with the same tag...")
+    plotter.add_bar(data=df, x='x', y='y', tag='my_tag')
+
+except pp.DuplicateTagError as e:
+    print("\nSuccessfully caught expected error!")
+    print(f"Error Type: {type(e).__name__}")
+    print(f"Message:\n{e}")
+except Exception as e:
+    print(f"Caught an unexpected error: {e}")
+finally:
+    plt.close('all')
+
+# --- 2. 测试 TagNotFoundError ---
+print("\n--- Test 2: Catching TagNotFoundError ---")
+try:
+    plotter = pp.Plotter(layout=(1, 1))
+    plotter.add_line(pd.DataFrame({'t': [0], 'v': [0]}), x='t', y='v', tag='actual_tag')
+    print("Plot with tag 'actual_tag' added successfully.")
+    
+    # 故意使用一个不存在的tag
+    print("Attempting to modify a plot with a non-existent tag...")
+    plotter.set_title('non_existent_tag', 'My Title')
+
+except pp.TagNotFoundError as e:
+    print("\nSuccessfully caught expected error!")
+    print(f"Error Type: {type(e).__name__}")
+    print(f"Message:\n{e}")
+except Exception as e:
+    print(f"Caught an unexpected error: {e}")
+finally:
+    plt.close('all')
+
+# --- 3. 测试 PlottingSpaceError ---
+print("\n--- Test 3: Catching PlottingSpaceError ---")
+try:
+    # 创建一个只能放1个图的画布
+    plotter = pp.Plotter(layout=(1, 1))
+    df = pd.DataFrame({'x': [1], 'y': [1]})
+    
+    plotter.add_bar(data=df, x='x', y='y')
+    print("First plot added successfully to a 1x1 grid.")
+
+    # 故意添加第二个图
+    print("Attempting to add a second plot to the full grid...")
+    plotter.add_bar(data=df, x='x', y='y')
+
+except pp.PlottingSpaceError as e:
+    print("\nSuccessfully caught expected error!")
+    print(f"Error Type: {type(e).__name__}")
+    print(f"Message:\n{e}")
+except Exception as e:
+    print(f"Caught an unexpected error: {e}")
+finally:
+    plt.close('all')
+
+print(f"\n--- Finished Example: {__file__} ---")

examples/Features_Customization/feature_expansion_example.py

@@ -0,0 +1,84 @@
+# examples/feature_expansion_example.py
+
+import paperplot as pp
+import pandas as pd
+import numpy as np
+import matplotlib.pyplot as plt
+from matplotlib.patches import Rectangle
+
+print(f"--- Running Example: {__file__} ---")
+
+# --- 1. 准备数据 ---
+# 主Y轴数据：温度
+df_temp = pd.DataFrame({
+    'time': np.linspace(0, 24, 50),
+    'temperature': 20 + 5 * np.sin(np.linspace(0, 2 * np.pi, 50)) + np.random.randn(50) * 0.5
+})
+
+# 次Y轴数据：降雨量
+df_rain = pd.DataFrame({
+    'time': np.linspace(0, 24, 10),
+    'rainfall': np.random.rand(10) * 10 + 5
+})
+
+# 回归数据
+df_scatter = pd.DataFrame({
+    'x_val': np.random.rand(100) * 10,
+    'y_val': 2 * np.random.rand(100) * 10 + 5 + np.random.randn(100) * 2
+})
+
+# --- 2. 创建一个1x2的网格 ---
+try:
+    plotter = pp.Plotter(layout=(1, 2), figsize=(12, 5))
+
+    # --- 左侧子图：双Y轴示例 ---
+    # 1. 绘制主Y轴（温度）
+    plotter.add_line(data=df_temp, x='time', y='temperature', tag='weather_plot', label='Temperature (°C)', color='red')
+    plotter.set_title('weather_plot', 'Hourly Weather Data')
+    plotter.set_xlabel('weather_plot', 'Time (hours)')
+    plotter.set_ylabel('weather_plot', 'Temperature (°C)', color='red')
+    plotter.tick_params('weather_plot', axis='y', labelcolor='red')
+
+    # 2. 创建twinx轴并绘制次Y轴（降雨量）
+    ax2 = plotter.add_twinx('weather_plot')
+    ax2.bar(df_rain['time'], df_rain['rainfall'], width=0.8, alpha=0.3, color='blue', label='Rainfall (mm)')
+    ax2.set_ylabel('Rainfall (mm)', color='blue')
+    ax2.tick_params(axis='y', labelcolor='blue')
+
+    # 3. 添加参考线和文本
+    plotter.add_hline('weather_plot', y=25, linestyle='--', color='red', label='Avg Temp')
+    plotter.add_text('weather_plot', x=12, y=26, text='High Temp Zone', color='red', ha='center')
+
+    # 4. 添加一个Patch (例如，一个表示夜间的矩形)
+    night_rect = Rectangle((20, 0), 4, 30, facecolor='gray', alpha=0.2, transform=plotter.get_ax('weather_plot').transData)
+    plotter.add_patch('weather_plot', night_rect)
+
+    # --- 右侧子图：回归图示例 ---
+    plotter.add_regplot(data=df_scatter, x='x_val', y='y_val', tag='reg_plot', color='green', scatter_kws={'alpha':0.6})
+    plotter.set_title('reg_plot', 'Regression Analysis')
+    plotter.set_xlabel('reg_plot', 'Independent Variable')
+    plotter.set_ylabel('reg_plot', 'Dependent Variable')
+    plotter.add_vline('reg_plot', x=5, linestyle=':', color='gray', label='Threshold')
+    plotter.add_text('reg_plot', x=5, y=25, text='Critical Point', color='gray', ha='left', va='bottom')
+
+    # --- 全局美化 ---
+    plotter.set_suptitle("Advanced Plotting Features Demonstration", fontsize=16, weight='bold', y=1.02)
+    # 注意：全局图例需要手动收集twinx轴的label
+    # 或者，我们可以让add_twinx返回的ax2也注册到tag_to_ax，这样add_global_legend就能自动收集
+    # 但目前add_twinx只返回ax2，所以需要手动处理
+    # 暂时不添加全局图例，因为twinx的图例收集需要更复杂的逻辑
+    # plotter.add_global_legend(loc='upper right') 
+    plotter.cleanup(align_labels=True)
+
+    # --- 5. 保存图像 ---
+    plotter.save("feature_expansion_figure.png")
+
+except (pp.PaperPlotError, ValueError) 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"\n--- Finished Example: {__file__} ---")
+print("A new file 'feature_expansion_figure.png' was generated.")

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

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

examples/Features_Customization/global_controls_example.py

@@ -0,0 +1,66 @@
+# examples/global_controls_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. 准备数据 ---
+def generate_data(label):
+    x = np.linspace(0, 10, 40)
+    y = np.sin(x + np.random.rand() * 5) * np.random.rand() + np.random.randn(40) * 0.1
+    return pd.DataFrame({'x': x, 'y': y, 'label': label})
+
+df1 = generate_data('Series A')
+df2 = generate_data('Series B')
+df3 = generate_data('Series C')
+df4 = generate_data('Series D')
+
+# --- 2. 创建一个2x2的简单网格 ---
+try:
+    # 使用 (2, 2) 元组来创建一个简单的2x2布局
+    plotter = pp.Plotter(layout=(2, 2), figsize=(10, 8))
+
+    # --- 3. 填充图表 ---
+    # 注意我们为每条线都设置了label，以便全局图例能收集到它们
+    plotter.add_line(data=df1, x='x', y='y', tag='tl', label='Series A', color='blue')
+    plotter.add_line(data=df2, x='x', y='y', tag='tr', label='Series B', color='red')
+    plotter.add_line(data=df3, x='x', y='y', tag='bl', label='Series C', color='green')
+    plotter.add_line(data=df4, x='x', y='y', tag='br', label='Series D', color='purple')
+
+    # --- 4. 使用新的全局控制功能 ---
+    
+    # a. 设置一个全局主标题
+    print("Setting a global suptitle...")
+    plotter.set_suptitle("Global Figure Title (Suptitle)", fontsize=20, weight='bold')
+
+    # b. 为所有子图设置独立的标题
+    plotter.set_title('tl', 'Top-Left Plot')
+    plotter.set_title('tr', 'Top-Right Plot')
+    plotter.set_title('bl', 'Bottom-Left Plot')
+    plotter.set_title('br', 'Bottom-Right Plot')
+
+    # c. 创建一个全局图例
+    # 它会自动收集所有子图的'label'，并移除子图自身的图例
+    print("Adding a global legend...")
+    plotter.add_global_legend(loc='upper right')
+
+    # d. 使用增强的cleanup功能
+    # 我们共享所有行和列的轴，并确保标签对齐
+    print("Running cleanup with label alignment...")
+    plotter.cleanup(share_y_on_rows=[0, 1], share_x_on_cols=[0, 1], align_labels=True)
+
+    # --- 5. 保存图像 ---
+    plotter.save("global_controls_figure.png")
+
+except (pp.PaperPlotError, ValueError) 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"\n--- Finished Example: {__file__} ---")
+print("A new file 'global_controls_figure.png' was generated.")

examples/Features_Customization/heatmap_colorbar_example.py

@@ -0,0 +1,68 @@
+# examples/heatmap_colorbar_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. 准备三组数据范围不同的热图数据 ---
+def generate_heatmap_data(vmin, vmax, size=5):
+    return pd.DataFrame(np.random.rand(size, size) * (vmax - vmin) + vmin)
+
+df1 = generate_heatmap_data(0, 10)
+df2 = generate_heatmap_data(5, 15)
+df3 = generate_heatmap_data(-5, 5)
+
+# --- 2. 演示共享颜色条功能 ---
+try:
+    print("Creating 3 heatmaps with a shared colorbar...")
+    plotter = pp.Plotter(layout=(1, 3), figsize=(12, 4))
+
+    # --- 3. 添加热图，并明确指定 cbar=False ---
+    # 这是关键一步：我们告诉plotter不要为每个热图单独创建颜色条
+    plotter.add_heatmap(data=df1, tag='h1', cbar=False, annot=True, fmt='.0f')
+    plotter.add_heatmap(data=df2, tag='h2', cbar=False, annot=True, fmt='.0f')
+    plotter.add_heatmap(data=df3, tag='h3', cbar=False, annot=True, fmt='.0f')
+
+    # --- 4. 设置标题 ---
+    plotter.set_title('h1', 'Range 0-10')
+    plotter.set_title('h2', 'Range 5-15')
+    plotter.set_title('h3', 'Range -5-5')
+
+    # --- 5. 调用 cleanup_heatmaps 来创建共享颜色条 ---
+    # 函数会自动找到所有热图的全局数据范围 (-5 到 15)
+    # 并创建一个能代表这个全局范围的颜色条
+    plotter.cleanup_heatmaps(tags=['h1', 'h2', 'h3'])
+    
+    # 我们也可以顺便清理一下Y轴，让它们对齐
+    plotter.cleanup(share_y_on_rows=[0])
+
+    # --- 6. 保存图像 ---
+    plotter.save("heatmap_shared_colorbar_figure.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')
+
+# --- 7. 作为对比，创建一个带独立颜色条的热图 ---
+try:
+    print("\nCreating a single heatmap with its own colorbar (default behavior)...")
+    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')
+    plotter_single.save("heatmap_default_figure.png")
+
+except pp.PaperPlotError as e:
+    print(f"\nA PaperPlot error occurred:\n{e}")
+finally:
+    plt.close('all')
+
+
+print(f"\n--- Finished Example: {__file__} ---")
+print("Two files were generated: 'heatmap_shared_colorbar_figure.png' and 'heatmap_default_figure.png'")

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