alterlab-scikit-learn

Scikit-learn

概述

此技能为使用 scikit-learn（业界标准的经典机器学习 Python 库）执行机器学习任务提供全面指导。可将此技能用于分类、回归、聚类、降维、预处理、模型评估，以及构建可用于生产环境的 ML 流水线。

安装

# Install scikit-learn using uv
uv pip install scikit-learn

# Optional: Install visualization dependencies
uv pip install matplotlib seaborn

# Commonly used with
uv pip install pandas numpy

何时使用此技能

在以下情况下使用 scikit-learn 技能：

• 构建分类或回归模型
• 执行聚类或降维
• 对机器学习数据进行预处理和转换
• 通过交叉验证评估模型性能
• 使用网格搜索或随机搜索调整超参数
• 为生产工作流创建 ML 流水线
• 为某项任务比较不同算法
• 处理结构化数据（表格数据）和文本数据
• 需要可解释的经典机器学习方法

不适用的情况

场景	改用
使用后验分布、可信区间或 MCMC 诊断的贝叶斯模型	alterlab-pymc
删失的事件发生时间结果（Cox 模型、生存森林、C-index）	alterlab-scikit-survival
调整 n_neighbors / min_dist 参数的 UMAP 嵌入	alterlab-umap
使用 SHAP 值和图表解释已拟合模型的预测	alterlab-shap
用于推断的系数表、p 值和残差诊断	alterlab-statsmodels

快速入门

最简分类流程：分层 train_test_split → StandardScaler（仅在训练集上拟合）→ 拟合估算器 → classification_report。对于混合数值型和分类型数据，将预处理封装在 Pipeline 中的 ColumnTransformer 里，以便进行交叉验证而不发生数据泄漏。

完整的分类和混合数据流水线复制粘贴示例，请参见 references/worked_examples.md。

核心功能

1. 监督学习

提供全面的算法，用于分类和回归任务。

主要算法：

• 线性模型：Logistic Regression、Linear Regression、Ridge、Lasso、ElasticNet
• 树模型：Decision Trees、Random Forest、Gradient Boosting
• 支持向量机：SVC、SVR，支持多种核函数
• 集成方法：AdaBoost、Voting、Stacking
• 神经网络：MLPClassifier、MLPRegressor
• 其他：Naive Bayes、K-Nearest Neighbors

适用场景：

• 分类：预测离散类别（垃圾邮件检测、图像分类、欺诈检测）
• 回归：预测连续值（价格预测、需求预测）

参见： references/supervised_learning.md，了解详细的算法文档、参数和用法示例。

2. 无监督学习

通过聚类和降维，从无标签数据中发现模式。

聚类算法：

• 基于划分：K-Means、MiniBatchKMeans
• 基于密度：DBSCAN、HDBSCAN、OPTICS
• 层次聚类：AgglomerativeClustering
• 概率模型：Gaussian Mixture Models
• 其他：MeanShift、SpectralClustering、BIRCH

降维方法：

• 线性方法：PCA、TruncatedSVD、NMF
• 流形学习：t-SNE、UMAP、Isomap、LLE
• 特征提取：FastICA、LatentDirichletAllocation

适用场景：

• 客户细分、异常检测、数据可视化
• 减少特征维度、探索性数据分析
• 主题建模、图像压缩

参见： references/unsupervised_learning.md，了解详细文档。

3. 模型评估与选择

用于稳健的模型评估、交叉验证和超参数调优的工具。

交叉验证策略：

• KFold、StratifiedKFold（分类）
• TimeSeriesSplit（时间序列数据）
• GroupKFold（分组样本）

超参数调优：

• GridSearchCV（穷举搜索）
• RandomizedSearchCV（随机采样）
• HalvingGridSearchCV（逐次减半）

指标：

• 分类：准确率、精确率、召回率、F1 分数、ROC AUC、混淆矩阵
• 回归：MSE、RMSE、MAE、R²、MAPE
• 聚类：轮廓系数、Calinski-Harabasz、Davies-Bouldin

适用场景：

• 客观比较模型性能
• 找到最优超参数
• 通过交叉验证防止过拟合
• 通过学习曲线了解模型行为

参见： references/model_evaluation.md，了解全面的指标和调优策略。

4. 数据预处理

将原始数据转换为适用于机器学习的格式。

缩放与归一化：

• StandardScaler（零均值、单位方差）
• MinMaxScaler（限定范围）
• RobustScaler（对异常值具有稳健性）
• Normalizer（按样本归一化）

对分类变量进行编码：

• OneHotEncoder（名义类别）
• OrdinalEncoder（有序类别）
• LabelEncoder（对目标标签 y 编码，而非特征）
• TargetEncoder（通过交叉拟合的目标均值，对高基数分类特征进行编码）

处理缺失值：

• SimpleImputer（均值、中位数、最常见值）
• KNNImputer（K 近邻）
• IterativeImputer（多变量插补）

特征工程：

• PolynomialFeatures（交互项）
• KBinsDiscretizer（分箱）
• 特征选择（RFE、SelectKBest、SelectFromModel）

适用场景：

• 在训练任何需要缩放特征的算法（SVM、KNN、神经网络）之前
• 将分类变量转换为数值格式
• 系统地处理缺失数据
• 为线性模型创建非线性特征

参见： references/preprocessing.md，了解详细的预处理技术。

5. 管道与组合

构建可复现、可用于生产环境的机器学习工作流。

关键组件：

• Pipeline：按顺序串联转换器和估算器
• ColumnTransformer：对不同列应用不同的预处理方式
• FeatureUnion：并行组合多个转换器
• TransformedTargetRegressor：转换目标变量

优点：

• 防止交叉验证中的数据泄漏
• 简化代码并提高可维护性
• 支持联合调优超参数
• 确保训练与预测之间的一致性

适用场景：

• 生产工作流中始终使用 Pipelines
• 混合数值特征和分类特征时（使用 ColumnTransformer）
• 使用预处理步骤执行交叉验证时
• 超参数调优包含预处理参数时

参见： references/pipelines_and_composition.md，了解全面的管道模式。

示例脚本

此技能附带两个可运行的端到端脚本：

python scripts/classification_pipeline.py   # mixed-data preprocessing, model comparison, GridSearchCV, evaluation, feature importance
python scripts/clustering_analysis.py        # optimal-k search, K-Means/DBSCAN/Agglomerative/GMM comparison, PCA visualization

参见 references/worked_examples.md，了解每个脚本演示的内容以及可独立复制粘贴的版本。

参考文档

此技能包含全面的参考文件，深入介绍特定主题：

快速参考

文件： references/quick_reference.md

• 常见导入模式和安装说明
• 常见任务的快速工作流模板
• 算法选择速查表
• 常见模式和注意事项
• 性能优化技巧

监督学习

文件： references/supervised_learning.md

• 线性模型（回归和分类）
• 支持向量机
• 决策树和集成方法
• K 近邻、朴素贝叶斯、神经网络
• 算法选择指南

无监督学习

文件： references/unsupervised_learning.md

• 各类聚类算法及其参数和适用场景
• 降维技术
• 离群点和新颖性检测
• 高斯混合模型
• 方法选择指南

模型评估

文件： references/model_evaluation.md

• 交叉验证策略
• 超参数调优方法
• 分类、回归和聚类指标
• 学习曲线和验证曲线
• 模型选择最佳实践

预处理

文件： references/preprocessing.md

• 特征缩放和归一化
• 类别变量编码
• 缺失值填补
• 特征工程技术
• 自定义转换器

管道与组合

文件： references/pipelines_and_composition.md

• 管道的构建和使用
• 用于混合数据类型的 ColumnTransformer
• 用于并行转换的 FeatureUnion
• 完整的端到端示例
• 最佳实践

操作示例

文件： references/worked_examples.md

• 快速入门分类和混合数据管道代码片段
• 分类模型工作流分步说明
• 聚类分析工作流分步说明
• 每个捆绑示例脚本的演示内容

最佳实践与故障排查

文件： references/best_practices_and_troubleshooting.md

• 管道和数据泄漏规范、仅在训练集上拟合、分层拆分
• 随机状态可复现性、指标选择、何时缩放特征
• 解决 ConvergenceWarning、过拟合和大型数据集内存错误的方法

常见工作流

• 分类模型： 加载数据 → 分层 train_test_split → 在 Pipeline 中使用 ColumnTransformer 进行预处理 → 使用 GridSearchCV 调优 → 在留出的测试集上运行 classification_report。
• 聚类分析： StandardScaler → 遍历不同的 k 值计算轮廓系数，以选择 optimal_k → 拟合 KMeans → 使用 PCA(n_components=2) 投影以进行可视化。

参见 references/worked_examples.md，了解每个工作流的编号版、可直接复制粘贴的步骤。

版本说明（scikit-learn 1.8–1.9）

• LogisticRegression(penalty=...) 已弃用（将在 1.10 中移除）：请使用 l1_ratio（0 = L2，1 = L1，中间值 = 弹性网络），并使用 C=np.inf 表示不加惩罚。
• SVC(probability=True) 已弃用（将在 1.11 中移除）：需要概率时，请将模型包装为 CalibratedClassifierCV(SVC(), ensemble=False)。
• MDS(metric=True/False) 已改为 metric_mds=；除非显式设置 copy，否则 HDBSCAN 会发出警告。
• mean_squared_error(..., squared=False) 已移除；请使用 root_mean_squared_error。

最佳实践（要点）

• 始终在 Pipeline 内进行预处理（以防止数据泄漏）；仅在训练集上拟合，对测试集执行 transform。
• 分类拆分时使用 stratify=y；在所有地方设置 random_state，以确保结果可复现。
• 对 SVM/KNN/NN/PCA/正则化线性模型/K-Means 的特征进行缩放；树模型和朴素贝叶斯则不需要。
• 根据问题选择指标：均衡数据使用 F1/准确率；不均衡数据使用精确率/召回率/ROC AUC/平衡准确率。

参见 references/best_practices_and_troubleshooting.md，查看代码示例，以及解决 ConvergenceWarning、过拟合和大型数据集内存错误的方法。

其他资源

• 官方文档：https://scikit-learn.org/stable/
• 用户指南：https://scikit-learn.org/stable/user_guide.html
• API 参考：https://scikit-learn.org/stable/api/index.html
• 示例集：https://scikit-learn.org/stable/auto_examples/index.html