stmmlib 0.2.0__py3-none-any.whl

stmmlib/beta/criteria.py

@@ -0,0 +1,247 @@
+"""Conditional selection criteria for Beta STMM: cAIC + conditional R2.
+
+Single source of truth for the `beta_criteria` helper previously inlined
+in research notebooks. Import it instead of copying::
+
+    from stmmlib.beta.criteria import beta_criteria
+
+Formulas (validated):
+    cAIC (Huber et al. 2016):  -2 * ll_cond + 2 * df_hat
+        df_hat = tr(H_pen^-1 @ H_unpen), the Liang-Wu-Zou (2008) bias
+        correction. H_pen/_unpen use the Fisher weight w = phi*mu*(1-mu).
+    cR2 (Nakagawa & Schielzeth 2013, latent-scale working version):
+        vf = var(X beta); vre = mean(diag(Z G Z')), G = Q^-1;
+        vresid = mean(mu(1-mu)/(1+phi)).
+
+Fixes vs the old notebook copy:
+    - beta log-density SUBTRACTS ln B(a,b) (the old copy added it, which
+      produced a cAIC off by 4.8e6 from the correct value).
+    - mu is always recomputed from the fitted (beta, b_hat); a stored
+      mu_hat is never trusted.
+    - area SAR uses des["rho_bound"] (spectral bound), not the gamma bound.
+
+Guards (refuse garbage instead of printing it):
+    - df_hat must lie in [0, p+q] (theorem: H_pen = H_unpen + blkdiag(0,Q)).
+    - ll_cond sanity vs the Laplace marginal (loose heuristic tolerance).
+    - finite vre.
+
+Scope: flat (non-nested) models M1-M5, M8-M12. Nested fits (M6/M7/M13/M14)
+return all-NaN fields -- their [prov, kab, cell] precision needs its own
+builder (documented follow-up, not silent garbage).
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy.special import betaln
+
+from stmmlib.beta.precision import PrecisionShapeError
+
+
+def _as_opt(fit):
+    return fit._opt if hasattr(fit, "_opt") else fit
+
+
+def beta_criteria(fit, W=None):
+    """Compute cAIC, df_hat, ll_cond, cR2 for a fitted Beta STMM.
+
+    Args:
+        fit: BetastmmResult (or raw opt dict from beta_laplace_structural).
+        W: spatial weight matrix override (default: opt/des stored W).
+
+    Returns:
+        dict with cAIC, df_hat, ll_cond, cR2_marginal, cR2_conditional,
+        var_fixed, var_random_latent, var_resid_beta; NaN fields when the
+        inputs are inconsistent (never a garbage number). None only when
+        required arrays are missing or an unexpected error occurs.
+    """
+    if fit is None:
+        return None
+    try:
+        opt = _as_opt(fit)
+        X = opt.get("X")
+        Z = opt.get("Z")
+        y = opt.get("y")
+        des = opt.get("des", {}) or {}
+        model = opt.get("model", "")
+        if X is None or Z is None or y is None:
+            return None
+
+        beta = fit.beta if hasattr(fit, "_opt") else opt.get("beta_hat")
+        try:
+            phi = float(fit.phi) if hasattr(fit, "_opt") else float(opt.get("phi", 20.0))
+        except Exception:
+            phi = float(np.exp(np.asarray(opt.get("logphi", [np.log(20.0)]))).ravel()[0])
+
+        logs = np.asarray(opt.get("logs", np.zeros(2)), dtype=float).ravel()
+        raw_dep = np.asarray(opt.get("raw_dep", np.array([])), dtype=float).ravel()
+        bh = opt.get("b_hat")
+        if beta is None or bh is None:
+            return None
+        beta = np.asarray(beta, dtype=float).ravel()
+        bh = np.asarray(bh, dtype=float).ravel()
+
+        from stmmlib.beta.structure import stmm_beta_structure
+        s = stmm_beta_structure(model)
+        if s["area"] in ("nested_iid", "nested_sar"):
+            return _nan_result()  # nested precision: dedicated builder needed
+
+        blocks = des.get("blocks", {}) or {}
+        n_area = len(blocks.get("area", []))
+        n_time = len(blocks.get("area_time", blocks.get("time", [])))
+        # Area spectral bound (NOT the gamma bound) for the SAR display mapping
+        rb = des.get("rho_bound", des.get("rho_bound_g", 0.95))
+
+        blocks_Q = []
+        if s["area"] in ("iid",):
+            Q_a = np.exp(-2.0 * logs[0]) * np.eye(n_area)
+        elif s["area"] in ("sar", "nested_sar", "seblup_rao_yu"):
+            rho = rb * np.tanh(raw_dep[0]) if len(raw_dep) > 0 else 0.0
+            # BUG-B4 fix: explicit W argument wins; opt["W"] may be None even
+            # when the key exists (old expression silently ignored use_W).
+            W_arr = W if W is not None else opt.get("W")
+            if W_arr is None:
+                W_arr = des.get("W_gamma")
+            if W_arr is None:
+                W_arr = np.eye(n_area)
+            elif hasattr(W_arr, "toarray"):
+                W_arr = W_arr.toarray()
+            W_arr = np.asarray(W_arr, dtype=float)[:n_area, :n_area]
+            A = np.eye(n_area) - rho * W_arr
+            Q_a = np.exp(-2.0 * logs[0]) * (A.T @ A)
+        else:
+            Q_a = np.eye(n_area)
+        blocks_Q.append(Q_a)
+
+        area_specific = s.get("time_scope") == "area_specific"
+        if s["time"] == "ar1" and n_time > 0:
+            # Frozen model mapping: ar1_precision squashes phi_t again
+            # (pb*tanh(pb*tanh(raw))); keep the tridiagonal form here.
+            pb = des.get("phi_bound", 0.95)
+            phi_t = pb * np.tanh(raw_dep[1]) if len(raw_dep) > 1 else 0.0
+            sigma2_inv = np.exp(-2.0 * (logs[1] if len(logs) > 1 else 0.0))
+            if area_specific:
+                from stmmlib.beta.precision import ar1_precision as _ar1p
+                from stmmlib._backend import Backend as _B
+                from scipy.sparse import block_diag as _spbd
+                T_loc = int(des.get("T", len(blocks.get("time", []))))
+                TQ = _ar1p(max(T_loc, 1), logs[1] if len(logs) > 1 else 0.0, phi_t, _B(gpu=False),
+                           phi_bound=pb)
+                if hasattr(TQ, "toarray"):
+                    TQ = TQ.toarray()
+                Q_t = _spbd([TQ] * n_area, format="csr").toarray()
+            else:
+                di = np.full(n_time, 1.0 + phi_t ** 2)
+                di[0] = di[-1] = 1.0
+                Q_t = sigma2_inv * (np.diag(di)
+                                    + np.diag(np.full(n_time - 1, -phi_t), 1)
+                                    + np.diag(np.full(n_time - 1, -phi_t), -1))
+            blocks_Q.append(Q_t)
+        elif n_time > 0:
+            Q_t = np.exp(-2.0 * logs[1]) * np.eye(n_time) if len(logs) > 1 else np.eye(n_time)
+            blocks_Q.append(Q_t)
+
+        from scipy.sparse import block_diag as _spblockdiag
+        Q_base = _spblockdiag(blocks_Q)
+        if hasattr(Q_base, "toarray"):
+            Q_base = Q_base.toarray()
+
+        n_gamma = len(blocks.get("interaction", []))
+        if n_gamma > 0:
+            # Same Q_g the fit uses (shared helper): the diagonal shortcut here
+            # was wrong whenever rho_gamma/phi_gamma were nonzero (M9-M12).
+            from stmmlib._backend import Backend
+            from stmmlib.beta.solvers import beta_Q_gamma
+            Q_g = beta_Q_gamma(
+                s, des, int(des.get("m", n_area)), int(des.get("T", n_time)),
+                n_gamma, logs, raw_dep, len(logs), len(raw_dep),
+                s["area"] in ("sar", "seblup_rao_yu"),
+                s["time"] == "ar1", Backend(gpu=False))
+            if Q_g is not None and Q_g.size > 0:
+                Q_full = np.block([
+                    [Q_base, np.zeros((Q_base.shape[0], n_gamma))],
+                    [np.zeros((n_gamma, Q_base.shape[0])), Q_g]])
+            else:
+                Q_full = Q_base
+        else:
+            Q_full = Q_base
+
+        q = Z.shape[1]
+        if Q_full.shape[0] != q:
+            raise PrecisionShapeError(
+                f"Precision/design size mismatch: Q is {Q_full.shape[0]}x"
+                f"{Q_full.shape[1]} but Z has {q} columns."
+            )
+
+        # Conditional mean from the fitted (beta, b_hat) -- never stored mu_hat
+        mu = np.clip(1 / (1 + np.exp(-(X @ beta + Z @ bh))), 1e-10, 1 - 1e-10)
+        w = phi * mu * (1 - mu)
+        A11 = X.T @ (X * w[:, None])
+        A12 = X.T @ (Z * w[:, None])
+        A22 = Z.T @ (Z * w[:, None]) + Q_full
+        Hm = np.block([[A11, A12], [A12.T, A22]])
+        M22 = Z.T @ (Z * w[:, None])
+        Mm = np.block([[A11, A12], [A12.T, M22]])
+
+        # df guard: nested cells-in-areas make Z'WZ rank-deficient; without
+        # enough Q shrinkage the raw solve explodes. df in [0, p+q] or NaN.
+        p_dof = X.shape[1] + Z.shape[1]
+        try:
+            df_hat = float(np.trace(np.linalg.solve(Hm, Mm)))
+            if not np.isfinite(df_hat) or df_hat < 0 or df_hat > p_dof:
+                df_hat = np.nan
+        except np.linalg.LinAlgError:
+            df_hat = np.nan
+
+        # Conditional log-lik: (a-1)ln y + (b-1)ln(1-y) MINUS ln B(a,b)
+        a = mu * phi
+        b = (1 - mu) * phi
+        ll_cond = float(np.sum((a - 1) * np.log(np.clip(y, 1e-15, 1.0)) +
+                               (b - 1) * np.log(np.clip(1 - y, 1e-15, 1.0)) -
+                               betaln(a, b)))
+        # ll guard (loose heuristic): far below the Laplace marginal means
+        # stale inputs -- refuse garbage instead of printing it. Threshold
+        # max(10, 1%|ll|): tight enough to catch a miscalibrated mu, loose
+        # enough for Laplace-vs-mode wiggle on heavy-shrink fits. The
+        # absolute floor exists because at small |ll| a purely relative
+        # test has no power; it is a deliberate slack, not a measurement.
+        ll_marg = float(opt.get("log_lik", np.nan))
+        if (not np.isfinite(ll_cond) or not np.isfinite(df_hat)
+                or (np.isfinite(ll_marg)
+                    and ll_cond < ll_marg - max(10.0, 0.01 * abs(ll_marg)))):
+            out = _nan_result()
+            out["df_hat"], out["ll_cond"] = df_hat, ll_cond
+            return out
+        caic = -2 * ll_cond + 2 * df_hat
+
+        # cR2 (Nakagawa working version)
+        try:
+            G = np.linalg.inv(Q_full)
+            vre = np.sum((Z @ G) * Z) / len(y)
+            if not np.isfinite(vre):
+                vre = np.nan
+        except np.linalg.LinAlgError:
+            vre = np.nan
+        vf = float(np.var(X @ beta))
+        vresid = float(np.mean(mu * (1 - mu) / (1 + phi)))
+        tot = vf + vre + vresid
+        r2m = vf / tot if tot > 0 else np.nan
+        r2c = (vf + vre) / tot if tot > 0 else np.nan
+
+        return {
+            "cAIC": caic, "df_hat": df_hat, "ll_cond": ll_cond,
+            "cR2_marginal": r2m, "cR2_conditional": r2c,
+            "var_fixed": vf, "var_random_latent": vre, "var_resid_beta": vresid,
+        }
+    except PrecisionShapeError:
+        raise
+    except Exception:
+        return None
+
+
+def _nan_result():
+    nan = float("nan")
+    return {"cAIC": nan, "df_hat": nan, "ll_cond": nan,
+            "cR2_marginal": nan, "cR2_conditional": nan,
+            "var_fixed": nan, "var_random_latent": nan,
+            "var_resid_beta": nan}

stmmlib/beta/design.py

@@ -0,0 +1,222 @@
+"""Design matrix construction for Beta mixed models.
+
+Builds Z (area/time/cell/interaction), block indices, W_gamma,
+and metadata for the Beta STMM Laplace engine.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+import pandas as pd
+
+from stmmlib.beta.structure import stmm_beta_structure
+
+if TYPE_CHECKING:
+    from stmmlib._backend import Backend
+
+
+def stmm_beta_make_design(d: pd.DataFrame, model: str, W=None, backend: Backend = None,
+                          rho_bound: float = 0.95) -> dict:
+    """Construct design matrix Z and metadata for a Beta STMM.
+
+    Z has area-major cell order: (area1:time1..timeT, area2:time1..timeT, ...)
+
+    Args:
+        d: pandas DataFrame with area, time columns (internal names).
+        model: Model ID string.
+        W: Spatial weight matrix.
+        backend: Array backend.
+
+    Returns:
+        dict with Z, blocks, W_gamma, B_area, B_time, metadata.
+    """
+    if backend is None:
+        from stmmlib._backend import Backend
+        backend = Backend(gpu=False)
+
+    xp = backend.xp
+    s = stmm_beta_structure(model)
+    area = s["area"]
+    time = s["time"]
+    time_scope = s["time_scope"]
+    interaction = s["interaction"]
+
+    # Extract indices
+    area_col = ".stmm_area"
+    time_col = ".stmm_time"
+    area_idx = d[area_col].values.astype(np.int32)
+    time_idx = d[time_col].values.astype(np.int32)
+    n = len(d)
+    m = int(np.max(area_idx)) + 1
+    T = int(np.max(time_idx)) + 1
+    n_cell = m * T
+
+    # Build Z
+    from scipy.sparse import csr_matrix, eye as sp_eye, kron as sp_kron
+
+    def _make_Z(idx, n_rows, n_cols):
+        row = np.arange(n_rows, dtype=np.int32)
+        return csr_matrix((np.ones(n_rows, dtype=np.float64), (row, idx)), shape=(n_rows, n_cols))
+
+    # Nested hierarchy (M6/M7/M13/M14): Z = [Z_prov, Z_kab, Z_cell]
+    if area in ("nested_iid", "nested_sar"):
+        if ".stmm_prov" not in d.columns or ".stmm_kab" not in d.columns:
+            raise ValueError(
+                "Nested models require province and district columns; "
+                "pass prov_col=/kab_col= (defaults 'prov'/'kab').")
+        prov_idx = d[".stmm_prov"].values.astype(np.int32)
+        kab_idx = area_idx  # .stmm_area IS the kab level for nested models
+        n_prov = int(np.max(prov_idx)) + 1
+        n_kab = m
+        Z_prov = _make_Z(prov_idx, n, n_prov)
+        Z_kab = _make_Z(kab_idx, n, n_kab)
+        Zc = _make_Z(area_idx * T + time_idx, n, n_cell)
+        Z = np.hstack([Z_prov.toarray(), Z_kab.toarray(), Zc.toarray()])
+        blocks = {
+            "prov": list(range(n_prov)),
+            "kab": list(range(n_prov, n_prov + n_kab)),
+            "cell": list(range(n_prov + n_kab, n_prov + n_kab + n_cell)),
+        }
+        des = {
+            "Z": Z, "blocks": blocks, "W_gamma": None, "rho_bound_g": rho_bound,
+            "B_area": None, "B_time": None, "n": n, "m": m, "T": T,
+            "n_cell": n_cell, "n_gamma": 0,
+            "n_prov": n_prov, "n_kab": n_kab,
+            "area_labels": d[area_col].unique().tolist(),
+            "time_labels": sorted(d[time_col].unique().tolist()),
+            "area_idx": area_idx, "time_idx": time_idx,
+        }
+        # Interaction at kab x time level (M13 temporal / M14 iid)
+        if interaction != "none":
+            B_area = _contr_sum(m)
+            B_time = _contr_sum(T)
+            Z_gamma = _build_Z_gamma(area_idx, time_idx, n, m, T, interaction,
+                                     B_area, B_time)
+            n_gamma = Z_gamma.shape[1]
+            blocks["interaction"] = list(range(Z.shape[1], Z.shape[1] + n_gamma))
+            des["Z"] = np.hstack([Z, Z_gamma])
+            des["B_area"] = B_area
+            des["B_time"] = B_time
+            des["n_gamma"] = n_gamma
+        return des
+    else:
+        des = _design_flat(d, area, time, time_scope, interaction, W, backend,
+                           area_idx, time_idx, n, m, T, n_cell, _make_Z,
+                           rho_bound=rho_bound)
+    return des
+
+
+def _design_flat(d, area, time, time_scope, interaction, W, backend,
+                 area_idx, time_idx, n, m, T, n_cell, _make_Z,
+                 rho_bound: float = 0.95):
+    """Flat (non-nested) design: Z = [Z_area, Z_cell|Z_time] (+ Z_gamma)."""
+    # Area dummy
+    Z_area = _make_Z(area_idx, n, m)
+
+    # Cell dummy (area x time)
+    cell_idx = area_idx * T + time_idx
+    Z_cell = _make_Z(cell_idx, n, n_cell)
+
+    if time_scope == "global":
+        # Global: Z = [Z_area, Z_time]
+        Z_time = _make_Z(time_idx, n, T)
+        Z = np.hstack([Z_area.toarray(), Z_time.toarray()])
+        blocks = {
+            "area": list(range(m)),
+            "time": list(range(m, m + T)),
+        }
+    else:
+        # Area-specific: Z = [Z_area, Z_cell]
+        Z = np.hstack([Z_area.toarray(), Z_cell.toarray()])
+        blocks = {
+            "area": list(range(m)),
+            "area_time": list(range(m, m + n_cell)),
+        }
+
+    # Contrast matrices for interaction
+    B_area = None
+    B_time = None
+    W_gamma = None
+    rho_bound_g = rho_bound
+
+    if interaction != "none":
+        B_area = _contr_sum(m)
+        B_time = _contr_sum(T)
+
+        if interaction in ("spatial", "st") and W is not None:
+            if backend.is_sparse(W):
+                W_arr = W.toarray()
+            else:
+                W_arr = np.asarray(W, dtype=np.float64)
+            W_gamma = W_arr
+            # BUG-B1 fix: eigvals (spectral radius), NOT eigvalsh -- W is
+            # asymmetric; eigvalsh silently reads one triangle, so the
+            # spectral radius can come out wrong on a row-standardized
+            # weights matrix.
+            eigenvalues = np.linalg.eigvals(W_arr)
+            max_abs_eig = np.max(np.abs(eigenvalues))
+            rho_bound_g = rho_bound / max_abs_eig if max_abs_eig > 1e-10 else rho_bound
+
+        # Interaction Z
+        Z_gamma = _build_Z_gamma(area_idx, time_idx, n, m, T, interaction, B_area, B_time)
+        n_gamma = Z_gamma.shape[1]
+        blocks["interaction"] = list(range(Z.shape[1], Z.shape[1] + n_gamma))
+        Z = np.hstack([Z, Z_gamma])
+
+    return {
+        "Z": Z,
+        "blocks": blocks,
+        "W_gamma": W_gamma,
+        "rho_bound_g": rho_bound_g,
+        "B_area": B_area,
+        "B_time": B_time,
+        "n": n,
+        "m": m,
+        "T": T,
+        "n_cell": n_cell,
+        "n_gamma": Z_gamma.shape[1] if interaction != "none" else 0,
+        "area_labels": d[".stmm_area"].unique().tolist() if ".stmm_area" in d.columns else [],
+        "time_labels": sorted(d[".stmm_time"].unique().tolist()) if ".stmm_time" in d.columns else [],
+        "area_idx": area_idx,
+        "time_idx": time_idx,
+    }
+
+
+def _contr_sum(n: int):
+    """Sum-to-zero contrast matrix (R-style contr.sum). Returns n x (n-1)."""
+    if n <= 1:
+        return np.ones((1, 1), dtype=np.float64)
+    B = np.eye(n, dtype=np.float64)[:, :-1]
+    B[-1, :] = -1.0
+    return B
+
+
+def _build_Z_gamma(area_idx, time_idx, n, m, T, interaction, B_area, B_time):
+    """Build Z_gamma from contrast matrices and full cell Z."""
+    from scipy.sparse import eye as sp_eye, kron as sp_kron, csr_matrix
+
+    # Full cell Z
+    cell_idx = area_idx * T + time_idx
+    Z_full = csr_matrix(
+        (np.ones(n, dtype=np.float64), (np.arange(n, dtype=np.int32), cell_idx)),
+        shape=(n, m * T),
+    )
+
+    m1 = B_area.shape[1]
+    T1 = B_time.shape[1]
+
+    if interaction == "iid":
+        K = sp_kron(csr_matrix(B_area), sp_eye(T, dtype=np.float64), format="csr")
+    elif interaction == "spatial":
+        K = sp_kron(csr_matrix(B_area), sp_eye(T, dtype=np.float64), format="csr")
+    elif interaction == "temporal":
+        K = sp_kron(sp_eye(m, dtype=np.float64), csr_matrix(B_time), format="csr")
+    elif interaction == "st":
+        K = sp_kron(csr_matrix(B_area), csr_matrix(B_time), format="csr")
+    else:
+        return np.zeros((n, 0), dtype=np.float64)
+
+    Z_gamma = (Z_full @ K).toarray()
+    return Z_gamma

stmmlib/beta/diagnose.py

@@ -0,0 +1,168 @@
+"""Boundary diagnosis for AR/precision parameters (pure decision logic).
+
+Maps the manual decision tree in docs/notes/PENANGANAN_BOUNDARY_AR_PHI.md into a
+pure function: no fitting, no simulation, no data access. It only classifies
+evidence the caller already collected (seed endpoints, bound sensitivity,
+gradient, panel length T).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class BoundaryDiagnosis:
+    """Structured boundary verdict (not free text)."""
+
+    classification: str
+    evidence: list = field(default_factory=list)
+    recommended_action: str = ""
+    citations: list = field(default_factory=list)
+
+
+_CITATIONS = [
+    "Nickell (1981) panel pile-up on short T",
+    "Chung et al. (2013) penalized likelihood for variance parameters",
+]
+
+_SEED_TOL = 1e-6
+_SHIFT_TOL = 0.01
+_GRAD_TOL = 1.0
+
+
+def _as_floats(values) -> list:
+    out = []
+    for v in values:
+        try:
+            if isinstance(v, (tuple, list)) and len(v) > 0:
+                v = v[0]
+            out.append(float(v))
+        except (TypeError, ValueError):
+            continue
+    return out
+
+
+def diagnose_boundary(
+    fit_result=None,
+    *,
+    n_seeds_tested: int = 0,
+    seed_endpoints=(),
+    bound_sensitivity=None,
+    gradient_at_solution=None,
+    T=None,
+    t_warn: int = 15,
+) -> BoundaryDiagnosis:
+    """Classify a boundary solution from collected evidence (pure function).
+
+    Rules: non-identical seed endpoints -> MULTI_BASIN; identical endpoints
+    with a significant bound shift and a small gradient -> ARTIFICIAL_BOUND;
+    identical endpoints with no shift and a large gradient ->
+    STRUCTURAL_BOUNDARY (dual ML + penalized report required, no cosmetic
+    fix). T < t_warn appends a Nickell/pile-up warning to evidence.
+    """
+    evidence: list = []
+    grad = gradient_at_solution
+    tt = T
+    if grad is None and fit_result is not None:
+        try:
+            om = (fit_result._opt or {}).get("optim", {}) or {}
+            g = om.get("grad_norm")
+            grad = float(g) if g is not None else None
+        except (AttributeError, TypeError, ValueError):
+            grad = None
+    if tt is None and fit_result is not None:
+        try:
+            des = (fit_result._opt or {}).get("des", {}) or {}
+            tt = des.get("T")
+        except (AttributeError, TypeError):
+            tt = None
+
+    endpoints = _as_floats(seed_endpoints or ())
+    n_seed_info = len(endpoints)
+    if n_seed_info >= 2:
+        spread = max(endpoints) - min(endpoints)
+        identical = spread <= _SEED_TOL
+        evidence.append(
+            f"{n_seed_info} seed endpoints, spread {spread:.3g} "
+            f"({'identical' if identical else 'not identical'})."
+        )
+    else:
+        identical = True
+        evidence.append(
+            f"Only {n_seed_info} seed endpoint(s) "
+            f"(n_seeds_tested={n_seeds_tested}); multi-basin not ruled out."
+        )
+
+    shift = None
+    shifted = False
+    if isinstance(bound_sensitivity, dict) and len(bound_sensitivity) >= 2:
+        vals = _as_floats(bound_sensitivity.values())
+        if vals:
+            shift = max(vals) - min(vals)
+            shifted = shift > _SHIFT_TOL
+            evidence.append(
+                f"Bound sensitivity over {len(vals)} settings, "
+                f"shift {shift:.3g} "
+                f"({'significant' if shifted else 'small'})."
+            )
+    elif bound_sensitivity is not None:
+        evidence.append("Bound sensitivity incomplete (need 2+ settings).")
+
+    if grad is not None:
+        try:
+            evidence.append(f"Gradient at solution {float(grad):.3g}.")
+        except (TypeError, ValueError):
+            pass
+    grad_large = grad is not None and float(grad) >= _GRAD_TOL
+    grad_small = grad is not None and float(grad) < _GRAD_TOL
+
+    if tt is not None:
+        try:
+            evidence.append(f"Panel length T={tt}.")
+        except (TypeError, ValueError):
+            pass
+
+    if not identical:
+        classification = "MULTI_BASIN"
+        action = "Perbanyak seed dan perbaiki starting value."
+    elif shifted and grad_small:
+        classification = "ARTIFICIAL_BOUND"
+        action = "Longgarkan bound berdasar bukti sensitivitas."
+    elif (not shifted) and grad_large and shift is not None:
+        classification = "STRUCTURAL_BOUNDARY"
+        action = (
+            "Wajib lapor ganda ML dan penalized/Bayes modal; "
+            "larang cosmetic fix."
+        )
+    elif shift is None and grad_large:
+        classification = "STRUCTURAL_BOUNDARY"
+        action = (
+            "Wajib lapor ganda ML dan penalized/Bayes modal; "
+            "larang cosmetic fix (sensitivitas bound disarankan)."
+        )
+    elif grad_large and shifted:
+        classification = "STRUCTURAL_BOUNDARY"
+        action = (
+            "Wajib lapor ganda ML dan penalized/Bayes modal; "
+            "larang cosmetic fix."
+        )
+    else:
+        classification = "INDETERMINATE"
+        action = "Lengkapi bukti (seed, sensitivitas bound, gradien)."
+
+    try:
+        if tt is not None and float(tt) < float(t_warn):
+            evidence.append(
+                f"T={tt} < {t_warn}: warning Nickell bias and pile-up "
+                "pada panel pendek."
+            )
+    except (TypeError, ValueError):
+        pass
+
+    return BoundaryDiagnosis(
+        classification=classification,
+        evidence=evidence,
+        recommended_action=action,
+        citations=list(_CITATIONS),
+    )