rulelift 1.3.0
A tool for analyzing rule effectiveness in credit risk management
Requires Python: >=3.6

# rulelift - 信用风险规则有效性分析工具

## 项目概述

rulelift 是一个用于信用风险管理中策略规则自动挖掘、有效性分析及监控的 Python 工具包。

- **实时评估监控上线规则的效度**：解决规则拦截样本无标签的问题，借助客户评级分布差异，实时评估逾期率、召回率、精确率、lift 值、相关性、规则间的增益、稳定性等核心指标
- **自动化挖掘高价值的规则**：自动从数据中挖掘有效的风控规则，支持单特征、多特征交叉、决策树、随机森林、GBDT、孤立森林等多种规则挖掘方法
- **可视化展示**：直观呈现变量分布、变量效度、规则效果、特征重要性、决策树结构和规则关系
- **成本效益高**：无需分流测试，基于规则命中用户记录即可评估规则效果，降低测试成本

它帮助风控团队评估优化规则的实际效果，识别冗余规则，自动挖掘有效规则，便于策略D类、A类的全面优化，提高风险控制能力，降低风控成本。

## 📊 项目统计


### PyPI Downloads
[![PyPI downloads](https://img.shields.io/pypi/dm/rulelift.svg)](https://pypistats.org/packages/rulelift)
[![PyPI version](https://img.shields.io/pypi/v/rulelift.svg)](https://pypi.org/project/rulelift/)



### Star History
[![Star History Chart](https://api.star-history.com/svg?repos=aialgorithm/rulelift&type=Date)](https://star-history.com/#aialgorithm/rulelift&Date)

## 📚 目录

- [项目概述](#项目概述)
- [完整的安装使用方法](#完整的安装使用方法)
  - [使用 pip 安装](#使用-pip-安装)
  - [从源码安装](#从源码安装)
  - [离线使用方式（考虑生产环境是无网）](#离线使用方式考虑生产环境是无网)
- [快速开始](#快速开始)
  - [1. 基本导入](#1-基本导入)
  - [2. 加载示例数据](#2-加载示例数据)
  - [3. 规则挖掘基础案例](#3-规则挖掘基础案例)
    - [3.1 单特征规则挖掘](#31-单特征规则挖掘)
    - [3.2 多特征交叉规则挖掘](#32-多特征交叉规则挖掘)
    - [3.3 树模型规则挖掘](#33-树模型规则挖掘)
    - [3.4 多特征交叉规则挖掘（包含损失率指标）](#34-多特征交叉规则挖掘包含损失率指标)
  - [4. 规则评估基础案例](#4-规则评估基础案例)
    - [4.1 规则效度评估](#41-规则效度评估)
    - [4.2 规则相关性分析](#42-规则相关性分析)
    - [4.3 策略增益计算](#43-策略增益计算)
  - [5. 变量分析基础案例](#5-变量分析基础案例)
- [核心功能详解](#核心功能详解)
  - [1. 树规则提取（TreeRuleExtractor）](#1-树规则提取treeruleextractor)
  - [2. 单特征规则挖掘（SingleFeatureRuleMiner）](#2-单特征规则挖掘singlefeatureminer）
  - [3. 多特征交叉规则挖掘（MultiFeatureRuleMiner）](#3-多特征交叉规则挖掘multifeaturerulerminer)
  - [4. 变量分析（VariableAnalyzer）](#4-变量分析variableanalyzer)
  - [5. 规则效度分析监控模块（analyze_rules）](#5-规则效度分析监控模块analyze_rules)
  - [6. 策略相关性、增益计算（calculate_strategy_gain）](#6-策略相关性增益计算calculate_strategy_gain)
- [核心指标说明](#核心指标说明)
  - [规则评估指标](#规则评估指标)
  - [变量分析指标](#变量分析指标)
  - [常见问题（FAQ）](#常见问题faq)
  - [版本信息](#版本信息)
  - [更新日志](#更新日志)
  - [许可证](#许可证)
  - [项目地址](#项目地址)
  - [联系方式](#联系方式)
  - [贡献指南](#贡献指南)
## 📦 项目依赖包

### 核心依赖
项目依赖项精简，兼容性良好，仅需要常见的依赖包
| 依赖包 | 版本要求 | 用途 |
|--------|----------|------|
| pandas | >=1.0.0,<2.4.0 | 数据处理和分析 |
| numpy | >=1.18.0,<2.5.0 | 数值计算 |
| scikit-learn | >=0.24.0,<1.9.0 | 机器学习算法 |
| matplotlib | >=3.3.0,<3.11.0 | 基础可视化 |
| seaborn | >=0.11.0,<0.14.0 | 统计可视化 |
| openpyxl | >=3.0.0 | Excel文件读写 |
## 🎯 项目功能概览

rulelift 提供了完整的规则挖掘和评估解决方案，包含以下核心功能模块：

| 功能模块 | 主要功能 | 适用场景 |
|---------|---------|---------|
| **规则挖掘** | 单特征规则挖掘、多特征交叉规则挖掘、树模型规则挖掘 | 从数据中自动挖掘有效的风控规则 |
| **规则评估** | 规则效度评估、规则相关性分析、策略增益计算 | 评估上线规则的实际效果，识别冗余规则 |
| **变量分析** | 变量效度分析、分箱分析、PSI计算 | 识别重要变量，优化特征工程 |
| **可视化** | 规则效果可视化、特征重要性图、决策树结构图 | 直观呈现分析结果，便于决策 |
| **损失率分析** | 损失率计算、损失提升度分析 | 评估规则的实际损失风险 |

### 功能特点

✅ **全面的规则挖掘**：支持5种树模型算法（DT、RF、CHI2、GBDT、ISF）
✅ **灵活的评估方式**：支持用户评级评估和目标标签评估
✅ **丰富的指标体系**：包含badrate、lift、precision、recall、F1、loss_rate、loss_lift等30+指标
✅ **业务解释性强**：支持特征趋势配置，避免不符合业务逻辑的规则
✅ **损失率支持**：支持损失率和损失提升度计算，全面评估风险
✅ **可视化完善**：提供热力图、特征重要性图、决策树结构图等多种可视化
✅ **易于使用**：提供简洁的API和详细的示例代码

---

## 完整的安装使用方法

### 使用 pip 安装（推荐）

```bash
pip install rulelift
```

### 从源码安装

```bash
git clone https://github.com/aialgorithm/rulelift.git
cd rulelift
pip install -e .
```

## 离线使用方式（考虑生产环境是无网）

### 方式一：离线安装rulelift及相关依赖

1. **在有网络的环境中下载依赖包**：

```bash
# 下载rulelift及其所有依赖
pip download rulelift -d ./packages/
```

2. **将下载的packages文件夹传输到离线环境**

3. **在离线环境中安装**：

```bash
# 进入packages文件夹
cd ./packages/

# 安装所有依赖包
pip install *.whl --no-index --find-links=.
```

### 方式二：通过源码直接调用

1. **下载源码**：

   * 从GitHub下载源码包：<https://github.com/aialgorithm/rulelift>

2. **将源码包传输到离线环境并解压**
需要手动安装pandas、numpy、scikit-learn、matplotlib、seaborn
3. **在Python代码中添加源码路径并导入**：

```python
import sys
import os

# 添加源码路径到系统路径
sys.path.append('/path/to/rulelift-master')

# 直接导入模块
from rulelift import load_example_data, analyze_rules, TreeRuleExtractor
```

## 快速开始

### 1. 基本导入

```python
from rulelift import (
    load_example_data, preprocess_data,
    SingleFeatureRuleMiner, MultiFeatureRuleMiner, TreeRuleExtractor,
    VariableAnalyzer, analyze_rules, calculate_strategy_gain
)
```

### 2. 加载示例数据

```python
# 加载示例数据
df = load_example_data('feas_target.csv')
```

### 3. 规则挖掘基础案例


#### 树模型规则挖掘

```python
from rulelift import TreeRuleExtractor

# 初始化树规则提取器
tree_miner = TreeRuleExtractor(
    df, 
    target_col='ISBAD', 
    exclude_cols=['ID', 'CREATE_TIME', 'OVD_BAL', 'AMOUNT'],
    algorithm='rf',  # 使用随机森林算法
    max_depth=5,
    n_estimators=10,
    test_size=0.3,
    random_state=42
)

# 训练模型
train_acc, test_acc = tree_miner.train()
print(f"训练集准确率: {train_acc:.4f}")
print(f"测试集准确率: {test_acc:.4f}")

# 提取规则
rules = tree_miner.extract_rules()
print(f"提取的规则数量: {len(rules)}")

# 获取规则DataFrame
rules_df = tree_miner.get_rules_as_dataframe(sort_by_lift=True)
print(rules_df.head())
```

**输出示例**：
```
训练集准确率: 0.8500
测试集准确率: 0.8200
提取的规则数量: 31
         rule_id                                        rule  predicted_class  class_probability  sample_count
0             0  ALI_FQZSCORE <= 535.0000                1            0.6500           120
1             1  BAIDU_FQZSCORE <= 420.0000                1            0.5800            95
2             2  ALI_FQZSCORE <= 535.0000 AND BAIDU_FQZSCORE <= 420.0000  1            0.7200           80
```

### 4. 规则评估基础案例

#### 规则效度评估

```python
from rulelift import analyze_rules

# 加载规则命中数据
hit_rule_df = load_example_data('hit_rule_info.csv')

# 通过用户评级评估规则效度
result_by_rating = analyze_rules(
    hit_rule_df, 
    rule_col='RULE',
    user_id_col='USER_ID',
    user_level_badrate_col='USER_LEVEL_BADRATE',
    hit_date_col='HIT_DATE',
    include_stability=True
)
print(result_by_rating[['RULE', 'actual_lift', 'actual_badrate', 'hit_rate_cv']].head())
```

**输出示例**：
```
         RULE  actual_lift  actual_badrate  hit_rate_cv
0  rule1     2.3456789      0.3456789     0.123456
1  rule2     2.123456      0.234567      0.145678
2  rule3     1.987654      0.123456      0.156789
```

### 5. 变量分析基础案例

```python
from rulelift import VariableAnalyzer

# 初始化变量分析器
var_analyzer = VariableAnalyzer(
    df, 
    exclude_cols=['ID', 'CREATE_TIME', 'OVD_BAL', 'AMOUNT'], 
    target_col='ISBAD'
)

# 分析所有变量的效度指标
var_metrics = var_analyzer.analyze_all_variables()
print("所有变量效度指标:")
print(var_metrics)

# 分析单个变量的分箱情况
feature = 'ALI_FQZSCORE'
bin_analysis = var_analyzer.analyze_single_variable(feature, n_bins=10)
print(f"\n{feature} 分箱分析:")
print(bin_analysis)
```

**输出示例**：
```
所有变量效度指标:
        variable        iv        ks        auc  missing_rate  single_value_rate  min_value  max_value  median_value  mean_diff  corr_with_target  psi
0  ALI_FQZSCORE  0.456789  0.452345  0.723456      0.012345      0.0456789      0.987654      0.723456      0.012345      0.456789      0.012345
1  BAIDU_FQZSCORE  0.3456789  0.3456789  0.678901      0.023456      0.056789      0.976543      0.678901      0.023456      0.3456789      0.023456

ALI_FQZSCORE 分箱分析:
        bin_range  count  bad_count  good_count  badrate  sample_ratio  cumulative_badrate
0  (514.999, 705.0]    120         78         42   0.6500        0.2400          0.6500
1  (705.0, 745.0]       95         55         40   0.5789        0.1900          0.6150
2  (745.0, 780.0]       80         45         35   0.5625        0.1600          0.5950
```

---

## 核心功能详解

### 1. 树规则提取（TreeRuleExtractor）

TreeRuleExtractor 是一个统一的树模型规则提取类，支持多种算法（DT、RF、CHI2、GBDT、ISF）。支持业务解释性配置、支持树复杂度及规则精度配置、支持评估规则全面方面指标badrate、损失率指标等等。

#### 1.1 支持的算法

| 算法 | 说明 | 适用场景 |
|------|------|----------|
| `dt` | 决策树（Decision Tree） | 快速生成规则，适合初步探索 |
| `rf` | 随机森林（Random Forest） | 规则稳定性好，多样性高，适合生产环境 |
| `chi2` | 卡方随机森林（Chi-square Random Forest） | 基于卡方分箱预处理，适合需要统计最优分箱的场景 |
| `gbdt` | 梯度提升树（Gradient Boosting Decision Tree） | 规则精度高，适合复杂场景 |
| `isf` | 孤立森林（Isolation Forest） | 适合挖掘异常样本的规则 |

**实践上可以 优先使用随机森林、GBDT等集成学习方法，通过调整超参数 n_estimators更大 max_features更小使得有更多及更多样规则，max_depth更小、min_samples_split较大，使得规则更简单更有解释性及统计可信度。传入业务字段（feature_trends）挖掘符合业务解释性规则。基于以上设置可以挖掘出符合业务逻辑的大量可靠规则以供选择**
#### 1.2 初始化参数详解

```python
from rulelift import TreeRuleExtractor

tree_miner = TreeRuleExtractor(
    df, 
    target_col='ISBAD',           # 目标字段名，默认为'ISBAD'
    exclude_cols=['ID', 'CREATE_TIME', 'OVD_BAL', 'AMOUNT'],  # 排除的字段名列表
    algorithm='rf',                # 算法类型：'dt'、'rf'、'chi2'、'gbdt'、'isf'，默认为'dt'
                                  # 注意：'xgb'已废弃，请使用'gbdt'（向后兼容）
    
    # 树复杂度配置（控制规则复杂度）
    max_depth=5,                  # 决策树最大深度，控制树的复杂度，值越小规则越简单，默认为5
    min_samples_split=10,         # 分裂节点所需的最小样本数，控制规则精度，值越大规则越简单，默认为10
    min_samples_leaf=5,           # 叶子节点的最小样本数，控制规则精度，值越大规则越简单，默认为5
    n_estimators=10,              # 随机森林/GBDT/孤立森林中树的数量，值越大规则数量越多，默认为10
    max_features='sqrt',           # 每棵树分裂时考虑的最大特征数：'sqrt'或'log2'，影响规则多样性，默认为'sqrt'
    
    # 卡方决策树分箱配置（仅适用于chi2算法）
    min_bins=5,                   # 卡方决策树分箱的最小分箱数，默认为5
    chi_square_threshold=0.05,    # 卡方检验阈值，用于确定分箱数量，值越小分箱越多，默认为0.05
    
    # GBDT正则化参数（仅适用于gbdt算法）
    learning_rate=0.1,           # 学习率，控制每棵树的贡献，默认为0.1
    subsample=1.0,               # 子采样比例，用于防止过拟合，默认为1.0
    
    # 数据划分配置
    test_size=0.3,                # 测试集比例，默认为0.3
    random_state=42,              # 随机种子，保证结果可复现，默认为42
    
    # 损失率指标配置
    amount_col='AMOUNT',          # 金额字段名，用于计算损失率指标，默认为None
    ovd_bal_col='OVD_BAL',        # 逾期金额字段名，用于计算损失率指标，默认为None
    
    # 业务解释性配置
    feature_trends={              # 特征与目标标签的正负相关性字典，用于避免不符合业务解释性的规则
        'ALI_FQZSCORE': -1,      # 负相关：分数越低，违约概率越高
        'BAIDU_FQZSCORE': -1,    # 负相关：分数越低，违约概率越高
        'NUMBER OF LOAN APPLICATIONS TO PBOC': 1  # 正相关：申请次数越多，违约概率越高
    }
)

# 训练模型
train_acc, test_acc = tree_miner.train()
print(f"训练集准确率: {train_acc:.4f}")
print(f"测试集准确率: {test_acc:.4f}")

# 提取规则
rules = tree_miner.extract_rules()
print(f"提取的规则数量: {len(rules)}")

# 获取规则DataFrame
rules_df = tree_miner.get_rules_as_dataframe(deduplicate=True, sort_by_lift=True)
print(rules_df.head())
```

**参数详细说明**：

| 参数 | 类型 | 默认值 | 说明 | 对规则复杂度的影响 |
|------|------|----------|------|---------------------|
| `max_depth` | int | `5` | 决策树最大深度 | 值越小规则越简单，建议3-8 |
| `min_samples_split` | int | `10` | 分裂节点所需的最小样本数 | 值越大规则越简单，建议5-20 |
| `min_samples_leaf` | int | `5` | 叶子节点的最小样本数 | 值越大规则越简单，建议5-15 |
| `n_estimators` | int | `10` | 随机森林/GBDT中树的数量 | 值越大规则数量越多，建议50-500 |
| `max_features` | str | `'sqrt'` | 每棵树分裂时考虑的最大特征数 | 影响规则多样性，'sqrt'或'log2' |
| `min_bins` | int | `5` | 卡方决策树分箱的最小分箱数 | 仅适用于chi2算法，建议5-10 |
| `chi_square_threshold` | float | `0.05` | 卡方检验阈值 | 仅适用于chi2算法，值越小分箱越多，建议0.01-0.05 |
| `min_bin_ratio` | float | `0.05` | 卡方分箱的最小样本占比 | 仅适用于chi2算法，控制分箱的最小样本数，建议0.03-0.1 |

**参数使用示例**：
```python
# 使用卡方分箱算法
chi2_miner = TreeRuleExtractor(
    df, 
    target_col='ISBAD',
    exclude_cols=['ID', 'CREATE_TIME', 'OVD_BAL', 'AMOUNT'],
    algorithm='chi2',
    min_bin_ratio=0.05  # 卡方分箱的最小样本占比
)
```

**控制规则复杂度的参数调优建议**：

1. **生成简单规则**：
   - 增加 `max_depth`（建议3-5）
   - 增加 `min_samples_split`（建议15-20）
   - 增加 `min_samples_leaf`（建议10-15）

2. **生成复杂规则**：
   - 减小 `max_depth`（建议6-10）
   - 减小 `min_samples_split`（建议5-10）
   - 减小 `min_samples_leaf`（建议3-8）

3. **提高规则多样性**：
   - 增加 `n_estimators`（建议100-500）
   - 使用 `max_features='log2'` 或手动设置较大值

4. **平衡规则复杂度和泛化能力**：
   - `max_depth`：5-8
   - `min_samples_leaf`：5-10
   - `min_samples_split`：10-20

#### 1.3 特征趋势判断（feature_trends）

规则挖掘中加入业务逻辑判断，`feature_trends` 参数用于配置特征与目标标签的正负相关性，避免不符合业务解释性的规则。

**参数说明**：
- `feature_trends`: Dict[str, int]，键为特征名，值为 1（正相关）或 -1（负相关），仅挖掘符合特征业务逻辑的规则
  - **正相关（值为1）**：表示特征数值越大，目标标签（违约概率）越高，如多头申请次数
  - **负相关（值为-1）**：特征数值越小，目标标签（违约概率）越高，如信用评分

**使用示例**：

```python
# 使用特征趋势过滤
tree_miner = TreeRuleExtractor(
    df, 
    target_col='ISBAD', 
    exclude_cols=['ID', 'CREATE_TIME'],
    algorithm='rf',
    feature_trends={
        'ALI_FQZSCORE': -1,      # 负相关：分数越低，违约概率越高
        'BAIDU_FQZSCORE': -1,    # 负相关：分数越低，违约概率越高
        'NUMBER OF LOAN APPLICATIONS TO PBOC': 1  # 正相关：申请次数越多，违约概率越高
    }
)

# 提取规则（会自动过滤不符合业务解释性的规则）
rules = tree_miner.extract_rules()
```

**效果示例**：

不使用 `feature_trends`：
```
Rule 1: BAIDU_FQZSCORE > 327.0000  # 该拦截规则，可能不符合业务解释性
Rule 2: NUMBER OF LOAN APPLICATIONS TO PBOC <= 5.0000  # 该拦截规则，可能不符合业务解释性
```

使用 `feature_trends`：
```
Rule 1: BAIDU_FQZSCORE <= 535.0000  # 负相关 
Rule 2: NUMBER OF LOAN APPLICATIONS TO PBOC > 2.0000  # 正相关 
```

#### 1.5 训练模型

```python
# 训练模型
train_acc, test_acc = tree_miner.train()
print(f"训练集准确率: {train_acc:.4f}")
print(f"测试集准确率: {test_acc:.4f}")
```

**返回值说明**：
- 对于 DT、RF、CHI2、GBDT 算法：返回 `(train_acc, test_acc)`，分别为训练集和测试集的准确率
- 对于 ISF 算法：返回 `(mean_score, std_score)`，分别为平均异常分数和标准差

#### 1.6 提取规则

```python
# 提取规则
rules = tree_miner.extract_rules()
print(f"提取的规则数量: {len(rules)}")

# 获取规则DataFrame
rules_df = tree_miner.get_rules_as_dataframe(deduplicate=True, sort_by_lift=True)
print(rules_df.head())
```

**参数说明**：
- `deduplicate`: bool，是否去重，默认为False
- `sort_by_lift`: bool，是否按lift倒序排序，默认为False

#### 1.7 规则评估

TreeRuleExtractor 提供了全面的规则评估功能，支持训练集和测试集的效度评估，包括损失率计算等高级指标。

### 1.7.1 损失率计算（Loss Rate）

损失率是评估规则实际风险损失的重要指标，需要提供金额字段和逾期金额字段。

**计算逻辑**：
- **损失率（loss_rate）**：特定规则或特征组合下，逾期金额总和除以总金额总和
  ```
  loss_rate = Σ(逾期金额) / Σ(总金额)
  ```
- **损失提升度（loss_lift）**：特定规则或特征组合的损失率除以整体样本的损失率
  ```
  loss_lift = 规则损失率 / 整体损失率
  ```

**业务价值**：
- 帮助风控团队评估规则的实际损失风险
- 结合badrate和lift指标，提供更全面的规则评估
- 优先选择高loss_lift的规则，降低实际损失

**使用方式**：
```python
# 初始化时指定金额和逾期金额字段
tree_miner = TreeRuleExtractor(
    df, 
    target_col='ISBAD',
    exclude_cols=['ID', 'CREATE_TIME'],
    amount_col='AMOUNT',      # 总金额字段名
    ovd_bal_col='OVD_BAL'      # 逾期金额字段名
)

# 训练并提取规则
tree_miner.train()
rules = tree_miner.extract_rules()

# 评估规则（包含损失率指标）
eval_results = tree_miner.evaluate_rules()

# 查看损失率指标
print(eval_results[['rule', 'train_loss_rate', 'train_loss_lift', 'test_loss_rate', 'test_loss_lift']].head())
```

**输出示例**：
```
         rule  train_loss_rate  train_loss_lift  test_loss_rate  test_loss_lift
0  rule_1         0.3456789       2.3456789      0.234567       1.987654
1  rule_2         0.234567       1.987654      0.123456       1.876543
2  rule_3         0.123456       1.765432      0.098765       1.765432
```

**损失率指标解读**：
- **loss_rate > 0.3**：高风险规则，实际损失较高
- **loss_rate 0.1-0.3**：中等风险规则
- **loss_rate < 0.1**：低风险规则，实际损失较低
- **loss_lift > 2.0**：高效规则，损失区分能力强
- **loss_lift 1.5-2.0**：良好规则
- **loss_lift < 1.5**：弱规则，建议优化

### 1.7.2 规则评估指标详解

```python
# 评估规则（包含损失率指标）
eval_results = tree_miner.evaluate_rules()
print(f"评估的规则数量: {len(eval_results)}")
print("规则评估结果（前5条）:")
print(eval_results[['rule', 'train_loss_rate', 'train_loss_lift', 'test_loss_rate', 'test_loss_lift', 'train_lift', 'test_lift', 'test_badrate_reduction']].head())
```

**输出示例**：

```
评估的规则数量: 31
规则评估结果（前5条）:
         rule  train_loss_rate  train_loss_lift  test_loss_rate  test_loss_lift  train_lift  test_lift  test_badrate_reduction
0  rule_1         0.3456789       2.3456789      0.234567       1.987654  2.123456      1.987654      0.4567
1  rule_2         0.234567       1.987654      0.123456       1.876543  1.654321      1.876543      0.3456
2  rule_3         0.123456       1.765432      0.098765       1.765432  1.543210      1.543210      0.2345
3  rule_4         0.098765       1.654321      0.076543       1.543210  1.432109      1.432109      0.1876
4  rule_5         0.076543       1.543210      0.065432       1.432109  1.321098      1.321098      0.1456
```

**核心评估指标说明**：

| 指标 | 说明 | 计算公式 | 业务意义 |
|------|------|----------|----------|
| `train_hit_count` | 训练集命中该规则的样本数 | - | 规则在训练集的覆盖范围 |
| `train_bad_count` | 训练集命中该规则的坏样本数 | - | 规则在训练集拦截的坏样本数量 |
| `train_badrate` | 训练集命中该规则的坏样本率 | train_bad_count / train_hit_count | 规则在训练集的风险区分能力 |
| `train_precision` | 训练集精确率 | train_bad_count / train_hit_count | 规则在训练集的预测准确性 |
| `train_recall` | 训练集召回率 | train_bad_count / total_bad_train | 规则在训练集对坏样本的覆盖能力 |
| `train_f1` | 训练集F1分数 | 2 * (precision * recall) / (precision + recall) | 训练集精确率和召回率的调和平均 |
| `train_lift` | 训练集lift值 | train_badrate / baseline_badrate_train | 规则在训练集的风险放大能力 |
| `train_loss_rate` | 训练集损失率 | total_ovd_bal_bad_selected / total_amount_selected | 规则在训练集的实际损失程度 |
| `train_loss_lift` | 训练集损失lift值 | train_loss_rate / overall_loss_rate_train | 规则在训练集的损失放大能力 |
| `train_hit_rate` | 训练集命中率 | train_hit_count / total_train_samples | 规则在训练集的覆盖率 |
| `train_baseline_badrate` | 训练集基准badrate | total_bad_train / total_train_samples | 训练集整体风险水平 |
| `train_badrate_after_interception` | 训练集拦截后badrate | (total_bad_train - train_bad_count) / (total_train_samples - train_hit_count) | 规则拦截后剩余样本的风险水平 |
| `train_badrate_reduction` | 训练集badrate降低幅度 | (baseline_badrate_train - badrate_after_interception_train) / baseline_badrate_train / train_hit_rate | **策略效率指标**：每1%命中率带来的badrate降低幅度 |
| `test_hit_count` | 测试集命中该规则的样本数 | - | 规则在测试集的覆盖范围 |
| `test_bad_count` | 测试集命中该规则的坏样本数 | - | 规则在测试集拦截的坏样本数量 |
| `test_badrate` | 测试集命中该规则的坏样本率 | test_bad_count / test_hit_count | 规则在测试集的风险区分能力 |
| `test_precision` | 测试集精确率 | test_bad_count / test_hit_count | 规则在测试集的预测准确性 |
| `test_recall` | 测试集召回率 | test_bad_count / total_bad_test | 规则在测试集对坏样本的覆盖能力 |
| `test_f1` | 测试集F1分数 | 2 * (precision * recall) / (precision + recall) | 测试集精确率和召回率的调和平均 |
| `test_lift` | 测试集lift值 | test_badrate / baseline_badrate_test | 规则在测试集的风险放大能力 |
| `test_loss_rate` | 测试集损失率 | total_ovd_bal_bad_selected / total_amount_selected | 规则在测试集的实际损失程度 |
| `test_loss_lift` | 测试集损失lift值 | test_loss_rate / overall_loss_rate_test | 规则在测试集的损失放大能力 |
| `test_hit_rate` | 测试集命中率 | test_hit_count / total_test_samples | 规则在测试集的覆盖率 |
| `test_baseline_badrate` | 测试集基准badrate | total_bad_test / total_test_samples | 测试集整体风险水平 |
| `test_badrate_after_interception` | 测试集拦截后badrate | (total_bad_test - test_bad_count) / (total_test_samples - test_hit_count) | 规则拦截后剩余样本的风险水平 |
| `test_badrate_reduction` | 测试集badrate降低幅度 | (baseline_badrate_test - badrate_after_interception_test) / baseline_badrate_test / test_hit_rate | **策略效率核心指标**：每1%命中率带来的badrate降低幅度，值越大策略效率越高 |
| `badrate_diff` | 训练集和测试集lift的差异 | train_lift - test_lift | 规则的泛化能力，值越小泛化能力越强 |
| `true_positive` | 真阳性（TP） | test_bad_count | 被正确拦截的坏样本数 |
| `false_positive` | 假阳性（FP） | test_good_count | 被错误拦截的好样本数 |
| `true_negative` | 真阴性（TN） | 未命中且为好样本的数量 | 未被拦截的好样本数 |
| `false_negative` | 假阴性（FN） | 未命中且为坏样本的数量 | 未被拦截的坏样本数 |

### 1.7.3 策略效率指标（test_badrate_reduction）

**test_badrate_reduction** 是衡量策略效率的核心指标，表示**每1%命中率带来的badrate降低幅度**。

**计算逻辑**：
```
test_badrate_reduction = [(基准badrate - 拦截后badrate) / 基准badrate] / 命中率
```

**业务解读**：
- **高值（> 0.5）**：高效策略，少量拦截即可显著降低整体badrate
- **中值（0.2-0.5）**：中等效率策略
- **低值（< 0.2）**：低效策略，需要大量拦截才能降低badrate

**应用场景**：
- 比较不同规则的效率，优先选择高badrate_reduction的规则
- 优化策略组合，平衡命中率和badrate降低效果
- 评估策略调整的效果，判断新规则是否提升了策略效率

### 1.7.4 评估指标组合建议

| 业务目标 | 推荐关注指标 | 最佳范围 |
|----------|--------------|----------|
| 降低整体风险 | `test_lift` + `test_badrate_reduction` | lift > 2.0, badrate_reduction > 0.3 |
| 降低实际损失 | `test_loss_lift` + `test_loss_rate` | loss_lift > 2.0, loss_rate < 0.1 |
| 提高规则泛化能力 | `badrate_diff` + `test_lift` | badrate_diff < 0.5, test_lift > 1.5 |
| 平衡精确率和召回率 | `test_f1` + `test_precision` | f1 > 0.5, precision > 0.6 |

**评估规则（包含损失率指标）**：

```python
# 筛选高效策略规则
high_efficiency_rules = eval_results[(
    eval_results['test_lift'] > 2.0 & 
    eval_results['test_badrate_reduction'] > 0.3 & 
    eval_results['test_loss_lift'] > 1.5
)]
print(f"高效策略规则数量: {len(high_efficiency_rules)}")
```

#### 1.8 不同算法使用示例

##### 1.8.1 决策树（DT）

```python
# 初始化决策树规则提取器
tree_miner_dt = TreeRuleExtractor(
    df, 
    target_col='ISBAD', 
    exclude_cols=['ID', 'CREATE_TIME', 'OVD_BAL', 'AMOUNT'],
    algorithm='dt',
    max_depth=3, 
    min_samples_split=20,
    min_samples_leaf=10,
    random_state=42
)

# 训练模型
train_acc, test_acc = tree_miner_dt.train()
print(f"训练集准确率: {train_acc:.4f}")
print(f"测试集准确率: {test_acc:.4f}")

# 提取规则
dt_rules = tree_miner_dt.extract_rules()
print(f"提取的规则数量: {len(dt_rules)}")

# 评估规则
eval_results = tree_miner_dt.evaluate_rules()
print(eval_results[['rule', 'test_hit_count', 'test_badrate', 'test_lift']].head())
```

##### 1.8.2 随机森林（RF）

随机森林适合挖掘稳定、多样的规则，通过控制参数可以生成大量高质量规则。

**随机森林提高规则多样性的方法**：
- **增加树的数量**：增加n_estimators可以生成更多规则
- **调整max_features**：使用max_features='log2'或手动设置较大值，提高规则多样性
- **减小min_samples_leaf**：减小叶子节点样本数限制，生成更多规则
- **增加max_depth**：适当增加深度，生成更复杂的规则

**参数调优建议**：
- **n_estimators**：增加树的数量可以生成更多规则，建议设置为100-500
- **max_depth**：控制单棵树的复杂度，建议设置为5-10
- **max_features**：增加考虑的特征数可以提高规则多样性，建议设置为'sqrt'或'log2'
- **min_samples_leaf**：减小叶子节点样本数限制，建议设置为5-20

**优化后随机森林使用示例**：

```python
# 初始化随机森林规则提取器，优化参数以挖掘更多规则
tree_miner_rf = TreeRuleExtractor(
    df, 
    target_col='ISBAD', 
    exclude_cols=['ID', 'CREATE_TIME', 'OVD_BAL', 'AMOUNT'],
    algorithm='rf',
    max_depth=8, 
    min_samples_split=10,  # 减小分裂样本数限制
    min_samples_leaf=5,    # 减小叶子节点样本数限制
    n_estimators=200,      # 增加树的数量，生成更多规则
    max_features='log2',   # 考虑更多特征，提高规则多样性
    random_state=42
)

# 训练模型
train_acc, test_acc = tree_miner_rf.train()
print(f"训练集准确率: {train_acc:.4f}")
print(f"测试集准确率: {test_acc:.4f}")

# 提取规则
rf_rules = tree_miner_rf.extract_rules()
print(f"提取的规则数量: {len(rf_rules)}")

# 评估规则
eval_results = tree_miner_rf.evaluate_rules()

# 按test_badrate_reduction排序，筛选高效规则
eval_results_sorted = eval_results.sort_values(by='test_badrate_reduction', ascending=False)
print("Top 10 高效规则:")
print(eval_results_sorted[['rule', 'test_lift', 'test_badrate_reduction', 'test_loss_lift']].head(10))
```

**随机森林规则挖掘最佳实践**：
1. **生成大量规则**：设置较大的n_estimators和较小的min_samples_leaf
2. **控制规则复杂度**：通过max_depth平衡规则复杂度和泛化能力
3. **提高规则多样性**：使用max_features='log2'或手动设置较大值
4. **筛选高效规则**：按test_badrate_reduction或test_lift排序，选择前N条规则
5. **去重处理**：使用get_rules_as_dataframe(deduplicate=True)去除重复规则

##### 1.8.3 卡方随机森林（CHI2）

卡方随机森林采用**卡方分箱预处理 + 随机森林**的方式实现，不需要复杂的自定义决策树分裂逻辑。

**实现原理**：
1. **卡方分箱预处理**：对每个数值型特征进行卡方分箱，基于统计检验合并相似分箱
2. **特征值替换**：将原始特征值替换为卡方分箱的上限
3. **随机森林训练**：基于卡方分箱后的特征值进行随机森林训练
4. **规则提取**：从随机森林中提取决策路径作为规则

**卡方分箱参数说明**：
- **min_bins**：最小分箱数，默认为5
- **chi_square_threshold**：卡方检验阈值，用于确定分箱数量，值越小分箱越多
- **min_bin_ratio**：卡方分箱的最小样本占比，默认为0.05，控制分箱的最小样本数

**卡方随机森林使用示例**：

```python
# 初始化卡方随机森林规则提取器，自定义分箱参数
tree_miner_chi2 = TreeRuleExtractor(
    df, 
    target_col='ISBAD', 
    exclude_cols=['ID', 'CREATE_TIME', 'OVD_BAL', 'AMOUNT'],
    algorithm='chi2',
    max_depth=5, 
    min_samples_split=20,
    min_samples_leaf=10,
    n_estimators=100,             # 随机森林的树数量
    max_features='sqrt',
    min_bins=8,                  # 自定义最小分箱数
    chi_square_threshold=0.01,    # 降低卡方阈值，生成更多分箱
    min_bin_ratio=0.05,           # 卡方分箱的最小样本占比
    random_state=42
)

# 训练模型（会自动进行卡方分箱预处理）
train_acc, test_acc = tree_miner_chi2.train()
print(f"训练集准确率: {train_acc:.4f}")
print(f"测试集准确率: {test_acc:.4f}")

# 提取规则
chi2_rules = tree_miner_chi2.extract_rules()
print(f"提取的规则数量: {len(chi2_rules)}")

# 评估规则
eval_results = tree_miner_chi2.evaluate_rules()
print(eval_results[['rule', 'test_hit_count', 'test_badrate', 'test_lift']].head())
```

**卡方分箱参数调优建议**：
- **min_bins**：增加最小分箱数可以生成更细粒度的规则，建议设置为5-10
- **chi_square_threshold**：降低卡方阈值可以增加分箱数量，建议设置为0.01-0.05
- **min_bin_ratio**：控制分箱的最小样本数，建议设置为0.03-0.1
- **max_depth**：控制树的深度，建议设置为5-8
- **min_samples_leaf**：控制叶子节点的最小样本数，建议设置为10-20
- **n_estimators**：增加树的数量可以提高规则多样性，建议设置为50-200

**卡方随机森林最佳实践**：
1. **生成更多分箱**：降低chi_square_threshold，增加min_bins
2. **控制规则复杂度**：通过max_depth平衡规则复杂度和泛化能力
3. **提高规则多样性**：增加n_estimators，使用max_features='sqrt'或'log2'
4. **筛选高效规则**：按test_badrate_reduction或test_lift排序，选择前N条规则
5. **去重处理**：使用get_rules_as_dataframe(deduplicate=True)去除重复规则
3. **确保样本充足**：每个分箱的样本数建议≥50
4. **验证分箱效果**：检查badrate是否呈现单调性或明显的风险趋势

##### 1.8.4 梯度提升树（GBDT）

GBDT适合挖掘高精度规则，通过迭代提升可以生成质量更高的规则。

**GBDT参数调优建议**：
- **n_estimators**：增加树的数量可以生成更多规则，建议设置为100-300
- **max_depth**：控制单棵树的复杂度，建议设置为3-8
- **learning_rate**：减小学习率可以提高规则质量，建议设置为0.01-0.1
- **min_samples_leaf**：控制叶子节点样本数，建议设置为5-15

**优化后GBDT使用示例**：

```python
# 初始化梯度提升树规则提取器，优化参数以挖掘高质量规则
tree_miner_gbdt = TreeRuleExtractor(
    df, 
    target_col='ISBAD', 
    exclude_cols=['ID', 'CREATE_TIME', 'OVD_BAL', 'AMOUNT'],
    algorithm='gbdt',
    max_depth=5,                # 适当增加深度，生成更复杂规则
    min_samples_split=5,         # 减小分裂样本数限制
    min_samples_leaf=8,          # 控制叶子节点样本数
    n_estimators=200,           # 增加树的数量，生成更多规则
    learning_rate=0.05,          # 减小学习率，提高规则质量
    max_features='sqrt',         # 增加特征多样性
    feature_trends={
        'ALI_FQZSCORE': -1,      # 负相关：分数越低，违约概率越高
        'BAIDU_FQZSCORE': -1,    # 负相关：分数越低，违约概率越高
        'NUMBER OF LOAN APPLICATIONS TO PBOC': 1  # 正相关：申请次数越多，违约概率越高
    },
    random_state=42
)

# 训练模型
train_acc, test_acc = tree_miner_gbdt.train()
print(f"训练集准确率: {train_acc:.4f}")
print(f"测试集准确率: {test_acc:.4f}")

# 提取规则
gbdt_rules = tree_miner_gbdt.extract_rules()
print(f"提取的规则数量: {len(gbdt_rules)}")

# 评估规则
eval_results = tree_miner_gbdt.evaluate_rules()

# 按test_lift和test_badrate_reduction综合排序
eval_results['score'] = eval_results['test_lift'] * 0.6 + eval_results['test_badrate_reduction'] * 0.4
eval_results_sorted = eval_results.sort_values(by='score', ascending=False)
print("Top 10 高质量规则:")
print(eval_results_sorted[['rule', 'test_lift', 'test_badrate_reduction', 'test_loss_lift', 'score']].head(10))
```

**GBDT规则挖掘最佳实践**：
1. **平衡精度和数量**：通过n_estimators和learning_rate平衡规则数量和质量
2. **控制过拟合**：使用合适的max_depth和min_samples_leaf
3. **结合特征趋势**：使用feature_trends确保规则符合业务逻辑
4. **综合评估**：结合test_lift和test_badrate_reduction评估规则
5. **梯度提升优势**：利用GBDT的迭代提升特性，生成高质量规则

**GBDT vs 随机森林：如何选择？**
- **需要高质量规则**：选择GBDT，生成的规则精度更高
- **需要多样化规则**：选择随机森林，生成的规则更具多样性
- **数据量较大**：GBDT和随机森林都适用，但随机森林训练速度更快
- **特征重要性清晰**：GBDT能提供更准确的特征重要性

### 1.8.5 从实际使用角度建议如何使用RF和GBDT挖掘更多多样性高效度规则

#### 1.8.5.1 随机森林（RF）使用建议

**适用场景**：
- 需要挖掘大量多样化规则
- 规则稳定性要求较高
- 特征数量较多，需要提高特征多样性
- 训练速度要求较快

**参数配置建议**：

```python
# 配置1：生成大量多样化规则（推荐）
tree_miner_rf = TreeRuleExtractor(
    df, 
    target_col='ISBAD', 
    exclude_cols=['ID', 'CREATE_TIME', 'OVD_BAL', 'AMOUNT'],
    algorithm='rf',
    max_depth=8,                # 适当增加深度
    min_samples_split=10,        # 减小分裂样本数限制
    min_samples_leaf=5,          # 减小叶子节点样本数限制
    n_estimators=300,           # 增加树的数量
    max_features='log2',        # 提高特征多样性
    random_state=42
)

# 配置2：生成高质量稳定规则
tree_miner_rf_stable = TreeRuleExtractor(
    df, 
    target_col='ISBAD', 
    exclude_cols=['ID', 'CREATE_TIME', 'OVD_BAL', 'AMOUNT'],
    algorithm='rf',
    max_depth=5,                # 控制深度
    min_samples_split=20,        # 增加分裂样本数限制
    min_sampl