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
|
|
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
|
规则来源,例如 |
'manual'
|
labels
|
tuple[str, ...]
|
调用方附加的稳定标签。 |
()
|
属性:
| 名称 | 类型 | 描述 |
|---|---|---|
rule_id |
str
|
由规范化表达式确定性生成的规则标识。 |
complexity |
int
|
原子条件数量。 |
required_features |
tuple[str, ...]
|
规则引用的输入列。 |
示例:
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"
|
validation_summary
|
Mapping[str, Any]
|
生成资格状态所依据的验证摘要。 |
dict()
|
transform ¶
追加逐规则、总命中数和等级命中数。
参数:
| 名称 | 类型 | 描述 | 默认 |
|---|---|---|---|
df
|
FrameLike
|
待应用规则的数据集。 |
必需 |
返回:
| 类型 | 描述 |
|---|---|
DataFrame | DataFrame
|
与输入类型一致的命中结果表。 |
引发:
| 类型 | 描述 |
|---|---|
ValueError
|
输入缺少任一规则引用列时抛出。 |
from_dict
classmethod
¶
从严格 artifact 恢复规则集。
参数:
| 名称 | 类型 | 描述 | 默认 |
|---|---|---|---|
payload
|
Mapping[str, Any]
|
由 :meth: |
必需 |
返回:
| 类型 | 描述 |
|---|---|
MarsRuleSet
|
完成 ID 和引用校验的规则集。 |
引发:
| 类型 | 描述 |
|---|---|
MarsRuleArtifactError
|
artifact 类型、版本、规则条目、ID 或等级引用非法时抛出。 |
save_json ¶
原子写出规则集 JSON。
参数:
| 名称 | 类型 | 描述 | 默认 |
|---|---|---|---|
path
|
Union[str, Path]
|
输出文件;父目录必须已经存在。 |
必需 |
引发:
| 类型 | 描述 |
|---|---|
FileNotFoundError
|
输出目录不存在时抛出。 |
Exception
|
临时文件写入、同步或原子替换失败时原样抛出。 |
load_json
classmethod
¶
读取并严格校验规则集 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 导出要求的最低部署资格; |
'validated'
|
missing_policy
|
Literal['reject', 'normalized_to_null']
|
|
'reject'
|
返回:
| 类型 | 描述 |
|---|---|
str
|
可嵌入 |
引发:
| 类型 | 描述 |
|---|---|
MarsRuleDeploymentError
|
资格不足、策略非法或 MISSING 无法安全导出时抛出。 |
mars.rule.MarsRuleMetricCondition
dataclass
¶
定义单个规则评估指标条件。
参数:
| 名称 | 类型 | 描述 | 默认 |
|---|---|---|---|
metric
|
str
|
固定长表中的指标列名。 |
必需 |
operator
|
('<', '<=', '==', '!=', '>=', '>')
|
比较运算符。 |
"<"
|
value
|
float
|
比较阈值。 |
必需 |
mars.rule.MarsRuleFilter
dataclass
¶
定义规则筛选阈值与跨目标、切片通过策略。
参数:
| 名称 | 类型 | 描述 | 默认 |
|---|---|---|---|
conditions
|
tuple[MarsRuleMetricCondition, ...]
|
单行评估结果必须同时满足的指标条件。 |
必需 |
targets
|
"primary"、"all" 或目标列元组
|
参与筛选的目标范围。 |
'primary'
|
target_scope
|
('all', 'any')
|
多目标条件的聚合方式。 |
"all"
|
slice_pass_rate
|
float | None
|
提供切片结果时要求通过的最小切片比例; |
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
|
explore
classmethod
¶
构造允许 in-sample 结果的探索策略。
参数:
| 名称 | 类型 | 描述 | 默认 |
|---|---|---|---|
**overrides
|
Any
|
覆盖默认 dataclass 字段的显式配置。 |
{}
|
返回:
| 类型 | 描述 |
|---|---|
MarsRuleMiningSpec
|
|
production
classmethod
¶
构造强制独立验证和统计门禁的生产策略。
参数:
| 名称 | 类型 | 描述 | 默认 |
|---|---|---|---|
**overrides
|
Any
|
覆盖默认 dataclass 字段的显式配置。 |
{}
|
返回:
| 类型 | 描述 |
|---|---|
MarsRuleMiningSpec
|
|
low_risk
classmethod
¶
构造默认低风险挖掘策略。
参数:
| 名称 | 类型 | 描述 | 默认 |
|---|---|---|---|
**overrides
|
Any
|
覆盖默认 dataclass 字段的显式配置。 |
{}
|
返回:
| 类型 | 描述 |
|---|---|
MarsRuleMiningSpec
|
Lift 上限分别为 0.9 和 0.8 的低风险策略。 |
mars.rule.MarsRuleMiningResult
dataclass
¶
规则挖掘的可审计结构化结果。
参数:
| 名称 | 类型 | 描述 | 默认 |
|---|---|---|---|
status
|
('success', '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 ¶
构造不产生文件副作用的结构化报告。
参数:
| 名称 | 类型 | 描述 | 默认 |
|---|---|---|---|
analysis
|
MarsRuleAnalysis | None
|
显式执行的高级分析;不传时省略相关 section。 |
None
|
返回:
| 类型 | 描述 |
|---|---|
MarsRuleReport
|
可进一步导出 HTML 或 Excel 的报告。 |
mars.rule.MarsRuleEvaluation
dataclass
¶
保存一次规则评估的固定长表。
参数:
| 名称 | 类型 | 描述 | 默认 |
|---|---|---|---|
overall_table
|
DataFrame
|
|
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 ¶
写出自包含 HTML 规则报告。
参数:
| 名称 | 类型 | 描述 | 默认 |
|---|---|---|---|
path
|
Union[str, Path]
|
输出 HTML 路径;父目录会自动创建。 |
'mars_rule_report.html'
|
返回:
| 类型 | 描述 |
|---|---|
Path
|
实际写出的文件路径。 |
mars.rule.MarsRuleGenerator ¶
Bases: ABC
规则候选生成器抽象接口。
子类只负责从训练数据生成不含样本指标的 :class:MarsRule。最终方向、筛选和去重由
:func:mars.rule.mine_rules 统一完成。
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
|
|
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: |
500
|
feature_prefilter_sample_size
|
int
|
统计预筛最大样本数。 |
100000
|
引发:
| 类型 | 描述 |
|---|---|
ValueError
|
分箱、交叉、候选或特征预筛预算非法时抛出。 |
generate ¶
生成分位点与交叉规则。
mars.rule.MarsTreeRuleGenerator ¶
Bases: MarsRuleGenerator
从多棵随机浅层决策树提取叶子路径。
每棵树使用确定性中位数填充值和显式缺失指示器训练;提取路径时将缺失分支还原为
IS MISSING,避免训练矩阵与部署命中语义漂移。
generate ¶
训练浅层树并提取可部署路径规则。