.. -- mode: rst --

|Travis|_ |Coveralls|_ |CircleCI|_ |Python27|_ |Python35|_

.. |Travis| image:: https://api.travis-ci.org/skope-rules/skope-rules.svg?branch=master .. _Travis: https://travis-ci.org/skope-rules/skope-rules

.. |Coveralls| image:: https://coveralls.io/repos/github/skope-rules/skope-rules/badge.svg?branch=master .. _Coveralls: https://coveralls.io/github/skope-rules/skope-rules?branch=master

.. |CircleCI| image:: https://circleci.com/gh/skope-rules/skope-rules/tree/master.svg?style=shield&circle-token=:circle-token .. _CircleCI: https://circleci.com/gh/skope-rules/skope-rules

.. |Python27| image:: https://img.shields.io/badge/python-2.7-blue.svg .. _Python27: https://badge.fury.io/py/skope-rules

.. |Python35| image:: https://img.shields.io/badge/python-3.5-blue.svg .. _Python35: https://badge.fury.io/py/skope-rules

.. image:: logo.png

skope-rules

Skope-rules 是一个基于 scikit-learn 构建的 Python 机器学习模块，采用 3 条款 BSD 许可证进行发布。

Skope-rules 的目标是学习逻辑且可解释的规则，用于“划定”目标类别的范围，即以高精度检测该类别的实例。

Skope-rules 在决策树的可解释性与随机森林的建模能力之间取得了平衡。

有关贡献者列表，请参阅 AUTHORS.rst <AUTHORS.rst>_ 文件。

.. image:: schema.png

安装

您可以使用 pip 获取最新源代码：

pip install skope-rules

快速入门

SkopeRules 可用于通过逻辑规则描述类别：

.. code:: python

from sklearn.datasets import load_iris
from skrules import SkopeRules

dataset = load_iris()
feature_names = ['sepal_length', 'sepal_width', 'petal_length', 'petal_width']
clf = SkopeRules(max_depth_duplication=2,
                 n_estimators=30,
                 precision_min=0.3,
                 recall_min=0.1,
                 feature_names=feature_names)

for idx, species in enumerate(dataset.target_names):
    X, y = dataset.data, dataset.target
    clf.fit(X, y == idx)
    rules = clf.rules_[0:3]
    print("鸢尾花", species 的规则)
    for rule in rules:
        print(rule)
    print()
    print(20*'=')
    print()

::

SkopeRules 也可以作为预测器使用，只需调用 "score_top_rules" 方法：

.. code:: python

from sklearn.datasets import load_boston
from sklearn.metrics import precision_recall_curve
from matplotlib import pyplot as plt
from skrules import SkopeRules

dataset = load_boston()
clf = SkopeRules(max_depth_duplication=None,
                 n_estimators=30,
                 precision_min=0.2,
                 recall_min=0.01,
                 feature_names=dataset.feature_names)

X, y = dataset.data, dataset.target > 25
X_train, y_train = X[:len(y)//2], y[:len(y)//2]
X_test, y_test = X[len(y)//2:], y[len(y)//2:]
clf.fit(X_train, y_train)
y_score = clf.score_top_rules(X_test) # 为每个测试样本获取风险评分
precision, recall, _ = precision_recall_curve(y_test, y_score)
plt.plot(recall, precision)
plt.xlabel('召回率')
plt.ylabel('精确率')
plt.title('精确率-召回率曲线')
plt.show()

::

更多示例和用法请查看我们的 文档 <http://skope-rules.readthedocs.io/en/latest/>。您还可以查看 演示笔记本 <notebooks/>。

与现有文献的联系

决策规则的主要优势在于其提供的模型具有可解释性。在机器学习领域，生成此类规则的问题已被广泛研究，例如 RuleFit [1]、Slipper [2]、LRI [3] 和 MLRules [4] 等。

决策规则是一种逻辑表达式，形式为“如果满足条件，则采取响应”。在二分类任务中，如果某个实例满足规则中的条件，则会被分配到其中一个类别；如果不满足条件，则保持未分配状态。

1. 在 [2, 3, 4] 中，规则的归纳是通过将每条单独的决策规则视为集成模型中的基分类器来完成的，这些基分类器会通过贪婪地最小化某种损失函数来构建集成模型。

2. 在 [1] 中，规则是从树集成中提取的；然后通过对权重进行 L1 正则化的优化问题求解，构建这些规则的加权组合，具体方法如 [5] 所述。

本包采用了第二种方法。规则是从树集成中提取的，这使我们能够利用现有的高效算法（如装袋决策树或梯度提升）来生成这样的树集成。随后，根据规则支持集的相似性阈值，移除过于相似或重复的规则。

本包的主要目标是提供满足精确率和召回率条件的规则。它仍然实现了 score (decision_function) 方法，但并未像 [1] 那样解决 L1 正则化的优化问题。相反，权重仅与规则的 OOB 相关精确率成比例。

此外，本包还提供了方便的方法来使用最精确的 k 条规则进行预测（参见 score_top_rules() 和 predict_top_rules() 函数）。

[1] Friedman 和 Popescu，《通过规则集成进行预测学习》，技术报告，2005 年。

[2] Cohen 和 Singer，《简单、快速且有效的规则学习器》，全国人工智能会议，1999 年。

[3] Weiss 和 Indurkhya，《轻量级规则归纳》，ICML，2000 年。

[4] Dembczyński、Kotłowski 和 Słowiński，《最大似然规则集成》，ICML，2008 年。

[5] Friedman 和 Popescu，《梯度导向正则化》，技术报告，2004 年。

依赖项

skope-rules 需要以下依赖项：

• Python (>= 2.7 或 >= 3.3)
• NumPy (>= 1.10.4)
• SciPy (>= 0.17.0)
• Pandas (>= 0.18.1)
• Scikit-Learn (>= 0.17.1)

运行示例时，还需要 Matplotlib >= 1.1.1。

文档

您可以在此处访问完整的项目文档：http://skope-rules.readthedocs.io/en/latest/

您还可以查看 notebooks/ 文件夹，其中包含一些使用示例。

skope-rules 快速上手指南

skope-rules 是一个基于 scikit-learn 构建的 Python 机器学习模块。它旨在通过学习逻辑化、可解释的规则来“界定”目标类别，即以高精确度检测特定类的实例。它在决策树的可解释性与随机森林的建模能力之间取得了平衡。

环境准备

在开始之前，请确保您的系统满足以下要求：

• Python 版本：>= 2.7 或 >= 3.3
• 核心依赖库：
  • NumPy (>= 1.10.4)
  • SciPy (>= 0.17.0)
  • Pandas (>= 0.18.1)
  • Scikit-Learn (>= 0.17.1)
• 可选依赖（用于运行示例和绘图）：
  • Matplotlib (>= 1.1.1)

安装步骤

您可以直接使用 pip 安装最新版本的 skope-rules：

pip install skope-rules

提示：如果您在国内网络环境下遇到下载缓慢的问题，可以使用国内镜像源加速安装，例如使用清华源：

pip install skope-rules -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

skope-rules 主要用于生成描述类别的逻辑规则。以下是一个基于 Iris 数据集的最简使用示例，展示如何提取分类规则：

from sklearn.datasets import load_iris
from skrules import SkopeRules

# 加载数据
dataset = load_iris()
feature_names = ['sepal_length', 'sepal_width', 'petal_length', 'petal_width']

# 初始化模型
# max_depth_duplication: 控制规则重复深度的参数
# n_estimators: 估计器数量
# precision_min/recall_min: 最小精确率和召回率阈值
clf = SkopeRules(max_depth_duplication=2,
                 n_estimators=30,
                 precision_min=0.3,
                 recall_min=0.1,
                 feature_names=feature_names)

# 针对每个类别提取规则
for idx, species in enumerate(dataset.target_names):
    X, y = dataset.data, dataset.target
    # 训练模型：当前类别为正例，其他为负例
    clf.fit(X, y == idx)
    
    # 获取前3条规则
    rules = clf.rules_[0:3]
    print("Rules for iris", species)
    for rule in rules:
        print(rule)
    print()
    print(20*'=')
    print()

此外，skope-rules 也可作为预测器使用。通过 score_top_rules 方法，您可以为测试样本获取风险评分，进而绘制精确率-召回率曲线（Precision-Recall Curve）以评估模型性能。