KNN 算法（K 近邻）

1. 方法概述

K 近邻（K-Nearest Neighbors, KNN）是一类基于距离的非参数监督学习方法，可用于分类与回归。其基本思想是：对新样本，寻找特征空间中距离最近的 K 个样本，并以邻域的类别投票（分类）或数值平均（回归）作为预测结果。

设共有 \(n\) 个样本、\(d\) 个特征，数据集为

$$ \mathcal{D}=\{(x_i,y_i)\}_{i=1}^{n},\quad x_i\in\mathbb{R}^d \tag{1} $$

其中 \(y_i\) 为类别标签（分类）或连续值（回归）。

2. 公共部分（预处理与距离度量）

系统在模型训练前支持缺失处理、编码、缩放、特征构造、特征选择与降维等步骤（均在训练集上拟合，再作用于测试集或交叉验证折内，避免数据泄漏）。

2.1 标准化与归一化

Z-score 标准化： $$ z_{ij}=\frac{x_{ij}-\mu_j}{\sigma_j} \tag{2} $$

Min-Max 归一化： $$ z_{ij}=\frac{x_{ij}-\min x_j}{\max x_j-\min x_j+\varepsilon} \tag{3} $$

2.2 One-Hot 编码（类别型变量）

$$ x^{(k)}_{ij}= \begin{cases} 1,& x_{ij}=\text{cat}_k\\ 0,& \text{otherwise} \end{cases} \tag{4} $$

2.3 多项式特征

$$ \phi(x)=\{x_1^{a_1}x_2^{a_2}\cdots x_d^{a_d}\mid a_1+\cdots+a_d\le d_p\} \tag{5} $$

2.4 特征选择（方差阈值 / 互信息）

方差阈值： $$ \operatorname{Var}(x_j)=\frac{1}{n-1}\sum_{i=1}^{n}(x_{ij}-\mu_j)^2 \tag{6} $$

互信息： $$ I(X;Y)=\sum_{x\in X}\sum_{y\in Y}p(x,y)\log\frac{p(x,y)}{p(x)p(y)} \tag{7} $$

2.5 降维（PCA）

协方差矩阵： $$ \Sigma=\frac{1}{n-1}\sum_{i=1}^{n}(x_i-\bar{x})(x_i-\bar{x})^\top \tag{8} $$

主成分解释率： $$ \eta_k=\frac{\lambda_k}{\sum_{j=1}^{d}\lambda_j} \tag{9} $$

2.6 IQR 异常值截断（可选）

$$ \text{IQR}=Q_3-Q_1,\quad x\leftarrow \min(\max(x,Q_1-k\cdot\text{IQR}),\,Q_3+k\cdot\text{IQR}) \tag{10} $$

2.7 距离度量（Minkowski）

$$ d(x,z)=\left(\sum_{j=1}^{d}|x_j-z_j|^p\right)^{1/p} \tag{11} $$

当 \(p=2\) 时为欧氏距离；\(p=1\) 时为曼哈顿距离。

2.8 符号说明（细化）

2.9 SMOTE（仅分类，可选）

当类别不平衡时，可对少数类样本进行过采样。对少数类样本 \(x\) 及其近邻 \(x_{nn}\in S_w\)，生成合成样本：

$$ x_{new}=x+\lambda\,(x_{nn}-x),\quad \lambda\sim U(0,1) \tag{12} $$

其中 \(U(0,1)\) 表示均匀分布。该操作仅在训练集上执行，避免数据泄漏。

2.10 交叉验证（k 折）

将数据划分为 \(k\) 个互斥子集，依次使用第 \(t\) 折作为验证集，其余作为训练集。指标取各折平均：

$$ \overline{M}=\frac{1}{k}\sum_{t=1}^{k} M_t \tag{13} $$

为衡量指标波动性，可计算方差与标准差：

$$ \operatorname{Var}(M)=\frac{1}{k-1}\sum_{t=1}^{k}(M_t-\overline{M})^2 \tag{13a} $$

$$ \operatorname{Std}(M)=\sqrt{\operatorname{Var}(M)} \tag{13b} $$

其中 \(M_t\) 表示第 \(t\) 折上的评价指标（如 Accuracy、F1、MAE 等）。

提示：式(13a)–(13b) 为较复杂的统计量，论文中可按需选用或省略。

3. 回归版（KNN Regression）

3.1 预测函数（均值 / 加权均值）

设 \(\mathcal{N}_K(x)\) 为样本 \(x\) 的 K 近邻集合，则

均值回归（uniform）： $$ \hat{y}(x)=\frac{1}{K}\sum_{i\in \mathcal{N}_K(x)}y_i \tag{14} $$

距离加权回归（distance）： $$ w_i=\frac{1}{d(x,x_i)+\varepsilon},\quad \hat{y}(x)=\frac{\sum_{i\in \mathcal{N}_K(x)}w_i y_i}{\sum_{i\in \mathcal{N}_K(x)}w_i} \tag{15} $$

3.2 回归评价指标

MAE $$ \text{MAE}=\frac{1}{n}\sum_{i=1}^{n}|y_i-\hat{y}_i| \tag{16} $$

MSE / RMSE $$ \text{MSE}=\frac{1}{n}\sum_{i=1}^{n}(y_i-\hat{y}_i)^2 \tag{17} $$

$$ \text{RMSE}=\sqrt{\text{MSE}} \tag{18} $$

决定系数 $$ R^2=1-\frac{\sum_{i=1}^{n}(y_i-\hat{y}_i)^2}{\sum_{i=1}^{n}(y_i-\bar{y})^2} \tag{19} $$

3.3 回归文字说明（可直接用于论文）

• 采用 KNN 回归模型对目标变量进行预测，邻居数为 \(K\)，距离采用 Minkowski 度量（式(11)）。
• 预测值由邻域样本的均值或距离加权均值给出（式(14)–(15)），以反映局部相似样本的贡献。
• 模型效果以 MAE、MSE、RMSE 与 \(R^2\) 衡量（式(16)–(19)）。
• 输出预测–真实对比图、残差分布与残差–拟合图，用于检验误差分布与拟合稳定性。

4. 分类版（KNN Classification）

4.1 多数投票 / 加权投票

令 \(\mathbb{I}(\cdot)\) 为指示函数，则

多数投票（uniform）： $$ \hat{y}(x)=\arg\max_{c}\sum_{i\in \mathcal{N}_K(x)}\mathbb{I}(y_i=c) \tag{20} $$

距离加权投票（distance）： $$ \hat{y}(x)=\arg\max_{c}\sum_{i\in \mathcal{N}_K(x)}w_i\,\mathbb{I}(y_i=c),\quad w_i=\frac{1}{d(x,x_i)+\varepsilon} \tag{21} $$

4.2 分类评价指标

准确率 $$ \text{Accuracy}=\frac{TP+TN}{TP+FP+TN+FN} \tag{22} $$

精确率 / 召回率 $$ \text{Precision}=\frac{TP}{TP+FP},\quad \text{Recall}=\frac{TP}{TP+FN} \tag{23} $$

F1 值 $$ \text{F1}=\frac{2\cdot\text{Precision}\cdot\text{Recall}}{\text{Precision}+\text{Recall}} \tag{24} $$

混淆矩阵元素定义（以正类为 1）： $$ TP=\sum_{i=1}^{n}\mathbb{I}(y_i=1,\hat{y}_i=1) \tag{25} $$

$$ FP=\sum_{i=1}^{n}\mathbb{I}(y_i=0,\hat{y}_i=1) \tag{26} $$

$$ TN=\sum_{i=1}^{n}\mathbb{I}(y_i=0,\hat{y}_i=0) \tag{27} $$

$$ FN=\sum_{i=1}^{n}\mathbb{I}(y_i=1,\hat{y}_i=0) \tag{28} $$

提示：式(25)–(28) 为基础定义，若篇幅有限可仅保留混淆矩阵图与 Accuracy/F1 公式。

ROC/PR 曲线面积（AUC，选用）： $$ \text{AUC}_{ROC}=\int_{0}^{1}\text{TPR}(\text{FPR})\,d(\text{FPR}) \tag{29} $$

$$ \text{AUC}_{PR}=\int_{0}^{1}\text{Precision}(\text{Recall})\,d(\text{Recall}) \tag{30} $$

提示：式(29)–(30) 为较复杂公式，本科/硕士论文可按需选用，若篇幅有限可仅保留 ROC/PR 图示与结论描述。

混淆矩阵表格形式（选用）： $$ \mathbf{C}=\begin{bmatrix} TP & FP \\\\ FN & TN \end{bmatrix} \tag{31} $$

阈值与 TPR/FPR 的关系（选用，二分类）： $$ \text{TPR}(\tau)=\frac{TP(\tau)}{TP(\tau)+FN(\tau)},\quad \text{FPR}(\tau)=\frac{FP(\tau)}{FP(\tau)+TN(\tau)} \tag{32} $$

阈值与 Precision/Recall 的关系（选用，二分类）： $$ \text{Precision}(\tau)=\frac{TP(\tau)}{TP(\tau)+FP(\tau)},\quad \text{Recall}(\tau)=\frac{TP(\tau)}{TP(\tau)+FN(\tau)} \tag{33} $$

宏/微平均（选用，多分类）： $$ \text{Precision}_{macro}=\frac{1}{C}\sum_{c=1}^{C}\text{Precision}_c,\quad \text{Recall}_{macro}=\frac{1}{C}\sum_{c=1}^{C}\text{Recall}_c \tag{34} $$

$$ \text{Precision}_{micro}=\frac{\sum_c TP_c}{\sum_c (TP_c+FP_c)},\quad \text{Recall}_{micro}=\frac{\sum_c TP_c}{\sum_c (TP_c+FN_c)} \tag{35} $$

加权平均 Precision/Recall（选用，多分类）： $$ \text{Precision}_{weighted}=\sum_{c=1}^{C}\frac{n_c}{N}\text{Precision}_c,\quad \text{Recall}_{weighted}=\sum_{c=1}^{C}\frac{n_c}{N}\text{Recall}_c \tag{36} $$

宏/微平均 F1（选用，多分类）： $$ \text{F1}_{macro}=\frac{1}{C}\sum_{c=1}^{C}\text{F1}_c,\quad \text{F1}_{micro}=\frac{2\cdot\text{Precision}_{micro}\cdot\text{Recall}_{micro}}{\text{Precision}_{micro}+\text{Recall}_{micro}} \tag{37} $$

加权平均 F1（选用，多分类）： $$ \text{F1}_{weighted}=\sum_{c=1}^{C}\frac{n_c}{N}\text{F1}_c \tag{38} $$

多分类混淆矩阵（选用）： $$ \mathbf{C}\in\mathbb{R}^{C\times C},\quad C_{ij}=\sum_{n=1}^{N}\mathbb{I}(y_n=i,\hat{y}_n=j) \tag{39} $$

提示：式(31)–(39) 为补充定义，可按需选用或省略；本科/硕士论文可优先保留核心指标与图示。

4.3 分类文字说明（可直接用于论文）

• 采用 KNN 分类模型对样本类别进行判别，邻居数为 \(K\)，距离度量为 Minkowski（式(11)）。
• 预测类别由邻域样本的多数投票或距离加权投票得到（式(20)–(21)）。
• 分类性能以 Accuracy、Precision、Recall、F1 为主（式(22)–(24)），并辅以混淆矩阵分析分类错误分布。
• 输出 ROC/PR 曲线、混淆矩阵与类别分布图，用于评价模型区分能力与类别平衡情况。

5. 实现说明与注意事项

• KNN 对距离度量敏感，建议在建模前进行标准化或归一化。
• \(K\) 过小易过拟合，过大易欠拟合，可结合交叉验证或调参曲线选择合适的 \(K\)。
• 特征维度过高时可考虑特征选择或降维，以降低“维度灾难”影响。

6. 界面流程与论文方法描述（可直接粘贴）

• 选择任务类型（分类/回归），加载数据或示例数据，设置目标列。
• 进行特征工程：缺失处理、One-Hot 编码、缩放（可选 SMOTE/特征选择/降维），并确保仅在训练集拟合后作用于测试集。
• 设置 KNN 参数：\(K\)、weights（uniform/distance）、距离度量（Minkowski）与 \(p\)、算法与 leaf_size、test_size、交叉验证折数。
• 运行模型，系统输出 Excel 结果表与图表（预测/指标/混淆矩阵/ROC/PR/残差等）。

提示：论文正文可仅保留核心公式与主要结果图，其余公式均已在本文档标注“可选”。

7. 与代码实现的对应关系

KNN 程序的实现对应 具体的算法/KNN算法/core/critic_calculator.py、core/knn_classifier.py、core/knn_regressor.py 与 ui/upload_widget.py。从代码看，它不是“只算一个 K 值然后给出结果”，而是把数据拆分、特征工程、调参、图表导出和结果复核整合成了一套完整流程。

实现中值得在 md 中明确说明的点如下：

1. 输出目录为时间戳目录
   程序默认在 results/ 下生成时间戳目录，Excel 与图像文件放在同目录，方便直接核对与引用。

2. KNN 的 Excel 结果偏重“可复核”
   除 原始数据、预测、指标、参数、图表清单 外，程序还会导出 报告摘要、训练集数据、测试集数据、类别分布、混淆矩阵（表）、分类报告、残差明细、误差统计、指标核对、调参结果、最优参数（调参）、参数与配置、参数与配置（分组） 等工作表。

3. 程序支持轻量调参，不只是固定超参数运行
   当启用调参时，代码会记录网格搜索或轻量搜索结果，并在 Excel 中单独写出调参表与最优参数表，因此论文中若使用调参结果，应写明 K、权重方式、距离度量及评价准则的选择过程。

4. 分类与回归导出结构有公共部分也有专属部分
   分类任务重点输出混淆矩阵、分类报告、ROC/PR、校准与类别分布；
   回归任务重点输出残差明细、误差统计以及预测-真实对比图。

5. 程序保留了指标复算表
   指标核对 会依据 预测 表中的 y_true 与 y_pred 重新计算指标，这对论文附录或审稿复核很有价值，因为它证明最终指标可由逐样本结果反推。

6. KNN 仍可输出模型文件与逐折预测
   代码中支持模型 pkl 导出以及 CV折i_预测 明细，因此若正文需要强调复现性，可以直接写“模型文件、每折预测与参数配置均已保留”。

8. 论文写作模板

方法描述模板：
“本文采用 K 近邻模型进行监督学习分析。首先对原始数据完成缺失处理、编码与标准化，并结合需要实施特征选择或降维。随后设置邻居数 \(K\)、距离度量、权重方式及训练测试划分比例，在训练集上建立 KNN 模型，并在测试集上输出预测结果。若启用交叉验证或轻量调参，则进一步基于多折结果与候选参数组合评估模型稳定性与参数敏感性。”

结果描述模板：
“程序结果文件包含逐样本预测、整体评价指标、调参结果、交叉验证信息、参数配置及图表清单。分类任务还给出混淆矩阵、分类报告、ROC/PR 曲线与类别分布；回归任务提供残差明细与误差统计。由于结果文件中额外给出了指标核对表，研究者可依据逐样本预测结果重新计算核心指标，从而保证论文结果的透明性与可复核性。”

9. 单篇终审补充

9.1 图题与表题对齐建议

• 阅读指南 表可写为：表X KNN 结果文件阅读指南。
• 原始数据 表可写为：表X KNN 原始输入数据表。
• 报告摘要 表可写为：表X KNN 结果摘要表。
• 训练集数据 表可写为：表X KNN 训练集数据表。
• 测试集数据 表可写为：表X KNN 测试集数据表。
• 预测 表可写为：表X KNN 逐样本预测结果表。
• 类别分布 表可写为：表X KNN 类别分布统计表。
• 混淆矩阵（表） 表可写为：表X KNN 混淆矩阵明细表。
• 混淆矩阵 表可写为：表X KNN 混淆矩阵汇总表。
• 分类报告 表可写为：表X KNN 分类报告表。
• 指标 表可写为：表X KNN 分类性能指标表。
• 指标核对 表可写为：表X KNN 指标复核表。
• 图表清单 表可写为：表X KNN 图表索引表。
• 参数与配置 表可写为：表X KNN 参数与配置表。
• 参数与配置（分组） 表可写为：表X KNN 分组参数配置表。
• confusion_matrix.png 建议写为：图X KNN 混淆矩阵图。
• roc.png 建议写为：图X KNN ROC 曲线图。
• pr.png 建议写为：图X KNN PR 曲线图。
• calibration.png 建议写为：图X KNN 校准曲线图。
• class_distribution_triptych.png 建议写为：图X KNN 类别分布图。

9.2 终审说明

• 当前最适合作为终审证据的代表性目录可采用 具体的算法/KNN算法/results/pytest_window1_baseline_knn_20260329_163659。该目录同时具备结果簿、实体图、输入快照和 repro 脚本。
• 真实工作表为 阅读指南/原始数据/报告摘要/训练集数据/测试集数据/预测/类别分布/混淆矩阵（表）/混淆矩阵/分类报告/指标/指标核对/图表清单/参数与配置/参数与配置（分组）。其中 指标核对 是 KNN 这篇很值得在论文附录中强调的复核表。
• 当前真实图文件稳定为 confusion_matrix.png、roc.png、pr.png、calibration.png、class_distribution_triptych.png。论文若说明分类可视化证据，可直接按这组文件对应图义组织图题。
• 当前复现脚本为 repro_knn_20260329_163659.py，采用脚本同目录输入快照 SRC_FILE = 'knn_window1_input.csv'，不是 repro_inputs/... 目录结构。因此该篇应写成“脚本同目录 CSV 快照复现”。
• 与 ui_flow 目录相比，baseline 目录多了 repro_knn_20260329_163659.py 与 knn_window1_input.csv，更适合作为单篇终审的标准证据来源。

9.3 全量强化补充

本篇终审补充绑定的真实算法目录为 具体的算法/KNN算法，本次采用的代表性结果目录为 具体的算法/KNN算法/results/pytest_window1_baseline_knn_20260329_163659。

该目录当前只保留一份主结果工作簿：

• pytest_window1_baseline_knn_20260329_163659.xlsx

实测工作表为：

• 阅读指南
• 原始数据
• 报告摘要
• 训练集数据
• 测试集数据
• 预测
• 类别分布
• 混淆矩阵（表）
• 混淆矩阵
• 分类报告
• 指标
• 指标核对
• 图表清单
• 参数与配置
• 参数与配置（分组）

其中最值得在论文或软件说明中强调的是 预测 与 指标核对 这两张表：前者给出逐样本输出，后者允许按最终结果反推整体指标，因此它比单纯的摘要指标更有复核价值。

当前目录中的真实图文件为：

• 具体的算法/KNN算法/results/pytest_window1_baseline_knn_20260329_163659/confusion_matrix.png
• 具体的算法/KNN算法/results/pytest_window1_baseline_knn_20260329_163659/roc.png
• 具体的算法/KNN算法/results/pytest_window1_baseline_knn_20260329_163659/pr.png
• 具体的算法/KNN算法/results/pytest_window1_baseline_knn_20260329_163659/calibration.png
• 具体的算法/KNN算法/results/pytest_window1_baseline_knn_20260329_163659/class_distribution_triptych.png

因此这一轮真实图证据是分类评估图组，并不包含回归残差图，也不包含降维嵌入图。引用图片时应限定为分类任务场景。

复现实物方面，该目录实际包含：

• 具体的算法/KNN算法/results/pytest_window1_baseline_knn_20260329_163659/repro_knn_20260329_163659.py
• 具体的算法/KNN算法/results/pytest_window1_baseline_knn_20260329_163659/knn_window1_input.csv

脚本中明确写成 SRC_FILE = 'knn_window1_input.csv'，并把 file_path 也写回该同目录 CSV 快照。因此这篇的真实可复现口径不是 repro_inputs/... 子目录，而是“结果目录同级输入快照 + repro 脚本”。

9.4 软件实现核查补充（2026-07）

• 当前源码核查到的实现是 KNN 分类/回归双分支，参数核心是 n_neighbors、weights、algorithm、leaf_size、p、metric，因此文档里的最近邻理论应和界面参数一一对应。
• 代表性结果目录的真实输出以分类评估图组、预测表、指标表和参数配置为主；当前核查口径下不应把它写成回归残差图目录或降维结果目录。
• 复现文件同样采用结果目录同级输入快照加 repro_knn_*.py 的口径，文中若要给出复现说明，应明确输入 CSV 与脚本在同一结果目录下。
• 若正文讨论加权投票、距离度量或投票规则，可以保留为理论补充，但软件解释要落回当前导出的指标、预测与混淆矩阵。