2026-05-10

可复现机器学习的项目模板

论文实验复现与机器学习流程模板

这是一个用于论文实验复现和机器学习流程整理的最小可运行项目。项目使用一份小型太阳能热利用系统样例数据，演示从数据检查、特征工程、模型训练、结果评估到 Pareto/TOPSIS 优化的完整流程。

样例数据为脱敏数据，只用于验证项目结构和代码流程，不代表任何实验系统的原始数据。

项目功能

本项目包含以下步骤：

1. 检查输入数据质量，包括缺失值、重复行、描述性统计和相关性分析。 2. 生成探索性图表，包括相关性热图和双变量散点图。 3. 构建模型特征，包括时间周期特征、温差、交互项和结构变量组合特征。 4. 训练多输出回归模型，包括 Ridge Regression 和 Random Forest。 5. 评估模型表现，输出 R2、MSE、RMSE、MAE 等指标。 6. 绘制真实值与预测值对比图。 7. 基于训练好的随机森林代理模型生成候选方案。 8. 使用 Pareto 筛选和 TOPSIS 方法选择最佳折中方案。

常用模型简介与选型参考

机器学习和深度学习中常用的模型很多，不同模型适合的数据类型、任务目标和数据规模并不相同。当前项目在 src/train.py 中默认使用 Ridge Regression 和 Random Forest 作为基础回归模型，但在论文复现或真实课题中，也常会接触以下模型。

常见传统机器学习模型

模型 基本介绍 常见应用场景 --- --- --- 线性回归 / Ridge / Lasso 用线性关系拟合输入与输出，Ridge 和 Lasso 在此基础上加入正则化，提高稳定性。 回归预测、基线对比、小样本表格数据 KNN 即 K-Nearest Neighbors，根据最近的 K 个样本进行分类或回归。 小规模数据分类、简单回归、模式识别入门 决策树 通过一系列条件分裂进行预测，结构直观、容易解释。 分类、回归、特征规则分析 随机森林 由多棵决策树集成而成，能降低单棵树过拟合风险。 表格数据分类与回归、特征重要性分析 SVM / SVR 通过构造最优间隔超平面完成分类或回归。 中小规模样本分类、非线性回归 XGBoost / LightGBM / CatBoost 基于梯度提升树的集成学习模型，通常在表格数据上效果较强。 表格数据建模、竞赛、工业预测任务

常见深度学习模型

模型 基本介绍 常见应用场景 --- --- --- BP 神经网络 BP 即反向传播神经网络，通常指最基础的多层前馈神经网络 MLP。 一般分类回归任务、神经网络入门 CNN 即卷积神经网络，擅长提取局部空间特征。 图像分类、目标检测、二维网格数据建模 RNN 循环神经网络，适合处理序列数据，但长序列训练时容易出现梯度问题。 序列预测、文本、时间序列基础建模 LSTM 长短期记忆网络，是改进版 RNN，更适合学习长时间依赖关系。 时间序列预测、语音、文本序列任务 GRU 门控循环单元，结构比 LSTM 更简洁，训练速度通常更快。 时间序列预测、序列建模、资源受限场景 Transformer 基于注意力机制的深度学习模型，已成为很多序列任务主流架构。 大语言模型、文本建模、长序列建模

常用模型可以怎么理解

从学习和使用频率来看，常被认为“常用”的模型通常包括：

1. 传统机器学习：线性回归、逻辑回归、KNN、决策树、随机森林、SVM、XGBoost、LightGBM。 2. 深度学习：BP 神经网络、CNN、RNN、LSTM、GRU、Transformer。

这些模型各自适合什么数据

1. 表格型结构化数据：常优先考虑线性回归、决策树、随机森林、XGBoost、LightGBM。 2. 图像数据：常优先考虑 CNN 及其变体。 3. 时间序列或文本序列数据：常优先考虑 LSTM、GRU、Transformer。 4. 数据量较小、需要快速建立基线时：可优先考虑 Ridge、KNN、决策树、随机森林。

本项目当前为什么选择 Ridge 和 Random Forest

本项目当前处理的是小型表格型工程数据，目标是完成一个可复现、可运行、便于论文实验整理的基线流程，因此优先选择了以下两类模型：

1. Ridge Regression：作为线性基线，用于快速判断变量之间是否存在稳定的线性关系。 2. Random Forest：作为非线性表格模型，用于拟合更复杂的变量关系，并作为后续优化阶段的代理模型。

如果后续替换为真实课题数据，可以在此基础上继续增加 XGBoost、LightGBM、SVR、BP、LSTM 或 GRU 等模型做对比实验。

目录结构

text reproduciblemlproject/ README.md requirements.txt data/ README.md sample/ samplesolarthermal.csv docs/ 数据字典.md 方法说明.md 结果说明.md src/ config.py datacheck.py evaluate.py features.py optimize.py plotresults.py runpipeline.py train.py outputs/ README.md figures/ metrics/ pareto/ predictions/ models/ README.md

环境要求

建议使用 Python 3.10 或更高版本。

安装依赖：

bash pip install -r requirements.txt

主要依赖包括：

- numpy - pandas - scikit-learn - matplotlib - joblib

快速运行

在项目根目录下执行：

bash python src/runpipeline.py --data data/sample/samplesolarthermal.csv

该命令会依次执行：

1. 数据质量检查。 2. 模型训练和评估。 3. Pareto/TOPSIS 候选方案优化。

可选参数：

bash python src/runpipeline.py --data data/sample/samplesolarthermal.csv --output outputs --models-dir models --split random --candidates 1000

参数说明：

参数 默认值 说明 --- --- --- --data data/sample/samplesolarthermal.csv 输入 CSV 数据路径 --output outputs 输出目录 --models-dir models 模型保存目录 --split random 验证集划分方式，可选 random 或 time --candidates 1000 优化阶段随机生成的候选方案数量

分步骤运行

如果需要单独检查某一步，可以按顺序运行以下命令。

数据检查：

bash python src/datacheck.py --data data/sample/samplesolarthermal.csv --output outputs

模型训练：

bash python src/train.py --data data/sample/samplesolarthermal.csv --output outputs --models-dir models

优化筛选：

bash python src/optimize.py --model models/randomforest.joblib --output outputs/pareto

输入数据

默认样例数据位于：

text data/sample/samplesolarthermal.csv

当前配置要求 CSV 至少包含以下列：

类型 列名 --- --- 时间列 timestep 输入变量 solarradiation 输入变量 ambienttemperature 输入变量 inlettemperature 输入变量 reynoldsnumber 输入变量 pipespacing 目标变量 thermalefficiency 目标变量 electricalefficiency 目标变量 pressuredrop

这些列在 src/config.py 中集中配置。

输出结果

运行完整流程后，主要输出如下。

数据质量和模型指标：

text outputs/metrics/dataqualitysummary.csv outputs/metrics/missingvalues.csv outputs/metrics/descriptivestatistics.csv outputs/metrics/correlationmatrix.csv outputs/metrics/modelmetrics.csv

图表：

text /ProjectImage/reproduciblemlproject/correlationheatmap.png /ProjectImage/reproduciblemlproject/bivariatescattergrid.png outputs/figures/ridgetraintruevspredicted.png outputs/figures/ridgevalidationtruevspredicted.png outputs/figures/randomforesttraintruevspredicted.png /ProjectImage/reproduciblemlproject/randomforestvalidationtruevspredicted.png /ProjectImage/reproduciblemlproject/paretofront.png

示例图表预览：

双变量散点图用于快速查看输入变量和目标变量之间的关系。

输入变量与目标变量双变量散点图

相关性热图用于查看各变量之间的线性相关程度。

相关性热图

随机森林验证集真实值与预测值对比图用于检查模型在验证集上的拟合效果。

随机森林验证集真实值与预测值对比图

Pareto 前沿图用于展示优化阶段筛选出的非支配解和 TOPSIS 最佳折中解。

Pareto 前沿图

预测和优化结果：

text outputs/predictions/modelpredictions.csv outputs/pareto/allcandidates.csv outputs/pareto/paretosolutions.csv outputs/pareto/bestsolution.csv

训练后的模型：

text models/ridge.joblib models/randomforest.joblib

核心配置

大多数项目级配置位于：

text src/config.py

常用配置项：

配置项 作用 --- --- BASEFEATURECOLUMNS 原始输入变量 TARGETCOLUMNS 模型预测目标 REQUIREDCOLUMNS 输入数据必须包含的列 DESIGNBOUNDS 优化阶段设计变量的采样范围 OBJECTIVEDIRECTIONS 各目标的优化方向 TOPSISWEIGHTS TOPSIS 折中选择的目标权重 VALIDATIONRATIO 验证集比例 SEED 随机种子

替换为真实论文数据

将该项目用于真实论文或实验数据时，建议按以下顺序修改：

1. 将真实可公开数据放入 data/sample/ 或新建 data/processed/。 2. 在 src/config.py 中修改输入变量、目标变量和必需列。 3. 在 src/config.py 中修改 DESIGNBOUNDS、OBJECTIVEDIRECTIONS 和 TOPSISWEIGHTS。 4. 如需调整特征工程逻辑，修改 src/features.py。 5. 如需调整模型类型或超参数，修改 src/train.py。 6. 在 docs/数据字典.md 中补充变量含义、单位、来源和取值范围。 7. 在 docs/方法说明.md 中记录实际建模方法。 8. 在 docs/结果说明.md 中记录真实运行结果和结论。 9. 重新运行完整流程：

bash python src/runpipeline.py --data

注

- 当前项目是复现模板，不应直接作为论文结论依据。 - 样例数据量较小，模型指标只用于验证流程是否可运行。 - 如果数据是严格时间序列，建议使用 --split time，避免随机划分造成信息泄漏。 - 如果替换为真实实验数据，应同步更新数据字典、方法说明和结果说明。