kevin-toolbox-dev 1.4.6__py3-none-any.whl → 1.4.8__py3-none-any.whl

kevin_toolbox/patches/for_matplotlib/common_charts/plot_confusion_matrix.py

@@ -1,26 +1,74 @@
-import os
 import numpy as np
 from sklearn.metrics import confusion_matrix
 import matplotlib.pyplot as plt
 import seaborn as sns
-from kevin_toolbox.patches.for_os.path import replace_illegal_chars
+from kevin_toolbox.patches.for_matplotlib.common_charts.utils import save_plot, save_record, get_output_path
+from kevin_toolbox.patches.for_matplotlib.variable import COMMON_CHARTS
 
+__name = ":common_charts:plot_confusion_matrix"
 
-def plot_confusion_matrix(data_s, title, gt_name, pd_name, label_to_value_s=None, output_dir=None,
+
+@COMMON_CHARTS.register(name=__name)
+def plot_confusion_matrix(data_s, title, gt_name, pd_name, label_to_value_s=None, output_dir=None, output_path=None,
                           replace_zero_division_with=0, **kwargs):
     """
         计算并绘制混淆矩阵
 
         参数：
-            replace_zero_division_with:         <float> 对于在normalize时引发除0错误的矩阵元素，使用何种值进行替代
-                                                    建议使用 np.nan 或者 0
+            data_s:             <dict> 数据。
+                                    形如 {<data_name>: <data list>, ...} 的字典
+            title:              <str> 绘图标题，同时用于保存图片的文件名。
+            gt_name:            <str> 在 data_s 中表示真实标签数据的键名。
+            pd_name:            <str> 在 data_s 中表示预测标签数据的键名。
+            label_to_value_s:   <dict> 标签-取值映射字典。
+                                    如 {"cat": 0, "dog": 1}）。
+            output_dir: <str or None>
+                图像保存的输出目录。如果同时指定了 output_path，则以 output_path 为准。
+                若 output_dir 和 output_path 均未指定，则图像将直接通过 plt.show() 显示而不会保存到文件。
+
+            output_dir:         <str> 图片输出目录。
+            output_path:        <str> 图片输出路径。
+                        以上两个只需指定一个即可，同时指定时以后者为准。
+                        当只有 output_dir 被指定时，将会以 title 作为图片名。
+                        若同时不指定，则直接调用 plt.show() 显示图像，而不进行保存。
+                        在保存为文件时，若文件名中存在路径不适宜的非法字符将会被进行替换。
+            replace_zero_division_with:     <float> 在归一化混淆矩阵时，如果遇到除0错误的情况，将使用该值进行替代。
+                                    建议使用 np.nan 或 0，默认值为 0。
+
+        其他可选参数：
+            dpi:                <int> 图像保存的分辨率。
+            suffix:             <str> 图片保存后缀。
+                                    目前支持的取值有 ".png", ".jpg", ".bmp"，默认为第一个。
+            normalize:          <str or None> 指定归一化方式。
+                                    可选值包括：
+                                        "true"（按真实标签归一化）
+                                        "pred"（按预测标签归一化）
+                                        "all"（整体归一化）
+                                    默认为 None 表示不归一化。
+            b_return_cfm:       <bool> 是否在返回值中包含计算得到的混淆矩阵数据。
+                                    默认为 False。
+            b_generate_record:  <boolean> 是否保存函数参数为档案。
+                                    默认为 False，当设置为 True 时将会把函数参数保存成 [output_path].record.tar。
+                                    后续可以使用 plot_from_record() 函数或者 Serializer_for_Registry_Execution 读取该档案，并进行修改和重新绘制。
+                                    该参数仅在 output_dir 和 output_path 非 None 时起效。
+
+        返回值：
+            当 b_return_cfm 为 True 时，返回值可能为一个包含 (图像路径, 混淆矩阵数据) 的元组。
     """
     paras = {
         "dpi": 200,
+        "suffix": ".png",
+        "b_generate_record": False,
         "normalize": None,  # "true", "pred", "all",
         "b_return_cfm": False,  # 是否输出混淆矩阵
     }
     paras.update(kwargs)
+    #
+    _output_path = get_output_path(output_path=output_path, output_dir=output_dir, title=title, **kwargs)
+    save_record(_func=plot_confusion_matrix, _name=__name,
+                _output_path=_output_path if paras["b_generate_record"] else None,
+                **paras)
+    data_s = data_s.copy()
 
     value_set = set(data_s[gt_name]).union(set(data_s[pd_name]))
     if label_to_value_s is None:
@@ -57,28 +105,27 @@ def plot_confusion_matrix(data_s, title, gt_name, pd_name, label_to_value_s=None
     plt.ylabel(f'{gt_name}')
     plt.title(f'{title}')
 
-    if output_dir is None:
-        plt.show()
-        output_path = None
-    else:
-        os.makedirs(output_dir, exist_ok=True)
-        output_path = os.path.join(output_dir, f'{replace_illegal_chars(title)}.png')
-        plt.savefig(output_path, dpi=paras["dpi"])
+    save_plot(plt=plt, output_path=_output_path, dpi=paras["dpi"], suffix=paras["suffix"])
 
     if paras["b_return_cfm"]:
-        return output_path, cfm
+        return _output_path, cfm
     else:
-        return output_path
+        return _output_path
 
 
 if __name__ == '__main__':
+    import os
+
     # 示例真实标签和预测标签
     y_true = np.array([0, 1, 2, 0, 1, 2, 0, 1, 2, 5])
     y_pred = np.array([0, 2, 1, 0, 2, 1, 0, 1, 1, 5])
 
-    plot_confusion_matrix(data_s={'a': y_true, 'b': y_pred},
-                          title='test', gt_name='a', pd_name='b',
-                          label_to_value_s={"A": 5, "B": 0, "C": 1, "D": 2, "E": 3},
-                          # output_dir=os.path.join(os.path.dirname(__file__), "temp"),
-                          replace_zero_division_with=-1,
-                          normalize="all")
+    plot_confusion_matrix(
+        data_s={'a': y_true, 'b': y_pred},
+        title='test_plot_confusion_matrix', gt_name='a', pd_name='b',
+        label_to_value_s={"A": 5, "B": 0, "C": 1, "D": 2, "E": 3},
+        output_dir=os.path.join(os.path.dirname(__file__), "temp"),
+        replace_zero_division_with=-1,
+        normalize="all",
+        b_generate_record=True
+    )

kevin_toolbox/patches/for_matplotlib/common_charts/plot_distribution.py

@@ -1,15 +1,66 @@
-import os
 import math
 import matplotlib.pyplot as plt
 import numpy as np
-from kevin_toolbox.patches.for_os.path import replace_illegal_chars
+from kevin_toolbox.patches.for_matplotlib.common_charts.utils import save_plot, save_record, get_output_path
+from kevin_toolbox.patches.for_matplotlib.variable import COMMON_CHARTS
 
+__name = ":common_charts:plot_distribution"
 
-def plot_distribution(data_s, title, x_name=None, x_name_ls=None, type_="hist", output_dir=None, **kwargs):
+
+@COMMON_CHARTS.register(name=__name)
+def plot_distribution(data_s, title, x_name=None, x_name_ls=None, type_="hist", output_dir=None, output_path=None,
+                      **kwargs):
+    """
+        概率分布图
+            支持以下几种绘图类型：
+                  1. 数字数据，绘制概率分布图： type_ 参数为 "hist" 或 "histogram" 时。
+                  2. 字符串数据，绘制概率直方图：type_ 参数为 "category" 或 "cate" 时。
+
+        参数：
+            data_s:             <dict> 数据。
+                                    形如 {<data_name>: <data list>, ...} 的字典，
+            title:              <str> 绘图标题，同时用于保存图片的文件名。
+            x_name:             <str> 以哪个 data_name 作为待绘制数据。
+            x_name_ls:          <list or tuple> 以多个 data_name 对应的多组数据在同一图中绘制多个概率分布图。
+            type_:              <str> 指定绘图类型。
+                                    支持的取值有：
+                                        - "hist" 或 "histogram"：     需要 <data list> 为数值数据，将绘制概率分布图。
+                                                                        需要进一步指定 steps 步长参数，
+                                                                        或者 min、max、bin_nums 参数。
+                                        - "category" 或 "cate"：      需要 <data list> 为字符串数据，将绘制概率直方图。
+            output_dir:         <str> 图片输出目录。
+            output_path:        <str> 图片输出路径。
+                        以上两个只需指定一个即可，同时指定时以后者为准。
+                        当只有 output_dir 被指定时，将会以 title 作为图片名。
+                        若同时不指定，则直接调用 plt.show() 显示图像，而不进行保存。
+                        在保存为文件时，若文件名中存在路径不适宜的非法字符将会被进行替换。
+
+        其他可选参数：
+            dpi:                <int> 图像保存的分辨率。
+            suffix:             <str> 图片保存后缀。
+                                    目前支持的取值有 ".png", ".jpg", ".bmp"，默认为第一个。
+            b_generate_record:  <boolean> 是否保存函数参数为档案。
+                                    默认为 False，当设置为 True 时将会把函数参数保存成 [output_path].record.tar。
+                                    后续可以使用 plot_from_record() 函数或者 Serializer_for_Registry_Execution 读取该档案，并进行修改和重新绘制。
+                                    该参数仅在 output_dir 和 output_path 非 None 时起效。
+
+        返回值：
+            <str> 图像保存的完整文件路径。如果 output_dir 或 output_path 被指定，
+                 则图像会保存到对应位置并返回保存路径；否则可能直接显示图像，
+                 返回值依赖于 save_plot 函数的具体实现。
+    """
     paras = {
-        "dpi": 200
+        "dpi": 200,
+        "suffix": ".png",
+        "b_generate_record": False
     }
     paras.update(kwargs)
+    #
+    _output_path = get_output_path(output_path=output_path, output_dir=output_dir, title=title, **kwargs)
+    save_record(_func=plot_distribution, _name=__name,
+                _output_path=_output_path if paras["b_generate_record"] else None,
+                **paras)
+    data_s = data_s.copy()
     if x_name is not None:
         x_name_ls = [x_name, ]
     assert isinstance(x_name_ls, (list, tuple)) and len(x_name_ls) > 0
@@ -47,19 +98,17 @@ def plot_distribution(data_s, title, x_name=None, x_name_ls=None, type_="hist",
     # 显示图例
     plt.legend()
 
-    if output_dir is None:
-        plt.show()
-        return None
-    else:
-        os.makedirs(output_dir, exist_ok=True)
-        output_path = os.path.join(output_dir, f'{replace_illegal_chars(title)}.png')
-        plt.savefig(output_path, dpi=paras["dpi"])
-        return output_path
+    save_plot(plt=plt, output_path=_output_path, dpi=paras["dpi"], suffix=paras["suffix"])
+    return _output_path
 
 
 if __name__ == '__main__':
-    plot_distribution(data_s={
-        'a': [1, 2, 3, 4, 5, 3, 2, 1],
-        'c': [1, 2, 3, 4, 5, 0, 0, 0]},
-        title='test', x_name_ls=['a', 'c'], type_="category",
-        output_dir=os.path.join(os.path.dirname(__file__), "temp"))
+    import os
+
+    plot_distribution(
+        data_s={
+            'a': [1, 2, 3, 4, 5, 3, 2, 1],
+            'c': [1, 2, 3, 4, 5, 0, 0, 0]},
+        title='test_plot_distribution', x_name_ls=['a', 'c'], type_="category",
+        output_dir=os.path.join(os.path.dirname(__file__), "temp")
+    )

kevin_toolbox/patches/for_matplotlib/common_charts/plot_from_record.py

@@ -0,0 +1,21 @@
+from kevin_toolbox.patches.for_matplotlib.variable import COMMON_CHARTS
+
+
+def plot_from_record(input_path, **kwargs):
+    """
+        从 record 中恢复并绘制图像
+            支持通过 **kwargs 对其中部分参数进行覆盖
+    """
+    from kevin_toolbox.computer_science.algorithm.registration import Serializer_for_Registry_Execution
+
+    serializer = Serializer_for_Registry_Execution()
+    serializer.load(input_path)
+    serializer.record_s["kwargs"].update(kwargs)
+    return serializer.recover()()
+
+
+if __name__ == '__main__':
+    import os
+
+    plot_from_record(input_path=os.path.join(os.path.dirname(__file__), "temp/好-吧.png.record.tar"),
+                     output_dir=os.path.join(os.path.dirname(__file__), "temp/recover"))

kevin_toolbox/patches/for_matplotlib/common_charts/plot_lines.py

@@ -1,15 +1,51 @@
-import os
-import copy
 import matplotlib.pyplot as plt
-from kevin_toolbox.patches.for_os.path import replace_illegal_chars
 from kevin_toolbox.patches.for_matplotlib.color import generate_color_list
+from kevin_toolbox.patches.for_matplotlib.common_charts.utils import save_plot, save_record, get_output_path
+from kevin_toolbox.patches.for_matplotlib.variable import COMMON_CHARTS
 
+__name = ":common_charts:plot_lines"
 
-def plot_lines(data_s, title, x_name, output_dir=None, **kwargs):
-    data_s = copy.copy(data_s)
+
+@COMMON_CHARTS.register(name=__name)
+def plot_lines(data_s, title, x_name, x_ticklabels_name=None, output_dir=None, output_path=None, **kwargs):
+    """
+        绘制折线图
+
+        参数：
+            data_s:             <dict> 数据。
+                                    形如 {<data_name>: <data list>, ...} 的字典
+            title:              <str> 绘图标题，同时用于保存图片的文件名。
+            x_name:             <str> 以哪个 data_name 作为 x 轴。
+                                    其余数据视为需要被绘制的数据点。
+                    例子： data_s={"step":[...], "acc_top1":[...], "acc_top3":[...]}
+                        当 x_name="step" 时，将会以 step 为 x 轴绘制 acc_top1 和 acc_top3 的 bar 图。
+            x_ticklabels_name:  <str or None> 若提供则表示 x 轴刻度标签对应的键名，用于替换默认的 x 轴刻度值。
+            output_dir:         <str> 图片输出目录。
+            output_path:        <str> 图片输出路径。
+                        以上两个只需指定一个即可，同时指定时以后者为准。
+                        当只有 output_dir 被指定时，将会以 title 作为图片名。
+                        若同时不指定，则直接调用 plt.show() 显示图像，而不进行保存。
+                        在保存为文件时，若文件名中存在路径不适宜的非法字符将会被进行替换。
+
+        其他可选参数：
+            dpi:                <int> 保存图像的分辨率。
+                                    默认为 200。
+            suffix:             <str> 图片保存后缀。
+                                    目前支持的取值有 ".png", ".jpg", ".bmp"，默认为第一个。
+            b_generate_record:  <boolean> 是否保存函数参数为档案。
+                                    默认为 False，当设置为 True 时将会把函数参数保存成 [output_path].record.tar。
+                                    后续可以使用 plot_from_record() 函数或者 Serializer_for_Registry_Execution 读取该档案，并进行修改和重新绘制。
+                                    该参数仅在 output_dir 和 output_path 非 None 时起效。
+            color_ls:           <list> 用于绘图的颜色列表，默认根据数据序列个数自动生成。
+            marker_ls:          <list of str> 折线图上各数据点的标记。
+            linestyle_ls:       <list of str> 线型。
+                                    默认值为 '-'，表示直线。
+    """
     line_nums = len(data_s) - 1
     paras = {
         "dpi": 200,
+        "suffix": ".png",
+        "b_generate_record": False,
         "color_ls": generate_color_list(nums=line_nums),
         "marker_ls": None,
         "linestyle_ls": '-',
@@ -19,10 +55,20 @@ def plot_lines(data_s, title, x_name, output_dir=None, **kwargs):
         if k.endswith("_ls") and not isinstance(v, (list, tuple)):
             paras[k] = [v] * line_nums
     assert line_nums == len(paras["color_ls"]) == len(paras["marker_ls"]) == len(paras["linestyle_ls"])
+    #
+    _output_path = get_output_path(output_path=output_path, output_dir=output_dir, title=title, **kwargs)
+    save_record(_func=plot_lines, _name=__name,
+                _output_path=_output_path if paras["b_generate_record"] else None,
+                **paras)
+    data_s = data_s.copy()
 
     plt.clf()
     #
     x_all_ls = data_s.pop(x_name)
+    if x_ticklabels_name is not None:
+        x_ticklabels = data_s.pop(x_ticklabels_name)
+        assert len(x_all_ls) == len(x_ticklabels)
+        plt.xticks(x_all_ls, x_ticklabels)
     data_s, temp = dict(), data_s
     for k, v_ls in temp.items():
         y_ls, x_ls = [], []
@@ -44,20 +90,18 @@ def plot_lines(data_s, title, x_name, output_dir=None, **kwargs):
     # 显示图例
     plt.legend()
 
-    if output_dir is None:
-        plt.show()
-        return None
-    else:
-        # 对非法字符进行替换
-        os.makedirs(output_dir, exist_ok=True)
-        output_path = os.path.join(output_dir, f'{replace_illegal_chars(title)}.png')
-        plt.savefig(output_path, dpi=paras["dpi"])
-        return output_path
+    save_plot(plt=plt, output_path=_output_path, dpi=paras["dpi"], suffix=paras["suffix"])
+    return _output_path
 
 
 if __name__ == '__main__':
-    plot_lines(data_s={
-        'a': [1, 2, 3, 4, 5],
-        'b': [5, 4, 3, 2, 1],
-        'c': [1, 2, 3, 4, 5]},
-        title='test', x_name='a', output_dir=os.path.join(os.path.dirname(__file__), "temp"))
+    import os
+
+    plot_lines(
+        data_s={
+            'a': [1, 2, 3, 4, 5],
+            'b': [5, 4, 3, 2, 1],
+            'c': [1, 2, 3, 4, 5]},
+        title='test_plot_lines',
+        x_name='a', output_dir=os.path.join(os.path.dirname(__file__), "temp")
+    )

kevin_toolbox/patches/for_matplotlib/common_charts/plot_scatters.py

@@ -1,15 +1,65 @@
-import os
 import matplotlib.pyplot as plt
 from kevin_toolbox.patches.for_matplotlib.color import generate_color_list
-from kevin_toolbox.patches.for_os.path import replace_illegal_chars
+from kevin_toolbox.patches.for_matplotlib.common_charts.utils import save_plot, save_record, get_output_path
+from kevin_toolbox.patches.for_matplotlib.variable import COMMON_CHARTS
 
+__name = ":common_charts:plot_scatters"
 
-def plot_scatters(data_s, title, x_name, y_name, cate_name=None, output_dir=None, **kwargs):
+
+@COMMON_CHARTS.register(name=__name)
+def plot_scatters(data_s, title, x_name, y_name, cate_name=None, output_dir=None, output_path=None, **kwargs):
+    """
+        绘制散点图
+            不同类别的数据点
+
+        参数：
+            data_s: <dict>
+                数据字典，其中每个键对应一个数据列表。必须包含 x_name 和 y_name 对应的键，
+                如果指定了 cate_name，还需要包含 cate_name 对应的键，用于按类别对散点图上数据点着色。
+            title: <str>
+                图形标题，同时用于生成保存图像时的文件名（标题中的非法字符会被替换）。
+            x_name:             <str> 以哪个 data_name 作为数据点的 x 轴。
+            y_name:             <str> 以哪个 data_name 作为数据点的 y 轴。
+            cate_name:          <str> 以哪个 data_name 作为数据点的类别。
+            output_dir:         <str or None> 图片输出目录。
+            output_path:        <str or None> 图片输出路径。
+                        以上两个只需指定一个即可，同时指定时以后者为准。
+                        当只有 output_dir 被指定时，将会以 title 作为图片名。
+                        若同时不指定，则直接调用 plt.show() 显示图像，而不进行保存。
+                        在保存为文件时，若文件名中存在路径不适宜的非法字符将会被进行替换。
+
+        其他可选参数：
+            dpi:                <int> 保存图像的分辨率。
+                                    默认为 200。
+            suffix:             <str> 图片保存后缀。
+                                    目前支持的取值有 ".png", ".jpg", ".bmp"，默认为第一个。
+            b_generate_record:  <boolean> 是否保存函数参数为档案。
+                                    默认为 False，当设置为 True 时将会把函数参数保存成 [output_path].record.tar。
+                                    后续可以使用 plot_from_record() 函数或者 Serializer_for_Registry_Execution 读取该档案，并进行修改和重新绘制。
+                                    该参数仅在 output_dir 和 output_path 非 None 时起效。
+            scatter_size:       <int> 散点的大小。
+                                    默认 5。
+
+        示例：
+            >>> data = {
+            ...     "age": [25, 30, 22, 40],
+            ...     "income": [50000, 60000, 45000, 80000],
+            ...     "gender": ["M", "F", "M", "F"]
+            ... }
+            >>> path = plot_scatters(data, "Age vs Income", "age", "income", cate_name="gender", output_dir="./plots")
+    """
     paras = {
         "dpi": 200,
+        "suffix": ".png",
+        "b_generate_record": False,
         "scatter_size": 5
     }
     paras.update(kwargs)
+    #
+    _output_path = get_output_path(output_path=output_path, output_dir=output_dir, title=title, **kwargs)
+    save_record(_func=plot_scatters, _name=__name,
+                _output_path=_output_path if paras["b_generate_record"] else None,
+                **paras)
 
     plt.clf()
     #
@@ -33,21 +83,20 @@ def plot_scatters(data_s, title, x_name, y_name, cate_name=None, output_dir=None
                        markersize=min(paras["scatter_size"], 5)) for i, j in color_s.items()
         ])
 
-    if output_dir is None:
-        plt.show()
-        return None
-    else:
-        os.makedirs(output_dir, exist_ok=True)
-        output_path = os.path.join(output_dir, f'{replace_illegal_chars(title)}.png')
-        plt.savefig(output_path, dpi=paras["dpi"])
-        return output_path
+    save_plot(plt=plt, output_path=_output_path, dpi=paras["dpi"], suffix=paras["suffix"])
+    return _output_path
 
 
 if __name__ == '__main__':
+    import os
+
     data_s_ = dict(
         x=[1, 2, 3, 4, 5],
         y=[2, 4, 6, 8, 10],
         categories=['A', 'B', 'A', 'B', 'A']
     )
 
-    plot_scatters(data_s=data_s_, title='test', x_name='x', y_name='y', cate_name='categories')
+    plot_scatters(
+        data_s=data_s_, title='test_plot_scatters', x_name='x', y_name='y', cate_name='categories',
+        output_dir=os.path.join(os.path.dirname(__file__), "temp")
+    )

kevin_toolbox/patches/for_matplotlib/common_charts/plot_scatters_matrix.py

@@ -1,14 +1,54 @@
-import os
 import pandas as pd
 import seaborn as sns
 import matplotlib.pyplot as plt
 from kevin_toolbox.patches.for_matplotlib.color import generate_color_list
-from kevin_toolbox.patches.for_os.path import replace_illegal_chars
+from kevin_toolbox.patches.for_matplotlib.common_charts.utils import save_plot, save_record, get_output_path
+from kevin_toolbox.patches.for_matplotlib.variable import COMMON_CHARTS
 
+__name = ":common_charts:plot_scatters_matrix"
 
-def plot_scatters_matrix(data_s, title, x_name_ls, cate_name=None, output_dir=None, cate_color_s=None, **kwargs):
+
+@COMMON_CHARTS.register(name=__name)
+def plot_scatters_matrix(data_s, title, x_name_ls, cate_name=None, output_dir=None, output_path=None, cate_color_s=None,
+                         **kwargs):
+    """
+        绘制散点图矩阵
+            该函数用于展示多个变量之间的两两关系。
+
+        参数：
+            data_s:             <dict> 数据。
+                                    形如 {<data_name>: <data list>, ...} 的字典
+            title:              <str> 绘图标题。
+            x_name_ls:          <list of str> 指定用于需要绘制哪些变量的两两关系。
+            cate_name:          <str or None> 使用哪个 data_name 对应的取值作为类别。
+            output_dir:         <str or None> 图片输出目录。
+            output_path:        <str or None> 图片输出路径。
+                        以上两个只需指定一个即可，同时指定时以后者为准。
+                        当只有 output_dir 被指定时，将会以 title 作为图片名。
+                        若同时不指定，则直接调用 plt.show() 显示图像，而不进行保存。
+                        在保存为文件时，若文件名中存在路径不适宜的非法字符将会被进行替换。
+            cate_color_s:       <dict or None> 类别-颜色映射字典，将 cate_name 中的每个类别映射到具体颜色。
+                                    默认为 None，自动生成颜色列表。
+
+        其他可选参数：
+            dpi:                <int> 保存图像的分辨率。
+                                    默认为 200。
+            suffix:             <str> 图片保存后缀。
+                                    目前支持的取值有 ".png", ".jpg", ".bmp"，默认为第一个。
+            b_generate_record:  <boolean> 是否保存函数参数为档案。
+                                    默认为 False，当设置为 True 时将会把函数参数保存成 [output_path].record.tar。
+                                    后续可以使用 plot_from_record() 函数或者 Serializer_for_Registry_Execution 读取该档案，并进行修改和重新绘制。
+                                    该参数仅在 output_dir 和 output_path 非 None 时起效。
+            diag_kind:          <str> 对角线图表的类型。
+                                    支持：
+                                        - "hist"（直方图）
+                                        - "kde"（核密度图）
+                                    默认为 "kde"。
+    """
     paras = {
         "dpi": 200,
+        "suffix": ".png",
+        "b_generate_record": False,
         "diag_kind": "kde"  # 设置对角线图直方图/密度图 {‘hist’, ‘kde’}
     }
     assert cate_name in data_s and len(set(x_name_ls).difference(set(data_s.keys()))) == 0
@@ -17,6 +57,11 @@ def plot_scatters_matrix(data_s, title, x_name_ls, cate_name=None, output_dir=No
         cate_color_s = {k: v for k, v in zip(temp, generate_color_list(len(temp)))}
     assert set(cate_color_s.keys()) == set(data_s[cate_name])
     paras.update(kwargs)
+    #
+    _output_path = get_output_path(output_path=output_path, output_dir=output_dir, title=title, **kwargs)
+    save_record(_func=plot_scatters_matrix, _name=__name,
+                _output_path=_output_path if paras["b_generate_record"] else None,
+                **paras)
 
     plt.clf()
     # 使用seaborn绘制散点图矩阵
@@ -29,19 +74,14 @@ def plot_scatters_matrix(data_s, title, x_name_ls, cate_name=None, output_dir=No
     #
     plt.subplots_adjust(top=0.95)
     plt.suptitle(f'{title}', y=0.98, x=0.47)
-    # g.fig.suptitle(f'{title}', y=1.05)
 
-    if output_dir is None:
-        plt.show()
-        return None
-    else:
-        os.makedirs(output_dir, exist_ok=True)
-        output_path = os.path.join(output_dir, f'{replace_illegal_chars(title)}.png')
-        plt.savefig(output_path, dpi=paras["dpi"])
-        return output_path
+    save_plot(plt=plt, output_path=_output_path, dpi=paras["dpi"], suffix=paras["suffix"])
+    return _output_path
 
 
 if __name__ == '__main__':
+    import os
+
     data_s_ = dict(
         x=[1, 2, 3, 4, 5],
         y=[2, 4, 6, 8, 10],
@@ -50,5 +90,8 @@ if __name__ == '__main__':
         title='test',
     )
 
-    plot_scatters_matrix(data_s=data_s_, title='test', x_name_ls=['y', 'x', 'z'], cate_name='categories',
-                         cate_color_s={'A': 'red', 'B': 'blue'})
+    plot_scatters_matrix(
+        data_s=data_s_, title='test_plot_scatters_matrix', x_name_ls=['y', 'x', 'z'], cate_name='categories',
+        cate_color_s={'A': 'red', 'B': 'blue'},
+        output_dir=os.path.join(os.path.dirname(__file__), "temp")
+    )

kevin_toolbox/patches/for_matplotlib/common_charts/utils/__init__.py

@@ -0,0 +1,3 @@
+from .get_output_path import get_output_path
+from .save_plot import save_plot
+from .save_record import save_record

kevin_toolbox/patches/for_matplotlib/common_charts/utils/get_output_path.py

@@ -0,0 +1,15 @@
+import os
+from kevin_toolbox.patches.for_os.path import replace_illegal_chars
+
+
+def get_output_path(output_path=None, output_dir=None, title=None, suffix=".png", **kwargs):
+    if output_path is None:
+        if output_dir is None:
+            output_path = None
+        else:
+            assert title is not None
+            assert suffix in [".png", ".jpg", ".bmp"]
+            output_path = os.path.join(output_dir, f'{replace_illegal_chars(title)}{suffix}')
+    else:
+        output_path = os.path.join(os.path.dirname(output_path), replace_illegal_chars(os.path.basename(output_path)))
+    return output_path

kevin_toolbox/patches/for_matplotlib/common_charts/utils/save_plot.py

@@ -0,0 +1,11 @@
+import os
+
+
+def save_plot(plt, output_path, dpi=200, suffix=".png", **kwargs):
+    assert suffix in [".png", ".jpg", ".bmp"]
+
+    if output_path is None:
+        plt.show()
+    else:
+        os.makedirs(os.path.dirname(output_path), exist_ok=True)
+        plt.savefig(output_path, dpi=dpi)

kevin_toolbox/patches/for_matplotlib/common_charts/utils/save_record.py

@@ -0,0 +1,34 @@
+import inspect
+from kevin_toolbox.patches.for_matplotlib.variable import COMMON_CHARTS
+
+
+def save_record(_name, _output_path,_func=None, **kwargs):
+    if _output_path is None:
+        return None
+
+    # 获取函数的参数列表
+    frame = inspect.currentframe().f_back
+    if _func is None:
+        func_name = inspect.getframeinfo(frame).function
+        _func = globals()[func_name]
+    sig = inspect.signature(_func)
+    #   获取参数值
+    args_info = inspect.getargvalues(frame)
+    arg_names = args_info.args
+    arg_values = args_info.locals
+    #   将参数值映射到函数签名中
+    kwargs_raw = {name: arg_values[name] for name in arg_names}
+    for param_name, param in sig.parameters.items():
+        if param.kind == param.VAR_KEYWORD:
+            kwargs_raw.update(arg_values[param_name])
+        elif param.kind == param.VAR_POSITIONAL:
+            kwargs_raw[param_name] = arg_values[param_name]
+
+    kwargs_raw.update(kwargs)
+
+    from kevin_toolbox.computer_science.algorithm.registration import Serializer_for_Registry_Execution
+    serializer = Serializer_for_Registry_Execution()
+    file_path = serializer.record_name(
+        _name=_name, _registry=COMMON_CHARTS
+    ).record_paras(**kwargs_raw).save(_output_path + ".record", b_pack_into_tar=True, b_allow_overwrite=True)
+    return file_path

kevin_toolbox/patches/for_matplotlib/variable.py

@@ -0,0 +1,20 @@
+import os
+from kevin_toolbox.computer_science.algorithm.registration import Registry
+
+COMMON_CHARTS = Registry(uid="COMMON_CHARTS")
+
+# 导入时的默认过滤规则
+ignore_s = [
+    {
+        "func": lambda _, __, path: os.path.basename(path) in ["temp", "test", "__pycache__",
+                                                               "_old_version"],
+        "scope": ["root", "dirs"]
+    },
+]
+
+# 从 kevin_toolbox/patches/for_matplotlib/common_charts 下收集被注册的方法
+COMMON_CHARTS.collect_from_paths(
+    path_ls=[os.path.join(os.path.dirname(__file__), "common_charts"), ],
+    ignore_s=ignore_s,
+    b_execute_now=False
+)