# 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_samples_leaf=10,         # 增加叶子节点样本数限制
    n_estimators=100,           # 适中的树的数量
    max_features='sqrt',        # 平衡特征多样性
    random_state=42
)
```

**实际使用建议**：
1. **第一阶段**：使用配置1生成大量多样化规则
2. **第二阶段**：筛选高lift和高badrate_reduction的规则
3. **第三阶段**：使用配置2对筛选后的规则进行验证
4. **第四阶段**：结合业务知识，选择最优规则组合

#### 1.8.5.2 梯度提升树（GBDT）使用建议

**适用场景**：
- 需要挖掘高精度规则
- 规则质量要求较高
- 特征重要性需要准确评估
- 数据量适中，可以接受较长的训练时间

**参数配置建议**：

```python
# 配置1：生成高质量规则（推荐）
tree_miner_gbdt = TreeRuleExtractor(
    df, 
    target_col='ISBAD', 
    exclude_cols=['ID', 'CREATE_TIME', 'OVD_BAL', 'AMOUNT'],
    algorithm='gbdt',
    max_depth=5,                # 控制深度
    min_samples_split=10,        # 适中的分裂样本数限制
    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
)

# 配置2：生成快速规则
tree_miner_gbdt_fast = TreeRuleExtractor(
    df, 
    target_col='ISBAD', 
    exclude_cols=['ID', 'CREATE_TIME', 'OVD_BAL', 'AMOUNT'],
    algorithm='gbdt',
    max_depth=3,                # 减小深度
    min_samples_split=20,        # 增加分裂样本数限制
    min_samples_leaf=10,         # 增加叶子节点样本数限制
    n_estimators=100,           # 减少树的数量
    learning_rate=0.1,          # 增大学习率，加快训练速度
    max_features='sqrt',         # 平衡特征多样性
    random_state=42
)
```

**实际使用建议**：
1. **第一阶段**：使用配置1生成高质量规则
2. **第二阶段**：筛选高lift和高badrate_reduction的规则
3. **第三阶段**：使用配置2快速验证规则效果
4. **第四阶段**：结合业务知识，选择最优规则组合

#### 1.8.5.3 RF和GBDT组合使用策略

**组合使用优势**：
- RF生成多样化规则，GBDT生成高质量规则
- 两者互补，提高规则覆盖范围
- 结合两者优势，提升整体策略效果

**组合使用示例**：

```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=300,
    max_features='log2',
    random_state=42
)

tree_miner_rf.train()
rf_rules = tree_miner_rf.extract_rules()
rf_eval = tree_miner_rf.evaluate_rules()

# 使用GBDT生成高质量规则
tree_miner_gbdt = TreeRuleExtractor(
    df, 
    target_col='ISBAD', 
    exclude_cols=['ID', 'CREATE_TIME', 'OVD_BAL', 'AMOUNT'],
    algorithm='gbdt',
    max_depth=5,
    min_samples_split=10,
    min_samples_leaf=8,
    n_estimators=200,
    learning_rate=0.05,
    max_features='sqrt',
    random_state=42
)

tree_miner_gbdt.train()
gbdt_rules = tree_miner_gbdt.extract_rules()
gbdt_eval = tree_miner_gbdt.evaluate_rules()

# 合并评估结果
all_eval = pd.concat([rf_eval, gbdt_eval], ignore_index=True)

# 筛选高效规则
high_efficiency_rules = all_eval[(
    all_eval['test_lift'] > 2.0 & 
    all_eval['test_badrate_reduction'] > 0.3 & 
    all_eval['test_loss_lift'] > 1.5
)]

# 去重
high_efficiency_rules = high_efficiency_rules.drop_duplicates(subset=['rule'])

print(f"RF规则数量: {len(rf_rules)}")
print(f"GBDT规则数量: {len(gbdt_rules)}")
print(f"高效规则数量: {len(high_efficiency_rules)}")
print("Top 10 高效规则:")
print(high_efficiency_rules[['rule', 'test_lift', 'test_badrate_reduction', 'test_loss_lift']].head(10))
```

**组合使用最佳实践**：
1. **并行训练**：同时训练RF和GBDT，提高效率
2. **规则合并**：合并两个算法的规则，增加多样性
3. **综合评估**：结合多个指标筛选高效规则
4. **去重处理**：去除重复规则，避免冗余
5. **业务验证**：结合业务知识，选择最优规则组合

##### 1.8.5 孤立森林（ISF）

```python
# 初始化孤立森林规则提取器，使用特征趋势判断
tree_miner_isf = TreeRuleExtractor(
    df, 
    target_col='ISBAD', 
    exclude_cols=['ID', 'CREATE_TIME', 'OVD_BAL', 'AMOUNT'],
    algorithm='isf',
    n_estimators=50,
    random_state=42,
    feature_trends={
        'ALI_FQZSCORE': -1,      # 负相关：分数越低，违约概率越高
        'BAIDU_FQZSCORE': -1,    # 负相关：分数越低，违约概率越高
        'NUMBER OF LOAN APPLICATIONS TO PBOC': 1  # 正相关：申请次数越多，违约概率越高
    }
)

# 训练模型
mean_score, std_score = tree_miner_isf.train()
print(f"平均异常分数: {mean_score:.4f}")
print(f"标准差: {std_score:.4f}")

# 提取规则
isf_rules = tree_miner_isf.extract_rules()
print(f"提取的异常规则数量: {len(isf_rules)}")

# 打印规则
tree_miner_isf.print_rules(top_n=5)
```

#### 1.9 可视化功能

##### 1.9.1 特征重要性图

```python
# 绘制特征重要性图
tree_miner.plot_feature_importance(save_path='images/tree_feature_importance.png')
```

##### 1.9.2 决策树结构图

```python
# 绘制决策树结构（仅适用于dt、chi2算法）
tree_miner.plot_decision_tree(save_path='images/tree_decision_structure.pdf')
```

##### 1.9.3 规则评估图

```python
# 绘制规则评估图
tree_miner.plot_rule_evaluation(save_path='images/tree_rule_evaluation.png')
```

#### 1.10 打印规则

```python
# 打印Top 5规则
tree_miner.print_rules(top_n=5)
```

---

### 2. 单特征规则挖掘（SingleFeatureRuleMiner）

用于对数据各特征的不同阈值进行效度分布分析。

#### 2.1 初始化参数详解

```python
from rulelift import SingleFeatureRuleMiner

# 初始化单特征规则挖掘器（不使用损失率指标）
sf_miner = SingleFeatureRuleMiner(
    df, 
    exclude_cols=['ID', 'CREATE_TIME', 'OVD_BAL', 'AMOUNT'],
    target_col='ISBAD'
)

# 初始化单特征规则挖掘器（使用损失率指标）
sf_miner_with_loss = SingleFeatureRuleMiner(
    df, 
    exclude_cols=['ID', 'CREATE_TIME', 'OVD_BAL', 'AMOUNT'],
    target_col='ISBAD',
    amount_col='AMOUNT',      # 金额字段名
    ovd_bal_col='OVD_BAL'      # 逾期金额字段名
)

# 初始化单特征规则挖掘器（使用卡方分箱）
sf_miner_chi2 = SingleFeatureRuleMiner(
    df, 
    exclude_cols=['ID', 'CREATE_TIME', 'OVD_BAL', 'AMOUNT'],
    target_col='ISBAD',
    algorithm='chi2',        # 使用卡方分箱算法
    binning_threshold=50,   # 唯一值数量阈值
    min_bin_ratio=0.05     # 最小分箱比例
)
```

#### 2.2 参数详细说明

| 参数 | 类型 | 默认值 | 说明 |
|------|------|----------|------|
| `df` | DataFrame | 必填 | 输入的数据集 |
| `exclude_cols` | List[str] | `None` | 排除的字段名列表 |
| `target_col` | str | `'ISBAD'` | 目标字段名 |
| `amount_col` | str | `None` | 金额字段名，用于计算损失率指标 |
| `ovd_bal_col` | str | `None` | 逾期金额字段名，用于计算损失率指标 |
| `algorithm` | str | `'quantile'` | 分箱算法：'quantile'（等频分箱，默认）、'chi2'（卡方分箱） |
| `binning_threshold` | int | `50` | 唯一值数量阈值，超过才分箱 |
| `min_bin_ratio` | float | `0.05` | 最小分箱比例，用于卡方分箱 |
| `algorithm` | str | `'quantile'` | 分箱算法：'quantile'（等频，默认）、'chi2'（卡方） |
| `binning_threshold` | int | `50` | 唯一值数量阈值，超过才分箱 |
| `min_bin_ratio` | float | `0.05` | 最小分箱比例，用于卡方分箱 |

#### 2.3 分析单个特征

```python
# 分析单个特征
feature = 'ALI_FQZSCORE'
metrics_df = sf_miner.calculate_single_feature_metrics(feature, num_bins=20)
print(f"\n=== {feature} 分箱分析 ===")
print(metrics_df.head())

# 获取Top规则
top_rules = sf_miner.get_top_rules(feature=feature, top_n=5, metric='lift', min_samples=10)
print(f"\n=== Top 5规则 ===")
print(top_rules[['rule_description', 'lift', 'badrate', 'selected_samples']])
```

#### 2.4 参数详细说明

| 参数 | 类型 | 默认值 | 说明 |
|------|------|----------|------|
| `feature` | str | 必填 | 特征名 |
| `num_bins` | int | `20` | 分箱数量 |
| `top_n` | int | `10` | 返回的规则数量 |
| `metric` | str | `'lift'` | 排序指标：'lift'、'badrate'、'loss_rate'、'loss_lift'等 |
| `min_samples` | int | `10` | 最小样本数过滤 |
| `min_lift` | float | `1.1` | 最小lift值过滤 |

#### 2.5 输出示例

```
=== Top 5规则 ===
                           rule_description      lift  badrate  selected_samples
0  ALI_FQZSCORE <= 665.0000  2.174292  0.666667              51
1  ALI_FQZSCORE <= 688.5000  2.087320  0.640000              75
2  ALI_FQZSCORE <= 705.0000  1.993101  0.611111             108
3  ALI_FQZSCORE <= 725.0000  1.928934  0.580000             150
4  ALI_FQZSCORE <= 745.0000  1.867925  0.555556             180
```

#### 2.6 可视化

```python
# 绘制特征指标分布图
plt = sf_miner.plot_feature_metrics(feature, metric='lift')
plt.savefig(f'{feature}_lift_distribution.png', dpi=300, bbox_inches='tight')
plt.close()
```

---

### 3. 多特征交叉规则挖掘（MultiFeatureRuleMiner）

用于生成双特征交叉分析结果，支持自定义分箱阈值、自动分箱、卡方分箱等多种分箱策略。支持损失率指标计算。

#### 3.1 初始化参数详解

```python
from rulelift import MultiFeatureRuleMiner

# 初始化多特征规则挖掘器（不使用损失率指标）
multi_miner = MultiFeatureRuleMiner(df, target_col='ISBAD')

# 初始化多特征规则挖掘器（使用损失率指标）
multi_miner_with_loss = MultiFeatureRuleMiner(
    df, 
    target_col='ISBAD',
    amount_col='AMOUNT',      # 金额字段名
    ovd_bal_col='OVD_BAL'      # 逾期金额字段名
)
```

#### 3.2 参数详细说明

| 参数 | 类型 | 默认值 | 说明 |
|------|------|----------|------|
| `df` | DataFrame | 必填 | 输入的数据集 |
| `target_col` | str | `'ISBAD'` | 目标字段名 |
| `amount_col` | str | `None` | 金额字段名，用于计算损失率指标 |
| `ovd_bal_col` | str | `None` | 逾期金额字段名，用于计算损失率指标 |

#### 3.3 生成交叉矩阵

```python
feature1 = 'ALI_FQZSCORE'
feature2 = 'BAIDU_FQZSCORE'

# 生成交叉矩阵
cross_matrix = multi_miner.generate_cross_matrix(
    feature1, feature2,
    max_unique_threshold=5,
    custom_bins1=None,
    custom_bins2=None,
    binning_method='quantile'
)

# 查看交叉矩阵
print(cross_matrix.head())
```

#### 3.3.1 交叉矩阵自定义分箱详解

交叉矩阵支持自定义分箱参数，允许用户根据业务知识调整分箱方式，生成更符合业务需求的规则。

**自定义分箱使用示例**：

```python
# 生成交叉矩阵，使用自定义分箱阈值
feature1 = 'ALI_FQZSCORE'
feature2 = 'BAIDU_FQZSCORE'

# 自定义分箱阈值
custom_bins1 = [0, 600, 700, 750, 800, 850, 900, 1000]
custom_bins2 = [0, 500, 600, 700, 800, 900, 1000]

# 使用自定义分箱生成交叉矩阵
cross_matrix_custom = multi_miner.generate_cross_matrix(
    feature1, feature2,
    max_unique_threshold=10,
    custom_bins1=custom_bins1,  # 自定义第一个特征的分箱阈值
    custom_bins2=custom_bins2,  # 自定义第二个特征的分箱阈值
    binning_method='chi2'        # 卡方分箱方法
)

print("自定义分箱交叉矩阵:")
print(cross_matrix_custom.head())
```

**交叉矩阵分箱参数说明**：

| 参数 | 类型 | 默认值 | 说明 |
|------|------|----------|------|
| `custom_bins1` | List[float] | `None` | 第一个特征的自定义分箱阈值列表 |
| `custom_bins2` | List[float] | `None` | 第二个特征的自定义分箱阈值列表 |
| `binning_method` | str | `'quantile'` | 分箱方法：'quantile'（等频）、'equal_width'（等宽）、'chi2'（卡方） |
| `max_unique_threshold` | int | `5` | 最大允许的唯一值数量阈值，超过则进行分箱 |

**不同分箱方法对比**：

| 分箱方法 | 优点 | 缺点 | 适用场景 |
|----------|------|------|----------|
| **quantile** | 每个分箱样本数量均衡 | 数值范围可能差异大 | 连续型变量，样本分布不均匀 |
| **equal_width** | 数值范围均匀，易于理解 | 样本数量可能差异大 | 连续型变量，样本分布均匀 |
| **chi2** | 基于统计检验，分箱最优 | 计算复杂，耗时较长 | 风控场景，追求最优分箱效果 |

**交叉矩阵自定义分箱最佳实践**：

1. **结合业务知识**：根据业务经验设置合理的分箱阈值
2. **考虑变量分布**：连续型变量优先使用卡方分箱
3. **控制分箱数量**：每个特征的分箱数量建议在5-10之间
4. **平衡样本数**：确保每个交叉组合的样本数足够（建议≥50）
5. **验证分箱效果**：检查badrate是否呈现单调性或明显的风险趋势

#### 3.3.2 交叉矩阵Excel导出自定义分箱

```python
# 生成交叉矩阵Excel，使用自定义分箱
cross_matrices = multi_miner.generate_cross_matrices_excel(
    features_list=['ALI_FQZSCORE', 'BAIDU_FQZSCORE'],
    output_path='cross_analysis_custom_bins.xlsx',
    metrics=['badrate', 'count', 'sample_ratio', 'lift', 'loss_rate', 'loss_lift'],
    binning_method='chi2',
    custom_bins1=[0, 600, 700, 750, 800, 850, 900, 1000],
    custom_bins2=[0, 500, 600, 700, 800, 900, 1000]
)
print(f"自定义分箱交叉矩阵Excel已保存到: cross_analysis_custom_bins.xlsx")
```

#### 3.4 参数详细说明

| 参数 | 类型 | 默认值 | 说明 |
|------|------|----------|------|
| `feature1` | str | 必填 | 第一个特征名 |
| `feature2` | str | 必填 | 第二个特征名 |
| `max_unique_threshold` | int | `5` | 最大允许的唯一值数量阈值，超过则进行分箱 |
| `custom_bins1` | List[float] | `None` | 第一个特征的自定义分箱阈值 |
| `custom_bins2` | List[float] | `None` | 第二个特征的自定义分箱阈值 |
| `binning_method` | str | `'quantile'` | 分箱方法：'quantile'（等频）或'chi2'（卡方） |

#### 3.5 支持的指标说明

多特征交叉分析支持多种指标，帮助策略人员全面评估特征组合的风险水平和业务价值：

| 指标 | 定义 | 业务意义 |
|------|------|----------|
| `badrate` | 坏样本比例 = 坏样本数 / 总样本数 | 直接反映该特征组合下的风险水平 |
| `count` | 样本数量 | 反映该特征组合的覆盖范围 |
| `bad_count` | 坏样本数量 | 该特征组合下的坏客户数量 |
| `sample_ratio` | 样本占比 = 该组合样本数 / 总样本数 | 反映该特征组合的业务重要性 |
| `lift` | 提升度 = 该组合badrate / 总样本badrate | 反映该特征组合的风险区分能力，值越大效果越好 |
| `loss_rate` | 损失率 = 损失金额 / 总金额 | 反映该特征组合的实际损失程度（需要提供amount_col和ovd_bal_col） |
| `loss_lift` | 损失提升度 = 该组合loss_rate / 总样本loss_rate | 反映该特征组合的损失区分能力（需要提供amount_col和ovd_bal_col） |

#### 3.6 生成交叉矩阵Excel文件

```python
# 生成交叉矩阵Excel文件（方便策略人员根据交叉矩阵制订规则）
cross_matrices = multi_miner.generate_cross_matrices_excel(
    features_list=['ALI_FQZSCORE', 'BAIDU_FQZSCORE'], 
    output_path='cross_analysis.xlsx'
)
print(f"交叉矩阵Excel文件已保存到: cross_analysis.xlsx")

# 查看生成的Excel文件
# 文件包含多个sheet，每个sheet对应一个特征组合
# 每个sheet包含：badrate、count、sample_ratio、lift等指标
```

#### 3.7 多特征两两交叉分析

支持传入多个特征，自动生成所有两两特征组合的交叉矩阵，方便策略人员全面分析特征间的交互关系。

```python
# 多特征两两交叉分析示例
features_list = ['ALI_FQZSCORE', 'BAIDU_FQZSCORE', 'NUMBER OF LOAN APPLICATIONS TO PBOC']
cross_matrices_multi = multi_miner.generate_cross_matrices_excel(
    features_list=features_list,
    output_path='cross_analysis_multi_features.xlsx',
    metrics=['badrate', 'count', 'sample_ratio', 'lift', 'loss_rate', 'loss_lift'],  # 支持多种指标分析
    binning_method='quantile'  # 支持等频分箱
)
print(f"多特征交叉矩阵Excel文件已保存到: cross_analysis_multi_features.xlsx")
```

#### 3.8 参数详细说明

| 参数 | 类型 | 默认值 | 说明 |
|------|------|----------|------|
| `features_list` | List[str] | 必填 | 特征清单列表，用于多特征两两组合生成矩阵 |
| `feature1` | str | `None` | 第一个特征名（兼容旧版本，当features_list为None时使用） |
| `feature2` | str | `None` | 第二个特征名（兼容旧版本，当features_list为None时使用） |
| `max_unique_threshold` | int | `5` | 最大允许的唯一值数量阈值，超过则进行分箱 |
| `custom_bins1` | List[float] | `None` | 第一个特征的自定义分箱阈值（仅当features_list长度为2时有效） |
| `custom_bins2` | List[float] | `None` | 第二个特征的自定义分箱阈值（仅当features_list长度为2时有效） |
| `binning_method` | str | `'quantile'` | 分箱方法：'quantile'（等频）或'chi2'（卡方） |
| `output_path` | str | `'cross_analysis.xlsx'` | Excel输出路径 |
| `metrics` | List[str] | `['badrate', 'count', 'sample_ratio']` | 要导出的指标列表，可选：'badrate', 'count', 'bad_count', 'sample_ratio', 'lift', 'loss_rate', 'loss_lift' |

#### 3.9 交叉矩阵Excel文件示例

生成的Excel文件包含多个sheet，每个sheet对应一个特征组合，例如：
- `ALI_FQZSCORE_x_BAIDU_FQZSCORE`：两个特征的交叉矩阵
- `ALI_FQZSCORE_x_NUMBER OF LOAN APPLICATIONS TO PBOC`：另一个特征组合
- 每个sheet包含以下指标：badrate、count、sample_ratio、lift等
- 策略人员可以根据交叉矩阵中的高lift区域制订规则

**Excel文件内容示例**：

| ALI_FQZSCORE | BAIDU_FQZSCORE | badrate | count | sample_ratio | lift |
|--------------|----------------|---------|-------|--------------|------|
| (500, 600]   | (300, 400]     | 0.6667  | 15    | 0.03         | 2.5  |
| (500, 600]   | (400, 500]     | 0.4000  | 25    | 0.05         | 1.5  |
| (600, 700]   | (300, 400]     | 0.5000  | 20    | 0.04         | 1.9  |
| (600, 700]   | (400, 500]     | 0.2000  | 30    | 0.06         | 0.8  |
| (700, 800]   | (300, 400]     | 0.3000  | 18    | 0.036        | 1.15 |
| (700, 800]   | (400, 500]     | 0.1500  | 40    | 0.08         | 0.58 |

**包含损失率指标的Excel示例**（需要在初始化时提供amount_col和ovd_bal_col）：

| ALI_FQZSCORE | BAIDU_FQZSCORE | badrate | count | loss_rate | loss_lift |
|--------------|----------------|---------|-------|-----------|-----------|
| (500, 600]   | (300, 400]     | 0.6667  | 15    | 0.4567    | 2.89      |
| (500, 600]   | (400, 500]     | 0.4000  | 25    | 0.3210    | 2.01      |
| (600, 700]   | (300, 400]     | 0.5000  | 20    | 0.2890    | 1.81      |
| (600, 700]   | (400, 500]     | 0.2000  | 30    | 0.1567    | 0.98      |

#### 3.10 获取Top规则

```python
# 获取Top规则
top_rules = multi_miner.get_cross_rules(
    feature1, feature2,
    top_n=10,
    metric='lift',
    min_samples=10,
    min_lift=1.1,
    max_unique_threshold=5,
    custom_bins1=None,
    custom_bins2=None,
    binning_method='quantile'
)

print(top_rules[['feature1_value', 'feature2_value', 'count', 'badrate', 'lift', 'rule_description']])
```

#### 3.11 可视化

```python
# 绘制交叉热力图
plt = multi_miner.plot_cross_heatmap(feature1, feature2, metric='lift')
plt.savefig('images/cross_feature_heatmap.png', dpi=300, bbox_inches='tight')
plt.close()
```

---

### 4. 变量分析（VariableAnalyzer）

支持对特征变量进行全面的效度分析和分箱分析，帮助风控团队识别重要变量，优化特征工程。

#### 4.1 初始化参数详解

```python
from rulelift import VariableAnalyzer

# 初始化变量分析器（不使用损失率指标）
var_analyzer = VariableAnalyzer(
    df, 
    exclude_cols=['ID', 'CREATE_TIME', 'OVD_BAL', 'AMOUNT'], 
    target_col='ISBAD'
)

# 初始化变量分析器（使用损失率指标）
var_analyzer_with_loss = VariableAnalyzer(
    df, 
    exclude_cols=['ID', 'CREATE_TIME', 'OVD_BAL', 'AMOUNT'], 
    target_col='ISBAD',
    amount_col='AMOUNT',      # 金额字段名
    ovd_bal_col='OVD_BAL'      # 逾期金额字段名
)
```

#### 4.2 参数详细说明

| 参数 | 类型 | 默认值 | 说明 |
|------|------|----------|------|
| `df` | DataFrame | 必填 | 输入的数据集 |
| `exclude_cols` | List[str] | `None` | 排除的字段名列表 |
| `target_col` | str | `'ISBAD'` | 目标字段名 |
| `amount_col` | str | `None` | 金额字段名，用于计算损失率指标 |
| `ovd_bal_col` | str | `None` | 逾期金额字段名，用于计算损失率指标 |

#### 4.3 分析所有变量的效度指标

```python
# 分析所有变量的效度指标
var_metrics = var_analyzer.analyze_all_variables()
print("\n=== 所有变量效度指标 ===")
print(var_metrics)
```

#### 4.4 变量分箱分布分析

变量分析支持多种分箱方式，包括自动分箱和自定义分箱，帮助风控团队深入理解变量分布和风险特征。

### 4.4.1 自定义分箱功能

**使用方式**：
```python
# 分析单个变量的分箱情况，使用自定义分箱阈值
feature = 'ALI_FQZSCORE'

# 自定义分箱阈值
custom_bins = [0, 600, 700, 750, 800, 850, 900, 1000]

# 使用自定义分箱
bin_analysis = var_analyzer.analyze_single_variable(
    feature, 
    n_bins=7,  # 分箱数量应比自定义阈值数量少1
    custom_bins=custom_bins,  # 传入自定义分箱阈值
    binning_method='chi2'  # 使用卡方分箱方法
)

print(f"\n=== {feature} 自定义分箱分析 ===")
print(bin_analysis)
```

**参数详细说明**：

| 参数 | 类型 | 默认值 | 说明 |
|------|------|----------|------|
| `feature` | str | 必填 | 特征名 |
| `n_bins` | int | `10` | 分箱数量 |
| `custom_bins` | list | `None` | 自定义分箱阈值列表，如[0, 50, 100, 150] |
| `binning_method` | str | `'quantile'` | 分箱方法：'quantile'（等频）、'equal_width'（等宽）、'chi2'（卡方） |
| `psi_dt` | str | `None` | PSI计算分割日期 |
| `date_col` | str | `None` | 日期字段名 |

### 4.4.2 支持的分箱方法

| 分箱方法 | 定义 | 优点 | 缺点 | 适用场景 |
|----------|------|------|------|----------|
| **quantile** | 等频分箱，每个分箱样本数量大致相等 | 样本分布均衡，避免极端分箱 | 数值范围可能差异较大 | 连续型变量，样本分布不均匀 |
| **equal_width** | 等宽分箱，每个分箱数值范围相等 | 数值范围均匀，易于理解 | 样本数量可能差异较大 | 连续型变量，样本分布均匀 |
| **chi2** | 基于卡方检验的最优分箱 | 基于统计检验，分箱效果最优 | 计算复杂，耗时较长 | 风控场景，追求最优分箱效果 |

### 4.4.3 输出示例

```
=== 所有变量效度指标 ===
        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      lift  loss_rate  loss_lift
0  (0.0, 600.0]        85         62         23   0.7294        0.1700          0.7294      3.2567  0.4567    2.8901
1  (600.0, 700.0]      120         78         42   0.6500        0.2400          0.6847      2.9130  0.3890    2.4312
2  (700.0, 750.0]       95         55         40   0.5789        0.1900          0.6461      2.5739  0.3210    2.0063
3  (750.0, 800.0]       80         45         35   0.5625        0.1600          0.6208      2.5000  0.2890    1.8063
4  (800.0, 850.0]       65         32         33   0.4923        0.1300          0.5952      2.1878  0.2456    1.5350
5  (850.0, 900.0]       45         18         27   0.4000        0.0900          0.5702      1.7778  0.1890    1.1813
6  (900.0, 1000.0]      10         2          8    0.2000        0.0200          0.5574      0.8889  0.0987    0.6169
```

### 4.4.4 变量分箱最佳实践

1. **连续型变量**：
   - 优先使用卡方分箱，生成最优分箱
   - 结合业务知识调整分箱阈值
   - 确保每个分箱的样本数足够（建议≥100）
   - 检查badrate是否呈现单调性或明显的风险趋势

2. **离散型变量**：
   - 类别数≤10：直接使用原始类别
   - 类别数>10：使用等频或卡方分箱合并相似类别
   - 注意高基数类别变量的处理
   - 关注稀有类别的风险特征

3. **分箱结果应用**：
   - 选择badrate单调递增/递减的分箱结果
   - 关注lift值高的分箱区间
   - 结合loss_rate和loss_lift评估实际风险
   - 验证分箱结果的稳定性（PSI<0.1）

#### 4.5 参数详细说明

| 参数 | 类型 | 默认值 | 说明 |
|------|------|----------|------|
| `feature` | str | 必填 | 特征名 |
| `n_bins` | int | `10` | 分箱数量 |
| `psi_dt` | str | `None` | PSI计算分割日期 |
| `date_col` | str | `None` | 日期字段名 |

#### 4.6 输出示例

```
=== 所有变量效度指标 ===
        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
```

#### 4.7 变量效度指标说明

| 指标 | 定义 | 最佳范围 | 意义 |
|------|------|----------|------|
| `iv` | 信息值(Information Value) | > 0.1 | 变量的预测能力，值越大预测能力越强 |
| `ks` | KS统计量 | > 0.2 | 变量对好坏客户的区分能力，值越大区分能力越强 |
| `auc` | 曲线下面积 | > 0.6 | 变量的整体预测能力，值越大预测能力越强 |
| `missing_rate` | 缺失率 | < 0.1 | 变量的缺失值比例，值越小数据质量越好 |
| `single_value_rate` | 单值率 | < 0.05 | 变量的唯一值比例，值越小区分能力越强 |
| `min_value` | 最小值 | - | 变量的最小值 |
| `max_value` | 最大值 | - | 变量的最大值 |
| `median_value` | 中位数 | - | 变量的中位数，反映中心趋势 |
| `mean_diff` | 均值差异 | > 0.1 | 好坏客户均值差异，值越大区分能力越强 |
| `corr_with_target` | 与目标变量相关系数 | - | 变量与目标变量的相关性，值越大越重要 |
| `psi` | 群体稳定性指标(PSI) | < 0.1 | 变量的稳定性指标，值越小越稳定 |

#### 4.8 可视化

```python
# 可视化变量分箱结果
var_analyzer.plot_variable_bins(feature, n_bins=10)
plt.savefig(f'{feature}_bin_analysis.png', dpi=300, bbox_inches='tight')
plt.close()
```

---

### 5. 规则效度分析监控模块（analyze_rules）

用于实时评估上线规则的效度。解决规则拦截样本无标签的问题，借助客户评级分布差异，推算逾期率、召回率、精确率、lift 值等核心指标。

#### 5.1 初始化参数详解

```python
from rulelift import analyze_rules

# 通过用户评级评估规则效度
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  # 是否包含稳定性指标
)

# 通过目标标签评估规则效度
result_by_target = analyze_rules(
    hit_rule_df, 
    rule_col='RULE',
    user_id_col='USER_ID',
    user_target_col='USER_TARGET',  # 用户实际逾期标签字段
    hit_date_col='HIT_DATE',  # 命中日期，用于计算稳定性指标
    include_stability=True  # 是否包含稳定性指标
)

# 同时使用两种方式评估规则效度
result_combined = analyze_rules(
    hit_rule_df, 
    rule_col='RULE',
    user_id_col='USER_ID',
    user_level_badrate_col='USER_LEVEL_BADRATE',
    user_target_col='USER_TARGET',
    hit_date_col='HIT_DATE',
    include_stability=True  # 是否包含稳定性指标
)
```

#### 5.2 参数详细说明

| 参数 | 类型 | 默认值 | 说明 |
|------|------|----------|------|
| `rule_score` | DataFrame | 必填 | 规则拦截客户信息 |
| `rule_col` | str | `'RULE'` | 规则字段名 |
| `user_id_col` | str | `'USER_ID'` | 用户编号字段名 |
| `user_level_badrate_col` | str | `None` | 用户评级坏账率字段名（可选） |
| `user_target_col` | str | `None` | 用户实际逾期字段名（可选） |
| `hit_date_col` | str | `None` | 命中日期字段名（可选，用于命中率监控） |
| `metrics` | list | `None` | 指定要计算的指标列表（可选） |
| `include_stability` | bool | `True` | 是否包含稳定性指标 |

#### 5.3 评估方式说明

##### 5.3.1 通过用户评级评估规则

当用户没有实际逾期标签时，可以使用用户评级对应的坏账率来评估规则效果。

**计算指标**：
- `estimated_badrate_pred`: 预估坏账率
- `estimated_recall_pred`: 预估召回率
- `estimated_precision_pred`: 预估精确率
- `estimated_lift_pred`: 预估lift值

##### 5.3.2 通过目标标签评估规则

当用户有实际逾期标签时，可以直接使用目标标签来评估规则效果。

**计算指标**：
- `actual_badrate`: 实际坏账率
- `actual_recall`: 实际召回率
- `actual_precision`: 实际精确率
- `actual_lift`: 实际lift值
- `f1`: F1分数

##### 5.3.3 命中率相关指标

当提供了 `hit_date_col` 时，还会计算以下指标：

| 指标 | 定义 | 业务意义 |
|------|------|----------|
| `base_hit_rate` | 历史平均命中率 | 反映规则的历史命中情况 |
| `current_hit_rate` | 当天命中率 | 反映规则的当前命中情况 |
| `hit_rate_cv` | 命中率变异系数 = 标准差/均值 | 反映规则命中率的稳定性，值越小越稳定 |
| `hit_rate_change_rate` | 命中率变化率 = (当前命中率 - 历史平均命中率) / 历史平均命中率 | 反映规则命中率的变化趋势 |

##### 5.3.4 稳定性指标

当提供了 `hit_date_col` 且 `include_stability=True` 时，还会计算以下稳定性指标：

| 指标 | 定义 | 业务意义 |
|------|------|----------|
| `hit_rate_std` | 命中率标准差 | 反映规则命中率的波动程度 |
| `hit_rate_cv` | 命中率变异系数 | 反映规则命中率的稳定性，值越小越稳定 |
| `max_monthly_change` | 最大月度变化率 | 反映规则命中率的最大波动 |
| `min_monthly_change` | 最小月度变化率 | 反映规则命中率的最小波动 |
| `avg_monthly_change` | 平均月度变化率 | 反映规则命中率的平均变化趋势 |
| `months_analyzed` | 分析的月份数量 | 反映分析的时间跨度 |

#### 5.4 规则相关性分析

```python
from rulelift import analyze_rule_correlation

# 规则相关性分析
correlation_matrix, max_correlation = analyze_rule_correlation(
    hit_rule_df, 
    rule_col='RULE', 
    user_id_col='USER_ID'
)
print(f"   规则相关性矩阵:")
print(correlation_matrix)
print(f"   每条规则的最大相关性:")
for rule, corr in max_correlation.items():
    print(f"   {rule}: {corr['max_correlation_value']:.4f}")
```

**输出示例**：

```
规则相关性矩阵:
          rule1     rule2     rule3
rule1  1.000000  0.234567  0.345678
rule2  0.234567  1.000000  0.456789
rule3  0.345678  0.456789  1.000000

每条规则的最大相关性:
rule1: 0.3457
rule2: 0.4568
rule3: 0.4568
```

#### 5.5 输出示例

```
=== 规则效度分析结果 ===
         RULE  actual_lift  actual_badrate  actual_recall        f1
0  rule1     2.3456789      0.3456789      0.456789  0.3456789
1  rule2     2.123456      0.234567       0.3456789  0.234567
2  rule3     1.987654      0.123456       0.234567  0.123456
```

---

### 6. 策略相关性、增益计算（calculate_strategy_gain）

评估策略组合效果，计算两两规则间的增益。

#### 6.1 初始化参数详解

```python
from rulelift import calculate_strategy_gain

# 定义两个策略组
strategy1 = ['rule1', 'rule2']
strategy2 = ['rule1', 'rule2', 'rule3']

# 计算策略增益（strategy1 到 strategy2 的额外价值）
gain = calculate_strategy_gain(
    hit_rule_df, 
    strategy1, 
    strategy2, 
    user_target_col='USER_TARGET'
)
print(f"\n策略增益: {gain:.4f}")
```

#### 6.2 参数详细说明

| 参数 | 类型 | 默认值 | 说明 |
|------|------|----------|------|
| `rule_score` | DataFrame | 必填 | 规则拦截客户信息 |
| `strategy_a_rules` | list | 必填 | 策略A的规则列表 |
| `strategy_b_rules` | list | 必填 | 策略B的规则列表 |
| `user_target_col` | str | `None` | 用户实际逾期字段名（可选） |
| `user_level_badrate_col` | str | `None` | 用户评级坏账率字段名（可选） |

#### 6.3 增益指标说明

| 指标 | 定义 | 业务意义 |
|------|------|----------|
| `gain_users` | 策略A在策略B之后新增的拦截用户数 | 反映策略A的额外覆盖能力 |
| `gain_bads` | 新增拦截用户中的坏客户数 | 反映策略A的额外拦截能力 |
| `gain_badrate` | 新增拦截用户的坏账率 | 反映新增拦截用户的质量 |
| `gain_lift` | 新增拦截用户坏账率相对于策略B坏账率的增益（倍数） | 反映策略A的额外价值 |
| `gain_coverage` | 新增拦截用户占总样本的比例 | 反映策略A的额外覆盖范围 |
| `gain_recall` | 新增拦截用户中的坏客户占总坏客户的比例 | 反映策略A的额外召回能力 |
| `b_hit_users` | 策略B拦截的用户数 | 反映策略B的覆盖范围 |
| `b_badrate` | 策略B拦截用户的坏账率 | 反映策略B的拦截质量 |

#### 6.4 输出示例

```
策略增益: 1.2345
```

---

## 常见问题（FAQ）

### Q1: 如何选择合适的规则挖掘算法？

**A**: 根据不同的业务场景选择算法：
- **DT（决策树）**：适合快速探索和初步分析，规则简单易懂
- **RF（随机森林）**：适合生产环境，规则稳定性好，多样性高
- **CHI2（卡方随机森林）**：适合需要统计最优分箱的场景，基于卡方检验的分箱预处理
- **GBDT（梯度提升树）**：适合复杂场景，规则精度高
- **ISF（孤立森林）**：适合挖掘异常样本的规则

**B**: 根据数据量和特征数量选择：
- **需要高质量规则**：选择 GBDT，生成的规则精度更高
- **需要多样化规则**：选择随机森林，生成的规则更具多样性
- **数据量较大**：GBDT 和随机森林都适用，但随机森林训练速度更快
- **特征重要性清晰**：GBDT 能提供更准确的特征重要性

### Q2: 如何配置特征趋势（feature_trends）？

**A**: 特征趋势用于避免不符合业务解释性的规则。

**B**: 配置方式：
```python
feature_trends={
    'ALI_FQZSCORE': -1,      # 负相关：分数越低，违约概率越高
    'BAIDU_FQZSCORE': -1,    # 负相关：分数越低，违约概率越高
    'NUMBER OF LOAN APPLICATIONS TO PBOC': 1  # 正相关：申请次数越多，违约概率越高
}
```

**C**: 业务含义：
- **正相关（值为1）**：表示特征数值越大，目标标签（违约概率）越高，只保留大于阈值的规则
- **负相关（值为-1）**：表示特征数值越小，目标标签（违约概率）越高，只保留小于等于阈值的规则

### Q3: 如何调整参数以获得更好的规则？

**A**: 根据目标调整参数：

**生成简单规则**：
- 增加 `max_depth`（建议3-5）
- 增加 `min_samples_split`（建议15-20）
- 增加 `min_samples_leaf`（建议10-15）

**生成复杂规则**：
- 减小 `max_depth`（建议6-10）
- 减小 `min_samples_split`（建议5-10）
- 减小 `min_samples_leaf`（建议3-8）

**提高规则多样性**：
- 增加 `n_estimators`（建议100-500）
- 使用 `max_features='log2'` 或手动设置较大值

**平衡规则复杂度和泛化能力**：
- `max_depth`：5-8
- `min_samples_leaf`：5-10

### Q4: 如何评估规则效果？

**A**: 使用以下指标评估规则：
- **test_lift**：规则的风险区分能力，值越大效果越好（建议 > 2.0）
- **test_badrate_reduction**：策略效率指标，每1%命中率带来的badrate降低幅度（建议 > 0.3）
- **test_loss_lift**：损失区分能力（建议 > 1.5）
- **test_precision**：精确率（建议 > 0.6）
- **test_recall**：召回率（建议 > 0.4）
- **test_f1**：F1分数（建议 > 0.5）

### Q5: 如何处理缺失值？

**A**: rulelift 库会自动处理缺失值：
- **数值型特征**：填充为 0
- **类别型特征**：填充为 'missing' 字符串
- **规则挖掘**：在计算指标时自动忽略缺失值

### Q6: 如何使用损失率指标？

**A**: 需要在初始化时提供金额字段和逾期金额字段：

```python
# 初始化时提供金额字段
tree_miner_with_loss = TreeRuleExtractor(
    df,
    target_col='ISBAD',
    exclude_cols=['ID', 'CREATE_TIME', 'OVD_BAL', 'AMOUNT'],
    algorithm='gbdt',
    amount_col='AMOUNT',      # 金额字段名
    ovd_bal_col='OVD_BAL'      # 逾期金额字段名
)
```

**B**: 损失率指标说明：
- **loss_rate**：特定规则或特征组合下，逾期金额总和除以总金额总和
- **loss_lift**：该组合loss_rate / 总样本loss_rate，反映损失区分能力

### Q7: 卡方随机森林如何工作？

**A**: 卡方随机森林采用"卡方分箱预处理 + 随机森林"的方式实现：

**B**: 实现步骤：
1. **卡方分箱预处理**：对每个数值型特征进行卡方分箱，基于统计检验合并相似分箱
2. **特征值替换**：将原始特征值替换为卡方分箱的上限
3. **随机森林训练**：基于卡方分箱后的特征值进行随机森林训练
4. **规则提取**：从随机森林中提取决策路径作为规则

**C**: 优势：
- ✅ 实现简单，不需要复杂的自定义决策树分裂逻辑
- ✅ 基于统计检验的最优分箱
- ✅ 可以完全复用随机森林的训练和规则提取逻辑
- ✅ 提高规则挖掘的准确性和可解释性

---

## 核心指标说明

### 规则评估指标

| 指标 | 定义 | 最佳范围 | 意义 |
|------|------|----------|------|
| `actual_lift` | 规则命中样本逾期率 / 总样本逾期率 | > 1.0 | 规则的风险区分能力，值越大效果越好 |
| `f1` | 2*(精确率*召回率)/(精确率+召回率) | 0-1 | 综合评估规则的精确率和召回率 |
| `actual_badrate` | 规则命中样本中的逾期比例 | 依业务场景而定 | 规则直接拦截的坏客户比例 |
| `actual_recall` | 规则命中的坏客户 / 总坏客户 | 0-1 | 规则对坏客户的覆盖能力 |
| `hit_rate_cv` | 命中率变异系数 = 标准差/均值 | < 0.2 | 规则命中率的稳定性，值越小越稳定 |
| `max_correlation_value` | 与其他规则的最大相关系数 | < 0.5 | 规则的独立性，值越小独立性越好 |

### 变量分析指标

| 指标 | 定义 | 最佳范围 | 意义 |
|------|------|----------|------|
| `iv` | 信息值(Information Value) | > 0.1 | 变量的预测能力，值越大预测能力越强 |
| `ks` | KS统计量 | > 0.2 | 变量对好坏客户的区分能力，值越大区分能力越强 |
| `auc` | 曲线下面积 | > 0.6 | 变量的整体预测能力，值越大预测能力越强 |
| `badrate` | 分箱中的坏客户比例 | 依业务场景而定 | 分箱的风险水平 |
| `cum_badrate` | 累积坏客户比例 | 依业务场景而定 | 累积分箱的风险水平 |

---

## 版本信息

### 当前版本：1.3.0

### 版本历史

#### v1.3.0 (2026-01-27)
**新增功能**：
- ✅ SingleFeatureRuleMiner 支持卡方分箱算法（algorithm='chi2'）
- ✅ SingleFeatureRuleMiner 支持智能分箱策略（algorithm、binning_threshold、min_bin_ratio 参数）
- ✅ SingleFeatureRuleMiner 实现最优阈值选择算法（基于卡方分数或信息增益）
- ✅ TreeRuleExtractor 实现真正的卡方随机森林算法（卡方分箱预处理 + 随机森林）
- ✅ TreeRuleExtractor 添加 GBDT 正则化参数（learning_rate、subsample）
- ✅ TreeRuleExtractor 添加 min_bin_ratio 参数控制卡方分箱最小样本占比
- ✅ MultiFeatureRuleMiner 增强卡方分箱实现

**优化改进**：
- ✅ 算法重命名：'xgb' → 'gbdt'（保持向后兼容性）
- ✅ 标记 XGBoostRuleMiner 为 deprecated
- ✅ 修复 metrics/basic.py 语法错误
- ✅ 统一算法命名和术语

**文档更新**：
- ✅ 更新 README.md，添加新参数说明
- ✅ 更新 example.py，修复参数错误
- ✅ 添加快速开始指南
- ✅ 添加常见问题（FAQ）部分

#### v1.2.4 (2025-12-01)
**新增功能**：
- ✅ 初始版本发布

---

## 更新日志

### 2026-01-27
- 🎉 实现 SingleFeatureRuleMiner 卡方分箱功能
- 🎉 实现 TreeRuleExtractor 卡方随机森林算法
- 🎉 添加快速开始指南和 FAQ
- 🎉 修复所有文档错误和参数错误

### 2025-12-01
- 🎉 初始版本发布

---

## ❓ 常见问题（FAQ）

### Q1: 如何选择合适的规则挖掘算法？

**A**: 根据不同的业务场景选择算法：
- **DT（决策树）**：适合快速探索和初步分析，规则简单易懂
- **RF（随机森林）**：适合生产环境，规则稳定性好，多样性高
- **CHI2（卡方决策树）**：适合分类特征较多的场景
- **GBDT（梯度提升树）**：适合复杂场景，规则精度高
- **ISF（孤立森林）**：适合挖掘异常样本的规则

### Q2: 如何配置特征趋势（feature_trends）？

**A**: 特征趋势用于避免不符合业务解释性的规则：
```python
feature_trends={
    'ALI_FQZSCORE': -1,      # 负相关：分数越低，违约概率越高
    'BAIDU_FQZSCORE': -1,    # 负相关：分数越低，违约概率越高
    'NUMBER OF LOAN APPLICATIONS TO PBOC': 1  # 正相关：申请次数越多，违约概率越高
}
```

### Q3: 如何计算损失率指标？

**A**: 需要在初始化时提供金额字段和逾期金额字段：
```python
# 对于规则挖掘器
tree_miner = TreeRuleExtractor(
    df, 
    target_col='ISBAD',
    amount_col='AMOUNT',      # 金额字段名
    ovd_bal_col='OVD_BAL'      # 逾期金额字段名
)

# 对于多特征交叉规则挖掘器
multi_miner = MultiFeatureRuleMiner(
    df, 
    target_col='ISBAD',
    amount_col='AMOUNT',      # 金额字段名
    ovd_bal_col='OVD_BAL'      # 逾期金额字段名
)
```

### Q4: 如何评估规则的实际效果？

**A**: 使用 `analyze_rules` 函数评估规则效度：
```python
# 通过用户评级评估
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
)

# 通过目标标签评估
result_by_target = analyze_rules(
    hit_rule_df, 
    rule_col='RULE',
    user_id_col='USER_ID',
    user_target_col='USER_TARGET',
    hit_date_col='HIT_DATE',
    include_stability=True
)
```

### Q5: 如何识别冗余规则？

**A**: 使用规则相关性分析识别冗余规则：
```python
# 规则相关性分析
correlation_matrix, max_correlation = analyze_rule_correlation(
    hit_rule_df, 
    rule_col='RULE', 
    user_id_col='USER_ID'
)

# 查看每条规则的最大相关性
for rule, corr in max_correlation.items():
    print(f"{rule}: {corr['max_correlation_value']:.4f}")
```

如果两条规则的相关性过高（> 0.8），则说明它们存在冗余，可以考虑删除其中一条。

### Q6: 如何优化规则组合？

**A**: 使用策略增益计算评估不同规则组合的效果：
```python
# 定义两个策略组
strategy1 = ['rule1', 'rule2']
strategy2 = ['rule1', 'rule2', 'rule3']

# 计算策略增益
gain = calculate_strategy_gain(
    hit_rule_df, 
    strategy1, 
    strategy2, 
    user_target_col='USER_TARGET'
)
print(f"策略增益: {gain:.4f}")
```

如果增益值较高，说明添加新规则能带来显著价值。

### Q7: 如何在离线环境中使用？

**A**: 参考文档中的"离线使用方式"部分，主要有两种方式：
1. **离线安装rulelift及相关依赖**：在有网络的环境中下载依赖包，然后传输到离线环境安装
2. **通过源码直接调用**：下载源码包，手动安装依赖，然后在Python代码中添加源码路径并导入

### Q8: 如何处理缺失值？

**A**: rulelift 会自动处理缺失值：
- 对于数值型特征：缺失值会被填充为0
- 对于类别型特征：缺失值会被填充为'missing'
- 用户也可以在传入数据前自行处理缺失值

### Q9: 如何调整树模型的复杂度？

**A**: 通过以下参数控制树模型的复杂度：
- `max_depth`：决策树最大深度，值越大规则越复杂
- `min_samples_split`：分裂节点所需的最小样本数，值越大规则越保守
- `min_samples_leaf`：叶子节点的最小样本数，值越大叶子节点包含的样本越多
- `n_estimators`：树的数量，值越大模型越稳定但训练时间越长

### Q10: 如何导出规则分析结果？

**A**: 支持多种导出方式：
```python
# 导出为CSV
rules_df.to_csv('rules.csv', index=False, encoding='utf-8-sig')

# 导出为Excel
rules_df.to_excel('rules.xlsx', index=False)

# 生成交叉矩阵Excel文件
cross_matrices = multi_miner.generate_cross_matrices_excel(
    features_list=['ALI_FQZSCORE', 'BAIDU_FQZSCORE'], 
    output_path='cross_analysis.xlsx'
)
```

### Q11: 如何可视化分析结果？

**A**: rulelift 提供了丰富的可视化功能：
```python
# 特征重要性图
tree_miner.plot_feature_importance(save_path='feature_importance.png')

# 决策树结构图
tree_miner.plot_decision_tree(save_path='decision_tree.pdf')

# 规则评估图
tree_miner.plot_rule_evaluation(save_path='rule_evaluation.png')

# 交叉特征热力图
multi_miner.plot_cross_heatmap(feature1, feature2, metric='lift')
```

---

## 许可证

MIT License

---

## 项目地址

- GitHub: https://github.com/aialgorithm/rulelift
- PyPI: https://pypi.org/project/rulelift/

---

## 联系方式

微信&github: aialgorithm
邮箱: 15880982687@qq.com

---

## 贡献指南

欢迎提交 Issue 和 Pull Request！如果您有任何建议或问题，请通过 GitHub Issues 反馈。
 https://github.com/aialgorithm/rulelift/issues
---

**开始使用 rulelift 优化您的风控规则系统吧！** 🚀
