数据探索 `hscredit.core.eda`

57 种数据探索与策略分析能力：数据质量、目标分布、坏率趋势、客群画像与迁移、 Vintage、Roll Rate、策略仿真、稳定性（PSI/CSI）等。

EDA (Exploratory Data Analysis) 模块 - 金融信贷数据探索性分析.

提供金融风控场景下的完整数据探索功能，采用函数式API设计： - 数据概览与质量评估 - 目标变量分析 (逾期率、分布) - 特征分析 (数值/类别特征分布) - 特征与标签关系 (IV、WOE、逾期率分箱) - 特征稳定性分析 (PSI、CSI、时间稳定性) - 相关性分析 - Vintage分析 - 综合报告生成

所有函数统一返回DataFrame格式，列名使用中文，便于理解和报告生成。

示例:

>>> import hscredit.core.eda as eda
>>>
>>> # 数据概览
>>> summary = eda.data_info(df)
>>>
>>> # 批量IV分析
>>> iv_result = eda.batch_iv_analysis(df, features=['age', 'income'], target='fpd15')
>>>
>>> # 逾期率趋势
>>> trend = eda.bad_rate_trend(df, target_col='fpd15', date_col='apply_month')
>>>
>>> # Vintage分析
>>> vintage = eda.vintage_analysis(df, vintage_col='issue_month', mob_col='mob', target_col='ever_dpd30')

hscredit.core.eda.data_info(df)[源代码]

数据集基础信息统计.

参数:: df (DataFrame) -- 输入数据
返回:: 数据集信息DataFrame，列包括[信息项, 值]
返回类型:: DataFrame

参考样例

>>> info = data_info(df)
>>> print(info)
            信息项         值
    样本数（行）     10000
   特征数（列）        50
    数值型特征        30
    分类型特征        15
    日期型特征         5
    缺失值列数        10
  内存使用(MB)      15.5

hscredit.core.eda.missing_analysis(df, threshold=0.0, features=None)[源代码]

缺失值分析.

参数:

df (DataFrame) -- 输入数据
threshold (float) -- 缺失率阈值，仅返回缺失率>=该值的特征
features (List[str]) -- 指定分析的特征列表，None则分析全部

返回:

缺失值分析DataFrame，列包括[特征名, 缺失数, 缺失率, 非空数, 查得率]

返回类型:

DataFrame

参考样例

>>> missing = missing_analysis(df, threshold=0.05)
>>> print(missing)
      特征名  缺失数   缺失率(%)  非空数  查得率(%)
0     age      0      0.00  10000    100.0
1  income    500      5.00   9500     95.0

hscredit.core.eda.feature_summary(df, features=None, y=None, val_df=None, models=None, model_type=None, model_params=None, max_n_bins=10, psi_method='random_split', psi_group_col=None, psi_date_col=None, psi_freq='M', psi_test_size=0.3, percentiles=None, random_state=42, numeric_as_categorical=None, force_numeric=None, n_jobs=-1, parallel_backend=None, parallel_config=None, show_progress=False, binning_method='quantile', binning_params=None)[源代码]

综合特征描述统计.

整合特征基础统计、IV、KS、PSI和模型特征重要性，快速获取数据集特征详情。

无论字段是字符还是数字，返回列名都是一致的： - 数值型特征：分位数返回对应分位点的数值 - 类别型特征：分位数返回按类别样本数逆序排列后对应分位点的类别值

参数:

df (DataFrame) -- 训练/基准数据集
features (List[str]) -- 特征列表，None则分析全部
y (str | Series | ndarray | List | Tuple | None) -- 目标变量，支持列名、数组、列表、元组或Series，不传则不计算IV/KS/特征重要性
val_df (DataFrame | None) -- 验证集，用于计算PSI，不传则使用psi_method指定的方式
models (Dict[str, Any] | None) -- 已训练好的模型字典，格式{'模型名': model}，用于获取特征重要性 - model需要支持feature_importances_属性或get_feature_importance()方法
model_type (Literal['xgboost', 'lightgbm', 'catboost', 'randomforest'] | None) -- 模型类型，用于自动训练模型提取特征重要性，可选'xgboost'/'lightgbm'/'catboost'/'randomforest'
model_params (Dict | None) -- 模型参数，配合model_type使用
max_n_bins (int) -- IV、趋势和PSI共用的最大分箱数，默认10
psi_method (Literal['random_split', 'group_col', 'date_col']) -- PSI计算方式 - 'random_split': 随机拆分两份数据计算PSI（默认） - 'group_col': 按psi_group_col指定的分组列计算PSI - 'date_col': 按psi_date_col指定的日期列分组计算PSI
psi_group_col (str | None) -- 分组列名（当psi_method='group_col'时使用）
psi_date_col (str | None) -- 日期列名（当psi_method='date_col'时使用）
psi_freq (str) -- 时间频率，'D'/'W'/'M'/'Q'，默认'M'
psi_test_size (float) -- 随机拆分比例（当psi_method='random_split'时使用），默认0.3
percentiles (List[float]) -- 分位数点，默认[0.01, 0.05, 0.25, 0.5, 0.75, 0.95, 0.99]
random_state (int) -- 随机种子
numeric_as_categorical (List[str] | None) -- 强制视为分类变量的数值列名列表（仅当指定时才生效）
force_numeric (List[str] | None) -- 强制视为数值变量的列名列表（仅当指定时才生效）
n_jobs (int) -- 并行工作数。-1根据数据规模保守推断，1为串行，正整数为明确指定
parallel_backend (str | None) -- 显式 joblib 后端；指定后优先于自动后端选择
parallel_config (Dict[str, Any] | None) -- 统一并行扩展配置，不会被函数原地修改
show_progress (bool) -- 是否显示已处理字段数、总字段数和当前处理字段
binning_method (str) -- IV、趋势和PSI共用的分箱方法，默认'quantile'（等频分箱）
binning_params (Dict[str, Any] | None) -- 传给OptimalBinning的扩展参数。外层 binning_method、max_n_bins、 random_state 的优先级高于其中的同名键；user_splits 字典按原字段名配置

返回:

综合特征描述DataFrame，包含以下列： - 基础统计: 特征名、字段类型、样本数、缺失数/率、唯一值数、众数等 - 分布统计: 最小值、最大值、平均值、标准差、各分位数 - 质量指标: 零值率、负值率、重复率 - 预测指标（传入y时）: IV、KS、趋势 - 稳定性指标: PSI - 重要性指标（传入models时）: 各模型特征重要性

返回类型:

DataFrame

所有比例字段返回0~1原始小数，所有数值指标均保留底层计算完整精度；展示格式由 pandas Styler或ExcelWriter的percent_cols等外部配置负责。

趋势列说明:

ascending: 坏样本率单调递增
descending: 坏样本率单调递减
peak: 倒U型趋势（先增后减）
valley: U型趋势（先减后增）
categorical: 类别型特征
unknown: 无法确定趋势

参考样例

>>> # 基础统计（无目标变量）
>>> summary = feature_summary(df)

>>> # 包含IV、KS、趋势（传入目标变量）
>>> summary = feature_summary(df, y='target')

>>> # 包含PSI（随机拆分）
>>> summary = feature_summary(df, y='target', psi_method='random_split')

>>> # 按日期分组计算PSI
>>> summary = feature_summary(df, y='target', psi_method='date_col', psi_date_col='apply_date')

>>> # 传入已训练模型获取特征重要性
>>> models = {'XGB': xgb_model, 'LGB': lgb_model}
>>> summary = feature_summary(df, y='target', models=models)

>>> # 自动训练模型获取特征重要性
>>> summary = feature_summary(df, y='target', model_type='xgboost')

>>> # 指定数值列视为分类变量（如年龄分段编码）
>>> summary = feature_summary(df, y='target', numeric_as_categorical=['age_group'])

>>> # 三项指标共用显式分箱；外层参数覆盖 binning_params 中的同名参数
>>> summary = feature_summary(
...     df,
...     y='target',
...     binning_method='quantile',
...     max_n_bins=10,
...     binning_params={
...         'min_bin_size': 0.05,
...         'user_splits': {'age': [25, 35, 45]},
...         'user_splits_fixed': True,
...     },
... )

hscredit.core.eda.numeric_summary(df, features=None, percentiles=None)[源代码]

数值特征详细统计.

参数:

df (DataFrame) -- 输入数据
features (List[str]) -- 指定分析的特征列表，None则分析全部数值型特征
percentiles (List[float]) -- 额外分位数，默认[0.01, 0.05, 0.95, 0.99]

返回:

数值特征统计DataFrame

返回类型:

DataFrame

参考样例

>>> num_stats = numeric_summary(df)
>>> print(num_stats[['特征名', '均值', '标准差', '偏度', '峰度']])

hscredit.core.eda.category_summary(df, features=None, max_categories=10)[源代码]

类别特征统计.

参数:

df (DataFrame) -- 输入数据
features (List[str]) -- 指定分析的特征列表，None则分析全部分类别特征
max_categories (int) -- 显示最常见的N个类别

返回:

类别特征统计DataFrame

返回类型:

DataFrame

参考样例

>>> cat_stats = category_summary(df)
>>> print(cat_stats[['特征名', '类别数', '最常见类别', '最常见占比(%)']])

hscredit.core.eda.data_quality_report(df, features=None, missing_threshold=0.5, constant_threshold=0.95)[源代码]

数据质量综合报告.

参数:

df (DataFrame) -- 输入数据
features (List[str]) -- 指定分析的特征列表，None则分析全部
missing_threshold (float) -- 缺失率阈值，超过视为质量问题
constant_threshold (float) -- 常数比例阈值，超过视为准常数特征

返回:

数据质量报告DataFrame，列包括[特征名, 问题类型, 严重程度, 建议处理]

返回类型:

DataFrame

参考样例

>>> quality = data_quality_report(df)
>>> print(quality)
      特征名      问题类型  严重程度         建议处理
0    phone      高缺失率      高    考虑删除或填充
1   status    准常数特征      中  检查业务意义

hscredit.core.eda.feature_group_analysis(df, features=None, group_cols=None, date_col=None, date_freq='M', stats='default', y=None, y_stats=None, sort_by=None, sort_order='desc', custom_sort_func=None, feature_order=None, include_overall=True, pivot=True, n_jobs=-1, parallel_backend=None, parallel_config=None)[源代码]

分组特征分布分析.

分析生产环境中特定时间段、客群或两者交叉组合下的特征分布，适用于监控不同维度下的特征表现、对比分析等场景。

参数:

df (DataFrame) -- 输入数据
features (List[str]) -- 分析的特征列表，None则分析全部数值型特征
group_cols (str | List[str]) -- 客群分组列（单级或多级），如 'segment' 或 ['segment', 'channel']
date_col (str | None) -- 时间列，用于时间分组分析，支持日期格式
date_freq (str) -- 时间频率，'D'日/'W'周/'M'月/'Q'季/'Y'年，默认'M'
stats (str | List[str] | Callable | Dict[str, Callable]) -- 统计指标 - 'default': 默认统计[均值、中位数、标准差、缺失率、唯一值数] - 'all': 全部基础统计指标 - 列表: 指定统计指标，如['均值', '标准差', 'IV'] - 函数: 自定义统计函数，接收Series返回标量 - 字典: 指标名到函数的映射，如{'变异系数': lambda x: x.std()/x.mean()}
y (str | Series | None) -- 目标变量，用于计算y相关统计（如逾期率、IV等）
y_stats (List[str]) -- y相关统计指标，如['逾期率', 'IV', 'KS']，需传入y才生效
sort_by (str | Tuple[str, str] | None) -- 排序依据，可以是'特征名'、'统计项'或(特征名, 统计项)元组
sort_order (Literal['desc', 'asc', 'custom']) -- 排序方式，'desc'降序/'asc'升序/'custom'自定义
custom_sort_func (Callable | None) -- 自定义排序函数，当sort_order='custom'时使用接收DataFrame，返回排序后的DataFrame
feature_order (List[str] | None) -- 特征顺序列表，用于指定特征展示顺序
include_overall (bool) -- 是否包含总体统计列
pivot (bool) -- 是否透视结果（True: 特征×统计项为行，分组为列；False: 长格式）

返回:

分组分析结果DataFrame - pivot=True时：多级索引(特征名, 统计项)，列为分组 - pivot=False时：长格式，包含[特征名, 统计项, 分组, 值]等列

返回类型:

DataFrame

参考样例

>>> # 单维度客群分组分析
>>> result = feature_group_analysis(
...     df,
...     features=['age', 'income'],
...     group_cols='customer_segment',
...     stats=['均值', '中位数', '缺失率']
... )
>>>
>>> # 时间维度分析（按月）
>>> result = feature_group_analysis(
...     df,
...     features=['age', 'income'],
...     date_col='apply_date',
...     date_freq='M',
...     stats='default'
... )
>>>
>>> # 客群+时间交叉分析（多级列）
>>> result = feature_group_analysis(
...     df,
...     features=['age', 'income'],
...     group_cols='segment',
...     date_col='apply_date',
...     date_freq='M'
... )
>>>
>>> # 自定义统计指标
>>> custom_stats = {
...     '变异系数': lambda x: x.std() / x.mean() if x.mean() != 0 else np.nan,
...     '10%分位数': lambda x: x.quantile(0.1),
...     '90%分位数': lambda x: x.quantile(0.9),
... }
>>> result = feature_group_analysis(df, features=['age'], stats=custom_stats)
>>>
>>> # 包含目标变量分析（如逾期率）
>>> result = feature_group_analysis(
...     df,
...     features=['age', 'income'],
...     group_cols='segment',
...     y='fpd15',
...     y_stats=['逾期率', '样本数']
... )
>>>
>>> # 排序展示
>>> result = feature_group_analysis(
...     df,
...     features=['age', 'income'],
...     group_cols='segment',
...     sort_by=('age', '均值'),
...     sort_order='desc'
... )

hscredit.core.eda.population_stability_monitor(expected, actual, segment_cols, binning_method='quantile', n_bins=5, bin_edges=None, date_col=None, date_freq='M', group_col=None, metrics='占比', sort_by=None, sort_order='desc', n_jobs=-1, parallel_backend=None, parallel_config=None)[源代码]

群体稳定性监控分析（Population Stability Monitor）.

金融风控中监控客群分布变化的核心方法，基于期望样本（expected）构建客群分层标准，分析实际样本（actual）在各维度下的客群占比变化。

适用场景: - 模型上线后监控生产客群是否偏离训练样本分布 - 对比不同时间段（如各月、各季度）的客群结构变化 - 分析不同渠道、产品线的客群构成差异 - 快速识别客群漂移（Population Drift）风险

指标说明: - 占比: 该分层在总样本中的比例（默认） - 样本数: 该分层的样本数量 - 绝对变化率: actual占比 - expected占比（百分点差值） - 相对变化率: (actual占比 - expected占比) / expected占比 × 100%

参数:

expected (DataFrame) -- 期望/基准数据集（如训练集、历史样本），用于构建分层标准
actual (DataFrame) -- 实际/监控数据集（如生产数据、近期样本），用于分析客群变化
segment_cols (str | List[str]) -- 客群分层变量，支持单变量或多变量交叉 - 字符串: 单一变量（如'收入'） - 列表: 多变量交叉（如['收入层级', '信用等级']）
binning_method (str) -- 分箱方法（当传入bin_edges时此参数忽略） - 'quantile': 等频分箱（默认，客群规模相近） - 'uniform': 等距分箱 - 'tree': 决策树分箱
n_bins (int) -- 分箱数，默认5层
bin_edges (Dict[str, List] | None) -- 自定义分箱边界，格式{变量名: [边界列表]} - 传入后直接使用，无需expected数据集计算分箱
date_col (str | None) -- 时间列，用于时间维度监控（如各月对比）
date_freq (str) -- 时间频率，'D'日/'W'周/'M'月/'Q'季，默认'M'
group_col (str | None) -- 分类列，用于分类维度监控（如各渠道对比）
metrics (str | List[str]) -- 统计指标，支持单选或多选 - '占比': 占比百分比（默认） - '样本数': 样本数量 - '绝对变化率': 占比差值（actual - expected） - '相对变化率': 占比变化百分比 - 列表: 多指标同时显示，如['占比', '样本数', '绝对变化率']
sort_by (str | None) -- 排序依据，可选'expected'/'actual_首列'/'actual_末列'
sort_order (Literal['desc', 'asc']) -- 排序方式，'desc'降序/'asc'升序

返回:

客群监控结果DataFrame - Index: 分层标签（单级或多级索引） - Columns: (维度, 指标) 多级列，维度包含expected和各actual维度

返回类型:

DataFrame

参考样例

>>> # 1. 基础用法：监控生产客群相对训练集的变化
>>> result = population_stability_monitor(
...     expected=train_df,              # 训练集作为基准
...     actual=prod_df,                 # 生产数据
...     segment_cols='income'           # 收入分层监控
... )
>>>
>>> # 2. 时间维度：监控各月客群变化趋势
>>> result = population_stability_monitor(
...     expected=historical_df,
...     actual=prod_df,
...     segment_cols='risk_score',
...     date_col='apply_date',
...     date_freq='M'
... )
>>>
>>> # 3. 多维度交叉：收入+信用等级
>>> result = population_stability_monitor(
...     expected=baseline_df,
...     actual=current_df,
...     segment_cols=['income_level', 'credit_grade']
... )
>>>
>>> # 4. 自定义分箱边界（expected可传可不传）
>>> bin_edges = {'age': [0, 25, 35, 45, 55, 100]}
>>> result = population_stability_monitor(
...     expected=None,                  # 传入bin_edges后可不传
...     actual=prod_df,
...     segment_cols='age',
...     bin_edges=bin_edges
... )
>>>
>>> # 5. 多指标显示
>>> result = population_stability_monitor(
...     expected=train_df,
...     actual=prod_df,
...     segment_cols='score',
...     metrics=['占比', '样本数', '绝对变化率', '相对变化率']
... )
>>>
>>> # 6. 渠道维度对比
>>> result = population_stability_monitor(
...     expected=train_df,
...     actual=current_df,
...     segment_cols='customer_type',
...     group_col='channel'
... )

hscredit.core.eda.target_distribution(df, target_col)[源代码]

目标变量分布统计.

参数:

df (DataFrame) -- 输入数据
target_col (str) -- 目标变量列名

返回:

目标分布DataFrame，列包括[类别, 样本数, 占比, 累计占比]

返回类型:

DataFrame

参考样例

>>> dist = target_distribution(df, 'fpd15')
>>> print(dist)
   类别   样本数   占比(%)  累计占比(%)
0   0    8500   85.00      85.00
1   1    1500   15.00     100.00

hscredit.core.eda.bad_rate_overall(df, target_col=None, overdue=None, dpds=None, del_grey=False, *, target=None)[源代码]

计算整体逾期率.

支持单标签分析（通过target_col）或多标签分析（通过overdue+dpds）。

参数:

df (DataFrame) -- 输入数据
target_col (str | None) -- 目标变量列名（单标签模式）
overdue (str | List[str] | None) -- 逾期天数字段名或列表，如 'MOB1' 或 ['MOB1', 'MOB3']
dpds (int | List[int] | None) -- 逾期定义天数或列表，如 7 或 [0, 7, 30] - 逾期天数 > dpds 为坏样本(1)，其他为好样本(0)
del_grey (bool) -- 是否删除逾期天数在 (0, dpd] 区间的灰样本
target (str | None)

返回:

单标签返回字典，多标签返回DataFrame

返回类型:

Dict | DataFrame

参考样例

>>> # 单标签分析
>>> result = bad_rate_overall(df, target_col='fpd15')
>>> print(result)
{'样本总数': 10000, '好样本数': 8500, '坏样本数': 1500, '逾期率(%)': 15.0}

>>> # 多标签分析
>>> result = bad_rate_overall(df, overdue=['MOB1', 'MOB3'], dpds=[7, 30])
>>> print(result)
     标签      样本总数  好样本数  坏样本数  逾期率(%)
0  MOB1>7     9800    8820     980    10.00
1  MOB1>30    9800    9400     400     4.08

hscredit.core.eda.bad_rate_by_dimension(df, dim_col=None, target_col=None, overdue=None, dpds=None, del_grey=False, sort_by='bad_rate', *, target=None, segment_col=None)[源代码]

分维度逾期率分析.

支持单标签或多标签分析。

参数:

df (DataFrame) -- 输入数据
dim_col (str) -- 维度列名（如渠道、产品类型）
target_col (str | None) -- 目标变量列名（单标签模式）
overdue (str | List[str] | None) -- 逾期天数字段名或列表
dpds (int | List[int] | None) -- 逾期定义天数或列表
del_grey (bool) -- 是否删除灰样本
sort_by (str) -- 排序方式，'bad_rate'或'count'
target (str | None)
segment_col (str | None)

返回:

单标签返回DataFrame，多标签返回{标签名: DataFrame}字典

返回类型:

DataFrame | Dict[str, DataFrame]

参考样例

>>> # 单标签
>>> result = bad_rate_by_dimension(df, 'channel', target_col='fpd15')

>>> # 多标签
>>> result = bad_rate_by_dimension(df, 'channel', overdue='MOB1', dpds=[7, 30])
>>> print(result['MOB1>7'])

hscredit.core.eda.bad_rate_trend(df, date_col, target_col=None, overdue=None, dpds=None, del_grey=False, freq='M', dimensions=None, *, target=None)[源代码]

逾期率时间趋势分析.

支持单标签或多标签分析。

参数:

df (DataFrame) -- 输入数据
date_col (str) -- 日期列名
target_col (str | None) -- 目标变量列名（单标签模式）
overdue (str | List[str] | None) -- 逾期天数字段名或列表
dpds (int | List[int] | None) -- 逾期定义天数或列表
del_grey (bool) -- 是否删除灰样本
freq (str) -- 时间频率，'D'日/'W'周/'M'月/'Q'季度
dimensions (List[str] | None) -- 分维度分析列表
target (str | None)

返回:

单标签返回DataFrame，多标签返回{标签名: DataFrame}字典

返回类型:

DataFrame | Dict[str, DataFrame]

参考样例

>>> # 单标签
>>> trend = bad_rate_trend(df, 'apply_date', target_col='fpd15', freq='M')

>>> # 多标签
>>> trend = bad_rate_trend(df, 'apply_date', overdue=['MOB1', 'MOB3'], dpds=30, freq='M')
>>> print(trend['MOB1>30'])

hscredit.core.eda.bad_rate_by_bins(df, score_col, target_col=None, overdue=None, dpds=None, del_grey=False, n_bins=10, method='quantile')[源代码]

评分分箱逾期率分析.

支持单标签或多标签分析。

参数:

df (DataFrame) -- 输入数据
score_col (str) -- 评分列名
target_col (str | None) -- 目标变量列名（单标签模式）
overdue (str | List[str] | None) -- 逾期天数字段名或列表
dpds (int | List[int] | None) -- 逾期定义天数或列表
del_grey (bool) -- 是否删除灰样本
n_bins (int) -- 分箱数
method (str) -- 分箱方法，'quantile'等频/'uniform'等距

返回:

单标签返回DataFrame，多标签返回{标签名: DataFrame}字典

返回类型:

DataFrame | Dict[str, DataFrame]

参考样例

>>> # 单标签
>>> bins = bad_rate_by_bins(df, 'score', target_col='fpd15', n_bins=10)

>>> # 多标签
>>> bins = bad_rate_by_bins(df, 'score', overdue=['MOB1', 'MOB3'], dpds=30, n_bins=10)
>>> print(bins['MOB1>30'])

hscredit.core.eda.sample_distribution(df, date_col, freq='M', target_col=None, *, target=None)[源代码]

样本时间分布分析.

参数:

df (DataFrame) -- 输入数据
date_col (str) -- 日期列名
freq (str) -- 时间聚合频率，'D' 日 / 'W' 周 / 'M' 月 / 'Q' 季度，默认 'M'
target_col (str | None) -- 目标变量列名（如有）
target (str | None)

返回:

样本分布DataFrame

返回类型:

DataFrame

参考样例

>>> dist = sample_distribution(df, 'apply_date', target_col='fpd15')
>>> print(dist[['时间周期', '样本数', '坏样本数', '逾期率(%)']])

hscredit.core.eda.feature_type_inference(df, categorical_threshold=20, unique_ratio_threshold=0.05, numeric_as_categorical=None, force_numeric=None)[源代码]

自动推断特征类型.

默认严格按照实际数据类型判断： - 数值类型（int/float）-> 'numerical' - 非数值类型（object/string/category）-> 'categorical'

仅当用户指定参数时才进行特殊处理： - numeric_as_categorical: 将指定的数值列视为 categorical - force_numeric: 将指定的列视为 numerical

参数:

df (DataFrame) -- 输入数据
categorical_threshold (int) -- 保留参数，不再用于默认类型判断
unique_ratio_threshold (float) -- 保留参数，不再用于默认类型判断
numeric_as_categorical (List[str] | None) -- 强制视为分类变量的数值列名列表
force_numeric (List[str] | None) -- 强制视为数值变量的列名列表

返回:

特征类型DataFrame

返回类型:

DataFrame

参考样例

>>> types = feature_type_inference(df)
>>> print(types[['特征名', '特征类型', '唯一值数', '建议处理方式']])
>>> # 将特定数值列视为分类
>>> types = feature_type_inference(df, numeric_as_categorical=['education_level'])

hscredit.core.eda.numeric_distribution(df, feature, n_bins=20)[源代码]

数值特征分布统计.

参数:

df (DataFrame) -- 输入数据
feature (str) -- 特征名
n_bins (int) -- 分箱数

返回:

分布统计DataFrame

返回类型:

DataFrame

参考样例

>>> dist = numeric_distribution(df, 'age', n_bins=10)
>>> print(dist[['分箱区间', '频数', '频率(%)', '累计频率(%)']])

hscredit.core.eda.categorical_distribution(df, feature, top_n=None)[源代码]

类别特征分布统计.

参数:

df (DataFrame) -- 输入数据
feature (str) -- 特征名
top_n (int) -- 仅显示前N个类别

返回:

分布统计DataFrame

返回类型:

DataFrame

参考样例

>>> dist = categorical_distribution(df, 'education', top_n=5)
>>> print(dist[['类别值', '频数', '频率(%)']])

hscredit.core.eda.outlier_detection(df, features=None, method='iqr', threshold=1.5, n_jobs=-1, parallel_backend=None, parallel_config=None)[源代码]

异常值检测.

参数:

df (DataFrame) -- 输入数据
features (List[str]) -- 指定检测的特征，None则检测全部数值型
method (Literal['iqr', 'zscore', 'mad']) -- 检测方法，'iqr'/'zscore'/'mad'
threshold (float) -- 阈值

返回:

异常值统计DataFrame

返回类型:

DataFrame

参考样例

>>> outliers = outlier_detection(df, method='iqr')
>>> print(outliers[['特征名', '异常值数', '异常值率(%)', '正常范围']])

hscredit.core.eda.rare_category_detection(df, features=None, threshold=0.01, n_jobs=-1, parallel_backend=None, parallel_config=None)[源代码]

稀有类别检测.

参数:

df (DataFrame) -- 输入数据
features (List[str]) -- 指定检测的特征，None则检测全部分类别
threshold (float) -- 稀有阈值（频率低于此值视为稀有）

返回:

稀有类别统计DataFrame

返回类型:

DataFrame

参考样例

>>> rare = rare_category_detection(df, threshold=0.01)
>>> print(rare[['特征名', '稀有类别', '频数', '频率(%)', '建议']])

hscredit.core.eda.concentration_analysis(df, features=None, n_jobs=-1, parallel_backend=None, parallel_config=None)[源代码]

集中度分析(Gini系数).

参数:

df (DataFrame) -- 输入数据
features (List[str]) -- 指定分析的特征，None则分析全部数值型

返回:

集中度分析DataFrame

返回类型:

DataFrame

参考样例

>>> concentration = concentration_analysis(df)
>>> print(concentration[['特征名', 'Gini系数', '集中度评级']])

hscredit.core.eda.feature_stability_over_time(df, features, date_col, freq='M', n_jobs=-1, parallel_backend=None, parallel_config=None)[源代码]

特征时序稳定性分析.

参数:

df (DataFrame) -- 输入数据
features (List[str]) -- 指定分析的特征列表
date_col (str) -- 日期列名
freq (str) -- 时间聚合频率，'D' 日 / 'W' 周 / 'M' 月 / 'Q' 季度，默认 'M'

返回:

时序稳定性DataFrame

返回类型:

DataFrame

参考样例

>>> stability = feature_stability_over_time(df, ['age', 'income'], 'apply_date')
>>> print(stability[['特征名', '均值标准差', '变异系数', '稳定性评级']])

hscredit.core.eda.iv_analysis(df, feature, target, n_bins=10, method='quantile')[源代码]

单变量IV分析.

复用 hscredit.core.metrics.IV_table

参数:

df (DataFrame) -- 输入数据
feature (str) -- 特征名
target (str) -- 目标变量名
n_bins (int) -- 分箱数
method (str) -- 分箱方法，取值同 OptimalBinning （如 'quantile' 等频、'tree' 决策树、'chi' 卡方、'mdlp' 信息论、 'best_iv' 最优IV 等），默认 'quantile'

返回:

IV分析结果字典，包含[特征名, IV值, 预测能力, 分箱明细]

返回类型:

Dict[str, str | float | DataFrame]

参考样例

>>> result = iv_analysis(df, 'age', 'fpd15')
>>> print(f"IV值: {result['IV值']}, 预测能力: {result['预测能力']}")
>>> print(result['分箱明细'])

hscredit.core.eda.batch_iv_analysis(df, features, target, n_bins=10, method='quantile', return_details=False, n_jobs=-1, parallel_backend=None, parallel_config=None)[源代码]

批量IV分析.

复用 hscredit.core.metrics.batch_iv

参数:

df (DataFrame) -- 输入数据
features (List[str]) -- 特征列表
target (str) -- 目标变量名
n_bins (int) -- 分箱数
method (str) -- 分箱方法，取值同 OptimalBinning （如 'quantile' 等频、'tree' 决策树、'chi' 卡方、'mdlp' 信息论、 'best_iv' 最优IV 等），默认 'quantile'
return_details (bool) -- 是否返回详细分箱结果

返回:

IV分析结果DataFrame，列包括[特征名, IV值, 预测能力, 分箱数]

返回类型:

DataFrame

参考样例

>>> iv_result = batch_iv_analysis(df, ['age', 'income', 'score'], 'fpd15')
>>> print(iv_result[['特征名', 'IV值', '预测能力']].sort_values('IV值', ascending=False))

hscredit.core.eda.woe_analysis(df, feature, target, n_bins=10, method='quantile')[源代码]

WOE分箱分析.

复用 hscredit.core.metrics.IV_table 获取WOE值

参数:

df (DataFrame) -- 输入数据
feature (str) -- 特征名
target (str) -- 目标变量名
n_bins (int) -- 分箱数
method (str) -- 分箱方法，取值同 OptimalBinning （如 'quantile' 等频、'tree' 决策树、'chi' 卡方、'mdlp' 信息论、 'best_iv' 最优IV 等），默认 'quantile'

返回:

WOE分析DataFrame

返回类型:

DataFrame

参考样例

>>> woe_df = woe_analysis(df, 'age', 'fpd15')
>>> print(woe_df[['分箱', '分箱标签', 'WOE值', 'IV值']])

hscredit.core.eda.binning_bad_rate(df, feature, target, n_bins=10, method='quantile')[源代码]

分箱逾期率分析.

复用 hscredit.core.metrics.compute_bin_stats

参数:

df (DataFrame) -- 输入数据
feature (str) -- 特征名
target (str) -- 目标变量名
n_bins (int) -- 分箱数
method (str) -- 分箱方法，取值同 OptimalBinning （如 'quantile' 等频、'tree' 决策树、'chi' 卡方、'mdlp' 信息论、 'best_iv' 最优IV 等），默认 'quantile'

返回:

分箱逾期率DataFrame

返回类型:

DataFrame

参考样例

>>> bin_df = binning_bad_rate(df, 'score', 'fpd15', n_bins=10)
>>> print(bin_df[['分箱', '样本数', '逾期率', 'LIFT值']])

hscredit.core.eda.monotonicity_check(df, feature, target, n_bins=10)[源代码]

单调性检验.

检查特征分箱后的逾期率是否单调变化

参数:

df (DataFrame) -- 输入数据
feature (str) -- 特征名
target (str) -- 目标变量名
n_bins (int) -- 分箱数

返回:

单调性检验结果

返回类型:

Dict[str, str | float]

参考样例

>>> result = monotonicity_check(df, 'score', 'fpd15')
>>> print(f"单调性: {result['单调性']}, 相关系数: {result['Spearman相关系数']}")

hscredit.core.eda.univariate_auc(df, feature, target)[源代码]

单变量AUC分析.

参数:

df (DataFrame) -- 输入数据
feature (str) -- 特征名
target (str) -- 目标变量名

返回:

AUC分析结果

返回类型:

Dict[str, str | float]

参考样例

>>> result = univariate_auc(df, 'score', 'fpd15')
>>> print(f"AUC: {result['AUC值']}, 区分能力: {result['区分能力']}")

hscredit.core.eda.feature_importance_ranking(df, features, target, metrics=['iv', 'auc'], n_jobs=-1, parallel_backend=None, parallel_config=None)[源代码]

综合特征重要性排序.

综合IV和AUC等多个指标评估特征重要性

参数:

df (DataFrame) -- 输入数据
features (List[str]) -- 特征列表
target (str) -- 目标变量名
metrics (List[str]) -- 评估指标列表

返回:

特征重要性DataFrame

返回类型:

DataFrame

参考样例

>>> ranking = feature_importance_ranking(df, feature_list, 'fpd15')
>>> print(ranking[['特征名', 'IV值', 'AUC值', '综合得分', '排名']])

hscredit.core.eda.correlation_matrix(df, features=None, method='pearson')[源代码]

计算相关性矩阵.

参数:

df (DataFrame) -- 输入数据
features (List[str]) -- 指定分析的特征，None则分析全部数值型
method (Literal['pearson', 'spearman', 'kendall']) --
相关计算方法，默认 'pearson'：
- 'pearson'：皮尔逊线性相关系数
- 'spearman'：斯皮尔曼秩相关（单调关系，抗非线性/异常值）
- 'kendall'：肯德尔 τ 秩相关（小样本/有序类别更稳健）

返回:

相关性矩阵DataFrame

返回类型:

DataFrame

参考样例

>>> corr = correlation_matrix(df, ['age', 'income', 'score'])
>>> print(corr)

hscredit.core.eda.high_correlation_pairs(df, features=None, threshold=0.8, method='pearson')[源代码]

高相关性特征对检测.

参数:

df (DataFrame) -- 输入数据
features (List[str]) -- 指定分析的特征
threshold (float) -- 高相关阈值
method (Literal['pearson', 'spearman', 'kendall']) --
相关计算方法，默认 'pearson'：
- 'pearson'：皮尔逊线性相关系数
- 'spearman'：斯皮尔曼秩相关（单调关系，抗非线性/异常值）
- 'kendall'：肯德尔 τ 秩相关（小样本/有序类别更稳健）

返回:

高相关特征对DataFrame，列为['特征1', '特征2', '相关系数', '绝对相关系数', '相关评级']；若没有特征对达到threshold，则返回仅含'信息'列的提示性DataFrame

返回类型:

DataFrame

参考样例

>>> pairs = high_correlation_pairs(df, threshold=0.8)
>>> if '特征1' in pairs.columns:
...     print(pairs[['特征1', '特征2', '相关系数', '相关评级']])
... else:
...     print(pairs['信息'].iloc[0])  # 未发现高相关特征对时的提示信息

hscredit.core.eda.correlation_filter(df, features, target, threshold=0.8, method='pearson')[源代码]

相关性筛选，剔除高相关特征.

策略：保留与目标变量相关性高的特征

参数:

df (DataFrame) -- 输入数据
features (List[str]) -- 特征列表
target (str) -- 目标变量
threshold (float) -- 高相关阈值
method (Literal['pearson', 'spearman', 'kendall']) --
相关计算方法，默认 'pearson'：
- 'pearson'：皮尔逊线性相关系数
- 'spearman'：斯皮尔曼秩相关（单调关系，抗非线性/异常值）
- 'kendall'：肯德尔 τ 秩相关（小样本/有序类别更稳健）

返回:

筛选后的特征列表

返回类型:

List[str]

参考样例

>>> selected = correlation_filter(df, feature_list, 'fpd15', threshold=0.8)
>>> print(f"从{len(feature_list)}个特征中筛选出{len(selected)}个")

hscredit.core.eda.vif_analysis(df, features=None, threshold=10.0)[源代码]

VIF多重共线性分析.

参数:

df (DataFrame) -- 输入数据
features (List[str]) -- 指定分析的特征，None则分析全部数值型
threshold (float) -- VIF阈值

返回:

VIF分析DataFrame

返回类型:

DataFrame

参考样例

>>> vif_df = vif_analysis(df, threshold=10)
>>> print(vif_df[['特征名', 'VIF值', '共线性评级']])

hscredit.core.eda.psi_analysis(base_df, current_df, feature, n_bins=10)[源代码]

单变量PSI稳定性分析.

复用 hscredit.core.metrics.psi_table

参数:

base_df (DataFrame) -- 基准数据集
current_df (DataFrame) -- 当前数据集
feature (str) -- 特征名
n_bins (int) -- 分箱数

返回:

PSI分析结果字典

返回类型:

Dict[str, str | float | DataFrame]

参考样例

>>> result = psi_analysis(train_df, test_df, 'age')
>>> print(f"PSI: {result['PSI值']}, 稳定性: {result['稳定性']}")

hscredit.core.eda.batch_psi_analysis(df, features, date_col, base_period, compare_periods, n_bins=10, n_jobs=-1, parallel_backend=None, parallel_config=None)[源代码]

批量PSI时间稳定性分析.

参数:

df (DataFrame) -- 输入数据
features (List[str]) -- 特征列表
date_col (str) -- 日期列名
base_period (str) -- 基准期（如'2023-01'）
compare_periods (List[str]) -- 对比期列表
n_bins (int) -- 分箱数

返回:

批量PSI结果DataFrame

返回类型:

DataFrame

参考样例

>>> psi_result = batch_psi_analysis(df, ['age', 'income'], 'apply_month',
...                                 '2023-01', ['2023-02', '2023-03'])
>>> print(psi_result[['特征名', '对比期', 'PSI值', '稳定性']])

hscredit.core.eda.csi_analysis(df, feature, target, date_col, base_period, compare_period)[源代码]

CSI特征稳定性分析.

复用 hscredit.core.metrics.csi

参数:

df (DataFrame) -- 输入数据
feature (str) -- 特征名
target (str) -- 目标变量名
date_col (str) -- 日期列名
base_period (str) -- 基准期
compare_period (str) -- 对比期

返回:

CSI分析结果

返回类型:

Dict[str, str | float]

参考样例

>>> result = csi_analysis(df, 'score', 'fpd15', 'apply_month', '2023-01', '2023-02')
>>> print(f"CSI: {result['CSI值']}")

hscredit.core.eda.time_psi_tracking(df, features, date_col, freq='M', n_bins=10, n_jobs=-1, parallel_backend=None, parallel_config=None)[源代码]

PSI时序追踪分析.

计算每个特征在不同时间段的PSI值变化趋势

参数:

df (DataFrame) -- 输入数据
features (List[str]) -- 特征列表
date_col (str) -- 日期列名
freq (str) -- 时间聚合频率，'D' 日 / 'W' 周 / 'M' 月 / 'Q' 季度，默认 'M'
n_bins (int) -- 分箱数

返回:

PSI时序追踪DataFrame

返回类型:

DataFrame

参考样例

>>> tracking = time_psi_tracking(df, ['age', 'income'], 'apply_date')
>>> print(tracking.pivot(index='时间周期', columns='特征名', values='PSI值'))

hscredit.core.eda.stability_report(df, features, date_col, target=None, psi_threshold=0.1, n_jobs=-1, parallel_backend=None, parallel_config=None)[源代码]

综合稳定性报告.

包含PSI分析和时间稳定性评估

参数:

df (DataFrame) -- 输入数据
features (List[str]) -- 特征列表
date_col (str) -- 日期列名
target (str) -- 目标变量名（可选）
psi_threshold (float) -- PSI阈值

返回:

综合稳定性报告DataFrame

返回类型:

DataFrame

参考样例

>>> report = stability_report(df, feature_list, 'apply_date')
>>> print(report[['特征名', '平均PSI', '最大PSI', '不稳定期数']])

hscredit.core.eda.psi_cross_analysis(df, features, date_col=None, group_col=None, freq='M', n_bins=10, return_matrix=True, n_jobs=-1, parallel_backend=None, parallel_config=None)[源代码]

PSI交叉分析 - 计算两两组之间的PSI矩阵.

支持两种方式分组： 1. 自动分组：指定日期列(date_col)和频率(freq)，按时间自动分组 2. 手工分组：指定分组列(group_col)，使用已有分组

计算每两组之间的PSI值，返回PSI矩阵或长格式DataFrame.

参数:

df (DataFrame) -- 输入数据
features (List[str]) -- 特征列表
date_col (str | None) -- 日期列名（自动分组模式）
group_col (str | None) -- 分组列名（手工分组模式）
freq (str) -- 时间频率，'D'日/'W'周/'M'月/'Q'季度，默认'M'
n_bins (int) -- PSI计算分箱数，默认10
return_matrix (bool) -- 是否返回矩阵格式，True返回方阵矩阵，False返回长格式

返回:

return_matrix=True: 返回 {特征名: PSI矩阵DataFrame} 字典
return_matrix=False: 返回长格式DataFrame [特征名, 组1, 组2, PSI值, 稳定性]

返回类型:

DataFrame | Dict[str, DataFrame]

参考样例

>>> # 自动按月份分组
>>> result = psi_cross_analysis(df, ['age', 'income'],
...                             date_col='apply_date', freq='M')
>>> print(result['age'])  # 查看age特征的PSI矩阵

>>> # 手工分组
>>> result = psi_cross_analysis(df, ['score'], group_col='channel')

>>> # 返回长格式
>>> result = psi_cross_analysis(df, ['age'], date_col='apply_date',
...                             freq='M', return_matrix=False)

hscredit.core.eda.feature_drift_report(df_base, df_target, features=None, method='psi', psi_bins=10, n_jobs=-1, parallel_backend=None, parallel_config=None)[源代码]

特征偏移综合报告.

对一批特征计算基准集与目标集之间的偏移指标，返回含 PSI / 均值变化 / 缺失率变化 / 偏移等级的汇总表，可用于上线前的数据质量检查和模型再训练决策。

参数:

df_base (DataFrame) -- 基准数据集（如训练集）
df_target (DataFrame) -- 目标数据集（如生产数据）
features -- 特征列表，None 时取两个数据集的公共数值列
method (str) -- 偏移度量方法，目前仅支持 'psi'
psi_bins (int) -- PSI 计算分箱数，默认 10

返回:

特征偏移报告 DataFrame，含特征名/PSI/均值变化/缺失率变化/偏移等级

返回类型:

DataFrame

参考样例

>>> report = feature_drift_report(train_df, prod_df)
>>> drifted = report[report['偏移等级'] == '显著偏移']
>>> print(drifted[['特征名', 'PSI', '偏移等级']])

hscredit.core.eda.score_drift_report(score_base, score_target, y_base=None, y_target=None, n_bins=10, n_jobs=-1, parallel_backend=None, parallel_config=None)[源代码]

评分分布偏移报告.

比较基准评分与目标评分分布，输出 PSI、均值/中位数/标准差变化，以及可选的 KS/AUC 变化，用于模型监控场景的评分稳定性预警。

参数:

score_base (Series) -- 基准评分 Series
score_target (Series) -- 目标评分 Series
y_base -- 基准真实标签（0/1），可选，提供时计算模型性能变化
y_target -- 目标真实标签（0/1），可选
n_bins (int) -- PSI 分箱数，默认 10

返回:

偏移报告字典，含 PSI / 分布统计 / 模型性能变化

返回类型:

dict

参考样例

>>> report = score_drift_report(train_score, prod_score, y_base=train_y, y_target=prod_y)
>>> print(report['PSI'], report['偏移等级'])
>>> print(report['分布统计'])

hscredit.core.eda.model_drift_report(model, X_base, X_target, y_base=None, y_target=None, features=None, score_method='auto', psi_bins=10, predict_kwargs=None, n_jobs=-1, parallel_backend=None, parallel_config=None)[源代码]

模型漂移监控报告.

从已训练模型生成基准集/目标集评分，统一输出评分漂移、特征漂移和摘要信息。

参数:

model -- 已训练模型，需提供 predict_score 或 predict_proba
X_base (DataFrame) -- 基准特征数据，如训练集或上线基准窗口
X_target (DataFrame) -- 目标特征数据，如生产监控窗口
y_base -- 基准真实标签，可选
y_target -- 目标真实标签，可选
features (List[str] | None) -- 参与特征漂移监控的字段，默认取两个数据集公共数值列
score_method (str) -- 评分口径，'auto' / 'score' / 'proba'
psi_bins (int) -- PSI 分箱数，默认 10
predict_kwargs (dict | None) -- 透传给模型预测方法的参数

返回:

字典，包含 评分漂移 / 特征漂移 / 漂移摘要

返回类型:

Dict[str, DataFrame | dict]

参考样例

>>> report = model_drift_report(model, train_x, oot_x, y_base=train_y, y_target=oot_y)
>>> print(report['漂移摘要'])

hscredit.core.eda.population_profile(df, features, segment_col=None, date_col=None, target=None, freq='M', percentiles=[0.25, 0.5, 0.75], n_jobs=-1, parallel_backend=None, parallel_config=None)[源代码]

客群画像分析.

计算各特征的均值、分位数、缺失率，以及坏率（若提供标签），支持按客群维度（segment_col）或时间（date_col）分组对比。

参数:

df (DataFrame) -- 输入数据
features (List[str]) -- 需要分析的特征列表
segment_col (str | None) -- 客群分组列（如渠道、产品线），为 None 时不分组
date_col (str | None) -- 时间列，为 None 时不按时间分组；与 segment_col 互斥，优先 segment_col
target (str | None) -- 目标变量列名（0/1），提供时输出各组坏率
freq (str) -- 时间聚合粒度，'M'=月，'Q'=季度，'Y'=年，仅 date_col 非 None 时有效
percentiles (List[float]) -- 分位数列表，默认 [0.25, 0.5, 0.75]

返回:

客群画像 DataFrame

返回类型:

DataFrame

参考样例

>>> profile = population_profile(df, features=['age', 'income'], target='fpd15')
>>> profile_by_seg = population_profile(df, features=['age'], segment_col='channel', target='fpd15')

hscredit.core.eda.population_shift_analysis(df_base, df_target, features, target=None, psi_n_bins=10, psi_threshold_warn=0.1, psi_threshold_alert=0.25, n_jobs=-1, parallel_backend=None, parallel_config=None)[源代码]

客群偏移分析.

计算基准数据集与目标数据集之间各特征的 PSI、均值变化、坏率变化，输出偏移摘要表，标注偏移等级和建议。

参数:

df_base (DataFrame) -- 基准数据集（如训练集/历史月份）
df_target (DataFrame) -- 目标数据集（如生产数据/近期月份）
features (List[str]) -- 需要分析的特征列表
target (str | None) -- 目标变量列名（0/1），提供时输出坏率变化
psi_n_bins (int) -- PSI 分箱数，默认 10
psi_threshold_warn (float) -- PSI 警告阈值，默认 0.1（黄色）
psi_threshold_alert (float) -- PSI 告警阈值，默认 0.25（红色）

返回:

偏移摘要 DataFrame，含特征名/PSI/均值变化/偏移等级/建议

返回类型:

DataFrame

参考样例

>>> result = population_shift_analysis(train_df, prod_df, features=['age', 'income'])
>>> print(result[['特征名', 'PSI', '偏移等级', '建议']])

hscredit.core.eda.population_monitoring_report(df_base, df_compare_list, compare_labels, features, target=None, psi_n_bins=10, top_drift_n=10, output_path='population_monitor.xlsx', n_jobs=-1, parallel_backend=None, parallel_config=None)[源代码]

多期客群监控 Excel 报告.

生成包含以下 Sheet 的 Excel 报告： - 总览：各期相对基准的 PSI 汇总热力表，含稳定性等级 - 趋势：各期样本量和坏率趋势（若提供 target） - 偏移Top{top_drift_n}：PSI 均值最高的特征详细对比分布

参数:

df_base (DataFrame) -- 基准数据集
df_compare_list (List[DataFrame]) -- 各期对比数据集列表
compare_labels (List[str]) -- 各期标签（与 df_compare_list 一一对应）
features (List[str]) -- 监控特征列表
target (str | None) -- 目标变量列名
psi_n_bins (int) -- PSI 计算分箱数
top_drift_n (int) -- 输出偏移最大的 N 个特征
output_path (str) -- 输出 Excel 路径

返回:

输出文件路径

返回类型:

str

参考样例

>>> path = population_monitoring_report(
...     df_base=train_df,
...     df_compare_list=[prod_2024q1, prod_2024q2],
...     compare_labels=['2024Q1', '2024Q2'],
...     features=['age', 'income', 'credit_score'],
...     target='fpd15',
...     output_path='monitor.xlsx',
... )

hscredit.core.eda.segment_drift_analysis(df, date_col, segment_col, features, target=None, base_period=None, freq='M', psi_n_bins=10, n_jobs=-1, parallel_backend=None, parallel_config=None)[源代码]

分客群、分时间的特征偏移三维矩阵.

计算每个 (客群, 时间) 组合相对于基准期（或第一期）的特征 PSI，输出长格式三维结果表，列为 [特征名, 客群, 时间, PSI, 偏移等级]。

参数:

df (DataFrame) -- 输入数据（须含 date_col 和 segment_col）
date_col (str) -- 日期列名
segment_col (str) -- 客群分组列名
features (List[str]) -- 分析特征列表
target (str | None) -- 目标变量（可选，用于输出各组坏率）
base_period (str | None) -- 基准期字符串（如 '2024-01'），None 时取最早一期
freq (str) -- 时间聚合频率，'M'=月，'Q'=季度，'Y'=年
psi_n_bins (int) -- PSI 计算分箱数

返回:

长格式 DataFrame，含特征名/客群/时间/PSI/偏移等级

返回类型:

DataFrame

参考样例

>>> result = segment_drift_analysis(df, date_col='apply_month',
...     segment_col='channel', features=['age', 'income'], base_period='2024-01')
>>> print(result.pivot_table(index=['客群', '时间'], columns='特征名', values='PSI'))

hscredit.core.eda.feature_cross_segment_effectiveness(df, features, target, segment_col, metric='iv', n_bins=10, min_segment_size=50, n_jobs=-1, parallel_backend=None, parallel_config=None)[源代码]

特征在不同客群下的有效性矩阵.

计算每个特征在每个客群下的 IV / KS / AUC，输出宽格式矩阵（行=特征，列=客群，格=指标值），用于快速发现特征在哪些客群有效、哪些失效。

参数:

df (DataFrame) -- 输入数据
features (List[str]) -- 特征列表
target (str) -- 目标变量列名（0/1）
segment_col (str) -- 客群分组列名
metric (str) -- 有效性指标，'iv' / 'ks' / 'auc'
n_bins (int) -- 分箱数（iv/ks 计算使用）
min_segment_size (int) -- 最小客群样本量，低于此值跳过

返回:

宽格式有效性矩阵 DataFrame

返回类型:

DataFrame

参考样例

>>> matrix = feature_cross_segment_effectiveness(
...     df, features=['age', 'income'], target='fpd15',
...     segment_col='channel', metric='iv')
>>> print(matrix)
#        channel_A  channel_B  全量
# age     0.15       0.08      0.12
# income  0.22       0.19      0.20

hscredit.core.eda.approval_badrate_tradeoff(y_true, score, n_points=100, score_low_risk='high')[源代码]

通过率 vs 坏率权衡分析.

生成「通过率 - 坏率」权衡曲线数据，每行对应一个评分阈值，输出该阈值下的通过率、拒绝率、通过人群坏率、拒绝人群坏率以及 KS 值，用于向业务方解释策略调整影响。

参数:

y_true (Series) -- 真实标签序列（0/1）
score (Series) -- 模型评分序列（越高越优质）
n_points (int) -- 阈值点数量，默认 100
score_low_risk (str) -- 'high' 表示高分为低风险（通过），'low' 表示低分为低风险

返回:

权衡表 DataFrame

返回类型:

DataFrame

参考样例

>>> tradeoff = approval_badrate_tradeoff(df['fpd15'], df['score'])
>>> # 找坏率≤3% 时通过率最高的阈值
>>> tradeoff[tradeoff['通过人群坏率(%)'] <= 3].head(1)

hscredit.core.eda.score_strategy_simulation(df, score_col, target, thresholds, amount_col=None, score_low_risk='high')[源代码]

评分阈值策略仿真.

对一组指定的评分阈值，分别计算每档策略对应的通过量（件/金额）、坏率、坏账量，便于与当前策略对比，做"如果把阈值调整到X会怎样"的仿真。

参数:

df (DataFrame) -- 输入 DataFrame
score_col (str) -- 评分列名
target (str) -- 目标变量列名（0/1）
thresholds (List[float]) -- 评分阈值列表（通过/拒绝切割点）
amount_col (str | None) -- 金额列名（可选），提供时计算通过金额和坏账金额
score_low_risk (str) -- 'high' 表示高分为低风险，'low' 表示低分为低风险

返回:

各阈值下的策略仿真结果 DataFrame

返回类型:

DataFrame

参考样例

>>> result = score_strategy_simulation(df, score_col='score', target='fpd15',
...     thresholds=[500, 520, 540, 560], amount_col='loan_amount')

hscredit.core.eda.vintage_performance_summary(df, vintage_col, mob_col, target_col, mob_points=None, amount_col=None)[源代码]

Vintage 账龄绩效汇总表.

以 vintage（放款批次，如放款月份）为行，MOB（账龄）为列，计算不同账龄下的累计坏率，支持金额加权。可传入多个 MOB 观测点（如 [3,6,9,12]）。

参数:

df (DataFrame) -- 输入 DataFrame
vintage_col (str) -- Vintage 列名（如放款年月 '2024-01'）
mob_col (str) -- 当前账龄（月）列名
target_col (str) -- 坏标签列名（0/1）
mob_points (List[int] | None) -- 关注的 MOB 观测点列表，None 时自动取所有整数 MOB
amount_col (str | None) -- 金额列名（可选），提供时输出金额加权坏率

返回:

Vintage 绩效汇总宽表，行=vintage，列=MOB_X_坏率

返回类型:

DataFrame

参考样例

>>> summary = vintage_performance_summary(df, vintage_col='loan_month',
...     mob_col='mob', target_col='fpd15', mob_points=[3,6,9,12])

hscredit.core.eda.roll_rate_matrix(df, dpd_t0, dpd_t1, bins=None, labels=None, mob_t0=None, mob_t1=None, date_t0=None, date_t1=None, amount_col=None)[源代码]

DPD 滚动率矩阵.

分析借款人在观察点（t0）到表现点（t1）之间逾期状态的迁移规律，同时输出订单与金额（可选）两个口径的计数矩阵、比例矩阵及整体汇总，量化各 DPD 状态段的资产质量改善（变好）、保持与恶化（变坏）程度，辅助信贷风险的动态监控与预警。

样本选取说明：应选取观察点之前已放款、且在观察点之后仍有未结清余额（贷款表现）的样本。调用方需在传入 DataFrame 前完成此过滤：剔除观察点前已提前结清的贷款，以及观察点之后才新发放的贷款，确保每笔样本在观察期（t0）和表现期（t1）均有有效 DPD 记录，避免已结清或未成熟贷款混入造成分布失真。

参数:

df (DataFrame) -- 输入 DataFrame（须已完成上述样本过滤）
dpd_t0 (str) -- 观察期 DPD 列名（t0 时刻逾期天数）
dpd_t1 (str) -- 表现期 DPD 列名（t1 时刻逾期天数）
bins (List[int] | None) -- DPD 分档断点，默认 [0, 1, 7, 15, 30, 60, 90, 120, inf]
labels (List[str] | None) -- 各档标签，默认 ['D0','D1-7','D8-15','D16-30','D31-60','D61-90','D91-120','D120+']
mob_t0 (int | None) -- 观察点账龄（MOB），用于表头标注，如 12 表示 "MOB12"
mob_t1 (int | None) -- 表现点账龄（MOB），用于表头标注，如 18 表示 "MOB18"
date_t0 (str | None) -- 观察点日期字符串（可选），如 '2023-06'，用于表头描述
date_t1 (str | None) -- 表现点日期字符串（可选），如 '2023-12'，用于表头描述
amount_col (str | None) -- 贷款金额列名（可选），提供时额外输出金额口径矩阵与比例矩阵

返回:

包含以下键的字典：

'元信息': 观察点/表现点描述、总订单数、订单口径变好/保持/变坏笔数及占比；若提供 amount_col 则同时包含金额口径汇总
'计数矩阵': 多层列索引的迁移计数宽表，含变好/保持/变坏/合计汇总列
'订单比例矩阵': 基于订单数行归一化的迁移概率（原始小数），含变好/保持/变坏汇总列
'金额矩阵': 当 amount_col 提供时，金额口径的迁移宽表，含汇总列
'金额比例矩阵': 当 amount_col 提供时，基于金额行归一化的迁移比例（原始小数）

返回类型:

Dict[str, DataFrame]

参考样例

>>> result = roll_rate_matrix(
...     df, dpd_t0='dpd_mob12', dpd_t1='dpd_mob18',
...     mob_t0=12, mob_t1=18, amount_col='loan_amount'
... )
>>> display(result['元信息'])
>>> display(result['计数矩阵'])
>>> display(result['订单比例矩阵'])
>>> display(result['金额矩阵'])
>>> display(result['金额比例矩阵'])

hscredit.core.eda.label_leakage_check(df, features, target, threshold_iv=0.5, threshold_auc=0.9, n_bins=10)[源代码]

标签泄露检测.

对每个特征计算 IV 和 AUC，超过阈值则标记为疑似泄露，可快速识别训练数据中存在未来信息的特征。

参数:

df (DataFrame) -- 输入 DataFrame
features (List[str]) -- 待检测特征列表
target (str) -- 目标变量列名（0/1）
threshold_iv (float) -- IV 泄露阈值，超过则告警，默认 0.5
threshold_auc (float) -- AUC 泄露阈值，超过则告警，默认 0.9
n_bins (int) -- IV 计算分箱数

返回:

标签泄露检测结果 DataFrame

返回类型:

DataFrame

参考样例

>>> result = label_leakage_check(df, features=df.columns[:-1].tolist(), target='fpd15')
>>> suspected = result[result['疑似泄露'] == True]
>>> print(suspected[['特征名', 'IV', 'AUC', '泄露原因']])

hscredit.core.eda.multi_label_correlation(df, labels, method='pearson', threshold=0.7)[源代码]

多标签相关性矩阵.

计算多个标签之间的相关性（皮尔逊或斯皮尔曼），并标注高相关标签对，用于判断多个目标变量是否相互依赖，以及选择最优目标变量。

参数:

df (DataFrame) -- 输入 DataFrame
labels (List[str]) -- 标签列名列表（均须为 0/1）
method (str) -- 相关系数方法，'pearson' 或 'spearman'
threshold (float) -- 高相关告警阈值（绝对值），默认 0.7

返回:

相关性矩阵 DataFrame，附带高相关标签对描述

返回类型:

DataFrame

参考样例

>>> corr_df = multi_label_correlation(df, labels=['fpd7', 'fpd15', 'fpd30'])
>>> print(corr_df)

hscredit.core.eda.vintage_analysis(df, vintage_col, mob_col, target_col, max_mob=12)[源代码]

Vintage账龄分析.

追踪不同放款批次（Vintage）随账龄（MOB）的风险表现变化

参数:

df (DataFrame) -- 输入数据
vintage_col (str) -- Vintage批次列（如放款月份）
mob_col (str) -- 账龄列（Month on Book）
target_col (str) -- 目标变量列（如是否逾期）
max_mob (int) -- 最大账龄

返回:

Vintage分析DataFrame

返回类型:

DataFrame

参考样例

>>> vintage = vintage_analysis(df, 'issue_month', 'mob', 'ever_dpd30', max_mob=12)
>>> print(vintage.pivot(index='MOB', columns='Vintage批次', values='累积坏账率(%)'))

hscredit.core.eda.vintage_summary(df, vintage_col, mob_col, target_col, max_mob=12)[源代码]

Vintage汇总统计.

参数:

df (DataFrame) -- 输入数据
vintage_col (str) -- Vintage批次列
mob_col (str) -- 账龄列
target_col (str) -- 目标变量列
max_mob (int) -- 最大账龄

返回:

Vintage汇总DataFrame

返回类型:

DataFrame

参考样例

>>> summary = vintage_summary(df, 'issue_month', 'mob', 'ever_dpd30')
>>> print(summary[['Vintage批次', '总开户数', f'MOB{max_mob}坏账率']])

hscredit.core.eda.roll_rate_analysis(df, overdue_cols, labels=None)[源代码]

滚动率分析.

分析不同逾期状态之间的转化情况

参数:

df (DataFrame) -- 输入数据
overdue_cols (List[str]) -- 各期逾期状态列（如['mob1_status', 'mob2_status', 'mob3_status']）
labels (List[str]) -- 状态标签（如['M0', 'M1', 'M2+']）

返回:

滚动率分析DataFrame

返回类型:

DataFrame

参考样例

>>> roll = roll_rate_analysis(df, ['mob1', 'mob2', 'mob3'], ['M0', 'M1', 'M2+'])
>>> print(roll)

hscredit.core.eda.eda_summary(df, target=None, features=None, date_col=None, n_jobs=-1, parallel_backend=None, parallel_config=None)[源代码]

EDA分析摘要.

快速生成数据集的关键分析结果

param df:

输入数据

param target:

目标变量名（可选）

param features:

特征列表（可选）

param date_col:

日期列名（可选）

return:

EDA摘要字典

参考样例
>>> summary = eda_summary(df, target='fpd15', date_col='apply_date')
>>> for key, value in summary.items():
...     print(f"

=== {key} ==="): ... print(value)

参数:

df (DataFrame)
target (str)
features (List[str])
date_col (str)

返回类型:

Dict[str, DataFrame]

hscredit.core.eda.generate_report(df, target=None, features=None, date_col=None, config=None, n_jobs=-1, parallel_backend=None, parallel_config=None)[源代码]

生成完整EDA报告.

参数:

df (DataFrame) -- 输入数据
target (str) -- 目标变量名
features (List[str]) -- 特征列表
date_col (str) -- 日期列名
config (Dict) -- 配置参数

返回:

完整报告字典

返回类型:

Dict[str, DataFrame]

参考样例

>>> report = generate_report(df, target='fpd15', date_col='apply_date',
...                          config={'iv_threshold': 0.02})
>>> export_report_to_excel(report, 'eda_report.xlsx')

hscredit.core.eda.export_report_to_excel(report, filepath, sheet_name_mapping=None, theme_color='2639E9', auto_width=True)[源代码]

导出报告到Excel.

使用 hscredit 的 ExcelWriter 生成专业格式的 Excel 报告。

参数:

report (Dict[str, DataFrame]) -- 报告字典
filepath (str) -- 导出文件路径
sheet_name_mapping (Dict[str, str]) -- 工作表名称映射
theme_color (str) -- 主题颜色，默认 '2639E9'（蓝色）
auto_width (bool) -- 是否自动调整列宽，默认 True

返回类型:

None

参考样例

>>> export_report_to_excel(report, 'eda_report.xlsx')
>>> export_report_to_excel(report, 'eda_report.xlsx', theme_color='00A651')

数据探索 hscredit.core.eda

数据探索 `hscredit.core.eda`