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,1004 @@
1
+ import logging
2
+ import warnings
3
+ import pandas as pd
4
+ import numpy as np
5
+ from tqdm import tqdm
6
+ import keras
7
+ from keras import ops
8
+ from ..utils import norm, format_data, format_paradigm, format_parameters, format_weights, logit, restrict_radians, lognormalpdf_n, von_mises_pdf, lognormal_pdf_mode_fwhm, norm2d
9
+ from ..utils.math import aggressive_softplus, aggressive_softplus_inverse, norm, _trapezoid
10
+ from ..utils.backend import softplus_inverse, mvn_log_prob, mvt_log_prob, sample_mvn, sample_mvt, sample_student_t, compute_gradients, safe_cholesky
11
+ import scipy.stats as ss
12
+ from ..stimuli import Stimulus, OneDimensionalRadialStimulus, OneDimensionalGaussianStimulus, OneDimensionalStimulusWithAmplitude, OneDimensionalRadialStimulusWithAmplitude, ImageStimulus, TwoDimensionalStimulus
13
+ from patsy import dmatrix, build_design_matrices
14
+
15
+ def _apply_temperature(ll, temperature):
16
+ """Divide a log-likelihood table by the temperature (None/1 = unchanged,
17
+ inf = flat)."""
18
+ if temperature is None or temperature == 1:
19
+ return ll
20
+ temperature = float(temperature)
21
+ if temperature <= 0:
22
+ raise ValueError('temperature must be > 0')
23
+ if np.isinf(temperature):
24
+ return np.zeros_like(ll)
25
+ return ll / temperature
26
+
27
+
28
+ _REMOVED_STATE = ('paradigm', 'data', 'parameters', 'weights', 'omega')
29
+
30
+
31
+ def _reject_state_kwargs(kwargs, class_name, strict=True):
32
+ """Explain the 0.7 API when a constructor still gets data or fitted values."""
33
+ removed = [k for k in kwargs if k in _REMOVED_STATE]
34
+ if removed:
35
+ raise TypeError(
36
+ f'{class_name} no longer takes {", ".join(removed)}. Since braincoder 0.7, '
37
+ 'models hold only their configuration: pass paradigm, parameters, weights, '
38
+ 'omega and dof to each method, e.g. model.predict(paradigm, parameters). '
39
+ 'See the migration guide: https://braincoder-devs.github.io/migration.html')
40
+ if kwargs and strict:
41
+ raise TypeError(f'{class_name} got unexpected arguments: {", ".join(kwargs)}')
42
+
43
+
44
+ def _cholesky_numpy(omega):
45
+ """Cholesky factor with adaptive jitter for a slightly non-PSD Ω."""
46
+ return ops.convert_to_numpy(safe_cholesky(ops.convert_to_tensor(omega, dtype='float32')))
47
+
48
+
49
+ def _check_finite_parameters(parameters):
50
+ if parameters is not None and not np.isfinite(parameters).all():
51
+ n_bad = int((~np.isfinite(parameters)).any(axis=1).sum())
52
+ raise ValueError(
53
+ f'{n_bad} of {len(parameters)} rows of the parameters contain NaN or inf, '
54
+ 'which would make every posterior NaN. Drop those voxels (with their '
55
+ 'data and Ω) before decoding.')
56
+
57
+
58
+ class EncodingModel(object):
59
+ """Abstract base class for encoding models."""
60
+
61
+ parameter_labels = None
62
+ stimulus_type = Stimulus
63
+
64
+ def _transform_parameters_forward(self, parameters):
65
+ """Map unconstrained optimizer parameters to the model's native space."""
66
+ out = []
67
+ for i, t in enumerate(self.transformations):
68
+ param = parameters[:, i][:, None]
69
+ if isinstance(t, tuple):
70
+ out.append(t[0](param))
71
+ elif t == 'identity':
72
+ out.append(param)
73
+ elif t == 'softplus':
74
+ out.append(ops.softplus(param))
75
+ elif t == 'aggressive_softplus':
76
+ out.append(aggressive_softplus(param))
77
+ elif t == 'sigmoid':
78
+ out.append(ops.sigmoid(param))
79
+ else:
80
+ raise NotImplementedError(f"Unknown transform: {t!r}")
81
+ return ops.concatenate(out, axis=1)
82
+
83
+ def _transform_parameters_backward(self, parameters):
84
+ """Inverse of :meth:`_transform_parameters_forward`."""
85
+ out = []
86
+ for i, t in enumerate(self.transformations):
87
+ param = parameters[:, i][:, None]
88
+ if isinstance(t, tuple):
89
+ out.append(t[1](param))
90
+ elif t == 'identity':
91
+ out.append(param)
92
+ elif t == 'softplus':
93
+ out.append(softplus_inverse(param))
94
+ elif t == 'aggressive_softplus':
95
+ out.append(aggressive_softplus_inverse(param))
96
+ elif t == 'sigmoid':
97
+ out.append(ops.log(param / (1.0 - param)))
98
+ else:
99
+ raise NotImplementedError(f"Unknown transform: {t!r}")
100
+ return ops.concatenate(out, axis=1)
101
+
102
+ #: Whether ``get_pseudoWWT`` needs a stimulus range (images do not).
103
+ pseudo_wwt_needs_stimulus_range = True
104
+
105
+ def __init__(self, n_dimensions=1, verbosity=logging.INFO, **kwargs):
106
+ """Configure the model. It holds no data, parameters or noise model."""
107
+ _reject_state_kwargs(kwargs, type(self).__name__)
108
+ if n_dimensions == 1:
109
+ self.stimulus = self._get_stimulus()
110
+ else:
111
+ self.stimulus = self._get_stimulus(n_dimensions=n_dimensions)
112
+
113
+ def get_parameter_labels(self):
114
+ """Return the ordered list of parameter labels used by the model."""
115
+ return self.parameter_labels
116
+
117
+ def _zero_baseline(self, parameters):
118
+ """Return a copy of parameters with the baseline column set to zero.
119
+
120
+ For models whose ``parameter_labels`` contains ``'baseline'`` this
121
+ removes the DC-offset from basis predictions so that the pseudo-WWT
122
+ matrix reflects only the signal covariance. For models without a
123
+ simple ``'baseline'`` label (e.g. ``EncodingRegressionModel``, whose
124
+ ``parameter_labels`` is a MultiIndex) the parameters are returned
125
+ unchanged.
126
+ """
127
+ if isinstance(self.parameter_labels, list) and 'baseline' in self.parameter_labels:
128
+ parameters = parameters.copy()
129
+ parameters['baseline'] = 0.0
130
+ return parameters
131
+
132
+ def _predict(self, paradigm, parameters, weights=None):
133
+ """Low-level prediction used by ``predict``/``simulate``."""
134
+ # Ensure all inputs are backend tensors to avoid mixed numpy/torch MPS issues
135
+ paradigm = ops.convert_to_tensor(paradigm, dtype='float32')
136
+ if parameters is not None:
137
+ parameters = ops.convert_to_tensor(parameters, dtype='float32')
138
+ if weights is not None:
139
+ weights = ops.convert_to_tensor(weights, dtype='float32')
140
+
141
+ if weights is None:
142
+ return self._basis_predictions(paradigm, parameters)
143
+ else:
144
+ return ops.tensordot(self._basis_predictions(paradigm, parameters), weights, axes=[[2], [1]])[:, :, 0, :]
145
+
146
+ def _get_stimulus_type(self, **kwargs):
147
+ """Return the ``Stimulus`` subclass used to clean/generate paradigms."""
148
+ return self.stimulus_type
149
+
150
+ def _get_stimulus(self, **kwargs):
151
+ """Instantiate the configured ``Stimulus`` type."""
152
+ return self.stimulus_type(**kwargs)
153
+
154
+ def predict(self, paradigm, parameters=None, weights=None):
155
+ """Return pandas predictions for the provided paradigm/parameters."""
156
+
157
+ weights, weights_ = self._get_weights(weights)
158
+
159
+ paradigm = self.get_paradigm(paradigm)
160
+ paradigm_ = self._get_paradigm(paradigm)[np.newaxis, ...]
161
+
162
+ parameters = self._get_parameters(parameters)
163
+
164
+ parameters_ = parameters.values[np.newaxis, ...] if parameters is not None else None
165
+
166
+ predictions = self._predict(paradigm_, parameters_, weights_)[0]
167
+
168
+ if weights is not None:
169
+ columns = weights.columns
170
+ else:
171
+ columns = parameters.index if parameters is not None else None
172
+
173
+ return pd.DataFrame(ops.convert_to_numpy(predictions), index=paradigm.index, columns=columns)
174
+
175
+ def simulate(self, paradigm, parameters=None, weights=None, noise=1.,
176
+ dof=None, n_repeats=1):
177
+ """Generate synthetic data by adding noise to predictions."""
178
+
179
+ weights, weights_ = self._get_weights(weights)
180
+ paradigm = self.get_paradigm(paradigm)
181
+ paradigm_ = self._get_paradigm(paradigm)
182
+
183
+ parameters = self._get_parameters(parameters)
184
+
185
+ stimulus = self.stimulus._generate_stimulus(paradigm_)
186
+
187
+ stimulus = np.repeat(stimulus[np.newaxis, ...], n_repeats, axis=0)
188
+
189
+ simulated_data = self._simulate(
190
+ stimulus,
191
+ parameters.values[np.newaxis, ...] if parameters is not None else None,
192
+ weights_, noise, dof)
193
+
194
+ simulated_data = ops.convert_to_numpy(simulated_data)
195
+
196
+ # Collapse the first two dimensions
197
+ simulated_data = np.reshape(simulated_data, (n_repeats*paradigm.shape[0], simulated_data.shape[2]))
198
+
199
+ if n_repeats == 1:
200
+ index = pd.Index(paradigm.index, name='stimulus')
201
+ else:
202
+ index = pd.MultiIndex.from_product([np.arange(n_repeats), paradigm.index], names=['repeat', 'stimulus'])
203
+
204
+ if weights is not None:
205
+ columns = weights.columns
206
+ else:
207
+ columns = parameters.index if parameters is not None else None
208
+
209
+ return pd.DataFrame(simulated_data, index=index, columns=columns)
210
+
211
+ def _simulate(self, paradigm, parameters, weights, noise=1., dof=None):
212
+ """Compute predictions and add noise."""
213
+
214
+ n_batches = paradigm.shape[0]
215
+ n_timepoints = paradigm.shape[1]
216
+
217
+ if weights is None:
218
+ n_voxels = parameters.shape[1]
219
+ else:
220
+ n_voxels = weights.shape[2]
221
+
222
+ if dof is None:
223
+ if np.isscalar(noise):
224
+ noise_samples = keras.random.normal(shape=(n_batches, n_timepoints, n_voxels),
225
+ stddev=noise)
226
+ else:
227
+ noise = noise.astype(np.float32)
228
+ L = safe_cholesky(ops.convert_to_tensor(noise))
229
+ noise_samples = sample_mvn(L, (n_batches, n_timepoints))
230
+ else:
231
+ if np.isscalar(noise):
232
+ noise_samples = sample_student_t(dof, noise, (n_batches, n_timepoints, n_voxels))
233
+ else:
234
+ noise = noise.astype(np.float32)
235
+ L = safe_cholesky(ops.convert_to_tensor(noise))
236
+ noise_samples = sample_mvt(L, dof, (n_batches, n_timepoints))
237
+
238
+ return self._predict(paradigm, parameters, weights) + noise_samples
239
+
240
+ def _gradient(self, stimuli, parameters):
241
+ """Compute d(predictions)/d(stimuli) using Jacobians."""
242
+ from ..utils.backend import compute_jacobian
243
+ stimuli = ops.convert_to_tensor(stimuli)
244
+ fn = lambda s: self._predict(s, parameters)
245
+ jacobians = compute_jacobian(fn, stimuli)
246
+ gradients = ops.sum(jacobians, axis=[-2, -1])
247
+ return ops.squeeze(gradients, axis=-1)
248
+
249
+ def likelihood(self, stimuli, data, parameters=None, weights=None, omega=None, dof=None, logp=False, normalize=True):
250
+ """Log-likelihood of observing ``data`` given stimuli and model parameters."""
251
+
252
+ data = format_data(data)
253
+ parameters = self._get_parameters(parameters)
254
+
255
+ if weights is not None:
256
+ weights = weights if not hasattr(weights, 'values') else weights.values
257
+
258
+ if omega is None:
259
+ raise ValueError('likelihood needs the noise covariance omega.')
260
+
261
+ if not isinstance(stimuli, pd.DataFrame):
262
+ stimuli = pd.DataFrame(stimuli)
263
+ stimuli.index.name = 'stimulus'
264
+ stimuli.columns.name = 'stimulus dimension'
265
+
266
+ omega_chol = _cholesky_numpy(omega)
267
+
268
+ likelihood = self._likelihood(stimuli.values[np.newaxis, ...],
269
+ data.values[np.newaxis, ...],
270
+ parameters.values[np.newaxis, ...] if parameters is not None else None,
271
+ weights[np.newaxis, ...] if weights is not None else None,
272
+ omega_chol,
273
+ dof,
274
+ logp,
275
+ normalize)
276
+
277
+ likelihood = ops.convert_to_numpy(likelihood)
278
+
279
+ likelihood = pd.DataFrame(
280
+ likelihood, index=data.index, columns=stimuli.index)
281
+
282
+ return likelihood
283
+
284
+ def _prepare_stimulus_range(self, stimulus_range):
285
+ if hasattr(stimulus_range, 'values'):
286
+ stimulus_range = stimulus_range.values
287
+
288
+ stimulus_range = self.stimulus._clean_paradigm(stimulus_range)
289
+
290
+ if stimulus_range.ndim == 1:
291
+ stimulus_range = stimulus_range[:, np.newaxis, np.newaxis]
292
+ elif stimulus_range.ndim == 2:
293
+ stimulus_range = stimulus_range[:, np.newaxis, :]
294
+ else:
295
+ raise Exception('Stimulus range needs to be either 1D or 2D')
296
+ return stimulus_range
297
+
298
+ def _predict_grid(self, stimulus_range, parameters, weights):
299
+ """Predictions for decoding: one batch per candidate stimulus."""
300
+ return self._predict(stimulus_range, parameters, weights)
301
+
302
+ def predict_stimulus_grid(self, stimulus_range, parameters=None, weights=None):
303
+ """Predicted response to every stimulus of a decoding grid.
304
+
305
+ Returns a float64 array ``(n_stimuli, n_voxels)``. Uses the same
306
+ batching as :meth:`get_stimulus_pdf` (one batch per grid point).
307
+ """
308
+ parameters = self._get_parameters(parameters)
309
+ if hasattr(parameters, 'values'):
310
+ parameters = parameters.values
311
+ _check_finite_parameters(parameters)
312
+ weights, weights_ = self._get_weights(weights)
313
+ stimulus_range = self._prepare_stimulus_range(stimulus_range)
314
+ pred = self._predict_grid(stimulus_range,
315
+ parameters[np.newaxis, :, :] if parameters is not None else None,
316
+ weights_)
317
+ return np.asarray(ops.convert_to_numpy(pred), dtype=np.float64)[:, 0, :]
318
+
319
+ def get_stimulus_pdf(self, data, stimulus_range, parameters=None, weights=None, omega=None, dof=None, normalize=True,
320
+ include_multidimensional_stimulus_index=False, noise_model=None, temperature=None):
321
+ """Evaluate posterior over stimuli for each time point given data.
322
+
323
+ Parameters
324
+ ----------
325
+ data : DataFrame or array (n_timepoints, n_voxels)
326
+ stimulus_range : array (n_stimuli,) or (n_stimuli, n_dims)
327
+ Grid of candidate stimuli (flat prior over the grid).
328
+ parameters, weights : DataFrame
329
+ Encoding parameters, and basis weights for basis-function models.
330
+ omega, dof : array, float, optional
331
+ Dense noise covariance and Student-t degrees of freedom, e.g. from
332
+ ``ResidualFitter.fit``. ``dof=None`` means Gaussian. Pass either
333
+ ``omega`` or ``noise_model``.
334
+ noise_model : braincoder.noise.LowRankNoise, optional
335
+ Factored noise model (low-rank + diagonal Ω, Gaussian or
336
+ Student-t). The likelihood is evaluated with the Woodbury identity
337
+ (no dense V × V matrix). Its ``temperature`` is applied unless
338
+ ``temperature`` is passed explicitly.
339
+ temperature : float, optional
340
+ Likelihood temperature T: posterior ∝ likelihood^(1/T). Default
341
+ ``None`` = 1 (or the noise model's own temperature). ``np.inf``
342
+ gives a flat posterior.
343
+ """
344
+
345
+ if hasattr(data, 'values'):
346
+ time_index = data.index
347
+ else:
348
+ time_index = pd.Index(np.arange(len(data)), name='frame')
349
+
350
+ stimulus_range = self._prepare_stimulus_range(stimulus_range)
351
+
352
+ if noise_model is not None:
353
+ pred = self.predict_stimulus_grid(stimulus_range[:, 0, :], parameters=parameters,
354
+ weights=weights)
355
+ ll = noise_model.grid_log_likelihood(data, pred).T # (n_stimuli, n_timepoints)
356
+ if temperature is None:
357
+ temperature = noise_model.temperature
358
+ else:
359
+ if hasattr(data, 'values'):
360
+ data = data.values
361
+
362
+ parameters = self._get_parameters(parameters)
363
+
364
+ if hasattr(parameters, 'values'):
365
+ parameters = parameters.values
366
+
367
+ _check_finite_parameters(parameters)
368
+
369
+ if omega is None:
370
+ raise ValueError('get_stimulus_pdf needs a noise model: pass omega (and dof) or noise_model.')
371
+
372
+ # Compute Cholesky factor here so callers never need to do it themselves.
373
+ # ``safe_cholesky`` symmetrises and adds adaptive diagonal jitter so a
374
+ # noise covariance that slipped slightly below PSD (e.g. residual
375
+ # fitter drove α/β/ρ to numerical edges) still factorises cleanly.
376
+ omega_t = ops.convert_to_tensor(omega, dtype='float32')
377
+ omega_chol = safe_cholesky(omega_t)
378
+
379
+ weights, weights_ = self._get_weights(weights)
380
+
381
+ # Convert ``data`` to a backend tensor at the entry point so the
382
+ # downstream ``data - prediction`` in ``_likelihood_timeseries``
383
+ # doesn't end up mixing numpy with a torch tensor (which raises
384
+ # ``TypeError: unsupported operand type(s) for -``).
385
+ data_t = ops.convert_to_tensor(data, dtype='float32')
386
+
387
+ prediction = self._predict_grid(stimulus_range,
388
+ parameters[np.newaxis, :, :] if parameters is not None else None,
389
+ weights_)
390
+ ll = self._likelihood_timeseries(data_t[None, :, :],
391
+ prediction,
392
+ omega_chol,
393
+ dof,
394
+ logp=True,
395
+ normalize=False)
396
+
397
+ ll = ops.convert_to_numpy(ll)
398
+
399
+ ll = _apply_temperature(ll, temperature)
400
+
401
+ if stimulus_range.shape[-1] == 1:
402
+ ll = pd.DataFrame(ll.T, index=time_index, columns=pd.Index(
403
+ stimulus_range[:, 0, 0], name='stimulus'))
404
+ else:
405
+ if include_multidimensional_stimulus_index:
406
+ index = pd.MultiIndex.from_frame(pd.DataFrame(stimulus_range[:, 0, :],
407
+ columns=self.stimulus.dimension_labels))
408
+ else:
409
+ index = None
410
+
411
+ ll = pd.DataFrame(ll.T, index=time_index, columns=index)
412
+
413
+ ll = np.exp(ll.apply(lambda d: d-d.max(), 1))
414
+
415
+ if normalize and not isinstance(ll.columns, pd.MultiIndex):
416
+ ll /= _trapezoid(ll, ll.columns)[:, np.newaxis]
417
+
418
+ return ll
419
+
420
+ def get_WWT(self, weights):
421
+ """Tuning similarity between voxels, from basis weights."""
422
+ weights = format_weights(weights)
423
+ return weights.T.dot(weights)
424
+
425
+ def _likelihood(self, stimuli, data, parameters, weights, omega_chol, dof, logp=False, normalize=False):
426
+ """Compute likelihoods for batches of stimuli."""
427
+ prediction = self._predict(stimuli, parameters, weights)
428
+ return self._likelihood_timeseries(data, prediction, omega_chol, dof, logp, normalize)
429
+
430
+ def _likelihood_timeseries(self, data, prediction, omega_chol, dof, logp=False, normalize=False):
431
+ """Evaluate log-probabilities for each residual timeseries."""
432
+ residuals = data - prediction
433
+
434
+ # Flatten to 2D for log_prob: (n_batches * n_timepoints, n_voxels)
435
+ n_batches, n_timepoints, n_voxels = residuals.shape
436
+ residuals_2d = ops.reshape(residuals, (n_batches * n_timepoints, n_voxels))
437
+
438
+ omega_chol_t = ops.convert_to_tensor(omega_chol, dtype='float32')
439
+
440
+ if dof is None:
441
+ p_flat = mvn_log_prob(residuals_2d, omega_chol_t)
442
+ else:
443
+ p_flat = mvt_log_prob(residuals_2d, omega_chol_t, dof)
444
+
445
+ p = ops.reshape(p_flat, (n_batches, n_timepoints))
446
+
447
+ if logp:
448
+ return p
449
+
450
+ if normalize:
451
+ p = p - ops.max(p, axis=1)[:, None]
452
+ p = ops.exp(p)
453
+ p = p / ops.sum(p, axis=1)[:, None]
454
+ else:
455
+ p = ops.exp(p)
456
+
457
+ return p
458
+
459
+ def _get_weights(self, weights=None):
460
+
461
+ weights = format_weights(weights)
462
+
463
+ if weights is None:
464
+ weights_ = weights
465
+ else:
466
+ weights_ = weights.values[np.newaxis, ...]
467
+
468
+ return weights, weights_
469
+
470
+ def get_fisher_information(self, stimuli, omega=None, dof=None, weights=None, parameters=None, n=1000,
471
+ analytical=True):
472
+ """Population Fisher information per stimulus value.
473
+
474
+ Two computation paths:
475
+
476
+ * **Analytical** (default) — closed form
477
+ ``FI(s) = J(s)ᵀ Ω⁻¹ J(s)`` for Gaussian noise, or
478
+ ``FI(s) = (ν + p) / (ν + p + 2) · J(s)ᵀ Ω⁻¹ J(s)`` for
479
+ multivariate Student-t with degrees of freedom ``ν = dof`` and
480
+ dimensionality ``p`` (number of voxels in ``Ω``). Exact, fast,
481
+ no MC noise; recommended for *any* fitted noise model.
482
+ * **Monte-Carlo** (``analytical=False``) — average squared score
483
+ over ``n`` simulated noise draws. Useful as a sanity check and
484
+ for non-quadratic likelihoods, but in our setup gives
485
+ essentially identical curves with much higher variance, so
486
+ prefer the analytical path.
487
+
488
+ The Student-t correction factor reduces FI relative to Gaussian
489
+ by exactly ``(ν + p) / (ν + p + 2) < 1`` for finite ``ν`` —
490
+ heavy-tailed noise carries less information per voxel.
491
+ """
492
+
493
+ if omega is None:
494
+ raise ValueError("Need noise covariance matrix omega!")
495
+
496
+ weights, weights_ = self._get_weights(weights)
497
+
498
+ parameters = self._get_parameters(parameters)
499
+ parameters_ = parameters.values[np.newaxis, ...].astype(np.float32) if parameters is not None else None
500
+
501
+ if stimuli.ndim == 1:
502
+ stimuli = stimuli[:, np.newaxis]
503
+
504
+ omega_t = ops.convert_to_tensor(omega, dtype='float32')
505
+ L = safe_cholesky(omega_t)
506
+ # p = dimensionality of the residual = number of voxels in Ω.
507
+ p_dim = int(omega_t.shape[0])
508
+
509
+ if analytical:
510
+ stimuli_ = ops.convert_to_tensor(stimuli[np.newaxis, ...])
511
+ gradient = self._gradient(stimuli_, parameters_)[0]
512
+
513
+ y = []
514
+ for i in range(gradient.shape[0]):
515
+ y.append(ops.solve_triangular(L, gradient[i, :, None], lower=True))
516
+
517
+ y = ops.concatenate(y, axis=1)
518
+ fisher_info = ops.sum(y ** 2, axis=0)
519
+ if dof is not None:
520
+ # Closed-form multivariate-t FI: scale by (ν + p) / (ν + p + 2).
521
+ # As ν → ∞ this approaches 1 and we recover the Gaussian case.
522
+ dof_t = ops.cast(dof, 'float32')
523
+ factor = (dof_t + p_dim) / (dof_t + p_dim + 2.0)
524
+ fisher_info = fisher_info * factor
525
+
526
+ else:
527
+ from ..utils.backend import compute_gradients
528
+ stimuli_ = ops.convert_to_tensor(
529
+ ops.tile(stimuli[np.newaxis, ...], [n, 1, 1]))
530
+
531
+ noise = sample_mvn(L, (n,)) if dof is None else sample_mvt(L, dof, (n,))
532
+ pred = self._predict(stimuli_, parameters_, weights_)
533
+ data = pred + noise[:, None, :]
534
+
535
+ stimuli_var = keras.Variable(stimuli_, name='stimuli')
536
+
537
+ def ll_fn():
538
+ # ``_likelihood`` returns log-probs of shape (n_sim, n_stim).
539
+ # Each entry depends only on its own ``stimuli_var`` row,
540
+ # so summing before differentiating is mathematically
541
+ # equivalent to taking the per-entry gradient and is the
542
+ # only form that works across TF / JAX / PyTorch backends
543
+ # (JAX's ``value_and_grad`` and torch's ``autograd.grad``
544
+ # both reject non-scalar outputs).
545
+ logp = self._likelihood(stimuli_var, data, parameters_, weights_, L, dof,
546
+ logp=True, normalize=False)
547
+ return ops.sum(logp)
548
+
549
+ ll, dy_dx = compute_gradients(ll_fn, [stimuli_var])
550
+ fisher_info = ops.mean(dy_dx[0] ** 2, 0)[..., 0]
551
+
552
+ fisher_info = ops.convert_to_numpy(fisher_info)
553
+
554
+ if stimuli.shape[1] == 1:
555
+ return pd.Series(fisher_info, index=pd.Index(stimuli[:, 0], name='stimulus'), name='Fisher information')
556
+ else:
557
+ return pd.Series(fisher_info, index=pd.MultiIndex.from_frame(pd.DataFrame(stimuli)), name='Fisher information')
558
+
559
+ def get_expected_uncertainty(self, stimuli, omega, dof=None,
560
+ parameters=None, weights=None,
561
+ n_simulations=1000, batch_stimuli=None,
562
+ decoder_stimulus_range=None,
563
+ progress=False):
564
+ """Simulate noisy responses, decode them, summarise per-stimulus.
565
+
566
+ Procedure (mirrors the analytical Fisher information but lets
567
+ you read off *posterior* quantities directly):
568
+
569
+ 1. For each stimulus ``s`` in ``stimuli``, draw ``n_simulations``
570
+ independent noisy responses ``r ~ p(r | s, Ω, dof)``.
571
+ 2. Compute the posterior ``p(s | r)`` over a fine
572
+ ``decoder_stimulus_range`` (defaults to ``stimuli`` itself).
573
+ 3. Take the posterior expected value of each simulated trial
574
+ and aggregate across the ``n_simulations`` repeats per stimulus.
575
+
576
+ Parameters
577
+ ----------
578
+ stimuli : array_like
579
+ Stimulus values to simulate from + use as the aggregation axis.
580
+ Shape ``(n_stim,)`` for 1-D models or ``(n_stim, n_dims)``.
581
+ omega : array_like
582
+ Noise covariance.
583
+ dof : float or None
584
+ Degrees of freedom for multivariate Student-t noise. ``None``
585
+ uses Gaussian.
586
+ parameters : DataFrame or None
587
+ Encoding-model parameters (one row per voxel).
588
+ weights : DataFrame or None
589
+ Basis weights for linear models.
590
+ n_simulations : int
591
+ Noisy repeats per stimulus.
592
+ batch_stimuli : int or None
593
+ Process this many stimuli per simulation/decoding batch.
594
+ ``None`` does them all at once. Use a small number (e.g. 25)
595
+ to bound memory when the stimulus grid is large.
596
+ decoder_stimulus_range : array_like or None
597
+ Grid for posterior evaluation. Defaults to ``stimuli``. Pass
598
+ a finer grid to make ``var_E`` reflect decoder resolution
599
+ independent of the simulation grid.
600
+ progress : bool
601
+ If True, print a one-line status per batch.
602
+
603
+ Returns
604
+ -------
605
+ DataFrame
606
+ Index = stimulus value (or MultiIndex for N-D stimuli).
607
+ Columns: ``mean_E, var_E, mean_error, mean_abs_error, n_sims``.
608
+ ``mean_E`` is the average posterior mean; ``var_E`` is its
609
+ empirical variance across simulations (≈ 1/FI in well-fit
610
+ regimes); ``mean_error = mean_E - true_value`` is decoder
611
+ bias; ``mean_abs_error`` is average absolute decode error.
612
+
613
+ Notes
614
+ -----
615
+ ``var_E`` is the variance of the *posterior expected value across
616
+ simulations* — different from the average posterior variance.
617
+ For unbiased decoders in a Gaussian/CRB regime,
618
+ ``var_E ≈ 1 / Fisher_information``. The two diverge when the
619
+ posterior is skewed or bounded by the grid edges.
620
+ """
621
+ from ..utils.math import get_expected_value
622
+ from ..utils.formatting import format_parameters, format_weights
623
+
624
+ stimuli_arr = np.asarray(stimuli)
625
+ if stimuli_arr.ndim == 1:
626
+ stimuli_arr = stimuli_arr[:, np.newaxis]
627
+
628
+ parameters = format_parameters(parameters) if parameters is not None else None
629
+ weights = format_weights(weights) if weights is not None else None
630
+
631
+ if decoder_stimulus_range is None:
632
+ decoder_stimulus_range = stimuli_arr
633
+ else:
634
+ decoder_stimulus_range = np.asarray(decoder_stimulus_range)
635
+ if decoder_stimulus_range.ndim == 1:
636
+ decoder_stimulus_range = decoder_stimulus_range[:, np.newaxis]
637
+
638
+ n_total = stimuli_arr.shape[0]
639
+ batch = n_total if batch_stimuli is None else int(batch_stimuli)
640
+
641
+ records = []
642
+ for start in range(0, n_total, batch):
643
+ stop = min(start + batch, n_total)
644
+ stim_batch = stimuli_arr[start:stop]
645
+ stim_df = pd.DataFrame(stim_batch,
646
+ columns=self.stimulus.dimension_labels
647
+ if hasattr(self.stimulus, 'dimension_labels')
648
+ else ['x'])
649
+ stim_df.index.name = 'stimulus'
650
+
651
+ sim = self.simulate(paradigm=stim_df, parameters=parameters,
652
+ weights=weights, noise=omega, dof=dof,
653
+ n_repeats=n_simulations)
654
+ # sim index: ('repeat', 'stimulus') if n_repeats > 1, else 'stimulus'.
655
+
656
+ pdf = self.get_stimulus_pdf(sim, decoder_stimulus_range,
657
+ parameters=parameters,
658
+ weights=weights, omega=omega,
659
+ dof=dof, normalize=True)
660
+ # Get expected value per simulated trial — works for 1-D pdfs.
661
+ try:
662
+ E = get_expected_value(pdf, normalize=True)
663
+ except Exception:
664
+ # 2-D stimulus pdfs aren't supported by get_expected_value;
665
+ # fall back to per-dimension expectation in that case.
666
+ raise NotImplementedError(
667
+ 'get_expected_uncertainty currently supports 1-D '
668
+ 'stimulus spaces only. Multidimensional posterior '
669
+ 'aggregation will be added when needed.')
670
+
671
+ # Align each E entry with its true stimulus.
672
+ idx = pdf.index
673
+ if isinstance(idx, pd.MultiIndex):
674
+ stim_lvl = next((n for n in idx.names
675
+ if n in ('stimulus', 'value')), idx.names[-1])
676
+ stim_pos = list(idx.names).index(stim_lvl)
677
+ true_idx = idx.get_level_values(stim_pos).to_numpy()
678
+ else:
679
+ true_idx = idx.to_numpy()
680
+ # true_idx is an offset into stim_batch's stimulus index; map to value.
681
+ stim_values = stim_batch[:, 0] if stim_batch.shape[1] == 1 else stim_batch
682
+ value_lookup = pd.Series(stim_values, index=stim_df.index)
683
+ true_vals = value_lookup.reindex(true_idx).to_numpy()
684
+ for tv, ev in zip(true_vals, np.asarray(E)):
685
+ records.append({'value': float(tv), 'E': float(ev)})
686
+ if progress:
687
+ print(f' [stim {start}:{stop}/{n_total}] '
688
+ f'{(stop - start) * n_simulations} simulated trials')
689
+
690
+ df = pd.DataFrame(records)
691
+ df['error'] = df['E'] - df['value']
692
+ df['abs_error'] = df['error'].abs()
693
+ out = df.groupby('value').agg(
694
+ mean_E=('E', 'mean'),
695
+ var_E=('E', 'var'),
696
+ mean_error=('error', 'mean'),
697
+ mean_abs_error=('abs_error', 'mean'),
698
+ n_sims=('E', 'count'),
699
+ )
700
+ return out
701
+
702
+ def _get_parameters(self, parameters=None):
703
+ """Return parameters formatted as DataFrame matching ``parameter_labels``."""
704
+
705
+ if parameters is None:
706
+ if self.parameter_labels is not None and len(self.parameter_labels) > 0:
707
+ raise ValueError(f'{type(self).__name__} needs parameters: pass parameters=... '
708
+ f'with columns {list(self.parameter_labels)}.')
709
+ return None
710
+
711
+ parameters = format_parameters(parameters)
712
+
713
+ return parameters[self.parameter_labels]
714
+
715
+ def get_paradigm(self, paradigm):
716
+ """Return the paradigm as a cleaned DataFrame."""
717
+
718
+ if paradigm is None:
719
+ raise ValueError('Please provide paradigm!')
720
+
721
+ return self.stimulus.clean_paradigm(paradigm)
722
+
723
+ def _get_paradigm(self, paradigm):
724
+ """Tensor-ready paradigm (np.array) used inside computation."""
725
+ return self.stimulus._clean_paradigm(paradigm)
726
+
727
+
728
+ class EncodingRegressionModel(EncodingModel):
729
+ """Encoding model whose parameters are linear combinations of regressors.
730
+
731
+ Parameters
732
+ ----------
733
+ design_data : DataFrame
734
+ Named stimulus dimensions plus the columns used by ``regressors``. It only
735
+ defines the design (columns, factor levels and so on). Pass the actual
736
+ paradigm, with the same columns, to each method.
737
+ regressors : dict
738
+ Patsy formula per parameter, e.g. ``{'mu': '0 + C(condition)'}``.
739
+ Parameters without a formula get an intercept.
740
+ """
741
+
742
+ def __init__(self, design_data=None, regressors=None,
743
+ baseline_parameter_values=None,
744
+ verbosity=logging.INFO, **kwargs):
745
+
746
+ if design_data is None:
747
+ raise TypeError(f'{type(self).__name__} needs design_data: a DataFrame with the stimulus '
748
+ 'dimensions and regressor columns.' +
749
+ (' It replaces the paradigm argument since braincoder 0.7.' if 'paradigm' in kwargs else ''))
750
+
751
+ super().__init__(verbosity=verbosity, **kwargs)
752
+
753
+ for label in self.stimulus.dimension_labels:
754
+ if label not in design_data:
755
+ raise ValueError('design_data is missing required dimension: ' + label +
756
+ '\nNote that `EncodingRegressionModel` requires named stimulus dimensions!')
757
+
758
+ design_data = design_data.astype(np.float32)
759
+ self.regressors = dict(regressors or {})
760
+ self.design_columns = list(design_data.columns)
761
+ self.base_parameter_labels = list(self.parameter_labels)
762
+ self.design_infos = {
763
+ parameter: dmatrix(self.regressors.get(parameter, '1'), design_data).design_info
764
+ for parameter in self.base_parameter_labels}
765
+ self.parameter_labels = pd.MultiIndex.from_tuples(
766
+ [(parameter + '_unbounded', column)
767
+ for parameter in self.base_parameter_labels
768
+ for column in self.design_infos[parameter].column_names],
769
+ names=['parameter', 'regressor'])
770
+
771
+ baseline_parameter_values = baseline_parameter_values or {}
772
+
773
+ self.baseline_parameter_values = {
774
+ param: baseline_parameter_values.get(param, 0.0)
775
+ for param in self.base_parameter_labels
776
+ }
777
+
778
+ # A one-entry memo: patsy is too slow to rerun at every optimizer step.
779
+ # It does not change any result, and it is keyed on the paradigm values.
780
+ self._design_cache = (None, None)
781
+
782
+ self._basis_basis_predictions = self._basis_predictions
783
+ self._basis_predictions = self._basis_predictions_regressors
784
+
785
+ self._base_transform_parameters_forward = self._transform_parameters_forward
786
+ self._base_transform_parameters_backward = self._transform_parameters_backward
787
+
788
+ self._transform_parameters_forward = lambda x: x
789
+ self._transform_parameters_backward = lambda x: x
790
+
791
+ def get_paradigm(self, paradigm):
792
+ """Return the paradigm with the columns of ``design_data``, in the same order."""
793
+ if not isinstance(paradigm, pd.DataFrame):
794
+ raise ValueError(f'{type(self).__name__} needs a paradigm DataFrame with columns {self.design_columns}.')
795
+ return paradigm[self.design_columns].astype(np.float32)
796
+
797
+ def _get_paradigm(self, paradigm):
798
+ if isinstance(paradigm, pd.DataFrame):
799
+ paradigm = paradigm[self.design_columns]
800
+ return self.stimulus._clean_paradigm(paradigm)
801
+
802
+ def _design_matrices(self, paradigm):
803
+ frame = pd.DataFrame(np.asarray(paradigm), columns=self.design_columns)
804
+ return {parameter: np.asarray(build_design_matrices([self.design_infos[parameter]], frame)[0], dtype=np.float32)
805
+ for parameter in self.base_parameter_labels}
806
+
807
+ def _get_base_parameters(self, design_matrices, regressor_parameters):
808
+
809
+ regressor_parameters = ops.convert_to_tensor(regressor_parameters, dtype='float32')
810
+ parameters = []
811
+
812
+ ix = 0
813
+
814
+ for parameter in self.base_parameter_labels:
815
+ design_matrix = design_matrices[parameter]
816
+ end_ix = ix + design_matrix.shape[1]
817
+
818
+ parameters.append(ops.sum(ops.convert_to_tensor(design_matrix)[:, np.newaxis, :] *
819
+ regressor_parameters[:, :, ix:end_ix], axis=2) + self.baseline_parameter_values[parameter])
820
+
821
+ ix = end_ix
822
+
823
+ parameters = ops.stack(parameters, axis=2)
824
+ parameters = keras.ops.map(self._base_transform_parameters_forward, parameters)
825
+
826
+ return parameters
827
+
828
+ def _basis_predictions_regressors(self, paradigm, parameters):
829
+ paradigm_ = ops.convert_to_numpy(paradigm)[0]
830
+ key = paradigm_.tobytes()
831
+ if self._design_cache[0] != key:
832
+ self._design_cache = (key, self._design_matrices(paradigm_))
833
+ base_parameters = self._get_base_parameters(self._design_cache[1], parameters)
834
+ stimulus_ix = [self.design_columns.index(label) for label in self.stimulus.dimension_labels]
835
+ base_paradigm = ops.convert_to_tensor(paradigm_[:, stimulus_ix][:, np.newaxis, :], dtype='float32')
836
+ result = self._basis_basis_predictions(base_paradigm, base_parameters)
837
+ return ops.reshape(result, [1, result.shape[0], -1])
838
+
839
+ def get_conditionspecific_parameters(self, conditions, parameters):
840
+
841
+ design_matrices = {
842
+ parameter: np.asarray(build_design_matrices([self.design_infos[parameter]], conditions)[0], dtype=np.float32)
843
+ for parameter in self.base_parameter_labels}
844
+
845
+ if hasattr(parameters, 'values'):
846
+ parameters_ = parameters.values
847
+ else:
848
+ parameters_ = np.array(parameters)
849
+
850
+ parameters_ = parameters_[np.newaxis, ...]
851
+
852
+ transformed_parameters = self._get_base_parameters(design_matrices, parameters_)
853
+ transformed_parameters = ops.convert_to_numpy(transformed_parameters)
854
+
855
+ transformed_parameters = np.reshape(transformed_parameters, (-1, transformed_parameters.shape[-1]))
856
+
857
+ transformed_parameters = pd.DataFrame(transformed_parameters,
858
+ index=pd.MultiIndex.from_product([conditions.index, parameters.index]),
859
+ columns=self.base_parameter_labels)
860
+
861
+ return transformed_parameters
862
+
863
+ def predict_stimulus_grid(self, stimulus_range, parameters=None, weights=None):
864
+ """Predicted response to every row of ``stimulus_range`` (n_stimuli, n_voxels)."""
865
+ pred = self.predict(stimulus_range, parameters=parameters, weights=weights)
866
+ return np.asarray(pred.values, dtype=np.float64)
867
+
868
+ def get_stimulus_pdf(self, data, stimulus_range, parameters=None, weights=None, omega=None, dof=None, normalize=True,
869
+ include_multidimensional_stimulus_index=False, noise_model=None, temperature=None):
870
+ """Posterior (unnormalised by default: max = 1) over regression stimuli.
871
+
872
+ ``noise_model`` / ``temperature``: see
873
+ :meth:`EncodingModel.get_stimulus_pdf`.
874
+ """
875
+
876
+ pred = self.predict(stimulus_range, parameters=parameters, weights=weights)
877
+
878
+ if noise_model is not None:
879
+ ll = noise_model.grid_log_likelihood(data, pred.values)
880
+ if temperature is None:
881
+ temperature = noise_model.temperature
882
+ ll = _apply_temperature(ll, temperature)
883
+ ll = pd.DataFrame(ll, index=data.index, columns=pd.MultiIndex.from_frame(stimulus_range))
884
+ if normalize:
885
+ ll = ll.sub(ll.max(axis=1), axis=0)
886
+ return np.exp(ll)
887
+
888
+ if omega is None:
889
+ raise ValueError('get_stimulus_pdf needs a noise model: pass omega (and dof) or noise_model.')
890
+
891
+ residuals = data.values[np.newaxis, :, :] - pred.values[:, np.newaxis, :]
892
+
893
+ omega_chol = _cholesky_numpy(omega)
894
+ n_units = data.shape[1]
895
+
896
+ n_batches, n_timepoints, n_voxels = residuals.shape
897
+ residuals_2d = ops.reshape(ops.convert_to_tensor(residuals, dtype='float32'),
898
+ (n_batches * n_timepoints, n_voxels))
899
+ omega_chol_t = ops.convert_to_tensor(omega_chol, dtype='float32')
900
+
901
+ if dof is None:
902
+ ll_flat = mvn_log_prob(residuals_2d, omega_chol_t)
903
+ else:
904
+ ll_flat = mvt_log_prob(residuals_2d, omega_chol_t, dof)
905
+
906
+ ll = ops.reshape(ll_flat, (n_batches, n_timepoints))
907
+ ll = ops.convert_to_numpy(ll)
908
+ ll = _apply_temperature(ll, temperature)
909
+
910
+ ll = pd.DataFrame(ll, index=pd.MultiIndex.from_frame(stimulus_range), columns=data.index).T
911
+
912
+ if normalize:
913
+ ll = ll.sub(ll.max(axis=1), axis=0)
914
+
915
+ ll = np.exp(ll)
916
+
917
+ return ll
918
+
919
+ class HRFEncodingModel(object):
920
+ """Mixin that equips an encoding model with HRF convolution support."""
921
+
922
+ def __init__(self, hrf_model=None, verbosity=logging.INFO,
923
+ flexible_hrf_parameters=False, **kwargs):
924
+
925
+ # *WithHRF classes forward their options here as well as to the base class.
926
+ _reject_state_kwargs(kwargs, type(self).__name__, strict=False)
927
+
928
+ if hrf_model is None:
929
+ raise ValueError('Please provide HRFModel!')
930
+
931
+ self.hrf_model = hrf_model
932
+
933
+ if flexible_hrf_parameters:
934
+ self.flexible_hrf_parameters = True
935
+ self.parameter_labels = self.get_parameter_labels() + self.hrf_model.parameter_labels
936
+ else:
937
+ self.flexible_hrf_parameters = False
938
+
939
+ def _predict(self, paradigm, parameters, weights):
940
+ """Convolve base predictions with HRF, reapplying amplitude/baseline."""
941
+ paradigm = ops.convert_to_tensor(paradigm, dtype='float32')
942
+ if parameters is not None:
943
+ parameters = ops.convert_to_tensor(parameters, dtype='float32')
944
+
945
+ n_pars = len(self.parameter_labels)
946
+ # Build modified parameters with baseline=0 and amplitude=1
947
+ parts = [parameters[:, :, i:i+1] for i in range(n_pars)]
948
+
949
+ if 'baseline' in self.parameter_labels:
950
+ baseline_idx = self.parameter_labels.index('baseline')
951
+ parts[baseline_idx] = ops.zeros_like(parts[baseline_idx])
952
+
953
+ if 'amplitude' in self.parameter_labels:
954
+ amplitude_idx = self.parameter_labels.index('amplitude')
955
+ parts[amplitude_idx] = ops.ones_like(parts[amplitude_idx])
956
+
957
+ standardized_parameters = ops.concatenate(parts, axis=2)
958
+
959
+ pre_convolve = EncodingModel._predict(
960
+ self, paradigm, standardized_parameters, weights)
961
+
962
+ kwargs = {}
963
+ if self.flexible_hrf_parameters:
964
+ for ix, label in enumerate(self.hrf_model.parameter_labels):
965
+ kwargs[label] = parameters[:, :, -len(self.hrf_model.parameter_labels) + ix]
966
+
967
+ pred_convolved = self.hrf_model.convolve(pre_convolve, **kwargs)
968
+
969
+ if 'amplitude' in self.parameter_labels:
970
+ pred_convolved *= parameters[:, :, amplitude_idx][:, None, :]
971
+
972
+ if 'baseline' in self.parameter_labels:
973
+ pred_convolved += parameters[:, :, baseline_idx][:, None, :]
974
+
975
+ return pred_convolved
976
+
977
+ def _predict_grid(self, stimulus_range, parameters, weights):
978
+ """Decode without the HRF.
979
+
980
+ A candidate stimulus has no time course to convolve: treating it as a
981
+ one-sample timeseries scales the tuning curve by the HRF's first
982
+ samples (about 1/17 at a TR of 1.6 s) and inflates the posterior.
983
+ """
984
+ warnings.warn(
985
+ 'Decoding with a *WithHRF model ignores the HRF. The data should be '
986
+ 'single-trial responses (e.g. betas) on the scale of the amplitude '
987
+ 'parameter, not BOLD timepoints.', UserWarning, stacklevel=3)
988
+ return self._predict_no_hrf(stimulus_range, parameters, weights)
989
+
990
+ def _not_for_timeseries(self, method):
991
+ raise NotImplementedError(
992
+ f'{method} treats stimuli as independent, but a *WithHRF model would '
993
+ 'convolve them as one timeseries. Use the same parameters, without '
994
+ 'HRF columns, on the model class without HRF.')
995
+
996
+ def get_fisher_information(self, *args, **kwargs):
997
+ self._not_for_timeseries('get_fisher_information')
998
+
999
+ def get_expected_uncertainty(self, *args, **kwargs):
1000
+ self._not_for_timeseries('get_expected_uncertainty')
1001
+
1002
+ def _predict_no_hrf(self, paradigm, parameters, weights):
1003
+ """Bypass HRF convolution; useful for diagnostics/debugging."""
1004
+ return EncodingModel._predict(self, paradigm, parameters, weights)