Classification Model Report

model_report

把 session 内多个 run 与上游产物(task-spec / data-profile / feature-analysis / new-models/*/)聚合到一个 6-sheet Excel,落到 <session_dir>/{session_name}_report.xlsx。定位与 classification-model-comparison 互补:comparison 只产 AUC/KS 对比表 + 分桶并排(JSON + md + xlsx);本 skill 补位全链路汇总(需求规格 → 样本分析 → 特征质量 → 多 run 三档评估 → 多 run 分桶并排 → AUC 最高 run 特征清单)。

1. 输入依赖

扫描范围: 仅扫 <session_dir>/new-models/*/,不扫 model-recommend/(历史模型通常无 eval JSON / explainability,纳入会全是占位行,无信息量)。

容错: 每个输入独立加载,缺失时对应 sheet 写"上游产物缺失"占位,不阻断整体流程。仅 <session_dir> 或 new-models/ 不存在时才立即退出。

2. 执行命令

<skill_dir> 指本 skill 所在目录(即本文件所在目录),执行时替换为实际绝对路径。

bashCopy code
python <skill_dir>/scripts/build_report.py \
    --session-dir <session_dir> \
    [-o <output.xlsx>]

示例:

bashCopy code
# 默认: 输出落 <session_dir>/{session_name}_report.xlsx
python <skill_dir>/scripts/build_report.py \
    --session-dir /path/to/runs/20260701-110624-draw_willingness

# 显式指定输出路径
python <skill_dir>/scripts/build_report.py \
    --session-dir /path/to/runs/20260701-110624-draw_willingness \
    -o /tmp/session_report.xlsx

Python 环境: 需要 openpyxl。当前默认 python 无 openpyxl,可用 /data/oceanus_ctr_wkdir/pyenv/anaconda_data_ai/bin/python 跑(Python 3.9 + openpyxl 3.0.10)。

3. 参数说明

build_report.py

session_name 推断: 取 session_dir.name(即目录名,如 20260701-110624-draw_willingness),作为默认输出文件名前缀。

4. 输出产物

单个 xlsx 文件,默认落在 <session_dir>/{session_name}_report.xlsx:

textCopy code
<session_dir>/
└── {session_name}_report.xlsx     # 6-sheet session 级全链路汇总报告

4.1 Sheet 列表

4.2 样式约定

通用样式:

• 标题行(第 1 行): 微软雅黑 14pt bold #1A3060,合并 A1 起的所有列
• source_note 行(第 2 行): 微软雅黑 9pt italic 灰字,合并所有列,内容为实际文件绝对路径(非占位符)
• definitions 行(第 3 行起,可选): 微软雅黑 9pt 灰字,合并所有列,说明本 sheet 布局 + 指标定义
• 表头: 微软雅黑 11pt bold 白字,深蓝底色(#1A3060),居中,thin border
• 数据行: 微软雅黑 10pt,thin border,数字右对齐/文本左对齐
• ws.sheet_view.showGridLines = False
• 列宽: 按 header 与数据内容长度自适应(min 10 / max 50)
• freeze_panes: 标题行下方(A2 或表头行下方)

KV 段头样式(Sheet 1 / 2 / 6 的 KV 部分):

• 段头行: 灰底 #D9D9D9 + 蓝字 bold #1A3060,合并所有列,前缀 ▌
• 字段列(A 列): 微软雅黑 10pt bold 深蓝字
• 值列(B 列): 微软雅黑 10pt,thin border

Split 标签行样式(Sheet 4 / 5):

• 灰底 #D9D9D9 + 蓝字 bold #1A3060,合并所有列,前缀 ▼,格式如 ▼ train 档 (共 N 个 run)

Sheet 1 特定样式:

• 8 个 KV 段(基础信息 / 路由溯源 / WHO / WHAT / HOW GOOD / CONSTRAINTS / HOW TO USE / 数据源),无 DataBar(纯文本概览);样本概况 + 切分配置已下沉到 Sheet 2

Sheet 2 特定样式:

• 4 个 KV 段 + 2 张附表
• 附表"分时段样本": 列 pday / 样本量 / 正样本 / 正样本率 / 正负比
• 附表"Train-Eval-OOT 切分": 列 split / 样本量 / 正样本 / 正样本率 / pday 范围
• KV 与附表之间仅 1 行空行间隔(_write_kv_sheet 返回 next_row, 调用方 cur_row = next_row + 1 定位, 不依赖 ws.max_row — 后者在 KV 只填 A:B 两列时会被 openpyxl 虚报)
• 不画 DataBar(纯数值, 与其他 sheet 区分)

Sheet 3 特定样式:

• 全量特征单表(17 列): # / feature / dtype / IV / 单变量 AUC / PSI / PSI 预警 / 有效分箱 / 缺失率 / unique / mean / std / min / q25 / median / q75 / max
• 无 KV 概况段(样本分析已在 Sheet 2, 避免重复);title + source_note + 表头 + 数据行直连
• 特征 union: stats.csv 为主序(含 dtype/缺失率/quantiles 最完整), iv_table / psi_table 补全 iv/auc/psi/有效分箱, 缺字段写 "—"; union 后按 IV 降序排序(缺失 IV 的特征排末尾)
• 标题: "3. 特征质量 (全量特征 — IV / 单变量 AUC / PSI / 缺失率 / 基础统计)"
• DataBar:
  • IV 列(列 4): 蓝色(#1A3060), 全表归一化
  • PSI 列(列 6): 红色(#C00000), 全表归一化
  • 缺失率 列(列 9): 红色(#C00000), 全表归一化
• freeze_panes = "C2"(冻住 # + feature 两列)
• 列宽: A=6 / B=60(feature 名) / C=10 / D-F=12 / G-H=10 / I=12 / J=10 / K-Q=14-16

Sheet 4 特定样式:

• 4 个 split 子表纵向堆叠(train / test / oot / all), 每个子表前插入 split 标签行
• 9 列: run_name / 样本量 / 正样本率 / AUC / KS / 准确率 / 精确率 / 召回率 / F1
• all = train+test+oot 合并(全集)评估, 指标口径与单 split 一致
• 不画 DataBar(用户要求: 仅看指标数值, 不用条形可视化; 与 AUC/KS 单指标对比交给 Sheet 5 + comparison skill)

Sheet 5 特定样式(严格参考 classification-model-comparison 的对比报告.xlsx Sheet 2 格式):

• 顶部 2 行声明(灰底小字 9pt):
  • R3 指标计算逻辑: 分桶=各模型按自己打分降序十分位(Decile10=最高分) | label率=桶内正样本占比 | 召回率=桶正样本/总正样本 | 累计召回=从高到低累计捕获正样本占比
  • R4 基线版本声明: 基线版本={runs_with_buckets[0].run_name} | Lift=各版本指标 / 基线同指标 (>1 表示优于基线)
• 仅 oot + all 两档, 2 个 split 子表纵向堆叠, 每个子表前插入 ▼ {sp} 档 (共 N 个 run) 标签行
• 列分组按 metric(非按 run): 分桶(1) + 人数(1) + label率 × n_runs + 召回率 × n_runs + 累计召回 × n_runs
• 每个 split 子表两层表头:
  • 第 1 层 metric group header(灰底 #D9D9D9 + 蓝字 bold #1A3060, 合并 n_runs 列): label率(正样本率) / 召回率 / 累计召回
  • 第 2 层模型名子表头(灰底 + 灰字 bold #333333): 每 group 下重复 n_runs 个 run_name, 基线 run 加 (基线) 后缀
• 10 个 decile 数据行(decile 10 → 1, 高分 → 低分), 分桶/人数 取首个有 buckets 的 run 的值
• DataBar(主表, 各列独立归一化):
  • label率 列: 绿色(#2E7D32)
  • 召回率 列: 蓝色(#1A3060)
  • 累计召回 列: 蓝色(#1A3060)
• Lift 子表(仅当 n_runs > 1 且基线 split 有 buckets 时, 在主表下方):
  • 副标题: 各版本 vs {baseline} Lift（label率 / 召回率 / 累计召回 相除）
  • 同主表两层表头结构, group 改为 label率 Lift / 召回率 Lift / 累计召回 Lift
  • 基线列 = -(灰字), 其他列 = 比值(>1 绿 #006100 / <1 红 #9C0006 / =1 灰 #333333)
  • 不画 DataBar(Lift 仅看数值)

Sheet 6 特定样式:

• 4 个 KV 段(基本信息 / 三档 AUC-KS / 训练参数 / 入模特征清单统计)
• 1 张合并全量表(非 2 张独立表): # / feature / importance / mean_abs_shap / mean_shap, 按 importance 降序
• 特征 join: fi_sorted 为主序, SHAP 按 feature 名 map 到对应行; SHAP-only(不在 fi 中)的特征追加在末尾
• importance 缺失写 "—", mean_abs_shap / mean_shap 缺失写 "—"
• KV 与全量表之间仅 1 行空行间隔(同 Sheet 2, 用 _write_kv_sheet(return_next_row=True) 定位, 不用 ws.max_row)
• DataBar: 仅 importance 列(蓝 #1A3060), 全表归一化
• 段头标题: ▌ 特征重要性 + SHAP (全量, 按 importance 降序; SHAP 列缺失写 —)
• run 选择逻辑: _find_best_run 按 oot AUC 降序(oot 缺失则按 train AUC 兜底)选 AUC 最高的 run

4.3 容错行为

5. 与其他 skill 的关联

6. 执行约束

7. 异常处理