SuperModelingFactory 0.2.0__py3-none-any.whl

Modeling_Tool/Eval/evaluate_model.pyi

@@ -0,0 +1,50 @@
+# =============================================================================
+# Modeling_Tool.Eval.evaluate_model
+# -----------------------------------------------------------------------------
+# Copyright (c) 2026 Kyle Sun <github.com/Kyle-J-Sun>. All rights reserved.
+# SuperModelingFactory — Licensed under the Business Source License 1.1.
+#
+# This stub describes the public API of a closed-source module compiled to a
+# native extension (.so / .pyd). The original source is not distributed.
+# Production / commercial use requires a separate commercial license.
+#
+# FINGERPRINT: SMF-EVALUATEMODE-566c8a99
+#   (Unique trace marker. Do not remove or alter — used for plagiarism
+#    detection across the public internet.)
+# =============================================================================
+
+import os
+from tracemalloc import start
+import numpy as np
+import pandas as pd
+from pandas.core.groupby.generic import NamedAgg
+from sklearn.metrics import roc_curve, precision_recall_curve, auc
+from matplotlib.font_manager import FontProperties, findfont
+import seaborn as sns
+import matplotlib.pyplot as plt
+from sklearn.utils.extmath import density
+import time
+from functools import wraps
+def timeit_decorator(func): ...
+def calc_pr(y_true, y_score, sample_weight=None): ...
+def summarize_pr(pr_df): ...
+def plot_pr_curve(pr_dfs, square_figsize = 8, to_show = True, save_path = None): ...
+def calc_roc(y_true, y_score, sample_weight=None): ...
+def summarize_roc(roc_df): ...
+def plot_ks_curve(roc_df, square_figsize = 8, to_show = True, save_path = None): ...
+def plot_roc_curve(roc_dfs, square_figsize = 8, fontdicts = fontdicts['main'], to_show = True, save_path = None): ...
+def plot_kde_curve(y_true, y_score_dict, bins = 20, square_figsize = 8, fontdicts = fontdicts['main'], to_show = True, save_path = None): ...
+def calc_equid_dist(y_true, y_score, y_group = None, bins = 10, sample_weight = None): ...
+def calc_equid_pct(y_true, y_score, y_group = None, bins = 10, ascending = True, sample_weight = None): ...
+def calc_fixed_pct(y_true, y_score, y_group = None, bin_edges = None, ascending = True, sample_weight = None): ...
+def summarize_pct(pct_df, ascending = True): ...
+def plot_dist_curve(dist_dfs, square_figsize = 8, fontdicts = fontdicts['main'], to_show = True, save_path = None): ...
+def plot_cumdist_curve(dist_dfs, square_figsize = 8, fontdicts = fontdicts['main'], to_show = True, save_path = None): ...
+def plot_pct_curve(pct_dfs, square_figsize = 8, fontdicts = fontdicts['main'], to_show = True, save_path = None): ...
+def plot_cumpct_curve(pct_dfs, square_figsize = 8, fontdicts = fontdicts['main'], to_show = True, save_path = None): ...
+def plot_gain_curve(pct_dfs, square_figsize = 8, fontdicts = fontdicts['main'], to_show = True, save_path = None): ...
+def evaluate_performance(datasets, dist_bins = 20, pct_bins = 10, square_figsize = 5, fontdicts = fontdicts['sub'], to_show = True, save_path = None, gains_table = True, equal_freq = True, pct_bin_edges = None): ...
+def resturct_gains(gains_table): ...
+def evaluate_distribution(datasets, dist_bins = 10, square_figsize = 5, fontdicts = fontdicts['sub'], toplot = True, save_path = None): ...
+def comparison_performance(datasets, pct_bins = 10, square_figsize = 5, fontdicts = fontdicts['sub'], to_show = True, save_path = None): ...
+def calc_lift_apt(y_true, y_score, start, stop, step, score_ascending = True, sample_weight = None): ...

Modeling_Tool/Eval/weighted_eval_utils.py

@@ -0,0 +1,326 @@
+# encoding: utf-8
+"""Native weighted evaluation helpers.
+
+Shared implementation for public Eval APIs when ``sample_weight`` or
+``weight_col`` is supplied. Unweighted callers keep using the historical
+implementations in ``evaluate_model.py`` and ``Model_Eval_Tool.py``.
+"""
+from __future__ import annotations
+
+from collections import OrderedDict
+
+import numpy as np
+import pandas as pd
+from sklearn.metrics import precision_recall_curve, roc_auc_score, roc_curve
+
+from Modeling_Tool.Core.sample_weight_utils import resolve_sample_weight
+
+
+def resolve_weights(data=None, weight_col=None, sample_weight=None, expected_len=None, wgt=None, wgt_col=None):
+    if weight_col is None:
+        weight_col = wgt_col
+    if sample_weight is None:
+        sample_weight = wgt
+    return resolve_sample_weight(
+        data=data,
+        weight_col=weight_col,
+        sample_weight=sample_weight,
+        expected_len=expected_len,
+    )
+
+
+def safe_weighted_average(values, weights=None):
+    values = np.asarray(values, dtype=float)
+    if weights is None:
+        return float(np.mean(values)) if len(values) else np.nan
+    weights = np.asarray(weights, dtype=float)
+    total = float(np.sum(weights))
+    if total == 0:
+        return np.nan
+    return float(np.average(values, weights=weights))
+
+
+def safe_auc(y_true, y_score, sample_weight=None):
+    try:
+        return float(roc_auc_score(y_true, y_score, sample_weight=sample_weight))
+    except Exception:
+        return np.nan
+
+
+def calc_roc(y_true, y_score, sample_weight=None):
+    y_true = np.asarray(y_true, dtype=float)
+    y_score = np.asarray(y_score, dtype=float)
+    weight = None if sample_weight is None else np.asarray(sample_weight, dtype=float)
+
+    mask = np.isfinite(y_true) & np.isfinite(y_score)
+    if weight is not None:
+        mask = mask & np.isfinite(weight)
+        weight = weight[mask]
+    y_true = y_true[mask]
+    y_score = y_score[mask]
+
+    if len(y_true) == 0:
+        return pd.DataFrame(columns=["fpr", "tpr", "thresholds", "thresholds_percentile", "FPR", "TPR", "KS"])
+
+    fpr, tpr, thresholds = roc_curve(y_true, y_score, sample_weight=weight)
+    out = pd.DataFrame({"fpr": fpr, "tpr": tpr, "thresholds": thresholds})
+    if weight is None:
+        out["thresholds_percentile"] = [100 * np.mean(y_score <= x) for x in thresholds]
+    else:
+        total_weight = float(weight.sum()) or 1.0
+        out["thresholds_percentile"] = [
+            100 * float(weight[y_score <= x].sum()) / total_weight for x in thresholds
+        ]
+    out["FPR"] = out["fpr"]
+    out["TPR"] = out["tpr"]
+    out["KS"] = (out["tpr"] - out["fpr"]).abs()
+    return out
+
+
+def calc_pr(y_true, y_score, sample_weight=None):
+    precision, recall, thresholds = precision_recall_curve(
+        y_true,
+        y_score,
+        sample_weight=sample_weight,
+    )
+    thresholds = np.r_[thresholds, np.nan]
+    return pd.DataFrame(
+        {
+            "precision": precision,
+            "recall": recall,
+            "thresholds": thresholds,
+        }
+    )
+
+
+def rank_bins(score, weight, nbins):
+    score = np.asarray(score, dtype=float)
+    weight = np.ones(len(score), dtype=float) if weight is None else np.asarray(weight, dtype=float)
+    order = np.lexsort((np.arange(len(score)), -score))
+    bins = np.empty(len(score), dtype=int)
+    total = float(weight.sum()) or float(len(score)) or 1.0
+    cum_weight = np.cumsum(weight[order])
+    labels = np.ceil(cum_weight / total * int(nbins)).astype(int)
+    labels = np.clip(labels, 1, int(nbins))
+    bins[order] = labels
+    return bins
+
+
+def get_gains_table(data, dep, score, nbins=10, weight_col=None, weighted_binning=None, **kwargs):
+    cols = [dep, score]
+    if weight_col is not None and weight_col in data.columns:
+        cols.append(weight_col)
+    df = data[cols].copy()
+    weight = resolve_weights(df, weight_col=weight_col, expected_len=len(df))
+    if weight is None:
+        weight = np.ones(len(df), dtype=float)
+
+    y = df[dep].astype(float).to_numpy()
+    s = df[score].astype(float).to_numpy()
+    df["_bin_num"] = rank_bins(s, weight, nbins)
+    df["_bin_range"] = df["_bin_num"]
+    df["_w"] = weight
+    df["_bad_w"] = weight * y
+    df["_good_w"] = weight * (1.0 - y)
+    grouped = df.groupby(["_bin_num", "_bin_range"], sort=True, dropna=False)
+    out = grouped.agg(
+        MIN=(score, "min"),
+        MAX=(score, "max"),
+        N=("_w", "sum"),
+        N_RAW=(dep, "size"),
+        PERF_CNT=("_w", "sum"),
+        N_BAD=("_bad_w", "sum"),
+        N_GOOD=("_good_w", "sum"),
+        AVG_SCORE=(score, lambda x: safe_weighted_average(x, df.loc[x.index, "_w"])),
+        UNIQUE_SCORE=(score, "nunique"),
+    )
+
+    total_weight = float(out["N"].sum()) or 1.0
+    total_bad = float(out["N_BAD"].sum()) or 1.0
+    total_good = float(out["N_GOOD"].sum()) or 1.0
+    overall_bad_rate = float(out["N_BAD"].sum()) / total_weight if total_weight else np.nan
+
+    out["PROP"] = out["N"] / total_weight
+    out["AVG_BAD"] = out["N_BAD"] / out["N"].replace(0, np.nan)
+    out["AVG_GOOD"] = out["N_GOOD"] / out["N"].replace(0, np.nan)
+    out["BAD_PCT_IN_EACH_BIN"] = out["N_BAD"] / total_bad
+    out["GOOD_PCT_IN_EACH_BIN"] = out["N_GOOD"] / total_good
+    out["N_CUM_BAD"] = out["N_BAD"].cumsum()
+    out["N_CUM_GOOD"] = out["N_GOOD"].cumsum()
+    out["CUM_BAD_PCT"] = out["BAD_PCT_IN_EACH_BIN"].cumsum()
+    out["CUM_GOOD_PCT"] = out["GOOD_PCT_IN_EACH_BIN"].cumsum()
+    out["KS_PER_BIN"] = (out["CUM_BAD_PCT"] - out["CUM_GOOD_PCT"]).abs()
+    out["KS"] = out["KS_PER_BIN"]
+    out["LIFT"] = out["AVG_BAD"] / overall_bad_rate if overall_bad_rate else np.nan
+    out["TRUE_BAD_SHIFT"] = out["AVG_BAD"].shift(1) / out["AVG_BAD"] - 1
+    out["RANK_ORDER_BUMP"] = out["TRUE_BAD_SHIFT"].apply(lambda x: 1 if x < 0 else 0)
+    with np.errstate(divide="ignore", invalid="ignore"):
+        out["WOE"] = np.log(out["BAD_PCT_IN_EACH_BIN"] / out["GOOD_PCT_IN_EACH_BIN"])
+    out["WOE"] = out["WOE"].replace([np.inf, -np.inf], 0).fillna(0)
+    out["IV"] = (out["BAD_PCT_IN_EACH_BIN"] - out["GOOD_PCT_IN_EACH_BIN"]) * out["WOE"]
+    out["AUC"] = safe_auc(y, s, sample_weight=weight)
+    return out
+
+
+def calc_lift_apt(y_true, y_score, start=1.0, stop=3.0, step=0.1, sample_weight=None):
+    y_true = np.asarray(y_true, dtype=float)
+    y_score = np.asarray(y_score, dtype=float)
+    weight = np.ones(len(y_true), dtype=float) if sample_weight is None else np.asarray(sample_weight, dtype=float)
+    gains = get_gains_table(
+        pd.DataFrame({"y": y_true, "s": y_score, "w": weight}),
+        "y",
+        "s",
+        nbins=100,
+        weight_col="w",
+    )
+    vals = []
+    for target in np.arange(start, stop + step / 2.0, step):
+        idx = (gains["LIFT"] - target).abs().idxmin()
+        vals.append(float(gains.loc[idx, "LIFT"]))
+    return np.asarray(vals)
+
+
+def calc_equid_dist(y_true, y_score, bins=10, sample_weight=None, **kwargs):
+    weight = np.ones(len(y_true), dtype=float) if sample_weight is None else np.asarray(sample_weight, dtype=float)
+    return get_gains_table(
+        pd.DataFrame({"y": y_true, "s": y_score, "w": weight}),
+        "y",
+        "s",
+        nbins=bins,
+        weight_col="w",
+    )
+
+
+def calc_equid_pct(y_true, y_score, bins=10, sample_weight=None, **kwargs):
+    return calc_equid_dist(y_true, y_score, bins=bins, sample_weight=sample_weight, **kwargs)
+
+
+def calc_fixed_pct(y_true, y_score, sample_weight=None, **kwargs):
+    return calc_equid_dist(y_true, y_score, sample_weight=sample_weight, **kwargs)
+
+
+def dataset_summary(name, data, tgt_name, scr_name, weight_col=None, nbins=10):
+    weight = resolve_weights(data, weight_col=weight_col, expected_len=len(data))
+    y_true = data[tgt_name].to_numpy()
+    y_score = data[scr_name].to_numpy()
+    roc_df = calc_roc(y_true, y_score, sample_weight=weight)
+    gains = get_gains_table(data, tgt_name, scr_name, nbins=nbins, weight_col=weight_col)
+    return {
+        "index": name,
+        "dataset": name,
+        "DATASET": name,
+        "AUC": safe_auc(y_true, y_score, sample_weight=weight),
+        "KS": float(roc_df["KS"].max()) if "KS" in roc_df else np.nan,
+        "LIFT": float(gains["LIFT"].max()) if "LIFT" in gains else np.nan,
+        "IV": float(gains["IV"].sum()) if "IV" in gains else np.nan,
+        "N": float(np.sum(weight)) if weight is not None else float(len(data)),
+        "N_RAW": int(len(data)),
+        "avgTrue": safe_weighted_average(y_true, weight),
+        "avgScore": safe_weighted_average(y_score, weight),
+    }
+
+
+def get_perf_summary(train=None, validation=None, oot=None, tgt_name=None, scr_name=None, weight_col=None, nbins=10, **kwargs):
+    rows = []
+    for name, data in (("ins", train), ("oos", validation), ("oot", oot)):
+        if data is not None:
+            rows.append(dataset_summary(name, data, tgt_name, scr_name, weight_col=weight_col, nbins=nbins))
+    return pd.DataFrame(rows)
+
+
+def evaluate_performance(datasets=None, tgt_name=None, scr_name=None, sample_weight=None, nbins=10, **kwargs):
+    rows = []
+    if datasets is None:
+        return pd.DataFrame(rows)
+    for name, payload in datasets.items():
+        if isinstance(payload, dict) and "data" in payload:
+            data = payload.get("data")
+            weight = payload.get("sample_weight", sample_weight)
+        else:
+            data = pd.DataFrame(
+                {
+                    tgt_name: payload["y_true"],
+                    scr_name: payload["y_score"],
+                }
+            )
+            weight = payload.get("sample_weight", sample_weight)
+        if data is None:
+            continue
+        tmp = data.copy()
+        tmp["_w"] = np.ones(len(tmp), dtype=float) if weight is None else weight
+        rows.append(dataset_summary(name, tmp, tgt_name, scr_name, weight_col="_w", nbins=nbins))
+    return pd.DataFrame(rows)
+
+
+class GainsTableCalculator:
+    def __init__(self, data=None, dep=None, score=None, nbins=10, weight_col=None, weighted_binning=None, **kwargs):
+        self.data = data
+        self.dep = dep
+        self.score = score
+        self.nbins = nbins
+        self.weight_col = weight_col
+        self.weighted_binning = weighted_binning
+        self.kwargs = kwargs
+
+    def calculate(self, weight_col=None, **kwargs):
+        return get_gains_table(
+            self.data,
+            self.dep,
+            self.score,
+            nbins=self.nbins,
+            weight_col=self.weight_col if weight_col is None else weight_col,
+            weighted_binning=self.weighted_binning,
+            **{**self.kwargs, **kwargs},
+        )
+
+
+class PerformanceEvaluator:
+    def __init__(self, tgt_name=None, scr_name=None, weight_col=None, nbins=10, **kwargs):
+        self.tgt_name = tgt_name
+        self.scr_name = scr_name
+        self.weight_col = weight_col
+        self.nbins = nbins
+        self.kwargs = kwargs
+        self.datasets = OrderedDict()
+
+    def add_dataset(self, name, data, weight_col=None, **kwargs):
+        self.datasets[name] = (data, weight_col)
+        return self
+
+    def evaluate(self, weight_col=None, to_show=False, display=False, **kwargs):
+        rows = []
+        for name, (data, ds_weight_col) in self.datasets.items():
+            wc = ds_weight_col or weight_col or self.weight_col
+            rows.append(dataset_summary(name, data, self.tgt_name, self.scr_name, weight_col=wc, nbins=self.nbins))
+        return pd.DataFrame(rows)
+
+
+def cross_risk_weighted_mean(data, agg_col, sample_weight, score_list, margin_name="Total_Avg_Risk"):
+    """Weighted-mean cross-risk table after bin columns are assigned."""
+    weight = np.asarray(sample_weight, dtype=float)
+    values = pd.to_numeric(data[agg_col], errors="coerce").to_numpy(dtype=float)
+    frame = data[["_bin_num1", "_bin_range1", "_bin_num2", "_bin_range2"]].copy()
+    frame["_w"] = weight
+    frame["_wv"] = values * weight
+
+    numerator = pd.crosstab(
+        [frame["_bin_num1"], frame["_bin_range1"]],
+        [frame["_bin_num2"], frame["_bin_range2"]],
+        values=frame["_wv"],
+        aggfunc="sum",
+        margins=True,
+        margins_name=margin_name,
+        rownames=[score_list[0], score_list[0]],
+        colnames=[score_list[1], score_list[1]],
+    )
+    denominator = pd.crosstab(
+        [frame["_bin_num1"], frame["_bin_range1"]],
+        [frame["_bin_num2"], frame["_bin_range2"]],
+        values=frame["_w"],
+        aggfunc="sum",
+        margins=True,
+        margins_name=margin_name,
+        rownames=[score_list[0], score_list[0]],
+        colnames=[score_list[1], score_list[1]],
+    )
+    return numerator / denominator.replace(0, np.nan)

Modeling_Tool/Explainability/Coalition_Structure.py

@@ -0,0 +1,305 @@
+# encoding: utf-8
+"""Coalition structure utilities for Owen Value explanations.
+
+The functions in this module build feature groups for SHAP
+``PartitionExplainer``. They combine data-driven correlation clustering with
+optional business priors, then convert the final groups to the linkage matrix
+accepted by ``shap.maskers.Partition``.
+"""
+from __future__ import annotations
+
+from typing import Dict, Iterable, List, Mapping, Optional, Sequence
+
+import numpy as np
+import pandas as pd
+from scipy.cluster.hierarchy import fcluster, linkage
+from scipy.spatial.distance import squareform
+
+__all__ = [
+    "CREDIT_PRIOR_GROUPS",
+    "compute_correlation_linkage",
+    "auto_cluster",
+    "apply_prior",
+    "validate_groups",
+    "group_correlation_summary",
+    "groups_to_shap_clustering",
+    "build_coalition_structure",
+]
+
+CREDIT_PRIOR_GROUPS = {
+    "delinquency": [
+        "max_dpd_12m", "dpd_cnt_6m", "ever_dpd30",
+        "dpd_cnt_3m", "max_dpd_6m", "ever_dpd90",
+    ],
+    "multi_lending": [
+        "inquiries_3m", "inquiries_6m", "inquiries_12m",
+        "active_loans", "loan_cnt_12m",
+    ],
+    "affordability": [
+        "monthly_income", "debt_to_income",
+        "monthly_obligation", "net_income", "dsr",
+    ],
+    "device_fraud": [
+        "device_risk", "ip_risk", "device_age_days",
+        "proxy_flag", "emulator_flag",
+    ],
+    "apply_behavior": [
+        "apply_hour", "form_fill_secs", "typo_cnt",
+        "paste_cnt", "apply_wday",
+    ],
+    "channel": ["channel_risk", "promo_code_used", "referral_flag"],
+}
+
+_ALLOWED_LINKAGE_METHODS = frozenset({"complete", "average", "single"})
+
+
+def _as_numeric_frame(X: pd.DataFrame) -> pd.DataFrame:
+    if not isinstance(X, pd.DataFrame):
+        raise TypeError("Coalition structure requires X to be a pandas DataFrame")
+    if X.shape[1] == 0:
+        raise ValueError("X must contain at least one feature")
+    frame = X.copy()
+    for col in frame.columns:
+        frame[col] = pd.to_numeric(frame[col], errors="coerce")
+    return frame
+
+
+def _check_method(method: str) -> str:
+    if method not in _ALLOWED_LINKAGE_METHODS:
+        raise ValueError(
+            "method must be one of {'complete', 'average', 'single'} for "
+            "precomputed correlation distances"
+        )
+    return method
+
+
+def _correlation_distance(X: pd.DataFrame, corr_method: str = "spearman") -> pd.DataFrame:
+    frame = _as_numeric_frame(X)
+    corr = frame.corr(method=corr_method).abs()
+    corr = corr.reindex(index=frame.columns, columns=frame.columns).fillna(0.0)
+    corr = corr.clip(lower=0.0, upper=1.0)
+    np.fill_diagonal(corr.values, 1.0)
+    dist = 1.0 - corr
+    np.fill_diagonal(dist.values, 0.0)
+    return dist
+
+
+def compute_correlation_linkage(
+    X: pd.DataFrame,
+    method: str = "complete",
+    corr_method: str = "spearman",
+) -> np.ndarray:
+    """Return a scipy linkage matrix from absolute correlation distances.
+
+    Distance is defined as ``1 - abs(corr)``. Constant or all-missing columns are
+    retained and treated as uncorrelated with other features.
+    """
+    method = _check_method(method)
+    if X.shape[1] < 2:
+        return np.empty((0, 4), dtype=float)
+    dist = _correlation_distance(X, corr_method=corr_method)
+    condensed = squareform(dist.values, checks=False)
+    return linkage(condensed, method=method)
+
+
+def auto_cluster(
+    X: pd.DataFrame,
+    threshold: float = 0.35,
+    method: str = "complete",
+    corr_method: str = "spearman",
+    min_group_size: int = 1,
+) -> Dict[str, List[str]]:
+    """Build data-driven feature groups using hierarchical clustering."""
+    if threshold < 0 or threshold > 1:
+        raise ValueError("threshold must be between 0 and 1")
+    features = list(X.columns)
+    if len(features) == 1:
+        return {"auto_cluster_1": features}
+
+    lnk = compute_correlation_linkage(X, method=method, corr_method=corr_method)
+    labels = fcluster(lnk, t=threshold, criterion="distance")
+    groups: Dict[str, List[str]] = {}
+    for feat, gid in zip(features, labels):
+        groups.setdefault(f"auto_cluster_{int(gid)}", []).append(feat)
+
+    if min_group_size > 1:
+        singletons = [key for key, feats in groups.items() if len(feats) < min_group_size]
+        merged: List[str] = []
+        for key in singletons:
+            merged.extend(groups.pop(key))
+        if merged:
+            groups["auto_singleton"] = merged
+    return groups
+
+
+def _prior_duplicates(prior_groups: Mapping[str, Sequence[str]], features: Sequence[str]) -> Dict[str, List[str]]:
+    seen: Dict[str, List[str]] = {}
+    feature_set = set(features)
+    for group_name, feats in prior_groups.items():
+        for feat in feats:
+            if feat in feature_set:
+                seen.setdefault(feat, []).append(group_name)
+    return {feat: groups for feat, groups in seen.items() if len(groups) > 1}
+
+
+def apply_prior(
+    auto_groups: Mapping[str, Sequence[str]],
+    prior_groups: Optional[Mapping[str, Sequence[str]]],
+    features: Sequence[str],
+) -> Dict[str, List[str]]:
+    """Merge business priors with data-driven groups.
+
+    Business priors win. Remaining features keep their automatic cluster with a
+    ``residual_`` prefix. Priors may contain feature names absent from X; those
+    are ignored. Repeated valid feature names across prior groups are rejected.
+    """
+    if not prior_groups:
+        return {str(k): list(v) for k, v in auto_groups.items()}
+
+    duplicates = _prior_duplicates(prior_groups, features)
+    if duplicates:
+        detail = "; ".join(f"{feat}: {groups}" for feat, groups in duplicates.items())
+        raise ValueError(f"Features appear in multiple prior groups: {detail}")
+
+    assigned = set()
+    merged: Dict[str, List[str]] = {}
+    feature_set = set(features)
+
+    for group_name, feats in prior_groups.items():
+        valid = [feat for feat in feats if feat in feature_set]
+        if valid:
+            merged[str(group_name)] = valid
+            assigned.update(valid)
+
+    for group_name, feats in auto_groups.items():
+        leftover = [feat for feat in feats if feat not in assigned]
+        if leftover:
+            key = f"residual_{group_name}"
+            merged.setdefault(key, []).extend(leftover)
+            assigned.update(leftover)
+
+    uncovered = [feat for feat in features if feat not in assigned]
+    if uncovered:
+        merged["ungrouped"] = uncovered
+    return merged
+
+
+def validate_groups(groups: Mapping[str, Sequence[str]], features: Sequence[str], raise_error: bool = True) -> bool:
+    """Validate complete, non-overlapping feature coverage."""
+    all_assigned = [feat for feats in groups.values() for feat in feats]
+    feature_set = set(features)
+    missing = feature_set - set(all_assigned)
+    unknown = set(all_assigned) - feature_set
+    duplicated = {feat for feat in all_assigned if all_assigned.count(feat) > 1}
+    ok = not missing and not duplicated and not unknown
+    if not ok and raise_error:
+        parts = []
+        if missing:
+            parts.append(f"missing={sorted(missing)}")
+        if duplicated:
+            parts.append(f"duplicated={sorted(duplicated)}")
+        if unknown:
+            parts.append(f"unknown={sorted(unknown)}")
+        raise ValueError("Invalid coalition groups: " + ", ".join(parts))
+    return ok
+
+
+def group_correlation_summary(
+    X: pd.DataFrame,
+    groups: Mapping[str, Sequence[str]],
+    corr_method: str = "spearman",
+) -> pd.DataFrame:
+    """Summarize within-group absolute correlation."""
+    frame = _as_numeric_frame(X)
+    corr = frame.corr(method=corr_method).abs().reindex(index=frame.columns, columns=frame.columns).fillna(0.0)
+    rows = []
+    for group_name, feats in groups.items():
+        valid = [feat for feat in feats if feat in corr.columns]
+        if len(valid) > 1:
+            sub = corr.loc[valid, valid].values
+            vals = sub[np.triu_indices_from(sub, k=1)]
+            avg_corr = float(np.nanmean(vals)) if vals.size else float("nan")
+            max_corr = float(np.nanmax(vals)) if vals.size else float("nan")
+        else:
+            avg_corr = float("nan")
+            max_corr = float("nan")
+        rows.append(
+            {
+                "group": group_name,
+                "n_features": len(valid),
+                "mean_abs_corr": round(avg_corr, 3) if np.isfinite(avg_corr) else np.nan,
+                "max_abs_corr": round(max_corr, 3) if np.isfinite(max_corr) else np.nan,
+                "features": valid,
+            }
+        )
+    return pd.DataFrame(rows).set_index("group")
+
+
+def groups_to_shap_clustering(
+    groups: Mapping[str, Sequence[str]],
+    features: Sequence[str],
+    intra_dist: float = 0.01,
+    inter_dist: float = 0.99,
+) -> np.ndarray:
+    """Convert feature groups to the linkage matrix used by SHAP Partition."""
+    features = list(features)
+    validate_groups(groups, features, raise_error=True)
+    n = len(features)
+    if n < 2:
+        return np.empty((0, 4), dtype=float)
+
+    feat_idx = {feat: idx for idx, feat in enumerate(features)}
+    dist_mat = np.full((n, n), float(inter_dist), dtype=float)
+    np.fill_diagonal(dist_mat, 0.0)
+
+    for feats in groups.values():
+        idxs = [feat_idx[feat] for feat in feats if feat in feat_idx]
+        for i in idxs:
+            for j in idxs:
+                if i != j:
+                    dist_mat[i, j] = float(intra_dist)
+
+    condensed = squareform(dist_mat, checks=False)
+    return linkage(condensed, method="complete")
+
+
+def build_coalition_structure(
+    X: pd.DataFrame,
+    prior_groups: Optional[Mapping[str, Sequence[str]]] = None,
+    threshold: float = 0.35,
+    method: str = "complete",
+    corr_method: str = "spearman",
+    min_group_size: int = 1,
+    intra_dist: float = 0.01,
+    inter_dist: float = 0.99,
+) -> dict:
+    """Build a complete coalition structure for Owen Value explanations.
+
+    Returns a dict containing final groups, automatic groups, correlation
+    linkage, SHAP-compatible linkage, and a within-group correlation summary.
+    """
+    frame = _as_numeric_frame(X)
+    features = list(frame.columns)
+    corr_lnk = compute_correlation_linkage(frame, method=method, corr_method=corr_method)
+    auto = auto_cluster(
+        frame,
+        threshold=threshold,
+        method=method,
+        corr_method=corr_method,
+        min_group_size=min_group_size,
+    )
+    final = apply_prior(auto, prior_groups, features)
+    validate_groups(final, features, raise_error=True)
+    summary = group_correlation_summary(frame, final, corr_method=corr_method)
+    shap_lnk = groups_to_shap_clustering(final, features, intra_dist=intra_dist, inter_dist=inter_dist)
+    return {
+        "groups": final,
+        "shap_lnk": shap_lnk,
+        "corr_lnk": corr_lnk,
+        "auto_groups": auto,
+        "summary": summary,
+        "features": features,
+        "threshold": threshold,
+        "method": method,
+        "corr_method": corr_method,
+    }