Day 31 文件的规范拆分和写法

@浙大疏锦行

一、规范的文件命名

一个典型的机器学习项目通常包含以下阶段：

• 数据加载：从文件、数据库、API 等获取原始数据。
  • 命名参考：load_data.py 、data_loader.py
• 数据探索与可视化：了解数据特性，初期可用 Jupyter Notebook，成熟后固化绘图函数。
  • 命名参考：eda.py 、visualization_utils.py
• 数据预处理：处理缺失值、异常值，进行标准化、归一化、编码等操作。
  • 命名参考：preprocess.py 、data_cleaning.py 、data_transformation.py
• 特征工程：创建新特征，选择、优化现有特征。
  • 命名参考：feature_engineering.py
• 模型训练：构建模型架构，设置超参数并训练，保存模型。
  • 命名参考：model.py 、train.py
• 模型评估：用合适指标评估模型在测试集上的性能，生成报告。
  • 命名参考：evaluate.py
• 模型预测：用训练好的模型对新数据预测。
  • 命名参考：predict.py 、inference.py

二、规范的文件夹管理

一、项目核心代码组织

• src/（source 的缩写）：存放项目的核心源代码。按照机器学习项目阶段进一步细分：
  • src/data/：放置与数据相关的代码。
    • src/data/load_data.py：负责从各类数据源（如文件系统、数据库、API 等）读取原始数据。
    • src/data/preprocess.py：进行数据清洗（处理缺失值、异常值）、数据转换（标准化、归一化、编码等）操作。
    • src/data/feature_engineering.py：根据业务和数据特点，创建新特征或对现有特征进行选择、优化。
  • src/models/：关于模型的代码。
    • src/models/model.py：定义模型架构，比如神经网络结构、机器学习算法模型设定等。
    • src/models/train.py：设置模型超参数，并执行训练过程，保存训练好的模型。
    • src/models/evaluate.py：使用合适的评估指标（如准确率、召回率、均方误差等），在测试集上评估模型性能，生成评估报告。
    • src/models/predict.py 或 src/models/inference.py：利用训练好的模型对新数据进行预测。
  • src/utils/：存放通用辅助函数代码，可进一步细分：
    • src/utils/io_utils.py：包含文件读写相关帮助函数，比如读取特定格式文件、保存数据到文件等。
    • src/utils/logging_utils.py：实现日志记录功能，方便记录项目运行过程中的信息，便于调试和监控。
    • src/utils/math_utils.py：特定的数值计算函数，像自定义的矩阵运算、统计计算等。
    • src/utils/plotting_utils.py：绘图工具函数，用于生成数据可视化图表（如绘制损失函数变化曲线、特征分布直方图等 ）。

二、配置文件管理

• config/ 目录：集中存放项目的配置文件，方便管理和切换不同环境（开发、测试、生产）的配置。
  • config/config.py 或 config/settings.py：以 Python 代码形式定义配置参数。
  • config/config.yaml 或 config/config.json：采用 YAML 或 JSON 格式，清晰列出文件路径、模型超参数、随机种子、API 密钥等可配置参数。
  • .env 文件：通常放在项目根目录，用于存储敏感信息（如数据库密码、API 密钥等），在代码中通过环境变量的方式读取，一般会被 .gitignore 忽略，防止敏感信息泄露。

三、实验与探索代码

• notebooks/ 或 experiments/ 目录：用于初期的数据探索、快速实验、模型原型验证。
  • notebooks/initial_eda.ipynb：在项目初期，使用 Jupyter Notebook 进行数据探索与可视化，了解数据特性，分析数据分布、相关性等。
  • experiments/model_experimentation.py：编写脚本对不同模型架构、超参数组合进行快速实验，对比实验结果，寻找最优模型设置。
    这部分往往是最开始的探索阶段，后面跑通了后拆分成了完整的项目，留作纪念用。

四、项目产出物管理

• data/ 目录：存放项目相关数据。
  • data/raw/：放置从外部获取的未经处理的原始数据，保持数据原始状态。
  • data/processed/：存放经过预处理（清洗、转换、特征工程等操作）后的数据，供模型训练和评估使用。
  • data/interim/：（可选）保存中间处理结果，比如数据清洗过程中生成的临时文件、特征工程中间步骤产生的数据等。
• models/ 目录：专门存放训练好的模型文件，根据模型保存格式不同，可能是 .pkl（Python pickle 格式，常用于保存 sklearn 模型 ）、.h5（常用于保存 Keras 模型 ）、.joblib 等。
• reports/ 或 output/ 目录：存储项目运行产生的各类报告和输出文件。
  • reports/evaluation_report.txt：记录模型评估的详细结果，包括各项评估指标数值、模型性能分析等。
  • reports/visualizations/：存放数据可视化图片，如损失函数收敛图、预测结果对比图等。
  • output/logs/：保存项目运行日志文件，记录项目从开始到结束过程中的关键信息，如训练开始时间、训练过程中的损失值变化、预测时间等。

三、机器学习项目的拆分

总结一下通用的拆分起步思路：

1. 首先，按照机器学习的主要工作流程（数据处理、训练、评估等）将代码分离到不同的 .py 文件中。这是最基本也是最有价值的一步。
2. 然后，创建一个 utils.py 来存放通用的辅助函数。
3. 考虑将所有配置参数集中到一个 config.py 文件中。
4. 为你的数据和模型产出物创建专门的顶层目录，如 data/ 和 models/，将它们与你的源代码（通常放在 src/ 目录）分开。

在机器学习项目开发过程中，以下几类代码通常具有较高的复用价值，可以在不同项目或同一项目的不同阶段重复使用：

1. 数据读写相关代码

   • 读取常见格式文件（CSV、Excel、JSON、Parquet 等）的函数
   • 向数据库（MySQL、PostgreSQL、MongoDB 等）读写数据的通用接口
   • 从 API 接口获取数据并解析的工具函数

2. 数据预处理通用逻辑

   • 缺失值处理（均值 / 中位数填充、众数填充、插值法等）的标准化函数
   • 异常值检测与处理（Z-score 法、IQR 法等）的通用实现
   • 数据类型转换（如字符串转日期、类别变量编码）的工具函数
   • 数据标准化、归一化的通用方法

3. 特征工程基础组件

   • 时间特征提取（如从日期中提取年 / 月 / 日、星期几、是否节假日等）
   • 文本特征处理（分词、停用词过滤、词向量转换等）
   • 特征选择通用方法（如基于方差、相关性、树模型重要性的选择）
   • 特征缩放、离散化的通用实现

4. 模型训练与评估工具

   • 交叉验证的通用实现（K 折交叉验证、分层抽样交叉验证等）
   • 模型超参数搜索框架（网格搜索、随机搜索的封装）
   • 常见评估指标计算函数（准确率、精确率、召回率、F1 值、AUC、MSE、MAE 等）
   • 模型训练过程中的早停（early stopping）逻辑

5. 通用辅助功能

   • 日志记录工具（统一的日志格式、不同级别日志输出控制）
   • 进度条显示（尤其适用于处理大量数据或长时间训练场景）
   • 路径处理工具（解决不同操作系统路径格式差异问题）
   • 时间戳生成、文件命名规则等工具函数

6. 可视化通用组件

   • 特征分布可视化（直方图、箱线图、密度图等）
   • 模型性能可视化（ROC 曲线、混淆矩阵热图、学习曲线等）
   • 相关性分析图表（热力图、散点图矩阵等）
   • 结果对比可视化（不同模型 / 参数的性能对比图）

7. 配置与环境管理

   • 配置文件解析工具（支持从 YAML/JSON/.env 等文件读取配置）
   • 环境变量管理函数（统一的环境变量读取和验证逻辑）
   • 项目路径初始化（自动创建数据、模型、日志等目录结构）

这些可复用代码通常会被整理到项目的utils目录下，或封装成独立的工具库，通过导入的方式在不同模块中使用，既能提高开发效率，也能保证代码一致性和可维护性

四、编码格式和类型注解

        常常会看到if __name__ == "__main__"这个写法，实际上，每个文件都是一个对象，对象就会有属性和方法。

        如果直接运行这个文件，则__name__等于__main__，若这个文件被其他模块导入，则__name__不等于__main__。

这个写法有如下好处：

        1. 明确程序起点：一个 Python 项目往往由多个模块组成。if __name__ == "__main__" 可清晰界定程序执行的起始位置。比如一个包含数据处理模块 data_processing.py、模型训练模块 model_training.py 的机器学习项目，在 model_training.py 中用 if __name__ == "__main__" 包裹训练相关的主逻辑代码，运行该文件时就知道需要从这里开始执行（其他文件都是附属文件），让项目结构和执行流程更清晰。（大多时候如此）

        2. 避免执行：python遵从模块导入即执行机制，当你使用 import xxx 导入一个模块时，Python 会执行该模块中的所有顶层代码（即不在任何函数或类内部的代码）。如果顶层代码中定义了全局变量或执行了某些操作（如读取文件、初始化数据库连接），这些操作会在导入时立即生效，并可能影响整个程序的状态。为了避免执行不必要的代码，我们可以使用 if __name__ == "__main__" 来避免在导入时执行不必要的代码。这样，只有当模块被直接运行时（即被执行 python xxx.py），才会执行顶层代码，而导入时则不会执行。这样，我们就可以确保在导入模块时，不会执行不必要的代码，从而提高程序的性能和可维护性。

        3. 合理的资源管理：if __name__ == "__main__" 与定义 main 函数结合使用，函数内变量在函数执行完这些变量被释放，能及时回收内存资源，避免内存泄漏，保证程序高效运行。

        类型注释（Type Annotations）是Python 3.5+引入的一个特性，它允许你在代码中指定变量、函数参数和返回值的类型。类型注释不会影响程序的运行，但可以提供以下好处：

   提高代码可读性 ：让其他开发者更容易理解代码的意图
   便于静态分析 ：IDE和工具可以利用类型信息提供更好的代码补全、错误检查等功能
   便于文档化 ：类型信息可以作为代码文档的一部分