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,467 @@
1
+ """Empirical-Bayes pRF fitter with a GP prior on one or more parameters.
2
+
3
+ Follows the three-stage recipe in Daghlian et al. (2025):
4
+
5
+ 1. Classical SSQ fit per vertex (delegated to ``ParameterFitter``).
6
+ 2. For each parameter that has a prior attached, fit the GP hyperparameters
7
+ (lengthscale, variance, nugget) by MLE on the classical estimates.
8
+ 3. MAP fit: jointly optimize the model parameters under a Gaussian
9
+ likelihood (per-vertex sigma) plus the GP log-prior. The hyperparameters
10
+ from stage 2 are held fixed.
11
+
12
+ The result is a regularized parameter map that borrows strength from the
13
+ spatial structure of the cortex while still respecting the data.
14
+ """
15
+
16
+ import numpy as np
17
+ import pandas as pd
18
+ import keras
19
+ from keras import ops
20
+ from tqdm.auto import tqdm
21
+
22
+ from ..utils import format_parameters
23
+ from ..utils.backend import compute_gradients, softplus_inverse
24
+ from .parameter_fitter import ParameterFitter
25
+
26
+
27
+ _LOG_2PI = float(np.log(2.0 * np.pi))
28
+
29
+
30
+ class BayesianParameterFitter(object):
31
+ """Three-stage empirical-Bayes fitter with a spatial GP prior.
32
+
33
+ Parameters
34
+ ----------
35
+ model : EncodingModel
36
+ data : DataFrame (n_timepoints, n_vertices)
37
+ paradigm : DataFrame or array
38
+ Stimulus paradigm, same convention as ``ParameterFitter``.
39
+ priors : dict[str, GeodesicGPPrior]
40
+ Mapping from parameter label to a prior. The number of vertices
41
+ in each prior must equal the number of columns in ``data``.
42
+
43
+ Notes
44
+ -----
45
+ The GP prior is applied to the parameter's *native* (constrained)
46
+ values — e.g. the linear-space mu of a LogGaussianPRF — matching
47
+ Daghlian et al.'s convention.
48
+ """
49
+
50
+ def __init__(self, model, data, paradigm, priors):
51
+ if not isinstance(priors, dict):
52
+ raise ValueError("priors must be a dict (use {} for a no-prior "
53
+ "ML fit with per-vertex sigma)")
54
+
55
+ n_vx = data.shape[1]
56
+ for name, prior in priors.items():
57
+ if name not in model.parameter_labels:
58
+ raise ValueError(
59
+ f"Prior on '{name}', but model parameters are "
60
+ f"{model.parameter_labels}")
61
+ if prior.n_vx != n_vx:
62
+ raise ValueError(
63
+ f"Prior on '{name}' has n_vx={prior.n_vx}, data has "
64
+ f"{n_vx} columns")
65
+
66
+ self.model = model
67
+ self.data = data.astype(np.float32)
68
+ self.paradigm = model.get_paradigm(paradigm)
69
+ self.priors = priors
70
+
71
+ # Filled in by the corresponding stage.
72
+ self.classical_estimates = None
73
+ self.classical_r2 = None
74
+ self.hyperparameter_history = None
75
+ self.map_estimates = None
76
+ self.map_sigma = None
77
+
78
+ # ------------------------------------------------------------ public API
79
+
80
+ def fit(self,
81
+ max_n_iterations=500,
82
+ learning_rate=0.01,
83
+ classical_kwargs=None,
84
+ hyperparam_kwargs=None,
85
+ map_kwargs=None,
86
+ shared_lengthscale=False,
87
+ joint_hyperparams=False,
88
+ progressbar=True):
89
+ """Run all three stages and return the MAP parameter estimates.
90
+
91
+ ``joint_hyperparams=True`` collapses the recipe to two stages:
92
+ classical SSQ fit, then a single joint MAP optimization that
93
+ co-fits voxel parameters *and* GP hyperparameters under the
94
+ type-II MAP objective ``log p(y|θ) + log p(θ|ψ)``. The
95
+ ``-½ log|K(ψ)|`` term in the prior log-prob automatically
96
+ penalizes over-smoothing of ψ, so stage 2's bias toward long
97
+ lengthscales is sidestepped entirely.
98
+ """
99
+ classical_kwargs = dict(classical_kwargs or {})
100
+ hyperparam_kwargs = dict(hyperparam_kwargs or {})
101
+ map_kwargs = dict(map_kwargs or {})
102
+
103
+ self.fit_classical(progressbar=progressbar, **classical_kwargs)
104
+ if joint_hyperparams:
105
+ # Skip stage 2; just tie variables if shared_lengthscale.
106
+ if shared_lengthscale:
107
+ self.tie_lengthscales()
108
+ else:
109
+ self.fit_hyperparameters(progressbar=progressbar,
110
+ shared_lengthscale=shared_lengthscale,
111
+ **hyperparam_kwargs)
112
+ return self.fit_map(max_n_iterations=max_n_iterations,
113
+ learning_rate=learning_rate,
114
+ joint_hyperparams=joint_hyperparams,
115
+ progressbar=progressbar,
116
+ **map_kwargs)
117
+
118
+ def tie_lengthscales(self):
119
+ """Tie every prior's ``_log_lengthscale`` Variable to one shared
120
+ instance, so subsequent fitting (stage 2 or stage 3) sees a
121
+ single shared lengthscale across all parameters. No-op when
122
+ there are < 2 priors. Variance and nugget stay per-prior.
123
+ """
124
+ priors_list = list(self.priors.values())
125
+ if len(priors_list) < 2:
126
+ return
127
+ shared_var = priors_list[0]._log_lengthscale
128
+ for p in priors_list[1:]:
129
+ p._log_lengthscale = shared_var
130
+
131
+ # ----------------------------------------------------------- stage 1
132
+
133
+ def fit_classical(self, init_pars=None, progressbar=True, **kwargs):
134
+ """Stage 1 — classical per-vertex SSQ fit via ``ParameterFitter``."""
135
+ fitter = ParameterFitter(self.model, self.data, self.paradigm,
136
+ log_dir=False)
137
+ self.classical_estimates = fitter.fit(
138
+ init_pars=init_pars, progressbar=progressbar, **kwargs)
139
+ self.classical_r2 = fitter.r2
140
+ self._classical_fitter = fitter
141
+ return self.classical_estimates
142
+
143
+ # ----------------------------------------------------------- stage 2
144
+
145
+ def fit_hyperparameters(self, progressbar=True,
146
+ shared_lengthscale=False, **kwargs):
147
+ """Stage 2 — fit each prior's hyperparameters by MLE on stage-1 values.
148
+
149
+ No-op when ``priors`` is empty (ML mode).
150
+
151
+ If ``shared_lengthscale=True`` and there are ≥2 priors, ties all
152
+ priors' ``_log_lengthscale`` Variables to a single shared one
153
+ and runs **joint** MLE over (shared l, per-prior v, per-prior
154
+ n). The motivation: the "topographic scale" of cortex is a
155
+ property of the surface, not of which pRF parameter you're
156
+ looking at — so adjacent voxels should be similar in *all*
157
+ parameters at the same ~mm scale. Sharing also regularizes
158
+ when the data is too thin to identify four lengthscales
159
+ independently.
160
+ """
161
+ if self.classical_estimates is None:
162
+ raise RuntimeError(
163
+ "Run fit_classical() before fit_hyperparameters()")
164
+
165
+ self.hyperparameter_history = {}
166
+ if shared_lengthscale and len(self.priors) >= 2:
167
+ return self._fit_hyperparameters_shared(progressbar=progressbar,
168
+ **kwargs)
169
+
170
+ for name, prior in self.priors.items():
171
+ values = self.classical_estimates[name].values.astype(np.float32)
172
+ self.hyperparameter_history[name] = prior.fit_hyperparameters(
173
+ values, progressbar=progressbar, **kwargs)
174
+
175
+ return {name: prior.hyperparameters
176
+ for name, prior in self.priors.items()}
177
+
178
+ def _fit_hyperparameters_shared(self, max_n_iterations=500,
179
+ learning_rate=0.05, tol=1e-4,
180
+ patience=20, progressbar=True):
181
+ """Joint MLE with one shared log_lengthscale + per-prior log_variance,
182
+ log_nugget. Mutates each prior so that its ``_log_lengthscale``
183
+ is the same Variable instance.
184
+ """
185
+ from tqdm.auto import tqdm
186
+ from keras import ops
187
+ import keras
188
+ from ..utils.backend import compute_gradients
189
+
190
+ self.tie_lengthscales()
191
+ priors_list = list(self.priors.values())
192
+ shared_var = priors_list[0]._log_lengthscale
193
+
194
+ trainable_vars = [shared_var]
195
+ for p in priors_list:
196
+ trainable_vars.extend([p._log_variance, p._log_nugget])
197
+
198
+ values_tensors = {}
199
+ for name, prior in self.priors.items():
200
+ v = self.classical_estimates[name].values.astype(np.float32)
201
+ values_tensors[name] = ops.convert_to_tensor(v, dtype='float32')
202
+
203
+ opt = keras.optimizers.Adam(learning_rate=learning_rate)
204
+
205
+ def joint_loss():
206
+ total = 0.0
207
+ for name, prior in self.priors.items():
208
+ v_arr = values_tensors[name]
209
+ total = total - prior._log_prob_tensor(
210
+ v_arr,
211
+ prior._log_lengthscale,
212
+ prior._log_variance,
213
+ prior._log_nugget,
214
+ )
215
+ return total
216
+
217
+ history = []
218
+ best = float('inf')
219
+ best_state = [ops.convert_to_numpy(v) for v in trainable_vars]
220
+ stall = 0
221
+
222
+ pbar = range(max_n_iterations)
223
+ if progressbar:
224
+ pbar = tqdm(pbar, desc='GP hyperparams (shared l)')
225
+
226
+ for step in pbar:
227
+ loss, grads = compute_gradients(joint_loss, trainable_vars)
228
+ opt.apply_gradients(zip(grads, trainable_vars))
229
+ loss_val = float(ops.convert_to_numpy(loss))
230
+ history.append(loss_val)
231
+ if loss_val < best - tol:
232
+ best = loss_val
233
+ best_state = [ops.convert_to_numpy(v) for v in trainable_vars]
234
+ stall = 0
235
+ else:
236
+ stall += 1
237
+ if progressbar:
238
+ pbar.set_description(
239
+ f'GP joint nLL {loss_val:.3f} | '
240
+ f'l={priors_list[0].lengthscale:.2f}')
241
+ if stall >= patience:
242
+ break
243
+
244
+ for var, val in zip(trainable_vars, best_state):
245
+ var.assign(val)
246
+
247
+ shared_l = float(ops.convert_to_numpy(ops.softplus(shared_var)))
248
+ self.hyperparameter_history['_shared'] = dict(
249
+ history=np.asarray(history),
250
+ best_neg_log_lik=best,
251
+ shared_lengthscale=shared_l,
252
+ )
253
+ for name, prior in self.priors.items():
254
+ self.hyperparameter_history[name] = dict(
255
+ hyperparameters=prior.hyperparameters,
256
+ shared_lengthscale=True,
257
+ )
258
+
259
+ return {name: prior.hyperparameters
260
+ for name, prior in self.priors.items()}
261
+
262
+ # ----------------------------------------------------------- stage 3
263
+
264
+ def fit_map(self,
265
+ max_n_iterations=500,
266
+ learning_rate=0.01,
267
+ init_pars=None,
268
+ fixed_pars=None,
269
+ tol=1e-4,
270
+ patience=30,
271
+ clipnorm=1.0,
272
+ joint_hyperparams=False,
273
+ progressbar=True):
274
+ """Stage 3 — MAP fit with Gaussian likelihood + GP log-prior.
275
+
276
+ ``clipnorm`` (default 1.0) clips the global gradient norm at
277
+ each Adam step. Belt-and-braces against the occasional
278
+ run-away update that would otherwise feed enormous values
279
+ into the Mahalanobis term and NaN out subsequent iterations.
280
+ Set to ``None`` to disable.
281
+
282
+ ``joint_hyperparams`` (default False): if True, each prior's
283
+ ``(_log_lengthscale, _log_variance, _log_nugget)`` Variables
284
+ are added to the trainable set and co-optimized with the model
285
+ parameters under the type-II MAP objective. K is recomputed
286
+ every step (no ``freeze_cholesky``), so the prior's
287
+ ``-½ log|K(ψ)|`` term provides automatic regularization on ψ
288
+ — long lengthscales make ``|K|`` large, penalizing themselves.
289
+ """
290
+ if self.classical_estimates is None:
291
+ raise RuntimeError("Run fit_classical() before fit_map()")
292
+
293
+ if init_pars is None:
294
+ init_pars = self.classical_estimates
295
+
296
+ n_t, n_vx = self.data.shape
297
+ n_pars = len(self.model.parameter_labels)
298
+
299
+ y = ops.convert_to_tensor(self.data.values, dtype='float32')
300
+
301
+ # Initial parameters in unconstrained (softplus-inverse, etc.) space.
302
+ init_native = self.model._get_parameters(init_pars).values.astype(
303
+ np.float32)
304
+ init_uncon = ops.convert_to_numpy(
305
+ self.model._transform_parameters_backward(init_native))
306
+
307
+ # Mask: only meaningful (nonzero-variance) vertices get gradients.
308
+ ssq_data = ops.sum((y - ops.mean(y, axis=0)[None, :]) ** 2, axis=0)
309
+ meaningful_ts = ops.convert_to_numpy(ssq_data > 0.0)
310
+
311
+ # Resolve fixed_pars → which columns of `params_var` are trainable.
312
+ fixed_pars = list(fixed_pars or [])
313
+ trainable_param_ix = [
314
+ i for i, lbl in enumerate(self.model.parameter_labels)
315
+ if lbl not in fixed_pars]
316
+ param_mask_np = np.zeros((n_vx, n_pars), dtype=np.float32)
317
+ for i in np.where(meaningful_ts)[0]:
318
+ for j in trainable_param_ix:
319
+ param_mask_np[i, j] = 1.0
320
+ param_mask = ops.convert_to_tensor(param_mask_np)
321
+
322
+ init_uncon_t = ops.convert_to_tensor(init_uncon)
323
+ params_var = keras.Variable(
324
+ init_uncon.copy(), dtype='float32', name='params')
325
+
326
+ # Per-vertex Gaussian noise variance, parameterized via softplus.
327
+ # Initial sigma^2 from classical residuals.
328
+ with_initial_pred = self.model.predict(
329
+ self.paradigm, self.classical_estimates)
330
+ residual = self.data.values - with_initial_pred.values
331
+ init_sigma2 = np.maximum(np.var(residual, axis=0).astype(np.float32),
332
+ 1e-4)
333
+ log_sigma2_uncon = ops.convert_to_numpy(softplus_inverse(
334
+ ops.convert_to_tensor(init_sigma2, dtype='float32')))
335
+ sigma2_var = keras.Variable(
336
+ log_sigma2_uncon.copy(), dtype='float32', name='log_sigma2')
337
+
338
+ trainable_variables = [params_var, sigma2_var]
339
+
340
+ # Indices of parameters that have a GP prior.
341
+ prior_indices = {name: self.model.parameter_labels.index(name)
342
+ for name in self.priors.keys()}
343
+
344
+ if joint_hyperparams:
345
+ # Type-II MAP: co-optimize ψ = (l, v, n) per prior with θ.
346
+ # K is rebuilt every step (no caching). Deduplicate the
347
+ # lengthscale Variable so a shared-lengthscale setup adds
348
+ # it once, not once per prior.
349
+ seen = set()
350
+ for prior in self.priors.values():
351
+ if id(prior._log_lengthscale) not in seen:
352
+ trainable_variables.append(prior._log_lengthscale)
353
+ seen.add(id(prior._log_lengthscale))
354
+ trainable_variables.extend([prior._log_variance,
355
+ prior._log_nugget])
356
+ else:
357
+ # Hyperparameters frozen. Cache L = chol(K) outside the
358
+ # gradient graph so CholeskyGrad never runs — it NaN'd on
359
+ # mild ill-conditioning and used to crash fit_map.
360
+ for prior in self.priors.values():
361
+ prior.freeze_cholesky()
362
+
363
+ paradigm_ = self.model.stimulus._clean_paradigm(self.paradigm)
364
+
365
+ def build_params_native():
366
+ uncon = (init_uncon_t * (1.0 - param_mask)
367
+ + params_var * param_mask)
368
+ return self.model._transform_parameters_forward(uncon)
369
+
370
+ def loss_fn():
371
+ native = build_params_native()
372
+ preds = self.model._predict(
373
+ paradigm_[None, ...], native[None, ...], None)[0] # (n_t, n_vx)
374
+ ssq = ops.sum((y - preds) ** 2, axis=0) # (n_vx,)
375
+ sigma2 = ops.softplus(sigma2_var) # (n_vx,)
376
+
377
+ n_t_f = ops.cast(n_t, 'float32')
378
+ # Per-vertex Gaussian nLL, summed over vertices.
379
+ nll = 0.5 * (n_t_f * (_LOG_2PI + ops.log(sigma2))
380
+ + ssq / sigma2)
381
+ nll_total = ops.sum(nll)
382
+
383
+ nlp_total = 0.0
384
+ for name, prior in self.priors.items():
385
+ idx = prior_indices[name]
386
+ nlp_total = nlp_total - prior.log_prob(native[:, idx])
387
+
388
+ return nll_total + nlp_total
389
+
390
+ # Note: we implement gradient clipping manually rather than via
391
+ # keras.optimizers.Adam(clipnorm=...) because the latter's
392
+ # behavior under the PyTorch backend interacts poorly with a
393
+ # transient NaN gradient (it scales by 1/NaN, poisoning Adam's
394
+ # moment buffers and producing NaN parameters that propagate
395
+ # for the rest of the loop). The manual path below scales by a
396
+ # NaN-safe factor and skips the update entirely if the loss or
397
+ # any gradient is non-finite.
398
+ opt = keras.optimizers.Adam(learning_rate=learning_rate)
399
+ history = []
400
+ best = float('inf')
401
+ # Snapshot every trainable (params + sigma2 + optionally
402
+ # hyperparams) so the joint path can restore the best ψ too.
403
+ best_state = [ops.convert_to_numpy(v) for v in trainable_variables]
404
+ stall = 0
405
+
406
+ pbar = range(max_n_iterations)
407
+ if progressbar:
408
+ pbar = tqdm(pbar, desc='MAP')
409
+
410
+ for step in pbar:
411
+ loss, grads = compute_gradients(loss_fn, trainable_variables)
412
+ loss_val = float(ops.convert_to_numpy(loss))
413
+
414
+ # Manual global-norm clip, NaN-safe. If the loss or any
415
+ # gradient is non-finite, skip the update so a single bad
416
+ # step cannot poison Adam's moment buffers.
417
+ grads_np = [ops.convert_to_numpy(g) for g in grads]
418
+ finite = (np.isfinite(loss_val)
419
+ and all(np.all(np.isfinite(g)) for g in grads_np))
420
+ if finite:
421
+ if clipnorm is not None:
422
+ global_norm = float(np.sqrt(
423
+ sum(float((g ** 2).sum()) for g in grads_np)))
424
+ if global_norm > clipnorm and global_norm > 0.0:
425
+ scale = clipnorm / global_norm
426
+ grads = [ops.convert_to_tensor(g * scale,
427
+ dtype='float32')
428
+ for g in grads_np]
429
+ opt.apply_gradients(zip(grads, trainable_variables))
430
+ history.append(loss_val)
431
+
432
+ if finite and loss_val < best - tol:
433
+ best = loss_val
434
+ best_state = [ops.convert_to_numpy(v)
435
+ for v in trainable_variables]
436
+ stall = 0
437
+ else:
438
+ stall += 1
439
+
440
+ if progressbar:
441
+ pbar.set_description(f'MAP nLP {loss_val:.2f}')
442
+
443
+ if stall >= patience and step > 50:
444
+ break
445
+
446
+ # Restore best-found values and produce native-space estimates.
447
+ for var, val in zip(trainable_variables, best_state):
448
+ var.assign(val)
449
+ native_best = ops.convert_to_numpy(build_params_native())
450
+ sigma2_native = ops.convert_to_numpy(ops.softplus(sigma2_var))
451
+
452
+ self.map_estimates = format_parameters(
453
+ native_best, self.model.parameter_labels)
454
+ self.map_estimates.index = self.data.columns
455
+ if not self.map_estimates.index.name:
456
+ self.map_estimates.index.name = 'source'
457
+
458
+ self.map_sigma = pd.Series(np.sqrt(sigma2_native),
459
+ index=self.data.columns, name='sigma')
460
+ self.map_history = np.asarray(history)
461
+
462
+ # Release any cached Cholesky so subsequent calls see live K.
463
+ # No-op if we never froze (joint_hyperparams=True path).
464
+ for prior in self.priors.values():
465
+ prior.unfreeze_cholesky()
466
+
467
+ return self.map_estimates