ins-pricing 0.1.11__py3-none-any.whl → 0.2.0__py3-none-any.whl

ins_pricing/modelling/{bayesopt → core/bayesopt}/core.py

@@ -3,62 +3,50 @@ from __future__ import annotations
 from dataclasses import asdict
 from datetime import datetime
 import os
+from pathlib import Path
 from typing import Any, Dict, List, Optional
-
-try:  # matplotlib is optional; avoid hard import failures in headless/minimal envs
-    import matplotlib
-    if os.name != "nt" and not os.environ.get("DISPLAY") and not os.environ.get("MPLBACKEND"):
-        matplotlib.use("Agg")
-    import matplotlib.pyplot as plt
-    _MPL_IMPORT_ERROR: Optional[BaseException] = None
-except Exception as exc:  # pragma: no cover - optional dependency
-    plt = None  # type: ignore[assignment]
-    _MPL_IMPORT_ERROR = exc
 import numpy as np
 import pandas as pd
 import torch
-import statsmodels.api as sm
-from sklearn.model_selection import ShuffleSplit
+from sklearn.model_selection import GroupKFold, ShuffleSplit, TimeSeriesSplit
 from sklearn.preprocessing import StandardScaler
 
 from .config_preprocess import BayesOptConfig, DatasetPreprocessor, OutputManager, VersionManager
+from .model_explain_mixin import BayesOptExplainMixin
+from .model_plotting_mixin import BayesOptPlottingMixin
 from .models import GraphNeuralNetSklearn
 from .trainers import FTTrainer, GLMTrainer, GNNTrainer, ResNetTrainer, XGBTrainer
-from .utils import EPS, PlotUtils, infer_factor_and_cate_list, set_global_seed
-try:
-    from ..plotting import curves as plot_curves
-    from ..plotting import diagnostics as plot_diagnostics
-    from ..plotting.common import PlotStyle, finalize_figure
-    from ..explain import gradients as explain_gradients
-    from ..explain import permutation as explain_permutation
-    from ..explain import shap_utils as explain_shap
-except Exception:  # pragma: no cover - optional for legacy imports
-    try:  # best-effort for non-package imports
-        from ins_pricing.plotting import curves as plot_curves
-        from ins_pricing.plotting import diagnostics as plot_diagnostics
-        from ins_pricing.plotting.common import PlotStyle, finalize_figure
-        from ins_pricing.explain import gradients as explain_gradients
-        from ins_pricing.explain import permutation as explain_permutation
-        from ins_pricing.explain import shap_utils as explain_shap
-    except Exception:  # pragma: no cover
-        plot_curves = None
-        plot_diagnostics = None
-        PlotStyle = None
-        finalize_figure = None
-        explain_gradients = None
-        explain_permutation = None
-        explain_shap = None
-
-
-def _plot_skip(label: str) -> None:
-    if _MPL_IMPORT_ERROR is not None:
-        print(f"[Plot] Skip {label}: matplotlib unavailable ({_MPL_IMPORT_ERROR}).", flush=True)
-    else:
-        print(f"[Plot] Skip {label}: matplotlib unavailable.", flush=True)
+from .utils import EPS, infer_factor_and_cate_list, set_global_seed
+
+
+class _CVSplitter:
+    """Wrapper to carry optional groups or time order for CV splits."""
+
+    def __init__(
+        self,
+        splitter,
+        *,
+        groups: Optional[pd.Series] = None,
+        order: Optional[np.ndarray] = None,
+    ) -> None:
+        self._splitter = splitter
+        self._groups = groups
+        self._order = order
+
+    def split(self, X, y=None, groups=None):
+        if self._order is not None:
+            order = np.asarray(self._order)
+            X_ord = X.iloc[order] if hasattr(X, "iloc") else X[order]
+            for tr_idx, val_idx in self._splitter.split(X_ord, y=y):
+                yield order[tr_idx], order[val_idx]
+            return
+        use_groups = groups if groups is not None else self._groups
+        for tr_idx, val_idx in self._splitter.split(X, y=y, groups=use_groups):
+            yield tr_idx, val_idx
 
 # BayesOpt orchestration and SHAP utilities
 # =============================================================================
-class BayesOptModel:
+class BayesOptModel(BayesOptPlottingMixin, BayesOptExplainMixin):
     def __init__(self, train_data, test_data,
                  model_nme, resp_nme, weight_nme, factor_nmes: Optional[List[str]] = None, task_type='regression',
                  binary_resp_nme=None,
@@ -89,7 +77,32 @@ class BayesOptModel:
                  final_refit: bool = True,
                  optuna_storage: Optional[str] = None,
                  optuna_study_prefix: Optional[str] = None,
-                 best_params_files: Optional[Dict[str, str]] = None):
+                 best_params_files: Optional[Dict[str, str]] = None,
+                 cv_strategy: Optional[str] = None,
+                 cv_splits: Optional[int] = None,
+                 cv_group_col: Optional[str] = None,
+                 cv_time_col: Optional[str] = None,
+                 cv_time_ascending: bool = True,
+                 ft_oof_folds: Optional[int] = None,
+                 ft_oof_strategy: Optional[str] = None,
+                 ft_oof_shuffle: bool = True,
+                 save_preprocess: bool = False,
+                 preprocess_artifact_path: Optional[str] = None,
+                 plot_path_style: Optional[str] = None,
+                 bo_sample_limit: Optional[int] = None,
+                 cache_predictions: bool = False,
+                 prediction_cache_dir: Optional[str] = None,
+                 prediction_cache_format: Optional[str] = None,
+                 region_province_col: Optional[str] = None,
+                 region_city_col: Optional[str] = None,
+                 region_effect_alpha: Optional[float] = None,
+                 geo_feature_nmes: Optional[List[str]] = None,
+                 geo_token_hidden_dim: Optional[int] = None,
+                 geo_token_layers: Optional[int] = None,
+                 geo_token_dropout: Optional[float] = None,
+                 geo_token_k_neighbors: Optional[int] = None,
+                 geo_token_learning_rate: Optional[float] = None,
+                 geo_token_epochs: Optional[int] = None):
         """Orchestrate BayesOpt training across multiple trainers.
 
         Args:
@@ -176,6 +189,47 @@ class BayesOptModel:
             final_ensemble=bool(final_ensemble),
             final_ensemble_k=int(final_ensemble_k),
             final_refit=bool(final_refit),
+            cv_strategy=str(cv_strategy or "random"),
+            cv_splits=cv_splits,
+            cv_group_col=cv_group_col,
+            cv_time_col=cv_time_col,
+            cv_time_ascending=bool(cv_time_ascending),
+            ft_oof_folds=ft_oof_folds,
+            ft_oof_strategy=ft_oof_strategy,
+            ft_oof_shuffle=bool(ft_oof_shuffle),
+            save_preprocess=bool(save_preprocess),
+            preprocess_artifact_path=preprocess_artifact_path,
+            plot_path_style=str(plot_path_style or "nested"),
+            bo_sample_limit=bo_sample_limit,
+            cache_predictions=bool(cache_predictions),
+            prediction_cache_dir=prediction_cache_dir,
+            prediction_cache_format=str(prediction_cache_format or "parquet"),
+            region_province_col=region_province_col,
+            region_city_col=region_city_col,
+            region_effect_alpha=float(region_effect_alpha)
+            if region_effect_alpha is not None
+            else 50.0,
+            geo_feature_nmes=list(geo_feature_nmes)
+            if geo_feature_nmes is not None
+            else None,
+            geo_token_hidden_dim=int(geo_token_hidden_dim)
+            if geo_token_hidden_dim is not None
+            else 32,
+            geo_token_layers=int(geo_token_layers)
+            if geo_token_layers is not None
+            else 2,
+            geo_token_dropout=float(geo_token_dropout)
+            if geo_token_dropout is not None
+            else 0.1,
+            geo_token_k_neighbors=int(geo_token_k_neighbors)
+            if geo_token_k_neighbors is not None
+            else 10,
+            geo_token_learning_rate=float(geo_token_learning_rate)
+            if geo_token_learning_rate is not None
+            else 1e-3,
+            geo_token_epochs=int(geo_token_epochs)
+            if geo_token_epochs is not None
+            else 50,
         )
         self.config = cfg
         self.model_nme = cfg.model_nme
@@ -204,15 +258,24 @@ class BayesOptModel:
         self.var_nmes = preprocessor.var_nmes
         self.num_features = preprocessor.num_features
         self.cat_categories_for_shap = preprocessor.cat_categories_for_shap
+        if getattr(self.config, "save_preprocess", False):
+            artifact_path = getattr(self.config, "preprocess_artifact_path", None)
+            if artifact_path:
+                target = Path(str(artifact_path))
+                if not target.is_absolute():
+                    target = Path(self.output_manager.result_dir) / target
+            else:
+                target = Path(self.output_manager.result_path(
+                    f"{self.model_nme}_preprocess.json"
+                ))
+            preprocessor.save_artifacts(target)
         self.geo_token_cols: List[str] = []
         self.train_geo_tokens: Optional[pd.DataFrame] = None
         self.test_geo_tokens: Optional[pd.DataFrame] = None
         self.geo_gnn_model: Optional[GraphNeuralNetSklearn] = None
         self._add_region_effect()
 
-        self.cv = ShuffleSplit(n_splits=int(1/self.prop_test),
-                               test_size=self.prop_test,
-                               random_state=self.rand_seed)
+        self.cv = self._build_cv_splitter()
         if self.task_type == 'classification':
             self.obj = 'binary:logistic'
         else:  # regression task
@@ -261,6 +324,45 @@ class BayesOptModel:
         self.ft_load = None
         self.version_manager = VersionManager(self.output_manager)
 
+    def _build_cv_splitter(self) -> _CVSplitter:
+        strategy = str(getattr(self.config, "cv_strategy", "random") or "random").strip().lower()
+        val_ratio = float(self.prop_test) if self.prop_test is not None else 0.25
+        if not (0.0 < val_ratio < 1.0):
+            val_ratio = 0.25
+        cv_splits = getattr(self.config, "cv_splits", None)
+        if cv_splits is None:
+            cv_splits = max(2, int(round(1 / val_ratio)))
+        cv_splits = max(2, int(cv_splits))
+
+        if strategy in {"group", "grouped"}:
+            group_col = getattr(self.config, "cv_group_col", None)
+            if not group_col:
+                raise ValueError("cv_group_col is required for group cv_strategy.")
+            if group_col not in self.train_data.columns:
+                raise KeyError(f"cv_group_col '{group_col}' not in train_data.")
+            groups = self.train_data[group_col]
+            splitter = GroupKFold(n_splits=cv_splits)
+            return _CVSplitter(splitter, groups=groups)
+
+        if strategy in {"time", "timeseries", "temporal"}:
+            time_col = getattr(self.config, "cv_time_col", None)
+            if not time_col:
+                raise ValueError("cv_time_col is required for time cv_strategy.")
+            if time_col not in self.train_data.columns:
+                raise KeyError(f"cv_time_col '{time_col}' not in train_data.")
+            ascending = bool(getattr(self.config, "cv_time_ascending", True))
+            order_index = self.train_data[time_col].sort_values(ascending=ascending).index
+            order = self.train_data.index.get_indexer(order_index)
+            splitter = TimeSeriesSplit(n_splits=cv_splits)
+            return _CVSplitter(splitter, order=order)
+
+        splitter = ShuffleSplit(
+            n_splits=cv_splits,
+            test_size=val_ratio,
+            random_state=self.rand_seed,
+        )
+        return _CVSplitter(splitter)
+
     def default_tweedie_power(self, obj: Optional[str] = None) -> Optional[float]:
         if self.task_type == 'classification':
             return None
@@ -473,142 +575,6 @@ class BayesOptModel:
                 col for col in self.train_oht_scl_data.columns if col not in excluded
             ]
 
-    # Single-factor plotting helper.
-    def plot_oneway(
-        self,
-        n_bins=10,
-        pred_col: Optional[str] = None,
-        pred_label: Optional[str] = None,
-        pred_weighted: Optional[bool] = None,
-        plot_subdir: Optional[str] = None,
-    ):
-        if plt is None and plot_diagnostics is None:
-            _plot_skip("oneway plot")
-            return
-        if pred_col is not None and pred_col not in self.train_data.columns:
-            print(
-                f"[Oneway] Missing prediction column '{pred_col}'; skip predicted line.",
-                flush=True,
-            )
-            pred_col = None
-        if pred_weighted is None and pred_col is not None:
-            pred_weighted = pred_col.startswith("w_pred_")
-        if pred_weighted is None:
-            pred_weighted = False
-        plot_subdir = plot_subdir.strip("/\\") if plot_subdir else "oneway"
-        plot_prefix = f"{self.model_nme}/{plot_subdir}"
-
-        def _safe_tag(value: str) -> str:
-            return (
-                value.strip()
-                .replace(" ", "_")
-                .replace("/", "_")
-                .replace("\\", "_")
-                .replace(":", "_")
-            )
-
-        if plot_diagnostics is None:
-            for c in self.factor_nmes:
-                fig = plt.figure(figsize=(7, 5))
-                if c in self.cate_list:
-                    group_col = c
-                    plot_source = self.train_data
-                else:
-                    group_col = f'{c}_bins'
-                    bins = pd.qcut(
-                        self.train_data[c],
-                        n_bins,
-                        duplicates='drop'  # Drop duplicate quantiles to avoid errors.
-                    )
-                    plot_source = self.train_data.assign(**{group_col: bins})
-                if pred_col is not None and pred_col in plot_source.columns:
-                    if pred_weighted:
-                        plot_source = plot_source.assign(
-                            _pred_w=plot_source[pred_col]
-                        )
-                    else:
-                        plot_source = plot_source.assign(
-                            _pred_w=plot_source[pred_col] * plot_source[self.weight_nme]
-                        )
-                plot_data = plot_source.groupby(
-                    [group_col], observed=True).sum(numeric_only=True)
-                plot_data.reset_index(inplace=True)
-                plot_data['act_v'] = plot_data['w_act'] / \
-                    plot_data[self.weight_nme]
-                if pred_col is not None and "_pred_w" in plot_data.columns:
-                    plot_data["pred_v"] = plot_data["_pred_w"] / plot_data[self.weight_nme]
-                ax = fig.add_subplot(111)
-                ax.plot(plot_data.index, plot_data['act_v'],
-                        label='Actual', color='red')
-                if pred_col is not None and "pred_v" in plot_data.columns:
-                    ax.plot(
-                        plot_data.index,
-                        plot_data["pred_v"],
-                        label=pred_label or "Predicted",
-                        color="tab:blue",
-                    )
-                ax.set_title(
-                    'Analysis of  %s : Train Data' % group_col,
-                    fontsize=8)
-                plt.xticks(plot_data.index,
-                           list(plot_data[group_col].astype(str)),
-                           rotation=90)
-                if len(list(plot_data[group_col].astype(str))) > 50:
-                    plt.xticks(fontsize=3)
-                else:
-                    plt.xticks(fontsize=6)
-                plt.yticks(fontsize=6)
-                ax2 = ax.twinx()
-                ax2.bar(plot_data.index,
-                        plot_data[self.weight_nme],
-                        alpha=0.5, color='seagreen')
-                plt.yticks(fontsize=6)
-                plt.margins(0.05)
-                plt.subplots_adjust(wspace=0.3)
-                if pred_col is not None and "pred_v" in plot_data.columns:
-                    ax.legend(fontsize=6)
-                pred_tag = _safe_tag(pred_label or pred_col) if pred_col else None
-                if pred_tag:
-                    filename = f'00_{self.model_nme}_{group_col}_oneway_{pred_tag}.png'
-                else:
-                    filename = f'00_{self.model_nme}_{group_col}_oneway.png'
-                save_path = self.output_manager.plot_path(
-                    f'{plot_prefix}/{filename}')
-                plt.savefig(save_path, dpi=300)
-                plt.close(fig)
-            return
-
-        if "w_act" not in self.train_data.columns:
-            print("[Oneway] Missing w_act column; skip plotting.", flush=True)
-            return
-
-        for c in self.factor_nmes:
-            is_cat = c in (self.cate_list or [])
-            group_col = c if is_cat else f"{c}_bins"
-            title = f"Analysis of {group_col} : Train Data"
-            pred_tag = _safe_tag(pred_label or pred_col) if pred_col else None
-            if pred_tag:
-                filename = f"00_{self.model_nme}_{group_col}_oneway_{pred_tag}.png"
-            else:
-                filename = f"00_{self.model_nme}_{group_col}_oneway.png"
-            save_path = self.output_manager.plot_path(
-                f"{plot_prefix}/{filename}"
-            )
-            plot_diagnostics.plot_oneway(
-                self.train_data,
-                feature=c,
-                weight_col=self.weight_nme,
-                target_col="w_act",
-                pred_col=pred_col,
-                pred_weighted=pred_weighted,
-                pred_label=pred_label,
-                n_bins=n_bins,
-                is_categorical=is_cat,
-                title=title,
-                save_path=save_path,
-                show=False,
-            )
-
     def _require_trainer(self, model_key: str) -> "TrainerBase":
         trainer = self.trainers.get(model_key)
         if trainer is None:
@@ -896,486 +862,6 @@ class BayesOptModel:
     def bayesopt_ft(self, max_evals=50):
         self.optimize_model('ft', max_evals)
 
-    # Lift curve plotting.
-    def plot_lift(self, model_label, pred_nme, n_bins=10):
-        if plt is None:
-            _plot_skip("lift plot")
-            return
-        model_map = {
-            'Xgboost': 'pred_xgb',
-            'ResNet': 'pred_resn',
-            'ResNetClassifier': 'pred_resn',
-            'GLM': 'pred_glm',
-            'GNN': 'pred_gnn',
-        }
-        if str(self.config.ft_role) == "model":
-            model_map.update({
-                'FTTransformer': 'pred_ft',
-                'FTTransformerClassifier': 'pred_ft',
-            })
-        for k, v in model_map.items():
-            if model_label.startswith(k):
-                pred_nme = v
-                break
-        safe_label = (
-            str(model_label)
-            .replace(" ", "_")
-            .replace("/", "_")
-            .replace("\\", "_")
-            .replace(":", "_")
-        )
-        plot_prefix = f"{self.model_nme}/lift"
-        filename = f"01_{self.model_nme}_{safe_label}_lift.png"
-
-        datasets = []
-        for title, data in [
-            ('Lift Chart on Train Data', self.train_data),
-            ('Lift Chart on Test Data', self.test_data),
-        ]:
-            if 'w_act' not in data.columns or data['w_act'].isna().all():
-                print(
-                    f"[Lift] Missing labels for {title}; skip.",
-                    flush=True,
-                )
-                continue
-            datasets.append((title, data))
-
-        if not datasets:
-            print("[Lift] No labeled data available; skip plotting.", flush=True)
-            return
-
-        if plot_curves is None:
-            fig = plt.figure(figsize=(11, 5))
-            positions = [111] if len(datasets) == 1 else [121, 122]
-            for pos, (title, data) in zip(positions, datasets):
-                if pred_nme not in data.columns or f'w_{pred_nme}' not in data.columns:
-                    print(
-                        f"[Lift] Missing prediction columns in {title}; skip.",
-                        flush=True,
-                    )
-                    continue
-                lift_df = pd.DataFrame({
-                    'pred': data[pred_nme].values,
-                    'w_pred': data[f'w_{pred_nme}'].values,
-                    'act': data['w_act'].values,
-                    'weight': data[self.weight_nme].values
-                })
-                plot_data = PlotUtils.split_data(lift_df, 'pred', 'weight', n_bins)
-                denom = np.maximum(plot_data['weight'], EPS)
-                plot_data['exp_v'] = plot_data['w_pred'] / denom
-                plot_data['act_v'] = plot_data['act'] / denom
-                plot_data = plot_data.reset_index()
-
-                ax = fig.add_subplot(pos)
-                PlotUtils.plot_lift_ax(ax, plot_data, title)
-
-            plt.subplots_adjust(wspace=0.3)
-            save_path = self.output_manager.plot_path(
-                f"{plot_prefix}/{filename}")
-            plt.savefig(save_path, dpi=300)
-            plt.show()
-            plt.close(fig)
-            return
-
-        style = PlotStyle() if PlotStyle else None
-        fig, axes = plt.subplots(1, len(datasets), figsize=(11, 5))
-        if len(datasets) == 1:
-            axes = [axes]
-
-        for ax, (title, data) in zip(axes, datasets):
-            pred_vals = None
-            if pred_nme in data.columns:
-                pred_vals = data[pred_nme].values
-            else:
-                w_pred_col = f"w_{pred_nme}"
-                if w_pred_col in data.columns:
-                    denom = np.maximum(data[self.weight_nme].values, EPS)
-                    pred_vals = data[w_pred_col].values / denom
-            if pred_vals is None:
-                print(
-                    f"[Lift] Missing prediction columns in {title}; skip.",
-                    flush=True,
-                )
-                continue
-
-            plot_curves.plot_lift_curve(
-                pred_vals,
-                data['w_act'].values,
-                data[self.weight_nme].values,
-                n_bins=n_bins,
-                title=title,
-                pred_label="Predicted",
-                act_label="Actual",
-                weight_label="Earned Exposure",
-                pred_weighted=False,
-                actual_weighted=True,
-                ax=ax,
-                show=False,
-                style=style,
-            )
-
-        plt.subplots_adjust(wspace=0.3)
-        save_path = self.output_manager.plot_path(
-            f"{plot_prefix}/{filename}")
-        if finalize_figure:
-            finalize_figure(fig, save_path=save_path, show=True, style=style)
-        else:
-            plt.savefig(save_path, dpi=300)
-            plt.show()
-            plt.close(fig)
-
-    # Double lift curve plot.
-    def plot_dlift(self, model_comp: List[str] = ['xgb', 'resn'], n_bins: int = 10) -> None:
-        # Compare two models across bins.
-        # Args:
-        #   model_comp: model keys to compare (e.g., ['xgb', 'resn']).
-        #   n_bins: number of bins for lift curves.
-        if plt is None:
-            _plot_skip("double lift plot")
-            return
-        if len(model_comp) != 2:
-            raise ValueError("`model_comp` must contain two models to compare.")
-
-        model_name_map = {
-            'xgb': 'Xgboost',
-            'resn': 'ResNet',
-            'glm': 'GLM',
-            'gnn': 'GNN',
-        }
-        if str(self.config.ft_role) == "model":
-            model_name_map['ft'] = 'FTTransformer'
-
-        name1, name2 = model_comp
-        if name1 not in model_name_map or name2 not in model_name_map:
-            raise ValueError(f"Unsupported model key. Choose from {list(model_name_map.keys())}.")
-        plot_prefix = f"{self.model_nme}/double_lift"
-        filename = f"02_{self.model_nme}_dlift_{name1}_vs_{name2}.png"
-
-        datasets = []
-        for data_name, data in [('Train Data', self.train_data),
-                                ('Test Data', self.test_data)]:
-            if 'w_act' not in data.columns or data['w_act'].isna().all():
-                print(
-                    f"[Double Lift] Missing labels for {data_name}; skip.",
-                    flush=True,
-                )
-                continue
-            datasets.append((data_name, data))
-
-        if not datasets:
-            print("[Double Lift] No labeled data available; skip plotting.", flush=True)
-            return
-
-        if plot_curves is None:
-            fig, axes = plt.subplots(1, len(datasets), figsize=(11, 5))
-            if len(datasets) == 1:
-                axes = [axes]
-
-            for ax, (data_name, data) in zip(axes, datasets):
-                pred1_col = f'w_pred_{name1}'
-                pred2_col = f'w_pred_{name2}'
-
-                if pred1_col not in data.columns or pred2_col not in data.columns:
-                    print(
-                        f"Warning: missing prediction columns {pred1_col} or {pred2_col} in {data_name}. Skip plot.")
-                    continue
-
-                lift_data = pd.DataFrame({
-                    'pred1': data[pred1_col].values,
-                    'pred2': data[pred2_col].values,
-                    'diff_ly': data[pred1_col].values / np.maximum(data[pred2_col].values, EPS),
-                    'act': data['w_act'].values,
-                    'weight': data[self.weight_nme].values
-                })
-                plot_data = PlotUtils.split_data(
-                    lift_data, 'diff_ly', 'weight', n_bins)
-                denom = np.maximum(plot_data['act'], EPS)
-                plot_data['exp_v1'] = plot_data['pred1'] / denom
-                plot_data['exp_v2'] = plot_data['pred2'] / denom
-                plot_data['act_v'] = plot_data['act'] / denom
-                plot_data.reset_index(inplace=True)
-
-                label1 = model_name_map[name1]
-                label2 = model_name_map[name2]
-
-                PlotUtils.plot_dlift_ax(
-                    ax, plot_data, f'Double Lift Chart on {data_name}', label1, label2)
-
-            plt.subplots_adjust(bottom=0.25, top=0.95, right=0.8, wspace=0.3)
-            save_path = self.output_manager.plot_path(
-                f"{plot_prefix}/{filename}")
-            plt.savefig(save_path, dpi=300)
-            plt.show()
-            plt.close(fig)
-            return
-
-        style = PlotStyle() if PlotStyle else None
-        fig, axes = plt.subplots(1, len(datasets), figsize=(11, 5))
-        if len(datasets) == 1:
-            axes = [axes]
-
-        label1 = model_name_map[name1]
-        label2 = model_name_map[name2]
-
-        for ax, (data_name, data) in zip(axes, datasets):
-            weight_vals = data[self.weight_nme].values
-            pred1 = None
-            pred2 = None
-
-            pred1_col = f"pred_{name1}"
-            pred2_col = f"pred_{name2}"
-            if pred1_col in data.columns:
-                pred1 = data[pred1_col].values
-            else:
-                w_pred1_col = f"w_pred_{name1}"
-                if w_pred1_col in data.columns:
-                    pred1 = data[w_pred1_col].values / np.maximum(weight_vals, EPS)
-
-            if pred2_col in data.columns:
-                pred2 = data[pred2_col].values
-            else:
-                w_pred2_col = f"w_pred_{name2}"
-                if w_pred2_col in data.columns:
-                    pred2 = data[w_pred2_col].values / np.maximum(weight_vals, EPS)
-
-            if pred1 is None or pred2 is None:
-                print(
-                    f"Warning: missing pred_{name1}/pred_{name2} or w_pred columns in {data_name}. Skip plot.")
-                continue
-
-            plot_curves.plot_double_lift_curve(
-                pred1,
-                pred2,
-                data['w_act'].values,
-                weight_vals,
-                n_bins=n_bins,
-                title=f"Double Lift Chart on {data_name}",
-                label1=label1,
-                label2=label2,
-                pred1_weighted=False,
-                pred2_weighted=False,
-                actual_weighted=True,
-                ax=ax,
-                show=False,
-                style=style,
-            )
-
-        plt.subplots_adjust(bottom=0.25, top=0.95, right=0.8, wspace=0.3)
-        save_path = self.output_manager.plot_path(
-            f"{plot_prefix}/{filename}")
-        if finalize_figure:
-            finalize_figure(fig, save_path=save_path, show=True, style=style)
-        else:
-            plt.savefig(save_path, dpi=300)
-            plt.show()
-            plt.close(fig)
-
-    # Conversion lift curve plot.
-    def plot_conversion_lift(self, model_pred_col: str, n_bins: int = 20):
-        if plt is None:
-            _plot_skip("conversion lift plot")
-            return
-        if not self.binary_resp_nme:
-            print("Error: `binary_resp_nme` not provided at BayesOptModel init; cannot plot conversion lift.")
-            return
-
-        if plot_curves is None:
-            fig, axes = plt.subplots(1, 2, figsize=(14, 6), sharey=True)
-            datasets = {
-                'Train Data': self.train_data,
-                'Test Data': self.test_data
-            }
-
-            for ax, (data_name, data) in zip(axes, datasets.items()):
-                if model_pred_col not in data.columns:
-                    print(f"Warning: missing prediction column '{model_pred_col}' in {data_name}. Skip plot.")
-                    continue
-
-                # Sort by model prediction and compute bins.
-                plot_data = data.sort_values(by=model_pred_col).copy()
-                plot_data['cum_weight'] = plot_data[self.weight_nme].cumsum()
-                total_weight = plot_data[self.weight_nme].sum()
-
-                if total_weight > EPS:
-                    plot_data['bin'] = pd.cut(
-                        plot_data['cum_weight'],
-                        bins=n_bins,
-                        labels=False,
-                        right=False
-                    )
-                else:
-                    plot_data['bin'] = 0
-
-                # Aggregate by bins.
-                lift_agg = plot_data.groupby('bin').agg(
-                    total_weight=(self.weight_nme, 'sum'),
-                    actual_conversions=(self.binary_resp_nme, 'sum'),
-                    weighted_conversions=('w_binary_act', 'sum'),
-                    avg_pred=(model_pred_col, 'mean')
-                ).reset_index()
-
-                # Compute conversion rate.
-                lift_agg['conversion_rate'] = lift_agg['weighted_conversions'] / \
-                    lift_agg['total_weight']
-
-                # Compute overall average conversion rate.
-                overall_conversion_rate = data['w_binary_act'].sum(
-                ) / data[self.weight_nme].sum()
-                ax.axhline(y=overall_conversion_rate, color='gray', linestyle='--',
-                           label=f'Overall Avg Rate ({overall_conversion_rate:.2%})')
-
-                ax.plot(lift_agg['bin'], lift_agg['conversion_rate'],
-                        marker='o', linestyle='-', label='Actual Conversion Rate')
-                ax.set_title(f'Conversion Rate Lift Chart on {data_name}')
-                ax.set_xlabel(f'Model Score Decile (based on {model_pred_col})')
-                ax.set_ylabel('Conversion Rate')
-                ax.grid(True, linestyle='--', alpha=0.6)
-                ax.legend()
-
-            plt.tight_layout()
-            plt.show()
-            return
-
-        fig, axes = plt.subplots(1, 2, figsize=(14, 6), sharey=True)
-        datasets = {
-            'Train Data': self.train_data,
-            'Test Data': self.test_data
-        }
-
-        for ax, (data_name, data) in zip(axes, datasets.items()):
-            if model_pred_col not in data.columns:
-                print(f"Warning: missing prediction column '{model_pred_col}' in {data_name}. Skip plot.")
-                continue
-
-            plot_curves.plot_conversion_lift(
-                data[model_pred_col].values,
-                data[self.binary_resp_nme].values,
-                data[self.weight_nme].values,
-                n_bins=n_bins,
-                title=f'Conversion Rate Lift Chart on {data_name}',
-                ax=ax,
-                show=False,
-            )
-
-        plt.tight_layout()
-        plt.show()
-
-    # ========= Lightweight explainability: Permutation Importance =========
-    def compute_permutation_importance(self,
-                                       model_key: str,
-                                       on_train: bool = True,
-                                       metric: Any = "auto",
-                                       n_repeats: int = 5,
-                                       max_rows: int = 5000,
-                                       random_state: Optional[int] = None):
-        if explain_permutation is None:
-            raise RuntimeError("explain.permutation is not available.")
-
-        model_key = str(model_key)
-        data = self.train_data if on_train else self.test_data
-        if self.resp_nme not in data.columns:
-            raise RuntimeError("Missing response column for permutation importance.")
-        y = data[self.resp_nme]
-        w = data[self.weight_nme] if self.weight_nme in data.columns else None
-
-        if model_key == "resn":
-            if self.resn_best is None:
-                raise RuntimeError("ResNet model not trained.")
-            X = self.train_oht_scl_data if on_train else self.test_oht_scl_data
-            if X is None:
-                raise RuntimeError("Missing standardized features for ResNet.")
-            X = X[self.var_nmes]
-            predict_fn = lambda df: self.resn_best.predict(df)
-        elif model_key == "ft":
-            if self.ft_best is None:
-                raise RuntimeError("FT model not trained.")
-            if str(self.config.ft_role) != "model":
-                raise RuntimeError("FT role is not 'model'; FT predictions unavailable.")
-            X = data[self.factor_nmes]
-            geo_tokens = self.train_geo_tokens if on_train else self.test_geo_tokens
-            geo_np = None
-            if geo_tokens is not None:
-                geo_np = geo_tokens.to_numpy(dtype=np.float32, copy=False)
-            predict_fn = lambda df, geo=geo_np: self.ft_best.predict(df, geo_tokens=geo)
-        elif model_key == "xgb":
-            if self.xgb_best is None:
-                raise RuntimeError("XGB model not trained.")
-            X = data[self.factor_nmes]
-            predict_fn = lambda df: self.xgb_best.predict(df)
-        else:
-            raise ValueError("Unsupported model_key for permutation importance.")
-
-        return explain_permutation.permutation_importance(
-            predict_fn,
-            X,
-            y,
-            sample_weight=w,
-            metric=metric,
-            task_type=self.task_type,
-            n_repeats=n_repeats,
-            random_state=random_state,
-            max_rows=max_rows,
-        )
-
-    # ========= Deep explainability: Integrated Gradients =========
-    def compute_integrated_gradients_resn(self,
-                                          on_train: bool = True,
-                                          baseline: Any = None,
-                                          steps: int = 50,
-                                          batch_size: int = 256,
-                                          target: Optional[int] = None):
-        if explain_gradients is None:
-            raise RuntimeError("explain.gradients is not available.")
-        if self.resn_best is None:
-            raise RuntimeError("ResNet model not trained.")
-        X = self.train_oht_scl_data if on_train else self.test_oht_scl_data
-        if X is None:
-            raise RuntimeError("Missing standardized features for ResNet.")
-        X = X[self.var_nmes]
-        return explain_gradients.resnet_integrated_gradients(
-            self.resn_best,
-            X,
-            baseline=baseline,
-            steps=steps,
-            batch_size=batch_size,
-            target=target,
-        )
-
-    def compute_integrated_gradients_ft(self,
-                                        on_train: bool = True,
-                                        geo_tokens: Optional[np.ndarray] = None,
-                                        baseline_num: Any = None,
-                                        baseline_geo: Any = None,
-                                        steps: int = 50,
-                                        batch_size: int = 256,
-                                        target: Optional[int] = None):
-        if explain_gradients is None:
-            raise RuntimeError("explain.gradients is not available.")
-        if self.ft_best is None:
-            raise RuntimeError("FT model not trained.")
-        if str(self.config.ft_role) != "model":
-            raise RuntimeError("FT role is not 'model'; FT explanations unavailable.")
-
-        data = self.train_data if on_train else self.test_data
-        X = data[self.factor_nmes]
-
-        if geo_tokens is None and getattr(self.ft_best, "num_geo", 0) > 0:
-            tokens_df = self.train_geo_tokens if on_train else self.test_geo_tokens
-            if tokens_df is not None:
-                geo_tokens = tokens_df.to_numpy(dtype=np.float32, copy=False)
-
-        return explain_gradients.ft_integrated_gradients(
-            self.ft_best,
-            X,
-            geo_tokens=geo_tokens,
-            baseline_num=baseline_num,
-            baseline_geo=baseline_geo,
-            steps=steps,
-            batch_size=batch_size,
-            target=target,
-        )
-
-    # Save model
     def save_model(self, model_name=None):
         keys = [model_name] if model_name else self.trainers.keys()
         for key in keys:
@@ -1401,149 +887,3 @@ class BayesOptModel:
             else:
                 if model_name:
                     print(f"[load_model] Warning: Unknown model key {key}")
-
-    def _sample_rows(self, data: pd.DataFrame, n: int) -> pd.DataFrame:
-        if len(data) == 0:
-            return data
-        return data.sample(min(len(data), n), random_state=self.rand_seed)
-
-    @staticmethod
-    def _shap_nsamples(arr: np.ndarray, max_nsamples: int = 300) -> int:
-        min_needed = arr.shape[1] + 2
-        return max(min_needed, min(max_nsamples, arr.shape[0] * arr.shape[1]))
-
-    def _build_ft_shap_matrix(self, data: pd.DataFrame) -> np.ndarray:
-        matrices = []
-        for col in self.factor_nmes:
-            s = data[col]
-            if col in self.cate_list:
-                cats = pd.Categorical(
-                    s,
-                    categories=self.cat_categories_for_shap[col]
-                )
-                codes = np.asarray(cats.codes, dtype=np.float64).reshape(-1, 1)
-                matrices.append(codes)
-            else:
-                vals = pd.to_numeric(s, errors="coerce")
-                arr = vals.to_numpy(dtype=np.float64, copy=True).reshape(-1, 1)
-                matrices.append(arr)
-        X_mat = np.concatenate(matrices, axis=1)  # Result shape (N, F)
-        return X_mat
-
-    def _decode_ft_shap_matrix_to_df(self, X_mat: np.ndarray) -> pd.DataFrame:
-        data_dict = {}
-        for j, col in enumerate(self.factor_nmes):
-            col_vals = X_mat[:, j]
-            if col in self.cate_list:
-                cats = self.cat_categories_for_shap[col]
-                codes = np.round(col_vals).astype(int)
-                codes = np.clip(codes, -1, len(cats) - 1)
-                cat_series = pd.Categorical.from_codes(
-                    codes,
-                    categories=cats
-                )
-                data_dict[col] = cat_series
-            else:
-                data_dict[col] = col_vals.astype(float)
-
-        df = pd.DataFrame(data_dict, columns=self.factor_nmes)
-        for col in self.cate_list:
-            if col in df.columns:
-                df[col] = df[col].astype("category")
-        return df
-
-    def _build_glm_design(self, data: pd.DataFrame) -> pd.DataFrame:
-        X = data[self.var_nmes]
-        return sm.add_constant(X, has_constant='add')
-
-    def _compute_shap_core(self,
-                           model_key: str,
-                           n_background: int,
-                           n_samples: int,
-                           on_train: bool,
-                           X_df: pd.DataFrame,
-                           prep_fn,
-                           predict_fn,
-                           cleanup_fn=None):
-        if explain_shap is None:
-            raise RuntimeError("explain.shap_utils is not available.")
-        return explain_shap.compute_shap_core(
-            self,
-            model_key,
-            n_background,
-            n_samples,
-            on_train,
-            X_df=X_df,
-            prep_fn=prep_fn,
-            predict_fn=predict_fn,
-            cleanup_fn=cleanup_fn,
-        )
-
-    # ========= GLM SHAP explainability =========
-    def compute_shap_glm(self, n_background: int = 500,
-                         n_samples: int = 200,
-                         on_train: bool = True):
-        if explain_shap is None:
-            raise RuntimeError("explain.shap_utils is not available.")
-        self.shap_glm = explain_shap.compute_shap_glm(
-            self,
-            n_background=n_background,
-            n_samples=n_samples,
-            on_train=on_train,
-        )
-        return self.shap_glm
-
-    # ========= XGBoost SHAP explainability =========
-    def compute_shap_xgb(self, n_background: int = 500,
-                         n_samples: int = 200,
-                         on_train: bool = True):
-        if explain_shap is None:
-            raise RuntimeError("explain.shap_utils is not available.")
-        self.shap_xgb = explain_shap.compute_shap_xgb(
-            self,
-            n_background=n_background,
-            n_samples=n_samples,
-            on_train=on_train,
-        )
-        return self.shap_xgb
-
-    # ========= ResNet SHAP explainability =========
-    def _resn_predict_wrapper(self, X_np):
-        model = self.resn_best.resnet.to("cpu")
-        with torch.no_grad():
-            X_tensor = torch.tensor(X_np, dtype=torch.float32)
-            y_pred = model(X_tensor).cpu().numpy()
-        y_pred = np.clip(y_pred, 1e-6, None)
-        return y_pred.reshape(-1)
-
-    def compute_shap_resn(self, n_background: int = 500,
-                          n_samples: int = 200,
-                          on_train: bool = True):
-        if explain_shap is None:
-            raise RuntimeError("explain.shap_utils is not available.")
-        self.shap_resn = explain_shap.compute_shap_resn(
-            self,
-            n_background=n_background,
-            n_samples=n_samples,
-            on_train=on_train,
-        )
-        return self.shap_resn
-
-    # ========= FT-Transformer SHAP explainability =========
-    def _ft_shap_predict_wrapper(self, X_mat: np.ndarray) -> np.ndarray:
-        df_input = self._decode_ft_shap_matrix_to_df(X_mat)
-        y_pred = self.ft_best.predict(df_input)
-        return np.asarray(y_pred, dtype=np.float64).reshape(-1)
-
-    def compute_shap_ft(self, n_background: int = 500,
-                        n_samples: int = 200,
-                        on_train: bool = True):
-        if explain_shap is None:
-            raise RuntimeError("explain.shap_utils is not available.")
-        self.shap_ft = explain_shap.compute_shap_ft(
-            self,
-            n_background=n_background,
-            n_samples=n_samples,
-            on_train=on_train,
-        )
-        return self.shap_ft