Reporting

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

mars.reporting.MarsProfileReport

Bases: _ReportQuery

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

保存 MarsDataProfiler 已计算的概览、数据质量、统计分布和对比表。 支持查询、Notebook 展示及 Excel、HTML 导出，查询时不重新计算统计。

属性：

名称	类型	描述
overview_table	DataFrame	全量特征概览表。
dq_tables	dict of str to DataFrame	数据质量指标趋势表字典。
stats_tables	dict of str to DataFrame	统计分布指标趋势表字典。
comparison_tables	dict of str to DataFrame	显式请求的当前样本与基准样本对比表。
report_meta	dict of str to Any	本次运行的实际参数、计算口径和结构化诊断。

Notes

show_overview 与 show_trend 使用 Pandas Styler 显示色带、数据条和 sparkline。 write_excel() 导出带条件格式的电子表格，write_html() 导出离线单文件报告。

示例：

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

search_features

search_features(
    query: str = "",
    *,
    sources: str | list[str] | None = None,
    limit: int = 20
) -> list[dict[str, Any]]

按英文标识、显示名、描述和来源检索，同名特征分别返回。

参数：

名称	类型	描述	默认
query	str	在英文 ID、显示名、描述和来源中查找包含此文本的特征，不区分大小写。 默认空字符串匹配全部特征。	''
sources	str | list[str] | None	按已登记来源筛选，默认不限制；与文本条件取交集，未知来源报错。	None
limit	int	非负返回数量上限，默认 20；设为 0 时返回空列表。	20

返回：

类型	描述
list[dict[str, Any]]	按字典顺序返回候选，每项包含 feature 和已登记的业务元数据。 相同中文名可匹配多个英文 ID，最终返回数仍受 limit 限制。

引发：

类型	描述
ValueError	查询文本、来源或数量无效时抛出。

示例：

>>> report.search_features("月收入")

save

save(path: str | Path, *, overwrite: bool = False) -> None

将完整报告保存为包含 JSON 清单与 Parquet 表的单个 ZIP 文件。

参数：

名称	类型	描述	默认
path	str | Path	目标文件路径，通常使用 .marsreport 后缀；父目录必须存在。	必需
overwrite	bool	是否覆盖已有文件，默认拒绝覆盖。设为 True 时，完整写入临时文件后再原子替换。	False

Notes

编码失败传播 ValueError；拒绝覆盖传播 FileExistsError；I/O 失败传播 OSError。 失败不会留下可误认为完整报告的半成品。

示例：

>>> report.save("analysis.marsreport")

describe

describe() -> dict[str, Any]

返回报告目录、字段口径、实际参数和限制，不重新计算指标。

返回：

类型	描述
dict[str, Any]	结构化说明；未登记的业务单位、标签定义和观察窗口标为 unknown。

示例：

>>> report.describe()["tables"]

get_table

get_table(
    name: str,
    *,
    features: str | list[str] | None = None,
    columns: list[str] | None = None,
    filters: dict[str, Any] | None = None,
    sort_by: str | list[str] | None = None,
    descending: bool = False,
    offset: int = 0,
    limit: int | None = None,
    sources: str | list[str] | None = None
) -> ReportFrame

查询已有结果，返回可继续加工且与原表类型一致的 DataFrame。

参数：

名称	类型	描述	默认
name	str	describe()["tables"] 中的公共表名，未计算的表不在目录中。	必需
features	str | list[str] | None	原始英文特征 ID，默认不限制。单特征表匹配 feature； 含多个特征角色的表匹配任一角色，多 ID 取并集。 报告声明固定特征范围时，匹配其中任一特征即可保留统计行。 规则等关系表通过成员表查找相关统计行，不为每个特征复制指标。	None
columns	list[str] | None	返回字段，默认保留全部列；显式指定时只返回所列字段，并保持指定顺序。 筛选和排序可使用未返回的列。	None
filters	dict[str, Any] | None	字段到标量相等条件或 {"op": ..., "value": ...} 的映射，默认不筛选。 支持 eq/ne/lt/le/gt/ge/in/not_in/is_null/is_not_null，各字段条件取交集。 非有限值接受 {"$mars": "float", "value": "nan"} 标签， value 也可为 "inf" 或 "-inf"；普通字符串保持原类型。	None
sort_by	str | list[str] | None	单个或多个排序字段，默认保留原行序；相同排序键保持原顺序。	None
descending	bool	是否按 sort_by 降序排列，默认升序；空值置后。	False
offset	int	筛选并排序后跳过的行数，默认 0，必须为非负整数。	0
limit	int | None	非负最大行数；0 返回保留列 schema 的空表，None 不限制。 排序配合 limit 实现 Top-K；需要续页计数时使用 limit 为正整数或 None 的 query_page。	None
sources	str | list[str] | None	按已登记来源筛选，默认不限制。含多个特征角色的表匹配任一角色的来源； 与 features 条件取交集，来源未知时报错。 单特征表要求同一 feature 同时满足特征与来源条件。 规则来源指成员特征的业务来源，不是候选生成器来源；可与 features 命中不同成员。	None

返回：

类型	描述
ReportFrame	查询结果的独立容器；不重新计算指标。

引发：

类型	描述
ValueError	表名、字段、操作符、来源或分页参数无效时抛出。

示例：

>>> report.get_table("summary", sort_by="iv", descending=True, limit=10)

query_page

query_page(name: str, **query: Any) -> dict[str, Any]

按 get_table 参数取得分页证据、总匹配数及持久引用。

参数：

名称	类型	描述	默认
name	str	公共表目录中的表名。	必需
**query	Any	get_table 的关键字参数；默认 offset=0、limit=10。 limit 只接受正整数或 None；None 返回 offset 后全部结果且无续页。 零行精确查询使用 get_table(limit=0)。	{}

返回：

类型	描述
dict[str, Any]	data 保留原生 DataFrame 类型；另含筛选后的总行数、本页行数、 本页之后的省略行数、截断原因和可重放引用 reference。 next_offset 指向下一页，结束时为 None。

引发：

类型	描述
ValueError	limit 不是正整数或 None，或其他 get_table 查询参数无效时抛出。

示例：

>>> page = report.query_page("summary", limit=5)

to_ai_context

to_ai_context(
    *,
    tables: list[str] | None = None,
    features: str | list[str] | None = None,
    columns: list[str] | None = None,
    filters: dict[str, Any] | None = None,
    limit: int = 10,
    max_chars: int = 16000,
    sources: str | list[str] | None = None,
    sort_by: str | list[str] | None = None,
    descending: bool = False,
    offset: int = 0,
    queries: dict[str, dict[str, Any]] | None = None
) -> str

查询已计算结果，并在字符预算内生成可回放的 JSON 摘要。

参数：

名称	类型	描述	默认
tables	list[str] | None	需要查询的公共表名。默认采用目录的 default_ai_queries， 未声明时选第一张表；提供 queries 时默认使用其中的表名。	None
features	str | list[str] | None	所有选中表共用的英文特征 ID 条件，默认不限制；匹配规则同 get_table。	None
columns	list[str] | None	所有选中表共用的返回字段，默认保留全部列；宽趋势表可按日期列选择范围。	None
filters	dict[str, Any] | None	所有选中表共用的筛选条件，格式同 get_table，默认不筛选。	None
limit	int	每表的非负整数行数上限，默认 10；不接受无界的 None。 0 保留空证据、schema、匹配数和查询引用，继续取证定位另给正页长。	10
max_chars	int	最终 JSON 的 Unicode 字符预算，默认 16,000，必须至少为 512。 预算包含身份、查询、口径和省略说明，按字符计数，不按 token 计数。 非空查询至少保留一条完整证据；必要说明与证据无法同时容纳时抛出异常。	16000
sources	str | list[str] | None	所有选中表共用的来源筛选条件，默认不限制；匹配规则同 get_table。	None
sort_by	str | list[str] | None	所有选中表共用的排序字段，默认保留原行序。	None
descending	bool	是否按排序字段降序排列，默认升序。	False
offset	int	每表筛选并排序后跳过的行数，默认 0。	0
queries	dict[str, dict[str, Any]] | None	表名到 get_table 查询参数的映射，同名参数覆盖上述共同参数。 默认各表共用上述参数；可为列结构不同的表分别指定字段、条件和 limit=0。	None

返回：

类型	描述
str	标准 JSON 字符串。相同 null 口径存放在表级 field_defaults， 字段定义继承该默认值。evidence.query 记录预算裁剪后的查询， 可用 get_table 精确回放；identities 按行补充未选出的特征身份。 省略记录包含数量、原因及继续查询位置，完整统计仍保存在报告中。

引发：

类型	描述
ValueError	查询无效或预算无法同时容纳最小必要说明及非空查询的一条证据时抛出。

示例：

>>> report.to_ai_context(queries={"summary": {"limit": 3}})

get_feature

get_feature(
    feature: str, *, limit: int = 100
) -> dict[str, Any]

读取与单个特征相关的已有统计表，并列出无可用行的结果类别。

参数：

名称	类型	描述	默认
feature	str	原始英文特征 ID；已登记但没有匹配统计行时， evidence_status 为 "no_evidence"。	必需
limit	int	每表非负最大行数，默认 100；0 保留空表 schema、匹配状态和省略数。 需要更多行时，可用 get_table 指定 offset 和 limit 继续查询。	100

返回：

类型	描述
dict[str, Any]	包含特征身份、元数据、tables、每表 omitted_rows、 unavailable 类别和 evidence_status。 tables 保留原生 DataFrame 类型，不自动渲染，也不按成员特征复制规则指标。

引发：

类型	描述
ValueError	特征不存在或分页参数无效时抛出。

示例：

>>> report.get_feature("age")["tables"]

__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,
    feature_metadata: FeatureMetadata | None = None,
    business_context: 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	字段类型变化与新增类别占比的对比表，默认不包含对比结果。	None
report_meta	Dict[str, Any] | None	本次运行的实际参数与诊断，默认使用空字典，不补算缺少的统计。	None
feature_metadata	FeatureMetadata | None	以英文特征 ID 为键的业务字典，或包含 feature 列的 Pandas/Polars 表。 支持 display_name、description、data_source 和 unit； 默认不补充业务解释，已有身份列中的有效信息仍会保留。	None
business_context	dict[str, Any] | None	JSON 业务上下文，仅用于解释结果，不改变统计。 标签定义按 labels 中的目标字段登记，未提供的信息标为 unknown。	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 排序。 可传入单列名或多列列表，字段必须存在于相应趋势表。	'total'
sort_ascending	bool	是否按 sort_by 升序排列特征行，默认降序。	False

返回：

类型	描述
None	写入报告文件，不返回数据。

Notes

数值格式沿用实际指标单位；业务文字、身份、分组名和表头按原文保存， 以 = 开头的字符串不会转换为公式。

示例：

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

导出可离线浏览的单文件画像 HTML 报告。

报告包含元数据、概览、数据质量、统计和对比表，支持搜索及按原值排序。 不生成图表，也不重新计算统计。

参数：

名称	类型	描述	默认
path	str	输出文件路径，默认写入 mars_profile_report.html；父目录必须存在。	'mars_profile_report.html'
report_name	str	HTML 页头和浏览器标签页的报告标题，默认使用 "MARS Data Profile"。	'MARS Data Profile'

返回：

类型	描述
None	写入报告文件，不返回数据。

Notes

父目录不存在时，底层写入函数抛出 FileNotFoundError； 报告渲染或文件写入失败时抛出 RuntimeError。

show_overview

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

展示特征概览宽表，数值单位按真实指标字段定义格式化。

参数：

名称	类型	描述	默认
features	Union[str, List[str]] | None	需要展示的特征名称。若为 None，展示全部特征。	None
sort_by	Union[str, List[str]] | None	特征行的排序字段。默认按已有的 dtype、missing_rate 依次排序； 显式指定时只使用所列字段，排序先于列投影和行数限制。	None
sort_ascending	bool	是否按排序字段升序排列，默认降序；也适用于默认排序字段。	False
columns	list[str] | None	展示字段。默认保留全部列；显式指定时只返回所列字段，并保持指定顺序。	None
limit	int | None	排序后的最大展示行数，默认不限制。设为 0 时返回保留列结构的空视图。	None
sources	str | list[str] | None	按已有特征来源筛选；来源未知时明确报错。	None

返回：

类型	描述
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] | None = None,
    sort_ascending: bool = False,
    *,
    columns: list[str] | None = None,
    limit: int | None = None,
    sources: str | list[str] | None = None
) -> pd.io.formats.style.Styler

展示指定指标的分组趋势，数值单位按所属指标定义格式化。

参数：

名称	类型	描述	默认
metric	str	指标或比较表名称，例如 "missing"、"mean"、"psi"、 "schema" 或 "unseen"。	必需
features	Union[str, List[str]] | None	需要展示的特征名称。若为 None，展示全部特征。	None
group_ascending	bool	分组列或时间切片列的横向排序方向，默认按列名升序。 仅在 columns=None 时生效；身份列置前，total 置后。	True
sort_by	Union[List[str], str] | None	表内排序依据，可以是单列或多列列表。None 优先选择 total； 没有该列的比较表按 feature 排序，均遵守 sort_ascending。	None
sort_ascending	bool	是否按 sort_by 升序排列。	False
columns	list[str] | None	展示字段。默认保留全部列并排列分组列；显式指定时保持所列字段及其顺序。	None
limit	int | None	排序后的最大展示行数，默认不限制。设为 0 时返回保留列结构的空视图。	None
sources	str | list[str] | None	按已登记来源筛选特征，默认不限制；与 features 取交集，未知来源报错。	None

返回：

类型	描述
Styler	样式化表；文本类型与计算状态保留原值，空查询结果仍可渲染。 对存在未计算状态的展示特征，在标题中列出状态与原因；原值仍在状态表中。 业务分组名称不影响单位；比例展示百分比，AUC、PSI、IV、Lift、WOE 保持数值口径，KS 展示 0–100 点。

引发：

类型	描述
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

Bases: _ReportQuery

保存特征区分度、分布稳定性和分箱风险的评估结果。

保存 MarsBinEvaluator 已计算的特征汇总、分箱明细和指标趋势表。 支持查询、Notebook 展示及 Excel、HTML 导出，查询时不重新分箱或计算指标。

属性：

名称	类型	描述
summary_table	DataFrame	特征级汇总评估表。
trend_tables	dict of str to DataFrame	指标名到趋势宽表的映射，分组值或时间段作为列。
detail_table	DataFrame	分箱明细表。
group_col	str	报告对外使用的分组列名；明细中的实际列名见 detail_group_col。

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	分箱明细表中的真实分组列名。

search_features

search_features(
    query: str = "",
    *,
    sources: str | list[str] | None = None,
    limit: int = 20
) -> list[dict[str, Any]]

按英文标识、显示名、描述和来源检索，同名特征分别返回。

参数：

名称	类型	描述	默认
query	str	在英文 ID、显示名、描述和来源中查找包含此文本的特征，不区分大小写。 默认空字符串匹配全部特征。	''
sources	str | list[str] | None	按已登记来源筛选，默认不限制；与文本条件取交集，未知来源报错。	None
limit	int	非负返回数量上限，默认 20；设为 0 时返回空列表。	20

返回：

类型	描述
list[dict[str, Any]]	按字典顺序返回候选，每项包含 feature 和已登记的业务元数据。 相同中文名可匹配多个英文 ID，最终返回数仍受 limit 限制。

引发：

类型	描述
ValueError	查询文本、来源或数量无效时抛出。

示例：

>>> report.search_features("月收入")

save

save(path: str | Path, *, overwrite: bool = False) -> None

将完整报告保存为包含 JSON 清单与 Parquet 表的单个 ZIP 文件。

参数：

名称	类型	描述	默认
path	str | Path	目标文件路径，通常使用 .marsreport 后缀；父目录必须存在。	必需
overwrite	bool	是否覆盖已有文件，默认拒绝覆盖。设为 True 时，完整写入临时文件后再原子替换。	False

Notes

编码失败传播 ValueError；拒绝覆盖传播 FileExistsError；I/O 失败传播 OSError。 失败不会留下可误认为完整报告的半成品。

示例：

>>> report.save("analysis.marsreport")

describe

describe() -> dict[str, Any]

返回报告目录、字段口径、实际参数和限制，不重新计算指标。

返回：

类型	描述
dict[str, Any]	结构化说明；未登记的业务单位、标签定义和观察窗口标为 unknown。

示例：

>>> report.describe()["tables"]

get_table

get_table(
    name: str,
    *,
    features: str | list[str] | None = None,
    columns: list[str] | None = None,
    filters: dict[str, Any] | None = None,
    sort_by: str | list[str] | None = None,
    descending: bool = False,
    offset: int = 0,
    limit: int | None = None,
    sources: str | list[str] | None = None
) -> ReportFrame

查询已有结果，返回可继续加工且与原表类型一致的 DataFrame。

参数：

名称	类型	描述	默认
name	str	describe()["tables"] 中的公共表名，未计算的表不在目录中。	必需
features	str | list[str] | None	原始英文特征 ID，默认不限制。单特征表匹配 feature； 含多个特征角色的表匹配任一角色，多 ID 取并集。 报告声明固定特征范围时，匹配其中任一特征即可保留统计行。 规则等关系表通过成员表查找相关统计行，不为每个特征复制指标。	None
columns	list[str] | None	返回字段，默认保留全部列；显式指定时只返回所列字段，并保持指定顺序。 筛选和排序可使用未返回的列。	None
filters	dict[str, Any] | None	字段到标量相等条件或 {"op": ..., "value": ...} 的映射，默认不筛选。 支持 eq/ne/lt/le/gt/ge/in/not_in/is_null/is_not_null，各字段条件取交集。 非有限值接受 {"$mars": "float", "value": "nan"} 标签， value 也可为 "inf" 或 "-inf"；普通字符串保持原类型。	None
sort_by	str | list[str] | None	单个或多个排序字段，默认保留原行序；相同排序键保持原顺序。	None
descending	bool	是否按 sort_by 降序排列，默认升序；空值置后。	False
offset	int	筛选并排序后跳过的行数，默认 0，必须为非负整数。	0
limit	int | None	非负最大行数；0 返回保留列 schema 的空表，None 不限制。 排序配合 limit 实现 Top-K；需要续页计数时使用 limit 为正整数或 None 的 query_page。	None
sources	str | list[str] | None	按已登记来源筛选，默认不限制。含多个特征角色的表匹配任一角色的来源； 与 features 条件取交集，来源未知时报错。 单特征表要求同一 feature 同时满足特征与来源条件。 规则来源指成员特征的业务来源，不是候选生成器来源；可与 features 命中不同成员。	None

返回：

类型	描述
ReportFrame	查询结果的独立容器；不重新计算指标。

引发：

类型	描述
ValueError	表名、字段、操作符、来源或分页参数无效时抛出。

示例：

>>> report.get_table("summary", sort_by="iv", descending=True, limit=10)

query_page

query_page(name: str, **query: Any) -> dict[str, Any]

按 get_table 参数取得分页证据、总匹配数及持久引用。

参数：

名称	类型	描述	默认
name	str	公共表目录中的表名。	必需
**query	Any	get_table 的关键字参数；默认 offset=0、limit=10。 limit 只接受正整数或 None；None 返回 offset 后全部结果且无续页。 零行精确查询使用 get_table(limit=0)。	{}

返回：

类型	描述
dict[str, Any]	data 保留原生 DataFrame 类型；另含筛选后的总行数、本页行数、 本页之后的省略行数、截断原因和可重放引用 reference。 next_offset 指向下一页，结束时为 None。

引发：

类型	描述
ValueError	limit 不是正整数或 None，或其他 get_table 查询参数无效时抛出。

示例：

>>> page = report.query_page("summary", limit=5)

to_ai_context

to_ai_context(
    *,
    tables: list[str] | None = None,
    features: str | list[str] | None = None,
    columns: list[str] | None = None,
    filters: dict[str, Any] | None = None,
    limit: int = 10,
    max_chars: int = 16000,
    sources: str | list[str] | None = None,
    sort_by: str | list[str] | None = None,
    descending: bool = False,
    offset: int = 0,
    queries: dict[str, dict[str, Any]] | None = None
) -> str

查询已计算结果，并在字符预算内生成可回放的 JSON 摘要。

参数：

名称	类型	描述	默认
tables	list[str] | None	需要查询的公共表名。默认采用目录的 default_ai_queries， 未声明时选第一张表；提供 queries 时默认使用其中的表名。	None
features	str | list[str] | None	所有选中表共用的英文特征 ID 条件，默认不限制；匹配规则同 get_table。	None
columns	list[str] | None	所有选中表共用的返回字段，默认保留全部列；宽趋势表可按日期列选择范围。	None
filters	dict[str, Any] | None	所有选中表共用的筛选条件，格式同 get_table，默认不筛选。	None
limit	int	每表的非负整数行数上限，默认 10；不接受无界的 None。 0 保留空证据、schema、匹配数和查询引用，继续取证定位另给正页长。	10
max_chars	int	最终 JSON 的 Unicode 字符预算，默认 16,000，必须至少为 512。 预算包含身份、查询、口径和省略说明，按字符计数，不按 token 计数。 非空查询至少保留一条完整证据；必要说明与证据无法同时容纳时抛出异常。	16000
sources	str | list[str] | None	所有选中表共用的来源筛选条件，默认不限制；匹配规则同 get_table。	None
sort_by	str | list[str] | None	所有选中表共用的排序字段，默认保留原行序。	None
descending	bool	是否按排序字段降序排列，默认升序。	False
offset	int	每表筛选并排序后跳过的行数，默认 0。	0
queries	dict[str, dict[str, Any]] | None	表名到 get_table 查询参数的映射，同名参数覆盖上述共同参数。 默认各表共用上述参数；可为列结构不同的表分别指定字段、条件和 limit=0。	None

返回：

类型	描述
str	标准 JSON 字符串。相同 null 口径存放在表级 field_defaults， 字段定义继承该默认值。evidence.query 记录预算裁剪后的查询， 可用 get_table 精确回放；identities 按行补充未选出的特征身份。 省略记录包含数量、原因及继续查询位置，完整统计仍保存在报告中。

引发：

类型	描述
ValueError	查询无效或预算无法同时容纳最小必要说明及非空查询的一条证据时抛出。

示例：

>>> report.to_ai_context(queries={"summary": {"limit": 3}})

get_feature

get_feature(
    feature: str, *, limit: int = 100
) -> dict[str, Any]

读取与单个特征相关的已有统计表，并列出无可用行的结果类别。

参数：

名称	类型	描述	默认
feature	str	原始英文特征 ID；已登记但没有匹配统计行时， evidence_status 为 "no_evidence"。	必需
limit	int	每表非负最大行数，默认 100；0 保留空表 schema、匹配状态和省略数。 需要更多行时，可用 get_table 指定 offset 和 limit 继续查询。	100

返回：

类型	描述
dict[str, Any]	包含特征身份、元数据、tables、每表 omitted_rows、 unavailable 类别和 evidence_status。 tables 保留原生 DataFrame 类型，不自动渲染，也不按成员特征复制规则指标。

引发：

类型	描述
ValueError	特征不存在或分页参数无效时抛出。

示例：

>>> report.get_feature("age")["tables"]

__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,
    feature_metadata: FeatureMetadata | None = None,
    business_context: 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	旧版来源参数，格式为特征 ID 到数据源的映射，默认不额外登记来源。 与 feature_metadata 的来源合并；同一特征来源冲突时报错。	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
feature_metadata	FeatureMetadata | None	以英文特征 ID 为键的业务字典，或含 feature 列的 Pandas/Polars 表。 支持 display_name、description、data_source 和 unit； 默认不补充业务解释，已有身份列中的有效信息仍会保留。	None
business_context	dict[str, Any] | None	JSON 业务上下文，仅用于解释结果，不改变统计。 多标签定义按 labels 中的目标字段组织，未提供的信息标为 unknown。	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 报告。

raw 与 binned 复用各引擎的同一 22 列模板，主展示统一为分箱 KS（0～100 点）。 导出副本的 ks 按特征、目标和实际分组取 max(detail.ks_bin)，供 KS 与 综合指标透视读取；最终汇总使用对应 Total 的分箱 KS，最终 KS 趋势只保留首个目标。 综合指标保留模板的 average 聚合，全部箱级 KS 未定义的组保持空值。 原报告的 ks、逐箱 ks_bin、元数据和计算状态保持原样，不重新拟合或评估。 口径说明分别记录源报告的 ks_method 与导出的 binned 口径；raw 诊断仍属于源报告。 openpyxl 不计算公式或刷新透视缓存，透视由原生 Excel 打开后刷新。

参数：

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

返回：

类型	描述
None	写入报告文件，不返回数据。

引发：

类型	描述
ValueError	当 engine 不受支持、缺少分箱 KS 的必要字段，或模板列与 detail_table 不一致时抛出。
RuntimeError	当底层 Excel 写入流程失败时抛出。

示例：

>>> import polars as pl
>>> from mars.analysis import profile_risk
>>> from pathlib import Path
>>> from tempfile import TemporaryDirectory
>>> data = pl.DataFrame({"age": [20, 25, 30, 35], "target": [0, 1, 0, 1]})
>>> report = profile_risk(
...     data, target="target", features=["age"], method="quantile", n_bins=2,
... ).report
>>> 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,
    include_total: 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" 排序。	'iv'
ascending	bool	是否按 sort_by 升序排序，默认降序。	False
include_summary	bool	是否包含汇总表区域，默认包含。	True
include_trends	bool	是否包含已生成的指标趋势区域，默认包含。	True
include_detail	bool	是否生成 Grouped Pivot 分箱明细区域及其导航、控件和数据。 默认生成；不影响原报告明细、公共查询或图表内部读取明细。	True
include_charts	bool	是否生成原生趋势图区域，默认生成，与 include_detail 独立。 启用时需要有效时间信息；False 时不解析绘图时间。	True
include_total	bool	是否在风险图中显示 Total 面板，默认显示；不改变全局统计或 RC 基准。	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",
    include_total: bool = True,
    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 自动选择。 显式指定时按传入顺序去重，只保留明细中的特征，不受 max_plots 限制。	None
target	str | List[str] | None	多目标报告下需要生成的目标列名。传入 None 时生成全部目标。	None
risk_corr_baseline	RiskCorrBaseline | None	绘图使用的 RC 基准。默认沿用报告保存的口径，未保存时使用 "total"。 "benchmark" 要求报告含已保存的参考表；显式传入时只影响图中 RC。	None
show_risk	Literal['count', 'amt', 'both']	风险线展示模式，分别表示件数口径、金额口径和双线同屏。	'both'
include_total	bool	是否显示 Total 面板；不改变全局统计或 RC 基准。	True
sort_by	str	未显式指定 features 时的特征排序字段。	'iv'
ascending	bool	是否按 sort_by 升序选择特征。	False
max_plots	int	未显式指定 features 时，每个目标最多选择的特征数，默认 20。	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",
    include_total: bool = True,
    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 自动选择。 显式指定时按传入顺序去重，只保留明细中的特征，不受 max_plots 限制。	None
target	str | List[str] | None	多目标报告下需要保存的目标列名。传入 None 时保存全部目标。	None
image_format	Literal['svg', 'png']	输出图片格式，默认 SVG；支持 PNG。	'svg'
filename_prefix	str	输出文件名前缀。	'risk_trend'
overwrite	bool	当目标文件已存在时是否覆盖。为 False 时抛出 FileExistsError。	True
dpi	int	PNG 输出分辨率。	150
risk_corr_baseline	RiskCorrBaseline | None	绘图使用的 RC 基准。默认沿用报告保存的口径，未保存时使用 "total"。 "benchmark" 要求报告含已保存的参考表；显式传入时只影响图中 RC。	None
show_risk	Literal['count', 'amt', 'both']	风险线展示模式，分别表示件数口径、金额口径和双线同屏。	'both'
include_total	bool	是否显示 Total 面板；不改变全局统计或 RC 基准。	True
sort_by	str	未显式指定 features 时的特征排序字段。	'iv'
ascending	bool	是否按 sort_by 升序选择特征。	False
max_plots	int	未显式指定 features 时，每个目标最多选择的特征数，默认 20。	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",
    include_total: bool = True,
    sort_by: str = "iv",
    ascending: bool = False,
    max_plots: int = 20
) -> MarsHtmlRenderResult

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

参数：

名称	类型	描述	默认
features	str | List[str] | None	需要渲染的特征名称。传入 None 时，按 sort_by 和 max_plots 自动选择。 显式指定时按传入顺序去重，只保留明细中的特征，不受 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 基准。默认沿用报告保存的口径，未保存时使用 "total"。 "benchmark" 要求报告含已保存的参考表；显式传入时只影响图中 RC。	None
show_risk	Literal['count', 'amt', 'both']	风险线展示模式，分别表示件数口径、金额口径和双线同屏。	'both'
include_total	bool	是否显示 Total 面板；不改变全局统计或 RC 基准。	True
sort_by	str	未显式指定 features 时的特征排序字段。	'iv'
ascending	bool	是否按 sort_by 升序选择特征。	False
max_plots	int	未显式指定 features 时，每个目标最多选择的特征数，默认 20。	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",
    include_total: bool = True,
    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 自动选择。 显式指定时按传入顺序去重，只保留明细中的特征，不受 max_plots 限制。	None
target	str | List[str] | None	多目标报告下需要展示的目标列名。传入 None 时展示全部目标。	None
risk_corr_baseline	RiskCorrBaseline | None	绘图使用的 RC 基准。默认沿用报告保存的口径，未保存时使用 "total"。 "benchmark" 要求报告含已保存的参考表；显式传入时只影响图中 RC。	None
show_risk	Literal['count', 'amt', 'both']	风险线展示模式，分别表示件数口径、金额口径和双线同屏。	'both'
include_total	bool	是否显示 Total 面板；不改变全局统计或 RC 基准。	True
sort_by	str	未显式指定 features 时的特征排序字段。	'iv'
ascending	bool	是否按 sort_by 升序选择特征。	False
max_plots	int	未显式指定 features 时，每个目标最多选择的特征数，默认 20。	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,
    *,
    sort_by: str | list[str] | None = None,
    sort_ascending: bool = False,
    columns: list[str] | None = None,
    limit: int | None = None,
    sources: str | list[str] | None = None
) -> pd.io.formats.style.Styler

展示特征级评估汇总表。

参数：

名称	类型	描述	默认
features	Union[str, List[str]] | None	需要展示的特征名称。若为 None，展示全部特征。	None
sort_by	str | list[str] | None	特征行的排序字段，支持单列或多列；默认保留原顺序，排序先于列投影和行数限制。	None
sort_ascending	bool	是否按 sort_by 升序排列，默认降序；仅指定排序字段时生效。	False
columns	list[str] | None	展示字段。默认保留全部列；显式指定时只返回所列字段，并保持指定顺序。	None
limit	int | None	排序后的最大展示行数，默认不限制；筛选后或截取后为空时抛出 ValueError。	None
sources	str | list[str] | None	按已登记来源筛选特征，默认不限制；与 features 取交集，未知来源报错。	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,
    *,
    columns: list[str] | None = None,
    limit: int | None = None,
    sources: str | list[str] | None = None
) -> pd.io.formats.style.Styler

展示指定指标在时间切片或客群分组中的变化。

返回带条件格式的 Pandas Styler，色阶方向按指标设置。 查询只读取已有趋势表，不重新聚合分箱明细。

参数：

名称	类型	描述	默认
metric	str	已生成的趋势指标名，可用 self.trend_tables.keys() 查看。 新报告通常包含 psi、auc、ks、iv 和 risk_corr。 bad_rate 读取分箱明细；历史报告已有的同名趋势表仍可展示。	必需
features	Union[str, List[str]] | None	原始英文特征 ID，默认展示所有特征。	None
group_ascending	bool	分组或时间切片列的横向排序方向，默认按列名升序。 仅在 columns=None 时生效；身份列置前，Total 置后。	True
sort_by	Union[str, List[str]]	特征行的排序字段，默认按 Total 排序，指定字段必须存在于趋势表。	'Total'
sort_ascending	bool	是否按 sort_by 升序排列特征行，默认降序；指标大小的业务含义须单独判断。	False
columns	list[str] | None	展示字段。默认保留全部列并排列分组列；显式指定时保持所列字段及其顺序。	None
limit	int | None	排序后的最大展示行数，默认不限制；筛选后或截取后为空时抛出 ValueError。	None
sources	str | list[str] | None	按已登记来源筛选特征，默认不限制；与 features 取交集，未知来源报错。	None

返回：

类型	描述
Styler	可在 Jupyter Notebook 中显示的样式化趋势表。

引发：

类型	描述
ValueError	指标、查询字段或来源无效，或查询结果为空时抛出。

示例：

>>> 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
{}

mars.reporting.Report

Bases: Protocol

供外部程序查询、引用和保存统计结果的公共报告契约。

报告按表名提供已计算结果，无需原始数据或特定分析器。 保存后的持久身份与查询参数可用于跨进程回放证据。

属性：

名称	类型	描述
report_id	str	持久产物标识，区别于 Agent 会话登记句柄。
format_version	int	当前文件格式版本。
report_type	str	分析报告类型。

示例：

>>> isinstance(load_report("analysis.marsreport"), Report)
True

describe

describe() -> dict[str, Any]

返回持久身份、表目录、字段定义、实际参数、业务上下文和诊断。

get_table

get_table(
    name: str,
    *,
    features: str | list[str] | None = None,
    columns: list[str] | None = None,
    filters: dict[str, Any] | None = None,
    sort_by: str | list[str] | None = None,
    descending: bool = False,
    offset: int = 0,
    limit: int | None = None,
    sources: str | list[str] | None = None
) -> ReportFrame

筛选、排序、选列并分页，返回与原表后端一致的独立容器。

get_feature

get_feature(
    feature: str, *, limit: int = 100
) -> dict[str, Any]

读取单特征元数据和关联表；limit=0 保留空表结构与省略计数。

search_features

search_features(
    query: str = "",
    *,
    sources: str | list[str] | None = None,
    limit: int = 20
) -> list[dict[str, Any]]

按文本和来源查找特征，返回英文 ID 及业务元数据，默认最多 20 项。

query_page

query_page(name: str, **query: Any) -> dict[str, Any]

取得分页计数与持久引用；limit 默认 10，只接受正整数或 None。

to_ai_context

to_ai_context(
    *,
    tables: list[str] | None = None,
    features: str | list[str] | None = None,
    columns: list[str] | None = None,
    filters: dict[str, Any] | None = None,
    limit: int = 10,
    max_chars: int = 16000,
    sources: str | list[str] | None = None,
    sort_by: str | list[str] | None = None,
    descending: bool = False,
    offset: int = 0,
    queries: dict[str, dict[str, Any]] | None = None
) -> str

按 Unicode 字符预算生成 JSON 证据；零行查询保留可回放引用。

save

save(path: str | Path, *, overwrite: bool = False) -> None

保存完整统计表、语义目录和持久身份，默认拒绝覆盖已有文件。

mars.reporting.ReportSnapshot

Bases: _ReportQuery

保存公共统计表及其解释信息的独立报告快照。

可查询、分页、生成 AI 上下文和导出文件，无需原始样本或分析会话。

参数：

名称	类型	描述	默认
tables	dict[str, ReportFrame]	公共表名到 Pandas/Polars 统计表的映射，构造时复制容器及 Pandas object 列中的可变值。	必需
description	dict[str, Any]	Report.describe() 返回的完整目录和元数据，必须与 tables 的表名一致。	必需

引发：

类型	描述
ValueError	描述不符合契约或表目录与传入统计表不一致。

Notes

快照只恢复已保存的统计，不重建分箱器、模型或拟合状态，也不重算新样本。 查询保留原表后端；画像和分箱的历史表会在内存中补齐身份列。

示例：

>>> restored = load_report("analysis.marsreport")
>>> restored.get_table("summary", limit=10)

search_features

search_features(
    query: str = "",
    *,
    sources: str | list[str] | None = None,
    limit: int = 20
) -> list[dict[str, Any]]

按英文标识、显示名、描述和来源检索，同名特征分别返回。

参数：

名称	类型	描述	默认
query	str	在英文 ID、显示名、描述和来源中查找包含此文本的特征，不区分大小写。 默认空字符串匹配全部特征。	''
sources	str | list[str] | None	按已登记来源筛选，默认不限制；与文本条件取交集，未知来源报错。	None
limit	int	非负返回数量上限，默认 20；设为 0 时返回空列表。	20

返回：

类型	描述
list[dict[str, Any]]	按字典顺序返回候选，每项包含 feature 和已登记的业务元数据。 相同中文名可匹配多个英文 ID，最终返回数仍受 limit 限制。

引发：

类型	描述
ValueError	查询文本、来源或数量无效时抛出。

示例：

>>> report.search_features("月收入")

save

save(path: str | Path, *, overwrite: bool = False) -> None

将完整报告保存为包含 JSON 清单与 Parquet 表的单个 ZIP 文件。

参数：

名称	类型	描述	默认
path	str | Path	目标文件路径，通常使用 .marsreport 后缀；父目录必须存在。	必需
overwrite	bool	是否覆盖已有文件，默认拒绝覆盖。设为 True 时，完整写入临时文件后再原子替换。	False

Notes

编码失败传播 ValueError；拒绝覆盖传播 FileExistsError；I/O 失败传播 OSError。 失败不会留下可误认为完整报告的半成品。

示例：

>>> report.save("analysis.marsreport")

get_table

get_table(
    name: str,
    *,
    features: str | list[str] | None = None,
    columns: list[str] | None = None,
    filters: dict[str, Any] | None = None,
    sort_by: str | list[str] | None = None,
    descending: bool = False,
    offset: int = 0,
    limit: int | None = None,
    sources: str | list[str] | None = None
) -> ReportFrame

查询已有结果，返回可继续加工且与原表类型一致的 DataFrame。

参数：

名称	类型	描述	默认
name	str	describe()["tables"] 中的公共表名，未计算的表不在目录中。	必需
features	str | list[str] | None	原始英文特征 ID，默认不限制。单特征表匹配 feature； 含多个特征角色的表匹配任一角色，多 ID 取并集。 报告声明固定特征范围时，匹配其中任一特征即可保留统计行。 规则等关系表通过成员表查找相关统计行，不为每个特征复制指标。	None
columns	list[str] | None	返回字段，默认保留全部列；显式指定时只返回所列字段，并保持指定顺序。 筛选和排序可使用未返回的列。	None
filters	dict[str, Any] | None	字段到标量相等条件或 {"op": ..., "value": ...} 的映射，默认不筛选。 支持 eq/ne/lt/le/gt/ge/in/not_in/is_null/is_not_null，各字段条件取交集。 非有限值接受 {"$mars": "float", "value": "nan"} 标签， value 也可为 "inf" 或 "-inf"；普通字符串保持原类型。	None
sort_by	str | list[str] | None	单个或多个排序字段，默认保留原行序；相同排序键保持原顺序。	None
descending	bool	是否按 sort_by 降序排列，默认升序；空值置后。	False
offset	int	筛选并排序后跳过的行数，默认 0，必须为非负整数。	0
limit	int | None	非负最大行数；0 返回保留列 schema 的空表，None 不限制。 排序配合 limit 实现 Top-K；需要续页计数时使用 limit 为正整数或 None 的 query_page。	None
sources	str | list[str] | None	按已登记来源筛选，默认不限制。含多个特征角色的表匹配任一角色的来源； 与 features 条件取交集，来源未知时报错。 单特征表要求同一 feature 同时满足特征与来源条件。 规则来源指成员特征的业务来源，不是候选生成器来源；可与 features 命中不同成员。	None

返回：

类型	描述
ReportFrame	查询结果的独立容器；不重新计算指标。

引发：

类型	描述
ValueError	表名、字段、操作符、来源或分页参数无效时抛出。

示例：

>>> report.get_table("summary", sort_by="iv", descending=True, limit=10)

query_page

query_page(name: str, **query: Any) -> dict[str, Any]

按 get_table 参数取得分页证据、总匹配数及持久引用。

参数：

名称	类型	描述	默认
name	str	公共表目录中的表名。	必需
**query	Any	get_table 的关键字参数；默认 offset=0、limit=10。 limit 只接受正整数或 None；None 返回 offset 后全部结果且无续页。 零行精确查询使用 get_table(limit=0)。	{}

返回：

类型	描述
dict[str, Any]	data 保留原生 DataFrame 类型；另含筛选后的总行数、本页行数、 本页之后的省略行数、截断原因和可重放引用 reference。 next_offset 指向下一页，结束时为 None。

引发：

类型	描述
ValueError	limit 不是正整数或 None，或其他 get_table 查询参数无效时抛出。

示例：

>>> page = report.query_page("summary", limit=5)

to_ai_context

to_ai_context(
    *,
    tables: list[str] | None = None,
    features: str | list[str] | None = None,
    columns: list[str] | None = None,
    filters: dict[str, Any] | None = None,
    limit: int = 10,
    max_chars: int = 16000,
    sources: str | list[str] | None = None,
    sort_by: str | list[str] | None = None,
    descending: bool = False,
    offset: int = 0,
    queries: dict[str, dict[str, Any]] | None = None
) -> str

查询已计算结果，并在字符预算内生成可回放的 JSON 摘要。

参数：

名称	类型	描述	默认
tables	list[str] | None	需要查询的公共表名。默认采用目录的 default_ai_queries， 未声明时选第一张表；提供 queries 时默认使用其中的表名。	None
features	str | list[str] | None	所有选中表共用的英文特征 ID 条件，默认不限制；匹配规则同 get_table。	None
columns	list[str] | None	所有选中表共用的返回字段，默认保留全部列；宽趋势表可按日期列选择范围。	None
filters	dict[str, Any] | None	所有选中表共用的筛选条件，格式同 get_table，默认不筛选。	None
limit	int	每表的非负整数行数上限，默认 10；不接受无界的 None。 0 保留空证据、schema、匹配数和查询引用，继续取证定位另给正页长。	10
max_chars	int	最终 JSON 的 Unicode 字符预算，默认 16,000，必须至少为 512。 预算包含身份、查询、口径和省略说明，按字符计数，不按 token 计数。 非空查询至少保留一条完整证据；必要说明与证据无法同时容纳时抛出异常。	16000
sources	str | list[str] | None	所有选中表共用的来源筛选条件，默认不限制；匹配规则同 get_table。	None
sort_by	str | list[str] | None	所有选中表共用的排序字段，默认保留原行序。	None
descending	bool	是否按排序字段降序排列，默认升序。	False
offset	int	每表筛选并排序后跳过的行数，默认 0。	0
queries	dict[str, dict[str, Any]] | None	表名到 get_table 查询参数的映射，同名参数覆盖上述共同参数。 默认各表共用上述参数；可为列结构不同的表分别指定字段、条件和 limit=0。	None

返回：

类型	描述
str	标准 JSON 字符串。相同 null 口径存放在表级 field_defaults， 字段定义继承该默认值。evidence.query 记录预算裁剪后的查询， 可用 get_table 精确回放；identities 按行补充未选出的特征身份。 省略记录包含数量、原因及继续查询位置，完整统计仍保存在报告中。

引发：

类型	描述
ValueError	查询无效或预算无法同时容纳最小必要说明及非空查询的一条证据时抛出。

示例：

>>> report.to_ai_context(queries={"summary": {"limit": 3}})

get_feature

get_feature(
    feature: str, *, limit: int = 100
) -> dict[str, Any]

读取与单个特征相关的已有统计表，并列出无可用行的结果类别。

参数：

名称	类型	描述	默认
feature	str	原始英文特征 ID；已登记但没有匹配统计行时， evidence_status 为 "no_evidence"。	必需
limit	int	每表非负最大行数，默认 100；0 保留空表 schema、匹配状态和省略数。 需要更多行时，可用 get_table 指定 offset 和 limit 继续查询。	100

返回：

类型	描述
dict[str, Any]	包含特征身份、元数据、tables、每表 omitted_rows、 unavailable 类别和 evidence_status。 tables 保留原生 DataFrame 类型，不自动渲染，也不按成员特征复制规则指标。

引发：

类型	描述
ValueError	特征不存在或分页参数无效时抛出。

示例：

>>> report.get_feature("age")["tables"]

describe

describe() -> dict[str, Any]

返回保存时的完整语义目录副本。

返回：

类型	描述
dict[str, Any]	包含原报告类型、持久身份、表目录、单位、实际参数、上下文和诊断的独立说明。

示例：

>>> restored.describe()["report_id"]

show_table

show_table(name: str, **query: Any) -> pd.DataFrame

查询并转换为 Pandas 表，缺少显示名时使用英文 ID。

参数：

名称	类型	描述	默认
name	str	describe()["tables"] 中的公共表名。	必需
**query	Any	传给 get_table 的筛选、排序、选列和分页参数，默认返回整表。 显式指定 columns 时只返回所列字段，不额外添加显示名列。	{}

返回：

类型	描述
DataFrame	独立 Pandas 表。已有显示名列中的空值回退为对应英文 ID，不修改统计值。

示例：

>>> restored.show_table("summary", limit=5)

write_html

write_html(
    path: str, *, report_name: str = "MARS Report Snapshot"
) -> None

将全部已保存统计与业务元数据导出为离线 HTML。

参数：

名称	类型	描述	默认
path	str	HTML 路径；父目录必须存在。	必需
report_name	str	报告标题，默认使用 "MARS Report Snapshot"。	'MARS Report Snapshot'

Notes

模型分交叉快照使用专用交互页面；其他快照使用通用表格页面。 导出不重新计算统计，也不恢复原报告的所有展示方法。

示例：

>>> restored.write_html("restored.html")

write_excel

write_excel(path: str) -> None

将所有公共表的当前值与业务元数据写入静态 Excel 工作簿。

参数：

名称	类型	描述	默认
path	str	Excel 路径；父目录必须存在。	必需

Notes

每张公共表对应一个工作表，统计值沿用快照语义。 不使用分箱报告的原生透视模板，也不依赖 Excel 刷新透视缓存。

示例：

>>> restored.write_excel("restored.xlsx")

mars.reporting.load_report

load_report(path: str | Path) -> ReportSnapshot

从单个 .marsreport 文件恢复已保存的公共统计表和语义目录。

参数：

名称	类型	描述	默认
path	str | Path	包含 manifest.json 和 Parquet 表的 ZIP 文件，当前仅支持格式版本 1。	必需

返回：

类型	描述
ReportSnapshot	保留原报告类型、表后端、schema、顺序、索引及持久身份的快照。 无需原始宽表、分箱器或分析会话，也不重新计算统计。

引发：

类型	描述
ValueError	格式、清单、表或版本无效时抛出。

Notes

加载时校验清单、表 schema、行数和列顺序，不支持跨格式版本迁移。 文件访问错误传播 OSError；父目录和路径由调用方管理。

示例：

>>> restored = load_report("analysis.marsreport")
>>> restored.get_feature("income")

mars.reporting.snapshot_report

snapshot_report(report: object) -> ReportSnapshot

通过公共接口复制完整统计表、语义目录和业务元数据。

参数：

名称	类型	描述	默认
report	object	实现 Report 契约的报告，也接受外部实现；无需原始样本。	必需

返回：

类型	描述
ReportSnapshot	与原对象隔离的快照，保留报告类型、持久身份及来源，不重新计算指标。

引发：

类型	描述
ValueError	对象不满足契约或目录不完整时抛出。

示例：

>>> isolated = snapshot_report(report)

可携带相关性证据

如何查询相关性、保存报告，以及加载后如何恢复子矩阵，见相关性与模型分交叉。

mars.reporting.CorrelationReport

Bases: ReportSnapshot

保存相关矩阵、候选状态和筛选决策的独立报告快照。

load_report() 返回通用快照，可用本模块同名公共函数继续执行矩阵和邻居查询。

参数：

名称	类型	描述	默认
tables	dict[str, Any]	候选目录、上三角特征对和筛选记录等已计算结果表。	必需
description	dict[str, Any]	与结果表对应的完整语义目录，含方法、候选范围、实际参数和业务元数据。	必需

示例：

>>> report = selector.get_correlation_report()
>>> report.get_matrix(["income"])

search_features

search_features(
    query: str = "",
    *,
    sources: str | list[str] | None = None,
    limit: int = 20
) -> list[dict[str, Any]]

按英文标识、显示名、描述和来源检索，同名特征分别返回。

参数：

名称	类型	描述	默认
query	str	在英文 ID、显示名、描述和来源中查找包含此文本的特征，不区分大小写。 默认空字符串匹配全部特征。	''
sources	str | list[str] | None	按已登记来源筛选，默认不限制；与文本条件取交集，未知来源报错。	None
limit	int	非负返回数量上限，默认 20；设为 0 时返回空列表。	20

返回：

类型	描述
list[dict[str, Any]]	按字典顺序返回候选，每项包含 feature 和已登记的业务元数据。 相同中文名可匹配多个英文 ID，最终返回数仍受 limit 限制。

引发：

类型	描述
ValueError	查询文本、来源或数量无效时抛出。

示例：

>>> report.search_features("月收入")

save

save(path: str | Path, *, overwrite: bool = False) -> None

将完整报告保存为包含 JSON 清单与 Parquet 表的单个 ZIP 文件。

参数：

名称	类型	描述	默认
path	str | Path	目标文件路径，通常使用 .marsreport 后缀；父目录必须存在。	必需
overwrite	bool	是否覆盖已有文件，默认拒绝覆盖。设为 True 时，完整写入临时文件后再原子替换。	False

Notes

编码失败传播 ValueError；拒绝覆盖传播 FileExistsError；I/O 失败传播 OSError。 失败不会留下可误认为完整报告的半成品。

示例：

>>> report.save("analysis.marsreport")

describe

describe() -> dict[str, Any]

返回保存时的完整语义目录副本。

返回：

类型	描述
dict[str, Any]	包含原报告类型、持久身份、表目录、单位、实际参数、上下文和诊断的独立说明。

示例：

>>> restored.describe()["report_id"]

get_table

get_table(
    name: str,
    *,
    features: str | list[str] | None = None,
    columns: list[str] | None = None,
    filters: dict[str, Any] | None = None,
    sort_by: str | list[str] | None = None,
    descending: bool = False,
    offset: int = 0,
    limit: int | None = None,
    sources: str | list[str] | None = None
) -> ReportFrame

查询已有结果，返回可继续加工且与原表类型一致的 DataFrame。

参数：

名称	类型	描述	默认
name	str	describe()["tables"] 中的公共表名，未计算的表不在目录中。	必需
features	str | list[str] | None	原始英文特征 ID，默认不限制。单特征表匹配 feature； 含多个特征角色的表匹配任一角色，多 ID 取并集。 报告声明固定特征范围时，匹配其中任一特征即可保留统计行。 规则等关系表通过成员表查找相关统计行，不为每个特征复制指标。	None
columns	list[str] | None	返回字段，默认保留全部列；显式指定时只返回所列字段，并保持指定顺序。 筛选和排序可使用未返回的列。	None
filters	dict[str, Any] | None	字段到标量相等条件或 {"op": ..., "value": ...} 的映射，默认不筛选。 支持 eq/ne/lt/le/gt/ge/in/not_in/is_null/is_not_null，各字段条件取交集。 非有限值接受 {"$mars": "float", "value": "nan"} 标签， value 也可为 "inf" 或 "-inf"；普通字符串保持原类型。	None
sort_by	str | list[str] | None	单个或多个排序字段，默认保留原行序；相同排序键保持原顺序。	None
descending	bool	是否按 sort_by 降序排列，默认升序；空值置后。	False
offset	int	筛选并排序后跳过的行数，默认 0，必须为非负整数。	0
limit	int | None	非负最大行数；0 返回保留列 schema 的空表，None 不限制。 排序配合 limit 实现 Top-K；需要续页计数时使用 limit 为正整数或 None 的 query_page。	None
sources	str | list[str] | None	按已登记来源筛选，默认不限制。含多个特征角色的表匹配任一角色的来源； 与 features 条件取交集，来源未知时报错。 单特征表要求同一 feature 同时满足特征与来源条件。 规则来源指成员特征的业务来源，不是候选生成器来源；可与 features 命中不同成员。	None

返回：

类型	描述
ReportFrame	查询结果的独立容器；不重新计算指标。

引发：

类型	描述
ValueError	表名、字段、操作符、来源或分页参数无效时抛出。

示例：

>>> report.get_table("summary", sort_by="iv", descending=True, limit=10)

query_page

query_page(name: str, **query: Any) -> dict[str, Any]

按 get_table 参数取得分页证据、总匹配数及持久引用。

参数：

名称	类型	描述	默认
name	str	公共表目录中的表名。	必需
**query	Any	get_table 的关键字参数；默认 offset=0、limit=10。 limit 只接受正整数或 None；None 返回 offset 后全部结果且无续页。 零行精确查询使用 get_table(limit=0)。	{}

返回：

类型	描述
dict[str, Any]	data 保留原生 DataFrame 类型；另含筛选后的总行数、本页行数、 本页之后的省略行数、截断原因和可重放引用 reference。 next_offset 指向下一页，结束时为 None。

引发：

类型	描述
ValueError	limit 不是正整数或 None，或其他 get_table 查询参数无效时抛出。

示例：

>>> page = report.query_page("summary", limit=5)

to_ai_context

to_ai_context(
    *,
    tables: list[str] | None = None,
    features: str | list[str] | None = None,
    columns: list[str] | None = None,
    filters: dict[str, Any] | None = None,
    limit: int = 10,
    max_chars: int = 16000,
    sources: str | list[str] | None = None,
    sort_by: str | list[str] | None = None,
    descending: bool = False,
    offset: int = 0,
    queries: dict[str, dict[str, Any]] | None = None
) -> str

查询已计算结果，并在字符预算内生成可回放的 JSON 摘要。

参数：

名称	类型	描述	默认
tables	list[str] | None	需要查询的公共表名。默认采用目录的 default_ai_queries， 未声明时选第一张表；提供 queries 时默认使用其中的表名。	None
features	str | list[str] | None	所有选中表共用的英文特征 ID 条件，默认不限制；匹配规则同 get_table。	None
columns	list[str] | None	所有选中表共用的返回字段，默认保留全部列；宽趋势表可按日期列选择范围。	None
filters	dict[str, Any] | None	所有选中表共用的筛选条件，格式同 get_table，默认不筛选。	None
limit	int	每表的非负整数行数上限，默认 10；不接受无界的 None。 0 保留空证据、schema、匹配数和查询引用，继续取证定位另给正页长。	10
max_chars	int	最终 JSON 的 Unicode 字符预算，默认 16,000，必须至少为 512。 预算包含身份、查询、口径和省略说明，按字符计数，不按 token 计数。 非空查询至少保留一条完整证据；必要说明与证据无法同时容纳时抛出异常。	16000
sources	str | list[str] | None	所有选中表共用的来源筛选条件，默认不限制；匹配规则同 get_table。	None
sort_by	str | list[str] | None	所有选中表共用的排序字段，默认保留原行序。	None
descending	bool	是否按排序字段降序排列，默认升序。	False
offset	int	每表筛选并排序后跳过的行数，默认 0。	0
queries	dict[str, dict[str, Any]] | None	表名到 get_table 查询参数的映射，同名参数覆盖上述共同参数。 默认各表共用上述参数；可为列结构不同的表分别指定字段、条件和 limit=0。	None

返回：

类型	描述
str	标准 JSON 字符串。相同 null 口径存放在表级 field_defaults， 字段定义继承该默认值。evidence.query 记录预算裁剪后的查询， 可用 get_table 精确回放；identities 按行补充未选出的特征身份。 省略记录包含数量、原因及继续查询位置，完整统计仍保存在报告中。

引发：

类型	描述
ValueError	查询无效或预算无法同时容纳最小必要说明及非空查询的一条证据时抛出。

示例：

>>> report.to_ai_context(queries={"summary": {"limit": 3}})

get_feature

get_feature(
    feature: str, *, limit: int = 100
) -> dict[str, Any]

读取与单个特征相关的已有统计表，并列出无可用行的结果类别。

参数：

名称	类型	描述	默认
feature	str	原始英文特征 ID；已登记但没有匹配统计行时， evidence_status 为 "no_evidence"。	必需
limit	int	每表非负最大行数，默认 100；0 保留空表 schema、匹配状态和省略数。 需要更多行时，可用 get_table 指定 offset 和 limit 继续查询。	100

返回：

类型	描述
dict[str, Any]	包含特征身份、元数据、tables、每表 omitted_rows、 unavailable 类别和 evidence_status。 tables 保留原生 DataFrame 类型，不自动渲染，也不按成员特征复制规则指标。

引发：

类型	描述
ValueError	特征不存在或分页参数无效时抛出。

示例：

>>> report.get_feature("age")["tables"]

show_table

show_table(name: str, **query: Any) -> pd.DataFrame

查询并转换为 Pandas 表，缺少显示名时使用英文 ID。

参数：

名称	类型	描述	默认
name	str	describe()["tables"] 中的公共表名。	必需
**query	Any	传给 get_table 的筛选、排序、选列和分页参数，默认返回整表。 显式指定 columns 时只返回所列字段，不额外添加显示名列。	{}

返回：

类型	描述
DataFrame	独立 Pandas 表。已有显示名列中的空值回退为对应英文 ID，不修改统计值。

示例：

>>> restored.show_table("summary", limit=5)

write_html

write_html(
    path: str, *, report_name: str = "MARS Report Snapshot"
) -> None

将全部已保存统计与业务元数据导出为离线 HTML。

参数：

名称	类型	描述	默认
path	str	HTML 路径；父目录必须存在。	必需
report_name	str	报告标题，默认使用 "MARS Report Snapshot"。	'MARS Report Snapshot'

Notes

模型分交叉快照使用专用交互页面；其他快照使用通用表格页面。 导出不重新计算统计，也不恢复原报告的所有展示方法。

示例：

>>> restored.write_html("restored.html")

write_excel

write_excel(path: str) -> None

将所有公共表的当前值与业务元数据写入静态 Excel 工作簿。

参数：

名称	类型	描述	默认
path	str	Excel 路径；父目录必须存在。	必需

Notes

每张公共表对应一个工作表，统计值沿用快照语义。 不使用分箱报告的原生透视模板，也不依赖 Excel 刷新透视缓存。

示例：

>>> restored.write_excel("restored.xlsx")

get_matrix

get_matrix(
    features: list[str] | None = None,
) -> pd.DataFrame

从保存结果恢复所选特征的有符号相关子矩阵，不访问原始样本。

参数：

名称	类型	描述	默认
features	list[str] | None	英文候选 ID，决定矩阵行列及顺序；默认使用全部候选。 候选较多时宜显式限定范围。	None

返回：

类型	描述
DataFrame	按请求顺序排列的矩阵，不可用值为 NaN；对角线沿用保存的实际结果。

引发：

类型	描述
ValueError	重复或未知候选 ID。

示例：

>>> report.get_matrix(["income", "loan_count"])

get_related

get_related(
    feature: str,
    *,
    sources: str | list[str] | None = None,
    offset: int = 0,
    limit: int = 20
) -> pl.DataFrame

查询与中心特征相关的其他特征，按相关系数绝对值降序返回。

参数：

名称	类型	描述	默认
feature	str	原始候选 ID，不以中文名作为键。	必需
sources	str | list[str] | None	仅筛选另一端特征的业务来源，默认不限制；未知来源报错。	None
offset	int	排序后跳过的行数，默认 0，必须为非负整数。	0
limit	int	最大返回行数，默认 20；0 返回空表。相关系数绝对值相同时保留候选顺序。	20

返回：

类型	描述
DataFrame	有符号相关系数、另一端特征的业务元数据、最终入选状态和实际筛选事件。

引发：

类型	描述
ValueError	ID、来源或分页参数无效。

示例：

>>> report.get_related("income", limit=10)

show_matrix

show_matrix(
    features: list[str] | None = None,
    *,
    max_features: int = 30
) -> Any

用固定 [-1, 1] 色标展示相关矩阵，空值与有效零值分别着色。

参数：

名称	类型	描述	默认
features	list[str] | None	英文候选 ID 及展示顺序，默认使用全部候选的原顺序。	None
max_features	int	最多展示的特征数，默认 30，必须为正整数。 仅展示所选列表的前若干项，省略数量显示在表标题中，不截断快照。	30

返回：

类型	描述
Any	包含英文 ID、显示名和来源的 Pandas Styler，支持 Notebook 展示及 HTML/Excel 导出。

引发：

类型	描述
ValueError	上限或候选 ID 无效。

示例：

>>> report.show_matrix(max_features=20)

mars.reporting.get_correlation_matrix

get_correlation_matrix(
    report: Report, features: list[str] | None = None
) -> pd.DataFrame

从已保存的上三角与实际对角值恢复所选特征的相关子矩阵。

参数：

名称	类型	描述	默认
report	Report	原始相关性报告，或 load_report() 恢复的相关性快照；不访问原始样本。	必需
features	list[str] | None	进入相关性阶段的英文候选 ID，决定返回矩阵的行列及顺序。 默认使用全部候选；候选较多时宜显式限定范围。	None

返回：

类型	描述
DataFrame	按请求顺序排列的有符号相关矩阵，不可用值为 NaN。 对角线沿用已保存的实际结果，不补为 1。

引发：

类型	描述
ValueError	报告类型不符、候选 ID 重复或 ID 未进入相关性阶段时抛出。

示例：

>>> get_correlation_matrix(restored, ["income", "loan_count"])

mars.reporting.get_related_features

get_related_features(
    report: Report,
    feature: str,
    *,
    sources: str | list[str] | None = None,
    offset: int = 0,
    limit: int = 20
) -> pl.DataFrame

按相关系数绝对值降序返回其他特征及其筛选证据。

来源条件只筛选另一端特征，不限制中心特征；相关系数绝对值相同时保留候选顺序。

参数：

名称	类型	描述	默认
report	Report	report_type="correlation" 的原始报告或通用快照。	必需
feature	str	作为查询中心的英文候选 ID，必须已进入相关性阶段。	必需
sources	str | list[str] | None	另一端特征的业务来源，默认不限制；来源未知时报错。	None
offset	int	按相关系数绝对值排序后跳过的行数，默认 0，必须为非负整数。	0
limit	int	最大返回行数，默认 20，必须为非负整数；0 返回空表。	20

返回：

类型	描述
DataFrame	另一端特征的 ID、显示名、来源、有符号相关系数、最终入选状态及实际淘汰事件。 决策记录来自原筛选过程，不根据相关系数重新生成。

引发：

类型	描述
ValueError	报告类型、ID、来源或分页无效。

示例：

>>> get_related_features(restored, "income", limit=5)

mars.reporting.show_correlation_matrix

show_correlation_matrix(
    report: Report,
    features: list[str] | None = None,
    *,
    max_features: int = 30
) -> Any

展示指定数量特征的有符号相关矩阵，使用固定 [-1, 1] 色标。

空值单独着色，有效零值保留为 0，不重新计算相关系数。

参数：

名称	类型	描述	默认
report	Report	原始相关性报告或加载后的相关性快照。	必需
features	list[str] | None	展示候选的英文 ID 及顺序，默认使用全部候选的原顺序。	None
max_features	int	最多展示的特征数，默认 30，必须为正整数。 仅展示所选列表的前若干项，省略数量显示在表标题中，不截断原报告。	30

返回：

类型	描述
Any	可在 Notebook 中显示的 Pandas Styler，也可调用 to_html() 或 to_excel()。

引发：

类型	描述
ValueError	上限非正整数或矩阵查询无效。

示例：

>>> show_correlation_matrix(restored, ["income", "loan_count"])

模型分交叉报告

从 mars.analysis 导入 ScoreCrossReport，准确签名见 Analysis API。 如何导出报告、保存后回放规则，见模型分交叉指南。