Reporting¶

报告对象、结构化结果容器和导出入口。

mars.reporting.MarsProfileReport ¶

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

作为数据探查（EDA）流水线的标准输出载体，该组件负责统一管理并呈现由 MarsDataProfiler 产出的高维特征统计指标与多维趋势矩阵。系统封装了对底层数据帧的只读访问接口、面向 Jupyter 环境的交互式富文本渲染，以及携带高保真条件格式的跨平台电子表格（Excel）持久化导出能力。

属性：

名称	类型	描述
`overview_table`	`DataFrame`	内部持有的全量特征概览宽表上下文引用。
`dq_tables`	`dict of str to DataFrame`	内部持有的数据质量指标趋势字典上下文引用。
`stats_tables`	`dict of str to DataFrame`	内部持有的统计分布指标趋势字典上下文引用。

Notes

该容器提供了针对数据质量探查与时序追踪的统一交互层 API。其内部暴露的 show_overview 与 show_trend 方法通过动态构建级联的样式渲染器（Pandas Styler），支持在交互式计算环境中直接将统计梯度映射为色带（Colormaps）、数据条（Data Bars）及微缩分布字符图（Sparklines）。调用持久化导出时，底层引擎将在物理存储层面上严格还原交互式环境中的条件格式规则，以确保离线监控报表与线上分析环境的视觉一致性。

示例：

>>> 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 = 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]]) -> None

初始化画像报告容器。

参数：

名称	类型	描述	默认
`overview`	`Union[DataFrame, DataFrame]`	特征概览宽表。	必需
`dq_tables`	`Dict[str, Union[DataFrame, DataFrame]]`	数据质量趋势表字典。	必需
`stats_tables`	`Dict[str, Union[DataFrame, DataFrame]]`	统计指标趋势表字典。	必需

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

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 产出的高维特征评估度量与多维趋势矩阵。系统封装了对底层评估数据帧的只读访问接口、面向交互式分析环境的富文本视图渲染，以及跨平台的高保真电子表格持久化导出能力，以支撑特征区分度审计与跨期分布漂移监控。

属性：

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

Notes

该容器提供了针对特征评估诊断的统一交互层 API。其暴露的 show_summary 与 show_trend 方法通过动态构建样式渲染器（Pandas Styler），支持直接将风控指标梯度映射为预警色带与数据条，以加速区分度缺陷与单调性倒挂的物理识别。执行持久化导出时，底层引擎严格还原交互式视图中的条件格式与业务阈值规则，确保离线模型监控文档与线上审计视图的视觉连贯性。

示例：

>>> 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 = 20, 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`	图表区域最多展示的特征数量。	`20`
`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`	样式化后的特征汇总表。

示例：

>>> 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.ProfileData ¶

Bases: NamedTuple

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

属性：

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

示例：

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

Reporting¶

mars.reporting.MarsProfileReport ¶

__init__ ¶

get_profile_data ¶

write_excel ¶

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.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 ¶