A tool for analyzing rule effectiveness in credit risk management

These details have not been verified by PyPI

Project links

Homepage

Project description

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

项目概述

rulelift 是一个用于信用风险管理中策略规则自动挖掘、有效性分析及监控的 Python 工具包。

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

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

📊 项目统计

PyPI Downloads

Star History

📚 目录

项目概述
完整的安装使用方法
快速开始
核心功能详解
- 1. 树规则提取（TreeRuleExtractor）
- [2. 单特征规则挖掘（SingleFeatureRuleMiner）](#2-单特征规则挖掘singlefeatureminer）
- 3. 多特征交叉规则挖掘（MultiFeatureRuleMiner）
- 4. 变量分析（VariableAnalyzer）
- 5. 规则效度分析监控模块（analyze_rules）
- 6. 策略相关性、增益计算（calculate_strategy_gain）
核心指标说明

📦 项目依赖包

核心依赖

项目依赖项精简，兼容性良好，仅需要常见的依赖包

依赖包	版本要求	用途
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 安装（推荐）

pip install rulelift

从源码安装

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

离线使用方式（考虑生产环境是无网）

方式一：离线安装rulelift及相关依赖

在有网络的环境中下载依赖包：

# 下载rulelift及其所有依赖
pip download rulelift -d ./packages/

将下载的packages文件夹传输到离线环境
在离线环境中安装：

# 进入packages文件夹
cd ./packages/

# 安装所有依赖包
pip install *.whl --no-index --find-links=.

方式二：通过源码直接调用

下载源码：
- 从GitHub下载源码包：https://github.com/aialgorithm/rulelift
将源码包传输到离线环境并解压 需要手动安装pandas、numpy、scikit-learn、matplotlib、seaborn
在Python代码中添加源码路径并导入：

import sys
import os

# 添加源码路径到系统路径
sys.path.append('/path/to/rulelift-master')

# 直接导入模块
from rulelift import load_example_data, analyze_rules, TreeRuleExtractor

快速开始

1. 基本导入

from rulelift import (
    load_example_data, preprocess_data,
    SingleFeatureRuleMiner, MultiFeatureRuleMiner, TreeRuleExtractor,
    VariableAnalyzer, analyze_rules, calculate_strategy_gain
)

2. 加载示例数据

# 加载示例数据
df = load_example_data('feas_target.csv')

3. 规则挖掘基础案例

树模型规则挖掘

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. 规则评估基础案例

规则效度评估

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. 变量分析基础案例

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 初始化参数详解

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

参数使用示例：

# 使用卡方分箱算法
chi2_miner = TreeRuleExtractor(
    df, 
    target_col='ISBAD',
    exclude_cols=['ID', 'CREATE_TIME', 'OVD_BAL', 'AMOUNT'],
    algorithm='chi2',
    min_bin_ratio=0.05  # 卡方分箱的最小样本占比
)

控制规则复杂度的参数调优建议：

生成简单规则：
- 增加 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
- min_samples_split：10-20

1.3 特征趋势判断（feature_trends）

规则挖掘中加入业务逻辑判断，feature_trends 参数用于配置特征与目标标签的正负相关性，避免不符合业务解释性的规则。

参数说明：

feature_trends: Dict[str, int]，键为特征名，值为 1（正相关）或 -1（负相关），仅挖掘符合特征业务逻辑的规则
- 正相关（值为1）：表示特征数值越大，目标标签（违约概率）越高，如多头申请次数
- 负相关（值为-1）：特征数值越小，目标标签（违约概率）越高，如信用评分

使用示例：

# 使用特征趋势过滤
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 训练模型

# 训练模型
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 提取规则

# 提取规则
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的规则，降低实际损失

使用方式：

# 初始化时指定金额和逾期金额字段
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 规则评估指标详解

# 评估规则（包含损失率指标）
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

评估规则（包含损失率指标）：

# 筛选高效策略规则
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）

# 初始化决策树规则提取器
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

优化后随机森林使用示例：

# 初始化随机森林规则提取器，优化参数以挖掘更多规则
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))

随机森林规则挖掘最佳实践：

生成大量规则：设置较大的n_estimators和较小的min_samples_leaf
控制规则复杂度：通过max_depth平衡规则复杂度和泛化能力
提高规则多样性：使用max_features='log2'或手动设置较大值
筛选高效规则：按test_badrate_reduction或test_lift排序，选择前N条规则
去重处理：使用get_rules_as_dataframe(deduplicate=True)去除重复规则

1.8.3 卡方随机森林（CHI2）

卡方随机森林采用卡方分箱预处理 + 随机森林的方式实现，不需要复杂的自定义决策树分裂逻辑。

实现原理：

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

卡方分箱参数说明：

min_bins：最小分箱数，默认为5
chi_square_threshold：卡方检验阈值，用于确定分箱数量，值越小分箱越多
min_bin_ratio：卡方分箱的最小样本占比，默认为0.05，控制分箱的最小样本数

卡方随机森林使用示例：

# 初始化卡方随机森林规则提取器，自定义分箱参数
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

卡方随机森林最佳实践：

生成更多分箱：降低chi_square_threshold，增加min_bins
控制规则复杂度：通过max_depth平衡规则复杂度和泛化能力
提高规则多样性：增加n_estimators，使用max_features='sqrt'或'log2'
筛选高效规则：按test_badrate_reduction或test_lift排序，选择前N条规则
去重处理：使用get_rules_as_dataframe(deduplicate=True)去除重复规则
确保样本充足：每个分箱的样本数建议≥50
验证分箱效果：检查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使用示例：

# 初始化梯度提升树规则提取器，优化参数以挖掘高质量规则
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规则挖掘最佳实践：

平衡精度和数量：通过n_estimators和learning_rate平衡规则数量和质量
控制过拟合：使用合适的max_depth和min_samples_leaf
结合特征趋势：使用feature_trends确保规则符合业务逻辑
综合评估：结合test_lift和test_badrate_reduction评估规则
梯度提升优势：利用GBDT的迭代提升特性，生成高质量规则

GBDT vs 随机森林：如何选择？

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

1.8.5 从实际使用角度建议如何使用RF和GBDT挖掘更多多样性高效度规则

1.8.5.1 随机森林（RF）使用建议

适用场景：

需要挖掘大量多样化规则
规则稳定性要求较高
特征数量较多，需要提高特征多样性
训练速度要求较快

参数配置建议：

# 配置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生成大量多样化规则
第二阶段：筛选高lift和高badrate_reduction的规则
第三阶段：使用配置2对筛选后的规则进行验证
第四阶段：结合业务知识，选择最优规则组合

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

适用场景：

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

参数配置建议：

# 配置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生成高质量规则
第二阶段：筛选高lift和高badrate_reduction的规则
第三阶段：使用配置2快速验证规则效果
第四阶段：结合业务知识，选择最优规则组合

1.8.5.3 RF和GBDT组合使用策略

组合使用优势：

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

组合使用示例：

# 使用随机森林生成多样化规则
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))

组合使用最佳实践：

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

1.8.5 孤立森林（ISF）

# 初始化孤立森林规则提取器，使用特征趋势判断
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 特征重要性图

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

1.9.2 决策树结构图

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

1.9.3 规则评估图

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

1.10 打印规则

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

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

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

2.1 初始化参数详解

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 分析单个特征

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

# 绘制特征指标分布图
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 初始化参数详解

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 生成交叉矩阵

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 交叉矩阵自定义分箱详解

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

自定义分箱使用示例：

# 生成交叉矩阵，使用自定义分箱阈值
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	基于统计检验，分箱最优	计算复杂，耗时较长	风控场景，追求最优分箱效果

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

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

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

# 生成交叉矩阵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文件

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

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

# 多特征两两交叉分析示例
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规则

# 获取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 可视化

# 绘制交叉热力图
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 初始化参数详解

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 分析所有变量的效度指标

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

4.4 变量分箱分布分析

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

4.4.1 自定义分箱功能

使用方式：

# 分析单个变量的分箱情况，使用自定义分箱阈值
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 变量分箱最佳实践

连续型变量：
- 优先使用卡方分箱，生成最优分箱
- 结合业务知识调整分箱阈值
- 确保每个分箱的样本数足够（建议≥100）
- 检查badrate是否呈现单调性或明显的风险趋势
离散型变量：
- 类别数≤10：直接使用原始类别
- 类别数>10：使用等频或卡方分箱合并相似类别
- 注意高基数类别变量的处理
- 关注稀有类别的风险特征
分箱结果应用：
- 选择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 可视化

# 可视化变量分箱结果
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 初始化参数详解

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 规则相关性分析

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 初始化参数详解

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: 配置方式：

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: 需要在初始化时提供金额字段和逾期金额字段：

# 初始化时提供金额字段
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: 实现步骤：

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

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: 特征趋势用于避免不符合业务解释性的规则：

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

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

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

# 对于规则挖掘器
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 函数评估规则效度：

# 通过用户评级评估
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: 使用规则相关性分析识别冗余规则：

# 规则相关性分析
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: 使用策略增益计算评估不同规则组合的效果：

# 定义两个策略组
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: 参考文档中的"离线使用方式"部分，主要有两种方式：

离线安装rulelift及相关依赖：在有网络的环境中下载依赖包，然后传输到离线环境安装
通过源码直接调用：下载源码包，手动安装依赖，然后在Python代码中添加源码路径并导入

Q8: 如何处理缺失值？

A: rulelift 会自动处理缺失值：

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

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

A: 通过以下参数控制树模型的复杂度：

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

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

A: 支持多种导出方式：

# 导出为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 提供了丰富的可视化功能：

# 特征重要性图
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 优化您的风控规则系统吧！ 🚀

Project details

These details have not been verified by PyPI

Project links

Homepage

Release history Release notifications | RSS feed

2.5.1

May 5, 2026

1.6.0

May 5, 2026

This version

1.3.0

Jan 30, 2026

1.2.4

Jan 20, 2026

1.2.3

Jan 13, 2026

1.2.2

Jan 11, 2026

1.2.1

Jan 10, 2026

1.2.0

Jan 10, 2026

1.1.6

Dec 25, 2025

1.1.5

Dec 25, 2025

1.1.4

Dec 24, 2025

1.1.3

Dec 24, 2025

1.1.2

Dec 24, 2025

1.1.1

Dec 23, 2025

0.3.0

Dec 17, 2025

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

rulelift-1.3.0.tar.gz (130.1 kB view details)

Uploaded Jan 30, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

rulelift-1.3.0-py3-none-any.whl (96.6 kB view details)

Uploaded Jan 30, 2026 Python 3

File details

Details for the file rulelift-1.3.0.tar.gz.

File metadata

Download URL: rulelift-1.3.0.tar.gz
Upload date: Jan 30, 2026
Size: 130.1 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.13.7

File hashes

Hashes for rulelift-1.3.0.tar.gz
Algorithm	Hash digest
SHA256	`cbbb3e4571de3dd3a2c64e84f7003f65fa4982407aa0cb9ac79b0109513916c6`
MD5	`81b7e1ce7b42e756e8203ddeeed00eaf`
BLAKE2b-256	`c23ee1dee125159025e4156fb4f9389b5d61d67fdfce2541a457158c84f26ade`

See more details on using hashes here.

File details

Details for the file rulelift-1.3.0-py3-none-any.whl.

File metadata

Download URL: rulelift-1.3.0-py3-none-any.whl
Upload date: Jan 30, 2026
Size: 96.6 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.13.7

File hashes

Hashes for rulelift-1.3.0-py3-none-any.whl
Algorithm	Hash digest
SHA256	`e372c03d47add6beb180877f5980deac714c9775afc616c09783b9e2c10d4d2d`
MD5	`8120796107aa498904bd66d4a260566c`
BLAKE2b-256	`db564ab6888ae6d5f889c0fb2f65a07275d919ba80b19abdebd6482b04aa461b`

See more details on using hashes here.

rulelift 1.3.0

Navigation

Verified details

Maintainers

Unverified details

Project links

Meta

Classifiers

Project description

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

项目概述

📊 项目统计

PyPI Downloads

Star History

📚 目录

📦 项目依赖包

核心依赖

🎯 项目功能概览

功能特点

完整的安装使用方法

使用 pip 安装（推荐）

从源码安装

离线使用方式（考虑生产环境是无网）

方式一：离线安装rulelift及相关依赖

方式二：通过源码直接调用

快速开始

1. 基本导入

2. 加载示例数据

3. 规则挖掘基础案例

树模型规则挖掘

4. 规则评估基础案例

规则效度评估

5. 变量分析基础案例

核心功能详解

1. 树规则提取（TreeRuleExtractor）

1.1 支持的算法

1.2 初始化参数详解

1.3 特征趋势判断（feature_trends）

1.5 训练模型

1.6 提取规则

1.7 规则评估

1.7.1 损失率计算（Loss Rate）

1.7.2 规则评估指标详解

1.7.3 策略效率指标（test_badrate_reduction）

1.7.4 评估指标组合建议

1.8 不同算法使用示例

1.8.1 决策树（DT）

1.8.2 随机森林（RF）

1.8.3 卡方随机森林（CHI2）

1.8.4 梯度提升树（GBDT）

1.8.5 从实际使用角度建议如何使用RF和GBDT挖掘更多多样性高效度规则

1.8.5.1 随机森林（RF）使用建议

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

1.8.5.3 RF和GBDT组合使用策略

1.8.5 孤立森林（ISF）

1.9 可视化功能

1.9.1 特征重要性图

1.9.2 决策树结构图

1.9.3 规则评估图

1.10 打印规则

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

2.1 初始化参数详解

2.2 参数详细说明

2.3 分析单个特征

2.4 参数详细说明

2.5 输出示例

2.6 可视化

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

3.1 初始化参数详解

3.2 参数详细说明

3.3 生成交叉矩阵

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

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

3.4 参数详细说明

3.5 支持的指标说明

3.6 生成交叉矩阵Excel文件

3.7 多特征两两交叉分析

3.8 参数详细说明

3.9 交叉矩阵Excel文件示例

3.10 获取Top规则