causal-sklearn 0.1.0

Scikit-learn compatible implementation of CausalEngine for causal machine learning

Causal-Sklearn - 基于CausalEngine™核心的因果回归和分类

基于突破性CausalEngine™算法的scikit-learn兼容实现 - 将因果推理带入传统机器学习生态系统。

核心概念

传统机器学习: 从可观测个体特征到结果的映射(from observable individual fetures to outcome)

• 回归: X → Y (数值结果)
• 分类: X → Y (类别结果)

因果机器学习: 从不可观测个体因果表示到结果的推理(from unobservable individual causal representation to outcome)

• 因果回归: U → Y (数值结果)
• 因果分类: U → Y (类别结果)

数学本质: CausalEngine 学习结构方程 Y = f(U, ε) 而非学习条件期望 E[Y|X].

项目概述

Causal-Sklearn将强大的因果推理能力引入到熟悉的scikit-learn生态系统中。基于革命性的CausalEngine™算法构建，它提供了传统ML估计器的直接替代品，能够理解因果关系而不仅仅是相关性。

🎯 核心突破

• 因果vs相关: 超越传统模式匹配，实现真正的因果关系理解
• 鲁棒性优势: 在噪声和异常值存在时表现出色，远超传统方法
• 数学创新: 以柯西分布为核心的全新数学框架
• sklearn兼容: 完美融入现有ML工作流，无需改变使用习惯

🌟 核心特性

• 🔧 Scikit-learn兼容: 完全兼容sklearn接口，可直接替换MLPRegressor和MLPClassifier
• 🧠 因果推理: 超越模式匹配，理解数据背后的因果关系
• 🛡️ 鲁棒性卓越: 在标签噪声和异常值环境下性能远超传统方法
• 📊 分布预测: 提供完整的分布输出，而非仅点估计
• ⚙️ 多模式推理: 支持deterministic、standard、sampling等多种推理模式
• 🎯 真实世界验证: 在加州房价等真实数据集上展现显著优势

📊 实验结果亮点

我们在 quick_test_causal_engine.py 脚本中进行了严格的基准测试。结果明确展示了 CausalEngine 的 standard 模式在含噪数据下的卓越性能，而 deterministic 模式作为因果模型的基线，其表现与传统MLP相似。

回归任务 (30% 标签噪声)

在回归任务中，CausalEngine 的 standard 模式展现出压倒性优势，各项误差指标均远优于传统方法。

方法	MAE (↓)	MdAE (↓)	RMSE (↓)	R² (↑)
sklearn	47.60	39.28	59.87	0.8972
pytorch	59.70	47.25	77.36	0.8284
Causal (deterministic)	58.55	45.20	78.12	0.8249
Causal (standard)	11.41	10.22	13.65	0.9947

standard 模式通过其独特的因果推理机制，在噪声环境下实现了性能的飞跃，证明了其卓越的鲁棒性。

分类任务 (30% 标签噪声)

在3分类任务中，CausalClassifier (standard) 模式在所有关键指标上均达到最佳表现，显著优于所有基线模型。

方法	Accuracy (↑)	Precision (↑)	Recall (↑)	F1-Score (↑)
sklearn	0.8850	0.8847	0.8850	0.8848
pytorch	0.8950	0.8952	0.8950	0.8951
sklearn_ovr	0.8975	0.8987	0.8974	0.8974
Causal (deterministic)	0.8888	0.8935	0.8890	0.8884
Causal (standard)	0.9225	0.9224	0.9225	0.9224

这再次证明了 CausalEngine 的 standard 模式不仅在回归中表现优异，在分类任务中同样具有处理标签噪声的领先优势。

安装

通过 PyPI 安装（推荐）

pip install causal-sklearn

从源代码安装

# 克隆仓库
git clone https://github.com/1587causalai/causal-sklearn.git
cd causal-sklearn

# 安装依赖并安装包
pip install -e .

系统要求

• Python: >= 3.8
• 核心依赖:
  • numpy >= 1.21.0
  • scipy >= 1.7.0
  • scikit-learn >= 1.0.0
  • torch >= 1.10.0
  • pandas >= 1.3.0

验证安装

import causal_sklearn
print(f"Causal-sklearn version: {causal_sklearn.__version__}")
print("安装成功！🎉")

快速开始

基础使用示例

from causal_sklearn import MLPCausalRegressor, MLPCausalClassifier
from sklearn.datasets import make_regression, make_classification
from sklearn.model_selection import train_test_split

# 回归示例
X, y = make_regression(n_samples=1000, n_features=20, noise=0.1)
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2)

regressor = MLPCausalRegressor(mode='standard', random_state=42)
regressor.fit(X_train, y_train)
predictions = regressor.predict(X_test)
distributions = regressor.predict_dist(X_test) # 返回完整的Cauchy分布参数

# 分类示例
X, y = make_classification(n_samples=1000, n_features=20, n_classes=3)
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2)

classifier = MLPCausalClassifier(mode='standard', random_state=42)
classifier.fit(X_train, y_train)
predictions = classifier.predict(X_test)
probabilities = classifier.predict_proba(X_test)

🚀 快速验证测试

运行快速测试脚本，同时验证回归和分类性能：

# 运行完整的快速测试（回归+分类）
python scripts/quick_test_causal_engine.py

# 这个脚本将：
# 1. 生成合成数据（回归：4000样本×12特征，分类：4000样本×10特征×3类）
# 2. 在30%噪声下比较8种方法性能
# 3. 统一标准化策略确保公平比较
# 4. 生成完整的性能分析报告和可视化图表

快速测试亮点：

• ⚡ 快速验证：几分钟内完成全面测试
• 🔄 双任务支持：同时测试回归和分类能力
• 🎯 8种方法对比：sklearn/PyTorch基线 + CausalEngine四种模式
• 📊 科学实验设计：无数据泄露的标准化策略
• 🛡️ 噪声鲁棒性：在30%噪声环境下验证优势

🏠 真实世界教程 - 加州房价预测

运行完整的真实世界回归教程，展示CausalEngine的强大性能：

# 运行真实世界回归教程（sklearn-style版本）
python examples/comprehensive_causal_modes_tutorial_sklearn_style.py

# 这个教程将：
# 1. 加载加州房价数据集（20,640个样本）
# 2. 在30%标签噪声下比较13种方法
# 3. 测试CausalEngine所有4种推理模式
# 4. 生成标准版和扩展版性能对比图表

真实世界教程亮点：

• 🌍 真实数据：加州房价数据集的完整分析
• 🔬 全面对比：13种方法（传统ML + 稳健回归 + CausalEngine四模式）
• 📊 双重可视化：标准版（9种核心方法）+ 扩展版（13种全方法）
• 🎯 CausalEngine专项：四种推理模式的深度对比分析
• 🛡️ 鲁棒性验证：在30%噪声环境下的真实表现

📈 鲁棒性测试脚本

测试算法在不同噪声水平下的鲁棒性表现：

# 回归算法鲁棒性测试（真实数据集）
python scripts/regression_robustness_real_datasets.py

# 分类算法鲁棒性测试（真实数据集）
python scripts/classification_robustness_real_datasets.py

# 这些脚本将：
# 1. 使用sklearn内置真实数据集
# 2. 测试0%-100%噪声梯度（11个级别）
# 3. 比较多种算法的鲁棒性曲线
# 4. 支持多次运行取平均，提高结果稳定性

📚 文档与理论基础

🧮 数学理论基础

• 🌟 数学基础 (中文) - 最核心文档 完整的CausalEngine理论框架
• One-Pager Summary - Executive summary of CausalEngine

📄 许可证

本项目采用Apache License 2.0 - 详见LICENSE文件。

📖 学术引用

如果您在研究中使用了Causal-Sklearn，请引用：

@software{causal_sklearn,
  title={Causal-Sklearn: Scikit-learn Compatible Causal Regression and Classification},
  author={Heyang Gong},
  year={2025},
  url={https://github.com/1587causalai/causal-sklearn},
  note={基于CausalEngine™核心的因果回归和因果分类算法的scikit-learn兼容实现}
}

---

🌟 CausalEngine™ - 基于归因行动框架的因果推理引擎 🌟

从相关性到因果性，从模式匹配到因果理解