rulelift 1.1.1

A tool for analyzing rule effectiveness in credit risk management

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

项目概述

rulelift 是一个用于信用风险管理中策略规则自动挖掘、有效性分析及监控的 Python 工具包。它帮助风控团队评估规则的实际效果，识别冗余规则，优化策略组合，提高风险控制能力。

核心价值

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

• 量化评估：解决无标签问题，利用客户评级分布差异推估逾期率、召回率、精确率、lift值等多个指标
• 实时监控：支持基于生产数据的规则效果分析
• 规则挖掘：自动从数据中挖掘有效的风控规则
• 策略优化：评估策略组合效果，计算两两规则间的增益
• 可视化展示：直观呈现规则效果和关系
• 成本效益高：无需分流测试，基于现有数据即可评估规则效果

安装方法

使用 pip 安装（推荐）

pip install rulelift

从源码安装

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

快速开始

1. 基本导入

from rulelift import (
    load_example_data, analyze_rules, analyze_rule_correlation,
    calculate_strategy_gain, DecisionTreeRuleExtractor
)

2. 加载示例数据

``利用客户评级

核心功能

1. 规则效度分析

result = analyze_rules(
    df, 
    rule_col='RULE',              # 规则字段名
    user_target_col='USER_TARGET', # 实际逾期字段
    hit_date_col='HIT_DATE'        # 命中日期字段（可选，用于命中率监控）
)

2. 规则相关性分析

correlation_matrix, max_correlation = analyze_rule_correlation(df)
print("\n=== 规则相关性矩阵 ===")
print(correlation_matrix.head())

3. 策略增益计算

# 定义两个策略组
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}")

4. 规则挖掘

单特征规则挖掘

from rulelift import SingleFeatureRuleMiner

# 初始化单特征规则挖掘器
sf_miner = SingleFeatureRuleMiner(min_coverage=0.05, min_badrate=0.1)

# 挖掘规则
sf_rules = sf_miner.fit_predict(X, y)
print(f"\n=== 单特征规则挖掘结果 ===")
for rule in sf_rules[:3]:
    print(f"特征: {rule['feature']}, 条件: {rule['condition']}, Badrate: {rule['badrate']:.4f}")

多特征规则挖掘

from rulelift import MultiFeatureRuleMiner

# 初始化多特征规则挖掘器
mf_miner = MultiFeatureRuleMiner(max_depth=2, min_samples=5)

# 挖掘规则
mf_rules = mf_miner.fit_predict(X, y)
print(f"\n=== 多特征规则挖掘结果 ===")
for rule in mf_rules[:3]:
    print(f"规则: {rule['rule']}, Badrate: {rule['badrate']:.4f}")

5. 可视化

from rulelift import plot_rule_comparison, plot_decision_tree

# 规则比较图（保存到本地）
plot_rule_comparison(result, metric='actual_lift', save_path='rule_comparison.png')
print("规则比较图已保存到 rule_comparison.png")

# 决策树可视化（保存到本地）
plot_decision_tree(dt_extractor, feature_names=X.columns.tolist(), save_path='decision_tree.png')
print("决策树图已保存到 decision_tree.png")

核心指标说明

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

示例数据结构

字段名	描述	类型	示例值
RULE	规则名称	字符串	人行近3个月申请>10
USER_ID	用户唯一标识	字符串	ID20221115003665
HIT_DATE	规则命中日期	日期	2022-10-01
USER_LEVEL	用户风险评级	整数	1
USER_LEVEL_BADRATE	评级对应坏账率	数值	0.2
USER_TARGET	实际逾期情况	整数	1（逾期）/ 0（未逾期）

最佳实践

1. 数据准备：

   • 确保数据包含唯一的用户标识和规则名称
   • 实际逾期字段（USER_TARGET）应为 0/1 格式
   • 评级坏账率字段（USER_LEVEL_BADRATE）应为数值型

2. 分场景使用：

   • 开发测试阶段：使用决策树规则提取和单/多特征规则挖掘生成候选规则
   • 生产监控阶段：使用 analyze_rules 定期评估规则效果，关注 lift 值和命中率稳定性

3. 规则优化建议：

   • 保留 lift 值 > 1.2 的规则
   • 移除命中率变异系数 > 0.5 的不稳定规则
   • 合并或移除相关系数 > 0.8 的冗余规则
   • 综合考虑 f1 分数，平衡精确率和召回率

4. 策略组合：

   • 使用 calculate_strategy_gain 评估不同策略组合的效果
   • 优先添加 lift 值高且与现有规则相关性低的规则
   • 定期评估策略整体效果，及时调整规则组合

API 文档

analyze_rules

def analyze_rules(rule_score, rule_col='RULE', user_id_col='USER_ID', 
                 user_level_badrate_col=None, user_target_col=None,
                 hit_date_col=None)

参数：

• rule_score: DataFrame，包含规则拦截客户信息
• rule_col: str，规则名字段名，默认 'RULE'
• user_id_col: str，用户编号字段名，默认 'USER_ID'
• user_level_badrate_col: str，用户评级坏账率字段名，可选
• user_target_col: str，用户实际逾期字段名，可选
• hit_date_col: str，命中日期字段名，可选（用于命中率监控）

返回值：

• DataFrame，包含所有规则的评估指标

DecisionTreeRuleExtractor

class DecisionTreeRuleExtractor:
    def __init__(self, max_depth=3, min_samples_leaf=5, criterion='gini')
    def fit(self, X, y)
    def extract_rules(self)

参数：

• max_depth: int，决策树最大深度
• min_samples_leaf: int，叶子节点最小样本数
• criterion: str，分裂标准，可选 'gini' 或 'entropy'

方法：

• fit(X, y): 拟合决策树模型
• extract_rules(): 提取规则，返回规则列表

calculate_strategy_gain

def calculate_strategy_gain(df, strategy1, strategy2, 
                           rule_col='RULE', user_id_col='USER_ID',
                           user_target_col=None, user_level_badrate_col=None)

参数：

• df: DataFrame，规则拦截客户信息
• strategy1: list，基础策略规则列表
• strategy2: list，增强策略规则列表
• user_target_col: str，用户实际逾期字段名，可选
• user_level_badrate_col: str，用户评级坏账率字段名，可选

返回值：

• float，策略2相对策略1的增益值

版本信息

当前版本：1.1.1

更新日志

v1.1.1 (2025-12-23)

• 新增策略自动挖掘功能
• 优化决策树规则显示，加入 lift 值和拦截用户数等指标
• 新增两两策略增益计算功能
• 完善 setup.py 配置，添加完整依赖列表
• 优化代码质量，修复所有已知问题

v0.3.0 (2025-12-17)

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

许可证

MIT License

项目地址

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

联系方式

作者: aialgorithm 邮箱: [e-mail]

贡献指南

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

---

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