模型可解释性
hscredit.core.models.explainability 统一结构化 SHAP 结果、全局和局部解释、中文绘图、业务原因码与
受约束反事实建议。反事实仅表示模型条件下的非因果候选变化，不构成授信承诺或审批依据。
- class hscredit.core.models.explainability.ExplanationResult(_explanation, _data, _sample_ids, target_class, output_index, model_output, explainer_type, background_summary, dataset_fingerprint, metadata)[源代码]
基类：
object一次模型解释计算的只读、可审计结果。
- 参数:
_explanation (Any)
_data (DataFrame)
_sample_ids (Index)
target_class (Any)
output_index (int | None)
model_output (str)
explainer_type (str)
background_summary (Mapping[str, Any])
dataset_fingerprint (str)
metadata (Mapping[str, Any])
- target_class: Any
- output_index: int | None
- model_output: str
- explainer_type: str
- background_summary: Mapping[str, Any]
- dataset_fingerprint: str
- metadata: Mapping[str, Any]
- classmethod from_explanation(explanation, *, data, target_class, output_index, model_output, explainer_type, background_summary, metadata)[源代码]
规范化 SHAP 输出并构造形状一致、外部不可原地修改的审计结果。
- 参数:
explanation (Any)
data (Any)
target_class (Any)
output_index (int | None)
model_output (str)
explainer_type (str)
background_summary (Mapping[str, Any])
metadata (Mapping[str, Any])
- 返回类型:
- property explanation: Any
返回独立的 SHAP Explanation 副本。
- property data: DataFrame
返回解释输入的深复制，避免外部修改审计结果。
- property sample_ids: Index
返回样本索引副本。
- property values: ndarray
返回二维 SHAP 贡献值副本。
- property base_values: ndarray
返回每个样本的 SHAP 基准值副本。
- property feature_names: list
返回固定顺序的特征名。
- class hscredit.core.models.explainability.ModelExplainer(model, feature_names=None, background_data=None, algorithm='auto', model_output='probability', target_class=1, max_background=200, random_state=42, explainer_type=None)[源代码]
基类：
object面向信贷模型的结构化 SHAP 解释器。
参数
- 参数:
model (Any) -- 已拟合且提供预测接口的模型。
background_data (DataFrame | ndarray | None) -- SHAP 背景数据；未提供时从解释数据确定性抽样。
algorithm (str) --
auto、tree、linear、permutation或kernel。feature_names (Sequence[str] | None)
model_output (str)
target_class (Any)
max_background (int)
random_state (int)
explainer_type (str | None)
属性
last_result_: 最近一次ExplanationResult。参考样例
>>> result = ModelExplainer(model, background_data=X_train).explain(X_test) >>> ModelExplainer(model).get_global_report(result)
- explain(X, *, max_samples=None, max_evals=None, check_additivity=True)[源代码]
计算选定类别的结构化 SHAP 解释。
- 参数:
X (ndarray | DataFrame)
max_samples (int | None)
max_evals (int | None)
check_additivity (bool)
- 返回类型:
- compute_shap_values(X, check_additivity=True)[源代码]
计算并返回选定类别的二维 SHAP 数组。
- 参数:
check_additivity (bool)
- 返回类型:
ndarray
- get_sample_report(result=None, *, sample_id=None, position=None, top_n=None)[源代码]
按样本索引或位置生成局部贡献长表。
- 返回类型:
DataFrame
- select_representative_samples(result=None, threshold=0.5, risk_direction=None)[源代码]
选择最高/最低风险、阈值附近、中位输出和贡献最大的代表样本。
- 参数:
result -- 结构化解释结果；None 时使用最近一次结果。
threshold -- 当前输出尺度下的业务决策阈值。
risk_direction --
higher_output_higher_risk或higher_output_lower_risk； None 时从解释元信息推导。
- 返回:
包含样本索引、选择理由、模型输出、风险排名和阈值距离的中文表。
- 返回类型:
DataFrame
- get_correlation_report(result=None, kind='feature_shap')[源代码]
返回特征-SHAP 或 SHAP-SHAP 的相关性报告。
- 返回类型:
DataFrame
- get_feature_clusters(result=None, max_clusters=None)[源代码]
按 SHAP 贡献相关性返回层次聚类叶序和聚类编号。
- 返回类型:
DataFrame
- get_feature_interactions(X=None, top_n=10, result=None)[源代码]
返回树模型精确交互或非树模型近似交互的前 N 个特征对。
- 返回类型:
DataFrame
- get_approximate_interactions(result=None, top_n=10)[源代码]
根据 SHAP 贡献 Spearman 相关性返回近似交互特征对。
- 返回类型:
DataFrame
- get_stability_report(result=None, *, mode='sample', X_train=None, y_train=None, X_validation=None, n_bootstrap=100, confidence_level=0.95, top_k=10, random_state=None)[源代码]
评估固定样本 Bootstrap 或模型重训后的解释稳定性。
- 返回类型:
DataFrame
- get_reason_codes(result=None, *, keep=3, risk_direction='higher_output_higher_risk', feature_map=None, reason_map=None)[源代码]
返回只包含不利局部贡献的中文业务原因码。
- 返回类型:
DataFrame
- plot_shap_summary(X=None, plot_type='dot', max_display=20, show=True, **kwargs)[源代码]
绘制 SHAP summary 图；支持
dot、violin和bar。
- class hscredit.core.models.explainability.CounterfactualExplainer(model, reference_data, constraints=None, output_type='auto', positive_class=1, max_candidates=100)[源代码]
基类：
object在模型与显式约束下搜索最小特征变更方案。
输出仅表示模型条件下的非因果建议，不代表真实因果效果或授信承诺。
- hscredit.core.models.explainability.model_explain_report(model, X=None, importance_type='gain', top_n=None, normalize=True)[源代码]
生成模型特征解释报告.
不依赖 SHAP，优先复用模型自身
get_feature_importances，再依次回退到feature_importances_/coef_，用于没有安装解释扩展包时的基础模型解释。- 参数:
model (BaseRiskModel) -- 已训练模型
X (DataFrame | ndarray | None) -- 特征矩阵，可选，用于推断特征名
importance_type (str) -- 模型重要性类型，默认
'gain'top_n (int | None) -- 返回前 N 个特征，None 表示全部返回
normalize (bool) -- 是否增加归一化重要性列，默认 True
- 返回:
模型解释报告 DataFrame，列名为中文
- 返回类型:
DataFrame
参考样例
>>> report = model_explain_report(model, X_test, importance_type='coef') >>> print(report[['特征名', '重要性', '排名']].head())
- hscredit.core.models.explainability.build_reason_codes(result, *, keep=3, risk_direction='higher_output_higher_risk', feature_map=None, reason_map=None)[源代码]
仅将风险方向一致的不利 SHAP 贡献转换为原因码。
- 参数:
keep (int)
risk_direction (str)
feature_map (Mapping[str, str] | None)
reason_map (Mapping[str, Mapping[str, Any]] | None)
- 返回类型:
DataFrame
- hscredit.core.models.explainability.plot_feature_importance(model, X=None, top_n=20, importance_type='gain', figsize=(10, 8), title=None, color='#2E86AB', show_values=True, show=True)[源代码]
绘制模型原生特征重要性水平条形图。
- 参数:
model -- 已拟合且提供原生重要性或系数的模型。
X -- 用于推断特征名的 DataFrame 或数组，可选。
top_n -- 展示前 N 个特征，必须为正整数。
importance_type -- 传给模型重要性接口的类型。
figsize -- Matplotlib 画布大小。
title -- 自定义标题；None 时使用中文默认标题。
color -- 条形颜色，显式值优先。
show_values -- 是否标注重要性数值。
show -- 是否调用
plt.show()。
- 返回:
Matplotlib Figure。