数据角色与运行边界

每次调用 MARS 时，都应明确当前分析数据、可选基准数据、target、特征范围和分组方式。 MARS 不根据变量名或日期猜测这些业务角色。

当前数据与基准数据

df 是本次需要画像、评估、筛选或监控的数据。benchmark_df 是可选的基准期样本， 不计入当前期 Total，也不会在趋势表中增加一个分组。

在分箱评估和监控中，分箱规则来源优先级为：

1. 显式传入的已拟合 binner。
2. benchmark_df。
3. 当前 df。

benchmark_df 同时提供 PSI 的参考分布（expected distribution）。 使用监督分箱时，拟合规则的数据必须至少包含两个有效 target 类别。

Target 表现状态

在分箱风险评估和监控中，target 使用 0 / False 表示好样本，1 / True 表示坏样本。 高层接口也接受字符串 "0"、"1"、"true"、"false"、"True" 和 "False"，并转换为二分类标签。 Null、浮点 NaN 和空字符串表示尚未表现；-1、2、0.5 及其他非空值会报错。 直接调用分箱器拟合时，仍须满足所选分箱器的标签要求，见分箱指南。

当前期 target 缺列或全空时，可以保留 target 名称并提供带标签的 benchmark_df。MARS 使用基准期 拟合监督规则，同时将当前期按无标签模式输出分布指标。

分组列与日期列

参数	职责
group_col	现有月份、渠道、客群等业务分组，决定报告面板和趋势列
time_col	原始日期，是风险图时间范围和按日缺失趋势的数据来源
time_grain	未提供 group_col 时，根据 time_col 生成日、周、月或窗口分组
dataset_flag_col	Modeling 的 train/val/oot 样本切片，不等同于业务趋势分组

同时存在月份分组和原始日期时，应同时传入 group_col 与 time_col，不要用月份字符串代替真实 日期范围。

单次运行边界

分析对象的构造配置只保存可复用策略，不长期保存原始 df、benchmark_df 或本次列角色。 再次生成依赖基准样本的报告时，应在新调用中重新传入基准数据。