shapeaudit 1.0.0__py3-none-any.whl

modelcheck/ale_fast.py

@@ -0,0 +1,167 @@
+"""
+ale_fast.py — ALE vetorizado + embedding de modelo
+
+Duas contribuições:
+
+1. ale_curve_fast — ALE com 1 chamada a predict() por bin (em vez de
+   uma por amostra), tratamento correto de bins vazios e suporte a
+   features categóricas/binárias.
+
+2. model_embedding_ale — representação vetorial do modelo construída a
+   partir dos perfis ALE de todas as features. Permite usar os detectores
+   geométricos (Fréchet, Mantel, eigenvalue) em QUALQUER arquitetura,
+   sem depender de shap.TreeExplainer.
+"""
+import numpy as np
+import pandas as pd
+from typing import List, Optional, Tuple
+
+
+def feature_kind(X: pd.DataFrame, feature: str) -> str:
+    """Classifica a feature: binary, categorical ou continuous."""
+    nu = X[feature].nunique(dropna=True)
+    if nu <= 1:  return 'constant'
+    if nu == 2:  return 'binary'
+    if nu <= 10: return 'categorical'
+    return 'continuous'
+
+
+def _predict(model, X: pd.DataFrame) -> np.ndarray:
+    """predict robusto: usa proba da classe positiva se classificador."""
+    if hasattr(model, 'predict_proba'):
+        try:
+            p = model.predict_proba(X)
+            if p.ndim == 2 and p.shape[1] == 2:
+                return np.asarray(p[:, 1], dtype=float)
+        except Exception:
+            pass
+    return np.asarray(model.predict(X), dtype=float)
+
+
+def ale_curve_fast(model, X: pd.DataFrame, feature: str,
+                   n_bins: int = 5,
+                   min_bin_n: int = 5) -> Optional[Tuple[np.ndarray, np.ndarray]]:
+    """
+    ALE vetorizado. Retorna (centros, ale_acumulado_centrado) ou None.
+
+    Ganho de performance: monta os DataFrames deslocados UMA vez por bin
+    e faz duas chamadas a predict por bin, em vez de chamadas por amostra.
+    Para features categóricas usa efeito médio por categoria.
+    """
+    kind = feature_kind(X, feature)
+    if kind == 'constant':
+        return None
+
+    x = X[feature].values
+
+    # ── Categóricas/binárias: efeito médio por categoria ─────────────
+    if kind in ('binary', 'categorical'):
+        cats = np.sort(pd.unique(x))
+        base = _predict(model, X)
+        centers, effects = [], []
+        for c in cats:
+            Xc = X.copy()
+            Xc[feature] = c
+            effects.append(float((_predict(model, Xc) - base).mean()))
+            centers.append(float(c))
+        if len(effects) < 2:
+            return None
+        arr = np.array(effects, dtype=float)
+        return np.array(centers, dtype=float), arr - arr.mean()
+
+    # ── Contínuas: ALE clássico, vetorizado ──────────────────────────
+    x = np.asarray(x, dtype=float)
+    edges = np.unique(np.percentile(x, np.linspace(0, 100, n_bins + 1)))
+    if len(edges) < 3:
+        return None
+
+    # digitize uma única vez para todas as amostras
+    idx = np.clip(np.digitize(x, edges[1:-1]), 0, len(edges) - 2)
+
+    centers, effects = [], []
+    for b in range(len(edges) - 1):
+        mask = idx == b
+        if mask.sum() < min_bin_n:
+            continue
+        sub = X[mask]
+        Xlo = sub.copy(); Xlo[feature] = edges[b]
+        Xhi = sub.copy(); Xhi[feature] = edges[b + 1]
+        # 2 chamadas a predict por bin, vetorizadas sobre o bin inteiro
+        d = _predict(model, Xhi) - _predict(model, Xlo)
+        effects.append(float(d.mean()))
+        centers.append(float((edges[b] + edges[b + 1]) / 2))
+
+    if len(effects) < 3:
+        return None
+    cum = np.cumsum(effects)
+    return np.array(centers), cum - cum.mean()
+
+
+def model_embedding_ale(model, X: pd.DataFrame,
+                        feature_names: Optional[List[str]] = None,
+                        n_bins: int = 5,
+                        n_points: int = 20,
+                        normalize: bool = True) -> Optional[np.ndarray]:
+    """
+    Embedding do modelo a partir dos perfis ALE.
+
+    Cada feature contribui com n_points valores interpolados do seu perfil
+    ALE. O vetor final tem dimensão n_features * n_points e representa o
+    "comportamento funcional" do modelo — comparável entre arquiteturas.
+
+    normalize=True escala cada perfil pela soma de |valores|, isolando a
+    FORMA da magnitude. normalize=False preserva magnitude (útil para
+    detectar colapso de importância).
+    """
+    if feature_names is None:
+        feature_names = list(X.columns)
+    parts = []
+    for f in feature_names:
+        out = ale_curve_fast(model, X, f, n_bins=n_bins)
+        if out is None:
+            parts.append(np.zeros(n_points))
+            continue
+        centers, vals = out
+        if len(centers) < 2:
+            parts.append(np.zeros(n_points))
+            continue
+        xi = np.linspace(centers[0], centers[-1], n_points)
+        yi = np.interp(xi, centers, vals)
+        if normalize:
+            s = np.abs(yi).sum()
+            yi = yi / s if s > 1e-12 else yi
+        parts.append(yi)
+    if not parts:
+        return None
+    return np.concatenate(parts)
+
+
+def sample_embeddings_ale(model, X: pd.DataFrame,
+                          feature_names: Optional[List[str]] = None,
+                          n_replicas: int = 30,
+                          frac: float = 0.7,
+                          n_bins: int = 5,
+                          n_points: int = 8,
+                          seed: int = 0) -> Optional[np.ndarray]:
+    """
+    Matriz de embeddings (n_replicas × dim) por subamostragem.
+
+    Substitui a matriz de SHAP values como "nuvem de pontos" que representa
+    o modelo, permitindo Fréchet / Mantel / eigenvalue drift sem SHAP.
+    """
+    if feature_names is None:
+        feature_names = list(X.columns)
+    rng = np.random.RandomState(seed)
+    n = max(int(len(X) * frac), 30)
+    rows = []
+    for r in range(n_replicas):
+        idx = rng.choice(len(X), min(n, len(X)), replace=False)
+        Xs = X.iloc[idx].reset_index(drop=True)
+        emb = model_embedding_ale(model, Xs, feature_names,
+                                  n_bins=n_bins, n_points=n_points,
+                                  normalize=False)
+        if emb is not None:
+            rows.append(emb)
+    if len(rows) < 3:
+        return None
+    return np.vstack(rows)

modelcheck/ale_selective.py

@@ -0,0 +1,157 @@
+"""
+ale_selective.py — SDD via ALE com bootstrap seletivo
+
+Problema medido (v1.23): o ALE vetorizado tem recall 1.00 mas
+especificidade 0.17 — dispara divergência até em `v1 vs v1`.
+Causa: classificar forma sobre ~5 pontos de perfil é instável.
+
+Estratégia (bootstrap seletivo):
+  Passo 1 — triagem rápida: ALE vetorizado sem bootstrap em TODAS as
+            features. Barato.
+  Passo 2 — confirmação: bootstrap APENAS nas features que a triagem
+            marcou. Caro, mas em poucas features.
+  Passo 3 — confirma a divergência somente se a forma se mantiver
+            estável em >= min_agreement das réplicas em AMBOS os modelos.
+
+Custo: proporcional ao nº de suspeitas, não ao nº de features.
+"""
+import numpy as np
+import pandas as pd
+from typing import List, Optional
+from collections import Counter
+
+
+def _shape_of(model, X, feature):
+    from modelcheck.shape import _shape_profile_small_n
+    from modelcheck.ale_fast import ale_curve_fast
+    out = ale_curve_fast(model, X, feature)
+    if out is None:
+        return None
+    p = _shape_profile_small_n(out[0], out[1], min_n=3)
+    return p['shape'] if p else None
+
+
+def _amplitude(model, X, feature):
+    from modelcheck.ale_fast import ale_curve_fast
+    out = ale_curve_fast(model, X, feature)
+    return 0.0 if out is None else float(np.ptp(out[1]))
+
+
+class SelectiveALEDetector:
+    """
+    SDD via ALE com confirmação por bootstrap apenas nas suspeitas.
+
+        det = SelectiveALEDetector()
+        res = det.compare(m1, m2, X_eval, feature_names)
+        print(det.report(res))
+    """
+
+    def __init__(self, n_boot: int = 12,
+                 frac: float = 0.75,
+                 min_agreement: float = 0.70,
+                 min_amplitude_ratio: float = 0.05,
+                 seed: int = 0):
+        self.n_boot = n_boot
+        self.frac = frac
+        self.min_agreement = min_agreement
+        self.min_amplitude_ratio = min_amplitude_ratio
+        self.seed = seed
+
+    def _stable_shape(self, model, X, feature):
+        """Forma modal e concordância entre réplicas."""
+        rng = np.random.RandomState(self.seed)
+        n = max(int(len(X) * self.frac), 40)
+        shapes = []
+        for _ in range(self.n_boot):
+            idx = rng.choice(len(X), min(n, len(X)), replace=False)
+            s = _shape_of(model, X.iloc[idx].reset_index(drop=True), feature)
+            if s:
+                shapes.append(s)
+        if not shapes:
+            return None, 0.0
+        sh, c = Counter(shapes).most_common(1)[0]
+        return sh, c / len(shapes)
+
+    def compare(self, model_v1, model_v2,
+                X_eval: pd.DataFrame,
+                feature_names: Optional[List[str]] = None) -> dict:
+        from modelcheck._validate import validate_inputs
+        X_eval, feature_names = validate_inputs(
+            model_v1, model_v2, X_eval, feature_names,
+            caller='SelectiveALEDetector')
+        if feature_names is None:
+            feature_names = list(X_eval.columns)
+
+        # ── Passo 1: triagem rápida ──────────────────────────────────
+        screened = []
+        amps = {}
+        for f in feature_names:
+            s1 = _shape_of(model_v1, X_eval, f)
+            s2 = _shape_of(model_v2, X_eval, f)
+            a1 = _amplitude(model_v1, X_eval, f)
+            a2 = _amplitude(model_v2, X_eval, f)
+            amps[f] = (a1, a2)
+            if s1 and s2 and s1 != s2:
+                screened.append((f, s1, s2))
+
+        # amplitude de referência: maior efeito observado
+        max_amp = max([max(a) for a in amps.values()] or [1e-9])
+
+        # ── Passo 2/3: confirmação só nas suspeitas ──────────────────
+        confirmed, rejected = [], []
+        for f, s1_fast, s2_fast in screened:
+            a1, a2 = amps[f]
+            # descarta features com efeito irrelevante (ruído numérico)
+            if max(a1, a2) / max_amp < self.min_amplitude_ratio:
+                rejected.append({'feature': f, 'reason': 'LOW_AMPLITUDE',
+                                 'shape_v1': s1_fast, 'shape_v2': s2_fast,
+                                 'amp_ratio': round(max(a1, a2) / max_amp, 4)})
+                continue
+            sh1, c1 = self._stable_shape(model_v1, X_eval, f)
+            sh2, c2 = self._stable_shape(model_v2, X_eval, f)
+            if sh1 is None or sh2 is None:
+                rejected.append({'feature': f, 'reason': 'UNSTABLE_PROFILE',
+                                 'shape_v1': s1_fast, 'shape_v2': s2_fast})
+                continue
+            if c1 < self.min_agreement or c2 < self.min_agreement:
+                rejected.append({'feature': f, 'reason': 'LOW_AGREEMENT',
+                                 'shape_v1': sh1, 'shape_v2': sh2,
+                                 'conf_v1': round(c1, 2), 'conf_v2': round(c2, 2)})
+                continue
+            if sh1 == sh2:
+                rejected.append({'feature': f, 'reason': 'NOT_CONFIRMED',
+                                 'shape_v1': sh1, 'shape_v2': sh2,
+                                 'conf_v1': round(c1, 2), 'conf_v2': round(c2, 2)})
+                continue
+            confirmed.append({'feature': f, 'shape_v1': sh1, 'shape_v2': sh2,
+                              'conf_v1': round(c1, 2), 'conf_v2': round(c2, 2),
+                              'amp_v1': round(a1, 5), 'amp_v2': round(a2, 5)})
+
+        score = max(0, 100 - len(confirmed) * 15)
+        return {
+            'divergences':   confirmed,
+            'screened':      [f for f, _, _ in screened],
+            'rejected':      rejected,
+            'n_screened':    len(screened),
+            'n_confirmed':   len(confirmed),
+            'n_features':    len(feature_names),
+            'health_score':  score,
+            'method':        'ALE + bootstrap seletivo',
+            'bootstrap_calls': len(screened) * self.n_boot * 2,
+        }
+
+    def report(self, r: dict) -> str:
+        L = [f"SelectiveALEDetector ({r['method']}):",
+             f"  Triagem: {r['n_screened']}/{r['n_features']} suspeitas  →  "
+             f"confirmadas: {r['n_confirmed']}",
+             f"  Chamadas de bootstrap: {r['bootstrap_calls']} "
+             f"(vs {r['n_features'] * 24} do bootstrap total)",
+             f"  Health Score: {r['health_score']}/100"]
+        for d in r['divergences']:
+            L.append(f"  ⚠ '{d['feature']}': {d['shape_v1']} → {d['shape_v2']} "
+                     f"(conf {d['conf_v1']:.0%}/{d['conf_v2']:.0%})")
+        for x in r['rejected']:
+            L.append(f"  ✓ '{x['feature']}' descartada: {x['reason']}")
+        if not r['divergences'] and not r['rejected']:
+            L.append("  ✅ Nenhuma suspeita na triagem.")
+        return "\n".join(L)