Reporting¶

状态：Stable。 导出流程见报告与评分卡。

mars.reporting.MarsProfileReport ¶

数据特征画像与质量评估报告容器。

管理 MarsDataProfiler 产出的特征概览、数据质量趋势和统计分布趋势表，并提供表格读取、富文本视图和 Excel 导出方法。

属性：

名称	类型	描述
`overview_table`	`DataFrame`	全量特征概览表。
`dq_tables`	`dict of str to DataFrame`	数据质量指标趋势表字典。
`stats_tables`	`dict of str to DataFrame`	统计分布指标趋势表字典。
`comparison_tables`	`dict of str to DataFrame`	显式请求的 current/benchmark 对比表。
`report_meta`	`dict of str to Any`	本次运行的轻量元数据与结构化诊断。

Notes

show_overview 与 show_trend 使用 Pandas Styler 显示色带、数据条和 sparkline。 write_excel() 导出带条件格式的电子表格。

示例：

>>> import polars as pl
>>> overview = pl.DataFrame({"feature": ["age"], "missing_rate": [0.0]})
>>> dq_tables = {"missing": pl.DataFrame({"feature": ["age"], "202601": [0.0]})}
>>> report = MarsProfileReport(overview, dq_tables=dq_tables, stats_tables={})
>>> overview_df, dq_dict, stat_dict, comparisons = report.get_profile_data()
>>> overview_df.height
1

init ¶

__init__(
    overview: Union[DataFrame, DataFrame],
    dq_tables: Dict[str, Union[DataFrame, DataFrame]],
    stats_tables: Dict[str, Union[DataFrame, DataFrame]],
    comparison_tables: (
        Dict[str, Union[DataFrame, DataFrame]] | None
    ) = None,
    report_meta: Dict[str, Any] | None = None,
) -> None

初始化画像报告容器。

参数：

名称	类型	描述	默认
`overview`	`Union[DataFrame, DataFrame]`	特征概览宽表。	必需
`dq_tables`	`Dict[str, Union[DataFrame, DataFrame]]`	数据质量趋势表字典。	必需
`stats_tables`	`Dict[str, Union[DataFrame, DataFrame]]`	统计指标趋势表字典。	必需
`comparison_tables`	`Dict[str, Union[DataFrame, DataFrame]] \| None`	Schema drift 与 unseen rate 对比表字典。	`None`
`report_meta`	`Dict[str, Any] \| None`	报告运行元数据与可恢复诊断。	`None`

get_profile_data ¶

get_profile_data() -> ProfileData

返回画像报告的原始数据对象。

返回：

类型	描述
`ProfileData`	包含概览表、数据质量趋势表、统计趋势表和对比表的命名元组。

示例：

>>> import polars as pl
>>> overview = pl.DataFrame({"feature": ["age"], "missing_rate": [0.0]})
>>> report = MarsProfileReport(overview, dq_tables={}, stats_tables={})
>>> report.get_profile_data().overview.height
1

write_excel ¶

write_excel(
    path: str = "mars_report.xlsx",
    group_ascending: bool = True,
    sort_by: Union[str, List[str]] = "total",
    sort_ascending: bool = False,
) -> None

导出画像 Excel 报告。

参数：

名称	类型	描述	默认
`path`	`str`	输出 Excel 文件路径。	`'mars_report.xlsx'`
`group_ascending`	`bool`	趋势页中分组列的横向排序方向。	`True`
`sort_by`	`Union[str, List[str]]`	趋势页内部的排序依据。	`'total'`
`sort_ascending`	`bool`	趋势页内部是否按 `sort_by` 升序排列。	`False`

返回：

类型	描述
`None`	方法仅产生文件写入副作用。

示例：

>>> import polars as pl
>>> from pathlib import Path
>>> from tempfile import TemporaryDirectory
>>> overview = pl.DataFrame({"feature": ["age"], "missing_rate": [0.0]})
>>> report = MarsProfileReport(overview, dq_tables={}, stats_tables={})
>>> with TemporaryDirectory() as tmp:
...     report.write_excel(str(Path(tmp) / "profile.xlsx")) is None
True

write_html ¶

write_html(
    path: str = "mars_profile_report.html",
    *,
    report_name: str = "MARS Data Profile"
) -> None

Export a self-contained interactive HTML profile report.

参数：

名称	类型	描述	默认
`path`	`str`	Output HTML file path.	`'mars_profile_report.html'`
`report_name`	`str`	Report title displayed in the HTML header.	`'MARS Data Profile'`

返回：

类型	描述
`None`	The method only writes the report file.

show_overview ¶

show_overview(
    features: Union[str, List[str]] | None = None,
    sort_by: Union[str, List[str]] | None = None,
    sort_ascending: bool = False,
) -> pd.io.formats.style.Styler

展示特征概览宽表。

参数：

名称	类型	描述	默认
`features`	`Union[str, List[str]] \| None`	需要展示的特征名称。若为 `None`，展示全部特征。	`None`
`sort_by`	`Union[str, List[str]] \| None`	排序依据列。若为 `None`，默认先按 `dtype` 再按 `missing_rate` 排序。	`None`
`sort_ascending`	`bool`	是否按 `sort_by` 升序排列。	`False`

返回：

类型	描述
`Styler`	适合在 Jupyter 环境中直接渲染的样式化概览表。

示例：

>>> import polars as pl
>>> overview = pl.DataFrame(
...     {
...         "feature": ["age"],
...         "dtype": ["Int64"],
...         "missing_rate": [0.0],
...         "zeros_rate": [0.0],
...         "unique_rate": [1.0],
...         "mode_rate": [0.25],
...     }
... )
>>> report = MarsProfileReport(overview, dq_tables={}, stats_tables={})
>>> hasattr(report.show_overview(features="age"), "to_html")
True

show_trend ¶

show_trend(
    metric: str,
    features: Union[str, List[str]] | None = None,
    group_ascending: bool = True,
    sort_by: Union[List[str], str] = "total",
    sort_ascending: bool = False,
) -> pd.io.formats.style.Styler

展示指定指标的分组趋势。

参数：

名称	类型	描述	默认
`metric`	`str`	指标名称，例如 `"missing"`、`"mean"` 或 `"psi"`。	必需
`features`	`Union[str, List[str]] \| None`	需要展示的特征名称。若为 `None`，展示全部特征。	`None`
`group_ascending`	`bool`	分组列或时间切片列的横向排序方向。	`True`
`sort_by`	`Union[List[str], str]`	趋势表内部排序依据，可以是单列或多列列表。	`'total'`
`sort_ascending`	`bool`	是否按 `sort_by` 升序排列。	`False`

返回：

类型	描述
`Styler`	样式化趋势热力表。

引发：

类型	描述
`ValueError`	当 `metric` 不在当前报告支持的指标范围内时抛出。

示例：

>>> import polars as pl
>>> overview = pl.DataFrame({"feature": ["age"], "dtype": ["Int64"], "missing_rate": [0.0]})
>>> trend = pl.DataFrame({"feature": ["age"], "dtype": ["Int64"], "2026-01": [0.0], "total": [0.0]})
>>> report = MarsProfileReport(overview, dq_tables={"missing": trend}, stats_tables={})
>>> hasattr(report.show_trend("missing", features="age"), "to_html")
True

mars.reporting.MarsBinningReport ¶

特征效能与稳定性评估报告容器。

管理 MarsBinEvaluator 产出的特征级汇总、分箱明细和指标趋势表，并提供表格读取、富文本视图、Excel 和 HTML 导出方法。

属性：

名称	类型	描述
`summary_table`	`DataFrame`	特征级汇总评估表。
`trend_tables`	`dict of str to DataFrame`	核心评估指标趋势表字典。
`detail_table`	`DataFrame`	分箱明细表。
`group_col`	`str`	内部挂载的分组维度标识。

Notes

show_summary 与 show_trend 使用 Pandas Styler 显示指标色带和数据条。write_excel() 和 write_html() 分别生成电子表格和交互式 HTML 报告。

示例：

>>> import polars as pl
>>> summary = pl.DataFrame({"feature": ["age"], "iv": [0.12], "ks": [18.0]})
>>> detail = pl.DataFrame({"feature": ["age"], "bin_index": [0], "count": [100]})
>>> trend_tables = {"psi": pl.DataFrame({"feature": ["age"], "202601": [0.01]})}
>>> report = MarsBinningReport(summary, trend_tables, detail, group_col="month")
>>> report.get_evaluation_data()[0].height
1

summary_table `property` ¶

summary_table: Union[DataFrame, DataFrame]

返回特征汇总评估表。

返回：

类型	描述
`DataFrame or DataFrame`	与构造时输入类型一致的汇总表。

示例：

>>> import polars as pl
>>> summary = pl.DataFrame({"feature": ["age"], "iv": [0.12]})
>>> report = MarsBinningReport(summary, {}, pl.DataFrame())
>>> report.summary_table.height
1

trend_tables `property` ¶

trend_tables: Dict[str, Union[DataFrame, DataFrame]]

返回指标趋势表字典。

返回：

类型	描述
`dict of str to pl.DataFrame or pd.DataFrame`	键为指标名称，值为对应趋势宽表。

示例：

>>> import polars as pl
>>> trend = {"psi": pl.DataFrame({"feature": ["age"], "2026-01": [0.01]})}
>>> report = MarsBinningReport(pl.DataFrame(), trend, pl.DataFrame())
>>> sorted(report.trend_tables)
['psi']

detail_table `property` ¶

detail_table: Union[DataFrame, DataFrame]

返回分箱明细表。

返回：

类型	描述
`DataFrame or DataFrame`	与构造时输入类型一致的分箱明细表。

示例：

>>> import polars as pl
>>> detail = pl.DataFrame({"feature": ["age"], "bin_index": [0]})
>>> report = MarsBinningReport(pl.DataFrame(), {}, detail)
>>> report.detail_table.height
1

missing_by_day_table `property` ¶

missing_by_day_table: Union[DataFrame, DataFrame] | None

返回按日聚合的缺失明细表。

返回：

类型	描述
`DataFrame or DataFrame or None`	若评估流程生成了按日缺失统计，则返回对应表；否则返回 `None`。

示例：

>>> import polars as pl
>>> missing = pl.DataFrame({"feature": ["age"], "date": ["2026-01-01"], "missing_rate": [0.0]})
>>> report = MarsBinningReport(pl.DataFrame(), {}, pl.DataFrame(), missing_by_day_table=missing)
>>> report.missing_by_day_table.height
1

report_meta `property` ¶

report_meta: Dict[str, Any]

返回报告元信息字典。

返回：

类型	描述
`dict of str to Any`	生成报告时记录的辅助元数据。

示例：

>>> import polars as pl
>>> report = MarsBinningReport(pl.DataFrame(), {}, pl.DataFrame(), report_meta={"target": "y"})
>>> report.report_meta["target"]
'y'

risk_corr_reference_table `property` ¶

risk_corr_reference_table: (
    Union[DataFrame, DataFrame] | None
)

返回 RC 参考坏率表。

返回：

类型	描述
`DataFrame or DataFrame or None`	报告生成时保存的 RC 参考表。

detail_group_col `property` ¶

detail_group_col: str | None

返回明细表内部使用的分组列名。

返回：

类型	描述
`str \| None`	分箱明细表中的真实分组列名。

init ¶

__init__(
    summary_table: Union[DataFrame, DataFrame],
    trend_tables: Dict[str, Union[DataFrame, DataFrame]],
    detail_table: Union[DataFrame, DataFrame],
    group_col: str | None = None,
    detail_group_col: str | None = None,
    feature_data_source: Dict[str, str] | None = None,
    dt_col: str | None = None,
    missing_by_day_table: (
        Union[DataFrame, DataFrame] | None
    ) = None,
    risk_corr_reference_table: (
        Union[DataFrame, DataFrame] | None
    ) = None,
    report_meta: Dict[str, Any] | None = None,
) -> None

初始化报告容器。

参数：

名称	类型	描述	默认
`summary_table`	`Union[DataFrame, DataFrame]`	特征级汇总表。	必需
`trend_tables`	`Dict[str, Union[DataFrame, DataFrame]]`	指标趋势表字典。	必需
`detail_table`	`Union[DataFrame, DataFrame]`	最细粒度的分箱明细表。	必需
`group_col`	`str \| None`	公开分组语义列名（例如 `'month'` 或 `'vintage'`）。	`None`
`detail_group_col`	`str \| None`	明细表内部实际使用的分组列名。未显式传入时默认沿用 `group_col`。	`None`
`feature_data_source`	`Dict[str, str] \| None`	特征到数据源标签的映射。	`None`
`dt_col`	`str \| None`	原始日期列名。	`None`
`missing_by_day_table`	`Union[DataFrame, DataFrame] \| None`	按日汇总的缺失率明细表。	`None`
`risk_corr_reference_table`	`Union[DataFrame, DataFrame] \| None`	报告内部保存的 RC 参考坏率表，供图表与明细复用同一口径。	`None`
`report_meta`	`Dict[str, Any] \| None`	报告元信息，例如目标列、绘图配置或上下文标签。	`None`

get_evaluation_data ¶

get_evaluation_data() -> Tuple[
    Union[pl.DataFrame, pd.DataFrame],
    Dict[str, Union[pl.DataFrame, pd.DataFrame]],
    Union[pl.DataFrame, pd.DataFrame],
]

获取评估报告的原始数据。

返回：

类型	描述
`tuple`	依次返回 `(summary_table, trend_tables, detail_table)`，且各对象类型与构造时输入保持一致。

示例：

>>> import polars as pl
>>> summary = pl.DataFrame({"feature": ["age"], "iv": [0.12]})
>>> detail = pl.DataFrame({"feature": ["age"], "bin_index": [0]})
>>> report = MarsBinningReport(summary, {}, detail)
>>> report.get_evaluation_data()[0].height
1

write_excel ¶

write_excel(
    path: str = "mars_bin_report.xlsx",
    engine: str = "openpyxl",
) -> None

导出分箱评估 Excel 报告。

参数：

名称	类型	描述	默认
`path`	`str`	输出 Excel 文件路径。	`'mars_bin_report.xlsx'`
`engine`	`str`	Excel 写入引擎，支持 `"auto"`、`"xlwings"` 和 `"openpyxl"`。	`'openpyxl'`

返回：

类型	描述
`None`	方法仅产生文件写入副作用。

引发：

类型	描述
`ValueError`	当 `engine` 不受支持，或模板列与 `detail_table` 不一致时抛出。
`RuntimeError`	当底层 Excel 写入流程失败时抛出。

示例：

>>> import polars as pl
>>> from pathlib import Path
>>> from tempfile import TemporaryDirectory
>>> report = MarsBinningReport(
...     pl.DataFrame({"feature": ["age"], "iv": [0.1]}),
...     {},
...     pl.DataFrame({"feature": ["age"], "bin_index": [0], "count": [10]}),
... )
>>> with TemporaryDirectory() as tmp:
...     report.write_excel(str(Path(tmp) / "report.xlsx"), engine="openpyxl") is None
True

write_html ¶

write_html(
    path: str = "mars_bin_report.html",
    *,
    report_name: str = "MARS Evaluation Report",
    max_plots: int = 500,
    chart_embed_mode: Literal[
        "auto", "inline", "asset"
    ] = "auto",
    sort_by: str = "iv",
    ascending: bool = False,
    include_summary: bool = True,
    include_trends: bool = True,
    include_detail: bool = True,
    include_charts: bool = True
) -> None

导出支持页面切换和大规模图表懒加载的交互式 HTML 报告。

参数：

名称	类型	描述	默认
`path`	`str`	输出 HTML 文件路径。	`'mars_bin_report.html'`
`report_name`	`str`	HTML 页面标题和报告名称。	`'MARS Evaluation Report'`
`max_plots`	`int`	每个 target 的图表区域最多展示的特征数量，默认 500。	`500`
`chart_embed_mode`	`Literal['auto', 'inline', 'asset']`	图表图片嵌入模式。`auto` 在图表数量超过 50 张时写入旁路资产并懒加载； `inline` 强制内嵌；`asset` 强制写入资产目录。	`'auto'`
`sort_by`	`str`	图表和汇总视图使用的排序指标。	`'iv'`
`ascending`	`bool`	是否按 `sort_by` 升序排序。	`False`
`include_summary`	`bool`	是否包含汇总表区域。	`True`
`include_trends`	`bool`	是否包含趋势分析区域。	`True`
`include_detail`	`bool`	是否包含明细区域。	`True`
`include_charts`	`bool`	是否包含图表区域。	`True`

返回：

类型	描述
`None`	方法仅产生文件写入副作用。

示例：

>>> import polars as pl
>>> from pathlib import Path
>>> from tempfile import TemporaryDirectory
>>> report = MarsBinningReport(pl.DataFrame({"feature": ["age"], "iv": [0.1]}), {}, pl.DataFrame())
>>> with TemporaryDirectory() as tmp:
...     path = Path(tmp) / "report.html"
...     report.write_html(str(path), include_charts=False)
...     path.exists()
True

build_risk_trend_figures ¶

build_risk_trend_figures(
    features: str | List[str] | None = None,
    *,
    target: str | List[str] | None = None,
    risk_corr_baseline: RiskCorrBaseline | None = None,
    show_risk: Literal["count", "amt", "both"] = "both",
    sort_by: str = "iv",
    ascending: bool = False,
    max_plots: int = 20,
    dpi: int = 150
) -> list[Figure]

构建风险趋势图对象。

参数：

名称	类型	描述	默认
`features`	`str \| List[str] \| None`	需要绘图的特征名称。传入 `None` 时，按 `sort_by` 和 `max_plots` 自动选择。	`None`
`target`	`str \| List[str] \| None`	多目标报告下需要生成的目标列名。传入 `None` 时生成全部目标。	`None`
`risk_corr_baseline`	`RiskCorrBaseline \| None`	绘图阶段使用的 RC 基准；传入 `None` 时沿用报告生成时保存的口径。	`None`
`show_risk`	`Literal['count', 'amt', 'both']`	风险线展示模式，分别表示件数口径、金额口径和双线同屏。	`'both'`
`sort_by`	`str`	未显式指定 `features` 时的特征排序字段。	`'iv'`
`ascending`	`bool`	是否按 `sort_by` 升序选择特征。	`False`
`max_plots`	`int`	未显式指定 `features` 时最多生成的特征数量。	`20`
`dpi`	`int`	设置到返回 figure 上的图像分辨率。	`150`

返回：

类型	描述
`list[Figure]`	Matplotlib 图对象列表。调用方负责在不再使用后关闭 figure。

引发：

类型	描述
`ValueError`	当报告明细为空、分组列缺失、目标不存在或风险线模式无效时抛出。

示例：

>>> import polars as pl
>>> report = MarsBinningReport(pl.DataFrame({"feature": ["age"], "iv": [0.1]}), {}, pl.DataFrame())
>>> callable(report.build_risk_trend_figures)
True

save_risk_trend_images ¶

save_risk_trend_images(
    output_dir: str | Path,
    features: str | List[str] | None = None,
    *,
    target: str | List[str] | None = None,
    image_format: Literal["svg", "png"] = "svg",
    filename_prefix: str = "risk_trend",
    overwrite: bool = True,
    dpi: int = 150,
    risk_corr_baseline: RiskCorrBaseline | None = None,
    show_risk: Literal["count", "amt", "both"] = "both",
    sort_by: str = "iv",
    ascending: bool = False,
    max_plots: int = 20
) -> list[Path]

保存风险趋势图为图片文件。

参数：

名称	类型	描述	默认
`output_dir`	`str \| Path`	图片输出目录；目录不存在时会自动创建。	必需
`features`	`str \| List[str] \| None`	需要绘图的特征名称。传入 `None` 时，按 `sort_by` 和 `max_plots` 自动选择。	`None`
`target`	`str \| List[str] \| None`	多目标报告下需要保存的目标列名。传入 `None` 时保存全部目标。	`None`
`image_format`	`Literal['svg', 'png']`	输出图片格式。	`'svg'`
`filename_prefix`	`str`	输出文件名前缀。	`'risk_trend'`
`overwrite`	`bool`	当目标文件已存在时是否覆盖。为 `False` 时抛出 `FileExistsError`。	`True`
`dpi`	`int`	PNG 输出分辨率。	`150`
`risk_corr_baseline`	`RiskCorrBaseline \| None`	绘图阶段使用的 RC 基准；传入 `None` 时沿用报告生成时保存的口径。	`None`
`show_risk`	`Literal['count', 'amt', 'both']`	风险线展示模式，分别表示件数口径、金额口径和双线同屏。	`'both'`
`sort_by`	`str`	未显式指定 `features` 时的特征排序字段。	`'iv'`
`ascending`	`bool`	是否按 `sort_by` 升序选择特征。	`False`
`max_plots`	`int`	未显式指定 `features` 时最多保存的特征数量。	`20`

返回：

类型	描述
`list[Path]`	已写出的图片路径列表。

引发：

类型	描述
`FileExistsError`	当 `overwrite=False` 且目标文件已存在时抛出。
`ValueError`	当图像格式、报告明细、分组列或目标参数无效时抛出。

示例：

>>> import polars as pl
>>> report = MarsBinningReport(pl.DataFrame({"feature": ["age"], "iv": [0.1]}), {}, pl.DataFrame())
>>> callable(report.save_risk_trend_images)
True

render_risk_trends_html ¶

render_risk_trends_html(
    features: str | List[str] | None = None,
    *,
    target: str | List[str] | None = None,
    image_format: Literal["svg", "png"] = "svg",
    embed_mode: Literal["inline", "asset"] = "inline",
    output_dir: str | Path | None = None,
    relative_to: str | Path | None = None,
    include_title: bool = True,
    include_caption: bool = True,
    return_figures: bool = False,
    dpi: int = 150,
    filename_prefix: str = "risk_trend",
    overwrite: bool = True,
    risk_corr_baseline: RiskCorrBaseline | None = None,
    show_risk: Literal["count", "amt", "both"] = "both",
    sort_by: str = "iv",
    ascending: bool = False,
    max_plots: int = 20
) -> MarsHtmlRenderResult

渲染可嵌入外部 HTML 报告的风险趋势图片段。

参数：

名称	类型	描述	默认
`features`	`str \| List[str] \| None`	需要渲染的特征名称。传入 `None` 时，按 `sort_by` 和 `max_plots` 自动选择。	`None`
`target`	`str \| List[str] \| None`	多目标报告下需要渲染的目标列名。传入 `None` 时渲染全部目标。	`None`
`image_format`	`Literal['svg', 'png']`	图片格式。`"svg"` 可直接内嵌 XML，`"png"` 可生成 data URI 或资产文件。	`'svg'`
`embed_mode`	`Literal['inline', 'asset']`	HTML 嵌入模式。`"inline"` 生成单文件片段，`"asset"` 写出图片并引用路径。	`'inline'`
`output_dir`	`str \| Path \| None`	`embed_mode="asset"` 时的图片输出目录。	`None`
`relative_to`	`str \| Path \| None`	asset 模式下计算 `img src` 相对路径的基准目录。	`None`
`include_title`	`bool`	是否在片段中包含标题。	`True`
`include_caption`	`bool`	是否为每张图包含 target 和 feature 说明。	`True`
`return_figures`	`bool`	是否在结果中返回 Matplotlib figure。为 `True` 时调用方负责关闭 figure。	`False`
`dpi`	`int`	PNG 输出分辨率。	`150`
`filename_prefix`	`str`	asset 模式下的输出文件名前缀。	`'risk_trend'`
`overwrite`	`bool`	asset 模式下目标文件已存在时是否覆盖。	`True`
`risk_corr_baseline`	`RiskCorrBaseline \| None`	绘图阶段使用的 RC 基准；传入 `None` 时沿用报告生成时保存的口径。	`None`
`show_risk`	`Literal['count', 'amt', 'both']`	风险线展示模式，分别表示件数口径、金额口径和双线同屏。	`'both'`
`sort_by`	`str`	未显式指定 `features` 时的特征排序字段。	`'iv'`
`ascending`	`bool`	是否按 `sort_by` 升序选择特征。	`False`
`max_plots`	`int`	未显式指定 `features` 时最多渲染的特征数量。	`20`

返回：

类型	描述
`MarsHtmlRenderResult`	HTML 片段、写出的资产路径和可选 figure 列表。

引发：

类型	描述
`FileExistsError`	当 asset 模式下 `overwrite=False` 且目标文件已存在时抛出。
`ValueError`	当嵌入模式、图像格式、报告明细、分组列或目标参数无效时抛出。

示例：

>>> import polars as pl
>>> report = MarsBinningReport(pl.DataFrame({"feature": ["age"], "iv": [0.1]}), {}, pl.DataFrame())
>>> callable(report.render_risk_trends_html)
True

plot_risk_trends ¶

plot_risk_trends(
    features: str | List[str] | None = None,
    *,
    target: str | List[str] | None = None,
    risk_corr_baseline: RiskCorrBaseline | None = None,
    show_risk: Literal["count", "amt", "both"] = "both",
    sort_by: str = "iv",
    ascending: bool = False,
    max_plots: int = 20,
    dpi: int = 150,
    return_figures: bool = False
) -> list[Figure] | None

直接展示分箱风险趋势图。

参数：

名称	类型	描述	默认
`features`	`str \| List[str] \| None`	需要绘图的特征名称。传入 `None` 时，按 `sort_by` 和 `max_plots` 自动选择。	`None`
`target`	`str \| List[str] \| None`	多目标报告下需要展示的目标列名。传入 `None` 时展示全部目标。	`None`
`risk_corr_baseline`	`RiskCorrBaseline \| None`	绘图阶段使用的 RC 基准；传入 `None` 时沿用报告生成时保存的口径。	`None`
`show_risk`	`Literal['count', 'amt', 'both']`	风险线展示模式，分别表示件数口径、金额口径和双线同屏。	`'both'`
`sort_by`	`str`	未显式指定 `features` 时的特征排序字段。	`'iv'`
`ascending`	`bool`	是否按 `sort_by` 升序选择特征。	`False`
`max_plots`	`int`	未显式指定 `features` 时最多展示的特征数量。	`20`
`dpi`	`int`	图像显示分辨率。	`150`
`return_figures`	`bool`	是否返回 Matplotlib figure。为 `True` 时调用方负责关闭 figure。	`False`

返回：

类型	描述
`list[Figure] or None`	默认返回 `None` 并关闭展示用图像；`return_figures=True` 时返回 figure 列表。

引发：

类型	描述
`ValueError`	当报告明细为空、分组列缺失或目标不存在时抛出。

示例：

>>> import polars as pl
>>> report = MarsBinningReport(pl.DataFrame({"feature": ["age"], "iv": [0.1]}), {}, pl.DataFrame())
>>> callable(report.plot_risk_trends)
True

show_summary ¶

show_summary(
    features: Union[str, List[str]] | None = None,
) -> pd.io.formats.style.Styler

展示特征汇总评分表。

参数：

名称	类型	描述	默认
`features`	`Union[str, List[str]] \| None`	需要展示的特征名称。若为 `None`，展示全部特征。	`None`

返回：

类型	描述
`Styler`	样式化后的特征汇总表。

引发：

类型	描述
`ValueError`	汇总表为空或指定特征没有匹配行时抛出。

示例：

>>> import polars as pl
>>> summary = pl.DataFrame({"feature": ["age"], "iv": [0.12], "ks": [18.0]})
>>> report = MarsBinningReport(summary, {}, pl.DataFrame())
>>> hasattr(report.show_summary(features="age"), "to_html")
True

show_trend ¶

show_trend(
    metric: str,
    features: Union[str, List[str]] | None = None,
    group_ascending: bool = True,
    sort_by: Union[str, List[str]] = "Total",
    sort_ascending: bool = False,
) -> pd.io.formats.style.Styler

展示指定指标的时间趋势热力图。

渲染并返回一个带条件格式 (Conditional Formatting) 的 Pandas Styler 对象，用于直观分析特征在不同时间切片（或客群分组）下的指标波动趋势。内置了针对风控业务语义优化的专属色盘 (Colormap)。

参数：

名称	类型	描述	默认
`metric`	`str`	需要展示的指标名称。支持的选项可通过 `self.trend_tables.keys()` 查看 (通常包含 'psi', 'auc', 'ks', 'iv', 'bad_rate', 'risk_corr')。	必需
`features`	`Union[str, List[str]] \| None`	需要展示的特征名列表。若为 None，则展示所有特征。	`None`
`group_ascending`	`bool`	分组/时间切片列的排序方向 (横向)。True 表示正序（从左到右由旧到新 / 由小到大）。	`True`
`sort_by`	`Union[str, List[str]]`	特征行的排序依据列。默认按照全局表现 (Total) 排序。	`'Total'`
`sort_ascending`	`bool`	特征行的排序方向 (纵向)。默认降序 (False)，即把表现最差/最好的特征排在最上面。	`False`

返回：

类型	描述
`Styler`	渲染完成的热力图对象。在 Jupyter Notebook 环境下会自动渲染为精美表格。

引发：

类型	描述
`ValueError`	当 `metric` 不在当前报告支持的趋势指标集合中时抛出。

示例：

>>> import polars as pl
>>> trend = pl.DataFrame({"feature": ["age"], "2026-01": [0.01], "Total": [0.01]})
>>> report = MarsBinningReport(pl.DataFrame(), {"psi": trend}, pl.DataFrame())
>>> hasattr(report.show_trend("psi", features="age"), "to_html")
True

mars.reporting.MarsHtmlRenderResult `dataclass` ¶

可嵌入 HTML 片段的渲染结果。

属性：

名称	类型	描述
`html`	`str`	可直接插入外部 HTML 报告的片段，不包含完整 `html` 或 `body` 标签。
`assets`	`list[Path]`	渲染过程中写出的图片资产路径。内嵌模式下通常为空列表。
`figures`	`list[Figure] \| None`	可选返回的 Matplotlib 图对象，便于 Notebook 调试或调用方继续加工。

示例：

>>> result = MarsHtmlRenderResult(html="<div></div>", assets=[])
>>> result.assets
[]

mars.reporting.ProfileData ¶

Bases: NamedTuple

画像报告底层数据对象集合。

属性：

名称	类型	描述
`overview`	`DataFrame`	特征概览宽表。
`dq_trends`	`dict of str to DataFrame`	数据质量指标的趋势宽表字典。
`stats_trends`	`dict of str to DataFrame`	统计分布指标的趋势宽表字典。
`comparisons`	`dict of str to DataFrame`	Schema drift 与 unseen rate 对比表字典。

示例：

>>> import polars as pl
>>> data = ProfileData(
...     overview=pl.DataFrame(), dq_trends={}, stats_trends={}, comparisons={}
... )
>>> data.dq_trends
{}

Reporting¶

mars.reporting.MarsProfileReport ¶

__init__ ¶

get_profile_data ¶

write_excel ¶

write_html ¶

show_overview ¶

show_trend ¶

mars.reporting.MarsBinningReport ¶

summary_table property ¶

trend_tables property ¶

detail_table property ¶

missing_by_day_table property ¶

report_meta property ¶

risk_corr_reference_table property ¶

detail_group_col property ¶

__init__ ¶

get_evaluation_data ¶

write_excel ¶

write_html ¶

build_risk_trend_figures ¶

save_risk_trend_images ¶

render_risk_trends_html ¶

plot_risk_trends ¶

show_summary ¶

show_trend ¶

mars.reporting.MarsHtmlRenderResult dataclass ¶

mars.reporting.ProfileData ¶

init ¶

summary_table `property` ¶

trend_tables `property` ¶

detail_table `property` ¶

missing_by_day_table `property` ¶

report_meta `property` ¶

risk_corr_reference_table `property` ¶

detail_group_col `property` ¶

init ¶

mars.reporting.MarsHtmlRenderResult `dataclass` ¶