跳转至

报告与评分卡

Reporting：Stable

本页的结构化 report 读取和 Excel/HTML 导出属于 Stable Reporting 能力。评分卡能力的状态 单独标注在对应章节。

适用场景

Report 用于继续筛选、复盘和组合计算；Excel/HTML 用于归档或人工交付；Scorecard 将已拟合分箱规则 与逻辑回归系数转换为评分映射和 SQL。

1. 获得 Report

下面的受测试示例定义了 report，后续导出调用均基于该对象：

import polars as pl

from mars.analysis import profile_risk

df = pl.DataFrame(
    {
        "apply_dt": [
            "2026-01-03",
            "2026-01-10",
            "2026-01-17",
            "2026-01-24",
            "2026-02-03",
            "2026-02-10",
            "2026-02-17",
            "2026-02-24",
            "2026-03-03",
            "2026-03-10",
            "2026-03-17",
            "2026-03-24",
        ],
        "month": ["2026-01"] * 4 + ["2026-02"] * 4 + ["2026-03"] * 4,
        "income": [
            3200,
            3600,
            -999,
            None,
            3300,
            4200,
            -999,
            5800,
            3400,
            4300,
            None,
            6100,
        ],
        "utilization": [
            0.12,
            0.18,
            0.52,
            0.61,
            0.14,
            0.29,
            0.54,
            0.58,
            0.16,
            0.31,
            0.56,
            0.63,
        ],
        "segment": [
            "new",
            "repeat",
            "vip",
            "vip",
            "new",
            "repeat",
            "vip",
            "vip",
            "new",
            "repeat",
            "vip",
            "vip",
        ],
        "target": [0, 0, 1, 1, 0, 1, 1, 1, 0, 1, 1, 1],
    }
)

risk_profile = profile_risk(
    df,
    target="target",
    features=["income", "utilization", "segment"],
    group_col="month",
    time_col="apply_dt",
    binning_type="native",
    method="quantile",
    n_bins=4,
    missing_values=[-999],
    special_values=[-999],
    psi_include_missing=False,
    psi_include_special=False,
)

report = risk_profile.report
summary = report.summary_table
binner = risk_profile.binner

常见对象与字段：

Report 状态 高价值字段
MarsProfileReport Stable overview_table、dq_tables、stats_tables、comparison_tables、report_meta
MarsBinningReport Stable summary_table、detail_table、trend_tables
MarsMonitoringReport Experimental 监控汇总、分箱统计、表现覆盖率和元数据
MarsModelingReport Experimental 多样本切片的汇总、明细、趋势和元数据

2. 导出 Excel 或 HTML

以下代码继续使用上一步定义的 report：

report.write_excel("risk_report.xlsx", engine="openpyxl")
report.write_html(
    "risk_report.html",
    report_name="Current-period risk review",
    max_plots=100,
    chart_embed_mode="auto",
)
HTML 模式 行为
auto 小报告内嵌图片，大报告生成同级资产目录并懒加载
inline 所有图片内嵌，适合必须单文件离线转发的报告
asset 强制使用相对路径图片目录，适合大报告归档

风险趋势图和 HTML Charts 需要评估阶段已经提供有效 time_col。group_col 不能替代日期范围。

MarsProfileReport.write_html() 始终生成无外部资源的单文件，包含 Metadata、Overview、 DQ、Stats 和 Comparisons 页面；它不生成图表。所有 Stable 报告导出已改为严格失败： 资源缺失、请求内容未生成或写入失败都会抛异常，不再只记日志后返回成功。

3. 单独复用趋势图

继续使用上一步定义的 report：

figures = report.build_risk_trend_figures(features=["income"])
fragment = report.render_risk_trends_html(
    features=["income"],
    image_format="svg",
    embed_mode="inline",
)

fragment.html 是可嵌入现有模板的 HTML 片段；资产模式同时返回已写入的图片路径。

4. 构建评分卡

Scoring：Experimental

评分映射、刻度参数和 SQL 输出仍可能调整。受控生产使用应固定 mars-risk==0.0.28， 并为 points_table 和生成 SQL 增加契约测试。

import polars as pl

from mars.feature import MarsNativeBinner
from mars.scoring import build_scorecard

X = pl.DataFrame(
    {
        "income": [2600, 3100, 3500, 3900, 4500, 5200, 6100, 7200],
        "utilization": [0.72, 0.64, 0.55, 0.48, 0.36, 0.28, 0.19, 0.11],
    }
)
y = pl.Series("target", [1, 1, 1, 0, 1, 0, 0, 0])

binner = MarsNativeBinner(method="quantile", n_bins=4).fit(
    X,
    y,
    features=["income", "utilization"],
)
scorecard = build_scorecard(
    binner,
    coefficients={"income": -0.35, "utilization": 0.70},
    intercept=-1.2,
    pdo=20,
    base_score=600,
    base_odds=50,
)

points_table = scorecard.points_table
sql = scorecard.generate_sql(
    features=["income", "utilization"],
    table_prefix="applications",
    score_name="credit_score",
)

评分卡要求分箱器已经使用 target 拟合并具备 WOE 映射。系数字典的特征必须与分箱器规则一致。

常见失败

  • HTML 图表为空：确认生成 report 时传入了有效 time_col。
  • 大报告单文件打开缓慢：使用 auto 或 asset，不要强制内嵌数百张图片。
  • 评分卡提示缺少映射：确认 binner 已拟合、特征名一致且包含 WOE 统计。

下一步