kevin-toolbox-dev 1.4.7__py3-none-any.whl → 1.4.9__py3-none-any.whl

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, x_ticklabels_name=None, 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,6 +55,12 @@ def plot_lines(data_s, title, x_name, x_ticklabels_name=None, output_dir=None, *
         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()
     #
@@ -48,20 +90,18 @@ def plot_lines(data_s, title, x_name, x_ticklabels_name=None, output_dir=None, *
     # 显示图例
     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,12 @@
+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)
+    plt.close()

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
+)

kevin_toolbox/patches/for_numpy/linalg/softmax.py

@@ -30,7 +30,7 @@ def softmax(x, axis=-1, temperature=None, b_use_log_over_x=False):
     else:
         # softmax(x)
         # 为了数值稳定，减去最大值
-        x = x - np.max(x)
+        x = x - np.max(x, axis=axis, keepdims=True)
         #
         if temperature is not None:
             assert temperature > 0
@@ -46,3 +46,6 @@ if __name__ == '__main__':
     print(softmax(np.asarray([[[0], [0.1]]]), temperature=0.00001, axis=1))
     print(softmax(np.asarray([[[0], [0.1]]]), temperature=0, axis=1))
     print(softmax([0, 1, 2], temperature=0.1))
+    print(softmax([[5.0000e-01, 5.0000e-01],
+                   [7.0000e-01, 3.0000e-01],
+                   [0.0000e+00, 1.0000e+03]], axis=-1, temperature=None))

kevin_toolbox_dev-1.4.9.dist-info/METADATA

@@ -0,0 +1,75 @@
+Metadata-Version: 2.1
+Name: kevin-toolbox-dev
+Version: 1.4.9
+Summary: 一个常用的工具代码包集合
+Home-page: https://github.com/cantbeblank96/kevin_toolbox
+Download-URL: https://github.com/username/your-package/archive/refs/tags/v1.0.0.tar.gz
+Author: kevin hsu
+Author-email: xukaiming1996@163.com
+License: MIT
+Keywords: mathematics,pytorch,numpy,machine-learning,algorithm
+Platform: UNKNOWN
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+Requires-Dist: torch (>=1.2.0)
+Requires-Dist: numpy (>=1.19.0)
+Provides-Extra: plot
+Requires-Dist: matplotlib (>=3.0) ; extra == 'plot'
+Provides-Extra: rest
+Requires-Dist: pytest (>=6.2.5) ; extra == 'rest'
+Requires-Dist: line-profiler (>=3.5) ; extra == 'rest'
+
+# kevin_toolbox
+
+一个通用的工具代码包集合
+
+
+
+环境要求
+
+```shell
+numpy>=1.19
+pytorch>=1.2
+```
+
+安装方法：
+
+```shell
+pip install kevin-toolbox  --no-dependencies
+```
+
+
+
+[项目地址 Repo](https://github.com/cantbeblank96/kevin_toolbox)
+
+[使用指南 User_Guide](./notes/User_Guide.md)
+
+[免责声明 Disclaimer](./notes/Disclaimer.md)
+
+[版本更新记录](./notes/Release_Record.md)：
+
+- v 1.4.9 （2025-03-27）【new feature】【bug fix】
+
+  - patches.for_numpy.linalg
+    - 【bug fix】fix bug in softmax()，修改 33 行，从减去全局最大值改为减去各个分组内部的最大值，避免全局最大值过大导致某些分组全体数值过小导致计算溢出。
+  - patches.for_matplotlib.common_charts.utils
+    - modify save_plot()，在最后增加 plt.close() 用于及时销毁已使用完的画布，避免不必要的内存占用。
+  - nested_dict_list
+    - 【new feature】modify traverse()，增加以下参数以更加精确地控制遍历时的行为：
+      - b_skip_repeated_non_leaf_node:  是否跳过重复的非叶节点。
+        - 何为重复？在内存中的id相同。
+        - 默认为 None，此时将根据 action_mode 的来决定：
+          - 对于会对节点进行修改的模式，比如 "remove" 和 "replace"，将设为 True，以避免预期外的重复转换和替换。
+          - 对于不会修改节点内容的模式，比如 "skip"，将设为 False。
+      - cond_for_repeated_leaf_to_skip：函数列表。在叶节点位置上，遇到满足其中某个条件的重复的元素时需要跳过。
+    - 同步修改内部使用了 traverse() 的 get_nodes() 和 copy_() 等函数。
+    - 新增了对应的测试用例。
+  - data_flow.file.json_
+    - 【bug fix】fix bug in write()。
+      - bug 归因：在 json_.write() 中通过使用 ndl.traverse() 来找出待转换的元素并进行转换，但是在 v1.4.8 前，该函数默认不会跳过重复（在内存中的id相同）出现的内容。由于该内容的不同引用实际上指向的是同一个，因此对这些引用的分别多次操作实际上就是对该内容进行了多次操作。
+      - bug 解决：在后续 v1.4.9 中为 ndl.traverse() 新增了 b_skip_repeated_non_leaf_node 用于控制是否需要跳过重复的引用。我们只需要在使用该函数时，令参数 b_skip_repeated_non_leaf_node=True即可。
+
+