TextClassification-通用文本分类

1. 方法概述

TextClassification-通用文本分类 的真实实现位于 core/calculator.py。它不是单一模型，而是一个传统机器学习文本分类统一接口，支持：

• svm：LinearSVC
• lr：LogisticRegression
• nb：MultinomialNB

设数据集为

$$ \mathcal{D}=\{(s_i,y_i)\}_{i=1}^{N} \tag{1} $$

其中 \(s_i\) 为文本，\(y_i\) 为类别标签。模块会先清洗文本与标签，再做向量化、训练、评估和 Excel/图表导出。

2. 数据清洗与切分

2.1 清洗逻辑

_prepare_data() 会先校验 text_column、label_column 和可选 id_column 是否存在，然后：

• 删除文本或标签缺失的样本；
• 对文本和标签做 strip()；
• 删除空白文本与空白标签。

记清洗后的文本为

$$ \tilde{s}_i=\mathrm{Clean}(s_i) \tag{2} $$

若用户没有提供样本 ID 列，代码会自动新增：

$$ \mathrm{id}_i=\texttt{row\_}i \tag{3} $$

因此训练阶段一定有可追踪的样本标识。

2.2 标签编码与训练/测试划分

标签先通过 LabelEncoder 编成整数：

$$ \tilde{y}_i=\mathrm{LE}(y_i) \tag{4} $$

随后调用 train_test_split() 做随机划分：

$$ \mathcal{D}_{\mathrm{train}}\cup \mathcal{D}_{\mathrm{test}}=\mathcal{D}',\qquad |\mathcal{D}_{\mathrm{test}}|\approx r|\mathcal{D}'| \tag{5} $$

其中 \(r=\text{test\_size}\)。若 stratify=True 且每类样本数不少于 2，则优先分层抽样；若分层失败，则自动回退为普通随机切分，并在 切分信息 中记录 stratify_note。

这说明该模块不是按时间顺序切分，而是经典监督学习随机评估流程。

3. 文本表示

3.1 Count 与 TF-IDF

模块支持两种向量化方式：

• vectorizer="count"
• vectorizer="tfidf"

若使用词袋表示，则

$$ x_{iv}=c(v,\tilde{s}_i) \tag{6} $$

若使用 TF-IDF，则

$$ x_{iv}=\mathrm{tf}_{iv}\cdot \log\frac{N}{\mathrm{df}_v} \tag{7} $$

其中 \(\mathrm{df}_v\) 为词项 \(v\) 的文档频数。

3.2 analyzer 与词表参数

真实可调参数包括：

• analyzer：word 或 char
• ngram_min
• ngram_max
• max_features
• min_df
• max_df
• stop_words
• lowercase

其中：

$$ \mathrm{ngram\_range}=(n_{\min},n_{\max}) \tag{8} $$

从 UI 默认值可以看出，该模块默认更偏向中文字符级建模：analyzer="char"，ngram_range=(2,4)。这与 README 中“中文推荐字符 n-gram”的说明是一致的。

4. 分类模型

4.1 LinearSVC 与 LogisticRegression

当模型为 svm 或 lr 时，代码走线性判别路径。可抽象写成

$$ z_c(x)=w_c^\top x+b_c \tag{9} $$

最终预测类别为

$$ \hat{y}=\arg\max_c z_c(x) \tag{10} $$

其中：

• svm 对应 LinearSVC
• lr 对应 LogisticRegression

lr 在二分类时使用 liblinear，多分类时使用 lbfgs。class_weight 只支持 None 或 balanced。

4.2 MultinomialNB

当模型为 nb 时，代码调用 MultinomialNB(alpha=...)。其条件分布可以理解为

$$ P(x\mid y=c)\propto \prod_{v=1}^{V}\theta_{cv}^{\,x_v} \tag{11} $$

其中 \(\alpha\) 是平滑参数，对应界面中的 alpha。

4.3 二分类得分

若是二分类，程序会尝试提取正类得分：

$$ \mathrm{score}_{+}(x)= \begin{cases} P(y=1\mid x), & \text{if predict\_proba exists} \\ f(x), & \text{if decision\_function exists} \end{cases} \tag{12} $$

这意味着：

• LogisticRegression 和 MultinomialNB 更可能给出概率；
• LinearSVC 给出的通常是决策间隔而不是概率。

该得分会写入 预测明细 工作表中的 score_proba_pos 或 score_decision_pos 列。

5. 评价指标与结果表

5.1 分类指标

测试集准确率定义为

$$ \mathrm{Accuracy}=\frac{1}{|\mathcal{D}_{\mathrm{test}}|}\sum_i \mathbf{1}(\hat{y}_i=y_i) \tag{13} $$

代码还会输出：

• precision_macro
• recall_macro
• f1_macro
• f1_weighted

混淆矩阵为

$$ \mathrm{CM}_{ab}=\sum_i \mathbf{1}(y_i=a,\hat{y}_i=b) \tag{14} $$

5.2 ROC / PR

只有二分类且存在可用 score 时，模块才计算 ROC-AUC 与 PR-AUC：

$$ \mathrm{ROC\text{-}AUC}=\int_0^1 \mathrm{TPR}(\mathrm{FPR}^{-1}(u))\,du \tag{15} $$

$$ \mathrm{PR\text{-}AUC}=\int_0^1 \mathrm{Precision}(r)\,dr \tag{16} $$

并额外生成：

• ROC曲线数据
• PR曲线数据
• roc_curve.png
• pr_curve.png

多分类场景下不会生成这些 ROC/PR 明细。

5.3 预测明细

预测明细 工作表只包含测试集样本，而不是全量样本。代码会回填：

• y_true_label
• y_pred_label
• is_correct
• text_preview

其中 text_preview 最多保留前 200 个字符，便于结果页快速预览误分类样本。

5.4 词表统计与 Top 特征

词表统计 由向量化器导出，包括：

• term
• doc_freq
• term_sum
• idf（TF-IDF 时）

其中词表频次统计来自训练集与测试集拼接后的稀疏矩阵。

Top 特征分两种情况：

1. 若模型有 coef_，则对每个类别提取正向和负向高权重词项：

$$ \mathrm{TopTerms}(c)=\operatorname{argsort}_j(w_{cj}) \tag{17} $$

1. 若模型有 feature_log_prob_，则输出朴素贝叶斯下的高条件对数概率词项。

这意味着：

• svm/lr 会输出 direction=positive/negative 风格的特征表；
• nb 会输出 log_prob 风格的特征表。

6. 输出结果与复现

6.1 Excel 工作表

_write_excel() 的真实输出为：

• 参数
• 原始数据
• 清洗后数据
• 数据概览
• 切分信息
• 指标汇总
• 分类报告
• 混淆矩阵
• 预测明细
• ROC曲线数据（二分类时）
• PR曲线数据（二分类时）
• 词表统计
• Top特征
• 图表清单

这里有一个重要实现细节：内存中的 raw_data 和 processed_data 在 get_results() 里是预览字典 shape/columns/head，不是完整 DataFrame；但写入 Excel 时，原始数据 和 清洗后数据 仍然是完整表格。

6.2 图表

代码稳定尝试导出的图表包括：

• class_distribution.png
• confusion_matrix.png
• roc_curve.png（二分类时）
• pr_curve.png（二分类时）

其中 class_distribution.png 基于清洗后的全量真实标签统计，而不是预测标签分布。

6.3 复现脚本

这个模块的复现导出比较特别：_write_repro_script() 不仅会复制原始输入到 repro_inputs/，还会把当前 core/calculator.py 与 core/__init__.py 复制到结果目录下的

repro_module/core/

然后生成 repro_text_classification_时间戳.py。这样做的目的是提升复现脚本的可移植性，避免结果目录脱离主工程后无法导入 Calculator。

7. 实现说明与注意事项

结合真实代码，这个模块可以概括为：一个面向论文与报告导出的传统文本分类总接口，核心是

• Count/TF-IDF
• LinearSVC
• LogisticRegression
• MultinomialNB

它的优点是：

• 参数暴露完整；
• Excel 与图表导出很细；
• 复现脚本可独立携带核心模块。

但边界同样明确：

• 不使用预训练语言模型；
• 没有深度上下文表示；
• 评估依赖单次随机切分；
• ROC/PR 仅覆盖二分类场景。

因此，这个实现更适合做经典文本分类基线、教学演示和论文中的传统模型对照实验。

8. 论文写作模板

可在论文“方法部分”中写为：

“本文采用通用文本分类框架对文本样本进行监督学习建模。首先，对原始文本进行清洗、分词和向量化表示，并构造训练集与评估集；其次，根据实验设置选择相应的文本表示方法和分类器，对文本类别进行建模；随后，在评估样本上输出预测标签、分类概率及相关评价指标；最后，结合结果表、图表和复现输出，对文本分类性能及模型稳定性进行分析。”

9. 单篇终审补充

9.1 图题与表题对齐建议

• 参数 表可写为：表X 通用文本分类参数设置表。
• 原始数据 表可写为：表X 通用文本分类原始数据表。
• 清洗后数据 表可写为：表X 通用文本分类清洗后数据表。
• 数据概览 表可写为：表X 通用文本分类数据概览表。
• 切分信息 表可写为：表X 通用文本分类数据切分信息表。
• 指标汇总 表可写为：表X 通用文本分类指标汇总表。
• 分类报告 表可写为：表X 通用文本分类分类报告表。
• 混淆矩阵 表可写为：表X 通用文本分类混淆矩阵表。
• 预测明细 表可写为：表X 通用文本分类预测明细表。
• ROC曲线数据 表可写为：表X 通用文本分类 ROC 曲线数据表。
• PR曲线数据 表可写为：表X 通用文本分类 PR 曲线数据表。
• 词表统计 表可写为：表X 通用文本分类词表统计表。
• Top特征 表可写为：表X 通用文本分类 Top 特征表。
• 图表清单 表可写为：表X 通用文本分类图表清单与路径表。
• class_distribution.png 建议写为：图X 通用文本分类类别分布图。
• confusion_matrix.png 建议写为：图X 通用文本分类混淆矩阵图。
• pr_curve.png 建议写为：图X 通用文本分类 PR 曲线图。
• roc_curve.png 建议写为：图X 通用文本分类 ROC 曲线图。

9.2 终审说明

• 当前代表性结果目录可采用 results/pytest_exportcheck_text_classification_20260316_061210/baseline_a_20260316_061210。其中主工作簿为 baseline_a_20260316_061210.xlsx，复现输出位于 repro_text_classification_20260316_061210/repro_text_classification_20260316_061210.xlsx。
• 当前真实工作表为 参数/原始数据/清洗后数据/数据概览/切分信息/指标汇总/分类报告/混淆矩阵/预测明细/ROC曲线数据/PR曲线数据/词表统计/Top特征/图表清单。论文表题应按这组中文口径落地，尤其不要把 图表清单 擅自改成“附图目录”后又丢失路径信息。
• 当前稳定图文件为 charts/class_distribution.png、charts/confusion_matrix.png、charts/pr_curve.png、charts/roc_curve.png。其中 class_distribution.png 基于清洗后的真实标签统计，不是预测标签分布。
• 真实 repro 脚本为 repro_text_classification_20260316_061210.py，并通过 SRC_FILE = SCRIPT_DIR / 'repro_inputs' / 'text_classification_repro_input.csv' 读取输入副本。复现目录中还会额外携带 repro_module/core/，正文若描述可移植复现，应把这一点写清。
• 当前目录下同时存在 baseline_a 和 baseline_b 两组结果，它们工作表结构一致但参数和输出文件名不同。论文正文引用时必须固定到其中一组，不宜混合摘取两组结果。

9.3 全量强化补充

• 本轮按真实磁盘再次核对，算法目录为 具体的算法3/NLP基础/TextClassification-通用文本分类。考虑到用户实跑证据更重要，代表性目录调整为 具体的算法3/NLP基础/TextClassification-通用文本分类/results/text_classification_manual_run_20260323_192215/text_classification_manual_20260323_192215。
• 该目录主工作簿为 text_classification_manual_20260323_192215.xlsx，真实工作表为 参数、原始数据、清洗后数据、数据概览、切分信息、指标汇总、分类报告、混淆矩阵、预测明细、词表统计、Top特征、图表清单。当前这次手动运行目录中未见 ROC曲线数据 与 PR曲线数据 工作表，因此正文不应沿用 baseline 目录那套更完整的工作表口径。
• 当前主图目录为 charts/，实际只有 class_distribution.png 与 confusion_matrix.png 两张图；手动运行目录中未见 roc_curve.png 与 pr_curve.png。因此这篇必须按“具体目录具体图证”写，不能把 smoke 目录里的 ROC/PR 图默认写到这次手动目录中。
• 当前 repro 脚本为 repro_text_classification_20260323_192215.py，并通过 SRC_FILE = SCRIPT_DIR / 'repro_inputs' / 'text_classification_sample.csv' 读取输入副本。目录中同时携带 repro_module/core/ 作为最小复现模块副本。
• 当前目录下还嵌套了 repro_text_classification_20260323_192215/ 及更深层递归复现目录，里面继续生成新的工作簿、图目录和 repro_inputs。因此这篇应明确写成“手动运行目录 + 递归复现目录”结构，而不是简单的单层主/复现并列。
• 若论文需要完整展示 ROC/PR，应另固定引用 pytest_exportcheck_text_classification_20260316_061210/baseline_a_20260316_061210 之类的目录；若强调用户实跑链路，则应优先采用当前手动目录，并接受其当前只有类别分布图和混淆矩阵图的事实。

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

• 当前实现应按具体目录分别写证据链，代表性目录可采用 具体的算法3/NLP基础/TextClassification-通用文本分类/results/text_classification_manual_run_20260323_192215/text_classification_manual_20260323_192215 或 具体的算法3/NLP基础/TextClassification-通用文本分类/results/pytest_exportcheck_text_classification_20260316_061210/baseline_a_20260316_061210。
• 正文应围绕 参数、原始数据、清洗后数据、数据概览、切分信息、指标汇总、分类报告、混淆矩阵、预测明细、词表统计、Top特征、图表清单 来写。
• 图证要按具体目录落地，手动目录可能只有 class_distribution.png 与 confusion_matrix.png，而 baseline 目录可能还包含 roc_curve.png 和 pr_curve.png。
• repro_text_classification_*.py + repro_inputs/... 这一复现链应按具体目录写，不要把 baseline 与手动目录混成单层结构。