stmmlib 0.2.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. stmmlib/__init__.py +30 -0
  2. stmmlib/_backend.py +153 -0
  3. stmmlib/_utils.py +175 -0
  4. stmmlib/beta/__init__.py +17 -0
  5. stmmlib/beta/config.py +108 -0
  6. stmmlib/beta/criteria.py +247 -0
  7. stmmlib/beta/design.py +222 -0
  8. stmmlib/beta/diagnose.py +168 -0
  9. stmmlib/beta/diagnostics.py +94 -0
  10. stmmlib/beta/fit.py +598 -0
  11. stmmlib/beta/gpu_solvers.py +169 -0
  12. stmmlib/beta/inference.py +403 -0
  13. stmmlib/beta/lrt_fixed.py +551 -0
  14. stmmlib/beta/moran_panel.py +733 -0
  15. stmmlib/beta/plot_data.py +252 -0
  16. stmmlib/beta/precision.py +98 -0
  17. stmmlib/beta/report.py +373 -0
  18. stmmlib/beta/result.py +696 -0
  19. stmmlib/beta/simulation.py +343 -0
  20. stmmlib/beta/solvers.py +2021 -0
  21. stmmlib/beta/structure.py +56 -0
  22. stmmlib/diagnostics_suite.py +663 -0
  23. stmmlib/gaussian/__init__.py +1 -0
  24. stmmlib/gaussian/blup.py +252 -0
  25. stmmlib/gaussian/covariance.py +599 -0
  26. stmmlib/gaussian/design.py +312 -0
  27. stmmlib/gaussian/diagnostics.py +308 -0
  28. stmmlib/gaussian/gls.py +285 -0
  29. stmmlib/gaussian/hessian.py +197 -0
  30. stmmlib/gaussian/lrt_fixed.py +289 -0
  31. stmmlib/gaussian/models.py +528 -0
  32. stmmlib/gaussian/optimization.py +361 -0
  33. stmmlib/gaussian/simulation.py +186 -0
  34. stmmlib/gaussian/summary.py +277 -0
  35. stmmlib/gaussian/transforms.py +419 -0
  36. stmmlib/gaussian/variance_decomp.py +191 -0
  37. stmmlib/lrt.py +74 -0
  38. stmmlib/output_format.py +148 -0
  39. stmmlib/output_format_beta.py +299 -0
  40. stmmlib/output_format_normal.py +118 -0
  41. stmmlib/registry.py +326 -0
  42. stmmlib/stmm.py +265 -0
  43. stmmlib-0.2.0.dist-info/METADATA +215 -0
  44. stmmlib-0.2.0.dist-info/RECORD +47 -0
  45. stmmlib-0.2.0.dist-info/WHEEL +5 -0
  46. stmmlib-0.2.0.dist-info/licenses/LICENSE +21 -0
  47. stmmlib-0.2.0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,169 @@
1
+ """GPU-accelerated (torch) variants of the Laplace hot loops.
2
+
3
+ Only the per-area T x T batched solves/logdets move to GPU; the cheap
4
+ curvature/score (numpy digamma/polygamma) and the outer L-BFGS-B stay on CPU.
5
+ Numerically identical to the numpy blocked solvers in solvers.py within fp
6
+ tolerance (float64 on CUDA).
7
+
8
+ When CUDA is unavailable these functions fall back to the numpy reference.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ import numpy as np
14
+
15
+ _TORCH = None
16
+
17
+
18
+ def _get_torch():
19
+ global _TORCH
20
+ if _TORCH is None:
21
+ try:
22
+ import torch
23
+ _TORCH = torch
24
+ except Exception:
25
+ _TORCH = False
26
+ return _TORCH
27
+
28
+
29
+ def gpu_available() -> bool:
30
+ torch = _get_torch()
31
+ return bool(torch) and torch.cuda.is_available() and torch.cuda.device_count() > 0
32
+
33
+
34
+ def _to_torch(torch, arr, device):
35
+ return torch.from_numpy(np.ascontiguousarray(arr, dtype=np.float64)).to(device)
36
+
37
+
38
+ def beta_mode_newton_blocked_gpu(X, Z, Q, m, T, beta, logphi, y, max_iter=50,
39
+ start_b=None, inner_tol=1e-6,
40
+ _numpy=None):
41
+ """Batched-torch version of beta_mode_newton_blocked (see solvers.py)."""
42
+ import torch
43
+
44
+ from stmmlib.beta.solvers import beta_nll_curvature, _beta_nll_score
45
+
46
+ if _numpy is None:
47
+ from stmmlib.beta.solvers import beta_mode_newton_blocked as _numpy
48
+
49
+ n, p = X.shape
50
+ phi = np.exp(logphi)
51
+ area_idx = Z[:, :m].argmax(1)
52
+ cell_idx = Z[:, m:].argmax(1)
53
+ cell_area = cell_idx // T
54
+ cell_time = cell_idx % T
55
+
56
+ u = np.zeros(m, dtype=np.float64) if start_b is None else start_b[:m].astype(np.float64).copy()
57
+ v = np.zeros(m * T, dtype=np.float64) if start_b is None else start_b[m:].astype(np.float64).copy()
58
+
59
+ Q_a = Q[:m, :m]
60
+ Qc_by_area = np.stack([Q[m:, m:][a*T:(a+1)*T, a*T:(a+1)*T] for a in range(m)])
61
+ Q_a_diag = np.ascontiguousarray(np.diag(Q_a))
62
+
63
+ dev = "cuda"
64
+ t_Qc = _to_torch(torch, Qc_by_area, dev) # (m, T, T)
65
+ t_Qa = _to_torch(torch, Q_a, dev) # (m, m)
66
+ t_Qa_diag = _to_torch(torch, Q_a_diag, dev) # (m,)
67
+ t_area = torch.from_numpy(area_idx).to(dev)
68
+ t_carea = torch.from_numpy(cell_area).to(dev)
69
+ t_ctime = torch.from_numpy(cell_time).to(dev)
70
+
71
+ for it in range(max_iter):
72
+ eta = X @ beta + u[area_idx] + v[cell_idx]
73
+ w = beta_nll_curvature(eta, y, phi)
74
+ s = _beta_nll_score(eta, y, phi)
75
+
76
+ w_cell = np.zeros((m, T), dtype=np.float64)
77
+ s_cell = np.zeros((m, T), dtype=np.float64)
78
+ np.add.at(w_cell, (cell_area, cell_time), w)
79
+ np.add.at(s_cell, (cell_area, cell_time), s)
80
+ roww = np.bincount(area_idx, weights=w, minlength=m)
81
+
82
+ g_u = np.bincount(area_idx, weights=s, minlength=m) + Q_a @ u
83
+ g_v = s_cell.ravel() + (Q[m:, m:] @ v)
84
+
85
+ t_wc = _to_torch(torch, w_cell, dev) # (m, T)
86
+ t_gv = _to_torch(torch, g_v, dev).reshape(m, T, 1)
87
+ t_gv2 = _to_torch(torch, g_v, dev).reshape(m, T)
88
+ C = t_Qc + torch.diag_embed(t_wc) # (m, T, T)
89
+ cwCinv = torch.linalg.solve(C, t_wc.unsqueeze(2))[:, :, 0] # (m, T)
90
+ Cinv_gv = torch.linalg.solve(C, t_gv)[:, :, 0] # (m, T)
91
+
92
+ S_diag = roww + Q_a_diag - (t_wc * cwCinv).sum(1).cpu().numpy()
93
+ rhs_u = -g_u + (t_wc * Cinv_gv).sum(1).cpu().numpy()
94
+
95
+ if np.allclose(Q_a, np.diag(Q_a_diag)):
96
+ du = rhs_u / np.maximum(S_diag, 1e-12)
97
+ else:
98
+ S_full = np.diag(S_diag) + (Q_a - np.diag(Q_a_diag))
99
+ try:
100
+ du = np.linalg.solve(S_full, rhs_u)
101
+ except np.linalg.LinAlgError:
102
+ du = np.linalg.lstsq(S_full, rhs_u, rcond=None)[0]
103
+
104
+ t_du = torch.from_numpy(du).to(dev)
105
+ rhs_v = -t_gv2 - t_wc * t_du.unsqueeze(1) # (m, T)
106
+ dv_b = torch.linalg.solve(C, rhs_v.unsqueeze(2))[:, :, 0]
107
+ dv = dv_b.cpu().numpy().ravel()
108
+
109
+ scale = 1.0
110
+ for _ in range(12):
111
+ u_new = u + scale * du
112
+ v_new = v + scale * dv
113
+ eta_new = X @ beta + u_new[area_idx] + v_new[cell_idx]
114
+ w_new = beta_nll_curvature(eta_new, y, phi)
115
+ if np.all(np.isfinite(w_new)):
116
+ u, v = u_new, v_new
117
+ break
118
+ scale *= 0.5
119
+ else:
120
+ break
121
+
122
+ scale = 1.0 + np.max(np.abs(np.concatenate([u, v])))
123
+ if np.max(np.abs(np.concatenate([du, dv]))) < inner_tol * scale:
124
+ return np.concatenate([u, v]), True, "blocked-gpu", it
125
+
126
+ return np.concatenate([u, v]), False, "blocked-gpu", it
127
+
128
+
129
+ def laplace_block_logdets_gpu(Z, w, Q, m, T, _numpy=None):
130
+ """Batched-torch version of laplace_block_logdets (see solvers.py)."""
131
+ import torch
132
+
133
+ from stmmlib.beta.solvers import laplace_block_logdets as _numpy
134
+
135
+ area_idx = Z[:, :m].argmax(1)
136
+ cell_idx = Z[:, m:].argmax(1)
137
+ cell_area = cell_idx // T
138
+ cell_time = cell_idx % T
139
+ Q_a = Q[:m, :m]
140
+ Q_c = Q[m:, m:]
141
+
142
+ roww = np.bincount(area_idx, weights=w, minlength=m)
143
+ w_cell = np.zeros((m, T), dtype=np.float64)
144
+ np.add.at(w_cell, (cell_area, cell_time), w)
145
+ Q_a_diag = np.ascontiguousarray(np.diag(Q_a))
146
+
147
+ dev = "cuda"
148
+ t_Qc = _to_torch(torch, np.stack([Q_c[a*T:(a+1)*T, a*T:(a+1)*T] for a in range(m)]), dev)
149
+ t_Qa = _to_torch(torch, Q_a, dev)
150
+ t_Qa_diag = _to_torch(torch, Q_a_diag, dev)
151
+ t_wc = _to_torch(torch, w_cell, dev)
152
+ C = t_Qc + torch.diag_embed(t_wc)
153
+ _sgn, ldet = torch.linalg.slogdet(C)
154
+ logdet_C = float(ldet.sum().cpu().item())
155
+ cwCinv = torch.linalg.solve(C, t_wc.unsqueeze(2))[:, :, 0]
156
+ S_diag = roww + Q_a_diag - (t_wc * cwCinv).sum(1).cpu().numpy()
157
+
158
+ if np.allclose(Q_a, np.diag(Q_a_diag)):
159
+ logdet_S = np.sum(np.log(np.maximum(S_diag, 1e-12)))
160
+ else:
161
+ S_full = np.diag(S_diag) + (Q_a - np.diag(Q_a_diag))
162
+ logdet_S = np.linalg.slogdet(S_full)[1]
163
+
164
+ logdet_H = logdet_C + logdet_S
165
+ logdet_Q = float(torch.linalg.slogdet(t_Qa)[1].cpu().item())
166
+ logdet_Qblocks = float(torch.linalg.slogdet(t_Qc)[1].sum().cpu().item())
167
+ logdet_Q = logdet_Q + logdet_Qblocks
168
+
169
+ return logdet_H, logdet_Q
@@ -0,0 +1,403 @@
1
+ """Standard errors, Wald tests, and inference for Beta STMMs.
2
+
3
+ Uses numerical Hessian from optim_results to compute:
4
+ - SEs for all parameters (beta, logphi, log_sigma, raw_dep)
5
+ - Wald t-tests and p-values
6
+ - Confidence intervals
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import numpy as np
12
+ from scipy.stats import norm
13
+
14
+ from stmmlib.beta.precision import PrecisionShapeError
15
+
16
+
17
+ def compute_stbl_inference(optim_results: dict, method: str = "numeric",
18
+ skip_hessian: bool = False) -> dict:
19
+ """Compute standard errors from Hessian of the Laplace objective.
20
+
21
+ Args:
22
+ optim_results: Output from beta_laplace_structural.
23
+ method: "numeric" (finite-difference Hessian, fast) or "profile"
24
+ (adds opt-in likelihood-profile SEs for structural/dependence
25
+ params; one 1-D scan per param, slower).
26
+ skip_hessian: True skips ALL Hessian work (fast/medium presets) --
27
+ se/vcov come back NaN/None and hessian_pd None. Display code must
28
+ say "SE tidak dihitung", never silently present NaNs as numbers.
29
+
30
+ Returns:
31
+ dict with se, tvalues, pvalues for all parameters, plus the split
32
+ se_fixed / se_structural and explicit hessian_pd / near_pd_applied
33
+ flags (never hide a repaired Hessian).
34
+ """
35
+ from stmmlib.beta.solvers import beta_nll_curvature
36
+
37
+ p = optim_results["p"]
38
+ ksd = optim_results.get("ksd", 2)
39
+ k = optim_results["k"]
40
+ n = optim_results["n"]
41
+
42
+ beta_hat = optim_results["beta_hat"]
43
+ logphi = optim_results["logphi"]
44
+ logs = optim_results["logs"]
45
+ raw_dep = optim_results["raw_dep"]
46
+
47
+ if skip_hessian:
48
+ return _empty_inference(optim_results, p, ksd, raw_dep)
49
+
50
+ param_vec = np.concatenate([beta_hat, [logphi], logs, raw_dep])
51
+ n_params = len(param_vec)
52
+
53
+ # Single Hessian source: solver H only (eps 1e-4 at best_param via
54
+ # _neg_marginal_l with warm-chain inner plus polish). A second FD
55
+ # computed here gives a materially different answer, so it is not
56
+ # computed: missing H means honest NaNs.
57
+ _H_solver = (optim_results.get("optim", {}) or {}).get("hessian")
58
+ if _H_solver is None or np.asarray(_H_solver).shape != (n_params, n_params):
59
+ _na = _empty_inference(optim_results, p, ksd, raw_dep)
60
+ _na["hessian_note"] = ("Hessian solver tidak tersedia; SE tidak dihitung "
61
+ "(sumber tunggal: Hessian solver, tanpa hitung ulang).")
62
+ return _na
63
+ H = np.asarray(_H_solver, dtype=np.float64)
64
+
65
+ # Ensure positive definite. A non-PD Hessian at the converged point means
66
+ # the point may not be a valid local maximum or the model is weakly
67
+ # identified (Pawitan 2001). Always report explicitly when near_pd() was
68
+ # applied; never present a repaired Hessian silently as clean.
69
+ hessian_pd = False
70
+ near_pd_applied = False
71
+ lambda_min = float("nan")
72
+ try:
73
+ from stmmlib._utils import is_pd, near_pd
74
+ from stmmlib._backend import Backend
75
+ backend = Backend(gpu=False)
76
+ lambda_min = float(np.linalg.eigvalsh(H).min())
77
+ if is_pd(H, backend):
78
+ hessian_pd = True
79
+ else:
80
+ near_pd_applied = True
81
+ H = near_pd(H, backend)
82
+ V = np.linalg.inv(H)
83
+ se = np.sqrt(np.maximum(np.diag(V), 0))
84
+ except np.linalg.LinAlgError:
85
+ se = np.full(n_params, np.nan)
86
+
87
+ tvalues = param_vec / se
88
+ pvalues = 2 * (1 - norm.cdf(np.abs(tvalues)))
89
+
90
+ # Parameter labels (shared with the skip_hessian path below)
91
+ labels = _inference_labels(optim_results, raw_dep, ksd, p)
92
+
93
+
94
+ # Split inference: Wald SEs are reliable for fixed effects (linear
95
+ # predictor scale). For structural/dependence parameters the Wald SE is
96
+ # only indicative on the transformed scale and can be unreliable near
97
+ # boundaries; prefer likelihood-profile SEs (method="profile", opt-in:
98
+ # slower, one 1-D scan per structural param).
99
+ p_fixed = int(p)
100
+ p_struct = int(p + 1 + ksd + len(raw_dep))
101
+ se_wald = se
102
+ se_profile = _profile_se(param_vec, p_fixed, p_struct, optim_results) if method == "profile" else np.full(p_struct - p_fixed, np.nan)
103
+
104
+ return {
105
+ "param_labels": labels,
106
+ "estimate": param_vec,
107
+ "se": se_wald,
108
+ "se_fixed": se_wald[:p_fixed],
109
+ "se_structural": se_wald[p_fixed:p_struct],
110
+ "se_profile_structural": se_profile,
111
+ "tvalue": tvalues,
112
+ "pvalue": pvalues,
113
+ "vcov": V if not np.any(np.isnan(se_wald)) else None,
114
+ "hessian_pd": bool(hessian_pd),
115
+ "lambda_min": lambda_min,
116
+ "near_pd_applied": bool(near_pd_applied),
117
+ "hessian_note": (
118
+ "Hessian tidak PD, diperbaiki via near_pd(). Titik konvergensi mungkin "
119
+ "bukan maksimum lokal valid / identifiability lemah."
120
+ if near_pd_applied else "Hessian positive definite."
121
+ ),
122
+ }
123
+
124
+
125
+ def _inference_labels(optim_results: dict, raw_dep, ksd: int, p: int) -> list:
126
+ """Parameter labels by role (single copy used by both inference paths)."""
127
+ x_cols = optim_results.get("des", {}).get("x_cols", [])
128
+ labels = ["(Intercept)"] + x_cols + ["log(phi)"]
129
+ from stmmlib.beta.structure import stmm_beta_structure
130
+ _s = stmm_beta_structure(optim_results["model"])
131
+ _is_nested = "prov" in optim_results.get("des", {}).get("blocks", {})
132
+ # Sigma labels by role: flat = [area, time, (gamma)];
133
+ # nested = [prov, kab, (eta if ar1), (gamma)]
134
+ _sig_names = (["log_sigma_prov", "log_sigma_kab"]
135
+ if _is_nested else ["log_sigma_area", "log_sigma_time"])
136
+ if _is_nested and _s["time"] == "ar1":
137
+ _sig_names.append("log_sigma_eta")
138
+ if ksd > len(_sig_names):
139
+ _sig_names.append("log_sigma_gamma")
140
+ labels += _sig_names
141
+ # Dependence names by role, in raw_dep order. Labels say "raw_* (atanh)":
142
+ # these are the internal optimizer parameters, NOT the model's rho/phi
143
+ # (rho = rb*tanh(raw), phi = phi_bound*tanh(...), phi_bound from des);
144
+ # transformed values are shown alongside in the summary table.
145
+ _dep_names = []
146
+ if _s["area"] in ("sar", "seblup_rao_yu"):
147
+ _dep_names.append("raw_rho (atanh)")
148
+ if _s["time"] == "ar1":
149
+ _dep_names.append("raw_phi_T (atanh)")
150
+ if _s["interaction"] in ("spatial", "st"):
151
+ _dep_names.append("raw_rho_gamma (atanh)")
152
+ if _s["interaction"] in ("temporal", "st"):
153
+ _dep_names.append("raw_phi_gamma (atanh)")
154
+ labels += _dep_names + [f"raw_dep_{i}" for i in range(len(raw_dep) - len(_dep_names))]
155
+ return labels
156
+
157
+
158
+ def _empty_inference(optim_results: dict, p: int, ksd: int, raw_dep) -> dict:
159
+ """No-Hessian inference shell: estimates + labels, SEs all NaN."""
160
+ beta_hat = np.asarray(optim_results["beta_hat"], dtype=float)
161
+ logphi = float(np.asarray(optim_results["logphi"], dtype=float).ravel()[0])
162
+ logs = np.asarray(optim_results["logs"], dtype=float).ravel()
163
+ raw_dep = np.asarray(raw_dep, dtype=float).ravel()
164
+ param_vec = np.concatenate([beta_hat, [logphi], logs, raw_dep])
165
+ n_all = len(param_vec)
166
+ nan = np.full(n_all, np.nan)
167
+ p_struct = int(p + 1 + ksd + len(raw_dep))
168
+ return {
169
+ "param_labels": _inference_labels(optim_results, raw_dep, ksd, p),
170
+ "estimate": param_vec,
171
+ "se": nan,
172
+ "se_fixed": nan[:p],
173
+ "se_structural": nan[p:p_struct],
174
+ "se_profile_structural": np.full(max(p_struct - p, 0), np.nan),
175
+ "tvalue": nan,
176
+ "pvalue": nan,
177
+ "vcov": None,
178
+ "hessian_pd": None,
179
+ "lambda_min": float("nan"),
180
+ "near_pd_applied": False,
181
+ "hessian_note": ("Hessian tidak dihitung (mode fast/medium) -- "
182
+ "SE/Wald/CI tidak tersedia."),
183
+ }
184
+
185
+
186
+ def _profile_se(param_vec: np.ndarray, p_fixed: int, p_struct: int,
187
+ optim_results: dict) -> np.ndarray:
188
+ """Likelihood-profile SEs for structural/dependence params via 1-D scans.
189
+
190
+ For each structural parameter j (>= p_fixed), find the interval where the
191
+ profiled negative log-likelihood rises by chi2_1(0.95)/2 = 1.9207 from its
192
+ minimum; SE = (upper-lower)/(2*1.96). Returns NaN when the scan hits a
193
+ boundary or the objective does not rise enough (weakly identified).
194
+
195
+ Cost is bounded (a few dozen objective evals per parameter), so this is
196
+ opt-in at the call site and skipped when the objective is unbounded.
197
+ """
198
+ n_struct = p_struct - p_fixed
199
+ se = np.full(n_struct, np.nan, dtype=np.float64)
200
+ if n_struct <= 0:
201
+ return se
202
+ thr = 1.920729 # 0.5 * chi2_1(0.95) = 0.5*3.841459
203
+ grid = np.linspace(-2.0, 2.0, 41) # steps in units of Wald SE
204
+ base = _neg_loglik_for_hessian(param_vec, optim_results)
205
+
206
+ for k in range(n_struct):
207
+ idx = p_fixed + k
208
+ sd = _safe_wald_sd(param_vec, p_fixed, p_struct, optim_results, k)
209
+ if not np.isfinite(sd) or sd <= 0:
210
+ continue
211
+ cross = []
212
+ for s in grid:
213
+ pv = param_vec.copy()
214
+ pv[idx] += s * sd
215
+ try:
216
+ ll = _neg_loglik_for_hessian(pv, optim_results)
217
+ except Exception:
218
+ ll = np.nan
219
+ if np.isfinite(ll):
220
+ cross.append((s, ll - base))
221
+ if not cross:
222
+ continue
223
+ # lower crossing (profile rises to threshold below the min)
224
+ lo = hi = np.nan
225
+ for s, delta in cross:
226
+ if s < 0 and np.isfinite(delta) and delta <= thr:
227
+ lo = s
228
+ for s, delta in cross:
229
+ if s > 0 and np.isfinite(delta) and delta <= thr:
230
+ hi = s
231
+ if np.isfinite(lo) and np.isfinite(hi):
232
+ se[k] = (hi - lo) * sd / (2 * 1.96)
233
+ return se
234
+
235
+
236
+ def _safe_wald_sd(param_vec, p_fixed, p_struct, optim_results, k) -> float:
237
+ """Diagonal Wald SD for one structural param, or NaN if unusable."""
238
+ try:
239
+ _pv = param_vec.copy()
240
+ eps = 1e-5
241
+ for i in range(p_fixed, p_struct):
242
+ pp = _pv.copy(); pm = _pv.copy()
243
+ pp[i] += eps; pm[i] -= eps
244
+ fp = _neg_loglik_for_hessian(pp, optim_results)
245
+ fm = _neg_loglik_for_hessian(pm, optim_results)
246
+ dd = (fp - 2 * _neg_loglik_for_hessian(_pv, optim_results) + fm) / eps**2
247
+ if i == p_fixed + k:
248
+ return float(np.sqrt(1.0 / dd)) if dd > 1e-12 else np.nan
249
+ except Exception:
250
+ return np.nan
251
+ return np.nan
252
+
253
+
254
+ def _neg_loglik_for_hessian(param_vec: np.ndarray, optim_results: dict) -> float:
255
+ """Evaluate negative marginal log-likelihood at given parameter vector."""
256
+ from scipy.special import betaln
257
+ from stmmlib.beta.solvers import beta_nll_curvature
258
+ from stmmlib.beta.precision import ar1_precision
259
+ from stmmlib.beta.design import stmm_beta_make_design
260
+ from stmmlib.beta.structure import stmm_beta_structure
261
+
262
+ p = optim_results["p"]
263
+ ksd = optim_results.get("ksd", 2)
264
+ n = optim_results["n"]
265
+ Z = optim_results["Z"]
266
+ X = optim_results["X"]
267
+ y = optim_results["y"]
268
+ des = optim_results["des"]
269
+ model = optim_results["model"]
270
+ blocks = des["blocks"]
271
+ n_area = len(blocks.get("area", []))
272
+ n_time = len(blocks.get("area_time", blocks.get("time", [])))
273
+ n_gamma = len(blocks.get("interaction", []))
274
+
275
+ beta = param_vec[:p]
276
+ logphi = param_vec[p]
277
+ logs = param_vec[p + 1: p + 1 + ksd]
278
+ raw_dep = param_vec[p + 1 + ksd:]
279
+ phi = np.exp(logphi)
280
+
281
+ # Assemble Q (profile path only; main SEs use solver H above).
282
+ s = stmm_beta_structure(model)
283
+ rb = des.get("rho_bound", des.get("rho_bound_g", 0.95))
284
+ _pb = des.get("phi_bound", 0.95)
285
+ from stmmlib._backend import Backend
286
+ backend = Backend(gpu=False)
287
+
288
+ _has_sar = s["area"] in ("sar", "seblup_rao_yu")
289
+ _has_ar1 = s["time"] == "ar1"
290
+ is_nested = "prov" in blocks
291
+ _raw_len = len(raw_dep)
292
+ _rho_i = 0 if _has_sar else None
293
+ _ph_i = (1 if _has_sar else 0) if _has_ar1 else None
294
+
295
+ from scipy.sparse import block_diag as _sp_blkdiag
296
+ blocks_Q = []
297
+ if is_nested:
298
+ # Nested hierarchy: [prov, kab, cell]; cell time shares kab variance
299
+ # for iid time (B9) and uses its own eta variance for AR(1) time.
300
+ n_prov = len(blocks.get("prov", []))
301
+ n_kab = len(blocks.get("kab", []))
302
+ n_cell = len(blocks.get("cell", []))
303
+ blocks_Q.append(np.exp(-2.0 * logs[0]) * np.eye(n_prov, dtype=np.float64))
304
+ blocks_Q.append(np.exp(-2.0 * logs[1]) * np.eye(n_kab, dtype=np.float64))
305
+ if _has_ar1:
306
+ ph = _pb * np.tanh(raw_dep[_ph_i]) if _raw_len > _ph_i else 0.0
307
+ TQ = ar1_precision(des["T"], logs[2], ph, backend, phi_bound=_pb)
308
+ if hasattr(TQ, 'toarray'):
309
+ TQ = TQ.toarray()
310
+ blocks_Q.append(_sp_blkdiag([TQ] * n_kab, format="csr").toarray())
311
+ else:
312
+ blocks_Q.append(np.exp(-2.0 * logs[1]) * np.eye(n_cell, dtype=np.float64))
313
+ Q_base = np.asarray(_sp_blkdiag(blocks_Q, format="csr").toarray())
314
+ else:
315
+ if s["area"] in ("iid",):
316
+ Q_a = np.exp(-2.0 * logs[0]) * np.eye(n_area, dtype=np.float64)
317
+ elif _has_sar:
318
+ rho = rb * np.tanh(raw_dep[_rho_i]) if _raw_len > _rho_i else 0.0
319
+ W = optim_results.get("W")
320
+ if W is None:
321
+ W = des.get("W_gamma")
322
+ if W is None:
323
+ W = np.eye(n_area, dtype=np.float64)
324
+ elif hasattr(W, 'toarray'):
325
+ W = W.toarray()
326
+ A = np.eye(n_area, dtype=np.float64) - rho * np.asarray(W, dtype=np.float64)[:n_area, :n_area]
327
+ Q_a = np.exp(-2.0 * logs[0]) * (A.T @ A)
328
+ else:
329
+ raise ValueError(f"Unknown area type: {s['area']!r}")
330
+ blocks_Q.append(Q_a)
331
+
332
+ if _has_ar1:
333
+ ph = _pb * np.tanh(raw_dep[_ph_i]) if _raw_len > _ph_i else 0.0
334
+ if "area_time" in blocks:
335
+ # area_specific ar1: block-diag per area (n_area blok T x T), no cross-area coupling
336
+ T_cell = n_time // n_area if n_area else n_time
337
+ TQ = ar1_precision(T_cell, logs[1], ph, backend, phi_bound=_pb)
338
+ if hasattr(TQ, 'toarray'):
339
+ TQ = TQ.toarray()
340
+ Q_t = _sp_blkdiag([TQ] * n_area, format="csr").toarray()
341
+ else:
342
+ Q_t = ar1_precision(n_time, logs[1], ph, backend, phi_bound=_pb)
343
+ if hasattr(Q_t, 'toarray'):
344
+ Q_t = Q_t.toarray()
345
+ else:
346
+ Q_t = np.exp(-2.0 * logs[1]) * np.eye(n_time, dtype=np.float64)
347
+ blocks_Q.append(Q_t)
348
+ Q_base = np.asarray(_sp_blkdiag(blocks_Q, format="csr").toarray())
349
+
350
+ Q_full = Q_base
351
+ if n_gamma > 0:
352
+ from stmmlib.beta.solvers import beta_Q_gamma
353
+ Q_g = beta_Q_gamma(s, des, des["m"], des["T"], n_gamma, logs, raw_dep,
354
+ ksd, optim_results.get("q_dep", len(raw_dep)),
355
+ _has_sar, _has_ar1, backend)
356
+ if Q_g is not None:
357
+ Q_full = np.block([[Q_base, np.zeros((Q_base.shape[0], n_gamma))],
358
+ [np.zeros((n_gamma, Q_base.shape[0])), Q_g]])
359
+
360
+ q = Z.shape[1]
361
+ if Q_full.shape[0] != q:
362
+ raise PrecisionShapeError(
363
+ f"Precision/design size mismatch: Q is {Q_full.shape[0]}x"
364
+ f"{Q_full.shape[1]} but Z has {q} columns for {model!r}."
365
+ )
366
+
367
+ # Newton solve (blocked for area-specific non-interaction models, same as fit)
368
+ from stmmlib.beta.solvers import beta_solve_mode, beta_solve_mode_blocked, laplace_block_logdets
369
+ use_blocked = (not is_nested and s["interaction"] == "none"
370
+ and s["time_scope"] == "area_specific")
371
+ schur_inner = use_blocked
372
+ start_b = optim_results.get("b_hat")
373
+ if use_blocked:
374
+ b, _, _ = beta_solve_mode_blocked(X, Z, Q_full, des["m"], des["T"], beta, logphi, y,
375
+ inner_max_iter=50, start_b=start_b, inner_tol=1e-6)
376
+ else:
377
+ b, _, _ = beta_solve_mode(X, Z, Q_full, beta, logphi, y, inner_max_iter=50, start_b=start_b, inner_tol=1e-6)
378
+
379
+ # NLL
380
+ eta = X @ beta + Z @ b
381
+ mu = 1.0 / (1.0 + np.exp(-eta))
382
+ mu = np.clip(mu, 1e-15, 1.0 - 1e-15)
383
+ a = mu * phi
384
+ bval = (1.0 - mu) * phi
385
+ nll = -np.sum(-betaln(a, bval) + (a - 1) * np.log(np.clip(y, 1e-15, 1.0)) +
386
+ (bval - 1) * np.log(np.clip(1.0 - y, 1e-15, 1.0)))
387
+ pen = 0.5 * b @ Q_full @ b
388
+
389
+ try:
390
+ if schur_inner:
391
+ logdet_H, logdet_Q = laplace_block_logdets(
392
+ Z, beta_nll_curvature(eta, y, phi), Q_full, des["m"], des["T"]
393
+ )
394
+ else:
395
+ logdet_Q = np.linalg.slogdet(Q_full)[1]
396
+ H_mat = Z.T @ (Z * beta_nll_curvature(eta, y, phi)[:, None]) + Q_full
397
+ logdet_H = np.linalg.slogdet(H_mat)[1]
398
+ except Exception:
399
+ logdet_Q = 0.0
400
+ logdet_H = 0.0
401
+
402
+ loglik = -nll - pen + 0.5 * logdet_Q - 0.5 * logdet_H
403
+ return -loglik if np.isfinite(loglik) else 1e20