跳转至

分箱与风险评估

适用场景

使用本指南评估单个特征与二分类 target 的关系，或使用稳定的基准期分箱规则评估当前数据。常见 输出包括 IV、KS、AUC、Lift、坏账率、PSI、缺失率和分箱趋势。

入口选择

目标 入口
按高层参数自动构建分箱器 profile_risk()
传入或复用已拟合分箱器 MarsBinEvaluator.evaluate()
只需要分箱和转换 MarsNativeBinner、MarsLiteOptBinner、MarsOptimalBinner

profile_risk() 不接受显式 binner。需要固定规则时使用 evaluator。

基准期规则评估当前期

下面的完整示例使用带标签的 baseline_df 拟合 CART 分箱，并评估 target 尚未表现的 current_df：

import polars as pl

from mars.analysis import MarsBinEvaluator

baseline_df = pl.DataFrame(
    {
        "income": [2600, 3100, 3500, 3900, 4500, 5200, 6100, 7200],
        "utilization": [0.72, 0.64, 0.55, 0.48, 0.36, 0.28, 0.19, 0.11],
        "target": [1, 1, 1, 0, 1, 0, 0, 0],
    }
)

current_df = pl.DataFrame(
    {
        "apply_dt": [
            "2026-04-03",
            "2026-04-10",
            "2026-04-17",
            "2026-04-24",
            "2026-05-03",
            "2026-05-10",
            "2026-05-17",
            "2026-05-24",
        ],
        "period": ["2026-04"] * 4 + ["2026-05"] * 4,
        "income": [2800, 3400, 4100, 5600, 3000, 3700, 4900, 6800],
        "utilization": [0.69, 0.58, 0.41, 0.24, 0.66, 0.51, 0.33, 0.16],
        "target": [None] * 8,
    }
)

evaluator = MarsBinEvaluator(
    binning_type="native",
    binner_params={"method": "cart", "n_bins": 4},
)
risk_profile = evaluator.evaluate(
    current_df,
    target="target",
    features=["income", "utilization"],
    benchmark_df=baseline_df,
    group_col="period",
    time_col="apply_dt",
)

report = risk_profile.report
fitted_binner = risk_profile.binner

规则来源优先级为显式 binner、benchmark_df、当前 df。基准样本不会进入当前期 Total， 但会提供 PSI expected distribution。

分箱器选择

类型 适用情况 标签要求
native + quantile 快速等频分箱、宽表初筛 不要求
native + uniform 需要固定宽度区间 不要求
native + cart 使用 target 的轻量监督分箱 要求
lite_opt 轻量单调监督分箱 要求
optimal 数学规划最优分箱与类别合并 要求

三个分箱器都继承 MarsBinnerBase，共享 transform()、profile_bin_performance()、 get_fit_report()、JSON artifact 和 prune()。

transform() 默认要求输入包含全部可用规则列。只转换子集时显式传 features=[...]；确实需要宽松处理时才使用 on_missing="warn" 或 "ignore"。 update_bins() 对未知特征默认报错，prune() 和 get_bin_mapping() 也不再静默忽略未知名称。

分箱诊断与 JSON artifact

get_fit_report() 固定返回 Polars 表，包含 feature、dtype、feature_type、 status、usable、n_bins 和 reason。宽表拟合可以保留成功 fallback，无规则特征 则标记为 failed；全部失败会抛出 ValueError。

binner.fit(baseline_df, target, features=features)
fit_report = binner.get_fit_report()
binner.save_json("artifacts/binner.json")
restored = MarsBinnerBase.load_json("artifacts/binner.json")

JSON 顶层包含 artifact_type、schema_version、binner_type、mars_version、params 和 state，当前 schema_version=1。这是正式跨版本规则格式；旧 {params, state} 载荷不兼容， 必须用 0.0.26 重新拟合或导出。Pickle/joblib 只用于 Python 进程级便利存储。

输出

MarsRiskProfile 保存本次 report、binner、targets 和 metadata。常用 report 字段：

字段 用途
summary_table 特征级指标汇总和排序
detail_table 分箱样本数、坏账率、WOE 和 IV 明细
trend_tables PSI、缺失率和坏账率等分组趋势
missing_by_day_table 使用 time_col 计算的按日缺失趋势

时间与 PSI

风险趋势图必须有有效 time_col。group_col 决定面板分组，但不能替代真实日期范围。只有未传 group_col 时，time_grain 才根据 time_col 生成分组。

psi_include_missing 和 psi_include_special 控制对应分箱是否进入 PSI；缺失率会单独报告， 监控场景通常保持两者为 False。

常见失败

  • 监督分箱数据只有一个有效 target 类别：改用带完整标签的基准样本，或选择无监督分箱。
  • benchmark_df 缺少 active feature 或权重列：基准数据必须包含拟合规则所需的全部列。
  • 复用规则时仍调用 profile_risk()：改用 MarsBinEvaluator.evaluate(..., binner=...)。
  • 生成图表时没有 time_col：重新评估并提供原始日期列。
  • WOE 转换或 SQL 报缺少映射：使用有两个有效类别的 target 拟合并完成 WOE 统计。

下一步