概率校准

hscredit.core.models.calibration 提供二分类概率校准算法、预训练模型包装器、校准报告和中文可靠性图。底层算法接受一维正类概率；ProbabilityCalibrator 接受模型特征并保持 classes_ 的真实概率列顺序。

class hscredit.core.models.calibration.BaseCalibrator(n_bins=10, strategy='uniform')[源代码]

基类：ArtifactSerializableMixin, BaseEstimator, ABC

概率校准算法的统一基类。

参数

参数:

n_bins (int) -- 校准指标与可靠性曲线分箱数，必须为正整数。
strategy (str) -- "uniform" 等宽分箱或 "quantile" 等频分箱。

artifact_kind = '概率校准器'

abstractmethod fit(y_prob, y_true)[源代码]: 使用原始正类概率和 0/1 标签拟合校准映射。

abstractmethod calibrate(y_prob)[源代码]: 把一维原始正类概率映射为一维校准概率。

transform(y_prob)[源代码]: 按 sklearn Transformer 风格返回一维校准概率。

predict_proba(y_prob)[源代码]: 返回 [P(0), P(1)] 两列校准概率。

compute_brier_score(y_true, y_prob)[源代码]

计算越小越好的 Brier 分数。

返回类型:: float

compute_calibration_metrics(y_true, y_prob)[源代码]

计算 Brier、ECE、MCE 和样本数。

返回类型:: Dict[str, float]

plot_reliability_diagram(y_true, y_prob, y_prob_calibrated=None, figsize=(10, 8), title=None, show=True, colors=None)[源代码]

绘制校准可靠性、概率分布、指标和概率变换四联图。

返回类型:: matplotlib.figure.Figure

class hscredit.core.models.calibration.PlattCalibrator(n_bins=10, strategy='uniform', C=1.0)[源代码]

基类：BaseCalibrator

在原始概率的 log-odds 上拟合逻辑回归校准映射。

参数:

n_bins (int)
strategy (str)
C (float)

fit(y_prob, y_true)[源代码]

拟合 Platt Scaling 并返回自身。

参数:

y_prob (ndarray | Series)
y_true (ndarray | Series)

calibrate(y_prob)[源代码]: 返回 Platt 校准后的一维概率。

class hscredit.core.models.calibration.IsotonicCalibrator(n_bins=10, strategy='uniform', out_of_bounds='clip')[源代码]

基类：BaseCalibrator

使用保序回归拟合非参数概率校准映射。

参数:

n_bins (int)
strategy (str)
out_of_bounds (str)

fit(y_prob, y_true)[源代码]: 拟合保序回归并返回自身。

calibrate(y_prob)[源代码]: 返回保序回归校准后的一维概率。

class hscredit.core.models.calibration.BetaCalibrator(n_bins=10, strategy='uniform')[源代码]

基类：BaseCalibrator

使用 log(p) 与 -log(1-p) 特征拟合 Beta 校准。

参数:

n_bins (int)
strategy (str)

fit(y_prob, y_true)[源代码]: 拟合 Beta 校准逻辑回归并返回自身。

calibrate(y_prob)[源代码]: 返回 Beta 校准后的一维概率。

class hscredit.core.models.calibration.HistogramCalibrator(n_bins=10, strategy='quantile')[源代码]

基类：BaseCalibrator

使用箱内真实正类频率进行直方图概率校准。

参数:

n_bins (int)
strategy (str)

fit(y_prob, y_true)[源代码]: 拟合直方图边界和箱内频率并返回自身。

calibrate(y_prob)[源代码]: 返回输入概率所在箱的真实正类频率。

class hscredit.core.models.calibration.ProbabilityCalibrator(method='platt', calib_ratio=0.2, n_bins=10, random_state=None, target='target', model=None, positive_class=None, calibrator_params=None)[源代码]

基类：ArtifactSerializableMixin, BaseEstimator, ClassifierMixin

概率校准器 - 统一入口.

提供统一的概率校准接口，支持多种校准方法。

参数

参数:

method (str) -- 校准方法，默认'platt' - 'platt': Platt Scaling (Sigmoid校准) - 'isotonic': 保序回归校准 - 'beta': Beta分布校准 - 'histogram': 直方图分箱校准
calib_ratio (float | None) -- 用于校准的数据比例，默认0.2 - 从训练集中划分出calib_ratio的数据用于校准 - 如果为None，需要使用独立的校准集
n_bins (int) -- 可靠性曲线的分箱数，默认10
random_state (int | None) -- 随机种子，默认None
target (str) -- 目标列名，默认'target' - 用于从DataFrame中提取目标变量
positive_class (Any | None) -- 正类标签；None 时使用基础模型 classes_[1]。
calibrator_params (Dict[str, Any] | None) -- 传递给具体校准算法的可克隆参数字典。
model (Any | None)

属性

变量:

calibrator_ -- 底层校准器实例
is_fitted_ -- 是否已拟合
calib_metrics_ -- 校准前后的指标对比

参数:

method (str)
calib_ratio (float | None)
n_bins (int)
random_state (int | None)
target (str)
model (Any | None)
positive_class (Any | None)
calibrator_params (Dict[str, Any] | None)

参考样例

>>> # 方式1：使用独立校准集
>>> calibrator = ProbabilityCalibrator(method='isotonic', model=model, calib_ratio=None)
>>> calibrator.fit(X_calib, y_calib)
>>> proba_calib = calibrator.predict_proba(X_test)

>>> # 方式2：自动划分校准集
>>> calibrator = ProbabilityCalibrator(method='platt', model=model, calib_ratio=0.2)
>>> calibrator.fit(X_train, y_train)  # 自动划分20%用于校准
>>> proba_calib = calibrator.predict_proba(X_test)

>>> # 方式3：scorecardpipeline风格
>>> calibrator = ProbabilityCalibrator(method='platt', model=model, calib_ratio=None)
>>> calibrator.fit(df_calib)  # df_calib包含target列
>>> proba_calib = calibrator.predict_proba(df_test)

>>> # 评估校准效果
>>> calibrator.plot_reliability_diagram(X_test, y_test)
>>> metrics = calibrator.get_calibration_metrics()

CALIB_METHODS = {'beta': <class 'hscredit.core.models.calibration.methods.BetaCalibrator'>, 'histogram': <class 'hscredit.core.models.calibration.methods.HistogramCalibrator'>, 'isotonic': <class 'hscredit.core.models.calibration.methods.IsotonicCalibrator'>, 'platt': <class 'hscredit.core.models.calibration.methods.PlattCalibrator'>, 'sigmoid': <class 'hscredit.core.models.calibration.methods.PlattCalibrator'>}

artifact_kind = '概率校准模型'

fit(X, y=None, model=None, target=None, **fit_params)[源代码]

拟合校准器.

支持两种传参风格：

sklearn风格:

calibrator = ProbabilityCalibrator(model=model, calib_ratio=None)
calibrator.fit(X_calib, y_calib)

scorecardpipeline风格:

calibrator = ProbabilityCalibrator(model=model, calib_ratio=None)
calibrator.fit(df_calib)  # df_calib包含target列

参数:

model -- 已训练的基础模型
X (ndarray | DataFrame) -- 特征矩阵或包含target的DataFrame
y (ndarray | Series | None) -- 目标变量，可选
target (str | None) -- 目标列名，默认使用初始化时设置的target
fit_params -- 其他参数

返回:

self

返回类型:

ProbabilityCalibrator

predict_proba(X)[源代码]

预测校准后的概率.

参数:: X (ndarray | DataFrame) -- 特征矩阵
返回:: 两列概率数组，shape (n_samples, 2)
返回类型:: ndarray

predict(X, threshold=0.5)[源代码]

预测类别标签.

参数:

X (ndarray | DataFrame) -- 特征矩阵
threshold (float) -- 分类阈值，默认0.5

返回:

预测类别

返回类型:

ndarray

get_calibration_metrics()[源代码]

获取校准前后的指标对比.

返回:: 包含校准前后指标的字典
返回类型:: Dict[str, Dict[str, float]]

calibration_report(X, y=None, target=None)[源代码]

生成校准前后指标对比报告.

返回:

包含指标、校准前、校准后、改善值和改善率的中文 DataFrame

参数:

X (ndarray | DataFrame)
y (ndarray | Series | None)
target (str | None)

返回类型:

DataFrame

report(X, y=None, target=None)[源代码]

calibration_report 的统一报告入口.

参数:: target (str | None)
返回类型:: DataFrame

plot_reliability_diagram(X, y=None, target=None, figsize=(10, 8), title=None, show=True, colors=None)[源代码]

绘制可靠性曲线.

参数:

X (ndarray | DataFrame) -- 特征矩阵或包含target的DataFrame
y (ndarray | Series | None) -- 目标变量，可选
target (str | None) -- 目标列名（scorecardpipeline风格使用）
figsize (Tuple[int, int]) -- 图表大小，默认(10, 8)
title (str | None) -- 图表标题，可选
show (bool) -- 是否显示图表，默认True
colors (List[str] | None)

返回:

matplotlib Figure对象

返回类型:

matplotlib.figure.Figure

calibrate_proba(y_prob)[源代码]

直接校准概率（不通过模型）.

参数:: y_prob (ndarray | Series) -- 原始概率
返回:: 校准后的概率
返回类型:: ndarray

class hscredit.core.models.calibration.CalibratedModel(base_model, calibrator)[源代码]

基类：ArtifactSerializableMixin, BaseEstimator, ClassifierMixin

已校准模型包装器.

将基础模型和校准器组合在一起，提供统一的预测接口。

参数

参数:

base_model -- 基础模型
calibrator (ProbabilityCalibrator) -- 概率校准器实例

参考样例

>>> from hscredit.core.models import XGBoost
>>> from hscredit.core.models.calibration import ProbabilityCalibrator, CalibratedModel
>>>
>>> # 训练基础模型
>>> model = XGBoost()
>>> model.fit(X_train, y_train)
>>>
>>> # 创建校准器并拟合
>>> calibrator = ProbabilityCalibrator(method='platt', model=model, calib_ratio=None)
>>> calibrator.fit(X_calib, y_calib)
>>>
>>> # 包装为已校准模型
>>> calibrated_model = CalibratedModel(model, calibrator)
>>> proba = calibrated_model.predict_proba(X_test)

artifact_kind = '概率校准模型'

predict_proba(X)[源代码]

预测校准后的正类（坏样本）概率。

将基础模型输出的原始概率经已拟合的校准器映射为更准确的概率。

参数:: X (ndarray | DataFrame) -- 特征矩阵，DataFrame 或 ndarray
返回:: 两列校准概率数组，shape (n_samples, 2)
返回类型:: ndarray

predict(X, threshold=0.5)[源代码]

基于校准后概率预测类别标签。

参数:

X (ndarray | DataFrame) -- 特征矩阵，DataFrame 或 ndarray
threshold (float) -- 判正阈值，校准概率 >= threshold 记为 1，默认为 0.5

返回:

0/1 类别数组

返回类型:

ndarray

predict_score(X)[源代码]

将校准后概率线性映射为 0–1000 的风险评分（概率越低分越高）。

采用 score = (1 - p) * 1000 的简易映射；若需标准 log-odds 评分卡刻度，请改用 ScoreCard 或 StandardScoreTransformer。

参数:: X (ndarray | DataFrame) -- 特征矩阵，DataFrame 或 ndarray
返回:: 0–1000 区间的风险评分数组
返回类型:: ndarray

evaluate(X, y, sample_weight=None, metrics=None)[源代码]

评估校准后模型的区分度与校准度。

参数:

X (ndarray | DataFrame) -- 特征矩阵，DataFrame 或 ndarray
y (ndarray | Series) -- 真实标签（0/1）
sample_weight (ndarray | None) -- 样本权重；KS 与 Lift 不支持时发出一次中文警告。
metrics (List[str] | None) -- 指标名列表；None 时返回 AUC、KS 和 Brier。

返回:

含 AUC / KS （区分度）与 Brier （校准度）的指标字典

返回类型:

Dict[str, float]

参考样例

>>> calibrated.evaluate(X_test, y_test)
{'AUC': ..., 'KS': ..., 'Brier': ...}

hscredit.core.models.calibration.calibrate_model(model, X_calib, y_calib=None, method='platt', target='target', **kwargs)[源代码]

便捷函数：创建并拟合概率校准器.

参数:

model -- 已训练的基础模型
X_calib (ndarray | DataFrame) -- 校准集特征或包含target的DataFrame
y_calib (ndarray | Series | None) -- 校准集标签，可选
method (str) -- 校准方法，默认'platt'
target (str) -- 目标列名（scorecardpipeline风格使用）
kwargs -- 其他参数

返回:

拟合好的ProbabilityCalibrator

返回类型:

ProbabilityCalibrator

参考样例

>>> calibrator = calibrate_model(model, X_calib, y_calib, method='isotonic')
>>> proba_calib = calibrator.predict_proba(X_test)

hscredit.core.models.calibration.plot_calibration_comparison(y_true, y_prob_dict, n_bins=10, figsize=(12, 5), title=None, show=True, colors=None)[源代码]

绘制多个模型的可靠性曲线和 Brier/ECE 指标比较。

参数:

y_true (ndarray | Series)
y_prob_dict (Dict[str, ndarray | Series])
n_bins (int)
figsize (Tuple[int, int])
title (str | None)
show (bool)
colors (List[str] | None)