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,666 @@
1
+ """Per-voxel iterative pRF / encoding-model fitter."""
2
+ import datetime
3
+ import logging
4
+ import os
5
+ import os.path as op
6
+ import warnings
7
+
8
+ import numpy as np
9
+ import pandas as pd
10
+ import keras
11
+ from keras import ops
12
+ from tqdm.auto import tqdm
13
+
14
+ from ..utils import format_data, format_parameters, format_paradigm, get_rsq
15
+ from ..utils.backend import compute_gradients, softplus_inverse
16
+
17
+ logger = logging.getLogger(__name__)
18
+
19
+ _VALID_NOISE_MODELS = ('ssq', 'gaussian')
20
+ # Floor added inside softplus(log_sigma2) to keep 1/σ² from blowing up
21
+ # on float32 when log_sigma2 drifts very negative for a near-noise-free
22
+ # voxel.
23
+ _SIGMA2_EPS = 1e-8
24
+
25
+
26
+ class ParameterFitter:
27
+ """Iterative optimizer that estimates model parameters for each voxel.
28
+
29
+ Single trainable ``(n_voxels, n_pars)`` keras Variable; only the
30
+ masked positions (meaningful voxels × non-fixed params) receive
31
+ gradients. Shared parameters are realized by a smaller Variable
32
+ that's broadcast back across voxels via a selector matrix.
33
+
34
+ Parameters
35
+ ----------
36
+ model : EncodingModel
37
+ data : pd.DataFrame
38
+ Timeseries, shape ``(n_timepoints, n_voxels)``.
39
+ paradigm : array-like
40
+ Stimulus paradigm; passed through ``model.get_paradigm``.
41
+ memory_limit : int
42
+ Soft budget for the grid-fit chunk size.
43
+ log_dir : str | None | False
44
+ TensorBoard log dir. ``False`` (default) disables logging.
45
+ """
46
+
47
+ def __init__(self, model, data, paradigm,
48
+ memory_limit=666666666, log_dir=False):
49
+ self.model = model
50
+ self.data = data.astype(np.float32)
51
+ self.paradigm = self._align_paradigm(model.get_paradigm(paradigm), paradigm)
52
+ self.memory_limit = memory_limit
53
+ self.log_dir = log_dir
54
+
55
+ if log_dir is None:
56
+ log_dir = op.abspath('logs/fit')
57
+
58
+ if log_dir is not False:
59
+ os.makedirs(log_dir, exist_ok=True)
60
+ if keras.backend.backend() == 'tensorflow':
61
+ import tensorflow as tf
62
+ self.summary_writer = tf.summary.create_file_writer(
63
+ op.join(log_dir,
64
+ datetime.datetime.now().strftime("%Y%m%d-%H%M%S")))
65
+
66
+ def _align_paradigm(self, paradigm, original):
67
+ """Give the paradigm the index of the data.
68
+
69
+ ``fit`` pairs rows by position, but pandas arithmetic in ``get_rsq``
70
+ and ``refine_baseline_and_amplitude`` pairs them by label, so a
71
+ mismatch would silently compare the wrong rows.
72
+ """
73
+ if len(paradigm) != len(self.data):
74
+ raise ValueError(f'paradigm has {len(paradigm)} rows but data has '
75
+ f'{len(self.data)}.')
76
+ if paradigm.index.equals(self.data.index):
77
+ return paradigm
78
+ if isinstance(original, (pd.DataFrame, pd.Series)):
79
+ name = paradigm.index.name
80
+ same_level = (name in self.data.index.names and paradigm.index.equals(
81
+ self.data.index.get_level_values(name)))
82
+ if not same_level:
83
+ warnings.warn(
84
+ 'The index of the paradigm differs from the index of the data. '
85
+ 'Pairing their rows by position and using the index of the data.',
86
+ RuntimeWarning, stacklevel=3)
87
+ return paradigm.set_axis(self.data.index, axis=0)
88
+
89
+ # ------------------------------------------------------------ fit
90
+ def fit(self, max_n_iterations=1000,
91
+ min_n_iterations=100,
92
+ init_pars=None,
93
+ confounds=None,
94
+ optimizer=None,
95
+ fixed_pars=None,
96
+ shared_pars=None,
97
+ noise_model='ssq',
98
+ store_intermediate_parameters=False,
99
+ r2_atol=1e-4,
100
+ lag=100,
101
+ learning_rate=0.01,
102
+ progressbar=True,
103
+ **kwargs):
104
+ """Estimate per-voxel parameters by iterative optimization.
105
+
106
+ Parameters
107
+ ----------
108
+ noise_model : {'ssq', 'gaussian'}, default ``'ssq'``
109
+ Loss function. ``'ssq'`` minimizes the sum of squared residuals.
110
+ ``'gaussian'`` minimizes a per-voxel Gaussian negative
111
+ log-likelihood with a free σ²ᵥ per voxel, stored in
112
+ ``self.estimated_sigma2``. Both have the same per-voxel optimum
113
+ (without ``shared_pars``). From a good grid start they follow
114
+ nearly the same path, and ``'gaussian'`` costs about 25% more per
115
+ iteration. From a poor start it can get there in fewer iterations,
116
+ with equal or unequal noise across voxels.
117
+ fixed_pars, shared_pars : list[str] | None
118
+ Parameter names to hold at their init value (``fixed_pars``)
119
+ or to tie to a single shared value across voxels
120
+ (``shared_pars``).
121
+ r2_atol, lag, min_n_iterations : float, int, int
122
+ Early-stop: stop when mean R² has improved by less than ``r2_atol``
123
+ over the last ``lag`` steps, after ``min_n_iterations``. Use a
124
+ smaller ``r2_atol`` (the default was 1e-6 before 0.7) when you
125
+ need a fully converged fit.
126
+ **kwargs
127
+ Forwarded to ``keras.optimizers.Adam`` when ``optimizer is
128
+ None``.
129
+
130
+ Returns
131
+ -------
132
+ pd.DataFrame
133
+ Per-voxel parameter estimates, indexed by voxel. Voxels that
134
+ contain any NaN or have zero variance cannot be fitted: they get
135
+ a warning, and NaN in both the parameters and ``self.r2``.
136
+ """
137
+ if noise_model not in _VALID_NOISE_MODELS:
138
+ raise ValueError(
139
+ f"noise_model must be one of {_VALID_NOISE_MODELS}, "
140
+ f"got {noise_model!r}")
141
+
142
+ n_voxels, n_pars = self.data.shape[1], len(self.model.parameter_labels)
143
+ n_timepoints = self.data.shape[0]
144
+
145
+ y = ops.convert_to_tensor(self.data.values, dtype='float32')
146
+ ssq_data = ops.sum((y - ops.mean(y, axis=0)[None, :]) ** 2, axis=0)
147
+ meaningful_ts = ops.convert_to_numpy(ssq_data > 0.0)
148
+ meaningful_ixs = np.where(meaningful_ts)[0]
149
+ n_masked = int((~meaningful_ts).sum())
150
+ if n_masked:
151
+ warnings.warn(
152
+ f'{n_masked} of {n_voxels} voxels contain NaN or have zero variance '
153
+ 'and cannot be fitted. Their parameters and R² will be NaN; '
154
+ 'drop them first to save compute.', RuntimeWarning, stacklevel=2)
155
+ # Masked voxels must not reach the loss: a NaN would poison any
156
+ # shared parameter through its gradient.
157
+ meaningful_t = ops.convert_to_tensor(meaningful_ts)
158
+ y_fit = ops.where(meaningful_t[None, :], y, ops.zeros_like(y))
159
+ meaningful_f = ops.cast(meaningful_t, 'float32')
160
+
161
+ # ---- init parameters in unconstrained space ----------------
162
+ if init_pars is None:
163
+ init_pars = self.model.get_init_pars(
164
+ data=y, paradigm=self.paradigm, confounds=confounds)
165
+ logger.info('Using model.get_init_pars (no init_pars given).')
166
+ init_pars = self.model._get_parameters(init_pars)
167
+ init_pars = ops.convert_to_numpy(
168
+ self.model._transform_parameters_backward(
169
+ init_pars.values.astype(np.float32)))
170
+ # The result of an earlier fit has NaN for masked voxels.
171
+ init_pars = init_pars.copy()
172
+ init_pars[~meaningful_ts] = 0.0
173
+ init_pars_t = ops.convert_to_tensor(init_pars)
174
+
175
+ # ---- which parameters are trainable, shared, fixed ----------
176
+ parameter_ix, shared_parameter_ixs, voxel_specific_ixs = \
177
+ self._resolve_param_partition(n_pars, fixed_pars, shared_pars)
178
+ voxel_mask, shared_mask = self._build_masks(
179
+ n_voxels, n_pars, meaningful_ixs, voxel_specific_ixs,
180
+ shared_parameter_ixs)
181
+
182
+ # ---- trainable Variables -----------------------------------
183
+ trainable_params = keras.Variable(
184
+ init_pars.copy(), name='parameters', dtype='float32')
185
+ trainable_variables = [trainable_params]
186
+
187
+ if shared_pars is not None:
188
+ init_shared = np.mean(init_pars[:, shared_parameter_ixs], axis=0)
189
+ trainable_shared = keras.Variable(
190
+ init_shared, name='shared_parameters', dtype='float32')
191
+ trainable_variables.append(trainable_shared)
192
+ selector_t = ops.convert_to_tensor(
193
+ self._selector_matrix(n_pars, shared_parameter_ixs))
194
+ else:
195
+ trainable_shared = None
196
+ selector_t = None
197
+
198
+ # Per-voxel log σ²ᵥ for Gaussian noise model.
199
+ # Initialized from initial residuals; clamped to >= 1e-4 to
200
+ # avoid log(0). Stored on softplus-inverse scale so the live
201
+ # σ²ᵥ = softplus(log_sigma2) is positive automatically.
202
+ if noise_model == 'gaussian':
203
+ with_init_pred = self.model._predict(
204
+ ops.convert_to_tensor(self.paradigm.values, dtype='float32')[None, ...],
205
+ self.model._transform_parameters_forward(init_pars_t)[None, ...],
206
+ None)[0]
207
+ init_resid = y_fit - with_init_pred
208
+ init_sigma2 = ops.convert_to_numpy(
209
+ ops.mean(init_resid ** 2, axis=0))
210
+ # NaN columns (all-NaN voxels, or model predictions that
211
+ # returned NaN at init) would propagate through
212
+ # ``np.maximum(NaN, 1e-4) -> NaN`` and poison the optimizer
213
+ # state for every voxel via Adam's shared moments. Replace
214
+ # with 1.0 (a benign value; the voxel is masked out of the
215
+ # loss anyway via ``meaningful_mask``).
216
+ init_sigma2 = np.nan_to_num(init_sigma2, nan=1.0)
217
+ init_sigma2 = np.maximum(init_sigma2, 1e-4).astype(np.float32)
218
+ log_sigma2 = keras.Variable(
219
+ ops.convert_to_numpy(softplus_inverse(
220
+ ops.convert_to_tensor(init_sigma2, dtype='float32'))),
221
+ name='log_sigma2', dtype='float32')
222
+ trainable_variables.append(log_sigma2)
223
+ else:
224
+ log_sigma2 = None
225
+
226
+ # ---- closures used inside the optimization loop -------------
227
+ paradigm_clean = self.model.stimulus._clean_paradigm(self.paradigm)
228
+ build_parameters = self._make_parameter_assembler(
229
+ init_pars_t, voxel_mask, shared_mask,
230
+ trainable_params, trainable_shared, selector_t, n_voxels)
231
+
232
+ def get_ssq(parameters):
233
+ predictions = self.model._predict(
234
+ paradigm_clean[None, ...], parameters[None, ...], None)
235
+ return ops.sum((y_fit - predictions[0]) ** 2, axis=0) * meaningful_f
236
+
237
+ # ---- optimizer ---------------------------------------------
238
+ if optimizer is None:
239
+ opt = keras.optimizers.Adam(learning_rate=learning_rate, **kwargs)
240
+ else:
241
+ opt = optimizer
242
+
243
+ # ---- loss --------------------------------------------------
244
+ # Both losses have the same per-voxel optimum. Adam is invariant to
245
+ # a constant per-voxel scale, so the paths only differ because σ²
246
+ # changes during the fit.
247
+ if noise_model == 'ssq':
248
+ def loss_fn():
249
+ pars = build_parameters()
250
+ native = self.model._transform_parameters_forward(pars)
251
+ return ops.sum(get_ssq(native))
252
+ else: # 'gaussian'
253
+ _LOG_2PI = float(np.log(2.0 * np.pi))
254
+ meaningful_mask = meaningful_f
255
+ n_t_f = ops.cast(n_timepoints, 'float32')
256
+
257
+ def loss_fn():
258
+ pars = build_parameters()
259
+ native = self.model._transform_parameters_forward(pars)
260
+ ssq = get_ssq(native)
261
+ sigma2 = ops.softplus(log_sigma2) + _SIGMA2_EPS
262
+ nll = 0.5 * (n_t_f * (_LOG_2PI + ops.log(sigma2))
263
+ + ssq / sigma2)
264
+ return ops.sum(nll * meaningful_mask)
265
+
266
+ # ---- main loop ---------------------------------------------
267
+ pbar = range(max_n_iterations)
268
+ if progressbar:
269
+ pbar = tqdm(pbar)
270
+
271
+ best_r2 = ops.ones(y.shape[1]) * float('-inf')
272
+ best_parameters = ops.zeros(init_pars.shape)
273
+ intermediate_parameters = [] if store_intermediate_parameters else None
274
+ mean_best_r2s = []
275
+ loss_history = []
276
+
277
+ # Regression models (RegressionGaussianPRF and friends) have TUPLE parameter
278
+ # labels -- (parameter, regressor) -- so a bare str.join raises
279
+ # "TypeError: sequence item 0: expected str instance, tuple found". These are
280
+ # logging arguments, evaluated eagerly regardless of log level, so the crash
281
+ # fires on every fit that passes `fixed_pars`. `fixed_pars` itself is a list of
282
+ # tuples for the same reason.
283
+ labels = self.model.parameter_labels
284
+ logger.info('Fitting: %s',
285
+ ', '.join(str(labels[ix]) for ix in parameter_ix))
286
+ if fixed_pars:
287
+ logger.info('Fixed: %s', ', '.join(str(p) for p in fixed_pars))
288
+ if shared_parameter_ixs:
289
+ logger.info('Shared: %s',
290
+ ', '.join(str(labels[ix]) for ix in shared_parameter_ixs))
291
+
292
+ for step in pbar:
293
+ loss, gradients = compute_gradients(loss_fn, trainable_variables)
294
+ loss_history.append(float(ops.convert_to_numpy(loss)))
295
+
296
+ # Re-compute outside the gradient tape for tracking. Torch has no
297
+ # tape: without stop_gradient this forward pass builds a graph that
298
+ # best_r2 and best_parameters keep alive, so voxels x pixels
299
+ # tensors pile up at every iteration.
300
+ pars = ops.stop_gradient(build_parameters())
301
+ untransformed = self.model._transform_parameters_forward(pars)
302
+ ssq = get_ssq(untransformed)
303
+ r2 = ops.where(meaningful_t, 1 - ssq / ssq_data,
304
+ ops.full_like(ssq, float('nan')))
305
+
306
+ # When no parameter is shared, track the best per-voxel
307
+ # state seen so far. With shared params the "best" needs
308
+ # to be defined jointly (the shared par changes for every
309
+ # voxel simultaneously), so just take the current state.
310
+ if shared_pars is None:
311
+ improved = r2 > best_r2
312
+ best_parameters = ops.where(
313
+ improved[:, None], untransformed, best_parameters)
314
+ best_r2 = ops.where(improved, r2, best_r2)
315
+ else:
316
+ best_parameters = untransformed
317
+ best_r2 = r2
318
+
319
+ mean_current_r2 = float(ops.convert_to_numpy(
320
+ r2[meaningful_ts]).mean())
321
+ mean_best_r2 = float(ops.convert_to_numpy(
322
+ best_r2[meaningful_ts]).mean())
323
+
324
+ # Early-stop on R²-plateau.
325
+ if step >= min_n_iterations:
326
+ r2_diff = mean_best_r2 - mean_best_r2s[
327
+ max(step - lag, 0)]
328
+ if 0.0 <= r2_diff < r2_atol:
329
+ if progressbar:
330
+ pbar.close()
331
+ break
332
+
333
+ mean_best_r2s.append(mean_best_r2)
334
+ opt.apply_gradients(zip(gradients, trainable_variables))
335
+
336
+ if progressbar:
337
+ pbar.set_description(
338
+ f'Current R2: {mean_current_r2:0.5f}/'
339
+ f'Best R2: {mean_best_r2:0.5f}')
340
+
341
+ if store_intermediate_parameters:
342
+ p = ops.convert_to_numpy(untransformed).T
343
+ intermediate_parameters.append(np.concatenate(
344
+ (np.reshape(p, np.prod(p.shape)),
345
+ ops.convert_to_numpy(r2)), 0))
346
+
347
+ # ---- assemble outputs --------------------------------------
348
+ # Per-iteration mean-best-R² trajectory (length = #steps actually
349
+ # taken; this can be shorter than ``max_n_iterations`` if the
350
+ # early-stop fired). Useful for diagnosing whether the
351
+ # ``r2_atol`` / ``lag`` defaults are stopping too soon or too
352
+ # late on a given dataset.
353
+ self.r2_history_ = np.asarray(mean_best_r2s, dtype=np.float64)
354
+ # Per-iteration loss (the actual minimization objective; same
355
+ # length as r2_history_). For ``noise_model='ssq'`` this is
356
+ # the total SSQ across voxels; for ``'gaussian'`` it is the
357
+ # total negative log-likelihood. Useful for cross-method
358
+ # convergence comparisons.
359
+ self.loss_history_ = np.asarray(loss_history, dtype=np.float64)
360
+
361
+ best_parameters = np.array(ops.convert_to_numpy(best_parameters))
362
+ best_parameters[~meaningful_ts] = np.nan
363
+ self.estimated_parameters = format_parameters(
364
+ best_parameters, self.model.parameter_labels)
365
+ self.estimated_parameters.index = self.data.columns
366
+ if not self.estimated_parameters.index.name:
367
+ self.estimated_parameters.index.name = 'source'
368
+
369
+ if noise_model == 'gaussian':
370
+ self.estimated_sigma2 = pd.Series(
371
+ ops.convert_to_numpy(ops.softplus(log_sigma2)),
372
+ index=self.data.columns, name='sigma2')
373
+ else:
374
+ self.estimated_sigma2 = None
375
+
376
+ if store_intermediate_parameters:
377
+ columns = pd.MultiIndex.from_product(
378
+ [self.model.parameter_labels + ['r2'], np.arange(n_voxels)],
379
+ names=['parameter', 'voxel'])
380
+ self.intermediate_parameters = pd.DataFrame(
381
+ intermediate_parameters, columns=columns,
382
+ index=pd.Index(np.arange(len(intermediate_parameters)),
383
+ name='step'))
384
+
385
+ self.predictions = self.model.predict(
386
+ self.paradigm, self.estimated_parameters)
387
+ best_r2 = np.array(ops.convert_to_numpy(best_r2))
388
+ best_r2[~meaningful_ts] = np.nan
389
+ self.r2 = pd.Series(best_r2, index=self.data.columns)
390
+
391
+ return self.estimated_parameters
392
+
393
+ # ------------------------------------------------------------ helpers
394
+ def _resolve_param_partition(self, n_pars, fixed_pars, shared_pars):
395
+ """Validate fixed/shared kwargs; return (trainable, shared, voxel-specific) indices."""
396
+ labels = self.model.parameter_labels
397
+ if fixed_pars is None:
398
+ parameter_ix = list(range(n_pars))
399
+ else:
400
+ for p in fixed_pars:
401
+ if p not in labels:
402
+ raise ValueError(
403
+ f'Fixed parameter "{p}" not in model parameters: {labels}')
404
+ parameter_ix = [ix for ix, lbl in enumerate(labels)
405
+ if lbl not in fixed_pars]
406
+
407
+ if shared_pars is None:
408
+ shared_parameter_ixs = []
409
+ voxel_specific_ixs = parameter_ix
410
+ else:
411
+ for p in shared_pars:
412
+ if p not in labels:
413
+ raise ValueError(
414
+ f'Shared parameter "{p}" not in model parameters: {labels}')
415
+ shared_parameter_ixs = [ix for ix, lbl in enumerate(labels)
416
+ if lbl in shared_pars]
417
+ voxel_specific_ixs = [ix for ix in parameter_ix
418
+ if ix not in shared_parameter_ixs]
419
+ return parameter_ix, shared_parameter_ixs, voxel_specific_ixs
420
+
421
+ @staticmethod
422
+ def _build_masks(n_voxels, n_pars, meaningful_ixs,
423
+ voxel_specific_ixs, shared_parameter_ixs):
424
+ """``(n_voxels, n_pars)`` boolean masks for voxel-specific +
425
+ shared trainable positions. Voxels with zero-variance data
426
+ contribute neither (their gradients are masked out)."""
427
+ voxel_mask = np.zeros((n_voxels, n_pars), dtype=np.float32)
428
+ if len(voxel_specific_ixs):
429
+ voxel_mask[np.ix_(meaningful_ixs, voxel_specific_ixs)] = 1.0
430
+ voxel_mask = ops.convert_to_tensor(voxel_mask)
431
+
432
+ if shared_parameter_ixs:
433
+ shared_mask = np.zeros((n_voxels, n_pars), dtype=np.float32)
434
+ shared_mask[:, shared_parameter_ixs] = 1.0
435
+ shared_mask = ops.convert_to_tensor(shared_mask)
436
+ else:
437
+ shared_mask = None
438
+ return voxel_mask, shared_mask
439
+
440
+ @staticmethod
441
+ def _selector_matrix(n_pars, shared_parameter_ixs):
442
+ """``(n_pars, n_shared)`` selector that scatters a length-
443
+ ``n_shared`` vector back to the right columns of an
444
+ ``(n_voxels, n_pars)`` array."""
445
+ s = np.zeros((n_pars, len(shared_parameter_ixs)), dtype=np.float32)
446
+ for j, pi in enumerate(shared_parameter_ixs):
447
+ s[pi, j] = 1.0
448
+ return s
449
+
450
+ @staticmethod
451
+ def _make_parameter_assembler(init_pars_t, voxel_mask, shared_mask,
452
+ trainable_params, trainable_shared,
453
+ selector_t, n_voxels):
454
+ """Return a closure that assembles the live ``(n_voxels, n_pars)``
455
+ parameter tensor from the trainable Variables + init values."""
456
+ if trainable_shared is None:
457
+ def build():
458
+ return (init_pars_t * (1.0 - voxel_mask)
459
+ + trainable_params * voxel_mask)
460
+ else:
461
+ def build():
462
+ proj = ops.matmul(
463
+ ops.reshape(trainable_shared, (1, -1)),
464
+ ops.transpose(selector_t)) # (1, n_pars)
465
+ shared_expanded = ops.tile(proj, [n_voxels, 1])
466
+ return (init_pars_t * (1.0 - voxel_mask - shared_mask)
467
+ + trainable_params * voxel_mask
468
+ + shared_expanded * shared_mask)
469
+ return build
470
+
471
+ # ------------------------------------------------------------ grid fit
472
+ def fit_grid(self, *args, fixed_pars=None,
473
+ use_correlation_cost=False,
474
+ positive_amplitude=True, **kwargs):
475
+ n_timepoints, n_voxels = self.data.shape
476
+ chunk_size = self.memory_limit / n_voxels / n_timepoints
477
+ # ``max(1, ...)`` guards against the case where the grid data
478
+ # is larger than ``memory_limit`` (e.g., full-cortex run with
479
+ # many TRs) and ``int(...)`` would otherwise drop to 0, causing
480
+ # a ZeroDivisionError below at ``len(par_grid) // chunk_size``.
481
+ chunk_size = max(1, int(kwargs.pop('chunk_size', chunk_size)))
482
+ logger.info('Working with chunk size of %d', chunk_size)
483
+
484
+ if fixed_pars is not None:
485
+ raise NotImplementedError(
486
+ 'fit_grid does not yet support fixed_pars; use fit() '
487
+ 'with fixed_pars=... after a refine step.')
488
+
489
+ if len(args) == len(self.model.parameter_labels):
490
+ kwargs = dict(zip(self.model.parameter_labels, args))
491
+
492
+ if set(kwargs.keys()) != set(self.model.parameter_labels):
493
+ raise ValueError(
494
+ f'Please provide parameter ranges for all of: '
495
+ f'{self.model.parameter_labels}')
496
+
497
+ def _create_grid(*grid_args):
498
+ return pd.MultiIndex.from_product(
499
+ grid_args,
500
+ names=self.model.parameter_labels).to_frame(index=False)
501
+
502
+ grid_args = [kwargs[k] for k in self.model.parameter_labels]
503
+ par_grid = _create_grid(*grid_args).astype(np.float32)
504
+ par_grid = par_grid.set_index(
505
+ pd.Index(par_grid.index // chunk_size, name='chunk'), append=True)
506
+
507
+ n_chunks = ((len(par_grid) - 1) // chunk_size) + 1
508
+ n_pars = par_grid.shape[1]
509
+ n_features = self.data.shape[1]
510
+ logging.info(f'Built grid of {len(par_grid)} parameter settings...')
511
+
512
+ data = ops.convert_to_tensor(self.data.values, dtype='float32')
513
+ paradigm_ = self.paradigm.values
514
+
515
+ if use_correlation_cost:
516
+ logger.info('Using correlation cost for grid fit.')
517
+ data_demeaned = data - ops.mean(data, axis=0, keepdims=True)
518
+ ssq_data = ops.sum(data_demeaned ** 2, axis=0, keepdims=True)
519
+
520
+ def _cost(pg):
521
+ pred = self.model._predict(paradigm_[None, ...],
522
+ pg[None, ...], None)
523
+ gp_dm = pred[0] - ops.mean(pred[0], axis=0, keepdims=True)
524
+ ssq_pred = ops.sum(gp_dm ** 2, axis=0, keepdims=True)
525
+ r = (ops.sum(gp_dm[:, None, :] * data_demeaned[:, :, None],
526
+ axis=0, keepdims=True)
527
+ / ops.sqrt(ssq_pred[:, None, :] * ssq_data[:, :, None]))
528
+ r = r[0]
529
+ if positive_amplitude:
530
+ r = ops.where(ops.isfinite(r), r, ops.ones_like(r) * -1)
531
+ else:
532
+ r = ops.where(ops.isfinite(r), r, ops.zeros_like(r))
533
+ r = r ** 2
534
+ return -r, ops.argmax(r, axis=1)
535
+ else:
536
+ def _cost(pg):
537
+ pred = self.model._predict(paradigm_[None, ...],
538
+ pg[None, ...], None)
539
+ ssq = ops.sum(
540
+ (pred[0, :, None, :] - data[:, :, None]) ** 2, axis=0)
541
+ return ssq, ops.argmin(ssq, axis=1)
542
+
543
+ best_pars = np.zeros((n_features, n_chunks, n_pars))
544
+ best_cost = np.zeros((n_features, n_chunks))
545
+ vox_ix = np.arange(n_features)
546
+
547
+ for chunk, pg in tqdm(par_grid.groupby('chunk')):
548
+ cost_, best_ix = _cost(pg.values)
549
+ cost_np = ops.convert_to_numpy(cost_)
550
+ best_ix_np = ops.convert_to_numpy(best_ix)
551
+ best_cost[:, chunk] = cost_np[vox_ix, best_ix_np]
552
+ best_pars[:, chunk] = np.array(pg.values)[best_ix_np]
553
+
554
+ best_chunks = ops.convert_to_numpy(
555
+ ops.argmin(ops.convert_to_tensor(best_cost, dtype='float32'),
556
+ axis=1))
557
+ best_pars = best_pars[vox_ix, best_chunks]
558
+
559
+ out = pd.DataFrame(best_pars, index=self.data.columns,
560
+ columns=self.model.parameter_labels
561
+ ).astype(np.float32)
562
+ if not out.index.name:
563
+ out.index.name = 'source'
564
+ return out
565
+
566
+ # ------------------------------------------------------------ refine
567
+ def refine_baseline_and_amplitude(self, parameters, n_iterations=1,
568
+ positive_amplitude=True,
569
+ l2_alpha=1e-3):
570
+ data = self.data
571
+ predictions = self.model.predict(parameters=parameters,
572
+ paradigm=self.paradigm)
573
+ parameters = parameters.copy()
574
+
575
+ if isinstance(parameters.columns, pd.MultiIndex):
576
+ amplitude_ix = ('amplitude_unbounded', 'Intercept')
577
+ baseline_ix = ('baseline_unbounded', 'Intercept')
578
+ if (amplitude_ix not in parameters.columns
579
+ or baseline_ix not in parameters.columns):
580
+ raise ValueError(
581
+ 'refine_baseline_and_amplitude needs both '
582
+ f'{amplitude_ix} and {baseline_ix} in the parameter '
583
+ 'DataFrame; got columns: '
584
+ f'{list(parameters.columns)}')
585
+ else:
586
+ if ('baseline' not in parameters.columns
587
+ or 'amplitude' not in parameters.columns):
588
+ raise ValueError(
589
+ "refine_baseline_and_amplitude needs both "
590
+ "'baseline' and 'amplitude' columns; got: "
591
+ f"{list(parameters.columns)}")
592
+ amplitude_ix = 'amplitude'
593
+ baseline_ix = 'baseline'
594
+
595
+ if (parameters[amplitude_ix] == 0).any():
596
+ raise ValueError(
597
+ 'refine_baseline_and_amplitude needs nonzero amplitudes to recover '
598
+ 'the shape of the prediction. Use a nonzero placeholder in the '
599
+ 'grid, e.g. amplitude=[1.].')
600
+
601
+ orig_r2 = get_rsq(data, predictions)
602
+ demeaned = ((predictions - parameters.loc[:, baseline_ix].T)
603
+ / parameters.loc[:, amplitude_ix])
604
+
605
+ X = np.stack((np.ones((predictions.shape[1], predictions.shape[0])),
606
+ demeaned.values.T[:, :]), 2).astype(np.float32)
607
+ Y = data.T.values[..., np.newaxis].astype(np.float32)
608
+
609
+ Xt = ops.transpose(ops.convert_to_tensor(X), (0, 2, 1))
610
+ X_t = ops.convert_to_tensor(X)
611
+ Y_t = ops.convert_to_tensor(Y)
612
+ XtX = ops.matmul(Xt, X_t)
613
+ XtY = ops.matmul(Xt, Y_t)
614
+ reg = l2_alpha * ops.eye(2)[None, :, :]
615
+ beta = ops.convert_to_numpy(ops.solve(XtX + reg, XtY))[..., 0]
616
+
617
+ new_parameters = parameters.copy().astype(np.float32)
618
+ new_parameters.loc[:, baseline_ix] = beta[:, 0]
619
+ new_parameters.loc[:, amplitude_ix] = beta[:, 1]
620
+ if positive_amplitude:
621
+ new_parameters[amplitude_ix] = np.clip(
622
+ new_parameters[amplitude_ix], 1e-4, np.inf)
623
+
624
+ new_pred = self.model.predict(parameters=new_parameters,
625
+ paradigm=self.paradigm)
626
+ new_r2 = get_rsq(data, new_pred)
627
+ ix = (new_r2 > orig_r2) & (data.std() != 0.0)
628
+ parameters.update(new_parameters.loc[ix].astype(np.float32))
629
+
630
+ if n_iterations == 1:
631
+ return parameters
632
+ return self.refine_baseline_and_amplitude(
633
+ parameters, n_iterations - 1,
634
+ positive_amplitude=positive_amplitude, l2_alpha=l2_alpha)
635
+
636
+ # ------------------------------------------------------------ misc API
637
+ def get_predictions(self, parameters=None):
638
+ if parameters is None:
639
+ parameters = self.estimated_parameters
640
+ return self.model.predict(self.paradigm, parameters, None)
641
+
642
+ def get_residuals(self, parameters=None):
643
+ if parameters is None:
644
+ parameters = self.estimated_parameters
645
+ return self.data - self.get_predictions(parameters).values
646
+
647
+ def get_rsq(self, parameters=None):
648
+ if parameters is None:
649
+ parameters = self.estimated_parameters
650
+ return get_rsq(self.data, self.get_predictions(parameters))
651
+
652
+ @property
653
+ def data(self):
654
+ return self._data
655
+
656
+ @data.setter
657
+ def data(self, data):
658
+ self._data = None if data is None else format_data(data)
659
+
660
+ @property
661
+ def paradigm(self):
662
+ return self._paradigm
663
+
664
+ @paradigm.setter
665
+ def paradigm(self, paradigm):
666
+ self._paradigm = format_paradigm(paradigm)