编码器 hscredit.core.encoders

9 种特征编码器（WOE / Target / Count / OneHot / Ordinal / Quantile / CatBoost / Cardinality / GBM），统一继承 BaseEncoder，兼容 sklearn Pipeline。

特征编码器模块.

提供各类特征编码功能，包括： - WOEEncoder: 证据权重编码 - TargetEncoder: 目标编码 - CountEncoder: 计数编码 - OneHotEncoder: 独热编码 - OrdinalEncoder: 序数编码 - QuantileEncoder: 分位数编码 - CatBoostEncoder: CatBoost编码 - GBMEncoder: 梯度提升树编码器（支持XGBoost/LightGBM/CatBoost+LR） - CardinalityEncoder: 高基数降维编码器

所有编码器均遵循sklearn Transformer接口规范。

class hscredit.core.encoders.BaseEncoder(cols=None, drop_invariant=False, return_df=True, handle_unknown='value', handle_missing='value', target=None, n_jobs=-1, parallel_backend=None, parallel_config=None)[源代码]

基类：ParallelizableMixin, ArtifactSerializableMixin, BaseEstimator, TransformerMixin, ABC

编码器基类.

所有编码器的抽象基类，提供统一的接口和通用功能。 遵循sklearn Transformer接口规范，同时支持scorecardpipeline风格。

参数

参数:

  • cols (List[str] | None) -- 需要编码的列名列表。如果为None，则自动识别所有类别型列

  • drop_invariant (bool) -- 是否删除方差为0的列，默认为False

  • return_df (bool) -- 是否返回DataFrame，默认为True

  • handle_unknown (str) -- 处理未知类别的方式，默认为'value' - 'value': 使用默认值（通常是0或全局均值） - 'error': 抛出错误 - 'return_nan': 返回NaN

  • handle_missing (str) -- 处理缺失值的方式，默认为'value' - 'value': 使用默认值（通常是0或全局均值） - 'error': 抛出错误 - 'return_nan': 返回NaN

  • target (str | None) -- scorecardpipeline风格的目标列名。如果提供，fit时从X中提取该列作为y

  • n_jobs (int | float | None) -- 并行工作数，默认为-1；None沿用旧串行行为

  • parallel_backend (str | None) -- joblib并行后端，默认为None

  • parallel_config (Mapping[str, Any] | None) -- joblib扩展配置，默认为None

属性

  • mapping_: 编码映射字典，格式为 {col: {category: encoded_value}}

  • cols_: 实际进行编码的列名列表（经过自动识别或过滤后）

  • _dropped_cols: 被删除的方差为0的列

参考样例

所有子类（WOE/Target/Count/OneHot/Ordinal/Quantile/CatBoost/GBM/Cardinality） 共享下述两种调用风格:

>>> from hscredit.core.encoders import WOEEncoder
>>> # sklearn 风格：X、y 分开传
>>> enc = WOEEncoder(cols=['city'])
>>> X_enc = enc.fit_transform(X, y)
>>> # scorecardpipeline 风格：目标列在 df 中，初始化指定 target
>>> enc = WOEEncoder(target='target', cols=['city'])
>>> X_enc = enc.fit_transform(df)
>>> enc.get_mapping('city')        # 查看某列的类别→编码映射
>>> enc.export_mapping()           # 导出可序列化映射

引用

接口约定（cols / drop_invariant / handle_unknown / handle_missing / return_df）对齐 category_encoders 库： https://contrib.scikit-learn.org/category_encoders/

artifact_kind = '编码器'
export_mapping()[源代码]

导出编码映射（可序列化）。

返回:

可序列化的编码映射字典

返回类型:

Dict[str, Any]

参考样例

>>> encoder.fit(X, y)
>>> mapping = encoder.export_mapping()
>>> import json
>>> with open('encoder_mapping.json', 'w') as f:
...     json.dump(mapping, f)
fit(X, y=None)[源代码]

拟合编码器。

支持两种API风格: 1. sklearn风格: fit(X, y) - X是特征矩阵，y是目标变量 2. scorecardpipeline风格: fit(df) - df是完整数据框，目标列名在初始化时通过target参数传入

优先级: fit时传入的y > 从X中提取target列

参数:

  • X (DataFrame) -- 训练数据，shape (n_samples, n_features) 或包含目标列的完整数据框

  • y (Series | None) -- 目标变量，对于有监督编码器（如WOE、Target）必须提供。 如果为None且初始化时提供了target参数，则从X中提取target列

返回:

拟合后的编码器自身

返回类型:

BaseEncoder

注意

fit方法会进行以下操作: 1. 数据验证和预处理 2. 自动识别类别型列（如果cols为None） 3. 删除方差为0的列（如果drop_invariant=True） 4. 计算编码映射

fit_transform(X, y=None)[源代码]

拟合并转换数据。

支持两种API风格: 1. sklearn风格: fit_transform(X, y) - X是特征矩阵，y是目标变量 2. scorecardpipeline风格: fit_transform(df) - df是完整数据框，目标列名在初始化时通过target参数传入

参数:

  • X (DataFrame) -- 训练数据，shape (n_samples, n_features) 或包含目标列的完整数据框

  • y (Series | None) -- 目标变量，对于某些编码器是必需的。 如果为None且初始化时提供了target参数，则从X中提取target列

返回:

编码后的数据

返回类型:

DataFrame | ndarray

get_mapping(col=None)[源代码]

获取编码映射。

参数:

col (str | None) -- 列名。如果提供，返回该列的映射 {category: encoded_value}； 如果为None，返回所有列的映射 {col: {category: encoded_value}}

返回:

编码映射字典

抛出:
返回类型:

Dict[str, Any]

import_mapping(mapping)[源代码]

导入编码映射。

参数:

mapping (Dict[str, Any]) -- 编码映射字典

参考样例

>>> import json
>>> with open('encoder_mapping.json', 'r') as f:
...     mapping = json.load(f)
>>> encoder.import_mapping(mapping)
inverse_transform(X)[源代码]

逆编码（将编码值还原为原始类别）。

编码器基类的默认实现：多数有监督/有损编码器（WOE/Target/Count/Quantile/CatBoost/GBM） 无法唯一还原原始类别，调用时抛出 NotImplementedError。 支持逆编码的子类（OneHot/Ordinal/Cardinality）会覆盖本方法。

参数:

X (DataFrame) -- 编码后的数据

返回:

逆编码后的数据

抛出:

NotImplementedError -- 当该编码器不支持逆编码时抛出

返回类型:

DataFrame

transform(X, y=None)[源代码]

转换数据。

将原始类别特征值转换为编码后的数值。 这是编码器的核心方法，用于将新数据应用到已训练的编码规则。

参数:

  • X (DataFrame) -- 需要转换的数据，shape (n_samples, n_features) - 支持DataFrame - 列名必须与fit时的特征名一致

  • y (Series | None) -- 目标变量，某些编码器需要，默认为None

返回:

编码后的数据，类型由return_df参数决定

抛出:

ValueError -- 当编码器尚未拟合时抛出

返回类型:

DataFrame | ndarray

注意

transform方法会自动处理: 1. 缺失值: 根据handle_missing参数处理 2. 未知类别: 根据handle_unknown参数处理

class hscredit.core.encoders.WOEEncoder(cols=None, regularization=1.0, woe_clip=5.0, handle_unknown='value', handle_missing='value', drop_invariant=False, return_df=True, target=None, n_jobs=-1, parallel_backend=None, parallel_config=None)[源代码]

基类：BaseEncoder

WOE (证据权重) 编码器.

直接对类别特征计算WOE值，不依赖分箱功能。

WOE计算公式： WOE = ln(P(坏样本|类别) / P(好样本|类别)) = ln(坏样本占比/好样本占比)

参数

参数:

  • cols (List[str] | None) -- 需要编码的列名列表。如果为None，则自动识别所有类别型列

  • regularization (float) -- 正则化参数，防止除零，默认为1.0

  • woe_clip (float | None) -- WOE值截断阈值，默认为5.0 当某个分箱无坏样本或无好样本时，WOE可能变得极大（如±10以上）， 这会导致评分卡中对应分箱的分数异常。 设置此参数可将WOE限制在[-woe_clip, woe_clip]范围内。 设置为None则不进行截断。

  • handle_unknown (str) --

    transform 时遇到 fit 未见过的类别的处理方式，默认为 'value'：

    • 'value'：编码为 0.0（中性 WOE）

    • 'return_nan'：编码为 NaN

    • 'error'：抛出异常

  • handle_missing (str) --

    缺失值（NaN）的处理方式，默认为 'value'：

    • 'value'：编码为 0.0（中性 WOE）

    • 'return_nan'：编码为 NaN

    • 'error'：fit/transform 遇缺失即抛出异常

  • drop_invariant (bool) -- 是否删除方差为0的列，默认为False

  • return_df (bool) -- 是否返回DataFrame，默认为True

  • target (str | None) -- scorecardpipeline 风格的目标列名，提供后 fit 时从 X 中提取该列作为 y

  • n_jobs (int | float | None)

  • parallel_backend (str | None)

  • parallel_config (Dict[str, Any] | None)

属性

  • mapping_: WOE编码映射字典，格式为 {col: {category: woe_value}}

  • iv_: 各特征的IV值，格式为 {col: iv_value}

参考样例

>>> from hscredit.core.encoders import WOEEncoder
>>> encoder = WOEEncoder(cols=['category', 'score'])
>>> X_encoded = encoder.fit_transform(X, y)
>>> print(encoder.iv_)
>>>
>>> # 获取IV摘要
>>> summary = encoder.summary()
>>> print(summary)

导出/加载（与 toad、scorecardpipeline 规则格式互通）:

>>> rules = encoder.export(to_json='woe_rules.json')
>>> WOEEncoder().load('woe_rules.json')

注意

与 BaseBinning 的 metric='woe' 不同，本编码器 直接对原始类别取值计算 WOE、不做数值分箱，适合基数适中的类别特征。regularization 采用加性平滑以避免某类别好/坏样本数为 0 时 WOE 取 ±∞。

引用

WOE（证据权重）与 IV（信息价值）出自信息论，系统应用于信用评分见 Siddiqi, N. (2006). Credit Risk Scorecards. Wiley； 公式与直观解释参考 https://www.listendata.com/2015/03/weight-of-evidence-woe-and-information.html

export(to_json=None)[源代码]

导出WOE编码规则，兼容 toad/scorecardpipeline 格式.

导出格式与 toad.WOETransformer.export() 和 scorecardpipeline.WOETransformer.export() 保持一致。

参数:

to_json (str | None) -- 可选，JSON 文件保存路径。如果提供，将规则保存到该文件

返回:

WOE编码规则字典，格式为 {feature: {value: woe_value, ...}, ...}

返回类型:

Dict[str, Dict]

参考样例

>>> from hscredit.core.encoders import WOEEncoder
>>> encoder = WOEEncoder(cols=['category', 'city'])
>>> encoder.fit(X, y)
>>>
>>> # 导出为字典
>>> rules = encoder.export()
>>>
>>> # 导出并保存到 JSON 文件
>>> rules = encoder.export(to_json='woe_rules.json')

与 toad/scorecardpipeline 的兼容性

导出的规则可以直接被 toad 和 scorecardpipeline 加载:

>>> import toad
>>> transformer = toad.transform.WOETransformer()
>>> transformer.load(rules)
>>>
>>> from scorecardpipeline import WOETransformer
>>> transformer = WOETransformer()
>>> transformer.load(rules)
get_iv()[源代码]

获取各特征的IV值。

返回:

特征名到IV值的映射字典

返回类型:

Dict[str, float]

get_mapping(col=None)[源代码]

获取WOE编码映射。

参数:

col (str | None) -- 列名。如果提供，返回该列的映射； 如果为None，返回所有列的映射

返回:

WOE映射字典。当 col 指定时返回 {category: woe_value}， col 为 None 时返回 {col: {category: woe_value}}

抛出:
返回类型:

Dict | Dict[str, Dict]

load(from_json, update=False)[源代码]

加载WOE编码规则，兼容 toad/scorecardpipeline 格式.

从字典或 JSON 文件加载WOE编码规则，支持 toad 和 scorecardpipeline 导出的格式。

参数:

  • from_json (str | Dict) -- WOE规则字典或 JSON 文件路径 - 字典: {'category': {'A': 0.5, 'B': -0.3}} - 文件路径: 'woe_rules.json'

  • update (bool) -- 是否更新现有规则（而非替换），默认为 False

返回:

self，支持链式调用

返回类型:

WOEEncoder

参考样例

>>> from hscredit.core.encoders import WOEEncoder
>>> encoder = WOEEncoder()
>>>
>>> # 从字典加载
>>> rules = {'category': {'A': 0.5, 'B': -0.3}}
>>> encoder.load(rules)
>>>
>>> # 从 JSON 文件加载
>>> encoder.load('woe_rules.json')
>>>
>>> # 更新现有规则
>>> encoder.load({'new_feature': {'X': 0.2}}, update=True)

与 toad/scorecardpipeline 的兼容性

可以直接加载 toad 和 scorecardpipeline 导出的规则:

>>> import toad
>>> toad_transformer = toad.transform.WOETransformer()
>>> toad_transformer.fit(df, y)
>>> rules = toad_transformer.export()
>>>
>>> encoder = WOEEncoder()
>>> encoder.load(rules)
summary()[源代码]

获取 WOE 编码摘要表（按 IV 降序）。

对每个已编码特征给出 IV 值及对应的预测能力评级，评级阈值为：

  • IV < 0.02：无预测力

  • 0.02 ≤ IV < 0.1：弱预测力

  • 0.1 ≤ IV < 0.3：中等预测力

  • 0.3 ≤ IV < 0.5：强预测力

  • IV ≥ 0.5：超强预测力（需检查是否标签泄漏）

返回:

含 特征 / IV值 / 预测能力 三列的 DataFrame，按 IV值 降序； 未拟合或无特征时返回空 DataFrame

返回类型:

DataFrame

参考样例

>>> encoder.fit(X, y)
>>> encoder.summary()
class hscredit.core.encoders.TargetEncoder(cols=None, smoothing=1.0, min_samples_leaf=1, noise=None, handle_unknown='value', handle_missing='value', drop_invariant=False, return_df=True, random_state=None, target=None, n_jobs=-1, parallel_backend=None, parallel_config=None)[源代码]

基类：BaseEncoder

目标编码器.

用目标变量的均值对每个类别进行编码： - 对于分类任务：该类别的正样本比例 - 对于回归任务：该类别的目标变量均值

使用平滑技术防止过拟合： encoded = (count * mean + smoothing * global_mean) / (count + smoothing)

参数

参数:

  • cols (List[str] | None) -- 需要编码的列名列表。如果为None，则自动识别所有列（支持类别型和数值型）

  • smoothing (float) -- 平滑参数，值越大收缩到全局均值的程度越大，默认为1.0

  • min_samples_leaf (int) -- 每个类别的最小样本数，少于该值则使用全局均值，默认为1

  • noise (float | None) -- 添加的高斯噪声标准差，用于防止过拟合，默认为None

  • handle_unknown (str) -- 处理未知类别的方式，默认为'value'

  • handle_missing (str) -- 处理缺失值的方式，默认为'value'

  • drop_invariant (bool) -- 是否删除方差为0的列，默认为False

  • return_df (bool) -- 是否返回DataFrame，默认为True

  • random_state (int | None)

  • target (str | None)

  • n_jobs (int | float | None)

  • parallel_backend (str | None)

  • parallel_config (Dict[str, Any] | None)

属性

  • mapping_: 目标编码映射字典，格式为 {col: {category: encoded_value}}

  • global_mean_: 全局目标均值

参考样例

>>> from hscredit.core.encoders import TargetEncoder
>>> encoder = TargetEncoder(cols=['category'])
>>> X_encoded = encoder.fit_transform(X, y)
>>>
>>> # 添加噪声防止过拟合
>>> encoder = TargetEncoder(cols=['category'], noise=0.05)
>>> X_encoded = encoder.fit_transform(X, y)

注意

目标编码直接使用了标签信息，存在目标泄漏/过拟合风险，应配合 smoothing、 min_samples_leaf、noise 等正则手段，并务必在训练集 fit、在验证/测试集 transform；若需更强的防泄漏，改用 :class:`CatBoostEncoder`（有序目标统计）。

引用

Micci-Barreca, D. (2001). A preprocessing scheme for high-cardinality categorical attributes in classification and prediction problems. ACM SIGKDD Explorations, 3(1). https://doi.org/10.1145/507533.507538

class hscredit.core.encoders.CountEncoder(cols=None, normalize=False, min_group_size=None, handle_unknown='value', handle_missing='value', drop_invariant=False, return_df=True, target=None, n_jobs=-1, parallel_backend=None, parallel_config=None)[源代码]

基类：BaseEncoder

计数编码器.

用每个类别的出现次数（或频率）进行编码。 适用于高基数类别特征，能有效捕捉类别的流行度信息。

参数

参数:

  • cols (List[str] | None) -- 需要编码的列名列表。如果为None，则自动识别所有列（支持类别型和数值型）

  • normalize (bool) -- 是否返回频率而不是计数，默认为False

  • min_group_size (int | None) -- 将频次低于此值的类别合并为"其他"，默认为None

  • handle_unknown (str) -- 处理未知类别的方式，默认为'value'

  • handle_missing (str) -- 处理缺失值的方式，默认为'value'

  • drop_invariant (bool) -- 是否删除方差为0的列，默认为False

  • return_df (bool) -- 是否返回DataFrame，默认为True

  • target (str | None)

  • n_jobs (int | float | None)

  • parallel_backend (str | None)

  • parallel_config (Dict[str, Any] | None)

属性

  • mapping_: 计数编码映射字典，格式为 {col: {category: count}}

  • total_count_: 总样本数

参考样例

>>> from hscredit.core.encoders import CountEncoder
>>> encoder = CountEncoder(cols=['category'])
>>> X_encoded = encoder.fit_transform(X)
>>>
>>> # 返回频率
>>> encoder = CountEncoder(cols=['category'], normalize=True)
>>> X_encoded = encoder.fit_transform(X)
>>>
>>> # 合并低频类别
>>> encoder = CountEncoder(cols=['category'], min_group_size=10)
>>> X_encoded = encoder.fit_transform(X)

注意

计数/频率编码为无监督方法，不使用标签 y，仅以类别出现频次反映其流行度，对高基数 类别尤其紧凑；但不同类别若频次相同会被编码为同一值（信息混淆），必要时与其他编码并用。

引用

频率/计数编码（frequency / count encoding）是类别特征工程的常用基线方法，参见 category_encoders CountEncoder： https://contrib.scikit-learn.org/category_encoders/count.html

class hscredit.core.encoders.OneHotEncoder(cols=None, drop=None, handle_unknown='ignore', handle_missing='value', use_cat_names=True, return_df=True, target=None, n_jobs=-1, parallel_backend=None, parallel_config=None)[源代码]

基类：BaseEncoder

独热编码器.

将每个类别转换为一个二进制列，适用于类别数量不多的特征。 支持数值型和类别型数据。

参数

参数:

  • cols (List[str] | None) -- 需要编码的列名列表。如果为None，则编码所有列

  • drop (str | None) -- 是否删除某一列以避免多重共线性，默认为None - None: 保留所有列 - 'first': 删除第一列 - 'if_binary': 二值特征时删除一列

  • handle_unknown (str) -- 处理未知类别的方式，默认为'ignore' - 'error': 抛出错误 - 'ignore': 忽略（所有编码列为0）

  • handle_missing (str) -- 处理缺失值的方式，默认为'value' - 'value': 单独编码为'missing'列 - 'error': 抛出错误

  • use_cat_names (bool) -- 是否使用类别值作为列名后缀，默认为True

  • return_df (bool) -- 是否返回DataFrame，默认为True

  • target (str | None)

  • n_jobs (int | float | None)

  • parallel_backend (str | None)

  • parallel_config (Dict[str, Any] | None)

属性

  • categories_: 各列的类别列表，格式为 {col: [category1, category2, ...]}

  • feature_names_: 编码后的特征名列表

参考样例

>>> from hscredit.core.encoders import OneHotEncoder
>>> encoder = OneHotEncoder(cols=['color'])
>>> X_encoded = encoder.fit_transform(X)
>>>
>>> # 删除第一列避免多重共线性
>>> encoder = OneHotEncoder(cols=['color'], drop='first')
>>> X_encoded = encoder.fit_transform(X)

注意

独热编码为无监督方法，列数随类别基数线性增长，仅适合低基数特征；用于线性/逻辑回归时 建议 drop='first' 以消除虚拟变量陷阱（多重共线性），用于树模型可保留全部列。

引用

虚拟变量（dummy variables）/ one-hot 编码是统计建模标准做法，参见 sklearn OneHotEncoder： https://scikit-learn.org/stable/modules/generated/sklearn.preprocessing.OneHotEncoder.html

get_feature_names()[源代码]

获取独热编码生成的特征名（不含未编码的透传列）。

返回:

独热编码后的特征名列表

返回类型:

List[str]

get_feature_names_out(input_features=None)[源代码]

获取转换后的全部输出列名（sklearn 兼容接口）。

输出顺序与 transform 一致：未编码透传列在前，独热编码列在后。

参数:

input_features -- 兼容 sklearn 接口的占位参数，未使用

返回:

输出列名数组

返回类型:

ndarray

inverse_transform(X)[源代码]

逆编码，将独热编码列还原为原始类别列。

对每个原始列，取值为 1 的独热列对应类别即为原始类别； 若所有独热列均为 0（如 drop 删除的参考类别或未知类别），则还原为 NaN。 缺失列（{col}_missing）激活时还原为 NaN。

参数:

X (DataFrame) -- 编码后的数据

返回:

逆编码后的数据

抛出:

NotFittedError -- 当编码器尚未拟合时抛出

返回类型:

DataFrame

class hscredit.core.encoders.OrdinalEncoder(cols=None, mapping=None, handle_unknown='value', handle_missing='value', drop_invariant=False, return_df=True, target=None, n_jobs=-1, parallel_backend=None, parallel_config=None)[源代码]

基类：BaseEncoder

序数编码器.

将每个类别映射为一个整数，保留类别的顺序关系（如果存在）。 适用于树模型和需要保留单一特征维度的场景。

参数

参数:

  • cols (List[str] | None) -- 需要编码的列名列表。如果为None，则自动识别所有列（支持类别型和数值型）

  • mapping (Dict[str, Dict[Any, int]] | None) -- 自定义映射字典，如{'col': {'a': 1, 'b': 2}}，默认为None

  • handle_unknown (str) -- 处理未知类别的方式，默认为'value'

  • handle_missing (str) -- 处理缺失值的方式，默认为'value'

  • drop_invariant (bool) -- 是否删除方差为0的列，默认为False

  • return_df (bool) -- 是否返回DataFrame，默认为True

  • target (str | None)

  • n_jobs (int | float | None)

  • parallel_backend (str | None)

  • parallel_config (Dict[str, Any] | None)

属性

  • mapping_: 序数编码映射字典，格式为 {col: {category: integer}}

参考样例

>>> from hscredit.core.encoders import OrdinalEncoder
>>> encoder = OrdinalEncoder(cols=['education'])
>>> X_encoded = encoder.fit_transform(X)
>>>
>>> # 自定义映射
>>> mapping = {'education': {'high': 3, 'medium': 2, 'low': 1}}
>>> encoder = OrdinalEncoder(cols=['education'], mapping=mapping)
>>> X_encoded = encoder.fit_transform(X)

注意

默认整数映射不含真实序关系，仅对天然有序的类别（如学历 高/中/低）通过 mapping 显式指定顺序才有意义；无序类别用于线性模型时应改用 OneHot 或 WOE 编码，否则会引入 虚假的大小关系。

引用

序数编码参见 sklearn OrdinalEncoder： https://scikit-learn.org/stable/modules/generated/sklearn.preprocessing.OrdinalEncoder.html

inverse_transform(X)[源代码]

逆编码，将整数编码还原为原始类别值。

基于拟合时的双射映射逆向还原。未知编码值（如缺失/未知的 -1） 无法唯一还原，保持原值不变。

参数:

X (DataFrame) -- 编码后的数据

返回:

逆编码后的数据

抛出:

NotFittedError -- 当编码器尚未拟合时抛出

返回类型:

DataFrame

class hscredit.core.encoders.QuantileEncoder(cols=None, quantile=0.5, smoothing=1.0, m=1.0, handle_unknown='value', handle_missing='value', drop_invariant=False, return_df=True, target=None, n_jobs=-1, parallel_backend=None, parallel_config=None)[源代码]

基类：BaseEncoder

分位数编码器.

用目标变量的指定分位数（如中位数）对每个类别进行编码。 适用于回归任务和存在异常值的场景。

参数

参数:

  • cols (List[str] | None) -- 需要编码的列名列表。如果为None，则自动识别所有列（支持类别型和数值型）

  • quantile (float) -- 分位数，范围[0, 1]，默认为0.5（中位数）

  • smoothing (float) -- 平滑参数，默认为1.0

  • m (float) -- 先验权重参数，默认为1.0

  • handle_unknown (str) -- 处理未知类别的方式，默认为'value'

  • handle_missing (str) -- 处理缺失值的方式，默认为'value'

  • drop_invariant (bool) -- 是否删除方差为0的列，默认为False

  • return_df (bool) -- 是否返回DataFrame，默认为True

  • target (str | None)

  • n_jobs (int | float | None)

  • parallel_backend (str | None)

  • parallel_config (Dict[str, Any] | None)

属性

  • mapping_: 分位数编码映射字典，格式为 {col: {category: quantile_value}}

  • global_quantile_: 全局分位数

参考样例

>>> from hscredit.core.encoders import QuantileEncoder
>>> encoder = QuantileEncoder(cols=['category'], quantile=0.5)
>>> X_encoded = encoder.fit_transform(X, y)
>>>
>>> # 使用第90百分位数
>>> encoder = QuantileEncoder(cols=['category'], quantile=0.9)
>>> X_encoded = encoder.fit_transform(X, y)

注意

以目标分位数（而非均值）编码，对异常值更稳健；通过 m 先验权重向全局分位数做收缩 （类别样本越少越靠近全局值）以抑制过拟合。同属有监督编码，需训练集 fit、测试集 transform。

引用

Valdez-Valenzuela, A. et al. (2021). Measuring the quantile encoder. https://arxiv.org/abs/2105.13783 ；另见 category_encoders QuantileEncoder： https://contrib.scikit-learn.org/category_encoders/quantile.html

class hscredit.core.encoders.CatBoostEncoder(cols=None, sigma=None, handle_unknown='value', handle_missing='value', drop_invariant=False, return_df=True, random_state=None, target=None, n_jobs=-1, parallel_backend=None, parallel_config=None)[源代码]

基类：BaseEncoder

CatBoost编码器.

使用有序目标统计（Ordered Target Statistics）方法， 通过随机排序和累积统计来防止过拟合和目标泄漏。

参数

参数:

  • cols (List[str] | None) -- 需要编码的列名列表。如果为None，则自动识别所有列（支持类别型和数值型）

  • sigma (float | None) -- 添加的高斯噪声标准差，默认为None

  • handle_unknown (str) -- 处理未知类别的方式，默认为'value'

  • handle_missing (str) -- 处理缺失值的方式，默认为'value'

  • drop_invariant (bool) -- 是否删除方差为0的列，默认为False

  • return_df (bool) -- 是否返回DataFrame，默认为True

  • random_state (int | None) -- 随机种子，用于可复现性，默认为None

  • target (str | None)

  • n_jobs (int | float | None)

  • parallel_backend (str | None)

  • parallel_config (Dict[str, Any] | None)

属性

  • mapping_: 目标编码映射字典，格式为 {col: {category: encoded_value}}

  • global_mean_: 全局目标均值

参考样例

>>> from hscredit.core.encoders import CatBoostEncoder
>>> encoder = CatBoostEncoder(cols=['category'])
>>> X_encoded = encoder.fit_transform(X, y)
>>>
>>> # 添加噪声
>>> encoder = CatBoostEncoder(cols=['category'], sigma=0.05, random_state=42)
>>> X_encoded = encoder.fit_transform(X, y)

注意

与普通目标编码相比，本编码器对样本随机排序后只用"当前样本之前"的目标累积统计来编码 （ordered target statistics），从而显著降低目标泄漏；random_state 决定排序， 影响结果可复现性。

引用

Prokhorenkova, L. et al. (2018). CatBoost: unbiased boosting with categorical features. NeurIPS 2018. https://arxiv.org/abs/1706.09516

class hscredit.core.encoders.GBMEncoder(cols=None, model_type='xgboost', n_estimators=100, max_depth=5, learning_rate=0.1, subsample=0.8, colsample_bytree=0.8, min_child_samples=20, random_state=None, output_type='leaves', drop_origin=True, handle_unknown='value', handle_missing='value', drop_invariant=False, return_df=True, model_params=None, task='classification', target=None, n_jobs=-1, parallel_backend=None, parallel_config=None)[源代码]

基类：BaseEncoder

梯度提升树编码器.

使用 XGBoost、LightGBM 或 CatBoost 训练树模型， 将样本在树中的位置（叶子节点）转换为特征。

支持多种输出格式: - 'leaves': 叶子节点索引 - 'onehot': 叶子节点独热编码 - 'probability': 预测概率 - 'embedding': 树路径 embedding

参数

参数:

  • cols (List[str] | None) -- 需要编码的列名列表。如果为None，则使用所有特征列

  • model_type (Literal['xgboost', 'lightgbm', 'catboost']) -- GBM模型类型，可选 'xgboost'、'lightgbm'、'catboost'，默认为'xgboost'

  • n_estimators (int) -- 树的数量，默认为100

  • max_depth (int) -- 树的最大深度，默认为5

  • learning_rate (float) -- 学习率，默认为0.1

  • subsample (float) -- 样本采样比例，默认为0.8

  • colsample_bytree (float) -- 特征采样比例，默认为0.8

  • min_child_samples (int) -- 叶子节点最小样本数，默认为20

  • random_state (int | None) -- 随机种子，用于可复现性，默认为None

  • output_type (Literal['leaves', 'onehot', 'probability', 'embedding']) -- 输出特征类型，默认为'leaves' - 'leaves': 返回每棵树上的叶子节点索引 - 'onehot': 对叶子节点进行独热编码 - 'probability': 返回预测概率（仅分类任务） - 'embedding': 返回树路径的embedding表示

  • drop_origin (bool) -- 是否删除原始特征列，默认为True（推荐，避免原始类别特征影响下游模型）

  • handle_unknown (str) -- 处理未知类别的方式，默认为'value'

  • handle_missing (str) -- 处理缺失值的方式，默认为'value'

  • drop_invariant (bool) -- 是否删除方差为0的列，默认为False

  • return_df (bool) -- 是否返回DataFrame，默认为True

  • model_params (Dict[str, Any] | None) -- 额外的模型参数，用于覆盖默认参数，默认为None

  • task (Literal['classification', 'regression']) -- 任务类型，'classification' 或 'regression'，默认为'classification'

  • target (str | None)

  • n_jobs (int | float | None)

  • parallel_backend (str | None)

  • parallel_config (Dict[str, Any] | None)

说明

默认设置 drop_origin=True，即只保留GBM生成的特征（叶子节点、概率等）， 删除原始特征。这样可以避免原始类别特征对下游模型（如LR）造成影响。

属性

  • model_: 训练好的GBM模型

  • n_trees_: 树的数量

  • n_features_: 原始特征数量

  • leaf_indices_: 每棵树的叶子节点索引映射

  • feature_names_: 编码后的特征名列表

  • classes_: 类别标签（分类任务）

  • mapping_: 类别特征编码映射（仅当输入包含object/category类型列时填充）

缺失值支持

XGBoost、LightGBM 和 CatBoost 都原生支持缺失值处理： - XGBoost: 自动学习缺失值的最优分裂方向 - LightGBM: 自动处理缺失值，无需填充 - CatBoost: 将缺失值作为特殊类别处理

对于类别特征中的缺失值，在编码为数值时会保留np.nan格式 对于数值特征中的缺失值，直接传递给GBM模型处理

参考样例

>>> from hscredit.core.encoders import GBMEncoder
>>> encoder = GBMEncoder(
...     model_type='xgboost',
...     n_estimators=50,
...     max_depth=4,
...     output_type='leaves'
... )
>>> X_encoded = encoder.fit_transform(X, y)
>>>
>>> # LightGBM + 独热编码
>>> encoder = GBMEncoder(
...     model_type='lightgbm',
...     output_type='onehot',
...     n_estimators=30,
...     max_depth=3
... )
>>> X_encoded = encoder.fit_transform(X, y)
>>>
>>> # CatBoost + 概率输出
>>> encoder = GBMEncoder(
...     model_type='catboost',
...     output_type='probability',
...     n_estimators=100
... )
>>> X_encoded = encoder.fit_transform(X, y)
>>>
>>> # GBM + LR 组合训练
>>> from sklearn.linear_model import LogisticRegression
>>> from sklearn.pipeline import Pipeline
>>>
>>> # 创建GBM编码器
>>> gbm_encoder = GBMEncoder(
...     model_type='xgboost',
...     output_type='leaves',
...     n_estimators=50,
...     max_depth=3
... )
>>>
>>> # 与LR组合
>>> pipeline = Pipeline([
...     ('gbm', gbm_encoder),
...     ('lr', LogisticRegression(max_iter=1000))
... ])
>>> pipeline.fit(X_train, y_train)
>>> y_pred = pipeline.predict(X_test)

引用

GBDT 叶子节点作为特征输入 LR 的范式出自 He, X. et al. (2014). Practical Lessons from Predicting Clicks on Ads at Facebook. ADKDD'14. https://dl.acm.org/doi/10.1145/2648584.2648589 。底层树模型文档： XGBoost https://xgboost.readthedocs.io/ 、LightGBM https://lightgbm.readthedocs.io/ 、 CatBoost https://catboost.ai/ 。

get_feature_importance()[源代码]

获取特征重要性。

返回:

特征重要性DataFrame，包含'feature'和'importance'两列

返回类型:

DataFrame

get_missing_stats()[源代码]

获取缺失值统计信息。

返回:

缺失值统计DataFrame，包含'feature'、'missing_count'、'missing_ratio'三列

返回类型:

DataFrame

get_model()[源代码]

获取训练好的GBM模型。

返回:

训练好的GBM模型对象

返回类型:

Any

plot_tree(tree_idx=0, **kwargs)[源代码]

绘制树结构。

参数:

  • tree_idx (int) -- 树的索引，默认为0（第一棵树）

  • kwargs -- 传递给plot_tree的其他参数

抛出:

NotImplementedError -- 当模型类型不支持可视化时抛出

class hscredit.core.encoders.CardinalityEncoder(cols=None, max_categories=10, other_label='other', special_values=None, handle_unknown='other', handle_missing='value', drop_invariant=False, return_df=True, target=None, n_jobs=-1, parallel_backend=None, parallel_config=None)[源代码]

基类：BaseEncoder

高基数降维编码器.

将类别型特征从高基数（如100个枚举值）降维为低基数（如最多10类）。 按训练集中各类别的频次排序，保留前 max_categories - 1 个类别， 其余合并为统一的 other_label 标签。

缺失值和特殊值不占 max_categories 配额，始终独立成类。

参数

参数:

  • cols (List[str] | None) -- 需要编码的列名列表。如果为None，则自动识别所有类别型列

  • max_categories (int) -- 每列最大类别数（含 other 标签，不含缺失及特殊值），默认为10

  • other_label (Any) -- 合并后的标签名称，默认为 'other'，支持自定义

  • special_values (List[Any] | None) -- 需要独立成类的特殊值列表（如 [-999, 'unknown']），默认为None

  • handle_unknown (str) -- 处理未知类别的方式，默认为 'other' - 'other': 映射为 other_label - 'error': 抛出错误 - 'return_nan': 返回 NaN

  • handle_missing (str) -- 处理缺失值的方式，默认为 'value' - 'value': 缺失值保持原样（NaN），独立成类 - 'error': 抛出错误 - 'return_nan': 返回 NaN

  • drop_invariant (bool) -- 是否删除方差为0的列，默认为False

  • return_df (bool) -- 是否返回DataFrame，默认为True

  • target (str | None)

  • n_jobs (int | float | None)

  • parallel_backend (str | None)

  • parallel_config (Dict[str, Any] | None)

属性

  • mapping_: 编码映射字典，格式为 {col: {原始类别: 编码后类别}}

  • top_categories_: 各列保留的高频类别列表，格式为 {col: [类别列表]}

  • category_counts_: 各列训练集类别频次统计

参考样例

>>> from hscredit.core.encoders import CardinalityEncoder
>>> encoder = CardinalityEncoder(cols=['city'], max_categories=10)
>>> X_encoded = encoder.fit_transform(X)
>>>
>>> # 自定义标签
>>> encoder = CardinalityEncoder(
...     cols=['city'], max_categories=5, other_label='其他城市'
... )
>>> X_encoded = encoder.fit_transform(X)
>>>
>>> # 特殊值独立成类
>>> encoder = CardinalityEncoder(
...     cols=['score_level'],
...     max_categories=8,
...     special_values=[-999, 'missing'],
... )
>>> X_encoded = encoder.fit_transform(X)
>>>
>>> # 逆编码
>>> X_original = encoder.inverse_transform(X_encoded)

注意

本编码器只做"高基数→低基数"的类别合并（频次 top-N 保留、其余归入 other_label）， 输出仍为类别值，通常作为 WOE/Target/OneHot 等编码的前置步骤，用于抑制长尾稀有类别带来的 过拟合与不稳定。合并依据为训练集频次，故为无监督步骤。

引用

高基数类别的稀有类别合并（rare-category grouping）是类别特征工程的常用预处理，参见 Micci-Barreca, D. (2001). A preprocessing scheme for high-cardinality categorical attributes. ACM SIGKDD Explorations. https://doi.org/10.1145/507533.507538

get_summary()[源代码]

获取各列的降维摘要。

返回:

DataFrame，含列名/原始类别数/保留类别数/合并类别数/特殊值数

返回类型:

DataFrame

get_top_categories(col=None)[源代码]

获取各列保留的高频类别。

参数:

col (str | None) -- 列名，如果为None则返回所有列

返回:

类别列表或字典

返回类型:

list | Dict[str, list]

inverse_transform(X)[源代码]

逆编码。

将编码后的数据还原为原始类别值。 注意: 被合并为 other_label 的类别无法恢复为原始值，逆编码后仍为 other_label。

参数:

X (DataFrame) -- 编码后的数据

返回:

逆编码后的数据

返回类型:

DataFrame