SuperModelingFactory 0.4.2__tar.gz → 0.5.0__tar.gz

{supermodelingfactory-0.4.2 → supermodelingfactory-0.5.0}/Modeling_Tool/Feature/PSI_Tool.py

@@ -58,7 +58,8 @@ class PSICalculator:
         equal_freq: bool = True,
         min_bin_prop: float = 0.05,
         content: float = 1e-6,
-        precision: int = 5
+        precision: int = 5,
+        missing_policy: str = "include"
     ):
         """
         Initialize PSICalculator with configuration parameters.
@@ -75,12 +76,26 @@ class PSICalculator:
             Small value to prevent division by zero. Default is 1e-6.
         precision : int, optional
             Decimal precision for rounding. Default is 5.
+        missing_policy : {"drop", "include", "warn_and_drop"}, optional
+            How NaN rows are handled. Default in 0.5.0 is "include", which routes
+            NaN rows through a dedicated "__MISSING__" bin so missing-rate drift
+            contributes to the PSI. This is the recommended production behaviour
+            and became the default in 0.5.0 (previously "drop" in 0.4.2 for
+            numeric backward-compat). Pass "drop" to reproduce pre-0.5.0
+            numbers, or "warn_and_drop" for legacy numbers with a RuntimeWarning
+            naming the NaN counts.
         """
+        if missing_policy not in {"include", "drop", "warn_and_drop"}:
+            raise ValueError(
+                f"PSICalculator.__init__: missing_policy must be one of "
+                f"'include', 'drop', 'warn_and_drop'; got {missing_policy!r}."
+            )
         self.buckets = buckets
         self.equal_freq = equal_freq
         self.min_bin_prop = min_bin_prop
         self.content = content
         self.precision = precision
+        self.missing_policy = missing_policy
     
 #     def _calculate_single_psi(
 #         self,
@@ -418,7 +433,8 @@ class PSICalculator:
         varlist: List[str],
         group_by: Optional[str] = None,
         group_name: Optional[str] = None,
-        return_details = False
+        return_details = False,
+        missing_policy: Optional[str] = None
     ) -> pd.DataFrame:
         """
         Calculate grouped PSI comparing two datasets, using expected as benchmark.
@@ -435,12 +451,18 @@ class PSICalculator:
             Column to group by in both datasets.
         group_name : str, optional
             Specific group column name for multi-group calculation.
+        missing_policy : {"drop", "include", "warn_and_drop"}, optional
+            How NaN rows are handled. If None (default), falls back to the value
+            configured on ``self.missing_policy``. Pass an explicit value to
+            override the class-level default for this call only. See
+            ``PSICalculator.__init__`` for the semantics of each mode.
             
         Returns
         -------
         pandas.DataFrame
             Grouped PSI results.
         """
+        effective_policy = missing_policy if missing_policy is not None else self.missing_policy
         return calculate_multigroup_psi_two_sets(
             expected_df = expected_df,
             actual_df = current_data,
@@ -452,7 +474,8 @@ class PSICalculator:
             content = self.content,
             precision = self.precision,
             group_name = group_name,
-            return_details = return_details
+            return_details = return_details,
+            missing_policy = effective_policy
         )
 
 
@@ -469,7 +492,7 @@ def _calculate_single_psi(
     min_bin_prop: float = 0.05,
     content: float = 1e-6,
     precision: int = 5,
-    missing_policy: str = "drop",
+    missing_policy: str = "include",
 ) -> Union[float, Tuple[float, pd.DataFrame]]:
     """
     Calculate Population Stability Index (PSI) for a single variable.
@@ -652,7 +675,8 @@ def calculate_psi(
     return_details: bool = False,
     min_bin_prop: float = 0.05,
     content: float = 1e-6,
-    precision: int = 5
+    precision: int = 5,
+    missing_policy: str = "include"
 ) -> Union[float, pd.DataFrame, Tuple[Dict, Dict]]:
     """
     Calculate Population Stability Index (PSI) for a variable, optionally by groups.
@@ -682,6 +706,14 @@ def calculate_psi(
         Small value to avoid division by zero. Default is 1e-6.
     precision : int, optional
         Decimal precision. Default is 5.
+    missing_policy : {"drop", "include", "warn_and_drop"}, optional
+        How NaN rows are handled. Default in 0.5.0 is "include", which routes
+        NaN rows through a dedicated "__MISSING__" bin so missing-rate drift
+        contributes to the PSI. This is the recommended production behaviour
+        and became the default in 0.5.0 (previously "drop" in 0.4.2 for
+        numeric backward-compat). Pass "drop" to reproduce pre-0.5.0
+        numbers, or "warn_and_drop" for legacy numbers with a RuntimeWarning
+        naming the NaN counts.
         
     Returns
     -------
@@ -734,7 +766,8 @@ def calculate_psi(
                     True,
                     min_bin_prop,
                     content,
-                    precision
+                    precision,
+                    missing_policy
                 )
                 results[group] = psi_value
                 details_dict[group] = detail
@@ -747,7 +780,8 @@ def calculate_psi(
                     False,
                     min_bin_prop,
                     content,
-                    precision
+                    precision,
+                    missing_policy
                 )
         
         if return_details:
@@ -765,7 +799,8 @@ def calculate_psi(
                 True, 
                 min_bin_prop, 
                 content, 
-                precision
+                precision,
+                missing_policy
             )
         else:
             return _calculate_single_psi(
@@ -776,7 +811,8 @@ def calculate_psi(
                 False, 
                 min_bin_prop, 
                 content, 
-                precision
+                precision,
+                missing_policy
             )
 
 
@@ -791,7 +827,8 @@ def calculate_within_psi(
     min_bin_prop: float = 0.05,
     content: float = 1e-6,
     precision: int = 5,
-    benchmark_display_name: Optional[str] = None
+    benchmark_display_name: Optional[str] = None,
+    missing_policy: str = "include"
 ) -> Union[pd.DataFrame, Dict]:
     """
     Calculate PSI values within a single dataset, comparing groups to a benchmark.
@@ -823,6 +860,14 @@ def calculate_within_psi(
         Decimal precision. Default is 5.
     benchmark_display_name : str, optional
         Custom name for benchmark in results.
+    missing_policy : {"drop", "include", "warn_and_drop"}, optional
+        How NaN rows are handled. Default in 0.5.0 is "include", which routes
+        NaN rows through a dedicated "__MISSING__" bin so missing-rate drift
+        contributes to the PSI. This is the recommended production behaviour
+        and became the default in 0.5.0 (previously "drop" in 0.4.2 for
+        numeric backward-compat). Pass "drop" to reproduce pre-0.5.0
+        numbers, or "warn_and_drop" for legacy numbers with a RuntimeWarning
+        naming the NaN counts.
         
     Returns
     -------
@@ -858,7 +903,8 @@ def calculate_within_psi(
                 return_details=True, 
                 min_bin_prop=min_bin_prop, 
                 content=content, 
-                precision=precision
+                precision=precision,
+                missing_policy=missing_policy
             )
             res_dict[obs_value] = psi
             detail_dict[obs_value] = details
@@ -872,7 +918,8 @@ def calculate_within_psi(
                 return_details=False, 
                 min_bin_prop=min_bin_prop, 
                 content=content, 
-                precision=precision
+                precision=precision,
+                missing_policy=missing_policy
             )
             res_dict[obs_value] = psi
     
@@ -895,7 +942,8 @@ def calculate_psi_within_dataset(
     buckets: int = 10,
     min_bin_prop: float = 0.05,
     content: float = 1e-6,
-    precision: int = 5
+    precision: int = 5,
+    missing_policy: str = "include"
 ) -> pd.DataFrame:
     """
     Calculate PSI for multiple variables within a dataset, comparing groups to a benchmark.
@@ -923,6 +971,14 @@ def calculate_psi_within_dataset(
         Small value to avoid division by zero. Default is 1e-6.
     precision : int, optional
         Decimal precision. Default is 5.
+    missing_policy : {"drop", "include", "warn_and_drop"}, optional
+        How NaN rows are handled. Default in 0.5.0 is "include", which routes
+        NaN rows through a dedicated "__MISSING__" bin so missing-rate drift
+        contributes to the PSI. This is the recommended production behaviour
+        and became the default in 0.5.0 (previously "drop" in 0.4.2 for
+        numeric backward-compat). Pass "drop" to reproduce pre-0.5.0
+        numbers, or "warn_and_drop" for legacy numbers with a RuntimeWarning
+        naming the NaN counts.
         
     Returns
     -------
@@ -946,7 +1002,8 @@ def calculate_psi_within_dataset(
             return_details=False, 
             min_bin_prop=min_bin_prop, 
             content=content, 
-            precision=precision
+            precision=precision,
+            missing_policy=missing_policy
         ).sort_values([grp_name]).reset_index(drop=True)
         
         single_psi['var'] = var
@@ -964,7 +1021,8 @@ def calculate_multivar_psi_two_sets(
     equal_freq: bool = True,
     min_bin_prop: float = 0.05,
     content: float = 1e-6,
-    precision: int = 5
+    precision: int = 5,
+    missing_policy: str = "include"
 ) -> pd.DataFrame:
     """
     Calculate PSI for multiple variables by comparing two different datasets.
@@ -992,6 +1050,14 @@ def calculate_multivar_psi_two_sets(
         Small value to avoid division by zero. Default is 1e-6.
     precision : int, optional
         Decimal precision. Default is 5.
+    missing_policy : {"drop", "include", "warn_and_drop"}, optional
+        How NaN rows are handled. Default in 0.5.0 is "include", which routes
+        NaN rows through a dedicated "__MISSING__" bin so missing-rate drift
+        contributes to the PSI. This is the recommended production behaviour
+        and became the default in 0.5.0 (previously "drop" in 0.4.2 for
+        numeric backward-compat). Pass "drop" to reproduce pre-0.5.0
+        numbers, or "warn_and_drop" for legacy numbers with a RuntimeWarning
+        naming the NaN counts.
         
     Returns
     -------
@@ -1011,7 +1077,8 @@ def calculate_multivar_psi_two_sets(
             target_col=var, 
             group_by=group_by, 
             buckets=buckets,
-            return_details=False
+            return_details=False,
+            missing_policy=missing_policy
         )
         if group_by is None:
             single_psi = pd.DataFrame([single_psi], columns=['psi'])
@@ -1151,7 +1218,8 @@ def calculate_multigroup_psi_two_sets(
     content: float = 1e-6,
     precision: int = 5,
     group_name: Optional[str] = None,
-    return_details: bool = False
+    return_details: bool = False,
+    missing_policy: str = "include"
 ) -> Union[pd.DataFrame, Dict[str, pd.DataFrame]]:
     """
     Calculate grouped PSI using expected DataFrame as benchmark, applied to actual DataFrame groups.
@@ -1181,6 +1249,12 @@ def calculate_multigroup_psi_two_sets(
     return_details : bool, optional
         是否返回详细分箱信息。若为 True，返回字典 {'psi': psi_df, 'details': details_df}，
         details_df 包含列：['bin', 'expected_percent', 'actual_percent', 'psi_component', group_name, 'var']
+    missing_policy : {"drop", "include", "warn_and_drop"}, optional
+        NaN 行处理策略。0.5.0 起默认为 "include"，将 NaN 行汇入独立的
+        "__MISSING__" 桶，使缺失率漂移进入 PSI 计算；这是推荐的生产行为，
+        并在 0.5.0 成为默认值（0.4.2 为 "drop" 以保持数值向后兼容）。
+        传入 "drop" 可复现 0.5.0 之前的数值，或 "warn_and_drop" 保留旧数值
+        同时发出 RuntimeWarning 报告两侧 NaN 数量。
     """
     if group_name is not None:
         if actual_df[group_name].isna().sum() > 0:
@@ -1203,7 +1277,8 @@ def calculate_multigroup_psi_two_sets(
                         return_details=True,
                         min_bin_prop=min_bin_prop,
                         content=content,
-                        precision=precision
+                        precision=precision,
+                        missing_policy=missing_policy
                     )
                     
                     psi_records.append({group_name: group, 'var': var, 'psi': psi_val})
@@ -1250,7 +1325,8 @@ def calculate_multigroup_psi_two_sets(
                     return_details=True,
                     min_bin_prop=min_bin_prop,
                     content=content,
-                    precision=precision
+                    precision=precision,
+                    missing_policy=missing_policy
                 )
                 psi_records.append({'var': var, 'psi': psi_val})
                 
@@ -1285,7 +1361,8 @@ def calculate_multigroup_psi_two_sets(
                 equal_freq=equal_freq, 
                 min_bin_prop=min_bin_prop, 
                 content=content, 
-                precision=precision
+                precision=precision,
+                missing_policy=missing_policy
             )
             
             return group_psi

{supermodelingfactory-0.4.2 → supermodelingfactory-0.5.0}/Modeling_Tool/WOE/WOE_Monotone_Binner.py

@@ -257,6 +257,11 @@ class MonotoneWOEBinner:
         # }}
         self._results: Dict[str, Any] = {}
         self._is_fitted = False
+        # N38 (0.5.0): populated by apply_woe when unseen categorical values are
+        # observed in transform data. Keys are feature names; each value is a
+        # dict with unseen_values/affected_rows/affected_frac/total_rows.
+        # Reset at the start of every apply_woe call.
+        self._unseen_category_stats: Dict[str, dict] = {}
 
     # ─────────────────────────────────────────────────────────────────
     # 内部工具
@@ -2047,6 +2052,7 @@ class MonotoneWOEBinner:
         data: pd.DataFrame,
         suffix: str = "_woe",
         inplace: bool = False,
+        unseen_category_policy: str = "warn",
     ) -> pd.DataFrame:
         """
         将 data 中的特征原始数值转换为 WOE 值，添加 *_woe 列。
@@ -2066,14 +2072,39 @@ class MonotoneWOEBinner:
         data    : 含原始特征列的 DataFrame
         suffix  : WOE 列后缀，默认 "_woe"
         inplace : 是否在原 DataFrame 上操作（False = 返回副本）
+        unseen_category_policy : {"warn", "raise", "silent"}, optional
+            How to handle transform-time categorical values not seen at fit
+            time. Default in 0.5.0 is ``"warn"``, which fills the unseen
+            value with ``missing_woe`` (same as previous behaviour) but
+            emits a ``RuntimeWarning`` per feature listing the unseen
+            categories and affected row count, and populates
+            ``self._unseen_category_stats`` for programmatic monitoring.
+            Pass ``"raise"`` to fail loudly on first unseen category, or
+            ``"silent"`` to reproduce the pre-0.5.0 fully-silent behaviour.
+
+        Attributes populated
+        --------------------
+        _unseen_category_stats : Dict[str, dict]
+            Keys are feature names that saw at least one unseen category in
+            the most recent ``apply_woe`` call. Each value is
+            ``{"unseen_values": set, "affected_rows": int,
+            "affected_frac": float, "total_rows": int}``. Reset at the
+            start of every ``apply_woe`` call.
 
         Returns
         -------
         DataFrame，新增 {feat}{suffix} 列
         """
+        if unseen_category_policy not in {"warn", "raise", "silent"}:
+            raise ValueError(
+                f"apply_woe: unseen_category_policy must be one of "
+                f"'warn', 'raise', 'silent'; got {unseen_category_policy!r}."
+            )
         self._check_fitted()
         df = data if inplace else data.copy()
         woe_outputs: Dict[str, np.ndarray] = {}
+        # Reset per-call so callers can inspect stats from the *latest* run only.
+        self._unseen_category_stats = {}
 
         for feat, vr in self._results.items():
             if feat not in df.columns:
@@ -2109,6 +2140,51 @@ class MonotoneWOEBinner:
 
             # ── 类别特征：按取值直接查 WOE，不做区间切分 ──
             if vr.get("is_categorical"):
+                # N38 (0.5.0): detect transform-time categories that were not
+                # seen at fit time so drift on categorical features is visible.
+                if unseen_category_policy != "silent":
+                    fit_categories = set(vr.get("categories", []) or [])
+                    if fit_categories:
+                        observed = set(series.dropna().unique().tolist())
+                        unseen = observed - fit_categories
+                        if unseen:
+                            affected_mask = series.isin(unseen)
+                            affected_rows = int(affected_mask.sum())
+                            total_rows = int(len(series))
+                            stats = {
+                                "unseen_values": unseen,
+                                "affected_rows": affected_rows,
+                                "affected_frac": affected_rows / max(total_rows, 1),
+                                "total_rows": total_rows,
+                            }
+                            self._unseen_category_stats[feat] = stats
+                            try:
+                                unseen_preview = sorted(unseen)[:5]
+                            except TypeError:
+                                unseen_preview = list(unseen)[:5]
+                            more_suffix = "..." if len(unseen) > 5 else ""
+                            if unseen_category_policy == "raise":
+                                raise ValueError(
+                                    f"apply_woe: feature {feat!r} has "
+                                    f"{len(unseen)} unseen categories in "
+                                    f"transform data: {unseen_preview}{more_suffix}. "
+                                    f"{affected_rows}/{total_rows} rows affected "
+                                    f"({stats['affected_frac']:.1%}). "
+                                    f"Pass unseen_category_policy='warn' to fill "
+                                    f"with missing_woe and warn, or 'silent' for "
+                                    f"legacy behaviour."
+                                )
+                            else:  # "warn"
+                                warnings.warn(
+                                    f"apply_woe: feature {feat!r} has "
+                                    f"{len(unseen)} unseen categories in "
+                                    f"transform data: {unseen_preview}{more_suffix}. "
+                                    f"Filling with missing_woe={feat_missing_woe}. "
+                                    f"{affected_rows}/{total_rows} rows affected "
+                                    f"({stats['affected_frac']:.1%}).",
+                                    RuntimeWarning,
+                                    stacklevel=2,
+                                )
                 wt = vr["woe_table"]
                 # 原始取值 → WOE（fit 路径，精确匹配；int/float 由 dict 等价性兼容）
                 # refine_cate 聚类后，一个箱含多个类别(cat_members)；逐成员展开建表

{supermodelingfactory-0.4.2 → supermodelingfactory-0.5.0}/Modeling_Tool/__init__.py

@@ -1,7 +1,7 @@
 # encoding: utf-8
 
 __author__ = "Jingkai Sun"
-__version__ = "0.4.2"
+__version__ = "0.5.0"
 
 # Core module - base data structures
 from .Core import (

{supermodelingfactory-0.4.2 → supermodelingfactory-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: SuperModelingFactory
-Version: 0.4.2
+Version: 0.5.0
 Summary: Credit risk modeling factory: WOE binning, scorecards, LightGBM, Excel reporting.
 Home-page: https://github.com/Kyle-J-Sun/SuperModelingFactory
 Author: Kyle Sun

{supermodelingfactory-0.4.2 → supermodelingfactory-0.5.0}/SuperModelingFactory.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: SuperModelingFactory
-Version: 0.4.2
+Version: 0.5.0
 Summary: Credit risk modeling factory: WOE binning, scorecards, LightGBM, Excel reporting.
 Home-page: https://github.com/Kyle-J-Sun/SuperModelingFactory
 Author: Kyle Sun

{supermodelingfactory-0.4.2 → supermodelingfactory-0.5.0}/pyproject.toml

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

{supermodelingfactory-0.4.2 → supermodelingfactory-0.5.0}/setup.py

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