指标 `hscredit.core.metrics`

43 种指标：分类指标（KS / AUC / Gini / 精确率 / 召回率 …）、稳定性指标（PSI / CSI）、特征指标（IV / WOE / 分箱统计）与金融指标，建模、评估、策略与监控共用同一套口径。

指标计算模块 - 统一的模型评估指标入口.

提供分类、回归、特征评估、稳定性、金融风控等场景的评估指标。

指标分类: - 分类指标: ks, auc, gini, accuracy, precision, recall, f1, ks_bucket - 特征评估: iv, iv_table, chi2_test, cramers_v, feature_importance, bin_stats - 稳定性: psi, psi_table, csi, csi_table, batch_psi - 金融风控: lift, lift_table, lift_curve, badrate, badrate_by_group - 回归指标: mse, mae, rmse, r2

使用示例:

>>> from hscredit.core import metrics
>>> metrics.ks(y_true, y_prob)
0.45
>>> metrics.iv(y_true, feature)
0.23
>>> metrics.psi(score_train, score_test)
0.05

命名规范: - 所有函数使用小写+下划线命名 - 分类指标: ks, auc, gini - 特征指标: iv, iv_table - 稳定性: psi, csi - 金融指标: lift, badrate

hscredit.core.metrics.ks(y_true, y_prob)[源代码]

计算Kolmogorov-Smirnov统计量.

KS值衡量模型区分正负样本的能力，值越大区分效果越好。 KS = max(TPR - FPR)，其中TPR为正样本累积率，FPR为负样本累积率。

参数

参数:

y_true (ndarray | Series) -- 真实标签 (0/1)，0为负样本，1为正样本
y_prob (ndarray | Series) -- 预测为正样本的概率值

返回:

KS统计量，取值范围[0, 1]，越接近1区分能力越强

抛出:

ValueError -- 标签非二值或y_true/y_prob长度不一致时
ValueError -- y_true中全为正样本或全为负样本时

返回类型:

float

参考样例

>>> from hscredit.core.metrics import ks
>>> y_true = [0, 0, 1, 1, 1, 0, 1, 0]  # 真实标签序列
>>> y_prob = [0.1, 0.3, 0.7, 0.6, 0.8, 0.2, 0.9, 0.4]  # 预测概率（高分对应坏样本）
>>> ks(y_true, y_prob)
0.75

引用

Kolmogorov-Smirnov 统计量原为两分布的最大累积差异检验 (Kolmogorov, 1933; Smirnov, 1948)，在信用评分中作为模型区分度的标准指标，定义见 Siddiqi, N. (2006). Credit Risk Scorecards. Wiley。经验阈值：KS<0.2 区分弱、0.2~0.4 可用、0.4~0.6 强、>0.75 需排查标签泄漏。

hscredit.core.metrics.auc(y_true, y_prob)[源代码]

计算ROC曲线下的面积(AUC).

AUC值衡量模型在不同分类阈值下区分正负样本的综合能力，值在0.5-1.0之间，越接近1.0模型效果越好。

参数

参数:

y_true (ndarray | Series) -- 真实标签 (0/1)，0为负样本，1为正样本
y_prob (ndarray | Series) -- 预测为正样本的概率值

返回:

AUC值，取值范围[0.5, 1.0]

抛出:

ValueError -- y_true/y_prob长度不一致时

返回类型:

float

参考样例

>>> from hscredit.core.metrics import auc
>>> y_true = [0, 0, 1, 1, 1, 0, 1, 0]
>>> y_prob = [0.1, 0.3, 0.7, 0.6, 0.8, 0.2, 0.9, 0.4]
>>> auc(y_true, y_prob)
0.875

引用

封装自 sklearn.metrics.roc_auc_score()。AUC 的概率解释（随机抽取一正一负样本，正样本得分更高的概率）见 Fawcett, T. (2006). An introduction to ROC analysis. Pattern Recognition Letters, 27(8), 861-874。

hscredit.core.metrics.gini(y_true, y_prob)[源代码]

计算基尼系数 (Gini Coefficient).

基尼系数是AUC的线性变换：基尼系数 = 2 * AUC - 1。范围从-1到1，越接近1表示模型区分能力越强。

参数

参数:

y_true (ndarray | Series) -- 真实标签 (0/1)，0为负样本，1为正样本
y_prob (ndarray | Series) -- 预测为正样本的概率值

返回:

基尼系数，取值范围[-1, 1]

抛出:

ValueError -- y_true/y_prob长度不一致时

返回类型:

float

参考样例

>>> from hscredit.core.metrics import gini
>>> y_true = [0, 0, 1, 1, 1, 0, 1, 0]
>>> y_prob = [0.1, 0.3, 0.7, 0.6, 0.8, 0.2, 0.9, 0.4]
>>> gini(y_true, y_prob)
0.75

引用

此处的基尼系数（亦称 Accuracy Ratio / Somers' D）由 AUC 线性变换得到， Gini = 2·AUC − 1，是信用风险领域衡量区分度的常用指标，见 Siddiqi, N. (2006). Credit Risk Scorecards. Wiley。

hscredit.core.metrics.accuracy(y_true, y_pred)[源代码]

计算准确率 (Accuracy).

准确率 = 预测正确的样本数 / 总样本数。

参数

参数:

y_true (ndarray | Series) -- 真实标签（任意类型）
y_pred (ndarray | Series) -- 预测标签（与y_true类型一致）

返回:

准确率，取值范围[0, 1]

抛出:

ValueError -- y_true/y_pred长度不一致时

返回类型:

float

参考样例

>>> from hscredit.core.metrics import accuracy
>>> y_true = [0, 1, 1, 0, 1]
>>> y_pred = [0, 1, 0, 0, 1]
>>> accuracy(y_true, y_pred)
0.8

hscredit.core.metrics.precision(y_true, y_pred, average='binary')[源代码]

计算精确率 (Precision).

精确率 = TP / (TP + FP)，即预测为正的样本中真正为正的比例。

参数

参数:

y_true (ndarray | Series) -- 真实标签
y_pred (ndarray | Series) -- 预测标签
average (str) -- 平均方式，'binary'（二分类默认只看正类），'micro'（全局TP/FP/FN）， 'macro'（各类分别计算后取平均），'weighted'（加权平均），默认为'binary'

返回:

精确率，取值范围[0, 1]

返回类型:

float

参考样例

>>> from hscredit.core.metrics import precision
>>> y_true = [0, 1, 1, 0, 1]
>>> y_pred = [0, 1, 0, 0, 1]
>>> precision(y_true, y_pred)       # 二分类默认
1.0
>>> precision(y_true, y_pred, average='macro')
0.9

hscredit.core.metrics.recall(y_true, y_pred, average='binary')[源代码]

计算召回率 (Recall / Sensitivity).

召回率 = TP / (TP + FN)，即所有正样本中被正确预测的比例。

参数

参数:

y_true (ndarray | Series) -- 真实标签
y_pred (ndarray | Series) -- 预测标签
average (str) -- 平均方式，'binary'（二分类默认只看正类），'micro'，'macro'，'weighted'，默认为'binary'

返回:

召回率，取值范围[0, 1]

返回类型:

float

参考样例

>>> from hscredit.core.metrics import recall
>>> y_true = [0, 1, 1, 0, 1]
>>> y_pred = [0, 1, 0, 0, 1]
>>> recall(y_true, y_pred)
0.666...

hscredit.core.metrics.f1(y_true, y_pred, average='binary')[源代码]

计算F1分数 (F1 Score).

F1 = 2 * (精确率 * 召回率) / (精确率 + 召回率)，是精确率和召回率的调和平均。

参数

参数:

y_true (ndarray | Series) -- 真实标签
y_pred (ndarray | Series) -- 预测标签
average (str) -- 平均方式，'binary'（二分类默认只看正类），'micro'，'macro'，'weighted'，默认为'binary'

返回:

F1分数，取值范围[0, 1]

返回类型:

float

参考样例

>>> from hscredit.core.metrics import f1
>>> y_true = [0, 1, 1, 0, 1]
>>> y_pred = [0, 1, 0, 0, 1]
>>> f1(y_true, y_pred)
0.8

hscredit.core.metrics.ks_bucket(y_true, y_prob, method='quantile', max_n_bins=10, min_bin_size=0.01, **kwargs)[源代码]

计算分桶KS统计表.

将样本按预测概率分为多个桶，计算每个桶的KS统计信息，包括各桶的样本数、坏账率、累积好坏样本率及KS贡献。

参数

参数:

y_true (ndarray | Series) -- 真实标签 (0/1)，0为负样本（好样本），1为正样本（坏样本）
y_prob (ndarray | Series) -- 预测为正样本的概率值
method (str) -- 分箱方法，取值与 OptimalBinning.VALID_METHODS 一致（共17种），默认为'quantile'。常用值： - quantile: 等频分箱 - uniform: 等宽分箱 - tree: 决策树最优分箱 - chi: 卡方分箱 - mdlp: MDLP信息论分箱 - best_iv/best_ks: 最优IV/KS分箱完整列表见 OptimalBinning
max_n_bins (int) -- 最大分桶数量，默认为10
min_bin_size (float) -- 每桶最小样本占比，默认为0.01
kwargs -- 其他传递给OptimalBinning的参数

返回:

包含桶统计信息的DataFrame，列包括： - 桶编号: 分箱序号 - 最小概率: 该桶内概率最小值 - 最大概率: 该桶内概率最大值 - 样本数: 该桶内样本数量 - 坏样本率: 该桶内坏样本占比 - 累积坏样本率: 累积坏样本占总坏样本比例 - 累积好样本率: 累积好样本占总好样本比例 - KS贡献: 该桶对KS值的贡献

抛出:

ValueError -- 数据全部为缺失值时

返回类型:

DataFrame

参考样例

>>> from hscredit.core.metrics import ks_bucket
>>> import numpy as np
>>> np.random.seed(42)
>>> y_true = np.random.randint(0, 2, 1000)
>>> y_prob = np.random.uniform(0, 1, 1000)
>>> result = ks_bucket(y_true, y_prob, max_n_bins=5)
>>> print(result[['桶编号', '样本数', '坏样本率']])

hscredit.core.metrics.roc_curve(y_true, y_prob)[源代码]

计算ROC曲线数据.

返回ROC曲线绘制所需的FPR、TPR和阈值数据。

参数

参数:

y_true (ndarray | Series) -- 真实标签 (0/1)
y_prob (ndarray | Series) -- 预测为正样本的概率值

返回:

三元组 (fpr, tpr, thresholds) - fpr: 假阳性率（False Positive Rate）数组 - tpr: 真阳性率（True Positive Rate）数组 - thresholds: 对应的概率阈值数组

返回类型:

Tuple[ndarray, ndarray, ndarray]

参考样例

>>> from hscredit.core.metrics import roc_curve
>>> y_true = [0, 0, 1, 1, 1, 0, 1, 0]
>>> y_prob = [0.1, 0.3, 0.7, 0.6, 0.8, 0.2, 0.9, 0.4]
>>> fpr, tpr, thresholds = roc_curve(y_true, y_prob)

hscredit.core.metrics.confusion_matrix(y_true, y_pred, labels=None)[源代码]

计算混淆矩阵.

混淆矩阵展示分类器的预测结果与真实标签的对应关系。

参数

参数:

y_true (ndarray | Series) -- 真实标签
y_pred (ndarray | Series) -- 预测标签
labels (list | None) -- 类别标签列表，指定矩阵的行序和列序，默认为None（自动推断）

返回:

混淆矩阵（2D ndarray） - 行表示真实类别，列表示预测类别 - 二分类时：[[TN, FP], [FN, TP]]

返回类型:

ndarray

参考样例

>>> from hscredit.core.metrics import confusion_matrix
>>> y_true = [0, 1, 1, 0, 1]
>>> y_pred = [0, 1, 0, 0, 1]
>>> confusion_matrix(y_true, y_pred)
array([[2, 0],
       [1, 2]])

hscredit.core.metrics.classification_report(y_true, y_pred, target_names=None, output_dict=False)[源代码]

生成分类报告.

输出各类的精确率、召回率、F1分数和支持样本数。

参数

参数:

y_true (ndarray | Series) -- 真实标签
y_pred (ndarray | Series) -- 预测标签
target_names (list | None) -- 目标类别名称列表，用于报告中替代类别标签显示
output_dict (bool) -- 如果为True，返回字典格式；否则返回格式化字符串，默认为False

返回:

当output_dict=False时返回格式化字符串，当output_dict=True时返回字典

返回类型:

str | dict

参考样例

>>> from hscredit.core.metrics import classification_report
>>> y_true = [0, 1, 1, 0, 1]
>>> y_pred = [0, 1, 0, 0, 1]
>>> print(classification_report(y_true, y_pred))
              precision    recall  f1-score   support

           0       0.67      1.00      0.80         2
           1       1.00      0.67      0.80         3

    accuracy                           0.80         5
   macro avg       0.83      0.83      0.80         5
weighted avg       0.87      0.80      0.80         5
>>> classification_report(y_true, y_pred, output_dict=True)
{'0': {'precision': 0.67, 'recall': 1.0, 'f1-score': 0.8, 'support': 2}, ...}

hscredit.core.metrics.ks_2samps(sample1, sample2)[源代码]

计算两组独立样本之间的 Kolmogorov-Smirnov 统计量（两样本KS）.

与 ks(y_true, y_prob) 不同，本函数比较两个独立样本的分布，适用于好坏样本分布对比分析。

参数:

sample1 (ndarray | Series) -- 第一组样本（通常是好样本的分数）
sample2 (ndarray | Series) -- 第二组样本（通常是坏样本的分数）

返回:

KS统计量，取值范围[0, 1]

返回类型:

float

参考样例

>>> from hscredit.core.metrics import ks_2samps
>>> import numpy as np
>>> np.random.seed(42)
>>> good_scores = np.random.normal(0.5, 0.1, 500)
>>> bad_scores = np.random.normal(0.7, 0.1, 500)
>>> ks_2samps(good_scores, bad_scores)
0.69

引用

封装自 :func:`scipy.stats.ks_2samp`（两样本 Kolmogorov-Smirnov 检验），取其返回的统计量分量。详见 https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.ks_2samp.html

hscredit.core.metrics.iv(y_true, feature, method='quantile', max_n_bins=10, min_bin_size=0.01, **kwargs)[源代码]

计算Information Value (信息价值).

IV用于衡量特征的预测能力，值越大表示特征的区分能力越强。

IV分级标准:

IV < 0.02: 无预测能力，应剔除
0.02 <= IV < 0.1: 弱预测能力
0.1 <= IV < 0.3: 中等预测能力
0.3 <= IV < 0.5: 强预测能力
IV >= 0.5: 极强预测能力，但需警惕过拟合

参数

参数:

y_true (ndarray | Series) -- 目标变量 (0/1)，0为负样本（好样本），1为正样本（坏样本）
feature (ndarray | Series) -- 特征变量（支持数值型和分类型，自动处理缺失值）
method (str) -- 分箱方法，默认为'quantile'（等频分箱），支持与OptimalBinning相同的全部分箱方法
max_n_bins (int) -- 最大分箱数，默认为10
min_bin_size (float) -- 每箱最小样本占比，默认为0.01
kwargs -- 其他传递给OptimalBinning的参数

返回:

IV值

抛出:

ValueError -- 数据全部为缺失值或y_true非二值时
ValueError -- y_true和feature长度不一致时

返回类型:

float

参考样例

>>> from hscredit.core.metrics import iv
>>> import numpy as np
>>> np.random.seed(42)
>>> y = np.random.randint(0, 2, 1000)
>>> x = np.random.randn(1000) + y * 0.5   # 与目标有一定关联的特征
>>> iv(y, x)
0.15

引用

IV = Σ (坏样本占比 − 好样本占比) · WOE，按分箱求和。定义与经验阈值见 Siddiqi, N. (2006). Credit Risk Scorecards. Wiley。IV 在数学上等价于好/坏两个条件分布之间的对称 KL 散度（与 PSI 同源）。

hscredit.core.metrics.iv_table(y_true, feature, method='quantile', max_n_bins=10, min_bin_size=0.01, **kwargs)[源代码]

计算IV详细统计表.

对特征进行分箱后，计算每箱的好坏样本数、占比、WOE、IV贡献等详细指标。

参数

参数:

y_true (ndarray | Series) -- 目标变量 (0/1)，0为负样本（好样本），1为正样本（坏样本）
feature (ndarray | Series) -- 特征变量（支持数值型和分类型，自动处理缺失值）
method (str) -- 分箱方法，默认为'quantile'（等频分箱）
max_n_bins (int) -- 最大分箱数，默认为10
min_bin_size (float) -- 每箱最小样本占比，默认为0.01
kwargs -- 其他传递给OptimalBinning的参数

返回:

包含各分箱详细统计的DataFrame，列包括：分箱标签、样本数、坏样本数、好样本数、坏样本率、好样本率、WOE值、分档IV值、累积IV值等

抛出:

ValueError -- 数据全部为缺失值时

返回类型:

DataFrame

参考样例

>>> from hscredit.core.metrics import iv_table
>>> import numpy as np
>>> np.random.seed(42)
>>> y = np.random.randint(0, 2, 1000)
>>> x = np.random.randn(1000) + y * 0.5
>>> table = iv_table(y, x, max_n_bins=5)
>>> print(table[['分箱标签', '样本数', '坏样本率', '分档IV值']])

hscredit.core.metrics.chi2_test(x, y)[源代码]

计算卡方独立性检验 (Chi-Square Test).

检验特征变量与目标变量之间是否存在统计学显著的关联关系。

参数

参数:

x (ndarray | Series) -- 特征变量（可以是分类或数值型，数值型会自动进行等频分箱）
y (ndarray | Series) -- 目标变量 (0/1)

返回:

二元组 (卡方统计量, p值) - 卡方统计量: 值越大表示偏离独立假设越远 - p值: 小于显著性水平（通常0.05）时拒绝独立假设

抛出:

ValueError -- x和y长度不一致时

返回类型:

Tuple[float, float]

参考样例

>>> from hscredit.core.metrics import chi2_test
>>> import numpy as np
>>> np.random.seed(42)
>>> y = np.random.randint(0, 2, 1000)
>>> x = np.random.randn(1000)
>>> chi2, p = chi2_test(x, y)
>>> print(f"chi2={chi2:.4f}, p={p:.4f}")

hscredit.core.metrics.cramers_v(x, y)[源代码]

计算Cramer's V关联强度 (Cramér's V).

Cramer's V是卡方检验的效应量，衡量两个分类变量之间的关联强度，取值范围0-1，值越大表示关联越强。

参数

参数:

x (ndarray | Series) -- 特征变量（数值型会自动分箱为10个区间）
y (ndarray | Series) -- 目标变量 (0/1)

返回:

Cramer's V值，取值范围[0, 1] - 0: 完全独立 - 0.1: 弱关联 - 0.3: 中等关联 - 0.5+: 强关联

抛出:

ValueError -- x和y长度不一致时

返回类型:

float

参考样例

>>> from hscredit.core.metrics import cramers_v
>>> import numpy as np
>>> np.random.seed(42)
>>> y = np.random.randint(0, 2, 1000)
>>> x = np.random.randn(1000)
>>> cramers_v(x, y)
0.05

hscredit.core.metrics.feature_importance(X, y, method='gini', **kwargs)[源代码]

计算特征重要性.

使用树模型基于特征对目标变量的分裂增益计算特征重要性。

参数

参数:

X (DataFrame | ndarray) -- 特征矩阵（DataFrame或numpy数组，DataFrame时使用列名作为索引名）
y (ndarray | Series) -- 目标变量 (0/1)
method (str) -- 计算方法 - 'gini': 使用决策树（max_depth=3）基于基尼重要性计算，默认为此值 - 'entropy': 使用随机森林（默认100棵树，max_depth=3）基于信息熵计算
kwargs -- 其他传递给模型的参数（如n_estimators、max_depth等）

返回:

特征重要性Series，索引为特征名（DataFrame输入时）或feature_0, feature_1...，值为重要性得分（归一化和为1）

返回类型:

Series

参考样例

>>> from hscredit.core.metrics import feature_importance
>>> import pandas as pd
>>> import numpy as np
>>> np.random.seed(42)
>>> X = pd.DataFrame({f'f{i}': np.random.randn(500) for i in range(5)})
>>> y = np.random.randint(0, 2, 500)
>>> importance = feature_importance(X, y, method='gini')
>>> print(importance.sort_values(ascending=False))

hscredit.core.metrics.psi(expected, actual, method='quantile', max_n_bins=10, min_bin_size=0.01, **kwargs)[源代码]

计算Population Stability Index (群体稳定性指标).

PSI用于衡量两个分布之间的差异，评估模型或特征的稳定性。值越小表示两个分布越接近，模型越稳定。

PSI分级标准:

PSI < 0.1: 没有显著变化，分布稳定
0.1 <= PSI < 0.25: 有轻微变化，需关注
PSI >= 0.25: 有显著变化，模型可能需要重新训练

参数

参数:

expected (ndarray | Series) -- 期望分布数据（通常是训练集或基准数据的特征/评分）
actual (ndarray | Series) -- 实际分布数据（通常是测试集或新上线数据的特征/评分）
method (str) -- 分箱方法，默认为'quantile'（等频分箱）
max_n_bins (int) -- 最大分箱数，默认为10
min_bin_size (float) -- 每箱最小样本占比，默认为0.01
kwargs -- 其他传递给OptimalBinning的参数

返回:

PSI值

返回类型:

float

参考样例

>>> from hscredit.core.metrics import psi, psi_rating
>>> import numpy as np
>>> np.random.seed(42)
>>> train_scores = np.random.randn(1000)  # 训练集评分分布
>>> test_scores = np.random.randn(1000) + 0.3  # 测试集评分分布偏移
>>> p = psi(train_scores, test_scores)  # 计算PSI评估分布稳定性
>>> print(f"PSI={p:.4f}, 评级: {psi_rating(p)}")

hscredit.core.metrics.psi_table(expected, actual, method='quantile', max_n_bins=10, min_bin_size=0.01, **kwargs)[源代码]

计算PSI详细统计表.

返回每个分箱的期望占比、实际占比及PSI贡献，用于分析分布变化的具体来源。

参数

参数:

expected (ndarray | Series) -- 期望分布数据（通常是训练集或基准数据）
actual (ndarray | Series) -- 实际分布数据（通常是测试集或新数据）
method (str) -- 分箱方法，默认为'quantile'（等频分箱）
max_n_bins (int) -- 最大分箱数，默认为10
min_bin_size (float) -- 每箱最小样本占比，默认为0.01
kwargs -- 其他传递给OptimalBinning的参数

返回:

包含各分箱详细统计的DataFrame，列包括： - 分箱: 分箱标签 - 期望样本数: 该分箱内期望数据量 - 实际样本数: 该分箱内实际数据量 - 期望占比: 期望样本占总样本比例 - 实际占比: 实际样本占总样本比例 - PSI贡献: 该分箱对总PSI的贡献

返回类型:

DataFrame

参考样例

>>> from hscredit.core.metrics import psi_table
>>> import numpy as np
>>> np.random.seed(42)
>>> train = np.random.randn(1000)
>>> test = np.random.randn(1000) + 0.5
>>> table = psi_table(train, test)
>>> print(table)

hscredit.core.metrics.psi_rating(psi_value)[源代码]

根据PSI值返回稳定性评级.

参数

参数:: psi_value (float) -- PSI值（通常由psi()函数计算得到）
返回:: 稳定性评级描述字符串 - PSI < 0.1: "没有显著变化 (PSI < 0.1)" - 0.1 <= PSI < 0.25: "有轻微变化 (0.1 <= PSI < 0.25)" - PSI >= 0.25: "有显著变化 (PSI >= 0.25)"
返回类型:: str

参考样例

>>> from hscredit.core.metrics import psi_rating
>>> psi_rating(0.05)
'没有显著变化 (PSI < 0.1)'
>>> psi_rating(0.3)
'有显著变化 (PSI >= 0.25)'

hscredit.core.metrics.csi(expected, actual, method='quantile', max_n_bins=10, min_bin_size=0.01, **kwargs)[源代码]

计算Characteristic Stability Index (特征稳定性指标).

CSI是PSI的变体，专门用于衡量单个特征分布的稳定性。与PSI的区别在于CSI通常针对单一特征，而非模型评分。

参数

参数:

expected (ndarray | Series) -- 期望分布数据（通常是训练集的特征数据）
actual (ndarray | Series) -- 实际分布数据（通常是测试集或新数据的特征）
method (str) -- 分箱方法，默认为'quantile'（等频分箱）
max_n_bins (int) -- 最大分箱数，默认为10
min_bin_size (float) -- 每箱最小样本占比，默认为0.01
kwargs -- 其他传递给OptimalBinning的参数

返回:

CSI值（计算方法与PSI相同）

抛出:

ValueError -- 数据为空时

返回类型:

float

参考样例

>>> from hscredit.core.metrics import csi
>>> import numpy as np
>>> np.random.seed(42)
>>> train = np.random.randn(1000)
>>> test = np.random.randn(1000) + 0.5
>>> csi(train, test)
0.34

hscredit.core.metrics.csi_table(expected, actual, method='quantile', max_n_bins=10, min_bin_size=0.01, **kwargs)[源代码]

计算CSI详细统计表.

参数

参数:

expected (ndarray | Series) -- 期望分布数据（通常是训练集的特征数据）
actual (ndarray | Series) -- 实际分布数据（通常是测试集或新数据的特征）
method (str) -- 分箱方法，默认为'quantile'（等频分箱）
max_n_bins (int) -- 最大分箱数，默认为10
min_bin_size (float) -- 每箱最小样本占比，默认为0.01
kwargs -- 其他传递给OptimalBinning的参数

返回:

包含各分箱详细统计的DataFrame，列与psi_table相同，PSI贡献列重命名为CSI贡献

返回类型:

DataFrame

参考样例

>>> from hscredit.core.metrics import csi_table
>>> import numpy as np
>>> np.random.seed(42)
>>> train = np.random.randn(1000)
>>> test = np.random.randn(1000) + 0.5
>>> table = csi_table(train, test)
>>> print(table)

hscredit.core.metrics.batch_psi(X_train, X_test, features=None, method='quantile', max_n_bins=10, min_bin_size=0.01, **kwargs)[源代码]

批量计算多特征的PSI.

对指定的多个特征同时计算PSI，返回各特征的PSI值和稳定性评级。

参数

参数:

X_train (DataFrame) -- 训练集特征DataFrame
X_test (DataFrame) -- 测试集特征DataFrame（与X_train列结构一致）
features (List[str] | None) -- 需要计算PSI的特征列表，默认为None（计算全部共同列）
method (str) -- 分箱方法，默认为'quantile'（等频分箱）
max_n_bins (int) -- 最大分箱数，默认为10
min_bin_size (float) -- 每箱最小样本占比，默认为0.01
kwargs -- 其他传递给OptimalBinning的参数

返回:

包含各特征PSI结果的DataFrame，列包括： - 特征: 特征名称 - PSI: PSI值 - 评级: 稳定性评级（由psi_rating函数返回）

返回类型:

DataFrame

参考样例

>>> from hscredit.core.metrics import batch_psi
>>> import numpy as np
>>> import pandas as pd
>>> np.random.seed(42)
>>> cols = ['age', 'income', 'credit_score']
>>> X_train = pd.DataFrame(np.random.randn(1000, 3), columns=cols)
>>> X_test = pd.DataFrame(np.random.randn(1000, 3) + 0.5, columns=cols)
>>> result = batch_psi(X_train, X_test)
>>> print(result)

hscredit.core.metrics.lift(y_true, y_prob, threshold=0.5)[源代码]

计算Lift值 (模型提升度).

Lift = 命中样本坏账率 / 总体坏账率。 Lift > 1 表示模型效果优于随机，Lift值越高表示模型对高风险群体的区分能力越强。

参数

参数:

y_true (ndarray | Series) -- 真实标签 (0/1)，0为负样本（好样本），1为正样本（坏样本）
y_prob (ndarray | Series) -- 预测概率或评分（高值表示高风险）
threshold (float) -- 分类阈值，默认为0.5。高于此阈值的样本视为"命中"

返回:

Lift值（>1表示有效，>3表示良好）

抛出:

ValueError -- y_true和y_prob长度不一致时

返回类型:

float

参考样例

>>> from hscredit.core.metrics import lift
>>> import numpy as np
>>> np.random.seed(42)
>>> y_true = np.random.randint(0, 2, 1000)  # 真实标签（0=好，1=坏）
>>> y_prob = np.random.uniform(0, 1, 1000)  # 预测概率
>>> lift(y_true, y_prob, threshold=0.8)  # 高阈值命中高分样本，计算LIFT值
1.5

hscredit.core.metrics.lift_at(y_true, y_prob, ratios=None, ascending=False)[源代码]

计算指定覆盖率下的LIFT值.

支持 1%/3%/5%/10% 等任意比例，适配风控场景中头部/尾部区分能力分析。

参数

参数:

y_true (ndarray | Series) -- 真实标签 (0/1)，0为负样本（好样本），1为正样本（坏样本）
y_prob (ndarray | Series) -- 预测概率或评分（高值表示高风险）
ratios (float | List[float]) -- 覆盖率，标量（如 0.05）或列表（如 [0.01, 0.03, 0.05, 0.10]）。默认为 [0.01, 0.03, 0.05, 0.10]
ascending (bool) -- False=高概率排前（风险模型头部），True=低概率排前（尾部分析），默认为False

返回:

单个 float（ratios 为标量时）或 DataFrame（ratios 为列表时）， DataFrame列包括：覆盖率、样本数、坏样本数、坏样本率、坏样本捕获率、LIFT值

返回类型:

float | DataFrame

参考样例

>>> from hscredit.core.metrics import lift_at
>>> import numpy as np
>>> np.random.seed(42)
>>> y_true = np.random.randint(0, 2, 1000)
>>> y_prob = np.random.uniform(0, 1, 1000)
>>> lift_at(y_true, y_prob, ratios=0.05)
1.4
>>> result = lift_at(y_true, y_prob, ratios=[0.01, 0.03, 0.05, 0.10])
>>> print(result)

hscredit.core.metrics.lift_table(y_true, y_prob, method='quantile', max_n_bins=10, min_bin_size=0.01, **kwargs)[源代码]

计算Lift详细统计表.

按预测概率分箱后计算每箱的样本统计、Lift值和累积Lift值。

参数

参数:

y_true (ndarray | Series) -- 真实标签 (0/1)，0为负样本（好样本），1为正样本（坏样本）
y_prob (ndarray | Series) -- 预测概率或评分
method (str) -- 分箱方法，默认为'quantile'（等频分箱）
max_n_bins (int) -- 最大分箱数，默认为10
min_bin_size (float) -- 每箱最小样本占比，默认为0.01
kwargs -- 其他传递给OptimalBinning的参数

返回:

包含各分箱详细统计的DataFrame，列包括：分箱序号、最小概率、最大概率、样本数、好样本数、坏样本数、坏样本率、样本占比、Lift值、坏账改善、累积Lift值、累积坏账改善

抛出:

ValueError -- 数据全部为缺失值时

返回类型:

DataFrame

参考样例

>>> from hscredit.core.metrics import lift_table
>>> import numpy as np
>>> np.random.seed(42)
>>> y_true = np.random.randint(0, 2, 1000)
>>> y_prob = np.random.uniform(0, 1, 1000)
>>> table = lift_table(y_true, y_prob, max_n_bins=5)
>>> print(table[['分箱', '样本数', '坏样本率', 'Lift值']])

hscredit.core.metrics.lift_curve(y_true, y_prob, percentages=None, tail=False)[源代码]

计算Lift曲线数据.

返回在不同覆盖率下的样本统计和Lift值，用于绘制Lift曲线和Decile Lift分析。

参数

参数:

y_true (ndarray | Series) -- 真实标签 (0/1)，0为负样本（好样本），1为正样本（坏样本）
y_prob (ndarray | Series) -- 预测概率或评分（高值表示高风险）
percentages (List[float]) -- 百分比切分点列表，默认为 [0.01, 0.03, 0.05, 0.10, 0.20, 0.30, 0.50] 支持任意比例组合
tail (bool) -- False=从高概率端截取（头部高风险客群，适合风险识别场景）， True=从低概率端截取（尾部低风险客群，适合优质客群筛选），默认为False

返回:

包含各覆盖率统计的DataFrame，列包括： - 覆盖率: 百分比标签 - 样本数: 截取的样本数 - 坏样本数: 截取样本中的坏样本数 - 坏样本捕获率: 坏样本捕获率 - Lift值: 该覆盖率下的Lift值

返回类型:

DataFrame

参考样例

>>> from hscredit.core.metrics import lift_curve
>>> import numpy as np
>>> np.random.seed(42)
>>> y_true = np.random.randint(0, 2, 1000)
>>> y_prob = np.random.uniform(0, 1, 1000)
>>> curve = lift_curve(y_true, y_prob, percentages=[0.05, 0.10, 0.20])
>>> print(curve)

hscredit.core.metrics.lift_monotonicity_check(y_true, y_prob, n_bins=10, direction='both')[源代码]

检查LIFT单调性.

风控场景理想状态：高风险端（头部）坏率单调递减，低风险端（尾部）坏率单调递增。违反单调性意味着评分在某区间区分能力弱，可作为调参约束目标。

参数

参数:

y_true (ndarray | Series) -- 真实标签 (0/1)，0为负样本（好样本），1为正样本（坏样本）
y_prob (ndarray | Series) -- 预测概率或评分（高值表示高风险）
n_bins (int) -- 分箱数，默认为10
direction (str) -- 检验方向，默认为'both' - 'head': 仅检验头部（高概率→低概率坏率是否递减） - 'tail': 仅检验尾部 - 'both': 头尾均检验

返回:

字典，含以下键： - head_monotonic (bool): 头部是否单调 - tail_monotonic (bool): 尾部是否单调 - head_lift_values (list): 头部各分箱LIFT值（由高风险到低风险） - tail_lift_values (list): 尾部各分箱LIFT值（由低风险到高风险） - head_violations (list): 头部违反单调性的分箱对 [(i, j, 差值)] - tail_violations (list): 尾部违反单调性的分箱对 - head_violation_ratio (float): 头部违反比例 0.0~1.0 - tail_violation_ratio (float): 尾部违反比例 0.0~1.0 - head_bin_table (pd.DataFrame): 头部分箱坏率统计表 - tail_bin_table (pd.DataFrame): 尾部分箱坏率统计表

返回类型:

Dict[str, Any]

参考样例

>>> from hscredit.core.metrics import lift_monotonicity_check
>>> import numpy as np
>>> np.random.seed(42)
>>> y_true = np.random.randint(0, 2, 1000)
>>> y_prob = np.random.uniform(0, 1, 1000)
>>> result = lift_monotonicity_check(y_true, y_prob, n_bins=10)
>>> print(result['head_monotonic'])

hscredit.core.metrics.rule_lift(y_true, rule_mask, amount=None)[源代码]

计算规则的Lift指标.

评估单一规则的命中样本相对于总体的坏账率提升，用于规则效果评估与对比。

参数

参数:

y_true (ndarray | Series) -- 真实标签 (0/1)，0为负样本（好样本），1为正样本（坏样本）
rule_mask (ndarray | Series) -- 规则命中掩码（布尔数组或0/1数组，True/1表示样本命中该规则）
amount (ndarray | Series | None) -- 金额数据（可选，用于计算金额维度的Lift指标）

返回:

Lift指标字典，包含以下键： - hit_count: 命中样本数 - hit_rate: 命中率（命中样本占总样本比例） - bad_count: 命中样本中的坏样本数 - good_count: 命中样本中的好样本数 - badrate: 命中样本坏账率 - overall_badrate: 总体坏账率 - lift: Lift值（命中坏账率/总体坏账率） - bad_improve: 坏账改善度（总体坏账率-非命中坏账率）/总体坏账率 - total_amount: 总金额（当amount非None时） - hit_amount: 命中金额（当amount非None时） - bad_amount: 命中金额中的坏样本对应金额（当amount非None时） - amount_lift: 金额维度Lift值（当amount非None时）

抛出:

ValueError -- y_true和rule_mask长度不一致时
ValueError -- amount长度与y_true不一致时

返回类型:

Dict[str, Any]

参考样例

>>> from hscredit.core.metrics import rule_lift
>>> import numpy as np
>>> np.random.seed(42)
>>> y_true = np.random.randint(0, 2, 1000)
>>> rule_mask = np.random.rand(1000) > 0.8  # 20%样本命中规则
>>> result = rule_lift(y_true, rule_mask)
>>> print(f"命中数={result['hit_count']}, Lift={result['lift']:.4f}")

hscredit.core.metrics.badrate(y_true, weights=None)[源代码]

计算总体坏账率.

坏账率 = 坏样本数 / 总样本数，即目标变量为1的样本占比。

参数

参数:

y_true (ndarray | Series) -- 真实标签 (0/1)，0为负样本（好样本），1为正样本（坏样本）
weights (ndarray | Series | None) -- 样本权重（可选），用于加权计算坏账率

返回:

坏账率，取值范围[0, 1]

返回类型:

float

参考样例

>>> from hscredit.core.metrics import badrate
>>> import numpy as np
>>> np.random.seed(42)
>>> y_true = np.random.randint(0, 2, 1000)
>>> badrate(y_true)
0.5

hscredit.core.metrics.badrate_by_group(y_true, group, weights=None)[源代码]

按分组计算坏账率.

将样本按指定分组变量进行分群，分别计算各组的坏账率，用于群体风险对比分析。

参数

参数:

y_true (ndarray | Series) -- 真实标签 (0/1)，0为负样本（好样本），1为正样本（坏样本）
group (ndarray | Series) -- 分组标签（支持数值型或分类型，如渠道、地区、年龄段等）
weights (ndarray | Series | None) -- 样本权重（可选），用于加权计算各组坏账率

返回:

各组坏账率统计的DataFrame，按坏账率降序排列，列包括： - 分组: 分组标签 - 样本数: 该组总样本数 - 好样本数: 该组好样本数量 - 坏样本数: 该组坏样本数量 - 坏账率: 该组坏账率 - 样本占比: 该组样本占总样本比例 - 与总体差异: 该组坏账率与总体坏账率的差值

抛出:

ValueError -- y_true和group长度不一致时

返回类型:

DataFrame

参考样例

>>> from hscredit.core.metrics import badrate_by_group
>>> import numpy as np
>>> np.random.seed(42)
>>> y_true = np.random.randint(0, 2, 1000)
>>> groups = np.random.choice(['A', 'B', 'C', 'D'], size=1000)
>>> result = badrate_by_group(y_true, groups)
>>> print(result)

hscredit.core.metrics.badrate_trend(y_true, date, freq='M')[源代码]

计算坏账率时间趋势.

按指定时间频率聚合样本，计算各时间段的坏账率及环比变化，支持日/周/月/季度多时间粒度分析。

参数

参数:

y_true (ndarray | Series) -- 真实标签 (0/1)，0为负样本（好样本），1为正样本（坏样本）
date (ndarray | Series) -- 日期数据（支持pandas datetime、numpy datetime64或字符串日期）
freq (str) -- 时间频率，默认为'M'（月） - 'D': 按日统计 - 'W': 按周统计 - 'M': 按月统计 - 'Q': 按季度统计

返回:

时间趋势数据DataFrame，列包括： - 时间周期: 统计时间段标签 - 样本数: 该时间段内样本总数 - 好样本数: 该时间段内好样本数量 - 坏样本数: 该时间段内坏样本数量 - 坏账率: 该时间段内坏账率 - 环比变化: 与上一期坏账率的差值 - 累积坏账率: 截至该时间段的累积坏账率

抛出:

ValueError -- y_true和date长度不一致时
ValueError -- freq不在'D'/'W'/'M'/'Q'范围内时

返回类型:

DataFrame

参考样例

>>> from hscredit.core.metrics import badrate_trend
>>> import numpy as np
>>> import pandas as pd
>>> np.random.seed(42)
>>> n = 1000
>>> y_true = np.random.randint(0, 2, n)
>>> dates = pd.date_range('2024-01-01', periods=n, freq='D')
>>> result = badrate_trend(y_true, dates, freq='M')
>>> print(result)

hscredit.core.metrics.badrate_by_score_bin(y_true, score, method='quantile', max_n_bins=10, min_bin_size=0.01, **kwargs)[源代码]

按评分分箱计算坏账率.

将评分按指定分箱方法划分为多个区间，计算各区间的坏账率及与总体坏账率的差异，用于评分卡分布分析与区间风险对比。

参数

参数:

y_true (ndarray | Series) -- 真实标签 (0/1)，0为负样本（好样本），1为正样本（坏样本）
score (ndarray | Series) -- 评分或预测概率（高评分/高概率表示高风险）
method (str) -- 分箱方法，默认为'quantile'（等频分箱），支持与OptimalBinning相同的全部分箱方法
max_n_bins (int) -- 最大分箱数，默认为10
min_bin_size (float) -- 每箱最小样本占比，默认为0.01
kwargs -- 其他传递给OptimalBinning的参数

返回:

分箱坏账率统计DataFrame，列包括： - 分箱: 分箱序号 - 最小评分: 该分箱内评分最小值 - 最大评分: 该分箱内评分最大值 - 样本数: 该分箱内样本总数 - 好样本数: 该分箱内好样本数量 - 坏样本数: 该分箱内坏样本数量 - 坏账率: 该分箱内坏账率 - 与总体差异: 该分箱坏账率与总体坏账率的差值

抛出:

ValueError -- 数据全部为缺失值时
ValueError -- y_true和score长度不一致时

返回类型:

DataFrame

参考样例

>>> from hscredit.core.metrics import badrate_by_score_bin
>>> import numpy as np
>>> np.random.seed(42)
>>> y_true = np.random.randint(0, 2, 1000)
>>> score = np.random.randn(1000) * 50 + 600  # 模拟评分分布
>>> result = badrate_by_score_bin(y_true, score, max_n_bins=5)
>>> print(result)

hscredit.core.metrics.score_stats(score, y_true=None)[源代码]

计算评分统计信息.

提供评分的完整描述性统计信息，包括样本量、缺失情况、分布特征，以及（当提供目标变量时）KS值和AUC值。

参数

参数:

score (ndarray | Series) -- 评分或预测概率数据（支持数值型数组）
y_true (ndarray | Series | None) -- 真实标签（可选，0/1。如果提供则计算KS和AUC）

返回:

评分统计字典，包含以下键： - 样本数: 评分总样本数 - 缺失数: 缺失值数量 - 缺失率: 缺失值占比 - 均值: 评分均值 - 标准差: 评分标准差 - 最小值: 评分最小值 - 最大值: 评分最大值 - 中位数: 评分中位数 - 分位数_25: 25%分位数 - 分位数_75: 75%分位数 - KS: （仅当y_true非None时）KS统计量 - AUC: （仅当y_true非None时）AUC值

返回类型:

Dict[str, Any]

参考样例

>>> from hscredit.core.metrics import score_stats
>>> import numpy as np
>>> np.random.seed(42)
>>> score = np.random.randn(1000) * 50 + 600
>>> stats = score_stats(score)
>>> print(f"均值={stats['均值']:.2f}, 标准差={stats['标准差']:.2f}")
>>> y_true = np.random.randint(0, 2, 1000)
>>> stats_with_target = score_stats(score, y_true)
>>> print(f"KS={stats_with_target.get('KS', 0):.4f}")

hscredit.core.metrics.score_stability(score_train, score_test, method='quantile', max_n_bins=10, min_bin_size=0.01, **kwargs)[源代码]

计算评分稳定性.

使用PSI（群体稳定性指标）评估训练集评分与测试集（新数据）评分之间的分布差异，封装了psi_table函数，提供简化的稳定性分析接口。

参数

参数:

score_train (ndarray | Series) -- 训练集评分（期望分布）
score_test (ndarray | Series) -- 测试集评分（实际分布）
method (str) -- 分箱方法，默认为'quantile'（等频分箱），支持与OptimalBinning相同的全部分箱方法
max_n_bins (int) -- 最大分箱数，默认为10
min_bin_size (float) -- 每箱最小样本占比，默认为0.01
kwargs -- 其他传递给OptimalBinning的参数

返回:

PSI详细统计表DataFrame，列包括： - 分箱: 分箱标签 - 期望样本数: 训练集该分箱内样本数 - 实际样本数: 测试集该分箱内样本数 - 期望占比: 训练集该分箱样本占总样本比例 - 实际占比: 测试集该分箱样本占总样本比例 - PSI贡献: 该分箱对总PSI的贡献

返回类型:

DataFrame

参考样例

>>> from hscredit.core.metrics import score_stability
>>> import numpy as np
>>> np.random.seed(42)
>>> train_scores = np.random.randn(1000) * 50 + 600
>>> test_scores = np.random.randn(1000) * 50 + 605
>>> result = score_stability(train_scores, test_scores)
>>> print(result)

hscredit.core.metrics.mse(y_true, y_pred)[源代码]

计算均方误差 (Mean Squared Error).

MSE = (1/n) * Σ(y_true - y_pred)²，对大误差更敏感。

参数

参数:

y_true (ndarray | Series) -- 真实值（目标变量）
y_pred (ndarray | Series) -- 预测值

返回:

MSE值，非负浮点数

返回类型:

float

参考样例

>>> from hscredit.core.metrics import mse
>>> y_true = [1.0, 2.0, 3.0, 4.0]
>>> y_pred = [1.1, 2.2, 2.9, 4.1]
>>> mse(y_true, y_pred)
0.0175

hscredit.core.metrics.mae(y_true, y_pred)[源代码]

计算平均绝对误差 (Mean Absolute Error).

MAE = (1/n) * Σ|y_true - y_pred|，对异常值鲁棒。

参数

参数:

y_true (ndarray | Series) -- 真实值（目标变量）
y_pred (ndarray | Series) -- 预测值

返回:

MAE值，非负浮点数

返回类型:

float

参考样例

>>> from hscredit.core.metrics import mae
>>> y_true = [1.0, 2.0, 3.0, 4.0]
>>> y_pred = [1.1, 2.2, 2.9, 4.1]
>>> mae(y_true, y_pred)
0.125

hscredit.core.metrics.rmse(y_true, y_pred)[源代码]

计算均方根误差 (Root Mean Squared Error).

RMSE = sqrt(MSE)，与目标变量单位一致，便于解释。

参数

参数:

y_true (ndarray | Series) -- 真实值（目标变量）
y_pred (ndarray | Series) -- 预测值

返回:

RMSE值，非负浮点数

返回类型:

float

参考样例

>>> from hscredit.core.metrics import rmse
>>> y_true = [1.0, 2.0, 3.0, 4.0]
>>> y_pred = [1.1, 2.2, 2.9, 4.1]
>>> rmse(y_true, y_pred)
0.132...

hscredit.core.metrics.r2(y_true, y_pred)[源代码]

计算决定系数 (R-squared).

R² = 1 - SS_res / SS_tot，其中SS_res为残差平方和，SS_tot为总平方和。取值范围通常为[0, 1]，越接近1表示模型拟合效果越好。

参数

参数:

y_true (ndarray | Series) -- 真实值（目标变量）
y_pred (ndarray | Series) -- 预测值

返回:

R²值，通常在[0, 1]范围内（可为负如果模型比均值预测更差）

返回类型:

float

参考样例

>>> from hscredit.core.metrics import r2
>>> y_true = [1.0, 2.0, 3.0, 4.0]
>>> y_pred = [1.1, 2.2, 2.9, 4.1]
>>> r2(y_true, y_pred)
0.988...

hscredit.core.metrics.compute_bin_stats(bins, y, target_type='binary', amount=None, epsilon=1e-10, bin_labels=None, round_digits=True, woe_clip=None)[源代码]

计算分箱统计信息（hscredit 全库统一的分箱指标计算入口）.

一次性计算某一特征分箱后的全部统计指标。所有分箱器、IV/PSI/LIFT 指标、规则报告与可视化均复用本函数，以保证口径一致。支持三种目标类型。

参数

参数:

bins (ndarray) -- 分箱索引数组（整数）。约定 -1 表示缺失值箱、-2 表示特殊值箱，两者在输出中被排到正常分箱之后
y (ndarray) --
目标变量，含义随 target_type 而变：
- target_type='binary'：0/1 数组（0=好样本，1=坏样本）
- target_type='continuous'：连续值数组（如逾期金额、余额）
- target_type='amount_weighted'：0/1 数组，并配合 amount 使用
target_type (Literal['binary', 'continuous', 'amount_weighted']) --
目标变量类型，默认 'binary'：
- 'binary'：二分类，计算样本/好坏数、坏样本率、WOE、IV、LIFT、KS 等
- 'continuous'：连续目标，计算各箱均值/求和等金额统计，不计算 WOE/IV
- 'amount_weighted'：基于二元标签但所有统计按 amount 加权（金额维度坏账）
amount (ndarray | None) -- 金额数组，仅 target_type='amount_weighted' 时必需，长度同 y
epsilon (float) -- 平滑参数，避免 WOE/IV 计算中除零或取对数为 ±inf，默认 1e-10
bin_labels (List[str] | None) -- 可选的分箱区间标签列表，长度需与唯一分箱数一致；缺省时输出箱序号
round_digits (bool) -- 是否对浮点列做四舍五入格式化，默认 True；作为中间计算（如指标搜索）时应设为 False 以保留精度
woe_clip (float | None) -- WOE 值截断阈值，默认 None 不截断。当某箱无坏样本或无好样本时 WOE 可能趋于 ±inf，设置后将 WOE 限制在 [-woe_clip, woe_clip]，避免评分卡分数异常

返回:

分箱统计 DataFrame（中文列名）。binary 模式主要列包括： 分箱 / 分箱标签 / 样本总数 / 好样本数 / 坏样本数 / 样本占比 / 坏样本率 / WOE值 / 分档IV值 / LIFT值 / 累积坏样本数 / 累积好样本数 / 分档KS值 / 坏账改善 等。累积类指标从正常分箱中坏样本率较高的一端开始计算，缺失值、特殊值等保留箱最后纳入累计，输出行顺序保持不变

返回类型:

DataFrame

参考样例

>>> import numpy as np
>>> from hscredit.core.metrics import compute_bin_stats
>>> bins = np.array([0, 0, 1, 1, 2, 2])
>>>
>>> # 二元目标（0/1）
>>> y_binary = np.array([0, 1, 0, 1, 0, 1])
>>> compute_bin_stats(bins, y_binary, target_type='binary')
>>>
>>> # 连续目标（逾期金额）
>>> y_amount = np.array([0, 1000, 0, 2000, 0, 1500])
>>> compute_bin_stats(bins, y_amount, target_type='continuous')
>>>
>>> # 金额加权（按逾期金额加权的坏账统计）
>>> y_flag = np.array([0, 1, 0, 1, 0, 1])
>>> amount = np.array([100, 1000, 200, 2000, 150, 1500])
>>> compute_bin_stats(bins, y_flag, target_type='amount_weighted', amount=amount)

引用

WOE / IV 的定义见 Siddiqi, N. (2006). Credit Risk Scorecards. Wiley；本函数的 WOE 取 ln(坏样本占比 / 好样本占比)，与 toad、scorecardpipeline 口径一致。

hscredit.core.metrics.add_margins(table)[源代码]

为分箱表添加合计行.

在分箱统计表末尾追加一行“合计”，对原始计数列求和、累计计数列取总体值，对率值类列按总体重算。缺失值箱与特殊值箱被放在正常分箱之后、合计行之前。兼容单层表头与多级表头（MultiIndex），同时支持样本口径与金额口径。

参数

参数:: table (DataFrame) -- 分箱统计表，通常由 compute_bin_stats() 生成，需包含 分箱标签 列；为空表时原样返回
返回:: 在末尾添加 合计 行后的分箱表（不修改入参，返回新对象）
返回类型:: DataFrame

参考样例

>>> import numpy as np
>>> from hscredit.core.metrics import compute_bin_stats, add_margins
>>> table = compute_bin_stats(np.array([0, 0, 1, 1]), np.array([0, 1, 0, 1]))
>>> add_margins(table)

hscredit.core.metrics.quadratic_curve_coefficient(bins, y, metric='lift', monotonic='descending')[源代码]

计算分箱曲线的二次项系数指标.

基于分箱后的 LIFT值 或 坏样本率 序列做二次多项式拟合，返回经趋势方向标准化后的二次项系数。返回值越大，表示曲线越符合指定趋势且弯曲程度越明显，可作为“最优分箱”搜索的目标函数。

参数

参数:

bins (ndarray) -- 分箱索引数组（整数）
y (ndarray) -- 目标变量 (0/1)，0=好样本，1=坏样本
metric (Literal['lift', 'bad_rate']) --
拟合曲线类型，默认 'lift'：
- 'lift'：使用各箱 LIFT 值序列
- 'bad_rate'：使用各箱坏样本率序列
monotonic (Literal['ascending', 'descending', 'valley', 'peak']) --
目标趋势，默认 'descending'：
- 'ascending'：期望曲线单调递增（使用单调约束二次拟合，保证拟合曲线在区间内只增不减）
- 'descending'：期望曲线单调递减（使用单调约束二次拟合，保证拟合曲线在区间内只减不增）
- 'valley'：期望曲线先降后升（U 形，二次项系数为正）
- 'peak'：期望曲线先升后降（倒 U 形，二次项系数为负）

返回:

标准化后的二次项系数；曲线违反目标趋势时返回负值作为惩罚，有效箱数不足 3 或曲线为常数时返回 0.0

返回类型:

float

参考样例

>>> import numpy as np
>>> from hscredit.core.metrics import quadratic_curve_coefficient
>>> bins = np.array([0, 0, 1, 1, 2, 2, 3, 3])
>>> y = np.array([1, 1, 1, 0, 0, 1, 0, 0])
>>> quadratic_curve_coefficient(bins, y, metric='lift', monotonic='descending')

hscredit.core.metrics.composite_binning_quality(bins, y, metric='lift', monotonic='descending')[源代码]

计算复合分箱质量评分.

在 quadratic_curve_coefficient() 之外，进一步将多项业务偏好加权汇总为单一评分，用于驱动“最优分箱”搜索，使分箱在保持单调趋势的同时兼顾头尾区分度与样本占比。显式纳入目标的分量包括：二次曲线得分、头部累计收益、尾部压降收益、样本占比加权边际收益、边际收益递减惩罚、头尾样本占比下限偏好、尾部塌陷/相邻零坏样本率惩罚等。

参数

参数:

bins (ndarray) -- 分箱索引数组（整数）
y (ndarray) -- 目标变量 (0/1)，0=好样本，1=坏样本
metric (Literal['lift', 'bad_rate']) -- 拟合曲线类型，'lift' 或 'bad_rate'，默认 'lift' （含义同 quadratic_curve_coefficient()）
monotonic (Literal['ascending', 'descending', 'valley', 'peak']) -- 目标趋势，'ascending' / 'descending' / 'valley' / 'peak'，默认 ``'descending'``（含义同 quadratic_curve_coefficient()）

返回:

复合质量评分（float），越大表示分箱质量越好

返回类型:

float

参考样例

>>> import numpy as np
>>> from hscredit.core.metrics import composite_binning_quality
>>> bins = np.array([0, 0, 1, 1, 2, 2, 3, 3])
>>> y = np.array([1, 1, 1, 0, 0, 1, 0, 0])
>>> composite_binning_quality(bins, y, metric='lift', monotonic='descending')

指标 hscredit.core.metrics

指标 `hscredit.core.metrics`