跳转至

10 分钟 Quickstart

本页从一个小型 Polars 数据集开始，完成风险评估并读取返回对象。运行前只需要安装 MARS：

pip install mars-risk==0.0.28

1. 运行完整示例

下面的代码块是受测试的完整示例，可以直接保存并运行。样本包含原始申请日期、已有月份分组、 两个数值特征、一个类别特征和二分类 target。

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

2. 读取返回对象

profile_risk() 返回 MarsRiskProfile，而不是直接返回文件路径：

字段 含义
report MarsBinningReport，包含汇总、明细、趋势和导出方法
binner 本次拟合的分箱器，可复用相同规则转换其他数据
targets 本次评估的 target 列表
metadata 特征、分组、日期和分箱配置等运行元数据

group_col="month" 决定报告按哪个分组展开；time_col="apply_dt" 保存真实日期范围并支持按日 缺失趋势。两者职责不同，详见数据角色与运行边界。

3. 导出报告

在示例末尾的 report 对象上继续调用：

report.write_html(
    "risk_report.html",
    report_name="Current-period risk review",
    max_plots=20,
    chart_embed_mode="auto",
)

HTML 图表需要评估时已经提供有效 time_col。需要控制基准期、复用分箱规则或评估无标签当前期时， 进入分箱与风险评估。

下一步