TSVD-截断 SVD

1. 方法概述

截断 SVD（Truncated SVD, TSVD）是在只保留前若干个主导奇异成分的前提下，对原始矩阵进行近似分解的方法。与完整 SVD 相比，它更关注前 \(k\) 个最重要的奇异方向，因此在降维、文本特征压缩和大规模矩阵分析中非常常见。

本项目中的 TSVD-截断 SVD 模块并不是手写 Lanczos 或随机化分解算法，而是对 sklearn.decomposition.TruncatedSVD 的工程化封装。根据当前代码，它具有以下特点：

1. 支持可选 label_col 作为样本名称列；
2. 支持 randomized 与 arpack 两种求解算法；
3. 支持 none、minmax、zscore 三种预处理方式；
4. 输出低维嵌入、成分矩阵、解释方差比与累计解释方差比；
5. 支持自定义累计解释方差阈值，并自动判断是否达到；
6. 输出二维嵌入图和解释方差图。

设共有 \(n\) 个样本、\(p\) 个被选中的特征，记原始特征矩阵为

$$ X=(x_{ij})_{n\times p},\quad i=1,2,\ldots,n,\ j=1,2,\ldots,p \tag{1} $$

若用户指定 label_col，该列仅用于样本名称展示，不参与 TSVD 计算；若未指定，则程序自动生成 样本1, 样本2, \ldots, 样本n 作为样本标识。

2. 数据要求与预处理

2.1 数据约束

根据 upload_widget.py、indicators_widget.py、data_validator.py 与 core/calculator.py 的实现，模块对输入数据的真实要求如下：

1. 数据不能为空；
2. 至少选择 1 个特征列；
3. 被选中的特征列必须存在；
4. 特征列不能含空值或非数值；
5. 特征列不能是常数列；
6. n_components 必须不小于 1；
7. 若 label_col 被同时勾为特征列，程序会直接报错；
8. 当 algorithm="randomized" 时，要求 n_components <= min(n,p)；
9. 当 algorithm="arpack" 时，要求 n_components < min(n,p)。

上传阶段的数据校验只要求存在可用数值列，但真正进入计算阶段时，上述约束会再次被严格检查。

2.2 Min-Max 归一化

当 normalize="minmax" 时，代码按列执行

$$ z_{ij}=\frac{x_{ij}-x_j^{\min}}{x_j^{\max}-x_j^{\min}} \tag{2} $$

若某列极差为 0，则会把分母替换为 1。

2.3 Z-score 标准化

当 normalize="zscore" 时，代码执行

$$ z_{ij}=\frac{x_{ij}-\mu_j}{\sigma_j} \tag{3} $$

其中 \(\sigma_j\) 按 ddof=0 计算；若某列标准差为 0，则同样以 1 替代。

若 normalize="none"，则直接令

$$ z_{ij}=x_{ij} \tag{4} $$

记进入截断 SVD 的矩阵为

$$ Z=(z_{ij})_{n\times p} \tag{5} $$

2.4 符号说明

符号	含义
\(n\)	样本数量
\(p\)	特征维数
\(k\)	保留维数 n_components
\(U_k\)	前 \(k\) 个左奇异向量
\(\Sigma_k\)	前 \(k\) 个奇异值对角矩阵
\(V_k^\top\)	前 \(k\) 个右奇异向量转置
\(T\)	低维嵌入矩阵
\(\rho_i\)	第 \(i\) 个成分的解释方差比
\(R_k\)	前 \(k\) 个成分累计解释方差比

3. 核心数学模型

3.1 截断分解形式

TSVD 的目标是只保留前 \(k\) 个主导奇异成分，将矩阵近似为

$$ Z\approx U_k\Sigma_kV_k^\top \tag{6} $$

其中 \(k\ll \min(n,p)\) 时，可以用较低维表示近似原始矩阵的主要结构。

3.2 低维嵌入

当前项目中，TruncatedSVD.fit_transform() 返回的样本低维表示可理解为

$$ T=ZV_k^\top=U_k\Sigma_k \tag{7} $$

这正对应导出的 Embedding 工作表。

3.3 成分矩阵

项目输出的 Components 表来自模型的 components_ 属性，可写为

$$ V_k^\top= \begin{bmatrix} v_1^\top\\ v_2^\top\\ \vdots\\ v_k^\top \end{bmatrix} \tag{8} $$

其中每一行反映一个截断成分在原始特征空间中的方向载荷。

4. 解释方差与阈值判断

4.1 解释方差比

当前代码直接读取 TruncatedSVD 模型的 explained_variance_ratio_，记为

$$ \rho_i=\texttt{explained\_variance\_ratio\_}[i] \tag{9} $$

并据此构造累计解释方差比

$$ R_k=\sum_{i=1}^{k}\rho_i \tag{10} $$

4.2 奇异值

若模型提供 singular_values_，程序会同步写入结果表。记第 \(i\) 个奇异值为

$$ s_i=\texttt{singular\_values\_}[i] \tag{11} $$

4.3 阈值判断逻辑

当前项目允许用户输入一组累计解释方差阈值，例如 80,90,95 或 0.8,0.9,0.95。代码会把这些值统一规范到 \((0,1]\) 区间，然后对每个阈值 \(\alpha\) 判断：

$$ R_k\ge \alpha\ ? \tag{12} $$

若达到，则进一步记录满足阈值所需的最小维数

$$ k_\alpha=\min\{k:\ R_k\ge \alpha\} \tag{13} $$

若未达到，则在指标表中记为“未达到”。

5. 项目中的参数口径

5.1 algorithm

当前支持：

1. randomized
2. arpack

两者都会直接传给 sklearn.decomposition.TruncatedSVD。

5.2 n_iter

界面中的 n_iter 会直接传入 TruncatedSVD。在随机化算法中，它通常对应幂迭代次数；在 arpack 路线上则主要作为接口参数保留。

5.3 tol

收敛阈值 tol 也会直接传入底层模型。当前界面要求它必须大于 0。

5.4 random_state

界面中“随机种子(0=不固定)”会在代码中转为：

1. 0 -> None

因此输入 0 并不是把随机种子固定为 0，而是表示不显式固定随机状态。

6. 代码实现细节

6.1 ProcessedData 的口径

导出的 ProcessedData 工作表保存的是预处理后的特征矩阵，并在首列保留样本名称列；RawData 则保存上传的原始完整数据表。

6.2 图表生成逻辑

当前模块会生成两张图：

1. embedding_scatter.png
2. explained_variance.png

其中：

1. embedding_scatter.png 只有在 embedding.shape[1] >= 2 时才会生成；
2. explained_variance.png 来自 ExplainedVariance 表中的 解释方差比 列。

6.3 阈值提示弹窗

除了把阈值结果写入 Metrics 表之外，结果页还会在计算完成后弹出提示框，直接告诉用户：

1. 某个解释方差阈值是否已达到；
2. 若已达到，所需的最小维数是多少。

7. 算法流程

结合当前项目代码，TSVD-截断 SVD 的实际执行流程如下：

1. 读取 .xlsx、.xls 或 .csv 文件，并识别可用数值列。
2. 在“特征设置”页选择可选 label_col 与参与降维的特征列。
3. 在“算法参数”页设置 n_components、algorithm、n_iter、tol、normalize、random_state 与 variance_thresholds。
4. 对选中特征执行 none、minmax 或 zscore 预处理。
5. 调用 sklearn.decomposition.TruncatedSVD.fit_transform() 生成低维嵌入。
6. 提取 components_、explained_variance_ratio_ 和 singular_values_。
7. 计算累计解释方差比，并针对用户设定阈值判断是否达到及所需维数。
8. 绘制前两维嵌入散点图与解释方差图。
9. 导出 tsvd_results.xlsx，并保存在 results/TSVD-截断 SVD分析结果_<时间戳>/ 目录下。

8. 关键参数说明

8.1 n_components

目标降维维度。对 randomized 算法要求不超过 min(样本数, 特征数)；对 arpack 算法要求严格小于该上界。

8.2 algorithm

当前支持：

1. randomized
2. arpack

randomized 更适合大矩阵近似分解，arpack 对维数约束更严格。

8.3 n_iter

迭代次数，默认值为 5。增大该值通常有助于随机化分解的稳定性，但也会增加计算时间。

8.4 tol

收敛阈值，默认值为 1e-6。该值越小，通常数值求解要求越严格。

8.5 normalize

当前支持：

1. none
2. minmax
3. zscore

由于 TSVD 直接作用在预处理后的数值矩阵上，不同预处理方式会显著改变解释方差比和嵌入结果。

8.6 variance_thresholds

支持输入百分比形式如 80,90,95，也支持小数形式如 0.8,0.9,0.95。代码会自动去重、排序并统一转换到 0 到 1 之间。

9. 输出结果与导出说明

9.1 Excel 工作表

根据 _export_excel() 的实现，导出的 Excel 文件包含：

1. Parameters
2. RawData
3. ProcessedData
4. Embedding
5. Components
6. ExplainedVariance
7. Metrics
8. Charts

其中：

1. Embedding 保存样本的低维表示；
2. Components 保存成分矩阵；
3. ExplainedVariance 保存每个成分的解释方差比、累计解释方差比和奇异值；
4. Metrics 保存总体累计解释方差比及阈值判断结果。

9.2 结果文件与图表目录

当前结果目录固定形如：

1. results/TSVD-截断 SVD分析结果_<时间戳>/

导出文件名固定为：

1. tsvd_results.xlsx

图表目录位于：

1. plots/embedding_scatter.png
2. plots/explained_variance.png

10. 论文写作建议

10.1 方法描述模板

“本文采用截断奇异值分解（TSVD）方法对高维特征矩阵进行降维。该方法仅保留前若干个主导奇异成分，在尽量保持主要方差信息的同时实现维度压缩。本文进一步结合解释方差比、累计解释方差比及阈值达到情况评估降维效果。”

10.2 结果解释模板

结果部分可写为：Embedding 表反映样本在保留成分上的低维坐标，Components 表反映各截断成分在原始特征上的载荷方向，ExplainedVariance 则可用于判断每个成分的重要性。若研究目标需要达到某个累计解释方差阈值，可直接引用 Metrics 表中的阈值判断结果。

10.3 图表题注模板

• 图 1 TSVD 前两维嵌入散点图。
• 图 2 TSVD 各成分解释方差比曲线。
• 表 1 TSVD 低维嵌入结果。
• 表 2 TSVD 解释方差比及累计解释方差比结果。

11. 实现说明与注意事项

1. 当前模块允许可选 label_col，但该列不能同时作为特征列。
2. arpack 算法对 n_components 的约束比 randomized 更严格。
3. 特征列若包含常数列，程序会直接报错而不是自动剔除。
4. RawData 保存完整原始数据，而 ProcessedData 保存预处理后的建模数据。
5. 若前 \(k\) 个成分的累计解释方差比仍达不到目标阈值，结果表会明确标注“未达到”。

12. 单篇终审补充

12.1 图题与表题对齐建议

当前 TSVD 模块的真实工作簿包含：

• Parameters
• RawData
• ProcessedData
• Embedding
• Components
• ExplainedVariance
• Metrics
• Charts

其中 ExplainedVariance 是这篇文档最适合在论文中重点引用的结果表，因为它同时包含解释方差比、累计解释方差比和奇异值；Metrics 则适合配合写“是否达到阈值”和“达到阈值所需维度”。

图文件保存在结果目录下的 plots/ 子目录，当前实现真实输出：

• embedding_scatter.png
• explained_variance.png

因此图题建议写成“TSVD 前两维嵌入散点图”“TSVD 解释方差比曲线”。不要写成“累计解释方差图”，因为当前图名和导出逻辑对应的是单独的解释方差比曲线；累计结果主要体现在 ExplainedVariance 工作表中。

12.2 终审说明

这篇文档最需要避免的误写，是把它套成完整 SVD 的口径。当前实现直接调用 TruncatedSVD，输出的 Embedding 列名也是 TSVD1、TSVD2 等，而不是完整 SVD 的 \(U\Sigma\) 形式表述。因此正文方法部分应明确这是截断 SVD。

另外，当前 repro 脚本和增强结果目录中已经采用新框架相对路径复现逻辑，结果目录中可见 repro_tsvd_截断_svd.py 和同目录输入副本链路。因此这篇可按新框架写可复现性，但不应把它说成“与 SVD 模块完全同一导出结构”。

12.3 全量强化补充

本次全量强化绑定的真实结果目录为 具体的算法3/聚类与降维/TSVD-截断 SVD/results/TSVD-截断 SVD分析结果_20260322_050946。该目录内主工作簿为 tsvd_results.xlsx，实际工作表为 Parameters、RawData、ProcessedData、Embedding、Components、ExplainedVariance、Metrics、Charts。这与前文终审说明一致，说明当前最佳实物证据应绑定这一轮标准目录，而不是仅引用早期 _enhanced 目录。

图件位于 plots/ 下，真实文件为 embedding_scatter.png 与 explained_variance.png。目录内同时存在 repro_tsvd_截断_svd.py 与 repro_inputs/tsvd_sample.csv。脚本当前真实参数写法为 INPUT_FILE = 'repro_inputs/tsvd_sample.csv'、OUTPUT_FILE = 'tsvd_results.xlsx'，并绑定 n_components = 2、algorithm = 'randomized'、n_iter = 5、tol = 1e-06、normalize = 'zscore'、random_state = 42、variance_thresholds = [0.8, 0.9, 0.95]。

因此 TSVD 当前已经具备“主工作簿 + 图目录 + repro 脚本 + repro_inputs 输入副本”的完整单轮证据链。正文若要强调可复现性，优先应绑定这轮 20260322_050946 目录，因为它比早期多层嵌套的 UIFlow 结果池更适合作为论文和交付说明中的标准样本。

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

• 当前主结果目录应写作 具体的算法3/聚类与降维/TSVD-截断 SVD/results/TSVD-截断 SVD分析结果_20260322_050946。
• 正文应围绕 Parameters、RawData、ProcessedData、Embedding、Components、ExplainedVariance、Metrics、Charts 来写。
• 图证应对应 embedding_scatter.png 与 explained_variance.png，并把截断 SVD 与完整 SVD 区分开。
• 复现脚本应按 repro_tsvd_截断_svd.py + repro_inputs/tsvd_sample.csv 的口径说明。