数据画像与特征分析¶

数据画像用于回答训练前最基础的问题：字段是否可用、缺失和特殊值是否异常、分布是否稳定、不同时间或业务分组之间是否出现漂移。

主要入口¶

from mars.analysis import MarsDataProfiler, profile_stats

MarsDataProfiler：配置好的画像器，适合反复分析不同数据集。
profile_stats：轻量函数入口，适合快速计算少量指标。

基本用法¶

profiler = MarsDataProfiler(missing_values=[-999])

report = profiler.generate_profile(
    df,
    features=["income", "utilization", "segment"],
    group_col="month",
    psi_include_missing=False,
    psi_include_special=False,
    metrics=["missing", "zeros", "mean", "psi"],
    enable_sparkline=False,
)

generate_profile 接收本次数据、特征范围、分组和指标列表。MarsDataProfiler 构造函数只保留稳定策略，例如缺失值、特殊值和 PSI 策略。

画像里的 PSI 可通过 psi_include_missing 和 psi_include_special 控制是否纳入缺失箱和特殊值箱。画像 PSI 公式复用 compute 表达式底座，数值和类别特征都会先走 MarsNativeBinner 分箱，再按分箱索引计算 PSI。数值特征默认会删除全局空箱，并合并占比低于 psi_min_bin_size=0.02 的小箱，以降低极小箱带来的 PSI 噪音。类别特征的 psi_n_bins 表示最多保留的 Top-K 类别数量，其余类别进入 Other 箱。需要更敏感地观察数值小箱漂移时，可以显式设置 psi_merge_small_bins=False，或调低 psi_min_bin_size。

常见输出¶

字段	含义
`overview_table`	特征级画像总览，通常用于排序、筛选和看板展示
`dq_tables`	数据质量指标趋势表字典
`stats_tables`	统计指标趋势表字典
`get_profile_data()`	返回 `overview`、`dq_trends`、`stats_trends` 的结构化集合

overview = report.overview_table
profile_data = report.get_profile_data()
dq_trends = profile_data.dq_trends
stats_trends = profile_data.stats_trends

分组与时间¶

已经有分组列时，使用 group_col：

report = profiler.generate_profile(df, group_col="month")

只有原始日期列时，使用 time_col 和 time_grain：

report = profiler.generate_profile(
    df,
    time_col="apply_dt",
    time_grain="month",
)

time_grain 可用于把日期聚合到天、周、月或自定义窗口。具体切分窗口由调用者根据业务需要选择。

数据源分组¶

数据源分组主要用于分箱评估和特征筛选链路，例如解释某类数据源的特征整体表现或筛选流失情况：

from mars.analysis import profile_risk

risk_profile = profile_risk(
    df,
    target="target",
    features=["income", "utilization", "segment"],
    group_col="month",
    feature_data_source={
        "user_profile": ["income"],
        "credit_usage": ["utilization"],
        "application": ["segment"],
    },
)

使用建议¶

画像阶段先关注缺失率、特殊值比例、稳定性和数据源分组。
对宽表建议先用 features 缩小范围，确认指标口径后再扩展到全量字段。
对上线监控或周期复盘，优先把 dq_tables 和 stats_tables 接入内部看板，而不是只看一次性 Excel。