跳转至

Rule API

Experimental

mars.rule 的 DSL、筛选策略、结果字段和 artifact 仍可能在 0.0.x 调整。不要从根 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

独立验证样本;不传时明确降级为样本内探索。

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

dayweekmonthyear

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 的可审计挖掘结果。

引发:

类型 描述
TypeError

spec、generators 或 seed_rules 未遵循类型化公开契约时抛出。

ValueError

production 缺少独立验证集或输入配置非法时抛出。

mars.rule.MarsRule dataclass

表示与样本评估结果无关的可部署规则。

参数:

名称 类型 描述 默认
expression str

Mars Rule DSL 表达式。

必需
source str

规则来源,例如 manualcombinationtree

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

生成资格状态所依据的验证摘要。

dict()

required_features property

required_features: Tuple[str, ...]

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

__post_init__

__post_init__() -> None

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

transform

transform(df: FrameLike) -> FrameLike

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

参数:

名称 类型 描述 默认
df FrameLike

待应用规则的数据集。

必需

返回:

类型 描述
DataFrame | DataFrame

与输入类型一致的命中结果表。

引发:

类型 描述
ValueError

输入缺少任一规则引用列时抛出。

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
minimum_qualification Literal['validated', 'temporally_validated'] | None

SQL 导出要求的最低部署资格;None 仅用于显式开发导出。

'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

固定长表中的指标列名。

必需
operator ('<', '<=', '==', '!=', '>=', '>')

比较运算符。

"<"
value float

比较阈值。

必需

__post_init__

__post_init__() -> None

校验指标条件。

mars.rule.MarsRuleFilter dataclass

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

参数:

名称 类型 描述 默认
conditions tuple[MarsRuleMetricCondition, ...]

单行评估结果必须同时满足的指标条件。

必需
targets "primary"、"all" 或目标列元组

参与筛选的目标范围。

'primary'
target_scope ('all', 'any')

多目标条件的聚合方式。

"all"
slice_pass_rate float | None

提供切片结果时要求通过的最小切片比例;None 表示只使用 overall。

None

__post_init__

__post_init__() -> None

校验聚合范围与通过率。

mars.rule.MarsRuleMiningSpec dataclass

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

参数:

名称 类型 描述 默认
profile ('explore', 'production')

探索模式保留点估计筛选;生产模式强制独立验证与统计门禁。

"explore"
direction ('high_risk', 'low_risk')

规则风险方向。

"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"
top_k int

最终最多保留的规则数。

10
max_candidates int

合并生成器后允许评估的候选上限。

100000
iou_threshold float

命中人群 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"
confidence_level float

production Wilson 单侧置信水平。

0.95
max_fdr float

production Benjamini-Hochberg 最大 q 值。

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 和 0.8 的低风险策略。

to_dict

to_dict() -> Dict[str, Any]

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

mars.rule.MarsRuleMiningResult dataclass

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

参数:

名称 类型 描述 默认
status ('success', 'no_rules')

最终业务状态;合法零入选使用 no_rules

"success"
rule_set MarsRuleSet

最终可部署规则定义。

必需
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,
) -> MarsRuleReport

构造不产生文件副作用的结构化报告。

参数:

名称 类型 描述 默认
analysis MarsRuleAnalysis | None

显式执行的高级分析;不传时省略相关 section。

None

返回:

类型 描述
MarsRuleReport

可进一步导出 HTML 或 Excel 的报告。

mars.rule.MarsRuleEvaluation dataclass

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

参数:

名称 类型 描述 默认
overall_table DataFrame

slice="__overall__" 的整体评估长表。

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

可选 top-k Lift bootstrap 区间;默认分析不会执行重采样。

DataFrame()
metadata Mapping[str, Any]

分析目标、字段配置、配对预算和样本量。

dict()

mars.rule.MarsRuleReport dataclass

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

参数:

名称 类型 描述 默认
summary_table DataFrame

挖掘状态、候选数量和验证状态汇总。

DataFrame()
detail_tables Mapping[str, DataFrame]

候选审计、评估、切片和可选高级分析表。

dict()
metadata Mapping[str, Any]

已解析策略、数据角色和运行版本。

dict()
caption str

Notebook 与文件报告标题。

'MARS Rule Mining Report'

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 不是支持的表或记录结构时抛出。

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

write_html

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

写出自包含 HTML 规则报告。

参数:

名称 类型 描述 默认
path Union[str, Path]

输出 HTML 路径;父目录会自动创建。

'mars_rule_report.html'

返回:

类型 描述
Path

实际写出的文件路径。

render_html

render_html() -> str

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

返回:

类型 描述
str

完整且对用户字段执行 HTML 转义的文档。

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 长表。每个目标只使用该目标非空且 可转换为二分类数值的样本,未定义比率保留为 null。

示例:

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

生成和主要筛选使用的二分类目标。

必需
aux_targets Sequence[str] | None

仅参与评估的辅助目标。

None
dataset str

写入长表的样本角色标签。

'evaluation'
group_col str | None

已存在的切片列。

None
time_col str | None

用于生成时间切片的日期列。

None
time_grain str | None

dayweekmonthyear;不传时保留原始日期文本。

None
amount_col str | None

金额指标列。

None
customer_col str | None

客户去重指标列。

None
batch_size int

单批物化和聚合的规则数量。

100
direction RuleDirection

精确检验使用的风险方向。

'high_risk'
confidence_level float

Wilson 单侧置信水平。

0.95
compute_statistics bool

是否计算 Wilson、精确检验和 BH-FDR;关闭时仍保留固定可空列。

False

返回:

类型 描述
MarsRuleEvaluation

整体表、切片表和运行元数据。

引发:

类型 描述
ValueError

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

mars.rule.MarsCombinationRuleGenerator

Bases: MarsRuleGenerator

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

参数:

名称 类型 描述 默认
n_bins int

每个特征的目标分位区间数。

5
max_cross_features int

单条组合规则最多包含的特征数。

2
max_candidates int

生成器候选上限。

100000
random_state int | None

宽表预筛抽样种子。

None
prefilter_single_rules bool

是否先按样本内 Lift 排序单规则,再生成交叉候选。

True
feature_prefilter_top_k int

宽表统计预筛最多保留的特征数。

300
feature_prefilter_min_features int

触发 :class:MarsStatsSelector 的数值特征数。

500
feature_prefilter_sample_size int

统计预筛最大样本数。

100000

引发:

类型 描述
ValueError

分箱、交叉、候选或特征预筛预算非法时抛出。

generate

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

生成分位点与交叉规则。

mars.rule.MarsTreeRuleGenerator

Bases: MarsRuleGenerator

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

每棵树使用确定性中位数填充值和显式缺失指示器训练;提取路径时将缺失分支还原为 IS MISSING,避免训练矩阵与部署命中语义漂移。

generate

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

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

mars.rule.MarsForestRuleGenerator

Bases: MarsRuleGenerator

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

generate

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

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

mars.rule.MarsGBDTRuleGenerator

Bases: MarsRuleGenerator

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

generate

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

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

mars.rule.MarsIsolationRuleGenerator

Bases: MarsRuleGenerator

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

generate

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

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