paperplotter 0.1.4__py3-none-any.whl

examples/Data_Analysis_Utils/data_analysis_utils_example.py

@@ -0,0 +1,81 @@
+# examples/data_analysis_utils_example.py
+
+import paperplot as pp
+import pandas as pd
+import numpy as np
+import matplotlib.pyplot as plt
+from scipy import stats
+
+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:
+    plotter = pp.Plotter(layout=(1, 2), figsize=(12, 5))
+    plotter.set_suptitle("Data Analysis Utilities", fontsize=16, weight='bold')
+
+    # --- 3. 左图: 分布拟合 ---
+    ax_dist = plotter.get_ax_by_name('ax00')
+    plotter.tag_to_ax['dist'] = ax_dist # 手动关联tag
+
+    # 绘制直方图
+    ax_dist.hist(df_dist['value'], bins=30, density=True, alpha=0.6, color='skyblue', label='Data Histogram')
+    
+    # 拟合并绘制正态分布
+    pp.utils.fit_and_plot_distribution(
+        ax=ax_dist,
+        data_series=df_dist['value'],
+        dist_name='norm',
+        color='red',
+        linestyle='--',
+        lw=2
+    )
+    
+    plotter.set_title('dist', 'fit_and_plot_distribution() Example')
+    plotter.set_xlabel('dist', 'Value')
+    plotter.set_ylabel('dist', 'Density')
+    plotter.set_legend('dist')
+
+    # --- 4. 右图: 数据分箱 ---
+    ax_bin = plotter.get_ax_by_name('ax01')
+    plotter.tag_to_ax['bin'] = ax_bin
+
+    # 绘制原始散点图
+    ax_bin.scatter(df_bin['x'], df_bin['y'], alpha=0.3, label='Raw Data')
+
+    # 分箱数据
+    binned_df = pp.utils.bin_data(df_bin, x='x', y='y', bins=5)
+    
+    # 绘制分箱后的结果（带误差棒的线图）
+    ax_bin.errorbar(binned_df['bin_center'], binned_df['y_agg'], 
+                     yerr=binned_df['y_error'], fmt='-o', color='green', 
+                     capsize=5, label='Binned Data (Mean ± Std)')
+
+    plotter.set_title('bin', 'bin_data() Example')
+    plotter.set_xlabel('bin', 'X Value')
+    plotter.set_ylabel('bin', 'Y Value')
+    plotter.set_legend('bin')
+
+
+    # --- 5. 清理和保存 ---
+    plotter.cleanup()
+    plotter.save("data_analysis_utils_example.png")
+
+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 'data_analysis_utils_example.png' was generated.")

examples/Data_Analysis_Utils/utility_functions_example.py

@@ -0,0 +1,82 @@
+# 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 的布局 ---
+try:
+    plotter = pp.Plotter(layout=(1, 2), figsize=(12, 5))
+    plotter.set_suptitle("Utility Functions Demonstration", fontsize=16, weight='bold')
+
+    # --- 3. 左侧子图: 高亮光谱峰 ---
+    plotter.add_line(data=spectra_df, x='wavenumber', y='intensity', tag='spectra')
+    plotter.set_title('spectra', 'highlight_peaks() Example')
+    plotter.set_xlabel('spectra', 'Wavenumber (cm⁻¹)')
+    plotter.set_ylabel('spectra', 'Intensity (a.u.)')
+    
+    # 调用 utils 函数
+    ax_spectra = plotter.get_ax('spectra')
+    pp.utils.highlight_peaks(
+        ax=ax_spectra, 
+        x=spectra_df['wavenumber'], 
+        y=spectra_df['intensity'], 
+        peaks_x=peaks_to_highlight,
+        label_positions={
+            1200: (1250, 0.4) # 手动将1200峰的标签移动到右下方
+        },
+        ha='center' # 水平居中
+    )
+
+    # --- 4. 右侧子图: 标记时间序列事件 ---
+    plotter.add_line(data=timeseries_df, x='time', y='signal', tag='timeseries', color='navy')
+    plotter.set_title('timeseries', 'add_event_markers() Example')
+    plotter.set_xlabel('timeseries', 'Time (s)')
+    plotter.set_ylabel('timeseries', 'Signal Value')
+
+    # 调用 utils 函数
+    ax_timeseries = plotter.get_ax('timeseries')
+    pp.utils.add_event_markers(
+        ax=ax_timeseries,
+        event_dates=event_points,
+        labels=event_labels,
+        label_positions={
+            25: (15, 2.5) # 手动移动 'Fault' 标签
+        }
+    )
+
+    # --- 5. 清理和保存 ---
+    plotter.cleanup(align_labels=True)
+    plotter.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}")
+finally:
+    plt.close('all')
+
+print(f"\n--- Finished Example: {__file__} ---")
+print("A new file 'utility_functions_example.png' was generated.")

examples/Domain_Specific_Plots/bifurcation_diagram_example.py

@@ -0,0 +1,70 @@
+# examples/bifurcation_diagram_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 logistic_map(r, x):
+    return r * x * (1 - x)
+
+n_steps = 1000
+n_transient = 200 # 忽略前面的瞬态过程
+r_values = np.linspace(2.5, 4.0, 2000)
+x_values = []
+bifurcation_param = []
+
+for r in r_values:
+    x = 0.1 # 初始值
+    # 迭代瞬态过程
+    for _ in range(n_transient):
+        x = logistic_map(r, x)
+    # 记录稳定后的值
+    for _ in range(n_steps):
+        x = logistic_map(r, x)
+        x_values.append(x)
+        bifurcation_param.append(r)
+
+df_bifurcation = pd.DataFrame({
+    'r': bifurcation_param,
+    'x': x_values
+})
+
+
+# --- 2. 创建绘图 ---
+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可以提高渲染性能
+    )
+    
+    # --- 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}")
+finally:
+    plt.close('all')
+
+print(f"\n--- Finished Example: {__file__} ---")
+print("A new file 'bifurcation_diagram_example.png' was generated.")

examples/Domain_Specific_Plots/concentration_map_example.py

@@ -0,0 +1,54 @@
+# examples/concentration_map_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浓度图数据
+np.random.seed(42)
+grid_size = 20
+x_coords = np.arange(grid_size)
+y_coords = np.arange(grid_size)
+X, Y = np.meshgrid(x_coords, y_coords)
+
+# 创建一个中心有高浓度，边缘浓度逐渐降低的模拟数据
+center_x, center_y = grid_size / 2, grid_size / 2
+sigma = 5
+concentration = np.exp(-((X - center_x)**2 + (Y - center_y)**2) / (2 * sigma**2))
+concentration += np.random.rand(grid_size, grid_size) * 0.1 # 添加一些噪声
+
+# 转换为DataFrame
+df_concentration = pd.DataFrame(concentration, index=y_coords, columns=x_coords)
+
+# --- 2. 创建绘图 ---
+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.)'} # 自定义颜色条标签
+    )
+    
+    # --- 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)')
+
+    # --- 4. 清理和保存 ---
+    plotter.cleanup()
+    plotter.save("concentration_map_example.png")
+
+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 'concentration_map_example.png' was generated.")

examples/Domain_Specific_Plots/domain_specific_plots_example.py

@@ -0,0 +1,104 @@
+# examples/domain_specific_plots_example.py
+
+import paperplot as pp
+import pandas as pd
+import numpy as np
+import matplotlib.pyplot as plt
+from sklearn.metrics import confusion_matrix, roc_curve, auc
+from sklearn.preprocessing import label_binarize
+from sklearn.decomposition import PCA
+
+print(f"--- Running Example: {__file__} ---")
+
+# --- 1. 准备数据 ---
+
+# SERS 光谱数据
+def generate_spectra_data(num_spectra=3):
+    x = np.linspace(400, 1800, 500)
+    df = pd.DataFrame({'wavenumber': x})
+    for i in range(num_spectra):
+        peak_pos = np.random.uniform(600, 1600)
+        peak_width = np.random.uniform(50, 150)
+        peak_intensity = np.random.uniform(0.5, 1)
+        noise = np.random.rand(500) * 0.05
+        y = peak_intensity * np.exp(-((x - peak_pos)**2) / (2 * peak_width**2)) + noise
+        df[f'Sample_{i+1}'] = y
+    return df
+
+spectra_df = generate_spectra_data()
+
+# 机器学习数据
+y_true = np.array([0, 1, 2, 0, 1, 2, 0, 1, 2, 0, 1, 2])
+y_score = np.random.rand(12, 3) # 模拟分类器的得分输出
+y_pred = np.argmax(y_score, axis=1)
+class_names = ['Class A', 'Class B', 'Class C']
+
+# 混淆矩阵
+cm = confusion_matrix(y_true, y_pred)
+
+# ROC 曲线数据
+y_true_bin = label_binarize(y_true, classes=[0, 1, 2])
+n_classes = y_true_bin.shape[1]
+fpr, tpr, roc_auc = dict(), dict(), dict()
+for i in range(n_classes):
+    fpr[class_names[i]], tpr[class_names[i]], _ = roc_curve(y_true_bin[:, i], y_score[:, i])
+    roc_auc[class_names[i]] = auc(fpr[class_names[i]], tpr[class_names[i]])
+
+# PCA 数据
+pca_data = np.random.rand(50, 10)
+pca = PCA(n_components=2)
+pca_result = pca.fit_transform(pca_data)
+pca_df = pd.DataFrame(data=pca_result, columns=['PC1', 'PC2'])
+pca_df['Category'] = np.random.choice(['Group X', 'Group Y'], 50)
+
+
+# --- 2. 创建一个 2x2 的布局 ---
+try:
+    plotter = pp.Plotter(layout=(2, 2), figsize=(12, 10))
+    plotter.set_suptitle("Domain-Specific Plotting Functions", fontsize=16, weight='bold')
+
+    # --- Top-Left: SERS 光谱 ---
+    y_cols = [col for col in spectra_df.columns if col.startswith('Sample')]
+    plotter.add_spectra(
+        data=spectra_df, x='wavenumber', y_cols=y_cols, tag='spectra', offset=0.5
+    )
+    plotter.set_title('spectra', 'SERS Spectra with Offset')
+    plotter.set_xlabel('spectra', 'Wavenumber (cm⁻¹)')
+    plotter.set_ylabel('spectra', 'Intensity (a.u.)')
+    plotter.set_legend('spectra')
+
+    # --- Top-Right: 混淆矩阵 ---
+    plotter.add_confusion_matrix(
+        matrix=cm, class_names=class_names, tag='cm', normalize=True
+    )
+    plotter.set_title('cm', 'Normalized Confusion Matrix')
+
+    # --- Bottom-Left: ROC 曲线 ---
+    plotter.add_roc_curve(
+        fpr=fpr, tpr=tpr, roc_auc=roc_auc, tag='roc'
+    )
+    # add_roc_curve 已经设置了大部分标题和标签，我们也可以覆盖它们
+    plotter.set_title('roc', 'Multi-Class ROC Curves')
+
+    # --- Bottom-Right: PCA 散点图 ---
+    plotter.add_pca_scatter(
+        data=pca_df, x_pc='PC1', y_pc='PC2', hue='Category', tag='pca'
+    )
+    plotter.set_title('pca', 'PCA Scatter Plot')
+    plotter.set_xlabel('pca', f'Principal Component 1 ({pca.explained_variance_ratio_[0]:.1%})')
+    plotter.set_ylabel('pca', f'Principal Component 2 ({pca.explained_variance_ratio_[1]:.1%})')
+
+
+    # --- 5. 清理和保存 ---
+    plotter.cleanup(align_labels=True)
+    plotter.save("domain_specific_plots.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}")
+finally:
+    plt.close('all')
+
+print(f"\n--- Finished Example: {__file__} ---")
+print("An updated file 'domain_specific_plots.png' was generated with 4 plots.")

examples/Domain_Specific_Plots/learning_curve_example.py

@@ -0,0 +1,86 @@
+# examples/learning_curve_example.py
+
+import paperplot as pp
+import numpy as np
+import matplotlib.pyplot as plt
+
+print(f"--- Running Example: {__file__} ---")
+
+# --- 1. 准备数据 ---
+# 模拟 scikit-learn 中 learning_curve 函数的输出
+np.random.seed(0)
+train_sizes = np.linspace(.1, 1.0, 5)
+n_folds = 5
+n_ticks = len(train_sizes)
+
+# 模拟一个欠拟合模型的得分
+train_scores_underfit = np.random.rand(n_ticks, n_folds) * 0.1 + 0.6
+test_scores_underfit = np.random.rand(n_ticks, n_folds) * 0.1 + 0.55
+
+# 模拟一个理想模型的得分
+train_scores_good = 0.95 - np.logspace(-1, -2, n_ticks)[:, np.newaxis] * (0.1 + np.random.rand(n_ticks, n_folds) * 0.1)
+test_scores_good = 0.9 - np.logspace(-1, -2, n_ticks)[:, np.newaxis] * (0.1 + np.random.rand(n_ticks, n_folds) * 0.1)
+
+# 模拟一个过拟合模型的得分
+train_scores_overfit = np.ones((n_ticks, n_folds)) * 0.99 - np.random.rand(n_ticks, n_folds) * 0.01
+test_scores_overfit = 0.7 - np.linspace(0, 0.2, n_ticks)[:, np.newaxis] + np.random.rand(n_ticks, n_folds) * 0.05
+
+
+# --- 2. 创建绘图 ---
+try:
+    plotter = pp.Plotter(layout=(1, 3), figsize=(18, 5))
+    plotter.set_suptitle("Learning Curve Examples", fontsize=16, weight='bold')
+
+    # --- 3. 绘制三个学习曲线 ---
+    # 理想模型
+    ax_good = plotter.get_ax_by_name('ax00')
+    pp.utils.plot_learning_curve(
+        ax=ax_good,
+        train_sizes=train_sizes * 1000, # 假设最多1000个样本
+        train_scores=train_scores_good,
+        test_scores=test_scores_good,
+        title='Good Fit',
+        color='blue'
+    )
+    plotter.tag_to_ax['good_fit'] = ax_good # 手动关联tag
+
+    # 欠拟合模型
+    ax_underfit = plotter.get_ax_by_name('ax01')
+    pp.utils.plot_learning_curve(
+        ax=ax_underfit,
+        train_sizes=train_sizes * 1000,
+        train_scores=train_scores_underfit,
+        test_scores=test_scores_underfit,
+        title='Underfitting',
+        color='orange'
+    )
+    plotter.tag_to_ax['underfit'] = ax_underfit
+
+    # 过拟合模型
+    ax_overfit = plotter.get_ax_by_name('ax02')
+    pp.utils.plot_learning_curve(
+        ax=ax_overfit,
+        train_sizes=train_sizes * 1000,
+        train_scores=train_scores_overfit,
+        test_scores=test_scores_overfit,
+        title='Overfitting',
+        color='red'
+    )
+    plotter.tag_to_ax['overfit'] = ax_overfit
+    
+    # --- 4. 统一Y轴范围以便比较 ---
+    plotter.set_ylim('good_fit', 0.4, 1.05)
+    plotter.set_ylim('underfit', 0.4, 1.05)
+    plotter.set_ylim('overfit', 0.4, 1.05)
+
+    # --- 5. 清理和保存 ---
+    plotter.cleanup()
+    plotter.save("learning_curve_example.png")
+
+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 'learning_curve_example.png' was generated.")

examples/Domain_Specific_Plots/phasor_diagram_example.py

@@ -0,0 +1,49 @@
+# examples/phasor_diagram_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. 准备数据 ---
+# 示例相量数据
+magnitudes = [1.0, 0.8, 1.2]
+angels = [0, 90, -45] # 角度，单位为度
+labels = ['V_ref', 'I_load', 'V_bus']
+
+# --- 2. 创建绘图 ---
+try:
+    # 初始化Plotter，创建一个普通的笛卡尔轴
+    # add_phasor_diagram 会自动将其转换为极坐标
+    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='ax00', # 使用布局中定义的tag
+        angle_unit='degrees'
+    )
+    
+    # 获取极坐标轴并设置标题
+    ax = plotter.get_ax('ax00')
+    ax.set_title('Phasor Diagram Example', va='bottom')
+
+    # --- 3. 清理和保存 ---
+    plotter.cleanup()
+    plotter.save("phasor_diagram_example.png")
+
+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 'phasor_diagram_example.png' was generated.")

examples/Domain_Specific_Plots/power_timeseries_example.py

@@ -0,0 +1,65 @@
+# examples/power_timeseries_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(0)
+time = np.linspace(0, 5, 500)
+# 基础信号
+base_signal = 0.98 + 0.02 * np.sin(time * 5)
+# 故障期间的电压跌落
+fault_dip = -0.5 * (np.exp(-(time - 1.1)**2 / 0.01))
+# 故障切除后的恢复振荡
+recovery_oscillation = 0.05 * np.sin((time - 1.2) * 20) * np.exp(-(time - 1.2) / 1.5)
+
+# 信号组合
+voltage = base_signal + fault_dip + recovery_oscillation
+frequency = 60 - 0.5 * (np.exp(-(time - 1.1)**2 / 0.02)) + 0.1 * np.sin((time - 1.2) * 15) * np.exp(-(time - 1.2))
+
+df = pd.DataFrame({
+    'time': time,
+    'Voltage (p.u.)': voltage,
+    'Frequency (Hz)': frequency
+})
+
+# 定义事件
+events = {
+    'Fault On': 1.0,
+    'Fault Cleared': 1.2
+}
+
+# --- 2. 创建绘图 ---
+try:
+    plotter = pp.Plotter(layout=(1, 1), figsize=(8, 5))
+    
+    # 使用新的 add_power_timeseries 方法
+    plotter.add_power_timeseries(
+        data=df,
+        x='time',
+        y_cols=['Voltage (p.u.)', 'Frequency (Hz)'], # 这里我们把两个不同单位的信号画在一起了，仅为演示
+        tag='power_dynamics',
+        events=events
+    )
+    
+    # --- 3. 设置标题和标签 ---
+    # add_power_timeseries 已经设置了默认标签，但我们可以覆盖它们
+    plotter.set_title('power_dynamics', 'Power System Dynamic Simulation')
+    plotter.set_ylabel('power_dynamics', 'Value') # 保持通用标签
+
+    # --- 4. 清理和保存 ---
+    plotter.cleanup()
+    plotter.save("power_timeseries_example.png")
+
+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 'power_timeseries_example.png' was generated.")

examples/Features_Customization/advanced_customization.py

@@ -0,0 +1,70 @@
+# examples/advanced_customization.py
+
+import paperplot as pp
+import pandas as pd
+import numpy as np
+import matplotlib.pyplot as plt
+from matplotlib.patches import Ellipse
+
+print(f"--- Running Example: {__file__} ---")
+
+# --- 1. 定义一个自定义美化模板 ---
+def custom_template(fig, axes):
+    """
+    一个自定义模板，它会给图表加上一个灰色背景，并用虚线绘制网格。
+    Args:
+        fig (plt.Figure): The main figure object.
+        axes (list[plt.Axes]): A list of axes to apply the template to.
+    """
+    print("\nApplying CUSTOM cleanup template...")
+    for ax in axes:
+        ax.set_facecolor('#f0f0f0') # 设置背景颜色
+        ax.grid(True, linestyle='--', color='white', linewidth=1.5)
+        ax.spines['top'].set_visible(False)
+        ax.spines['right'].set_visible(False)
+        ax.spines['left'].set_color('gray')
+        ax.spines['bottom'].set_color('gray')
+
+# --- 2. 准备数据 ---
+df = pd.DataFrame({
+    'x': np.random.gumbel(size=100),
+    'y': np.random.gumbel(size=100)
+})
+
+# --- 3. 初始化并绘图 ---
+try:
+    plotter = pp.Plotter(figsize=(6, 6), layout=(1, 1))
+
+    # 注册我们的自定义模板
+    print("Registering custom cleanup template named 'gray_grid'...")
+    # plotter.register_cleanup_template('gray_grid', custom_template)
+
+    plotter.add_scatter(data=df, x='x', y='y', tag='gumbel_dist')
+
+    # --- 4. 使用 "逃生舱口" get_ax() 进行高级定制 ---
+    print("Using get_ax() for advanced customization...")
+    # 假设我们要添加一个matplotlib原生对象，比如一个椭圆
+    ax = plotter.get_ax('gumbel_dist')
+
+    # 创建一个椭圆 Patch
+    ellipse = Ellipse(xy=(0, 0), width=2, height=4, angle=30, 
+                      facecolor='none', edgecolor='red', linestyle='--', lw=2)
+    ax.add_patch(ellipse)
+    
+    # 设置标题和标签
+    plotter.set_title('gumbel_dist', 'Gumbel Distribution with Ellipse')
+    plotter.set_xlabel('gumbel_dist', 'X value')
+    plotter.set_ylabel('gumbel_dist', 'Y value')
+
+    # --- 5. 使用自定义模板进行美化并保存 ---
+    plotter.cleanup()
+    plotter.save("advanced_customization_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__} ---")