SuperModelingFactory 0.7.2__tar.gz → 0.8.0__tar.gz

{supermodelingfactory-0.7.2 → supermodelingfactory-0.8.0}/Modeling_Tool/Feature/Feature_Screen.py

@@ -51,6 +51,10 @@ _MONOTONE_INIT_KEYS = frozenset({
     "direction_conflict_policy",
     "missing_bin_strategy",
     "refine_min_n_bins_policy",
+    "sv_min_bin_size",
+    "sv_small_policy",
+    "sv_woe_smoothing",
+    "sv_smoothing_alpha",
 })
 _MONOTONE_FIT_KEYS = frozenset({"chi2_binning", "chi2_p", "chi2_init_size", "n_jobs"})
 

{supermodelingfactory-0.7.2 → supermodelingfactory-0.8.0}/Modeling_Tool/Pipeline/credit_model.py

@@ -62,11 +62,30 @@ class CreditModelPipelineConfig:
     woe_engine: str = "equal_freq"
     woe_fit_query: str | None = None
     extra_eval_datasets: dict[str, pd.DataFrame] | None = None
+    # sv_* govern special-value (SV) WOE bins only; the defaults below reproduce
+    # pre-0.8.0 behavior bit-for-bit. They reach WOE_Master via fit(**woe_params)
+    # and MonotoneWOEBinner via __init__(**monotone_woe_params).
     woe_params: dict[str, Any] = field(
-        default_factory=lambda: {"nbins": 10, "equal_freq": True, "min_bin_prop": 0.05}
+        default_factory=lambda: {
+            "nbins": 10,
+            "equal_freq": True,
+            "min_bin_prop": 0.05,
+            "sv_min_bin_size": 0.0,
+            "sv_small_policy": "keep",
+            "sv_woe_smoothing": "none",
+            "sv_smoothing_alpha": 0.0,
+        }
     )
     monotone_woe_params: dict[str, Any] = field(
-        default_factory=lambda: {"n_init_bins": 20, "min_bin_size": 0.03, "min_n_bins": 2}
+        default_factory=lambda: {
+            "n_init_bins": 20,
+            "min_bin_size": 0.03,
+            "min_n_bins": 2,
+            "sv_min_bin_size": 0.0,
+            "sv_small_policy": "keep",
+            "sv_woe_smoothing": "none",
+            "sv_smoothing_alpha": 0.0,
+        }
     )
 
     train_models: list[str] = field(default_factory=lambda: ["lr", "lgb", "xgb", "cat"])

{supermodelingfactory-0.7.2 → supermodelingfactory-0.8.0}/Modeling_Tool/Pipeline/feature_validation.py

@@ -66,11 +66,31 @@ class FeatureValidationPipelineConfig:
     woe_enabled: bool = True
     woe_fit_query: str | None = None
     woe_engine: str = "monotone"
+    # sv_* govern special-value (SV) WOE bins only; the defaults below reproduce
+    # pre-0.8.0 behavior bit-for-bit. Monotone-side sv_* keys only survive because
+    # they are listed in _MONOTONE_INIT_KEYS below — unlisted keys are dropped
+    # silently, so the two lists must be kept in sync.
     woe_params: dict[str, Any] = field(
-        default_factory=lambda: {"nbins": 10, "equal_freq": True, "min_bin_prop": 0.05}
+        default_factory=lambda: {
+            "nbins": 10,
+            "equal_freq": True,
+            "min_bin_prop": 0.05,
+            "sv_min_bin_size": 0.0,
+            "sv_small_policy": "keep",
+            "sv_woe_smoothing": "none",
+            "sv_smoothing_alpha": 0.0,
+        }
     )
     monotone_woe_params: dict[str, Any] = field(
-        default_factory=lambda: {"n_init_bins": 20, "min_bin_size": 0.03, "min_n_bins": 2}
+        default_factory=lambda: {
+            "n_init_bins": 20,
+            "min_bin_size": 0.03,
+            "min_n_bins": 2,
+            "sv_min_bin_size": 0.0,
+            "sv_small_policy": "keep",
+            "sv_woe_smoothing": "none",
+            "sv_smoothing_alpha": 0.0,
+        }
     )
     categorical_features: list[str] | None = None
     monotone_refine_cate_enabled: bool = False
@@ -170,6 +190,10 @@ class FeatureValidationPipeline:
         "direction_conflict_policy",
         "missing_bin_strategy",
         "refine_min_n_bins_policy",
+        "sv_min_bin_size",
+        "sv_small_policy",
+        "sv_woe_smoothing",
+        "sv_smoothing_alpha",
     }
     _MONOTONE_FIT_KEYS = {"chi2_binning", "chi2_p", "chi2_init_size", "n_jobs"}
 

{supermodelingfactory-0.7.2 → supermodelingfactory-0.8.0}/Modeling_Tool/WOE/WOE_Master.py

@@ -289,7 +289,9 @@ class WOE_Master(object):
         self.varlist = varlist
 
     def fit(self, nbins=10, equal_freq=True, tree_binning_seed=None, chi2_config=None,
-            precision=5, min_bin_prop=0.05, include_missing=True, fillna=None, spec_values=[]):
+            precision=5, min_bin_prop=0.05, include_missing=True, fillna=None, spec_values=[],
+            sv_min_bin_size=0.0, sv_small_policy="keep",
+            sv_woe_smoothing="none", sv_smoothing_alpha=0.0):
         """Fit WOE binning for variables in varlist.
 
         Args:
@@ -302,6 +304,11 @@ class WOE_Master(object):
             include_missing: bool, include missing value bin (default True)
             fillna: int/float, value to fill missing data
             spec_values: list, special values to handle
+            sv_min_bin_size: float, low-frequency special-value bin threshold as a
+                share of all samples; 0.0 disables the fallback (legacy behaviour)
+            sv_small_policy: str, 'keep' (default) / 'neutral' / 'merge_missing'
+            sv_woe_smoothing: str, 'none' (default) / 'laplace'
+            sv_smoothing_alpha: float, Laplace smoothing strength alpha (pseudo-counts)
         Returns:
             None, updates self.woe_dict attribute
         """
@@ -323,6 +330,10 @@ class WOE_Master(object):
                                     ascending=True,
                                     fillna=fillna,
                                     spec_values=spec_values,
+                                    sv_min_bin_size=sv_min_bin_size,
+                                    sv_small_policy=sv_small_policy,
+                                    sv_woe_smoothing=sv_woe_smoothing,
+                                    sv_smoothing_alpha=sv_smoothing_alpha,
                                     drop_bin_info=True,
                                     ret_woe_table=True)
             woe_table = woe_res[-1]
@@ -381,7 +392,9 @@ class WOE_Master(object):
         return data_woe
 
     def update_woe(self, varlist, nbins=10, equal_freq=True, tree_binning_seed=None, chi2_config=None,
-                   precision=5, min_bin_prop=0.05, include_missing=True, fillna=None, spec_values=[]):
+                   precision=5, min_bin_prop=0.05, include_missing=True, fillna=None, spec_values=[],
+                   sv_min_bin_size=0.0, sv_small_policy="keep",
+                   sv_woe_smoothing="none", sv_smoothing_alpha=0.0):
         """Update WOE binning for specified variables.
 
         Args:
@@ -395,6 +408,11 @@ class WOE_Master(object):
             include_missing: bool, include missing value bin (default True)
             fillna: int/float, value to fill missing data
             spec_values: list, special values to handle
+            sv_min_bin_size: float, low-frequency special-value bin threshold as a
+                share of all samples; 0.0 disables the fallback (legacy behaviour)
+            sv_small_policy: str, 'keep' (default) / 'neutral' / 'merge_missing'
+            sv_woe_smoothing: str, 'none' (default) / 'laplace'
+            sv_smoothing_alpha: float, Laplace smoothing strength alpha (pseudo-counts)
         Returns:
             None, updates self.woe_dict attribute
         """
@@ -417,6 +435,10 @@ class WOE_Master(object):
                                     ascending=True,
                                     fillna=fillna,
                                     spec_values=spec_values,
+                                    sv_min_bin_size=sv_min_bin_size,
+                                    sv_small_policy=sv_small_policy,
+                                    sv_woe_smoothing=sv_woe_smoothing,
+                                    sv_smoothing_alpha=sv_smoothing_alpha,
                                     drop_bin_info=True,
                                     ret_woe_table=True)
             woe_table = woe_res[-1]

{supermodelingfactory-0.7.2 → supermodelingfactory-0.8.0}/Modeling_Tool/WOE/WOE_Master.pyi

@@ -27,11 +27,11 @@ class WOE_Master(object):
     def __init__(self, train_data, varlist, dep = None, graph_save_dir = '', woe_suffix = '_woe', missing_ref_value = ..., remove_exist_dir = False): ...
     def remove_folder(file_path): ...
     def load_mapping_table(self, mapping_table_csv): ...
-    def fit(self, nbins = 10, equal_freq = True, tree_binning_seed = None, chi2_config = None, precision = 5, min_bin_prop = 0.05, include_missing = True, fillna = None, spec_values = []): ...
+    def fit(self, nbins = 10, equal_freq = True, tree_binning_seed = None, chi2_config = None, precision = 5, min_bin_prop = 0.05, include_missing = True, fillna = None, spec_values = [], sv_min_bin_size = 0.0, sv_small_policy = 'keep', sv_woe_smoothing = 'none', sv_smoothing_alpha = 0.0): ...
     def get_mapping_table(self): ...
     def save_mapping_table(self, save_dir): ...
     def transform(self, data = None, varlist = None): ...
-    def update_woe(self, varlist, nbins = 10, equal_freq = True, tree_binning_seed = None, chi2_config = None, precision = 5, min_bin_prop = 0.05, include_missing = True, fillna = None, spec_values = []): ...
+    def update_woe(self, varlist, nbins = 10, equal_freq = True, tree_binning_seed = None, chi2_config = None, precision = 5, min_bin_prop = 0.05, include_missing = True, fillna = None, spec_values = [], sv_min_bin_size = 0.0, sv_small_policy = 'keep', sv_woe_smoothing = 'none', sv_smoothing_alpha = 0.0): ...
     def plot_bivar_graph(self, data, group = None, dirname = None, varlist = None): ...
 def load_mapping_table(mapping_table_csv): ...
 def get_mapping_table(woe_dict): ...

{supermodelingfactory-0.7.2 → supermodelingfactory-0.8.0}/Modeling_Tool/WOE/WOE_Monotone_Binner.py

@@ -245,6 +245,18 @@ class MonotoneWOEBinner:
                          显示 N 位小数（:.Nf），例如 N=2 时 1234.5678 → 1234.57。
                          注意：较低的精度会使 load_woe_bins(get_final_bins()) 的
                          round-trip 边界稍有误差，但通常可忽略。
+    sv_min_bin_size    : 低占比 SV 兜底阈值（SV 箱占**全量**样本的占比），
+                         默认 0.0 = 关闭。
+    sv_small_policy    : 占比 < sv_min_bin_size 的 SV 箱如何处理，
+                         'keep'（默认，经验 WOE，零行为变更）/
+                         'neutral'（woe=iv=0）/
+                         'merge_missing'（bad/good 并入 [Missing] 箱后重算，
+                         被合并行的存表 WOE 改写为 [Missing] 的 WOE；
+                         无 [Missing] 箱时降级 'neutral' 并告警）。
+    sv_woe_smoothing   : SV 箱 WOE 是否向全局坏率收缩，'none'（默认）/'laplace'。
+    sv_smoothing_alpha : 平滑强度 α（伪计数），默认 0.0（数值等价旧 WOE）。
+                         方式1 优先：低占比箱走兜底后**不再**平滑；平滑只作用于
+                         占比达标（或 policy='keep'）的 SV 箱。
 
     fit() 参数（传入 fit() 方法，不在 __init__ 中设置）
     -------------------------------------------------------
@@ -279,6 +291,10 @@ class MonotoneWOEBinner:
         direction_conflict_policy: Optional[str] = None,
         missing_bin_strategy: Optional[str] = None,
         refine_min_n_bins_policy: Optional[str] = "warn",
+        sv_min_bin_size: float = 0.0,
+        sv_small_policy: str = "keep",
+        sv_woe_smoothing: str = "none",
+        sv_smoothing_alpha: float = 0.0,
     ):
         self.feature_cols      = list(feature_cols)
         self.target_col        = target_col
@@ -344,9 +360,32 @@ class MonotoneWOEBinner:
                     "missing_bin_strategy='fixed_woe' conflicts with NaN in special_values: "
                     "missing rows would get an empirical bin, not the fixed missing_woe constant."
                 )
+        # ── SV 箱治理参数（G19；默认 keep/none/0.0 = 旧行为，零行为变更） ──
+        if sv_small_policy not in {"keep", "neutral", "merge_missing"}:
+            raise ValueError(
+                f"sv_small_policy must be one of ['keep', 'neutral', 'merge_missing']; "
+                f"got {sv_small_policy!r}"
+            )
+        if sv_woe_smoothing not in {"none", "laplace"}:
+            raise ValueError(
+                f"sv_woe_smoothing must be one of ['none', 'laplace']; "
+                f"got {sv_woe_smoothing!r}"
+            )
+        if not (0.0 <= sv_min_bin_size < 1.0):
+            raise ValueError(
+                f"sv_min_bin_size must be in [0.0, 1.0); got {sv_min_bin_size}"
+            )
+        if sv_smoothing_alpha < 0.0:
+            raise ValueError(
+                f"sv_smoothing_alpha must be >= 0.0; got {sv_smoothing_alpha}"
+            )
         self.min_bad_count = min_bad_count
         self.min_good_count = min_good_count
         self.small_bin_policy = small_bin_policy
+        self.sv_min_bin_size = sv_min_bin_size
+        self.sv_small_policy = sv_small_policy
+        self.sv_woe_smoothing = sv_woe_smoothing
+        self.sv_smoothing_alpha = sv_smoothing_alpha
         self.monotone_direction = monotone_direction
         self.reference_target = reference_target
         self.direction_conflict_policy = direction_conflict_policy
@@ -514,16 +553,31 @@ class MonotoneWOEBinner:
         return pd.Series(0, index=sub.index)
 
     def _compute_woe_single_bin(
-        self, sub: pd.DataFrame, total_bad: float, total_good: float
+        self, sub: pd.DataFrame, total_bad: float, total_good: float,
+        smooth: bool = False,
     ) -> Dict[str, float]:
-        """计算某子集的 bad/good/woe/iv 等统计量。"""
+        """计算某子集的 bad/good/woe/iv 等统计量。
+
+        ``smooth=True`` 允许 G19 的拉普拉斯平滑生效（仅 SV 箱路径显式开启，
+        普通箱调用保持 ``smooth=False``、口径不变）。
+        """
         eps = self.eps
         n    = len(sub)
         bad  = float(sub[self.target_col].sum())
         good = float((sub[self.target_col] == 0).sum())
         bad_rate = bad / (bad + good) if (bad + good) > 0 else 0.0
-        pct_bad  = bad  / (total_bad  + eps)
-        pct_good = good / (total_good + eps)
+        if smooth and self.sv_woe_smoothing == "laplace" and self.sv_smoothing_alpha > 0.0:
+            # 把箱内 bad_rate 向全局基准率 p 收缩，再换算回等效 bad/good 计数。
+            # 该式在 alpha→∞ 时 bad_rate→p，WOE→0（严格单调收缩到中性）；
+            # 直接给 pct_bad/pct_good 加伪计数则会收敛到 logit(p) 而非 0。
+            a = self.sv_smoothing_alpha
+            p = total_bad / (total_bad + total_good + eps)
+            r = (bad + a * p) / (bad + good + a)
+            pct_bad  = ((bad + good) * r)         / (total_bad  + eps)
+            pct_good = ((bad + good) * (1.0 - r)) / (total_good + eps)
+        else:
+            pct_bad  = bad  / (total_bad  + eps)
+            pct_good = good / (total_good + eps)
         woe = math.log((pct_bad + eps) / (pct_good + eps))
         iv  = (pct_bad - pct_good) * woe
         return dict(n=n, bad=int(bad), good=int(good),
@@ -577,16 +631,120 @@ class MonotoneWOEBinner:
         """
         计算所有特殊值的独立 WOE 明细，返回 DataFrame。
         每行对应一个特殊值，bin_label 为 '[sv=xxx]' 或 '[Missing]'。
+
+        G19：当 sv_small_policy / sv_woe_smoothing 启用时，按固定顺序决策
+        （方式1 兜底优先，方式2 平滑仅作用于占比达标的保留箱），并额外产出
+        ``sv_policy_applied`` 审计列。
         """
+        governance_on = (
+            self.sv_small_policy != "keep" or self.sv_woe_smoothing != "none"
+        )
+        n_total = total_bad + total_good
         records = []
+        missing_row_idx = None
         for sv, sv_df in sv_groups.items():
             if len(sv_df) == 0:
                 continue
-            stats = self._compute_woe_single_bin(sv_df, total_bad, total_good)
+            if not governance_on:
+                stats = self._compute_woe_single_bin(sv_df, total_bad, total_good)
+            else:
+                label = _sv_label(sv)
+                is_small = (
+                    self.sv_small_policy != "keep"
+                    and self.sv_min_bin_size > 0.0
+                    and n_total > 0
+                    and len(sv_df) / n_total < self.sv_min_bin_size
+                    # [Missing] is the merge *target*, never a merge source.
+                    and not (self.sv_small_policy == "merge_missing"
+                             and label == "[Missing]")
+                )
+                if is_small and self.sv_small_policy == "neutral":
+                    stats = self._compute_woe_single_bin(sv_df, total_bad, total_good)
+                    stats["woe"] = 0.0
+                    stats["iv"] = 0.0
+                    stats["sv_policy_applied"] = "neutral"
+                elif is_small:
+                    # merge_missing：先留经验值，全部 SV 收集完后再合并
+                    stats = self._compute_woe_single_bin(sv_df, total_bad, total_good)
+                    stats["sv_policy_applied"] = "pending_merge"
+                else:
+                    stats = self._compute_woe_single_bin(
+                        sv_df, total_bad, total_good, smooth=True
+                    )
+                    stats["sv_policy_applied"] = "keep"
+                if label == "[Missing]":
+                    missing_row_idx = len(records)
             stats["bin_label"] = _sv_label(sv)
             stats["sv"] = sv
             records.append(stats)
-        return pd.DataFrame(records) if records else pd.DataFrame()
+        sv_table = pd.DataFrame(records) if records else pd.DataFrame()
+        if (
+            governance_on
+            and self.sv_small_policy == "merge_missing"
+            and len(sv_table) > 0
+        ):
+            sv_table = self._merge_small_into_missing(
+                sv_table, missing_row_idx, total_bad, total_good
+            )
+        return sv_table
+
+    def _merge_small_into_missing(
+        self, sv_table: pd.DataFrame, missing_row_idx: Optional[int],
+        total_bad: float, total_good: float,
+    ) -> pd.DataFrame:
+        """把 pending_merge 的低占比 SV 行并入 [Missing] 行并重算 WOE。
+
+        被合并行保留自己的行，但其存表 WOE 被改写为 [Missing] 重算后的 WOE，
+        iv 置 0（避免与合并目标重复计入总 IV）。这样 apply_woe 的
+        ``bin_label -> woe`` 映射天然指向缺失箱口径，transform 侧零改动。
+        无 [Missing] 箱时降级为 neutral 并告警。
+
+        n/bad/good 是**转移**而非复制：合并目标加上、来源行清零。否则
+        ``sv_table["n"].sum()`` 会重复计数，进而污染 pct_n/lift 与
+        transform 侧的 fit_missing_rate 漂移基线。
+        """
+        pend = sv_table["sv_policy_applied"] == "pending_merge"
+        if not pend.any():
+            return sv_table
+        if missing_row_idx is None:
+            for i in sv_table.index[pend]:
+                warnings.warn(
+                    f"sv_small_policy='merge_missing' but feature has no [Missing] bin; "
+                    f"falling back to 'neutral' for SV {sv_table.loc[i, 'sv']!r}.",
+                    UserWarning, stacklevel=2,
+                )
+                sv_table.loc[i, "woe"] = 0.0
+                sv_table.loc[i, "iv"] = 0.0
+                sv_table.loc[i, "sv_policy_applied"] = "neutral(fallback)"
+            return sv_table
+        m = missing_row_idx
+        new_n    = int(sv_table.loc[m, "n"])    + int(sv_table.loc[pend, "n"].sum())
+        new_bad  = float(sv_table.loc[m, "bad"])  + float(sv_table.loc[pend, "bad"].sum())
+        new_good = float(sv_table.loc[m, "good"]) + float(sv_table.loc[pend, "good"].sum())
+        pct_bad  = new_bad  / (total_bad  + self.eps)
+        pct_good = new_good / (total_good + self.eps)
+        woe = math.log((pct_bad + self.eps) / (pct_good + self.eps))
+        sv_table.loc[m, "n"] = new_n
+        sv_table.loc[m, "bad"] = int(new_bad)
+        sv_table.loc[m, "good"] = int(new_good)
+        sv_table.loc[m, "bad_rate"] = (
+            new_bad / (new_bad + new_good) if (new_bad + new_good) > 0 else 0.0
+        )
+        sv_table.loc[m, "pct_bad"] = pct_bad
+        sv_table.loc[m, "pct_good"] = pct_good
+        sv_table.loc[m, "woe"] = woe
+        sv_table.loc[m, "iv"] = (pct_bad - pct_good) * woe
+        sv_table.loc[m, "sv_policy_applied"] = "merge_target"
+        sv_table.loc[pend, "n"] = 0
+        sv_table.loc[pend, "bad"] = 0
+        sv_table.loc[pend, "good"] = 0
+        sv_table.loc[pend, "bad_rate"] = 0.0
+        sv_table.loc[pend, "pct_bad"] = 0.0
+        sv_table.loc[pend, "pct_good"] = 0.0
+        sv_table.loc[pend, "woe"] = woe
+        sv_table.loc[pend, "iv"] = 0.0
+        sv_table.loc[pend, "sv_policy_applied"] = "merged_into_missing"
+        return sv_table
 
     @staticmethod
     def _is_monotone(woe_values: np.ndarray) -> bool:

{supermodelingfactory-0.7.2 → supermodelingfactory-0.8.0}/Modeling_Tool/WOE/WOE_Monotone_Binner.pyi

@@ -33,14 +33,15 @@ _SPECIAL_BIN_PREFIX: object
 _CATE_GROUP_SEP: object
 
 class MonotoneWOEBinner:
-    def __init__(self, feature_cols: List[str], target_col: str, n_init_bins: int = 20, min_bin_size: float = 0.03, min_n_bins: int = 2, eps: float = 1e-06, missing_woe: float = 0.0, special_values: Optional[List] = None, cate_feats: Optional[List[str]] = None, bin_label_decimals: Optional[int] = None, min_bad_count: Optional[int] = None, min_good_count: Optional[int] = None, small_bin_policy: Optional[str] = None, monotone_direction: Any = 'auto', reference_target: Optional[str] = None, direction_conflict_policy: Optional[str] = None, missing_bin_strategy: Optional[str] = None, refine_min_n_bins_policy: Optional[str] = 'warn'): ...
+    def __init__(self, feature_cols: List[str], target_col: str, n_init_bins: int = 20, min_bin_size: float = 0.03, min_n_bins: int = 2, eps: float = 1e-06, missing_woe: float = 0.0, special_values: Optional[List] = None, cate_feats: Optional[List[str]] = None, bin_label_decimals: Optional[int] = None, min_bad_count: Optional[int] = None, min_good_count: Optional[int] = None, small_bin_policy: Optional[str] = None, monotone_direction: Any = 'auto', reference_target: Optional[str] = None, direction_conflict_policy: Optional[str] = None, missing_bin_strategy: Optional[str] = None, refine_min_n_bins_policy: Optional[str] = 'warn', sv_min_bin_size: float = 0.0, sv_small_policy: str = 'keep', sv_woe_smoothing: str = 'none', sv_smoothing_alpha: float = 0.0): ...
     def _split_special(self, df: pd.DataFrame, feat: str): ...
     def _cat_to_bin_map(vr: Dict) -> Dict: ...
     def _split_special_for_plot(self, df: pd.DataFrame, feat: str, vr: Dict): ...
     def _assign_normal_bins(self, sub: pd.DataFrame, feat: str, vr: Dict, fitted_edges: list) -> pd.Series: ...
-    def _compute_woe_single_bin(self, sub: pd.DataFrame, total_bad: float, total_good: float) -> Dict[str, float]: ...
+    def _compute_woe_single_bin(self, sub: pd.DataFrame, total_bad: float, total_good: float, smooth: bool = False) -> Dict[str, float]: ...
     def _compute_woe_table(self, df: pd.DataFrame, feat: str, edges: list) -> tuple: ...
     def _compute_sv_table(self, sv_groups: Dict, total_bad: float, total_good: float) -> pd.DataFrame: ...
+    def _merge_small_into_missing(self, sv_table: pd.DataFrame, missing_row_idx: Optional[int], total_bad: float, total_good: float) -> pd.DataFrame: ...
     def _is_monotone(woe_values: np.ndarray) -> bool: ...
     def _is_monotone_dir(woe_values: np.ndarray, direction: int) -> bool: ...
     def _direction_of(woe_values: np.ndarray) -> str: ...

{supermodelingfactory-0.7.2 → supermodelingfactory-0.8.0}/Modeling_Tool/WOE/WOE_Tool.py

@@ -6,6 +6,7 @@ WOE转换与单调性分析工具包
 import numpy as np
 import pandas as pd
 import logging
+import warnings
 
 from Modeling_Tool.Core.Binning_Tool import (
     _parse_bin_range_bounds,
@@ -203,7 +204,9 @@ class WOETransformer:
 
     def __init__(self, nbins=10, precision=5, min_bin_prop=0.05, include_missing=False,
                  equal_freq=True, fillna=-999999, chi2_config=None, tree_binning_seed=None,
-                 spec_values=None, drop_bin_info=True, ret_woe_table=True):
+                 spec_values=None, drop_bin_info=True, ret_woe_table=True,
+                 sv_min_bin_size=0.0, sv_small_policy="keep",
+                 sv_woe_smoothing="none", sv_smoothing_alpha=0.0):
         """初始化WOE转换器。
 
         参数:
@@ -230,7 +233,33 @@ class WOETransformer:
             是否删除中间分箱信息列
         ret_woe_table : bool, optional
             是否返回WOE映射表
+        sv_min_bin_size : float, optional
+            低占比特殊值箱兜底阈值（占全量样本比例），0.0 = 关闭（保旧行为）
+        sv_small_policy : str, optional
+            'keep'（默认）/'neutral'/'merge_missing'，低占比 SV 箱的处理方式
+        sv_woe_smoothing : str, optional
+            'none'（默认）/'laplace'，SV 箱 WOE 是否向全局坏率收缩
+        sv_smoothing_alpha : float, optional
+            拉普拉斯平滑强度 α（伪计数），0.0 = 数值等价旧 WOE
         """
+        if sv_small_policy not in {"keep", "neutral", "merge_missing"}:
+            raise ValueError(
+                f"sv_small_policy must be one of ['keep', 'neutral', 'merge_missing']; "
+                f"got {sv_small_policy!r}"
+            )
+        if sv_woe_smoothing not in {"none", "laplace"}:
+            raise ValueError(
+                f"sv_woe_smoothing must be one of ['none', 'laplace']; "
+                f"got {sv_woe_smoothing!r}"
+            )
+        if not (0.0 <= sv_min_bin_size < 1.0):
+            raise ValueError(
+                f"sv_min_bin_size must be in [0.0, 1.0); got {sv_min_bin_size}"
+            )
+        if sv_smoothing_alpha < 0.0:
+            raise ValueError(
+                f"sv_smoothing_alpha must be >= 0.0; got {sv_smoothing_alpha}"
+            )
         self.nbins = nbins
         self.precision = precision
         self.min_bin_prop = min_bin_prop
@@ -242,6 +271,162 @@ class WOETransformer:
         self.spec_values = spec_values if spec_values is not None else []
         self.drop_bin_info = drop_bin_info
         self.ret_woe_table = ret_woe_table
+        self.sv_min_bin_size = sv_min_bin_size
+        self.sv_small_policy = sv_small_policy
+        self.sv_woe_smoothing = sv_woe_smoothing
+        self.sv_smoothing_alpha = sv_smoothing_alpha
+
+    # G19: SV-bin governance shares MonotoneWOEBinner's eps so both engines
+    # produce identical numbers for the same counts.
+    _SV_EPS = 1e-6
+
+    def _sv_row_mask(self, woe_table):
+        """识别特殊值箱行：MIN == MAX 且该值属于 spec_values（双条件防误识别）。"""
+        spec_values = list(self.spec_values or [])
+        if not spec_values:
+            return pd.Series(False, index=woe_table.index)
+        return (
+            woe_table["MIN"].isin(spec_values)
+            & (woe_table["MIN"] == woe_table["MAX"])
+            & (woe_table["N"] > 0)
+        )
+
+    def _missing_row_label(self, woe_table, sv_mask):
+        """识别缺失值箱行标签；无缺失箱返回 None。
+
+        fit 路径下 MIN/MAX 聚合的是**原始**变量列，缺失箱因此整箱为 NaN；
+        若调用方在分箱前已 fillna（哨兵进入数据），则 MIN == MAX == fillna。
+        """
+        nan_bin = woe_table["MIN"].isna() & woe_table["MAX"].isna() & (woe_table["N"] > 0)
+        sentinel_bin = (
+            (woe_table["MIN"] == woe_table["MAX"])
+            & (woe_table["MIN"] == self.fillna)
+            & (woe_table["N"] > 0)
+            & ~sv_mask
+        )
+        candidates = woe_table.index[nan_bin | sentinel_bin]
+        return candidates[0] if len(candidates) else None
+
+    def _govern_sv_bins(self, woe_table, var):
+        """对 spec_values 对应的箱行应用 sv_small_policy / sv_woe_smoothing。
+
+        口径与 ``MonotoneWOEBinner._compute_sv_table`` 严格一致：方式1 兜底优先，
+        方式2 平滑只作用于占比达标（或 policy='keep'）的 SV 箱。
+
+        缺失箱同样是一个受治理的 SV 箱（MonotoneWOEBinner 的 sv_table 里
+        ``[Missing]`` 与其它 SV 行同权），因此并入治理行集合；它只是**永远不作为
+        merge 来源**（target-only，不能并入自己）。若仅按 ``_sv_row_mask``
+        取行，缺失箱（MIN/MAX 聚合原始列 ⇒ NaN/NaN）会漏出平滑循环，导致同参数
+        下两引擎的 [Missing] WOE 不一致。
+        """
+        eps = self._SV_EPS
+        total_bad  = float(woe_table["N_BAD"].sum())
+        total_good = float(woe_table["N_GOOD"].sum())
+        n_total = total_bad + total_good
+        p = total_bad / (n_total + eps)
+
+        sv_mask = self._sv_row_mask(woe_table)
+        missing_label = self._missing_row_label(woe_table, sv_mask)
+        governed_idx = list(woe_table.index[sv_mask])
+        if missing_label is not None and missing_label not in governed_idx:
+            governed_idx.append(missing_label)
+        if not governed_idx:
+            return woe_table
+        pending_merge = []
+        for idx in governed_idx:
+            is_small = (
+                self.sv_small_policy != "keep"
+                and self.sv_min_bin_size > 0.0
+                and n_total > 0
+                and float(woe_table.loc[idx, "N"]) / n_total < self.sv_min_bin_size
+                # 缺失箱是 merge 的目标，永远不做来源。
+                and not (self.sv_small_policy == "merge_missing"
+                         and idx == missing_label)
+            )
+            if is_small and self.sv_small_policy == "neutral":
+                woe_table.loc[idx, "WOE"] = 0.0
+                woe_table.loc[idx, "IV"] = 0.0
+            elif is_small:
+                pending_merge.append(idx)
+            elif self.sv_woe_smoothing == "laplace" and self.sv_smoothing_alpha > 0.0:
+                # 与 MonotoneWOEBinner._compute_woe_single_bin 同式：先把箱内
+                # bad_rate 向基准率 p 收缩，再换算回等效 bad/good 计数。
+                a = self.sv_smoothing_alpha
+                n_bad  = float(woe_table.loc[idx, "N_BAD"])
+                n_good = float(woe_table.loc[idx, "N_GOOD"])
+                r = (n_bad + a * p) / (n_bad + n_good + a)
+                pct_bad  = ((n_bad + n_good) * r)         / (total_bad  + eps)
+                pct_good = ((n_bad + n_good) * (1.0 - r)) / (total_good + eps)
+                woe = float(np.log((pct_bad + eps) / (pct_good + eps)))
+                woe_table.loc[idx, "BAD_PCT_PER_BIN"] = pct_bad
+                woe_table.loc[idx, "GOOD_PCT_PER_BIN"] = pct_good
+                woe_table.loc[idx, "WOE"] = woe
+                woe_table.loc[idx, "IV"] = (pct_bad - pct_good) * woe
+        if pending_merge:
+            woe_table = self._merge_sv_into_missing_master(
+                woe_table, pending_merge, missing_label,
+                total_bad, total_good, var,
+            )
+        return woe_table
+
+    def _merge_sv_into_missing_master(self, woe_table, pending_merge, missing_label,
+                                      total_bad, total_good, var):
+        """把低占比 SV 行的 bad/good 并入缺失箱行并重算 WOE。
+
+        与 ``MonotoneWOEBinner._merge_small_into_missing`` 一一对应：被合并行保留
+        自己的行，但存表 WOE 改写为缺失箱重算后的 WOE、IV 置 0，因此 transform
+        侧（``mapping_woe`` / ``convert_single_var_woe``）无需任何改动。
+        无缺失箱时降级为 neutral 并告警。
+
+        N/N_BAD/N_GOOD 是**转移**而非复制（来源行清零），保证 N 列合计不变。
+        """
+        eps = self._SV_EPS
+        if missing_label is None:
+            for idx in pending_merge:
+                warnings.warn(
+                    f"sv_small_policy='merge_missing' but {var!r} has no [Missing] bin; "
+                    f"falling back to 'neutral' for SV "
+                    f"{woe_table.loc[idx, 'MIN']!r}.",
+                    UserWarning, stacklevel=2,
+                )
+                woe_table.loc[idx, "WOE"] = 0.0
+                woe_table.loc[idx, "IV"] = 0.0
+            return woe_table
+        m = missing_label
+        add_bad  = float(woe_table.loc[pending_merge, "N_BAD"].sum())
+        add_good = float(woe_table.loc[pending_merge, "N_GOOD"].sum())
+        new_n    = int(woe_table.loc[m, "N"]) + int(woe_table.loc[pending_merge, "N"].sum())
+        new_bad  = float(woe_table.loc[m, "N_BAD"])  + add_bad
+        new_good = float(woe_table.loc[m, "N_GOOD"]) + add_good
+        pct_bad  = new_bad  / (total_bad  + eps)
+        pct_good = new_good / (total_good + eps)
+        woe = float(np.log((pct_bad + eps) / (pct_good + eps)))
+        woe_table.loc[m, "N"] = new_n
+        woe_table.loc[m, "N_BAD"] = int(new_bad)
+        woe_table.loc[m, "N_GOOD"] = int(new_good)
+        woe_table.loc[m, "AVG_BAD"] = (
+            new_bad / (new_bad + new_good) if (new_bad + new_good) > 0 else np.nan
+        )
+        woe_table.loc[m, "AVG_GOOD"] = (
+            new_good / (new_bad + new_good) if (new_bad + new_good) > 0 else np.nan
+        )
+        woe_table.loc[m, "BAD_PCT_PER_BIN"] = pct_bad
+        woe_table.loc[m, "GOOD_PCT_PER_BIN"] = pct_good
+        woe_table.loc[m, "WOE"] = woe
+        woe_table.loc[m, "IV"] = (pct_bad - pct_good) * woe
+        woe_table.loc[pending_merge, "N"] = 0
+        woe_table.loc[pending_merge, "N_BAD"] = 0
+        woe_table.loc[pending_merge, "N_GOOD"] = 0
+        woe_table.loc[pending_merge, "AVG_BAD"] = np.nan
+        woe_table.loc[pending_merge, "AVG_GOOD"] = np.nan
+        woe_table.loc[pending_merge, "LIFT"] = np.nan
+        woe_table.loc[pending_merge, "BAD_PCT_PER_BIN"] = 0.0
+        woe_table.loc[pending_merge, "GOOD_PCT_PER_BIN"] = 0.0
+        woe_table.loc[pending_merge, "WOE"] = woe
+        woe_table.loc[pending_merge, "IV"] = 0.0
+        # AVG_BAD 已被合并改写，LIFT 依赖其均值，需整表重算。
+        woe_table["LIFT"] = woe_table["AVG_BAD"] / woe_table["AVG_BAD"].mean()
+        return woe_table
 
     def _get_woe_table(self, binning_res, var, dep):
         """根据分箱结果计算WOE表。
@@ -288,8 +473,13 @@ class WOETransformer:
             woe_table, "BAD_PCT_PER_BIN", "GOOD_PCT_PER_BIN"
         )
 
-        # WOE Mapping Dictionary
         woe_table = woe_table.reset_index(drop=False)
+
+        # ── G19：低占比 SV 箱治理（与 MonotoneWOEBinner 口径对齐）──
+        if self.sv_small_policy != "keep" or self.sv_woe_smoothing != "none":
+            woe_table = self._govern_sv_bins(woe_table, var)
+
+        # WOE Mapping Dictionary
         woe_mapping_dict = dict(zip(woe_table[f"_bin_range_{var}"], woe_table["WOE"]))
 
         return woe_table, woe_mapping_dict
@@ -912,7 +1102,9 @@ def plot_monotonicity_check(data, column, title=None, include_missing=True):
 def woe_transform(train_df, var, dep, nbins, oot_df=None, chi2_config=None, tree_binning_seed=None,
                   precision=5, min_bin_prop=0.05, include_missing=False, equal_freq=True,
                   ascending=True, fillna=-999999, spec_values=None, drop_bin_info=True,
-                  ret_woe_table=True, check_monotonicity=False):
+                  ret_woe_table=True, check_monotonicity=False,
+                  sv_min_bin_size=0.0, sv_small_policy="keep",
+                  sv_woe_smoothing="none", sv_smoothing_alpha=0.0):
     """将变量转换为WOE值。
 
     对单个变量进行分箱并计算WOE值，支持训练集和验证集的转换。
@@ -954,6 +1146,14 @@ def woe_transform(train_df, var, dep, nbins, oot_df=None, chi2_config=None, tree
         是否返回WOE映射表，默认为True
     check_monotonicity : bool, optional
         是否检查单调性，默认为False
+    sv_min_bin_size : float, optional
+        低占比特殊值箱兜底阈值（占全量样本比例），默认0.0（关闭）
+    sv_small_policy : str, optional
+        'keep'（默认）/'neutral'/'merge_missing'
+    sv_woe_smoothing : str, optional
+        'none'（默认）/'laplace'
+    sv_smoothing_alpha : float, optional
+        拉普拉斯平滑强度α，默认0.0
 
     返回:
     --------
@@ -982,7 +1182,11 @@ def woe_transform(train_df, var, dep, nbins, oot_df=None, chi2_config=None, tree
         tree_binning_seed=tree_binning_seed,
         spec_values=spec_values,
         drop_bin_info=drop_bin_info,
-        ret_woe_table=ret_woe_table
+        ret_woe_table=ret_woe_table,
+        sv_min_bin_size=sv_min_bin_size,
+        sv_small_policy=sv_small_policy,
+        sv_woe_smoothing=sv_woe_smoothing,
+        sv_smoothing_alpha=sv_smoothing_alpha,
     )
     return transformer.transform_single(
         train_df=train_df,

{supermodelingfactory-0.7.2 → supermodelingfactory-0.8.0}/Modeling_Tool/WOE/WOE_Tool.pyi

@@ -23,7 +23,12 @@ def is_monotonic(data, column, direction = 'auto', strict = False, handle_nan =
 def check_monotonicity(data, var): ...
 
 class WOETransformer:
-    def __init__(self, nbins = 10, precision = 5, min_bin_prop = 0.05, include_missing = False, equal_freq = True, fillna = -999999, chi2_config = None, tree_binning_seed = None, spec_values = None, drop_bin_info = True, ret_woe_table = True): ...
+    _SV_EPS: float
+    def __init__(self, nbins = 10, precision = 5, min_bin_prop = 0.05, include_missing = False, equal_freq = True, fillna = -999999, chi2_config = None, tree_binning_seed = None, spec_values = None, drop_bin_info = True, ret_woe_table = True, sv_min_bin_size = 0.0, sv_small_policy = 'keep', sv_woe_smoothing = 'none', sv_smoothing_alpha = 0.0): ...
+    def _sv_row_mask(self, woe_table): ...
+    def _missing_row_label(self, woe_table, sv_mask): ...
+    def _govern_sv_bins(self, woe_table, var): ...
+    def _merge_sv_into_missing_master(self, woe_table, pending_merge, missing_label, total_bad, total_good, var): ...
     def _get_woe_table(self, binning_res, var, dep): ...
     def transform_single(self, train_df, var, dep, oot_df = None, check_monotonicity_flag = False): ...
     def transform(self, train_df, varlist, dep, oot_df = None, check_monotonicity_flag = False): ...
@@ -36,6 +41,6 @@ class WOEMappingTransformer:
 def woe_transform_cdaml(data, varlist, woe_mapping_path, missing_ref = None, ret_bin_no = False, ret_category = False, rename_orig_var = False, suffix = ''): ...
 def get_woe_table(data, var, dep, grp_name = None, nbins = 10, precision = 5, min_bin_prop = 0.05, include_missing = True, equal_freq = True, fillna = -999999, chi2_config = None, tree_binning_seed = None, spec_values = None): ...
 def plot_monotonicity_check(data, column, title = None, include_missing = True): ...
-def woe_transform(train_df, var, dep, nbins, oot_df = None, chi2_config = None, tree_binning_seed = None, precision = 5, min_bin_prop = 0.05, include_missing = False, equal_freq = True, ascending = True, fillna = -999999, spec_values = None, drop_bin_info = True, ret_woe_table = True, check_monotonicity = False): ...
+def woe_transform(train_df, var, dep, nbins, oot_df = None, chi2_config = None, tree_binning_seed = None, precision = 5, min_bin_prop = 0.05, include_missing = False, equal_freq = True, ascending = True, fillna = -999999, spec_values = None, drop_bin_info = True, ret_woe_table = True, check_monotonicity = False, sv_min_bin_size = 0.0, sv_small_policy = 'keep', sv_woe_smoothing = 'none', sv_smoothing_alpha = 0.0): ...
 def woe_transformation(train_df, varlist, dep, oot_df = None, nbins = 10, chi2_config = None, tree_binning_seed = None, precision = 5, min_bin_prop = 0.05, include_missing = False, equal_freq = True, fillna = -999999, spec_values = None, drop_bin_info = True, ret_woe_table = True): ...
 def mapping_woe(data, varlist, woe_mapping_table, suffix = '_woe', drop_bin_info = True, missing_ref_value = -999999): ...

{supermodelingfactory-0.7.2 → supermodelingfactory-0.8.0}/Modeling_Tool/__init__.py

@@ -1,7 +1,7 @@
 # encoding: utf-8
 
 __author__ = "Jingkai Sun"
-__version__ = "0.7.2"
+__version__ = "0.8.0"
 
 from ._utils import SMF_MISSING_BIN
 

{supermodelingfactory-0.7.2 → supermodelingfactory-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: SuperModelingFactory
-Version: 0.7.2
+Version: 0.8.0
 Summary: Credit risk modeling factory: WOE binning, scorecards, LightGBM, Excel reporting.
 Home-page: https://github.com/Kyle-J-Sun/SuperModelingFactory
 Author: Kyle Sun
@@ -265,7 +265,7 @@ em.close_workbook()
 
 ## 版本
 
-- **Version**: 0.7.2
+- **Version**: 0.8.0
 - **Author**: Jingkai Sun
 
 ## 许可证

{supermodelingfactory-0.7.2 → supermodelingfactory-0.8.0}/README.md

@@ -208,7 +208,7 @@ em.close_workbook()
 
 ## 版本
 
-- **Version**: 0.7.2
+- **Version**: 0.8.0
 - **Author**: Jingkai Sun
 
 ## 许可证

{supermodelingfactory-0.7.2 → supermodelingfactory-0.8.0}/SuperModelingFactory.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: SuperModelingFactory
-Version: 0.7.2
+Version: 0.8.0
 Summary: Credit risk modeling factory: WOE binning, scorecards, LightGBM, Excel reporting.
 Home-page: https://github.com/Kyle-J-Sun/SuperModelingFactory
 Author: Kyle Sun
@@ -265,7 +265,7 @@ em.close_workbook()
 
 ## 版本
 
-- **Version**: 0.7.2
+- **Version**: 0.8.0
 - **Author**: Jingkai Sun
 
 ## 许可证

{supermodelingfactory-0.7.2 → supermodelingfactory-0.8.0}/pyproject.toml

@@ -12,7 +12,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "SuperModelingFactory"
-version = "0.7.2"
+version = "0.8.0"
 description = "Credit risk modeling factory: WOE binning, scorecards, LightGBM, Excel reporting."
 readme = "README.md"
 requires-python = ">=3.10"

{supermodelingfactory-0.7.2 → supermodelingfactory-0.8.0}/setup.py

@@ -15,7 +15,7 @@ def _read(path: str) -> str:
 
 setup(
     name="SuperModelingFactory",
-    version=os.environ.get("SMF_VERSION", "0.7.2"),
+    version=os.environ.get("SMF_VERSION", "0.8.0"),
     description="Credit risk modeling factory: WOE binning, scorecards, LightGBM, Excel reporting.",
     long_description=_read("README.md"),
     long_description_content_type="text/markdown",