braincoder 0.7.1__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.
@@ -0,0 +1,361 @@
1
+ """Gaussian-Process prior over a pRF parameter, indexed by cortical distance.
2
+
3
+ Following Daghlian et al. (2025), this places a zero-mean multivariate-normal
4
+ prior on the per-vertex values of a single pRF parameter, with covariance
5
+ given by an RBF kernel over a precomputed pairwise distance matrix
6
+ (typically geodesic distance on the cortical surface). The hyperparameters
7
+ (lengthscale, variance, nugget) are estimated by maximum likelihood from
8
+ the classical (per-vertex) parameter estimates — stage 2 of the empirical
9
+ Bayes recipe in the paper. Stage 3 then uses this prior to regularize a
10
+ joint fit of the model parameters.
11
+ """
12
+
13
+ import numpy as np
14
+ import keras
15
+ from keras import ops
16
+ from tqdm.auto import tqdm
17
+
18
+ from ..utils.backend import float64_device, to_float64, softplus_inverse, compute_gradients
19
+
20
+ _LOG_2PI = float(np.log(2.0 * np.pi))
21
+
22
+
23
+ class GeodesicGPPrior(object):
24
+ """Zero-mean GP prior with an RBF kernel over a pairwise distance matrix.
25
+
26
+ Covariance:
27
+ K(i, j) = variance * exp(-d(i,j)^2 / (2 * lengthscale^2))
28
+ + nugget * delta(i, j)
29
+
30
+ Parameters
31
+ ----------
32
+ distance_matrix : array (n_vx, n_vx)
33
+ Symmetric, non-negative pairwise distances. Geodesic distance on
34
+ the cortical surface is the typical choice.
35
+ lengthscale_init, variance_init, nugget_init : float
36
+ Initial values for the three RBF hyperparameters, in their
37
+ natural (positive) space. Stored internally on a softplus scale
38
+ so they remain positive during optimization.
39
+ jitter : float
40
+ Small constant added to the diagonal beyond ``nugget`` for
41
+ Cholesky stability. Scales with the mean diagonal of K so it
42
+ adapts to ``variance``.
43
+ """
44
+
45
+ def __init__(self, distance_matrix,
46
+ lengthscale_init=10.0,
47
+ variance_init=1.0,
48
+ nugget_init=0.1,
49
+ jitter=1e-4,
50
+ psd_correction='mds'):
51
+ """``psd_correction``: how to handle non-Euclidean input distances.
52
+
53
+ * ``'mds'`` (default) — classical multi-dimensional scaling embeds
54
+ the distance matrix into Euclidean space. RBF on the resulting
55
+ Euclidean distances is provably PSD (Schoenberg 1938), so the
56
+ Cholesky never NaNs even when the input is a graph distance
57
+ (mesh-edge Dijkstra, geodesic, heat-method, …). Recommended.
58
+ * ``'none'`` — use the raw distances as-is. Fine for genuinely
59
+ Euclidean inputs; will fail Cholesky on graph distances.
60
+ """
61
+ d = np.asarray(distance_matrix, dtype=np.float32)
62
+ if d.ndim != 2 or d.shape[0] != d.shape[1]:
63
+ raise ValueError(
64
+ f"distance_matrix must be square 2-D, got shape {d.shape}")
65
+
66
+ if psd_correction == 'mds':
67
+ d = mds_embed_distances(d)
68
+ elif psd_correction != 'none':
69
+ raise ValueError(
70
+ f"psd_correction must be 'mds' or 'none', got {psd_correction!r}")
71
+
72
+ self.n_vx = d.shape[0]
73
+ self._distance_sq = ops.convert_to_tensor(d ** 2, dtype='float32')
74
+ self.jitter = float(jitter)
75
+
76
+ # Free variables in unconstrained (softplus-inverse) space.
77
+ self._log_lengthscale = keras.Variable(
78
+ _to_unconstrained(lengthscale_init), dtype='float32',
79
+ name='gp_log_lengthscale')
80
+ self._log_variance = keras.Variable(
81
+ _to_unconstrained(variance_init), dtype='float32',
82
+ name='gp_log_variance')
83
+ self._log_nugget = keras.Variable(
84
+ _to_unconstrained(nugget_init), dtype='float32',
85
+ name='gp_log_nugget')
86
+
87
+ # Frozen Cholesky factor used during MAP (set by freeze()).
88
+ # Skipping the Cholesky op in the gradient graph avoids
89
+ # TF's CholeskyGrad blowing up under mild ill-conditioning,
90
+ # which is what triggers `Tensor had NaN values` in fit_map.
91
+ self._cached_L = None
92
+ self._cached_log_det = None
93
+
94
+ # ------------------------------------------------------------------ API
95
+
96
+ @property
97
+ def lengthscale(self):
98
+ return float(ops.convert_to_numpy(ops.softplus(self._log_lengthscale)))
99
+
100
+ @property
101
+ def variance(self):
102
+ return float(ops.convert_to_numpy(ops.softplus(self._log_variance)))
103
+
104
+ @property
105
+ def nugget(self):
106
+ return float(ops.convert_to_numpy(ops.softplus(self._log_nugget)))
107
+
108
+ @property
109
+ def hyperparameters(self):
110
+ return dict(lengthscale=self.lengthscale,
111
+ variance=self.variance,
112
+ nugget=self.nugget)
113
+
114
+ @property
115
+ def trainable_variables(self):
116
+ return [self._log_lengthscale, self._log_variance, self._log_nugget]
117
+
118
+ def covariance(self):
119
+ """Return the current covariance matrix K (with nugget + jitter)."""
120
+ return self._build_covariance(self._log_lengthscale,
121
+ self._log_variance,
122
+ self._log_nugget)
123
+
124
+ def freeze_cholesky(self):
125
+ """Precompute & cache the Cholesky factor at current hyperparams.
126
+
127
+ After calling this, ``log_prob(values)`` uses the cached factor
128
+ and ``stop_gradient``s it so the gradient w.r.t. ``values``
129
+ flows through ``solve_triangular(L, v)`` only — not back
130
+ through ``cholesky(K)``. This sidesteps TF's ``CholeskyGrad``
131
+ producing NaN under mild ill-conditioning during MAP, which
132
+ otherwise crashes ``fit_map`` after dozens of Adam steps.
133
+
134
+ Call this once before starting the MAP loop with hyperparams
135
+ held fixed. ``unfreeze_cholesky()`` clears the cache.
136
+ """
137
+ K = self._build_covariance(self._log_lengthscale,
138
+ self._log_variance,
139
+ self._log_nugget)
140
+ with float64_device():
141
+ L = ops.cholesky(to_float64(K))
142
+ self._cached_L = ops.stop_gradient(L)
143
+ self._cached_log_det = ops.stop_gradient(
144
+ 2.0 * ops.sum(ops.log(ops.diag(L))))
145
+ return self._cached_L
146
+
147
+ def unfreeze_cholesky(self):
148
+ """Clear cached Cholesky factor so log_prob recomputes K."""
149
+ self._cached_L = None
150
+ self._cached_log_det = None
151
+
152
+ def log_prob(self, values):
153
+ """Log-probability of a length-n_vx vector under the current K.
154
+
155
+ ``values`` may be a numpy array or any Keras-backed tensor.
156
+ If ``freeze_cholesky()`` has been called, uses the cached
157
+ factor instead of recomputing.
158
+ """
159
+ v = ops.convert_to_tensor(values, dtype='float32')
160
+ v = ops.reshape(v, (-1,))
161
+ if self._cached_L is not None:
162
+ return self._log_prob_tensor_cached(v)
163
+ return self._log_prob_tensor(v,
164
+ self._log_lengthscale,
165
+ self._log_variance,
166
+ self._log_nugget)
167
+
168
+ def fit_hyperparameters(self, values,
169
+ max_n_iterations=500,
170
+ learning_rate=0.05,
171
+ tol=1e-4,
172
+ patience=20,
173
+ progressbar=True):
174
+ """Estimate (lengthscale, variance, nugget) by MLE from fixed values.
175
+
176
+ This is stage 2 of the paper's empirical-Bayes recipe: the
177
+ per-vertex parameter estimates from the classical fit are held
178
+ fixed and the GP hyperparameters are optimized to maximize the
179
+ marginal likelihood log p(values | K(theta)).
180
+ """
181
+ v = ops.convert_to_tensor(np.asarray(values, dtype=np.float32),
182
+ dtype='float32')
183
+ v = ops.reshape(v, (-1,))
184
+ if int(ops.shape(v)[0]) != self.n_vx:
185
+ raise ValueError(
186
+ f"values has {int(ops.shape(v)[0])} entries, "
187
+ f"distance matrix is {self.n_vx} x {self.n_vx}")
188
+
189
+ opt = keras.optimizers.Adam(learning_rate=learning_rate)
190
+ history = []
191
+ best = float('inf')
192
+ best_vars = [ops.convert_to_numpy(x) for x in self.trainable_variables]
193
+ stall = 0
194
+
195
+ pbar = range(max_n_iterations)
196
+ if progressbar:
197
+ pbar = tqdm(pbar, desc='GP hyperparams')
198
+
199
+ for step in pbar:
200
+ def loss_fn():
201
+ return -self._log_prob_tensor(v,
202
+ self._log_lengthscale,
203
+ self._log_variance,
204
+ self._log_nugget)
205
+
206
+ loss, grads = compute_gradients(loss_fn, self.trainable_variables)
207
+ opt.apply_gradients(zip(grads, self.trainable_variables))
208
+ loss_val = float(ops.convert_to_numpy(loss))
209
+ history.append(loss_val)
210
+
211
+ if loss_val < best - tol:
212
+ best = loss_val
213
+ best_vars = [ops.convert_to_numpy(x)
214
+ for x in self.trainable_variables]
215
+ stall = 0
216
+ else:
217
+ stall += 1
218
+
219
+ if progressbar:
220
+ pbar.set_description(
221
+ f'GP nLL {loss_val:.3f} | l={self.lengthscale:.2f} '
222
+ f'v={self.variance:.3f} nug={self.nugget:.3f}')
223
+
224
+ if stall >= patience:
225
+ break
226
+
227
+ # Restore best-found hyperparameters.
228
+ for var, value in zip(self.trainable_variables, best_vars):
229
+ var.assign(value)
230
+
231
+ return dict(history=np.asarray(history),
232
+ best_neg_log_lik=best,
233
+ hyperparameters=self.hyperparameters)
234
+
235
+ # ------------------------------------------------------------- internals
236
+
237
+ def _build_covariance(self, log_l, log_v, log_n):
238
+ l = ops.softplus(log_l)
239
+ v = ops.softplus(log_v)
240
+ n = ops.softplus(log_n)
241
+ K = v * ops.exp(-self._distance_sq / (2.0 * l * l))
242
+ eye = ops.eye(self.n_vx, dtype='float32')
243
+ # Adaptive jitter scales with the variance term so it stays
244
+ # numerically relevant when v >> 1 (e.g. priors on a parameter
245
+ # with a large native scale, like numerosity 'mu' in [10, 40]).
246
+ K = K + (n + v * self.jitter + 1e-9) * eye
247
+ return K
248
+
249
+ def _log_prob_tensor(self, values, log_l, log_v, log_n):
250
+ # Build the covariance and run Cholesky / triangular solves in
251
+ # float64 — RBF kernels on ~hundreds of vertices are inherently
252
+ # ill-conditioned and float32 Cholesky bottoms out at NaN.
253
+ # Standard practice in TFP / GPyTorch / GPflow.
254
+ K = self._build_covariance(log_l, log_v, log_n)
255
+ with float64_device():
256
+ L = ops.cholesky(to_float64(K))
257
+ v64 = to_float64(ops.reshape(values, (-1, 1)))
258
+ y = ops.solve_triangular(L, v64, lower=True)
259
+ mahal = ops.sum(y * y)
260
+ log_det = 2.0 * ops.sum(ops.log(ops.diag(L)))
261
+ n_float = ops.cast(self.n_vx, 'float64')
262
+ lp = -0.5 * (mahal + log_det + n_float * _LOG_2PI)
263
+ lp = ops.cast(lp, 'float32')
264
+ return ops.convert_to_tensor(lp)
265
+
266
+ def _log_prob_tensor_cached(self, values):
267
+ # Uses self._cached_L (already stop_gradient'd).
268
+ # Gradient w.r.t. `values` flows only through solve_triangular,
269
+ # which is stable; Cholesky is not in the backward graph.
270
+ with float64_device():
271
+ v64 = to_float64(ops.reshape(values, (-1, 1)))
272
+ y = ops.solve_triangular(self._cached_L, v64, lower=True)
273
+ mahal = ops.sum(y * y)
274
+ n_float = ops.cast(self.n_vx, 'float64')
275
+ lp = -0.5 * (mahal + self._cached_log_det + n_float * _LOG_2PI)
276
+ lp = ops.cast(lp, 'float32')
277
+ return ops.convert_to_tensor(lp)
278
+
279
+
280
+ def _to_unconstrained(x):
281
+ """Map a positive scalar to its softplus-inverse value as float32."""
282
+ x_arr = np.asarray(x, dtype=np.float32).reshape(())
283
+ return ops.convert_to_numpy(
284
+ softplus_inverse(ops.convert_to_tensor(x_arr, dtype='float32')))
285
+
286
+
287
+ def mds_embed_distances(d, return_info=False):
288
+ """Closest Euclidean approximation of a distance matrix, by classical MDS.
289
+
290
+ Classical MDS works on the double-centered squared-distance matrix
291
+ ``B = -0.5 * J D² J``. Its positive eigenvalues' coordinates give a
292
+ Euclidean embedding; negative eigenvalues correspond to the
293
+ non-Euclidean part of the input metric, which is dropped. The output
294
+ is the matrix of Euclidean distances among the embedded coordinates.
295
+
296
+ Consequences that callers rely on:
297
+
298
+ * ``exp(-d²/2l²)`` and ``exp(-beta d)`` are positive semi-definite for
299
+ every ``l, beta > 0`` on the output (Schoenberg 1938), which they need
300
+ not be on the input: mesh-edge Dijkstra and other geodesic distances
301
+ are generally not Euclidean.
302
+ * Discarding negative eigenvalues can only lengthen distances
303
+ (``output >= input`` up to rounding), so the output is not the input:
304
+ report ``info['negative_eigenvalue_fraction']`` and compare the two.
305
+ * Two points at distance 0 with identical distance rows (e.g. voxels
306
+ that share a mesh vertex) stay at distance 0, so a kernel on the output
307
+ is singular on that pair. It is PSD, not strictly PD, there.
308
+
309
+ Memory is ``O(n²)``: the distances come from the Gram matrix
310
+ ``C Cᵀ = V_+ diag(w_+) V_+ᵀ``, not from an ``n × n × r`` difference tensor.
311
+
312
+ Parameters
313
+ ----------
314
+ d : array (n, n)
315
+ Symmetric, finite, non-negative distances.
316
+ return_info : bool
317
+ Also return a dict with ``n_components``,
318
+ ``negative_eigenvalue_fraction`` (Σ|negative eigenvalues| / Σ|all
319
+ eigenvalues|; 0 for a Euclidean input).
320
+
321
+ Returns
322
+ -------
323
+ d_euclidean : float32 array (n, n)
324
+ info : dict, only if ``return_info``
325
+ """
326
+ d = np.asarray(d, dtype=np.float64)
327
+ if d.ndim != 2 or d.shape[0] != d.shape[1]:
328
+ raise ValueError(f'distance matrix must be square 2-D, got shape {d.shape}')
329
+ if not np.isfinite(d).all():
330
+ raise ValueError(
331
+ f'distance matrix has {int((~np.isfinite(d)).sum())} non-finite '
332
+ 'entries (unreachable vertices on a disconnected mesh or patch?); '
333
+ 'it cannot be embedded.')
334
+ if (d < 0).any():
335
+ raise ValueError('distance matrix has negative entries')
336
+ n = d.shape[0]
337
+ D2 = d ** 2
338
+ # Double-centering without forming J = I - 11ᵀ/n
339
+ row_mean = D2.mean(axis=1, keepdims=True)
340
+ B = -0.5 * (D2 - row_mean - row_mean.T + D2.mean())
341
+ # Symmetrize before eigendecomposition (numerical drift)
342
+ B = 0.5 * (B + B.T)
343
+ w, V = np.linalg.eigh(B)
344
+ # Keep positive eigenvalues only: the negative ones are exactly the
345
+ # non-Euclidean component we want to discard.
346
+ pos = w > 1e-10 * max(np.abs(w).max(), np.finfo(np.float64).tiny)
347
+ # Pairwise Euclidean distances from the Gram matrix of the embedding.
348
+ G = (V[:, pos] * w[pos]) @ V[:, pos].T
349
+ g = np.diag(G)
350
+ d_euc = np.sqrt(np.clip(g[:, None] + g[None, :] - 2.0 * G, 0.0, None)).astype(np.float32)
351
+ np.fill_diagonal(d_euc, 0.0)
352
+ if return_info:
353
+ total = np.abs(w).sum()
354
+ neg = np.abs(w[w < 0]).sum()
355
+ return d_euc, dict(n_components=int(pos.sum()),
356
+ negative_eigenvalue_fraction=float(neg / total) if total > 0 else 0.0)
357
+ return d_euc
358
+
359
+
360
+ # Backwards-compatible private name.
361
+ _mds_embed_distances = mds_embed_distances