Scoring¶

Experimental

Scoring 的评分映射、刻度参数和 SQL 输出仍可能调整。受控生产使用应固定精确版本，并为评分表和生成 SQL 增加契约测试。完整流程见报告与评分卡。

mars.scoring.MarsScorecard `dataclass` ¶

评分卡结果对象。

该对象封装了由已拟合分箱器和逻辑回归系数推导出的分值明细表，同时保留评分卡刻度参数，便于导出 CSV、Excel 或生成部署 SQL。

本对象属于 Experimental Scoring API；生产使用应固定 MARS 版本并验证评分映射和生成 SQL。

属性：

名称	类型	描述
`points_table`	`DataFrame or DataFrame`	评分卡分值明细表，包含特征、分箱、WOE、系数与最终分值。
`base_points`	`float`	基础分。
`factor`	`float`	评分卡缩放因子。
`offset`	`float`	评分卡偏移量。
`pdo`	`float`	Points to Double the Odds 参数。
`base_score`	`float`	基准分数。
`base_odds`	`float`	基准赔率。
`intercept`	`float`	逻辑回归截距项。
`coefficients`	`dict of str to float`	特征系数字典。

示例：

>>> card = MarsScorecard(
...     points_table=pl.DataFrame({"feature": ["age"], "bin_index": [0], "points": [12.0]}),
...     base_points=600.0,
...     factor=28.85,
...     offset=600.0,
...     pdo=20.0,
...     base_score=600.0,
...     base_odds=50.0,
...     intercept=0.0,
...     coefficients={"age": 0.3},
...     _binner=None,
... )
>>> card.base_points
600.0

to_integer ¶

to_integer(
    round_decimals: int = 0, rebalance: bool = True
) -> MarsScorecard

返回分值取整后的评分卡副本。

参数：

名称	类型	描述	默认
`round_decimals`	`int`	分值保留的小数位数。为 `0` 时，分箱分值列会转为整数。	`0`
`rebalance`	`bool`	是否把四舍五入产生的总分漂移回补到基础分。	`True`

返回：

类型	描述
`MarsScorecard`	取整后的新评分卡对象，原对象不被修改。

引发：

类型	描述
`ValueError`	当输入参数、列配置或数据状态不满足当前方法要求时抛出。

示例：

>>> card = MarsScorecard(
...     points_table=pl.DataFrame({"feature": ["age"], "bin_index": [0], "points": [12.4]}),
...     base_points=600.0,
...     factor=28.85,
...     offset=600.0,
...     pdo=20.0,
...     base_score=600.0,
...     base_odds=50.0,
...     intercept=0.0,
...     coefficients={"age": 0.3},
...     _binner=None,
... )
>>> rounded = card.to_integer()
>>> isinstance(rounded, MarsScorecard)
True

write_csv ¶

write_csv(path: str = 'mars_scorecard.csv') -> None

导出评分卡分值表为 CSV 文件。

参数：

名称	类型	描述	默认
`path`	`str`	输出文件路径。	`'mars_scorecard.csv'`

返回：

类型	描述
`None`	函数仅产生 CSV 文件写入副作用。

示例：

>>> from pathlib import Path
>>> from tempfile import TemporaryDirectory
>>> card = MarsScorecard(
...     points_table=pl.DataFrame({"feature": ["age"], "bin_index": [0], "points": [12.0]}),
...     base_points=600.0,
...     factor=28.85,
...     offset=600.0,
...     pdo=20.0,
...     base_score=600.0,
...     base_odds=50.0,
...     intercept=0.0,
...     coefficients={"age": 0.3},
...     _binner=None,
... )
>>> with TemporaryDirectory() as tmp:
...     path = Path(tmp) / "scorecard.csv"
...     card.write_csv(str(path))
...     path.exists()
True

write_excel ¶

write_excel(path: str = 'mars_scorecard.xlsx') -> None

导出评分卡为 Excel 文件。

参数：

名称	类型	描述	默认
`path`	`str`	输出文件路径。	`'mars_scorecard.xlsx'`

返回：

类型	描述
`None`	函数仅产生 Excel 文件写入副作用。

Notes

导出结果包含 Config 与 Points 两个工作表，分别记录评分卡参数与分值明细。若环境缺少 xlsxwriter，会自动回退到 openpyxl。

示例：

>>> from pathlib import Path
>>> from tempfile import TemporaryDirectory
>>> card = MarsScorecard(
...     points_table=pl.DataFrame({"feature": ["age"], "bin_index": [0], "points": [12.0]}),
...     base_points=600.0,
...     factor=28.85,
...     offset=600.0,
...     pdo=20.0,
...     base_score=600.0,
...     base_odds=50.0,
...     intercept=0.0,
...     coefficients={"age": 0.3},
...     _binner=None,
... )
>>> with TemporaryDirectory() as tmp:
...     path = Path(tmp) / "scorecard.xlsx"
...     card.write_excel(str(path))
...     path.exists()
True

generate_sql ¶

generate_sql(
    *,
    features: List[str] | None = None,
    table_prefix: str = "t",
    score_name: str = "score",
    include_base_points: bool = True
) -> str

生成评分卡 SQL 片段。

参数：

名称	类型	描述	默认
`features`	`List[str] \| None`	需要生成 SQL 的特征列表。默认为全部系数特征。	`None`
`table_prefix`	`str`	SQL 中引用特征列时使用的表别名前缀。传空字符串表示不加前缀。	`'t'`
`score_name`	`str`	最终总分字段名称。	`'score'`
`include_base_points`	`bool`	是否在总分表达式中包含基础分。	`True`

返回：

类型	描述
`str`	可直接嵌入 `SELECT` 语句的 SQL 片段。若没有任何有效特征，则返回空字符串。

示例：

>>> from mars.feature import MarsNativeBinner
>>> X = pl.DataFrame({"age": [20, 30, 40, 50]})
>>> y = pl.Series("target", [0, 0, 1, 1])
>>> binner = MarsNativeBinner(method="quantile", n_bins=2).fit(X, y, features=["age"])
>>> scorecard = build_scorecard(
...     binner,
...     {"age": 0.3},
...     intercept=-1.2,
...     pdo=20,
...     base_score=600,
...     base_odds=50,
... )
>>> sql = scorecard.generate_sql(features=["age"], table_prefix="t")
>>> "age_points" in sql
True

mars.scoring.build_scorecard ¶

build_scorecard(
    binner: MarsBinnerBase,
    coefficients: Dict[str, float],
    intercept: float,
    pdo: float,
    base_score: float,
    base_odds: float,
) -> MarsScorecard

基于分箱器和逻辑回归系数构建评分卡。

本函数属于 Experimental Scoring API；生产使用应固定 MARS 版本并验证评分表和生成 SQL。

参数：

名称	类型	描述	默认
`binner`	`MarsBinnerBase`	已拟合的分箱器，且能够提供分箱映射与 WOE 信息。	必需
`coefficients`	`Dict[str, float]`	特征系数字典，键为特征名，值为对应逻辑回归系数。	必需
`intercept`	`float`	逻辑回归截距项。	必需
`pdo`	`float`	Points to Double the Odds 参数，必须为正数。	必需
`base_score`	`float`	评分卡基准分数。	必需
`base_odds`	`float`	基准赔率，必须为正数。	必需

返回：

类型	描述
`MarsScorecard`	构建完成的评分卡对象。

引发：

类型	描述
`ValueError`	当 `pdo` 或 `base_odds` 非正，`coefficients` 为空，或分箱器缺少构建评分卡所需的映射信息时抛出。

示例：

>>> from mars.feature import MarsNativeBinner
>>> X = pl.DataFrame({"age": [20, 30, 40, 50]})
>>> y = pl.Series("target", [0, 0, 1, 1])
>>> binner = MarsNativeBinner(method="quantile", n_bins=2).fit(X, y, features=["age"])
>>> card = build_scorecard(binner, {"age": 0.3}, intercept=-1.2, pdo=20, base_score=600, base_odds=50)
>>> isinstance(card, MarsScorecard)
True