# rulelift - 信用风险规则有效性分析工具

## 项目概述

rulelift 是一个用于信用风险管理中策略规则自动挖掘、有效性分析及监控的 Python 工具包。
- 实时评估监控上线规则的效度；
- 自动化挖掘高价值的规则；

## 核心价值

在风控领域，规则系统因其配置便利和强解释性而广泛应用，但面临规则效果监控难、优化难的挑战。rulelift 提供了全面的解决方案：

- **规则实时评估**：解决规则拦截样本无标签的问题，借助客户评级分布差异，实时评估逾期率、召回率、精确率、lift 值、相关性、规则间的增益、稳定性等核心指标
- **规则自动挖掘**：自动从数据中挖掘有效的风控规则，支持单特征、多特征交叉、决策树、随机森林、XGB等规则挖掘
- **可视化展示**：直观呈现变量分布、变量效度、规则效果、特征重要性、决策树结构和规则关系
- **成本效益高**：无需分流测试，基于规则命中用户记录即可评估规则效果，降低测试成本

它帮助风控团队评估优化规则的实际效果，识别冗余规则，自动挖掘有效规则，优化策略组合，提高风险控制能力，降低风控成本。

## 完整的安装使用方法

### 使用 pip 安装（推荐）

```bash
pip install rulelift
```

### 从源码安装

```bash
git clone https://github.com/aialgorithm/rulelift.git
cd rulelift
pip install -e .
```

## 快速开始

### 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')


```

## 核心功能

### 1. 树规则提取（TreeRuleExtractor）

TreeRuleExtractor 是一个统一的树模型规则提取类，支持多种算法（DT、RF、CHI2、XGB、ISF）。支持业务解释性配置、支持树复杂度及规则精度配置、支持评估规则全面方面指标badrate、损失率指标等等；

#### 1.1 支持的算法

| 算法 | 说明 | 适用场景 |
|------|------|----------|
| `dt` | 决策树（Decision Tree） | 快速生成规则，适合初步探索 |
| `rf` | 随机森林（Random Forest） | 规则稳定性好，多样性高，适合生产环境 |
| `chi2` | 卡方决策树（Chi-square Decision Tree） | 适合分类特征较多的场景 |
| `xgb` | XGBoost（梯度提升树） | 规则精度高，适合复杂场景 |
| `isf` | 孤立森林（Isolation Forest） | 适合挖掘异常样本的规则 |

#### 1.2 基本使用

```python
from rulelift import TreeRuleExtractor

# 初始化树规则提取器
tree_miner = TreeRuleExtractor(
    df, 
    target_col='ISBAD', 
    exclude_cols=['ID', 'CREATE_TIME'],
    algorithm='rf',  # 使用随机森林算法
    max_depth=5,     # 树复杂度配置：决策树最大深度
    n_estimators=10,  # 树复杂度配置：随机森林中树的数量
    min_samples_split=10,  # 规则精度配置：分裂节点所需的最小样本数
    min_samples_leaf=5,  # 规则精度配置：叶子节点的最小样本数
    test_size=0.3,  # 测试集比例
    random_state=42,  # 随机种子
    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())
```

#### 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.4 常用参数

| 参数 | 类型 | 默认值 | 说明 |
|------|------|----------|------|
| `algorithm` | str | `'dt'` | 算法类型：'dt'、'rf'、'chi2'、'xgb'、'isf' |
| `max_depth` | int | `5` | 决策树最大深度，控制树的复杂度 |
| `min_samples_split` | int | `10` | 分裂节点所需的最小样本数，控制规则精度 |
| `min_samples_leaf` | int | `5` | 叶子节点的最小样本数，控制规则精度 |
| `n_estimators` | int | `10` | 随机森林/XGBoost/孤立森林中树的数量 |
| `max_features` | str | `'sqrt'` | 每棵树分裂时考虑的最大特征数：'sqrt'或'log2' |
| `test_size` | float | `0.3` | 测试集比例 |
| `random_state` | int | `42` | 随机种子，保证结果可复现 |
| `feature_trends` | Dict[str, int] | `None` | 特征与目标标签的正负相关性字典，用于避免不符合业务解释性的规则 |
| `amount_col` | str | `None` | 金额字段名，用于计算损失率指标 |
| `ovd_bal_col` | str | `None` | 逾期金额字段名，用于计算损失率指标 |

#### 1.5 不同算法使用示例

TreeRuleExtractor 支持多种树模型算法（决策树、卡方决策树、随机森林、xgb、孤立森林），下面是一些常用算法的使用示例：

##### 1.5.1 决策树（DT）

```python
# 初始化决策树规则提取器
tree_miner_dt = TreeRuleExtractor(
    df, 
    target_col='ISBAD', 
    exclude_cols=['ID', 'CREATE_TIME'],
    algorithm='dt',
    max_depth=3, 
    min_samples_split=20,
    min_samples_leaf=10,
    random_state=42
)
```

##### 1.5.2 随机森林（RF）

```python
# 初始化随机森林规则提取器
tree_miner_rf = TreeRuleExtractor(
    df, 
    target_col='ISBAD', 
    exclude_cols=['ID', 'CREATE_TIME'],
    algorithm='rf',
    max_depth=3, 
    min_samples_split=20,
    min_samples_leaf=10,
    n_estimators=5,
    max_features='sqrt',
    random_state=42
)
```

##### 1.5.3 卡方决策树（CHI2）

```python
# 初始化卡方决策树规则提取器
tree_miner_chi2 = TreeRuleExtractor(
    df, 
    target_col='ISBAD', 
    exclude_cols=['ID', 'CREATE_TIME'],
    algorithm='chi2',
    max_depth=3, 
    min_samples_split=20,
    min_samples_leaf=10,
    random_state=42
)
```

##### 1.5.4 XGBoost（XGB）

```python
# 初始化XGBoost规则提取器，使用特征业务解释性判断
tree_miner_xgb = TreeRuleExtractor(
    df, 
    target_col='ISBAD', 
    exclude_cols=['ID', 'CREATE_TIME'],
    algorithm='xgb',
    max_depth=3,
    min_samples_split=10,
    min_samples_leaf=10,
    n_estimators=10,
    feature_trends={
        'ALI_FQZSCORE': -1,      # 负相关：分数越低，违约概率越高
        'BAIDU_FQZSCORE': -1,    # 负相关：分数越低，违约概率越高
        'NUMBER OF LOAN APPLICATIONS TO PBOC': 1  # 正相关：申请次数越多，违约概率越高
    },
    random_state=42
)
```

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

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

#### 1.6 输出示例

```python
# 打印Top 5规则
for i, rule in enumerate(rules[:5]):
    print(f"\n=== Rule {i+1} ===")
    print(f"规则描述: {rule['rule']}")
    print(f"预测类别: {rule['class_name']} (概率: {rule['class_probability']:.4f})")
    print(f"样本数量: {rule['sample_count']}")
    print(f"重要性: {rule['importance']:.2f}")
```

#### 1.7 挖掘效果评估

TreeRuleExtractor 提供了全面的规则评估功能，支持训练集和测试集的效度评估。

**评估指标**：
- **训练集指标**：训练集上的准确率、召回率、精确率、F1分数、lift值
- **测试集指标**：测试集上的准确率、召回率、精确率、F1分数、lift值
- **损失率指标**（可选）：如果提供了 `amount_col` 和 `ovd_bal_col`，还会计算损失率和损失lift值

**使用示例**：

```python
# 训练模型
train_acc, test_acc = tree_miner.train()
print(f"训练集准确率: {train_acc:.4f}")
print(f"测试集准确率: {test_acc:.4f}")

# 提取规则
rules = tree_miner.extract_rules()

# 评估规则（包含损失率指标）
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']].head())
```

**输出示例**：

```
评估的规则数量: 31
规则评估结果（前5条）:
         rule  train_loss_rate  train_loss_lift  test_loss_rate  test_loss_lift  train_lift  test_lift
0  rule_1         0.3456789       2.3456789      0.234567       1.987654  2.123456      1.987654
1  rule_2         0.234567       1.987654      0.123456       1.876543  1.654321      1.876543
2  rule_3         0.123456       1.765432      0.098765       1.765432  1.543210      1.543210
3  rule_4         0.098765       1.654321      0.076543       1.543210  1.432109      1.432109
4  rule_5         0.076543       1.543210      0.065432       1.432109  1.321098      1.321098
```

---

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

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

#### 2.1 基本使用

```python
from rulelift import SingleFeatureRuleMiner

# 初始化单特征规则挖掘器
sf_miner = SingleFeatureRuleMiner(
    df, 
    exclude_cols=['ID', 'CREATE_TIME'],
    target_col='ISBAD'
)

# 分析单个特征
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.2 可视化

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

#### 2.3 常用参数

| 参数 | 类型 | 默认值 | 说明 |
|------|------|----------|------|
| `exclude_cols` | List[str] | `None` | 排除的字段名列表 |
| `target_col` | str | `'ISBAD'` | 目标字段名 |
| `num_bins` | int | `20` | 分箱数量 |
| `min_samples` | int | `10` | 最小样本数过滤 |
| `min_lift` | float | `1.1` | 最小lift值过滤 |

#### 2.4 输出示例

```
=== 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
```

---

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

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

#### 3.1 基本使用

```python
from rulelift import MultiFeatureRuleMiner

# 初始化多特征规则挖掘器
multi_miner = MultiFeatureRuleMiner(df, target_col='ISBAD')


feature1 = 'ALI_FQZSCORE'
feature2 = 'BAIDU_FQZSCORE'


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

#### 3.2 生成交叉矩阵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.2.1 多特征两两交叉分析

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

```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'],  # 支持多种指标分析
    binning_method='quantile'  # 支持等频分箱
)
print(f"多特征交叉矩阵Excel文件已保存到: cross_analysis_multi_features.xlsx")
```

#### 3.3 常用参数

| 参数 | 类型 | 默认值 | 说明 |
|------|------|----------|------|
| `target_col` | str | `'ISBAD'` | 目标字段名 |
| `top_n` | int | `10` | 返回的规则数量 |
| `metric` | str | `'lift'` | 排序指标：'lift'、'badrate'等 |
| `min_samples` | int | `10` | 最小样本数过滤 |
| `min_lift` | float | `1.1` | 最小lift值过滤 |
| `max_unique_threshold` | int | `5` | 最大允许的唯一值数量阈值 |
| `custom_bins1` | List[float] | `None` | 第一个特征的自定义分箱阈值 |
| `custom_bins2` | List[float] | `None` | 第二个特征的自定义分箱阈值 |
| `binning_method` | str | `'quantile'` | 分箱方法：'quantile'（等频）或'chi2'（卡方） |
| `metrics` | List[str] | `['badrate', 'count', 'sample_ratio', 'lift']` | 支持的指标列表：'badrate'、'count'、'sample_ratio'、'lift'、'loss_rate'、'loss_lift' |


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

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

| 指标 | 定义 | 业务意义 |
|------|------|----------|
| `badrate` | 坏样本比例 = 坏样本数 / 总样本数 | 直接反映该特征组合下的风险水平 |
| `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.5 交叉矩阵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      |

---

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

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

#### 4.1 基本使用

```python
from rulelift import VariableAnalyzer

# 初始化变量分析器
var_analyzer = VariableAnalyzer(
    df, 
    exclude_cols=['ID', 'CREATE_TIME'], 
    target_col='ISBAD'
)

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

# 分析单个变量的分箱情况
feature = 'ALI_FQZSCORE'
bin_analysis = var_analyzer.analyze_single_variable(feature, n_bins=10)
print(f"\n=== {feature} 分箱分析 ===")
print(bin_analysis)

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

#### 4.2 常用参数

| 参数 | 类型 | 默认值 | 说明 |
|------|------|----------|------|
| `exclude_cols` | List[str] | `None` | 排除的字段名列表 |
| `target_col` | str | `'ISBAD'` | 目标字段名 |
| `n_bins` | int | `10` | 分箱数量 |

#### 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
```

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

| 指标 | 定义 | 最佳范围 | 意义 |
|------|------|----------|------|
| `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 | 变量的稳定性指标，值越小越稳定 |

---

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

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

#### 5.1 基本使用

analyze_rules 函数支持两种规则评估方式：通过用户评级评估和通过目标标签评估。

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

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

```python
from rulelift import analyze_rules

# 通过用户评级评估规则效度
result_by_rating = analyze_rules(
    df, 
    rule_col='RULE',
    user_id_col='USER_ID',
    user_level_badrate_col='USER_LEVEL_BADRATE',  # 用户评级坏账率字段
    hit_date_col='HIT_DATE'  # 命中日期，用于计算稳定性指标
)

print("\n=== 通过用户评级评估的规则效度分析结果 ===")
print(result_by_rating[['RULE', 'actual_lift', 'actual_badrate', 'hit_rate', 'hit_rate_cv']].head())
```

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

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

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

print("\n=== 通过目标标签评估的规则效度分析结果 ===")
print(result_by_target[['RULE', 'actual_lift', 'actual_badrate', 'actual_recall', 'f1']].head())
```

##### 5.1.3 同时使用两种方式评估

也可以同时提供用户评级和目标标签，系统会自动选择合适的评估方式。

```python
# 同时使用两种方式评估规则效度
result_combined = analyze_rules(
    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'
)

print("\n=== 综合评估的规则效度分析结果 ===")
print(result_combined[['RULE', 'actual_lift', 'actual_badrate', 'actual_recall', 'f1', 'hit_rate', 'hit_rate_cv']].head())
```

#### 5.2 常用参数

| 参数 | 类型 | 默认值 | 说明 |
|------|------|----------|------|
| `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 输出示例

```
=== 规则效度分析结果 ===
         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

#规则相关性分析
print("\n3. 规则相关性分析:")
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}")

from rulelift import calculate_strategy_gain

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

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

#### 6.2 常用参数

| 参数 | 类型 | 默认值 | 说明 |
|------|------|----------|------|
| `strategy1` | list | - | 基础策略规则列表 |
| `strategy2` | list | - | 增强策略规则列表 |
| `user_target_col` | str | `None` | 用户实际逾期字段名（可选） |
| `user_level_badrate_col` | str | `None` | 用户评级坏账率字段名（可选） |

---

## 核心指标说明

### 规则评估指标

| 指标 | 定义 | 最佳范围 | 意义 |
|------|------|----------|------|
| `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.2.2

## 更新日志

### v1.2.2 (2025-01-10)
- **新增特征趋势过滤功能**：TreeRuleExtractor 支持 `feature_trends` 参数，提升规则的业务解释性
- **优化孤立森林规则提取**：基于树结构提取规则，支持多特征组合
- **优化SingleFeatureRuleMiner**：过滤极端值阈值，避免无意义规则
- **优化MultiFeatureRuleMiner**：添加最小样本数和lift值过滤，添加交叉矩阵Excel生成功能
- **优化规则DataFrame输出**：支持按lift倒序排序
- **删除变量分析中的损失率指标**：专注于核心效度指标
- **完善文档**：更新所有功能的使用示例、结果示例及常用参数介绍，补充规则评估说明和变量分析说明
- **修复已知问题**：解决所有已知bug和性能问题

### v1.1.5 (2025-12-23)
- 新增变量分析模块，支持IV、KS、AUC等指标计算
- 实现单变量等频分箱分析功能
- 新增策略自动挖掘功能
- 优化决策树规则显示，加入 lift 值和拦截用户数等指标
- 新增两两策略增益计算功能
- 优化代码质量，修复所有已知问题

### v1.0.0 (2025-12-17)
- 新增命中率变异系数（hit_rate_cv）用于监控规则稳定性
- 新增 F1 分数计算，综合评估规则效果
- 优化规则相关性分析，新增最大相关性指标
- 改进命中率计算逻辑
- 完善文档，新增技术原理和缺陷分析

---

## 许可证

MIT License

---

## 项目地址

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

---

## 联系方式

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

---

## 贡献指南

欢迎提交 Issue 和 Pull Request！如果您有任何建议或问题，请通过 GitHub Issues 反馈。

---

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