{"id":30306306,"url":"https://github.com/1587causalai/causal-sklearn","last_synced_at":"2025-08-17T09:05:18.722Z","repository":{"id":303014385,"uuid":"1014136279","full_name":"1587causalai/causal-sklearn","owner":"1587causalai","description":"Scikit-learn Compatible Causal Machine Learning Library - Based on CausalEngine™","archived":false,"fork":false,"pushed_at":"2025-08-17T04:17:49.000Z","size":7696,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-17T06:13:16.022Z","etag":null,"topics":["cauchy-distribution","causal-inference","causal-machine-learning","machine-learning","python","pytorch","scikit-learn"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/1587causalai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-05T05:55:16.000Z","updated_at":"2025-08-17T04:17:53.000Z","dependencies_parsed_at":"2025-07-05T07:25:23.626Z","dependency_job_id":"afaeebef-3b68-4568-a434-851af956b82d","html_url":"https://github.com/1587causalai/causal-sklearn","commit_stats":null,"previous_names":["1587causalai/causal-sklearn"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/1587causalai/causal-sklearn","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1587causalai%2Fcausal-sklearn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1587causalai%2Fcausal-sklearn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1587causalai%2Fcausal-sklearn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1587causalai%2Fcausal-sklearn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/1587causalai","download_url":"https://codeload.github.com/1587causalai/causal-sklearn/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1587causalai%2Fcausal-sklearn/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270815031,"owners_count":24650674,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-17T02:00:09.016Z","response_time":129,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cauchy-distribution","causal-inference","causal-machine-learning","machine-learning","python","pytorch","scikit-learn"],"created_at":"2025-08-17T09:02:40.058Z","updated_at":"2025-08-17T09:05:18.675Z","avatar_url":"https://github.com/1587causalai.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Causal-Sklearn - 基于CausalEngine™核心的因果回归和分类\n\n基于突破性CausalEngine™算法的scikit-learn兼容实现 - 将因果推理带入传统机器学习生态系统。\n\n- Causal Regression 是基于因果关系的回归预测，是没有treatment的因果推断。\n- 回归将从误差最小化， 而因果回归是极大思然\n\n\n## 核心概念\n\n**传统机器学习**: 从可观测个体特征到结果的映射(from observable individual fetures to outcome)\n- 回归: X → Y (数值结果)  \n- 分类: X → Y (类别结果)\n\n**因果机器学习**: 从不可观测个体因果表示到结果的推理(from unobservable individual causal representation to outcome)\n- 因果回归: U → Y (数值结果)\n- 因果分类: U → Y (类别结果)\n\n数学本质: CausalEngine 学习结构方程 **Y = f(U, ε)** 而非学习条件期望 **E[Y|X]**. \n\n## 项目概述\n\nCausal-Sklearn将强大的因果推理能力引入到熟悉的scikit-learn生态系统中。基于革命性的CausalEngine™算法构建，它提供了传统ML估计器的直接替代品，能够理解因果关系而不仅仅是相关性。\n\n### 🎯 核心突破\n- **因果vs相关**: 超越传统模式匹配，实现真正的因果关系理解\n- **鲁棒性优势**: 在噪声和异常值存在时表现出色，远超传统方法\n- **数学创新**: 以柯西分布为核心的全新数学框架\n- **sklearn兼容**: 完美融入现有ML工作流，无需改变使用习惯\n\n## 🌟 核心特性\n\n- **🔧 Scikit-learn兼容**: 完全兼容sklearn接口，可直接替换`MLPRegressor`和`MLPClassifier`\n- **🧠 因果推理**: 超越模式匹配，理解数据背后的因果关系\n- **🛡️ 鲁棒性卓越**: 在标签噪声和异常值环境下性能远超传统方法\n- **📊 分布预测**: 提供完整的分布输出，而非仅点估计\n- **⚙️ 多模式推理**: 支持deterministic、standard、sampling等多种推理模式\n- **🎯 真实世界验证**: 在加州房价等真实数据集上展现显著优势\n\n## 📊 实验结果亮点\n\n我们在 `quick_test_causal_engine.py` 脚本中进行了严格的基准测试。结果明确展示了 CausalEngine 的 `standard` 模式在含噪数据下的卓越性能，而 `deterministic` 模式作为因果模型的基线，其表现与传统MLP相似。\n\n### 回归任务 (30% 标签噪声)\n\n在回归任务中，CausalEngine 的 `standard` 模式展现出压倒性优势，各项误差指标均远优于传统方法。\n\n| 方法                       | MAE (↓) | MdAE (↓) | RMSE (↓) | R² (↑) |\n| :------------------------- | :------ | :------- | :------- | :----- |\n| sklearn                    | 47.60   | 39.28    | 59.87    | 0.8972 |\n| pytorch                    | 59.70   | 47.25    | 77.36    | 0.8284 |\n| Causal (deterministic)     | 58.55   | 45.20    | 78.12    | 0.8249 |\n| **Causal (standard)**      | **11.41** | **10.22** | **13.65** | **0.9947** |\n\n*`standard` 模式通过其独特的因果推理机制，在噪声环境下实现了性能的飞跃，证明了其卓越的鲁棒性。*\n\n### 分类任务 (30% 标签噪声)\n\n在3分类任务中，`CausalClassifier (standard)` 模式在所有关键指标上均达到最佳表现，显著优于所有基线模型。\n\n| 方法                       | Accuracy (↑) | Precision (↑) | Recall (↑) | F1-Score (↑) |\n| :------------------------- | :----------- | :------------ | :--------- | :----------- |\n| sklearn                    | 0.8850       | 0.8847        | 0.8850     | 0.8848       |\n| pytorch                    | 0.8950       | 0.8952        | 0.8950     | 0.8951       |\n| sklearn_ovr                | 0.8975       | 0.8987        | 0.8974     | 0.8974       |\n| Causal (deterministic)     | 0.8888       | 0.8935        | 0.8890     | 0.8884       |\n| **Causal (standard)**      | **0.9225**   | **0.9224**    | **0.9225** | **0.9224**   |\n\n*这再次证明了 CausalEngine 的 `standard` 模式不仅在回归中表现优异，在分类任务中同样具有处理标签噪声的领先优势。*\n\n## 安装\n\n### 通过 PyPI 安装（推荐）\n\n```bash\npip install causal-sklearn\n```\n\n### 从源代码安装\n\n```bash\n# 克隆仓库\ngit clone https://github.com/1587causalai/causal-sklearn.git\ncd causal-sklearn\n\n# 安装依赖并安装包\npip install -e .\n```\n\n### 系统要求\n\n- **Python**: \u003e= 3.8\n- **核心依赖**: \n  - numpy \u003e= 1.21.0\n  - scipy \u003e= 1.7.0  \n  - scikit-learn \u003e= 1.0.0\n  - torch \u003e= 1.10.0\n  - pandas \u003e= 1.3.0\n\n### 验证安装\n\n```python\nimport causal_sklearn\nprint(f\"Causal-sklearn version: {causal_sklearn.__version__}\")\nprint(\"安装成功！🎉\")\n```\n\n## 快速开始\n\n### 基础使用示例\n\n```python\nfrom causal_sklearn import MLPCausalRegressor, MLPCausalClassifier\nfrom sklearn.datasets import make_regression, make_classification\nfrom sklearn.model_selection import train_test_split\n\n# 回归示例\nX, y = make_regression(n_samples=1000, n_features=20, noise=0.1)\nX_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2)\n\nregressor = MLPCausalRegressor(mode='standard', random_state=42)\nregressor.fit(X_train, y_train)\npredictions = regressor.predict(X_test)\ndistributions = regressor.predict_dist(X_test) # 返回完整的Cauchy分布参数\n\n# 分类示例\nX, y = make_classification(n_samples=1000, n_features=20, n_classes=3)\nX_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2)\n\nclassifier = MLPCausalClassifier(mode='standard', random_state=42)\nclassifier.fit(X_train, y_train)\npredictions = classifier.predict(X_test)\nprobabilities = classifier.predict_proba(X_test)\n```\n\n### 🚀 快速验证测试\n\n运行快速测试脚本，同时验证回归和分类性能：\n\n```bash\n# 运行完整的快速测试（回归+分类）\npython scripts/quick_test_causal_engine.py\n\n# 这个脚本将：\n# 1. 生成合成数据（回归：4000样本×12特征，分类：4000样本×10特征×3类）\n# 2. 在30%噪声下比较8种方法性能\n# 3. 统一标准化策略确保公平比较\n# 4. 生成完整的性能分析报告和可视化图表\n```\n\n**快速测试亮点**：\n- ⚡ 快速验证：几分钟内完成全面测试\n- 🔄 双任务支持：同时测试回归和分类能力\n- 🎯 8种方法对比：sklearn/PyTorch基线 + CausalEngine四种模式\n- 📊 科学实验设计：无数据泄露的标准化策略\n- 🛡️ 噪声鲁棒性：在30%噪声环境下验证优势\n\n### 🏠 真实世界教程 - 加州房价预测\n\n运行完整的真实世界回归教程，展示CausalEngine的强大性能：\n\n```bash\n# 运行真实世界回归教程（sklearn-style版本）\npython examples/comprehensive_causal_modes_tutorial_sklearn_style.py\n\n# 这个教程将：\n# 1. 加载加州房价数据集（20,640个样本）\n# 2. 在30%标签噪声下比较13种方法\n# 3. 测试CausalEngine所有4种推理模式\n# 4. 生成标准版和扩展版性能对比图表\n```\n\n**真实世界教程亮点**：\n- 🌍 真实数据：加州房价数据集的完整分析\n- 🔬 全面对比：13种方法（传统ML + 稳健回归 + CausalEngine四模式）\n- 📊 双重可视化：标准版（9种核心方法）+ 扩展版（13种全方法）\n- 🎯 CausalEngine专项：四种推理模式的深度对比分析\n- 🛡️ 鲁棒性验证：在30%噪声环境下的真实表现\n\n### 📈 鲁棒性测试脚本\n\n测试算法在不同噪声水平下的鲁棒性表现：\n\n```bash\n# 回归算法鲁棒性测试（真实数据集）\npython scripts/regression_robustness_real_datasets.py\n\n# 分类算法鲁棒性测试（真实数据集）\npython scripts/classification_robustness_real_datasets.py\n\n# 这些脚本将：\n# 1. 使用sklearn内置真实数据集\n# 2. 测试0%-100%噪声梯度（11个级别）\n# 3. 比较多种算法的鲁棒性曲线\n# 4. 支持多次运行取平均，提高结果稳定性\n```\n\n\n\n## 📚 文档与理论基础\n\n### 🧮 数学理论基础\n- **[🌟 数学基础 (中文)](docs/mathematical_foundation.md)** - **最核心文档** 完整的CausalEngine理论框架\n- **[One-Pager Summary](docs/ONE_PAGER.md)** - Executive summary of CausalEngine\n\n## 📄 许可证\n\n本项目采用Apache License 2.0 - 详见[LICENSE](LICENSE)文件。\n\n\n## 📖 学术引用\n\n如果您在研究中使用了Causal-Sklearn，请引用：\n\n```bibtex\n@software{causal_sklearn,\n  title={Causal-Sklearn: Scikit-learn Compatible Causal Regression and Classification},\n  author={Heyang Gong},\n  year={2025},\n  url={https://github.com/1587causalai/causal-sklearn},\n  note={基于CausalEngine™核心的因果回归和因果分类算法的scikit-learn兼容实现}\n}\n```\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**🌟 CausalEngine™ - 基于归因行动框架的因果推理引擎 🌟**\n\n*从相关性到因果性，从模式匹配到因果理解*\n\n\u003c/div\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F1587causalai%2Fcausal-sklearn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F1587causalai%2Fcausal-sklearn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F1587causalai%2Fcausal-sklearn/lists"}