SuperModelingFactory 0.3.6__tar.gz → 0.3.7__tar.gz

{supermodelingfactory-0.3.6 → supermodelingfactory-0.3.7}/Modeling_Tool/Explainability/Model_Explainer.py

@@ -22,6 +22,7 @@ from __future__ import annotations
 import ast
 import importlib.metadata
 import sys
+import warnings
 
 import numpy as np
 import pandas as pd
@@ -848,6 +849,125 @@ class ModelExplainer:
     # ------------------------------------------------------------------ #
     # LIME
     # ------------------------------------------------------------------ #
+    @staticmethod
+    def _lime_missing_mask(frame: pd.DataFrame) -> pd.Series:
+        numeric = frame.select_dtypes(include=[np.number])
+        if numeric.empty:
+            return pd.Series(False, index=frame.index)
+        return numeric.isna().any(axis=1)
+
+    @classmethod
+    def _warn_lime_missing(
+        cls,
+        frame: pd.DataFrame,
+        *,
+        role: str,
+        missing_strategy: str,
+        n_before: int,
+        n_after: int,
+        fill_values: dict[str, float] | None = None,
+    ) -> None:
+        numeric = frame.select_dtypes(include=[np.number])
+        if numeric.empty:
+            return
+        null_cols = [col for col in numeric.columns if numeric[col].isna().any()]
+        if not null_cols:
+            return
+        details = []
+        for col in null_cols:
+            count = int(numeric[col].isna().sum())
+            pct = 100.0 * count / len(frame) if len(frame) else 0.0
+            detail = f"{col}: {count}/{len(frame)} ({pct:.1f}%)"
+            if fill_values and col in fill_values:
+                detail += f", median_fill={fill_values[col]:.6g}"
+            details.append(detail)
+        msg = (
+            f"LIME missing_strategy={missing_strategy!r} on {role}: "
+            f"null columns={null_cols}; " + "; ".join(details)
+        )
+        if missing_strategy == "drop":
+            msg += f"; rows {n_before} -> {n_after}"
+        warnings.warn(msg, UserWarning, stacklevel=3)
+
+    @classmethod
+    def _prepare_lime_data(
+        cls,
+        train: pd.DataFrame,
+        rows: pd.DataFrame | None = None,
+        *,
+        train_role: str = "X_train",
+        rows_role: str = "x_row",
+        missing_strategy: str = "median",
+    ) -> tuple[pd.DataFrame, pd.DataFrame | None]:
+        if missing_strategy not in {"median", "drop"}:
+            raise ValueError("missing_strategy must be 'median' or 'drop'")
+
+        train_clean = train.copy()
+        rows_clean = rows.copy() if rows is not None else None
+        numeric_cols = list(train_clean.select_dtypes(include=[np.number]).columns)
+
+        if missing_strategy == "median":
+            fill_values: dict[str, float] = {}
+            for col in numeric_cols:
+                if train_clean[col].isna().any() or (
+                    rows_clean is not None and rows_clean[col].isna().any()
+                ):
+                    median_val = float(train_clean[col].median())
+                    fill_values[col] = median_val
+                    train_clean[col] = train_clean[col].fillna(median_val)
+                    if rows_clean is not None:
+                        rows_clean[col] = rows_clean[col].fillna(median_val)
+            cls._warn_lime_missing(
+                train,
+                role=train_role,
+                missing_strategy=missing_strategy,
+                n_before=len(train),
+                n_after=len(train_clean),
+                fill_values=fill_values or None,
+            )
+            if rows_clean is not None:
+                cls._warn_lime_missing(
+                    rows,
+                    role=rows_role,
+                    missing_strategy=missing_strategy,
+                    n_before=len(rows),
+                    n_after=len(rows_clean),
+                    fill_values=fill_values or None,
+                )
+            return train_clean, rows_clean
+
+        n_train_before = len(train_clean)
+        train_clean = train_clean.loc[~cls._lime_missing_mask(train_clean)].copy()
+        cls._warn_lime_missing(
+            train,
+            role=train_role,
+            missing_strategy=missing_strategy,
+            n_before=n_train_before,
+            n_after=len(train_clean),
+        )
+        if train_clean.empty:
+            raise ValueError(
+                f"LIME missing_strategy='drop' removed all rows from {train_role} "
+                f"({n_train_before} -> 0). Provide complete training data or use missing_strategy='median'."
+            )
+
+        if rows_clean is not None:
+            n_rows_before = len(rows_clean)
+            rows_clean = rows_clean.loc[~cls._lime_missing_mask(rows_clean)].copy()
+            cls._warn_lime_missing(
+                rows,
+                role=rows_role,
+                missing_strategy=missing_strategy,
+                n_before=n_rows_before,
+                n_after=len(rows_clean),
+            )
+            if rows_clean.empty:
+                raise ValueError(
+                    f"LIME missing_strategy='drop' removed all rows from {rows_role} "
+                    f"({n_rows_before} -> 0). Impute missing values or use missing_strategy='median'."
+                )
+        return train_clean, rows_clean
+
     def _build_lime_explainer(self, X_train, num_features=None, random_state=None, **lime_kwargs):
         LimeTabularExplainer = _lazy_lime()
         train = self._as_frame(X_train if X_train is not None else self.background_data)
@@ -864,7 +984,16 @@ class ModelExplainer:
             **lime_kwargs,
         )
 
-    def lime_explain_instance(self, x_row, X_train=None, num_features=10, num_samples=5000, random_state=None, **lime_kwargs):
+    def lime_explain_instance(
+        self,
+        x_row,
+        X_train=None,
+        num_features=10,
+        num_samples=5000,
+        random_state=None,
+        missing_strategy="median",
+        **lime_kwargs,
+    ):
         """Explain one sample with LIME."""
         if isinstance(x_row, pd.Series):
             x_row = x_row.to_frame().T
@@ -874,7 +1003,14 @@ class ModelExplainer:
         if frame.shape[0] != 1:
             frame = frame.iloc[[0]]
 
-        train = X_train if X_train is not None else self.background_data
+        train_raw = self._as_frame(X_train if X_train is not None else self.background_data)
+        train, frame = self._prepare_lime_data(
+            train_raw,
+            frame,
+            train_role="X_train",
+            rows_role="x_row",
+            missing_strategy=missing_strategy,
+        )
         explainer = self._build_lime_explainer(train, num_features, random_state, **lime_kwargs)
         explanation = explainer.explain_instance(
             data_row=np.asarray(frame.iloc[0]),
@@ -896,17 +1032,36 @@ class ModelExplainer:
         out.attrs["score"] = explanation.score
         return out
 
-    def lime_global_importance(self, X, X_train=None, num_features=10, num_samples=2000, sample_size=100, random_state=None, **lime_kwargs):
+    def lime_global_importance(
+        self,
+        X,
+        X_train=None,
+        num_features=10,
+        num_samples=2000,
+        sample_size=100,
+        random_state=None,
+        missing_strategy="median",
+        **lime_kwargs,
+    ):
         """Aggregate LIME local weights across a sample as global importance."""
+        train_raw = self._as_frame(X_train if X_train is not None else self.background_data)
         frame = self._sample_frame(X, sample_size=sample_size, random_state=random_state)
+        train, frame = self._prepare_lime_data(
+            train_raw,
+            frame,
+            train_role="X_train",
+            rows_role="X",
+            missing_strategy=missing_strategy,
+        )
         rows = []
         for _, row in frame.iterrows():
             local = self.lime_explain_instance(
                 row,
-                X_train=X_train,
+                X_train=train,
                 num_features=num_features,
                 num_samples=num_samples,
                 random_state=random_state,
+                missing_strategy="median",
                 **lime_kwargs,
             )
             rows.append(local)

{supermodelingfactory-0.3.6 → supermodelingfactory-0.3.7}/Modeling_Tool/Pipeline/_common.py

@@ -150,6 +150,132 @@ def safe_to_csv(df: pd.DataFrame | None, path: str | os.PathLike, index: bool =
     df.to_csv(path, index=index)
 
 
+def persist_explain_outputs(
+    outputs: Mapping[str, Any],
+    explain_dir: str | os.PathLike,
+) -> dict[str, dict[str, str]]:
+    """Write explain_outputs tables to ``explain_dir`` and return path index."""
+    explain_root = Path(explain_dir)
+    explain_root.mkdir(parents=True, exist_ok=True)
+    manifest_rows: list[dict[str, str]] = []
+    explain_paths: dict[str, dict[str, str]] = {}
+
+    if "import_error" in outputs:
+        err_path = explain_root / "import_error.txt"
+        err_path.write_text(str(outputs["import_error"]), encoding="utf-8")
+        manifest_rows.append(
+            {"model": "_global", "artifact": "import_error", "path": str(err_path), "status": "error"}
+        )
+
+    for model_name, payload in outputs.items():
+        if model_name == "import_error":
+            continue
+        if not isinstance(payload, dict):
+            continue
+        model_dir = explain_root / str(model_name)
+        paths: dict[str, str] = {}
+
+        if payload.get("error") and "feature_importance" not in payload:
+            err_path = model_dir / "error.txt"
+            model_dir.mkdir(parents=True, exist_ok=True)
+            err_path.write_text(str(payload["error"]), encoding="utf-8")
+            paths["error"] = str(err_path)
+            manifest_rows.append(
+                {
+                    "model": str(model_name),
+                    "artifact": "error",
+                    "path": str(err_path),
+                    "status": "error",
+                }
+            )
+            explain_paths[str(model_name)] = paths
+            continue
+
+        fi = payload.get("feature_importance")
+        if isinstance(fi, pd.DataFrame) and not fi.empty:
+            fi_path = model_dir / "feature_importance.csv"
+            safe_to_csv(fi, fi_path)
+            paths["feature_importance"] = str(fi_path)
+            manifest_rows.append(
+                {
+                    "model": str(model_name),
+                    "artifact": "feature_importance",
+                    "path": str(fi_path),
+                    "status": "ok",
+                }
+            )
+
+        owen = payload.get("owen")
+        if isinstance(owen, dict):
+            if owen.get("error"):
+                err_path = model_dir / "owen_error.txt"
+                model_dir.mkdir(parents=True, exist_ok=True)
+                err_path.write_text(str(owen["error"]), encoding="utf-8")
+                paths["owen_error"] = str(err_path)
+                manifest_rows.append(
+                    {
+                        "model": str(model_name),
+                        "artifact": "owen_error",
+                        "path": str(err_path),
+                        "status": "error",
+                    }
+                )
+            for artifact, filename in (
+                ("feature_importance", "owen_feature_importance.csv"),
+                ("group_importance", "owen_group_importance.csv"),
+            ):
+                table = owen.get(artifact)
+                if isinstance(table, pd.DataFrame) and not table.empty:
+                    table_path = model_dir / filename
+                    safe_to_csv(table, table_path)
+                    key = f"owen_{artifact}"
+                    paths[key] = str(table_path)
+                    manifest_rows.append(
+                        {
+                            "model": str(model_name),
+                            "artifact": key,
+                            "path": str(table_path),
+                            "status": "ok",
+                        }
+                    )
+
+        for artifact_key in ("shap_summary", "plot_error"):
+            plot_path = payload.get(artifact_key)
+            if plot_path and artifact_key == "shap_summary":
+                paths["shap_summary"] = str(plot_path)
+                manifest_rows.append(
+                    {
+                        "model": str(model_name),
+                        "artifact": "shap_summary",
+                        "path": str(plot_path),
+                        "status": "ok",
+                    }
+                )
+            elif plot_path and artifact_key == "plot_error":
+                err_path = model_dir / "plot_error.txt"
+                model_dir.mkdir(parents=True, exist_ok=True)
+                err_path.write_text(str(plot_path), encoding="utf-8")
+                paths["plot_error"] = str(err_path)
+                manifest_rows.append(
+                    {
+                        "model": str(model_name),
+                        "artifact": "plot_error",
+                        "path": str(err_path),
+                        "status": "plot_error",
+                    }
+                )
+
+        if paths:
+            explain_paths[str(model_name)] = paths
+
+    if manifest_rows:
+        manifest_df = pd.DataFrame(manifest_rows)
+        safe_to_csv(manifest_df, explain_root / "explain_manifest.csv", index=False)
+        explain_paths.setdefault("_manifest", {})["explain_manifest"] = str(explain_root / "explain_manifest.csv")
+
+    return explain_paths
+
+
 def get_raw_model(model: Any) -> Any:
     if hasattr(model, "_model") and hasattr(model._model, "model"):
         return model._model.model

{supermodelingfactory-0.3.6 → supermodelingfactory-0.3.7}/Modeling_Tool/Pipeline/credit_model.py

@@ -13,6 +13,7 @@ from ._common import (
     as_list,
     make_dirs,
     merge_dict,
+    persist_explain_outputs,
     predict_positive,
     safe_to_csv,
     validate_woe_fit_query_columns,
@@ -106,6 +107,7 @@ class CreditModelPipelineResult:
     optuna_results: dict[str, pd.DataFrame] = field(default_factory=dict)
     perf_results: dict[str, pd.DataFrame] = field(default_factory=dict)
     explain_outputs: dict[str, Any] = field(default_factory=dict)
+    explain_paths: dict[str, dict[str, str]] = field(default_factory=dict)
     report_path: str | None = None
     lr_search_results: pd.DataFrame | None = None
     warm_start_summary: pd.DataFrame | None = None
@@ -173,13 +175,15 @@ class CreditModelPipeline:
 
         output_dir = Path(cfg.output_dir)
         if cfg.write_outputs or cfg.write_excel:
-            make_dirs(
+            dirs = [
                 output_dir,
                 output_dir / "figs" / "woe",
                 output_dir / "figs" / "mono_woe",
                 output_dir / "figs" / "perf",
-                output_dir / "explain",
-            )
+            ]
+            if cfg.write_outputs and self._will_run_explainability():
+                dirs.append(output_dir / "explain")
+            make_dirs(*dirs)
         if cfg.save_models:
             make_dirs(self._model_output_dir(), output_dir / "artifacts")
 
@@ -219,6 +223,9 @@ class CreditModelPipeline:
             woe_artifacts.get("extra_eval"),
         )
         explain_outputs = self._run_explainability(model_inputs, models)
+        explain_paths: dict[str, dict[str, str]] = {}
+        if cfg.write_outputs and explain_outputs:
+            explain_paths = persist_explain_outputs(explain_outputs, output_dir / "explain")
         model_paths: dict[str, str] = {}
         artifact_paths: dict[str, str] = {}
         model_paths_frame = None
@@ -261,6 +268,7 @@ class CreditModelPipeline:
             }
             for name, perf in perf_results.items():
                 sheets[f"Perf_{name.upper()}"] = perf
+            sheets.update(self._explain_excel_sheets(explain_outputs))
             write_basic_excel(report_path, sheets, title="SuperModelingFactory Credit Model Pipeline Report")
 
         return CreditModelPipelineResult(
@@ -273,6 +281,7 @@ class CreditModelPipeline:
             optuna_results=optuna_results,
             perf_results=perf_results,
             explain_outputs=explain_outputs,
+            explain_paths=explain_paths,
             report_path=report_path,
             lr_search_results=lr_search_results,
             warm_start_summary=warm_start_summary,
@@ -977,6 +986,28 @@ class CreditModelPipeline:
             return wrapper.predict_with_base_margin(data[feature_cols], init_score, return_prob=True)
         return predict_positive(wrapper, data, feature_cols)
 
+    def _will_run_explainability(self) -> bool:
+        cfg = self.config
+        return bool(as_list(cfg.explain_models)) or bool(cfg.owen_enabled)
+
+    def _explain_excel_sheets(self, explain_outputs: dict[str, Any]) -> dict[str, pd.DataFrame]:
+        sheets: dict[str, pd.DataFrame] = {}
+        for model_name, payload in explain_outputs.items():
+            if model_name == "import_error" or not isinstance(payload, dict):
+                continue
+            fi = payload.get("feature_importance")
+            if isinstance(fi, pd.DataFrame) and not fi.empty:
+                sheets[f"Explain_{str(model_name).upper()}_FI"] = fi
+            owen = payload.get("owen")
+            if isinstance(owen, dict):
+                owen_fi = owen.get("feature_importance")
+                if isinstance(owen_fi, pd.DataFrame) and not owen_fi.empty:
+                    sheets[f"Explain_{str(model_name).upper()}_Owen_FI"] = owen_fi
+                owen_grp = owen.get("group_importance")
+                if isinstance(owen_grp, pd.DataFrame) and not owen_grp.empty:
+                    sheets[f"Explain_{str(model_name).upper()}_Owen_Group"] = owen_grp
+        return sheets
+
     def _run_explainability(
         self,
         model_inputs: dict[str, dict[str, Any]],
@@ -987,6 +1018,7 @@ class CreditModelPipeline:
         if not explain_models and not cfg.owen_enabled:
             return {}
         outputs: dict[str, Any] = {}
+        explain_dir = Path(cfg.output_dir) / "explain"
         try:
             from Modeling_Tool import ModelExplainer
         except Exception as exc:
@@ -1005,6 +1037,14 @@ class CreditModelPipeline:
                 item: dict[str, Any] = {}
                 if name in explain_models:
                     item["feature_importance"] = exp.feature_importance(X=eval_x, normalize=True)
+                    if cfg.write_outputs and cfg.plot_outputs:
+                        plot_path = explain_dir / name / "shap_summary.png"
+                        plot_path.parent.mkdir(parents=True, exist_ok=True)
+                        try:
+                            exp.summary_plot(X=eval_x, show=False, save_path=str(plot_path))
+                            item["shap_summary"] = str(plot_path)
+                        except Exception as plot_exc:
+                            item["plot_error"] = repr(plot_exc)
                 if cfg.owen_enabled and name != "xgb":
                     item["owen"] = self._run_owen(exp, eval_x, feature_cols)
                 outputs[name] = item

{supermodelingfactory-0.3.6 → supermodelingfactory-0.3.7}/Modeling_Tool/__init__.py

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

{supermodelingfactory-0.3.6 → supermodelingfactory-0.3.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: SuperModelingFactory
-Version: 0.3.6
+Version: 0.3.7
 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.3.6
+- **Version**: 0.3.7
 - **Author**: Jingkai Sun
 
 ## 许可证

{supermodelingfactory-0.3.6 → supermodelingfactory-0.3.7}/README.md

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

{supermodelingfactory-0.3.6 → supermodelingfactory-0.3.7}/SuperModelingFactory.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: SuperModelingFactory
-Version: 0.3.6
+Version: 0.3.7
 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.3.6
+- **Version**: 0.3.7
 - **Author**: Jingkai Sun
 
 ## 许可证

{supermodelingfactory-0.3.6 → supermodelingfactory-0.3.7}/pyproject.toml

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

{supermodelingfactory-0.3.6 → supermodelingfactory-0.3.7}/setup.py

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