Rule API¶

Experimental

mars.rule 的 DSL、筛选策略、结果字段和 artifact 仍可能在 0.0.x 调整。请从 mars.rule 导入这些名称，根 mars 不提供这些导出。在受控流程中使用时，固定精确版本，并对 JSON 和 SQL 结果增加契约测试。

mars.rule.mine_rules ¶

mine_rules(
    train_df: FrameLike,
    *,
    target: str,
    validation_df: FrameLike | None = None,
    aux_targets: Sequence[str] | None = None,
    features: Sequence[str] | None = None,
    group_col: str | None = None,
    time_col: str | None = None,
    time_grain: str | None = None,
    amount_col: str | None = None,
    customer_col: str | None = None,
    seed_rules: (
        Sequence[Union[str, MarsRule]] | None
    ) = None,
    spec: MarsRuleMiningSpec | None = None,
    generators: Sequence[MarsRuleGenerator] | None = None
) -> MarsRuleMiningResult

生成、评估、筛选并组装可部署规则集。

参数：

名称	类型	描述	默认
`train_df`	`FrameLike`	候选生成和训练筛选样本。	必需
`target`	`str`	主二分类目标列。	必需
`validation_df`	`FrameLike \| None`	独立验证样本。explore 下省略时使用训练表做样本内筛选，并发出警告； production 下必须提供，否则报错。	`None`
`aux_targets`	`Sequence[str] \| None`	仅参与评估和类型化筛选的辅助目标。	`None`
`features`	`Sequence[str] \| None`	自动生成使用的数值特征；不传时排除所有数据角色列后推断。	`None`
`group_col`	`str \| None`	验证样本中已有的业务分组列；提供后优先于 `time_col`。	`None`
`time_col`	`str \| None`	未传 `group_col` 时，用于构造验证时间切片的日期列。	`None`
`time_grain`	`str \| None`	验证时间切片粒度，支持 `day`、`week`、`month` 和 `year`；不传时保留日期列的原始文本。	`None`
`amount_col`	`str \| None`	用于规则评估的金额列，默认不计算金额指标。	`None`
`customer_col`	`str \| None`	用于去重客户指标的客户标识列，默认不计算客户指标。	`None`
`seed_rules`	`Sequence[Union[str, MarsRule]] \| None`	用户提供的 DSL 规则候选。	`None`
`spec`	`MarsRuleMiningSpec \| None`	类型化挖掘策略；不传时使用默认高风险策略。	`None`
`generators`	`Sequence[MarsRuleGenerator] \| None`	自定义生成器；不传时使用组合规则和浅层树，空序列表示只评估 seed rules。	`None`

返回：

类型	描述
`MarsRuleMiningResult`	不保存原始 DataFrame 的挖掘结果，包含最终规则、完整候选审计、评估表和实际策略。没有合法入选规则时返回 `status="no_rules"` 与空 RuleSet。

引发：

类型	描述
`TypeError`	spec、generators 或 seed_rules 未遵循类型化公开契约时抛出。
`ValueError`	production 缺少独立验证集或输入配置非法时抛出。

mars.rule.MarsRule `dataclass` ¶

保存规则表达式、生成来源和稳定标识，不保存样本指标。

参数：

名称	类型	描述	默认
`expression`	`str`	Mars Rule DSL 表达式。构造时解析、校验并规范化，用规范文本生成 `rule_id`。	必需
`source`	`str`	候选生成来源，默认为 `manual`，也可为 `combination` 或 `tree`。该字段与特征元数据中的业务来源不同。	`'manual'`
`labels`	`tuple[str, ...]`	调用方附加的稳定标签。	`()`

属性：

名称	类型	描述
`rule_id`	`str`	由规范化表达式确定性生成的规则标识。
`complexity`	`int`	原子条件数量。
`required_features`	`tuple[str, ...]`	规则引用的输入列。

示例：

>>> rule = MarsRule("age <= 25 AND debt > 0.5")
>>> rule.rule_id.startswith("mr_")
True

__post_init__ ¶

__post_init__() -> None

规范化表达式并计算稳定派生字段。

mars.rule.MarsRuleSet `dataclass` ¶

保存有序规则定义、等级归属和部署资格。

参数：

名称	类型	描述	默认
`rules`	`Sequence[MarsRule]`	有序规则定义。	`tuple()`
`grades`	`Mapping[str, Sequence[str]]`	等级到规则 ID 的映射。	`dict()`
`metadata`	`Mapping[str, Any]`	不包含样本指标的 artifact 元数据。	`dict()`
`qualification`	`('exploratory', 'validated', 'temporally_validated')`	规则集部署资格；手工构造和 explore 结果默认为 `exploratory`。	`"exploratory"`
`validation_summary`	`Mapping[str, Any]`	资格状态所依据的验证摘要。具有验证资格时必须满足摘要契约；默认空摘要用于 exploratory 规则集。	`dict()`

required_features `property` ¶

required_features: Tuple[str, ...]

返回规则集引用的全部输入列。

__post_init__ ¶

__post_init__() -> None

冻结集合顺序并校验 ID、表达式和等级引用。

transform ¶

transform(df: FrameLike) -> FrameLike

追加逐规则、总命中数和等级命中数。

参数：

名称	类型	描述	默认
`df`	`FrameLike`	待应用规则的数据集。	必需

返回：

类型	描述
`DataFrame \| DataFrame`	保留输入列并追加命中列，返回类型与输入一致。 `rule__<rule_id>` 为 0/1 命中标记，`rule_hit_count` 为命中规则数， `grade__<等级>__hit_count` 为各等级命中数。空规则集的总命中数为 0。

引发：

类型	描述
`ValueError`	输入缺少任一规则引用列时抛出。规则与列类型不兼容时传播 schema 校验异常。

to_dict ¶

to_dict() -> Dict[str, Any]

返回严格、带版本的规则集 artifact。

from_dict `classmethod` ¶

from_dict(payload: Mapping[str, Any]) -> MarsRuleSet

从严格 artifact 恢复规则集。

参数：

名称	类型	描述	默认
`payload`	`Mapping[str, Any]`	由 :meth:`to_dict` 生成的规则集对象。	必需

返回：

类型	描述
`MarsRuleSet`	完成 ID 和引用校验的规则集。

引发：

类型	描述
`MarsRuleArtifactError`	artifact 类型、版本、规则条目、ID 或等级引用非法时抛出。

save_json ¶

save_json(path: Union[str, Path]) -> None

原子写出规则集 JSON。

参数：

名称	类型	描述	默认
`path`	`Union[str, Path]`	输出文件；父目录必须已经存在。	必需

引发：

类型	描述
`FileNotFoundError`	输出目录不存在时抛出。
`Exception`	临时文件写入、同步或原子替换失败时原样抛出。

load_json `classmethod` ¶

load_json(path: Union[str, Path]) -> MarsRuleSet

读取并严格校验规则集 JSON。

参数：

名称	类型	描述	默认
`path`	`Union[str, Path]`	Mars RuleSet artifact 文件。	必需

返回：

类型	描述
`MarsRuleSet`	恢复后的规则集。

引发：

类型	描述
`MarsRuleArtifactError`	JSON 语法、顶层结构或 artifact 契约非法时抛出。

generate_sql ¶

generate_sql(
    *,
    table_alias: str = "",
    include_grade_counts: bool = True,
    minimum_qualification: (
        Literal["validated", "temporally_validated"] | None
    ) = "validated",
    missing_policy: Literal[
        "reject", "normalized_to_null"
    ] = "reject"
) -> str

生成 ANSI SQL 命中列和汇总列片段。

参数：

名称	类型	描述	默认
`table_alias`	`str`	输入表别名；空字符串表示不添加前缀。	`''`
`include_grade_counts`	`bool`	是否生成各等级的命中计数列，默认为 `True`；逐规则和总命中列始终生成。	`True`
`minimum_qualification`	`Literal['validated', 'temporally_validated'] \| None`	SQL 导出的最低部署资格，默认要求 `validated`； `None` 允许显式开发导出，`temporally_validated` 要求时间验证资格。	`'validated'`
`missing_policy`	`Literal['reject', 'normalized_to_null']`	`IS MISSING` 的 ANSI SQL 策略；默认拒绝，声明上游已完成 NaN 到 NULL 规范化后才允许映射。	`'reject'`

返回：

类型	描述
`str`	可嵌入 `SELECT` 的逗号分隔 SQL 片段。

引发：

类型	描述
`MarsRuleDeploymentError`	资格不足、策略非法或 MISSING 无法安全导出时抛出。

mars.rule.MarsRuleMetricCondition `dataclass` ¶

定义单个规则评估指标条件。

参数：

名称	类型	描述	默认
`metric`	`str`	评估长表中支持的指标列名，例如 `lift`、`event_count` 或 `coverage`。	必需
`operator`	`('<', '<=', '==', '!=', '>=', '>')`	比较运算符。	`"<"`
`value`	`float`	比较阈值，单位与指标一致。coverage 和事件率使用小数比例，Lift 无量纲。	必需

__post_init__ ¶

__post_init__() -> None

校验指标条件。

mars.rule.MarsRuleFilter `dataclass` ¶

定义规则筛选阈值与跨目标、切片通过策略。

参数：

名称	类型	描述	默认
`conditions`	`tuple[MarsRuleMetricCondition, ...]`	规则命中行必须同时满足的指标条件；所需指标为 null 时不通过。	必需
`targets`	`"primary"、"all" 或目标列元组`	参与筛选的目标范围。默认 `"primary"` 只检查主目标； `"all"` 检查全部评估目标，目标列元组则只检查指定目标。	`'primary'`
`target_scope`	`('all', 'any')`	多目标结果的通过方式。默认 `"all"` 要求每个目标都通过， `"any"` 要求至少一个目标通过。	`"all"`
`slice_pass_rate`	`float \| None`	整体通过后，切片还需满足的最小通过比例。默认 `None` 只检查 overall；指定比例且存在切片表时，每个目标分别计算切片通过率。	`None`

__post_init__ ¶

__post_init__() -> None

校验聚合范围与通过率。

mars.rule.MarsRuleMiningSpec `dataclass` ¶

规则挖掘的可复用、可序列化策略。

参数：

名称	类型	描述	默认
`profile`	`('explore', 'production')`	默认 `"explore"` 按点估计筛选，结果资格保持 exploratory； `"production"` 要求独立验证，并强制检查置信界、FDR 和适用的时间条件。	`"explore"`
`direction`	`('high_risk', 'low_risk')`	默认 `"high_risk"` 寻找高事件率人群；`"low_risk"` 寻找低事件率人群。方向决定排序和统计检验尾部；筛选阈值由两个 filter 单独控制。	`"high_risk"`
`candidate_filter`	`MarsRuleFilter`	训练集候选筛选规则。	`_high_candidate_filter()`
`validation_filter`	`MarsRuleFilter`	验证集最终筛选规则。	`_high_validation_filter()`
`grade_filters`	`Mapping[str, MarsRuleFilter]`	规则等级到筛选条件的映射。	`dict()`
`selection_strategy`	`('ranked', 'cascade')`	默认 `"ranked"` 在完整样本上评估、排序并去重； `"cascade"` 每轮在剩余人群中重新生成和筛选，已选规则以 OR 累积覆盖。	`"ranked"`
`top_k`	`int`	最终最多保留的规则数。	`10`
`max_candidates`	`int`	合并生成器后允许评估的候选上限。	`100000`
`iou_threshold`	`float`	规则命中集合的交并比阈值，默认为 0.3。候选与更高优先级规则的 IoU 大于等于该值时被剔除。	`0.3`
`batch_size`	`int`	规则批量评估大小。	`100`
`iou_batch_size`	`int`	IoU 掩码处理批次大小。	`512`
`max_rounds`	`int`	cascade 最多轮数。	`10`
`random_state`	`int`	默认生成器随机种子。	`42`
`on_generator_error`	`('raise', 'record')`	默认 `"raise"` 立即抛出生成器异常；`"record"` 记录错误后继续处理其他来源。	`"raise"`
`confidence_level`	`float`	Wilson 单侧置信水平，默认为 0.95。production 使用相应的 Lift 置信界检查筛选条件；高级分析中的 bootstrap 使用单独的双侧区间。	`0.95`
`max_fdr`	`float`	production 允许的最大 BH q 值，默认为 0.05；按相同 dataset、target 和 slice 内的候选检验校正。	`0.05`
`min_time_slices`	`int`	获得时间验证资格所需的最少有效切片数。	`3`

__post_init__ ¶

__post_init__() -> None

校验挖掘预算和策略。

explore `classmethod` ¶

explore(**overrides: Any) -> MarsRuleMiningSpec

构造允许 in-sample 结果的探索策略。

参数：

名称	类型	描述	默认
`**overrides`	`Any`	覆盖默认 dataclass 字段的显式配置。	`{}`

返回：

类型	描述
`MarsRuleMiningSpec`	`profile='explore'` 的挖掘策略。

production `classmethod` ¶

production(**overrides: Any) -> MarsRuleMiningSpec

构造强制独立验证和统计门禁的生产策略。

参数：

名称	类型	描述	默认
`**overrides`	`Any`	覆盖默认 dataclass 字段的显式配置。	`{}`

返回：

类型	描述
`MarsRuleMiningSpec`	`profile='production'` 的挖掘策略。

low_risk `classmethod` ¶

low_risk(**overrides: Any) -> MarsRuleMiningSpec

构造默认低风险挖掘策略。

参数：

名称	类型	描述	默认
`**overrides`	`Any`	覆盖默认 dataclass 字段的显式配置。	`{}`

返回：

类型	描述
`MarsRuleMiningSpec`	训练候选 Lift 上限为 0.9、验证 Lift 上限为 0.8 的低风险策略。

to_dict ¶

to_dict() -> Dict[str, Any]

返回可 JSON 序列化的完整策略。

mars.rule.MarsRuleMiningResult `dataclass` ¶

规则挖掘的可审计结构化结果。

参数：

名称	类型	描述	默认
`status`	`('success', 'no_rules')`	最终业务状态。没有规则通过筛选时为 `no_rules`，仍保留淘汰审计；数据、DSL 和计算异常会继续抛出。	`"success"`
`rule_set`	`MarsRuleSet`	最终规则定义与资格；能否导出部署 SQL 还取决于资格和缺失值策略。	必需
`candidate_table`	`DataFrame`	候选来源、淘汰阶段和原因审计表。	必需
`evaluation`	`MarsRuleEvaluation`	训练与验证整体、切片长表。	必需
`spec`	`MarsRuleMiningSpec`	完整解析后的挖掘策略。	必需
`metadata`	`Mapping[str, Any]`	数据角色、验证状态、版本和阶段耗时。	`dict()`

analyze ¶

analyze(
    df: FrameLike,
    *,
    target: str | None = None,
    amount_col: str | None = None,
    customer_col: str | None = None,
    max_pairs: int = 5000,
    bootstrap_repeats: int = 0,
    confidence_level: float | None = None,
    random_state: int | None = None
) -> MarsRuleAnalysis

按需计算最终规则的交互和累计贡献。

参数：

名称	类型	描述	默认
`df`	`FrameLike`	分析样本；结果对象不会保存该数据。	必需
`target`	`str \| None`	分析目标；不传时使用挖掘主目标。	`None`
`amount_col`	`str \| None`	金额列；不传时沿用挖掘阶段配置。	`None`
`customer_col`	`str \| None`	客户列；不传时沿用挖掘阶段配置。	`None`
`max_pairs`	`int`	交互分析最大规则对数。	`5000`
`bootstrap_repeats`	`int`	最终规则 Lift 重采样次数；默认关闭。	`0`
`confidence_level`	`float \| None`	bootstrap 区间置信水平；不传时沿用挖掘 spec。	`None`
`random_state`	`int \| None`	bootstrap 种子；不传时沿用挖掘 spec。	`None`

返回：

类型	描述
`MarsRuleAnalysis`	交互、累计表和分析元数据。

to_report ¶

to_report(
    analysis: MarsRuleAnalysis | None = None,
    *,
    feature_metadata: FeatureMetadata | None = None,
    business_context: dict[str, Any] | None = None
) -> MarsRuleReport

将已有挖掘结果整理为结构化报告。

参数：

名称	类型	描述	默认
`analysis`	`MarsRuleAnalysis \| None`	已显式计算的高级分析结果；默认不添加交互、累计和 bootstrap 表，并在 `analysis_states` 中记录未计算状态。	`None`
`feature_metadata`	`FeatureMetadata \| None`	英文特征 ID 对应的中文名、业务来源、定义和单位。	`None`
`business_context`	`dict[str, Any] \| None`	标签、样本、币种及发现证据说明；不改变实际计算参数。	`None`

返回：

类型	描述
`MarsRuleReport`	满足公共 Report 契约，可查询、保存及导出 HTML 或 Excel 的报告。本方法只整理已有结果，不重新挖掘、验证或自动执行高级分析。

示例：

>>> report = result.to_report(feature_metadata={"income": {"data_source": "application"}})

mars.rule.MarsRuleEvaluation `dataclass` ¶

保存一次规则评估的固定长表。

参数：

名称	类型	描述	默认
`overall_table`	`DataFrame`	整体评估长表，`slice="__overall__"`；每条规则、每个目标分别保存 hit、miss 和 total 行。	`DataFrame()`
`slice_table`	`DataFrame`	按业务分组或时间切片展开的同结构长表；未请求切片时为空。	`DataFrame()`
`metadata`	`Mapping[str, Any]`	数据集角色、目标和列配置等运行元数据。	`dict()`

mars.rule.MarsRuleAnalysis `dataclass` ¶

保存按需执行的规则高级分析结果。

参数：

名称	类型	描述	默认
`interaction_table`	`DataFrame`	两两命中重叠和组合风险表，按需包含金额与客户指标。	`DataFrame()`
`cumulative_table`	`DataFrame`	按 RuleSet 顺序累计覆盖与边际贡献表，按需包含金额与客户指标。	`DataFrame()`
`bootstrap_table`	`DataFrame`	最终规则的 Lift bootstrap 分位数区间；默认不执行重采样，表为空。	`DataFrame()`
`metadata`	`Mapping[str, Any]`	分析目标、字段配置、配对预算和样本量。	`dict()`

mars.rule.MarsRuleReport ¶

Bases: _ReportQuery

规则挖掘的结构化报告与显式导出器。

参数：

名称	类型	描述	默认
`summary_table`	`DataFrame \| None`	挖掘状态、候选数量和验证状态汇总。	`None`
`detail_tables`	`Mapping[str, DataFrame] \| None`	候选审计、评估、切片和可选高级分析表。	`None`
`metadata`	`Mapping[str, Any] \| None`	已解析策略、数据角色和运行版本。	`None`
`caption`	`str`	Notebook 与文件报告标题。	`'MARS Rule Mining Report'`
`feature_metadata`	`FeatureMetadata \| None`	英文特征 ID 对应的业务名、来源、定义和单位。	`None`
`business_context`	`dict[str, Any] \| None`	标签定义、样本范围、币种及证据来源；缺失解释保持 unknown。	`None`

属性：

名称	类型	描述
`report_id`	`str`	构造时生成的报告标识，查询、保存和恢复时保持不变。
`report_type`	`str`	`rule` 或 `rule_benchmark`；后者不包含规则部署资格。
`format_version`	`int`	公共 `.marsreport` 格式版本，目前为 1。

Notes

Rule 仍为 Experimental。报告只保存已有证据，不重建 RuleSet 或赋予部署权限。业务元数据、上下文或规则表达式校验失败时抛出 ValueError。特征查询依据规则成员关系筛选原统计表，每条统计行只返回一次。 features 和 sources 条件必须同时满足，但可以匹配同一规则的不同特征。 sources 指特征元数据中的业务来源；候选生成来源保存在规则表和候选表中。

示例：

>>> report = MarsRuleReport()
>>> report.describe()["report_type"]
'rule'

describe ¶

describe() -> dict[str, Any]

取得包含规则关联、单位和状态的公共目录。

返回：

类型	描述
`dict[str, Any]`	独立目录副本，包含各表的统计粒度、单位、状态和特征关联方式。未执行分析保持 `not_computed`，已执行但没有结果保持 `computed_empty`。

示例：

>>> MarsRuleReport().describe()["format_version"]
1

show_table ¶

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

查询报告表，并处理已有显示名列的空值。

参数：

名称	类型	描述	默认
`name`	`str`	公共表名。	必需
`**query`	`Any`	传给 `get_table` 的筛选、排序、选列和分页参数。显式指定 `columns` 时，仅返回所选字段。	`{}`

返回：

类型	描述
`DataFrame`	独立 Pandas 表。已有显示名列的空值会回退为英文 ID；不额外添加身份列或显示名列。

示例：

>>> report.show_table("candidates", limit=5)

from_benchmark `classmethod` ¶

from_benchmark(
    benchmark: Union[
        FrameLike,
        Mapping[str, Any],
        Sequence[Mapping[str, Any]],
    ],
    *,
    caption: str = "MARS Rule Benchmark Report"
) -> MarsRuleReport

从 benchmark 记录构造可导出的结构化报告。

参数：

名称	类型	描述	默认
`benchmark`	`Union[FrameLike, Mapping[str, Any], Sequence[Mapping[str, Any]]]`	单条记录、记录序列或 Pandas/Polars 表。	必需
`caption`	`str`	报告标题。	`'MARS Rule Benchmark Report'`

返回：

类型	描述
`MarsRuleReport`	包含 benchmark 明细和行数汇总的报告。

引发：

类型	描述
`TypeError`	benchmark 不是支持的表或记录结构时抛出。

示例：

>>> MarsRuleReport.from_benchmark({"seconds": 1.25}).report_type
'rule_benchmark'

write_excel ¶

write_excel(
    path: Union[str, Path] = "mars_rule_report.xlsx",
    *,
    engine: str | None = None
) -> None

把报告写入多工作表 Excel。

参数：

名称	类型	描述	默认
`path`	`Union[str, Path]`	输出工作簿路径；父目录会自动创建。	`'mars_rule_report.xlsx'`
`engine`	`str \| None`	可选 Pandas ExcelWriter 引擎。	`None`

示例：

>>> report.write_excel("rules.xlsx")

write_html ¶

write_html(
    path: Union[str, Path] = "mars_rule_report.html",
) -> Path

写出自包含 HTML 规则报告。

参数：

名称	类型	描述	默认
`path`	`Union[str, Path]`	输出 HTML 路径；父目录会自动创建。	`'mars_rule_report.html'`

返回：

类型	描述
`Path`	实际写出的文件路径。

示例：

>>> report.write_html("rules.html")

render_html ¶

render_html() -> str

渲染不落盘的自包含 HTML 字符串。

返回：

类型	描述
`str`	自包含 HTML 文档，用户字段经过 HTML 转义。candidates 只预览前 100 行，并显示总数和完整查询入口；Excel 与 `.marsreport` 保存完整表。

示例：

>>> MarsRuleReport().render_html().startswith("<!doctype html>")
True

mars.rule.MarsRuleGenerator ¶

Bases: ABC

规则候选生成器抽象接口。

子类只负责从训练数据生成不含样本指标的 :class:MarsRule。最终方向、筛选和去重由 :func:mars.rule.mine_rules 统一完成。

generate `abstractmethod` ¶

generate(
    df: FrameLike,
    *,
    target: str,
    features: Sequence[str] | None = None
) -> List[MarsRule]

生成规则候选。

参数：

名称	类型	描述	默认
`df`	`FrameLike`	训练样本。	必需
`target`	`str`	主二分类目标。	必需
`features`	`Sequence[str] \| None`	显式候选特征；不传时由生成器推断数值特征。	`None`

返回：

类型	描述
`list[MarsRule]`	已规范化并精确去重的候选规则。

mars.rule.MarsRuleEvaluator ¶

评估规则命中的样本、金额和客户指标。

接受 Pandas 或 Polars 表，返回固定结构的 Polars 长表。每个目标分别校验标签， sample_count、事件率和 Lift 只使用该目标已表现样本；total_count 和分布覆盖率保留全部样本。未定义比率为 null。全未表现切片仍保留分布人数，状态为 "unobserved"，监督指标为空。

示例：

>>> import polars as pl
>>> from mars.rule import MarsRule, MarsRuleEvaluator, MarsRuleSet
>>> frame = pl.DataFrame({"age": [20, 40], "y": [1, 0]})
>>> rules = MarsRuleSet([MarsRule("age < 30")])
>>> result = MarsRuleEvaluator().evaluate(frame, rules, target="y")
>>> result.overall_table.filter(pl.col("group") == "hit")["event_count"][0]
1

evaluate ¶

evaluate(
    df: FrameLike,
    rule_set: MarsRuleSet,
    *,
    target: str,
    aux_targets: Sequence[str] | None = None,
    dataset: str = "evaluation",
    group_col: str | None = None,
    time_col: str | None = None,
    time_grain: str | None = None,
    amount_col: str | None = None,
    customer_col: str | None = None,
    batch_size: int = 100,
    direction: RuleDirection = "high_risk",
    confidence_level: float = 0.95,
    compute_statistics: bool = False
) -> MarsRuleEvaluation

评估规则整体与切片指标。

参数：

名称	类型	描述	默认
`df`	`FrameLike`	待评估样本。	必需
`rule_set`	`MarsRuleSet`	不含样本指标的规则定义。	必需
`target`	`str`	主二分类目标列，用于评估并写入 `primary_target` 元数据。	必需
`aux_targets`	`Sequence[str] \| None`	额外评估的目标列；每个目标独立排除自己的 null、NaN 标签，默认不添加。	`None`
`dataset`	`str`	写入长表 `dataset` 的样本角色，默认为 `"evaluation"`；不改变计算样本。	`'evaluation'`
`group_col`	`str \| None`	已存在的业务分组列。提供后按该列切片，优先于 `time_col`。	`None`
`time_col`	`str \| None`	未传 `group_col` 时，用于生成时间切片的日期列；两者都省略时只计算整体。	`None`
`time_grain`	`str \| None`	`day`、`week`、`month` 或 `year`；不传时保留原始日期文本。	`None`
`amount_col`	`str \| None`	金额列。提供后计算已表现样本中的金额覆盖、事件金额占比和金额 Lift；省略时相关指标保持 null。	`None`
`customer_col`	`str \| None`	客户标识列。提供后计算已表现样本中的去重客户指标；省略时相关指标保持 null。	`None`
`batch_size`	`int`	单批物化和聚合的规则数量。	`100`
`direction`	`RuleDirection`	单侧超几何检验的方向，默认为 `"high_risk"`； `"low_risk"` 使用低事件率尾部。仅统计计算开启时影响检验值。	`'high_risk'`
`confidence_level`	`float`	Wilson 单侧置信水平。	`0.95`
`compute_statistics`	`bool`	是否增加 Wilson 单侧置信界、超几何检验 p 值和 BH q 值，默认关闭。关闭时保留这些列并填 null；开启时在相同 dataset、target、slice 内校正。	`False`

返回：

类型	描述
`MarsRuleEvaluation`	整体表、切片表和运行元数据。每行由 dataset、rule_id、target、slice 和 group 标识；coverage 的分母为相同 dataset、target、slice 的已表现人数。

引发：

类型	描述
`ValueError`	缺列、目标非二分类、时间粒度非法或规则引用缺失时抛出。

mars.rule.MarsCombinationRuleGenerator ¶

Bases: MarsRuleGenerator

使用分位点生成单变量和受控交叉规则。

参数：

名称	类型	描述	默认
`n_bins`	`int`	数值特征的目标分位区间数，默认为 5；重复分位点去重后可能减少。	`5`
`max_cross_features`	`int`	单条组合规则最多引用的特征数，默认为 2。两特征生成 AND、OR 组合，三个及以上特征只生成 AND 组合。	`2`
`max_candidates`	`int`	本生成器最多返回的候选数，默认为 100,000；工作流还会应用合并后的总预算。	`100000`
`random_state`	`int \| None`	宽表预筛抽样种子。	`None`
`prefilter_single_rules`	`bool`	是否先按样本内 Lift 排序单变量规则，默认开启。开启后最多使用 `max(8, isqrt(max_candidates))` 条单变量规则生成交叉候选。	`True`
`feature_prefilter_top_k`	`int`	宽表统计预筛最多保留的特征数。	`300`
`feature_prefilter_min_features`	`int`	触发 :class:`MarsStatsSelector` 预筛的数值特征数，默认为 500；少于该值时直接生成分位点规则。	`500`
`feature_prefilter_sample_size`	`int`	统计预筛最大样本数。	`100000`

引发：

类型	描述
`ValueError`	分箱、交叉、候选或特征预筛预算非法时抛出。

generate ¶

generate(
    df: FrameLike,
    *,
    target: str,
    features: Sequence[str] | None = None
) -> List[MarsRule]

生成分位点与交叉规则。

参数：

名称	类型	描述	默认
`df`	`FrameLike`	用于生成候选的训练表；规则结果不保存原始数据。	必需
`target`	`str`	目标列名。默认推断候选特征时排除该列；显式传入 `features` 时由调用方排除。	必需
`features`	`Sequence[str] \| None`	候选特征范围；默认推断除目标列外的数值特征，显式范围也只保留数值列。	`None`

返回：

类型	描述
`list[MarsRule]`	返回受候选预算限制的分位点规则和交叉规则。

mars.rule.MarsTreeRuleGenerator ¶

Bases: MarsRuleGenerator

从多棵随机浅层决策树提取叶子路径。

每棵树使用确定性中位数填充值和显式缺失指示器训练；提取路径时将缺失分支还原为 IS MISSING，使训练和后续执行的缺失命中保持一致。

参数：

名称	类型	描述	默认
`n_trees`	`int`	训练的浅层树数量，默认为 15。	`15`
`max_depths`	`Sequence[int] \| None`	每棵树随机选择的最大深度集合；默认使用 `(2, 3, 4)`。	`None`
`feature_fraction`	`float`	每棵树抽取的原始特征比例，默认为 0.8，至少抽取一个特征。	`0.8`
`n_jobs`	`int`	joblib 并行拟合任务数，默认为 `-1`，按 joblib 约定使用可用核心。	`-1`
`random_state`	`int \| None`	特征抽样、深度选择和树种子的随机种子；默认不固定。	`None`
`dt_params`	`Dict[str, Any] \| None`	传给 `DecisionTreeClassifier` 的参数，默认空字典。显式参数优先于生成器补充的默认值；启用 Optuna 后，调优结果会改写深度和叶子样本量。	`None`
`tuning_backend`	`Literal['none', 'optuna']`	是否在各树内部调参，默认 `"none"`；`"optuna"` 使用分层 CV ROC AUC。	`'none'`
`tuning_trials`	`int`	启用 Optuna 后每棵树的试验次数，默认为 10。	`10`

引发：

类型	描述
`ValueError`	树数量或调参次数小于 1、特征比例不在 (0, 1] 内、深度包含非正值，或调参后端不受支持时抛出。

generate ¶

generate(
    df: FrameLike,
    *,
    target: str,
    features: Sequence[str] | None = None
) -> List[MarsRule]

训练浅层树并提取可部署路径规则。

参数：

名称	类型	描述	默认
`df`	`FrameLike`	用于生成候选的训练表；规则结果不保存原始数据。	必需
`target`	`str`	目标列名。默认推断候选特征时排除该列；显式传入 `features` 时由调用方排除。	必需
`features`	`Sequence[str] \| None`	候选特征范围；默认推断除目标列外的数值特征，显式范围也只保留数值列。	`None`

返回：

类型	描述
`list[MarsRule]`	返回多棵浅层树的去重路径规则，并补充显式缺失规则。没有数值特征时返回空列表；样本不足或目标不足两类时只返回缺失规则。

mars.rule.MarsForestRuleGenerator ¶

Bases: MarsRuleGenerator

从随机森林叶子路径提取候选规则。

参数：

名称	类型	描述	默认
`n_estimators`	`int`	森林中的树数量，默认为 50。	`50`
`max_depth`	`int`	每棵树的最大深度，默认为 3。	`3`
`feature_fraction`	`float`	每次分裂可考虑的模型矩阵特征比例，默认为 0.8。	`0.8`
`min_samples_leaf`	`NumericLeafSize`	叶子的最小样本量，默认 0.01。整数表示人数，浮点数表示训练样本比例。	`0.01`
`random_state`	`int \| None`	随机森林种子；默认不固定。	`None`
`n_jobs`	`int`	sklearn 并行任务数，默认为 `-1`，使用全部可用核心。	`-1`

generate ¶

generate(
    df: FrameLike,
    *,
    target: str,
    features: Sequence[str] | None = None
) -> List[MarsRule]

训练随机森林并提取全部叶子路径。

参数：

名称	类型	描述	默认
`df`	`FrameLike`	用于生成候选的训练表；规则结果不保存原始数据。	必需
`target`	`str`	目标列名。默认推断候选特征时排除该列；显式传入 `features` 时由调用方排除。	必需
`features`	`Sequence[str] \| None`	候选特征范围；默认推断除目标列外的数值特征，显式范围也只保留数值列。	`None`

返回：

类型	描述
`list[MarsRule]`	返回森林叶子路径和显式缺失规则，按规范表达式去重。没有候选特征、样本不足或目标不足两类时返回空列表。

mars.rule.MarsGBDTRuleGenerator ¶

Bases: MarsRuleGenerator

从 sklearn 或 LightGBM GBDT 弱学习器提取规则路径。

参数：

名称	类型	描述	默认
`backend`	`Literal['sklearn', 'lightgbm']`	模型后端，默认为 `"sklearn"`；LightGBM 在使用时延迟导入。	`'sklearn'`
`n_estimators`	`int`	弱学习器数量，默认为 80。	`80`
`max_depth`	`int`	每棵树的最大深度，默认为 3。	`3`
`learning_rate`	`float`	弱学习器的学习率，默认为 0.05。	`0.05`
`feature_fraction`	`float`	特征采样比例，默认为 0.8。sklearn 使用 `max_features`， LightGBM 使用同名参数。	`0.8`
`min_samples_leaf`	`NumericLeafSize`	叶子的最小样本量，默认 0.01。整数表示人数，浮点数表示训练样本比例。 LightGBM 将比例换算为至少一个样本的 `min_child_samples`。	`0.01`
`random_state`	`int \| None`	模型随机种子；默认不固定。	`None`
`n_jobs`	`int`	LightGBM 的并行任务数，默认为 `-1`；sklearn 后端不使用该参数。	`-1`
`model_params`	`Dict[str, Any] \| None`	额外模型参数，默认空字典。sklearn 后端允许覆盖 `max_features`，其他参数应避开构造时明确传入的同名项；LightGBM 后端以生成器配置为准。	`None`

引发：

类型	描述
`ValueError`	模型后端不受支持，或树数量、最大深度、特征比例、叶子样本量、学习率不满足要求时抛出。

generate ¶

generate(
    df: FrameLike,
    *,
    target: str,
    features: Sequence[str] | None = None
) -> List[MarsRule]

训练指定 GBDT 后端并提取路径规则。

参数：

名称	类型	描述	默认
`df`	`FrameLike`	用于生成候选的训练表；规则结果不保存原始数据。	必需
`target`	`str`	目标列名。默认推断候选特征时排除该列；显式传入 `features` 时由调用方排除。	必需
`features`	`Sequence[str] \| None`	候选特征范围；默认推断除目标列外的数值特征，显式范围也只保留数值列。	`None`

返回：

类型	描述
`list[MarsRule]`	返回指定 GBDT 后端的路径规则和显式缺失规则，按规范表达式去重。没有候选特征、样本不足或目标不足两类时返回空列表。

mars.rule.MarsIsolationRuleGenerator ¶

Bases: MarsRuleGenerator

从孤立森林异常路径生成无监督候选规则。

模型不使用目标值拟合，但训练矩阵仍只保留目标转为数值后非空且非 NaN 的行。候选的业务风险方向和最终资格由挖掘工作流评估。

参数：

名称	类型	描述	默认
`n_estimators`	`int`	孤立树数量，默认为 100。	`100`
`max_samples`	`Union[int, float, Literal['auto']]`	每棵树使用的样本数或比例，传给 sklearn；默认 `"auto"`。	`'auto'`
`feature_fraction`	`float`	每棵树抽取的模型矩阵特征比例，默认为 0.8。	`0.8`
`contamination`	`Union[float, Literal['auto']]`	sklearn 的异常比例参数，默认 `"auto"`。候选筛选使用的异常标记由 `anomaly_quantile` 单独确定。	`'auto'`
`path_depth_limit`	`int`	提取路径时允许的最大深度，默认为 4；更深的叶子路径不生成候选。	`4`
`min_leaf_samples`	`int`	叶子命中人数下限，默认为 50。	`50`
`anomaly_quantile`	`float`	异常分数的分位阈值，默认为 0.95；达到阈值的行标记为异常。仅保留异常人数大于 0、且异常比例不低于全体异常比例的叶子。	`0.95`
`max_candidates`	`int`	去重后最多返回的候选数，默认为 5,000，包含显式缺失规则。	`5000`
`random_state`	`int \| None`	模型随机种子；默认不固定。	`None`
`n_jobs`	`int`	sklearn 并行任务数，默认为 `-1`，使用全部可用核心。	`-1`
`model_params`	`Dict[str, Any] \| None`	传给 `IsolationForest` 的额外参数，默认空字典。不应与生成器明确传入的模型参数重复。	`None`

引发：

类型	描述
`ValueError`	树数量、路径深度、叶子人数或候选预算小于 1，特征比例不在 (0, 1] 内，或异常分位阈值不在 (0, 1) 内时抛出。

generate ¶

generate(
    df: FrameLike,
    *,
    target: str,
    features: Sequence[str] | None = None
) -> List[MarsRule]

训练孤立森林并提取受深度和预算约束的路径。

参数：

名称	类型	描述	默认
`df`	`FrameLike`	用于生成候选的训练表；规则结果不保存原始数据。	必需
`target`	`str`	目标列名。默认推断候选特征时排除该列；显式传入 `features` 时由调用方排除。	必需
`features`	`Sequence[str] \| None`	候选特征范围；默认推断除目标列外的数值特征，显式范围也只保留数值列。	`None`

返回：

类型	描述
`list[MarsRule]`	返回满足路径深度、叶子样本数和异常比例条件的叶子路径规则，并补充显式缺失规则。合并去重后按 `max_candidates` 截断。没有候选特征或样本不足时返回空列表。

Rule API¶

mars.rule.mine_rules ¶

mars.rule.MarsRule dataclass ¶

__post_init__ ¶

mars.rule.MarsRuleSet dataclass ¶

required_features property ¶

__post_init__ ¶

transform ¶

to_dict ¶

from_dict classmethod ¶

save_json ¶

load_json classmethod ¶

generate_sql ¶

mars.rule.MarsRuleMetricCondition dataclass ¶

__post_init__ ¶

mars.rule.MarsRuleFilter dataclass ¶

__post_init__ ¶

mars.rule.MarsRuleMiningSpec dataclass ¶

__post_init__ ¶

explore classmethod ¶

production classmethod ¶

low_risk classmethod ¶

to_dict ¶

mars.rule.MarsRuleMiningResult dataclass ¶

analyze ¶

to_report ¶

mars.rule.MarsRuleEvaluation dataclass ¶

mars.rule.MarsRuleAnalysis dataclass ¶

mars.rule.MarsRuleReport ¶

describe ¶

show_table ¶

from_benchmark classmethod ¶

write_excel ¶

write_html ¶

render_html ¶

mars.rule.MarsRuleGenerator ¶

generate abstractmethod ¶

mars.rule.MarsRuleEvaluator ¶

evaluate ¶

mars.rule.MarsCombinationRuleGenerator ¶

generate ¶

mars.rule.MarsTreeRuleGenerator ¶

generate ¶

mars.rule.MarsForestRuleGenerator ¶

generate ¶

mars.rule.MarsGBDTRuleGenerator ¶

generate ¶

mars.rule.MarsIsolationRuleGenerator ¶

generate ¶

mars.rule.MarsRule `dataclass` ¶

mars.rule.MarsRuleSet `dataclass` ¶

required_features `property` ¶

from_dict `classmethod` ¶

load_json `classmethod` ¶

mars.rule.MarsRuleMetricCondition `dataclass` ¶

mars.rule.MarsRuleFilter `dataclass` ¶

mars.rule.MarsRuleMiningSpec `dataclass` ¶

explore `classmethod` ¶

production `classmethod` ¶

low_risk `classmethod` ¶

mars.rule.MarsRuleMiningResult `dataclass` ¶

mars.rule.MarsRuleEvaluation `dataclass` ¶

mars.rule.MarsRuleAnalysis `dataclass` ¶

from_benchmark `classmethod` ¶

generate `abstractmethod` ¶