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,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)
|