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.
- braincoder/__init__.py +27 -0
- braincoder/barstimuli.py +569 -0
- braincoder/data/szinte2024/dm_gazecenter.npz +0 -0
- braincoder/data/szinte2024/gauss_parameters.tsv +2366 -0
- braincoder/data/szinte2024/grid_coordinates.tsv +3601 -0
- braincoder/data/szinte2024/mask-v1_bold.tsv.gz +0 -0
- braincoder/hrf.py +272 -0
- braincoder/models/__init__.py +21 -0
- braincoder/models/base.py +1004 -0
- braincoder/models/linear.py +100 -0
- braincoder/models/prf_1d.py +369 -0
- braincoder/models/prf_2d.py +824 -0
- braincoder/noise.py +614 -0
- braincoder/optimize/__init__.py +22 -0
- braincoder/optimize/bayesian_fitter.py +467 -0
- braincoder/optimize/gp_prior.py +361 -0
- braincoder/optimize/parameter_fitter.py +666 -0
- braincoder/optimize/residual_fitter.py +563 -0
- braincoder/optimize/stimulus_fitter.py +656 -0
- braincoder/optimize/weight_fitter.py +112 -0
- braincoder/stimuli.py +224 -0
- braincoder/utils/__init__.py +4 -0
- braincoder/utils/backend.py +533 -0
- braincoder/utils/calibration.py +186 -0
- braincoder/utils/cortex.py +141 -0
- braincoder/utils/data.py +252 -0
- braincoder/utils/formatting.py +63 -0
- braincoder/utils/math.py +131 -0
- braincoder/utils/mcmc.py +114 -0
- braincoder/utils/stats.py +267 -0
- braincoder/utils/visualize.py +26 -0
- braincoder-0.7.1.dist-info/METADATA +136 -0
- braincoder-0.7.1.dist-info/RECORD +36 -0
- braincoder-0.7.1.dist-info/WHEEL +5 -0
- braincoder-0.7.1.dist-info/licenses/LICENSE +22 -0
- braincoder-0.7.1.dist-info/top_level.txt +1 -0
|
@@ -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
|