特征筛选 `hscredit.core.selectors`

23 种特征筛选器，覆盖缺失率、众数率、方差、相关性、VIF、IV、Lift、PSI、模型重要性、逐步回归、Boruta、组合筛选等维度。SelectionReportCollector 可手动聚合多个已拟合筛选器的报告，生成统一中文摘要。

特征筛选模块.

提供多种特征筛选方法，从多个维度评估和筛选特征。

筛选方法分类

过滤法: 方差、相关性、VIF、缺失率、单一值率、基数、IV、Lift、PSI
包装法: 穷举搜索、逐步回归、Boruta
嵌入法: 特征重要性、Lasso、树模型重要性、Permutation Importance

通用特性

独立使用: fit/transform 接口
sklearn Pipeline 集成
统一的中文筛选报告

参考样例

>>> from hscredit.core.selectors import VarianceSelector, IVSelector, CorrSelector
>>> from hscredit.core.selectors.base import SelectionReportCollector
>>> import pandas as pd
>>> import numpy as np
>>> np.random.seed(42)
>>> X = pd.DataFrame(np.random.randn(1000, 10), columns=[f'f{i}' for i in range(10)])
>>> y = pd.Series(np.random.randint(0, 2, 1000))
>>> selector = VarianceSelector(threshold=0.01)
>>> selector.fit(X, y)
VarianceSelector(...)
>>> report = selector.get_selection_report()
>>> print(f"输入特征数: {report['输入特征数']}, 选中特征数: {report['选中特征数']}")

class hscredit.core.selectors.BaseFeatureSelector(target='target', include=None, exclude=None, binner=None, binning_params=None, threshold=0.0, n_jobs=-1, force_drop=None, parallel_backend=None, parallel_config=None)[源代码]

基类：ParallelizableMixin, TransformerMixin, BaseEstimator, ABC

特征筛选器基类.

所有特征筛选器都继承此类，实现统一的 fit/transform 接口。支持中文筛选报告生成。支持可选的分箱器，在筛选前对数据进行分箱处理。

参数

参数:

target (str) -- 目标变量列名，默认为 'target'。在 scorecardpipeline 风格中用于从 DataFrame 中提取目标列；在 sklearn 风格中若 fit 传入了 y 参数则优先使用 y
include (List[str] | None) -- 强制保留的特征列表，这些特征无论如何都会被保留
exclude (List[str] | None) -- 强制剔除的特征列表，这些特征无论如何都会被剔除
binner (Any | None) -- 可选的已配置分箱器实例，支持已训练或待训练状态，不接受分箱器类
binning_params (Dict[str, Any] | None) -- 可选的 OptimalBinning 构造参数字典。未传入 binner 时，基类使用该字典创建分箱器；同时传入时 binner 优先
threshold (float | int | str) -- 筛选阈值，不同筛选器含义不同
n_jobs (int | float | None) -- 并行工作数，默认为 -1；None 沿用旧串行行为
force_drop (List[str] | None) -- 强制剔除的特征列表，效果与 exclude 合并
parallel_backend (str | None) -- joblib 并行后端，默认为 None
parallel_config (Mapping[str, Any] | None) -- joblib 扩展配置，默认为 None

属性

selected_features_: 选中保留的特征列表
removed_features_: 被剔除的特征列表
dropped_: 被剔除的特征及原因 DataFrame，包含 '特征' 和 '剔除原因' 两列
scores_: 各特征的筛选得分的 Series
n_features_in_: fit 时输入的特征数量
forced_dropped_: 被强制剔除的特征列表
include_: 处理后的强制保留特征列表（字符串会被转为单元素列表）
exclude_: 处理后的强制剔除特征列表（包含 force_drop 的合并结果）

参考样例

sklearn 风格（推荐用于纯特征矩阵）

>>> from hscredit.core.selectors import VarianceSelector
>>> import pandas as pd
>>> import numpy as np
>>> np.random.seed(42)
>>> X = pd.DataFrame(np.random.randn(100, 5), columns=[f'feat_{i}' for i in range(5)])
>>> y = pd.Series(np.random.randint(0, 2, 100))
>>> selector = VarianceSelector(threshold=0.1, include=['feat_0'], exclude=['feat_4'])
>>> selector.fit(X, y)
VarianceSelector(...)
>>> print(selector.selected_features_)
['feat_0', ...]

scorecardpipeline 风格（推荐用于完整数据框）

>>> from hscredit.core.selectors import IVSelector
>>> import pandas as pd
>>> import numpy as np
>>> np.random.seed(42)
>>> df = pd.DataFrame({
...     'feat1': np.random.randn(1000),
...     'feat2': [1] * 1000,  # 低方差，会被剔除
...     'target': np.random.randint(0, 2, 1000)
... })
>>> selector = IVSelector(threshold=0.02, target='target')
>>> selector.fit(df)
IVSelector(...)
>>> report = selector.get_selection_report()
>>> print(f"输入: {report['输入特征数']}, 输出: {report['选中特征数']}")
输入: 2, 输出: 1

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

事务式拟合筛选器，失败时恢复进入本次拟合前的完整状态。

参数:

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

返回类型:

BaseFeatureSelector

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

拟合并转换数据。

等价于依次调用 fit(X, y) 和 transform(X)。

参数

参数:

X (DataFrame | ndarray) -- 输入特征矩阵（DataFrame 或 numpy 数组），或包含目标列的完整数据框
y (ndarray | Series | None) -- 目标变量，可选

返回:

筛选后的特征数据

返回类型:

DataFrame | ndarray

get_dropped_df()[源代码]

获取被剔除特征的 DataFrame。

返回 DataFrame 列说明

特征 (str): 被剔除的特征名称
剔除原因 (str): 特征被剔除的原因描述

返回:: 包含被剔除特征及原因的 DataFrame，无数据时返回仅含列名的空 DataFrame
返回类型:: DataFrame

参考样例

>>> from hscredit.core.selectors import VarianceSelector
>>> import pandas as pd
>>> import numpy as np
>>> np.random.seed(42)
>>> X = pd.DataFrame(np.random.randn(100, 5), columns=[f'f{i}' for i in range(5)])
>>> y = pd.Series(np.random.randint(0, 2, 100))
>>> selector = VarianceSelector(threshold=0.1)
>>> selector.fit(X, y)
VarianceSelector(...)
>>> dropped_df = selector.get_dropped_df()
>>> print(f"共剔除 {len(dropped_df)} 个特征")

get_feature_names_out(input_features=None)[源代码]

返回转换后的字段名，兼容 sklearn Pipeline。

返回类型:: ndarray

get_scores_df()[源代码]

获取特征得分的 DataFrame。

返回 DataFrame 列说明

特征 (str): 特征名称
得分 (float): 特征在筛选器中的得分
状态 (str): 特征状态，取值为 '选中' 或 '剔除'

DataFrame 按得分降序排列。

返回:: 包含特征得分的 DataFrame，无得分时返回仅含列名的空 DataFrame
返回类型:: DataFrame

参考样例

>>> from hscredit.core.selectors import VarianceSelector
>>> import pandas as pd
>>> import numpy as np
>>> np.random.seed(42)
>>> X = pd.DataFrame(np.random.randn(100, 5), columns=[f'f{i}' for i in range(5)])
>>> y = pd.Series(np.random.randint(0, 2, 100))
>>> selector = VarianceSelector(threshold=0.1)
>>> selector.fit(X, y)
VarianceSelector(...)
>>> scores_df = selector.get_scores_df()
>>> print(scores_df.head())

get_selection_report()[源代码]

获取中文筛选报告。

报告包含筛选器的基础信息、统计信息、选中/剔除特征列表及特征得分。

返回字典键值说明

筛选器 (str): 筛选器类名
筛选方法 (str): 筛选方法名称
时间戳 (str): 报告生成时间，格式为 YYYY-MM-DD HH:MM:SS
阈值 (Any): 筛选阈值
参数 (Dict): 筛选器初始化参数（过滤后的有效参数）
强制操作 (Dict | None): 强制保留/剔除的特征信息
输入特征数 (int): fit 时的输入特征数量
选中特征数 (int): 选中的特征数量
剔除特征数 (int): 被剔除的特征数量
特征保留率 (str): 保留比例，格式为 "XX.XX%"
选中特征 (List[str]): 选中特征名称列表
剔除特征 (List[str]，可选): 被剔除特征名称列表
剔除原因 (List[str]，可选): 各剔除特征对应的原因
剔除详情 (List[Dict]，可选): 剔除特征的详细信息
特征得分 (Dict): 各特征得分的字典
得分统计 (Dict，可选): 得分的统计摘要（最大值、最小值、平均值、中位数）

返回:: 包含筛选结果的字典，未拟合时返回包含 "状态" 和 "message" 的字典
返回类型:: Dict[str, Any]

参考样例

>>> from hscredit.core.selectors import VarianceSelector
>>> import pandas as pd
>>> import numpy as np
>>> np.random.seed(42)
>>> X = pd.DataFrame(np.random.randn(100, 5), columns=[f'f{i}' for i in range(5)])
>>> y = pd.Series(np.random.randint(0, 2, 100))
>>> selector = VarianceSelector(threshold=0.1)
>>> selector.fit(X, y)
VarianceSelector(...)
>>> report = selector.get_selection_report()
>>> print(f"输入: {report['输入特征数']}, 选中: {report['选中特征数']}")
输入: 5, 选中: ...

get_selection_report_df()[源代码]

获取简化的 DataFrame 格式报告。

适用于快速查看和导出到 Excel 等场景。

返回 DataFrame 列说明

筛选器 (str): 筛选器类名
筛选方法 (str): 筛选方法名称
阈值 (Any): 筛选阈值
输入特征数 (int): 输入特征数量
选中特征数 (int): 选中特征数量
剔除特征数 (int): 剔除特征数量
保留率 (str): 特征保留比例

返回:: 包含筛选报告关键指标的 DataFrame（单行）
返回类型:: DataFrame

参考样例

>>> from hscredit.core.selectors import VarianceSelector
>>> import pandas as pd
>>> import numpy as np
>>> np.random.seed(42)
>>> X = pd.DataFrame(np.random.randn(100, 5), columns=[f'f{i}' for i in range(5)])
>>> y = pd.Series(np.random.randint(0, 2, 100))
>>> selector = VarianceSelector(threshold=0.1)
>>> selector.fit(X, y)
VarianceSelector(...)
>>> report_df = selector.get_selection_report_df()
>>> print(report_df)

get_support(indices=False)[源代码]

返回选择掩码；indices=True 时返回选中列位置。

参数:: indices (bool)
返回类型:: ndarray

get_support_mask()[源代码]

获取特征选择掩码。

返回一个布尔数组，长度为输入特征数，True 表示该特征被选中。

返回:: 布尔 numpy 数组，True 对应选中特征的下标
抛出:: NotFittedError -- 当筛选器尚未拟合时
返回类型:: ndarray

参考样例

>>> from hscredit.core.selectors import VarianceSelector
>>> import pandas as pd
>>> import numpy as np
>>> np.random.seed(42)
>>> X = pd.DataFrame(np.random.randn(100, 5), columns=[f'f{i}' for i in range(5)])
>>> y = pd.Series(np.random.randint(0, 2, 100))
>>> selector = VarianceSelector(threshold=0.1)
>>> selector.fit(X, y)
VarianceSelector(...)
>>> mask = selector.get_support_mask()
>>> mask.sum() == len(selector.selected_features_)
True

transform(X)[源代码]

根据筛选结果转换数据。

根据 fit 阶段选中的特征，对输入数据进行筛选。

参数

参数:: X (DataFrame | ndarray | List[str]) -- 输入数据，支持 DataFrame、numpy 数组或特征名列表
返回:: 筛选后的数据，类型与输入一致 - DataFrame/ndarray 输入：返回仅包含选中特征的 DataFrame（若包含 target 列则透传） - 列表输入：返回筛选后的特征名列表
抛出:: NotFittedError -- 当筛选器尚未拟合时
返回类型:: DataFrame | ndarray | List[str]

参考样例

>>> from hscredit.core.selectors import VarianceSelector
>>> import pandas as pd
>>> import numpy as np
>>> np.random.seed(42)
>>> X = pd.DataFrame(np.random.randn(100, 5), columns=[f'f{i}' for i in range(5)])
>>> y = pd.Series(np.random.randint(0, 2, 100))
>>> selector = VarianceSelector(threshold=0.1)
>>> selector.fit(X, y)
VarianceSelector(...)
>>> X_selected = selector.transform(X)
>>> X_selected.shape[1] < X.shape[1]
True

class hscredit.core.selectors.SelectionReportCollector(name='特征筛选流程')[源代码]

基类：object

特征筛选报告收集器.

聚合多个已拟合筛选器的结果并生成汇总报告。当前通过 add_report 手动添加，不会自动挂接 sklearn Pipeline。

使用方式

>>> from hscredit.core.selection import (
...     SelectionReportCollector,
...     VarianceSelector,
...     CorrSelector
... )
>>> collector = SelectionReportCollector()
>>>
>>> # 方式1: 手动添加筛选器
>>> selector1 = VarianceSelector(threshold=0.1)
>>> selector1.fit(X)
>>> collector.add_report(selector1)
>>>
>>> selector2 = CorrSelector(threshold=0.8)
>>> selector2.fit(X, y)
>>> collector.add_report(selector2)
>>>
>>> # 获取汇总报告
>>> summary = collector.get_summary()
>>> print(summary)
>>>
>>> # 导出为DataFrame
>>> df = collector.to_dataframe()

参数:: name (str)

add_report(selector, stage_name=None)[源代码]

添加筛选器报告。

将已拟合的筛选器结果添加到收集器中，并生成阶段名称。阶段名称默认为"阶段{序号}"。

参数

参数:

selector (BaseFeatureSelector) -- 已拟合的筛选器对象，必须实现 get_selection_report() 方法
stage_name (str | None) -- 阶段名称，如 '粗筛'、'精筛' 等，默认根据已有报告数量自动生成

返回:

self（支持链式调用）

抛出:

ValidationError -- 当 selector 未实现 get_selection_report() 方法时

返回类型:

SelectionReportCollector

参考样例

>>> from hscredit.core.selectors.base import SelectionReportCollector
>>> from hscredit.core.selectors import VarianceSelector
>>> import pandas as pd
>>> import numpy as np
>>> np.random.seed(42)
>>> X = pd.DataFrame(np.random.randn(100, 5), columns=[f'f{i}' for i in range(5)])
>>> y = pd.Series(np.random.randint(0, 2, 100))
>>> collector = SelectionReportCollector()
>>> selector = VarianceSelector(threshold=0.1)
>>> selector.fit(X, y)
>>> collector.add_report(selector, stage_name="粗筛")
SelectionReportCollector(name='特征筛选流程', stages=1)

get_dropped_summary()[源代码]

获取被剔除特征的汇总表。

汇总所有筛选阶段中被剔除的特征及其剔除原因。

返回 DataFrame 列说明

特征 (str): 被剔除的特征名称
阶段 (str): 该特征被剔除的阶段名称
筛选器 (str): 该阶段使用的筛选器类名
剔除原因 (str): 特征被剔除的原因描述
得分 (Any): 特征在筛选器中的得分，无得分时为 'N/A'

返回:: 剔除特征汇总 DataFrame，无记录时返回空 DataFrame
返回类型:: DataFrame

参考样例

>>> from hscredit.core.selectors.base import SelectionReportCollector
>>> from hscredit.core.selectors import VarianceSelector
>>> import pandas as pd
>>> import numpy as np
>>> np.random.seed(42)
>>> X = pd.DataFrame(np.random.randn(100, 5), columns=[f'f{i}' for i in range(5)])
>>> y = pd.Series(np.random.randint(0, 2, 100))
>>> collector = SelectionReportCollector()
>>> selector = VarianceSelector(threshold=0.1)
>>> selector.fit(X, y)
>>> collector.add_report(selector)
>>> dropped = collector.get_dropped_summary()
>>> print(f"共剔除 {len(dropped)} 个特征")

get_feature_trace()[源代码]

获取特征追踪表。

记录每个特征在每个筛选阶段的状态变化，包括选中、剔除或未处理。

返回 DataFrame 列说明

特征 (str): 特征名称
阶段 (str): 筛选阶段的名称
筛选器 (str): 该阶段使用的筛选器类名
状态 (str): 特征在当前阶段的状态，取值为 '选中'、'剔除' 或 '未处理'
得分/原因 (Any): 选中特征的得分，或剔除特征的原因

返回:: 特征追踪 DataFrame，无记录时返回空 DataFrame
返回类型:: DataFrame

参考样例

>>> from hscredit.core.selectors.base import SelectionReportCollector
>>> from hscredit.core.selectors import VarianceSelector
>>> import pandas as pd
>>> import numpy as np
>>> np.random.seed(42)
>>> X = pd.DataFrame(np.random.randn(100, 5), columns=[f'f{i}' for i in range(5)])
>>> y = pd.Series(np.random.randint(0, 2, 100))
>>> collector = SelectionReportCollector()
>>> selector = VarianceSelector(threshold=0.1)
>>> selector.fit(X, y)
>>> collector.add_report(selector)
>>> trace = collector.get_feature_trace()
>>> print(trace.head())

get_summary()[源代码]

获取汇总报告。

汇总报告包含筛选流程的整体统计信息和各阶段的筛选详情。

返回字典键值说明

流程名称 (str): 筛选流程名称
创建时间 (str): 报告创建时间，格式为 YYYY-MM-DD HH:MM:SS
筛选轮次 (int): 执行的筛选阶段总数
原始特征数 (int): 第一阶段输入的特征数量
最终特征数 (int): 最后一个阶段输出的特征数量
累计剔除特征数 (int): 所有阶段累计剔除的特征总数
特征保留率 (str): 特征保留比例，格式为 "XX.XX%"，无记录时为 "N/A"
筛选器列表 (List[Dict]): 各阶段的筛选器详情列表，每项包含阶段、筛选器、输入、输出、剔除、阈值

返回:: 包含汇总统计和阶段详情的字典，无记录时返回包含 "状态" 和 "message" 的字典
返回类型:: Dict[str, Any]

参考样例

>>> from hscredit.core.selectors.base import SelectionReportCollector
>>> from hscredit.core.selectors import VarianceSelector
>>> import pandas as pd
>>> import numpy as np
>>> np.random.seed(42)
>>> X = pd.DataFrame(np.random.randn(100, 5), columns=[f'f{i}' for i in range(5)])
>>> y = pd.Series(np.random.randint(0, 2, 100))
>>> collector = SelectionReportCollector()
>>> selector = VarianceSelector(threshold=0.1)
>>> selector.fit(X, y)
>>> collector.add_report(selector)
>>> summary = collector.get_summary()
>>> print(f"原始特征数: {summary['原始特征数']}, 最终特征数: {summary['最终特征数']}")
原始特征数: 5, 最终特征数: ...

print_summary()[源代码]

打印汇总报告到控制台。

以格式化的方式打印筛选流程的整体统计信息和各阶段详情。

打印内容

筛选流程名称和创建时间
筛选轮次、原始/最终特征数、累计剔除数、特征保留率
各阶段筛选器详情（阶段名、筛选器名称、输入/输出/剔除特征数）

参考样例

>>> from hscredit.core.selectors.base import SelectionReportCollector
>>> from hscredit.core.selectors import VarianceSelector
>>> import pandas as pd
>>> import numpy as np
>>> np.random.seed(42)
>>> X = pd.DataFrame(np.random.randn(100, 5), columns=[f'f{i}' for i in range(5)])
>>> y = pd.Series(np.random.randint(0, 2, 100))
>>> collector = SelectionReportCollector()
>>> selector = VarianceSelector(threshold=0.1)
>>> selector.fit(X, y)
>>> collector.add_report(selector)
>>> collector.print_summary()

返回类型:: None

to_dataframe()[源代码]

转换为 DataFrame 格式。

将收集到的各筛选阶段报告汇总为一个 DataFrame，每行对应一个筛选阶段。

返回 DataFrame 列说明

阶段 (str): 筛选阶段的名称
筛选器 (str): 该阶段使用的筛选器类名
阈值 (Any): 该阶段使用的筛选阈值
输入特征数 (int): 该阶段输入的特征数量
选中特征数 (int): 该阶段输出的特征数量
剔除特征数 (int): 该阶段剔除的特征数量

返回:: 筛选结果汇总 DataFrame，无记录时返回空 DataFrame
返回类型:: DataFrame

参考样例

>>> from hscredit.core.selectors.base import SelectionReportCollector
>>> from hscredit.core.selectors import VarianceSelector
>>> import pandas as pd
>>> import numpy as np
>>> np.random.seed(42)
>>> X = pd.DataFrame(np.random.randn(100, 5), columns=[f'f{i}' for i in range(5)])
>>> y = pd.Series(np.random.randint(0, 2, 100))
>>> collector = SelectionReportCollector()
>>> selector = VarianceSelector(threshold=0.1)
>>> selector.fit(X, y)
>>> collector.add_report(selector)
>>> df = collector.to_dataframe()
>>> print(df)

to_excel(filepath)[源代码]

导出为 Excel 文件。

将筛选报告导出为多 Sheet 的 Excel 文件，同时生成一份 JSON 格式的详细报告。

Excel 文件内容

筛选汇总 Sheet: 各筛选阶段的统计汇总
特征追踪 Sheet: 每个特征在各阶段的状态变化（仅在有记录时生成）
剔除特征 Sheet: 被剔除特征的详细信息（仅在有记录时生成）
JSON 报告: 与 Excel 同目录的 {文件名}_report.json，包含完整汇总信息

参数:: filepath (str) -- 保存路径，必须以 .xlsx 结尾
返回类型:: None

参考样例

>>> from hscredit.core.selectors.base import SelectionReportCollector
>>> from hscredit.core.selectors import VarianceSelector
>>> import pandas as pd
>>> import numpy as np
>>> np.random.seed(42)
>>> X = pd.DataFrame(np.random.randn(100, 5), columns=[f'f{i}' for i in range(5)])
>>> y = pd.Series(np.random.randint(0, 2, 100))
>>> collector = SelectionReportCollector()
>>> selector = VarianceSelector(threshold=0.1)
>>> selector.fit(X, y)
>>> collector.add_report(selector)
>>> collector.to_excel("筛选报告.xlsx")

class hscredit.core.selectors.TypeSelector(dtype_include=None, dtype_exclude=None, target='target', include=None, exclude=None, force_drop=None, n_jobs=-1, binner=None, binning_params=None, parallel_backend=None, parallel_config=None)[源代码]

direction	含义	评分方式
auto	自动选择最优方向（默认）	score = max(LIFT_bad-1, 1-LIFT_good, 0)
bad	仅评估找坏人能力	score = max(LIFT_bad - 1, 0)
good	仅评估找好人能力	score = max(1 - LIFT_good, 0)

特征筛选 hscredit.core.selectors

特征筛选 `hscredit.core.selectors`