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,563 @@
1
+ import warnings
2
+
3
+ import numpy as np
4
+ import keras
5
+ from keras import ops
6
+ from tqdm.auto import tqdm
7
+ from ..utils import format_data, format_paradigm, logit
8
+ from ..utils.backend import softplus_inverse, mvn_log_prob, mvt_log_prob, compute_gradients, safe_cholesky, strict_cholesky
9
+ from .gp_prior import mds_embed_distances
10
+
11
+ # Exceptions that indicate a bug in the likelihood / model code rather
12
+ # than numerical divergence. Re-raised immediately by ResidualFitter.fit:
13
+ # lowering the learning rate cannot fix them. TypeError covers JAX's
14
+ # TracerArrayConversionError and ConcretizationTypeError (both subclass
15
+ # jax.errors.JAXTypeError -> TypeError), i.e. host conversions such as
16
+ # ``float(ops.convert_to_numpy(x))`` inside traced code.
17
+ _PROGRAMMING_ERRORS = (TypeError, AttributeError, NameError, ImportError,
18
+ NotImplementedError, KeyError, IndexError)
19
+
20
+
21
+ class ResidualFitter(object):
22
+ """Fit a parametric noise covariance Ω (and Student-t ν) to residuals.
23
+
24
+ Ω = ρ ττᵀ + (1 − ρ) diag(τ²) + σ² WWᵀ (optionally mixed with the sample
25
+ covariance via ``lambd``).
26
+
27
+ With a pairwise distance matrix ``D`` passed to :meth:`fit`, the shared
28
+ factor becomes distance-dependent:
29
+
30
+ Ω = ρ [α (e^{−β D̃} ∘ ττᵀ) + (1 − α) ττᵀ] + (1 − ρ) diag(τ²) + σ² WWᵀ
31
+
32
+ with α ∈ (0, 1), β > 0 and D̃ the classical-MDS Euclidean embedding of
33
+ ``D`` (see :func:`braincoder.optimize.gp_prior.mds_embed_distances`). It
34
+ nests the model above at α = 0 and at β = 0. Each term is positive
35
+ semi-definite for every parameter value: e^{−β D̃} because D̃ is Euclidean
36
+ (Schoenberg 1938), its Hadamard product with ττᵀ by the Schur product
37
+ theorem, and WWᵀ as a Gram matrix. With ρ < 1 and τ > 0 the diagonal term
38
+ makes Ω positive definite, also when voxels share a location (D̃ = 0).
39
+
40
+ .. warning::
41
+ Ω has a single shared factor. On real single-trial fMRI betas the
42
+ residuals typically need tens of factors, and this Ω underestimates
43
+ held-out noise (held-out Mahalanobis distances ~4× too large on 7T
44
+ data), giving overconfident decoding posteriors. ``lambd > 0`` is
45
+ unsafe when n_voxels > n_trials (rank-deficient sample covariance).
46
+ The pseudo-WWᵀ from ``get_pseudoWWT`` is uncentred. For calibrated
47
+ decoding see :class:`braincoder.noise.LowRankNoise` and the
48
+ "Noise models for decoding" docs page.
49
+ """
50
+
51
+ def __init__(self, model, data, paradigm=None, parameters=None, weights=None, lambd=0.0):
52
+
53
+ self.model = model
54
+ self.data = format_data(data)
55
+ self.lambd = lambd
56
+
57
+ self.paradigm = self.model.get_paradigm(paradigm)
58
+ self.parameters = parameters
59
+ self.weights = weights
60
+
61
+ def fit(self, init_rho=.1, init_tau=None, init_dof=1., init_sigma2=1e-3, D=None, max_n_iterations=1000,
62
+ resid_dist='gauss',
63
+ min_n_iterations=100,
64
+ method='gauss',
65
+ residuals=None,
66
+ normalize_WWT=True,
67
+ use_wwt=True,
68
+ learning_rate=0.02, rtol=1e-6, lag=100,
69
+ init_alpha=0.99,
70
+ init_beta=None,
71
+ spherical=False,
72
+ progressbar=True,
73
+ max_consecutive_failures=50,
74
+ stimulus_range=None,
75
+ WWT=None,
76
+ psd_correction='mds',
77
+ cholesky=None):
78
+ """``use_wwt`` (default True): include the ``σ² · WᵀW`` term in
79
+ Ω. When False, Ω is built without the tuning-similarity
80
+ contribution — useful for testing whether ``WᵀW`` is doing
81
+ real spatial-noise modeling or just creating
82
+ signal-correlation structure that interacts with regularized
83
+ encoding fits. ``σ²`` stays in the trainable set but has zero
84
+ effect on Ω (gradient → 0; Adam leaves it inert).
85
+
86
+ The ``WWT`` term comes from, in order: the ``WWT`` argument; the
87
+ ``weights`` of the fitter; or the model's pseudo-WWT, which needs
88
+ ``stimulus_range`` for models that are not image-based.
89
+
90
+ Failure handling: a step whose cost or gradients are non-finite,
91
+ or which raises a numerical error (e.g. a Cholesky failure), is
92
+ rolled back to the best values so far and the learning rate is
93
+ reduced by 10%. ``max_consecutive_failures`` (default 50) such
94
+ steps in a row raise ``RuntimeError``. Programming errors
95
+ (``TypeError`` -- including JAX tracer-conversion errors --
96
+ ``AttributeError``, ``NameError``, ...) are re-raised
97
+ immediately. If no step ever produces a finite cost the fit
98
+ raises instead of returning an unfitted Ω. The number of
99
+ rolled-back steps is stored in ``self.n_failed_steps``.
100
+
101
+ Distance-dependent noise (``D``): ``D`` is an ``(n_voxels, n_voxels)``
102
+ symmetric, finite, non-negative distance matrix. β is constrained
103
+ positive with a softplus; α lies in (0, 1). ``init_beta`` must be
104
+ > 0 and defaults to ``1 / median(off-diagonal D̃)``.
105
+
106
+ ``psd_correction``: ``'mds'`` (default) replaces ``D`` by its
107
+ classical-MDS Euclidean embedding D̃ before the fit, which is what
108
+ makes Ω positive definite by construction. Exponential kernels on
109
+ raw graph or geodesic distances need not be PSD. ``'none'`` uses
110
+ ``D`` as given, only for distances you know are Euclidean. The
111
+ embedded matrix and its diagnostics are stored in
112
+ ``self.distance_matrix_embedded_`` and ``self.mds_info_``.
113
+
114
+ ``cholesky``: ``'strict'`` factorises Ω as it is, with no jitter, and
115
+ counts any numerical failure in ``n_failed_steps``. ``'safe'`` uses
116
+ :func:`~braincoder.utils.backend.safe_cholesky`, which adds adaptive
117
+ jitter to the diagonal. The default is ``'strict'`` with ``D`` and
118
+ ``'safe'`` without, so fits without ``D`` are unchanged. Pass
119
+ ``cholesky='strict'`` when comparing a fit without ``D`` with one
120
+ with ``D``, so that the kernel is the only difference. In strict mode
121
+ the smallest eigenvalue of the returned Ω (float64) is stored in
122
+ ``self.omega_min_eigenvalue_``.
123
+ """
124
+
125
+ if cholesky is None:
126
+ cholesky = 'strict' if D is not None else 'safe'
127
+ if cholesky not in ('strict', 'safe'):
128
+ raise ValueError(f"cholesky must be 'strict' or 'safe', got {cholesky!r}")
129
+ factorise = strict_cholesky if cholesky == 'strict' else safe_cholesky
130
+
131
+ n_voxels = self.data.shape[1]
132
+ if n_voxels == 0:
133
+ raise ValueError('ResidualFitter: data has no voxels; a noise model '
134
+ 'cannot be fitted to an empty selection.')
135
+
136
+ if n_voxels == 0:
137
+ raise ValueError('ResidualFitter: data contains 0 voxels — '
138
+ 'cannot fit a noise model')
139
+
140
+ if D is not None and self.lambd > 0.0:
141
+ # get_omega() below checks self.lambd>0 first and returns
142
+ # _get_omega_lambda(...) without ever touching D/alpha/beta --
143
+ # confirmed empirically (alpha/beta sit frozen at their init
144
+ # values across the whole fit, "Gradients do not exist for
145
+ # variables ['alpha_trans', 'beta']" UserWarning). A caller
146
+ # passing both would silently get a non-geodesic Omega while
147
+ # believing they'd requested the geodesic-distance structure.
148
+ # Loud failure here beats a mislabeled result downstream.
149
+ raise ValueError(
150
+ 'ResidualFitter.fit(): D (geodesic distance) and '
151
+ 'lambd > 0 (shrinkage toward the sample covariance) are '
152
+ 'not composable in this implementation -- lambd > 0 '
153
+ 'silently overrides the distance-structured Omega and '
154
+ 'never uses D/alpha/beta. Pass lambd=0 when fitting with '
155
+ 'D, or drop D if you want lambd-shrinkage instead.')
156
+
157
+ if residuals is None:
158
+ predictions = self.model.predict(self.paradigm, self.parameters, self.weights)
159
+ if len(predictions) != len(self.data):
160
+ raise ValueError(f'paradigm has {len(predictions)} rows but data '
161
+ f'has {len(self.data)}.')
162
+ if not predictions.columns.equals(self.data.columns):
163
+ if set(predictions.columns) != set(self.data.columns):
164
+ raise ValueError(
165
+ 'The voxels of the model and of the data differ: pass '
166
+ 'parameters and weights for exactly the columns of data.')
167
+ predictions = predictions[self.data.columns]
168
+ # By position, like the fitters: labels may differ between the
169
+ # index of the data and the index of the paradigm.
170
+ residuals = self.data.values - predictions.values
171
+
172
+ if not np.isfinite(residuals).all():
173
+ raise ValueError(
174
+ f'ResidualFitter: residuals of '
175
+ f'{int((~np.isfinite(residuals)).any(axis=0).sum())} of {n_voxels} '
176
+ 'voxels contain NaN or inf. Check the data and parameters of these '
177
+ 'voxels, and drop them before fitting the noise model.')
178
+
179
+ sample_cov = np.cov(residuals.T)
180
+
181
+ # ── λ=1 short-circuit ─────────────────────────────────────────────────
182
+ # When lambd≥1 the parametric component vanishes entirely (gradient=0),
183
+ # so running the full optimisation is wasteful and dof can drift to ∞.
184
+ # Instead: use the sample covariance directly (with adaptive jitter) and
185
+ # fit only dof via a short dedicated loop.
186
+ if self.lambd >= 1.0:
187
+ mean_var = float(np.mean(np.diag(sample_cov)))
188
+ omega = sample_cov + np.eye(n_voxels) * (mean_var * 1e-4 + 1e-9)
189
+ if method == 't':
190
+ omega_t = ops.convert_to_tensor(omega, dtype='float32')
191
+ omega_chol = ops.cholesky(omega_t)
192
+ residuals_t = ops.convert_to_tensor(residuals, dtype='float32')
193
+ dof_ = keras.Variable(softplus_inverse(init_dof), name='dof_trans', dtype='float32')
194
+ opt = keras.optimizers.Adam(learning_rate=learning_rate)
195
+ for _ in range(max_n_iterations):
196
+ def _dof_loss():
197
+ return -ops.sum(mvt_log_prob(residuals_t, omega_chol,
198
+ ops.softplus(dof_)))
199
+ _, grads = compute_gradients(_dof_loss, [dof_])
200
+ opt.apply_gradients(zip(grads, [dof_]))
201
+ dof = float(ops.convert_to_numpy(ops.softplus(dof_)))
202
+ return omega, dof
203
+ return omega, None
204
+
205
+ if init_tau is None:
206
+ init_tau = residuals.std(0)[np.newaxis, :].astype(np.float32)
207
+
208
+ tau_ = keras.Variable(softplus_inverse(init_tau),
209
+ name='tau_trans', dtype='float32')
210
+
211
+ if not spherical:
212
+ rho_ = keras.Variable(logit(init_rho),
213
+ name='rho_trans', dtype='float32')
214
+ sigma2_ = keras.Variable(softplus_inverse(init_sigma2),
215
+ name='sigma2_trans', dtype='float32')
216
+
217
+ if use_wwt:
218
+ if WWT is None:
219
+ if self.weights is not None:
220
+ WWT = self.model.get_WWT(self.weights)
221
+ else:
222
+ if stimulus_range is None and self.model.pseudo_wwt_needs_stimulus_range:
223
+ raise ValueError(
224
+ 'ResidualFitter needs a stimulus_range to build the pseudo-WWT from '
225
+ 'parameters: call fit(stimulus_range=...). Alternatively, pass WWT=..., '
226
+ 'pass weights to the fitter, or use use_wwt=False.')
227
+ WWT = self.model.get_pseudoWWT(stimulus_range, self.parameters)
228
+
229
+ import pandas as pd
230
+ if isinstance(WWT, (pd.DataFrame, pd.Series)):
231
+ WWT = WWT.values
232
+
233
+ WWT = ops.convert_to_tensor(WWT, dtype='float32')
234
+ WWT = ops.clip(WWT, -1e10, 1e10)
235
+ print(f'WWT max: {float(ops.convert_to_numpy(ops.max(WWT)))}')
236
+ if normalize_WWT:
237
+ WWT = WWT / ops.mean(WWT)
238
+ else:
239
+ # Strip the σ²·WᵀW term from Ω. sigma2_ stays trainable
240
+ # but multiplies a zero matrix, so it contributes
241
+ # nothing and Adam leaves it inert.
242
+ print('USE_WWT=False: omitting σ²·WᵀW term from Ω')
243
+ WWT = ops.zeros((n_voxels, n_voxels), dtype='float32')
244
+
245
+ trainable_variables = [tau_, rho_, sigma2_]
246
+ else:
247
+ trainable_variables = [tau_]
248
+
249
+ residuals_tensor = ops.convert_to_tensor(residuals, dtype='float32')
250
+
251
+ if D is None:
252
+
253
+ if spherical:
254
+
255
+ def transform_variables(variables):
256
+ return ops.softplus(variables[0])
257
+
258
+ def get_omega(variables):
259
+ tau = transform_variables(variables)
260
+ # reshape, not squeeze: with a single voxel tau has
261
+ # shape (1, 1) and squeeze collapses it to a 0-d
262
+ # scalar, which ops.diag rejects
263
+ return ops.diag(ops.reshape(tau**2, [-1]))
264
+
265
+ def get_pbar_description(cost, best_cost, variables):
266
+ tau = transform_variables(variables)
267
+ mean_tau = float(ops.convert_to_numpy(ops.mean(tau)))
268
+ return f'fit stat: {cost:0.4f} (best: {best_cost:0.4f}, mean tau: {mean_tau:0.4f}'
269
+
270
+ else:
271
+
272
+ def transform_variables(variables):
273
+ tau_ = variables[0]
274
+ rho_ = variables[1]
275
+ sigma2_= variables[2]
276
+ tau = ops.softplus(tau_)
277
+ rho = ops.sigmoid(rho_)
278
+ sigma2 = ops.softplus(sigma2_)
279
+ return tau, rho, sigma2
280
+
281
+ def get_omega(variables):
282
+ tau, rho, sigma2 = transform_variables(variables)
283
+ if self.lambd > 0.0:
284
+ return self._get_omega_lambda(tau, rho, sigma2, WWT,
285
+ self.lambd, sample_cov)
286
+ return self._get_omega(tau, rho, sigma2, WWT)
287
+
288
+ def get_pbar_description(cost, best_cost, variables):
289
+ tau, rho, sigma2 = transform_variables(variables)
290
+ mean_tau = float(ops.convert_to_numpy(ops.mean(tau)))
291
+ s = (f'fit stat: {cost:0.4f} (best: {best_cost:0.4f}, '
292
+ f'rho: {float(ops.convert_to_numpy(rho)):0.3f}, sigma2: {float(ops.convert_to_numpy(sigma2)):0.3f}, '
293
+ f'mean tau: {mean_tau:0.4f}')
294
+ if len(variables) == 4:
295
+ dof = float(ops.convert_to_numpy(ops.softplus(variables[3])))
296
+ s += f', dof: {dof:0.1f}'
297
+ return s
298
+
299
+ else:
300
+
301
+ if spherical:
302
+ raise ValueError('D cannot be combined with spherical=True: a '
303
+ 'diagonal Ω has no distance-dependent term.')
304
+ if self.lambd > 0.0:
305
+ raise ValueError('D cannot be combined with lambd > 0: the '
306
+ 'sample-covariance mixture ignores D.')
307
+ D = np.asarray(D, dtype=np.float64)
308
+ if D.shape != (n_voxels, n_voxels):
309
+ raise ValueError(f'D has shape {D.shape}, data has {n_voxels} voxels.')
310
+ if not np.allclose(D, D.T, atol=1e-5):
311
+ raise ValueError('D must be symmetric.')
312
+
313
+ if psd_correction == 'mds':
314
+ D_embedded, self.mds_info_ = mds_embed_distances(D, return_info=True)
315
+ elif psd_correction == 'none':
316
+ if not np.isfinite(D).all() or (D < 0).any():
317
+ raise ValueError('D must be finite and non-negative.')
318
+ D_embedded, self.mds_info_ = D.astype(np.float32), None
319
+ else:
320
+ raise ValueError("psd_correction must be 'mds' or 'none', "
321
+ f'got {psd_correction!r}')
322
+ self.distance_matrix_embedded_ = D_embedded
323
+
324
+ if init_beta is None:
325
+ off_diagonal = D_embedded[~np.eye(n_voxels, dtype=bool)]
326
+ positive = off_diagonal[off_diagonal > 0]
327
+ init_beta = 1.0 / float(np.median(positive)) if positive.size else 1.0
328
+ if not init_beta > 0:
329
+ raise ValueError(f'init_beta must be > 0 (beta is constrained '
330
+ f'positive), got {init_beta}. beta -> 0 is the '
331
+ 'model without D: fit without D for that.')
332
+ D = ops.convert_to_tensor(D_embedded, dtype='float32')
333
+
334
+ alpha_ = keras.Variable(logit(init_alpha),
335
+ name='alpha_trans', dtype='float32')
336
+ beta_ = keras.Variable(softplus_inverse(float(init_beta)),
337
+ name='beta_trans', dtype='float32')
338
+
339
+ trainable_variables += [alpha_, beta_]
340
+
341
+ def transform_variables(variables):
342
+ tau_, rho_, sigma2_, alpha_, beta_ = variables[:5]
343
+ tau = ops.softplus(tau_)
344
+ rho = ops.sigmoid(rho_)
345
+ sigma2 = ops.softplus(sigma2_)
346
+ alpha = ops.sigmoid(alpha_)
347
+ beta = ops.softplus(beta_)
348
+ return tau, rho, sigma2, alpha, beta
349
+
350
+ def get_omega(variables):
351
+ tau, rho, sigma2, alpha, beta = transform_variables(variables)
352
+ if self.lambd > 0.0:
353
+ return self._get_omega_lambda(tau, rho, sigma2, WWT,
354
+ self.lambd, sample_cov)
355
+ return self._get_omega_distance(tau, rho, sigma2, WWT, alpha, beta, D)
356
+
357
+ def get_pbar_description(cost, best_cost, variables):
358
+ tau, rho, sigma2, alpha, beta = transform_variables(variables)
359
+ mean_tau = float(ops.convert_to_numpy(ops.mean(tau)))
360
+ s = (f'fit stat: {cost:0.4f} (best: {best_cost:0.4f}, '
361
+ f'rho: {float(ops.convert_to_numpy(rho)):0.3f}, sigma2: {float(ops.convert_to_numpy(sigma2)):0.3f}, '
362
+ f'mean tau: {mean_tau:0.4f}, alpha: {float(ops.convert_to_numpy(alpha)):0.3f}, '
363
+ f'beta: {float(ops.convert_to_numpy(ops.convert_to_tensor(beta))):0.3f}')
364
+ if len(variables) == 6:
365
+ dof = float(ops.convert_to_numpy(ops.softplus(variables[5])))
366
+ s += f', dof: {dof:0.1f}'
367
+ return s
368
+
369
+ if method == 'gauss':
370
+ def likelihood(omega):
371
+ omega_chol = factorise(omega)
372
+ return ops.sum(mvn_log_prob(residuals_tensor, omega_chol))
373
+
374
+ fit_stat = likelihood
375
+
376
+ elif method == 't':
377
+
378
+ dof_ = keras.Variable(softplus_inverse(init_dof),
379
+ name='dof_trans', dtype='float32')
380
+ trainable_variables += [dof_]
381
+
382
+ def likelihood(omega):
383
+ omega_chol = factorise(omega)
384
+ dof = ops.softplus(trainable_variables[-1])
385
+ return ops.sum(mvt_log_prob(residuals_tensor, omega_chol, dof))
386
+
387
+ fit_stat = likelihood
388
+
389
+ elif method in ('ssq_cov', 'slogsq_cov'):
390
+ raise NotImplementedError()
391
+
392
+ opt = keras.optimizers.Adam(learning_rate=learning_rate)
393
+
394
+ pbar = range(max_n_iterations)
395
+ if progressbar:
396
+ pbar = tqdm(pbar)
397
+
398
+ self.costs = np.zeros(max_n_iterations)
399
+
400
+ def save_values(variables):
401
+ return [ops.convert_to_numpy(ops.convert_to_tensor(v)) for v in variables]
402
+
403
+ def restore_values(variables, saved):
404
+ for var, val in zip(variables, saved):
405
+ var.assign(val)
406
+
407
+ best_cost = np.inf
408
+ best_omega = None
409
+ best_values = save_values(trainable_variables)
410
+
411
+ # Bookkeeping for failed steps. A step "fails" when the cost or
412
+ # gradients are non-finite, or when a *numerical* exception is
413
+ # raised (e.g. safe_cholesky giving up, a backend Cholesky
414
+ # error). Those are treated as divergence: roll back to the best
415
+ # values, shrink the learning rate by 10%, retry. Programming
416
+ # errors (TypeError -- which includes JAX's
417
+ # TracerArrayConversionError / ConcretizationTypeError --
418
+ # AttributeError, NameError, ...) are re-raised immediately:
419
+ # backing off the learning rate cannot fix them, and swallowing
420
+ # them used to make a fit "complete" with Ω frozen at its
421
+ # initial value.
422
+ self.n_failed_steps = 0
423
+ consecutive_failures = 0
424
+ seen_failure_types = set()
425
+
426
+ def _register_failure(reason, exc=None):
427
+ nonlocal learning_rate, opt, consecutive_failures
428
+ self.n_failed_steps += 1
429
+ consecutive_failures += 1
430
+ key = type(exc).__name__ if exc is not None else reason
431
+ if key not in seen_failure_types:
432
+ seen_failure_types.add(key)
433
+ msg = (f'ResidualFitter step {step}: {reason}; restoring best '
434
+ f'values and reducing learning rate to '
435
+ f'{0.9 * learning_rate:.3g}.')
436
+ if exc is not None:
437
+ msg += f' Exception: {type(exc).__name__}: {exc}'
438
+ warnings.warn(msg, RuntimeWarning, stacklevel=3)
439
+ learning_rate = 0.9 * learning_rate
440
+ opt = keras.optimizers.Adam(learning_rate=learning_rate)
441
+ restore_values(trainable_variables, best_values)
442
+ if consecutive_failures >= max_consecutive_failures:
443
+ raise RuntimeError(
444
+ f'ResidualFitter: {consecutive_failures} consecutive '
445
+ f'failed optimisation steps (last: {reason}). '
446
+ f'Best cost so far: {best_cost}. Aborting rather than '
447
+ f'returning an unfitted Ω.') from exc
448
+
449
+ for step in pbar:
450
+ def loss_fn():
451
+ omega = get_omega(trainable_variables)
452
+ return -fit_stat(omega)
453
+
454
+ try:
455
+ cost_tensor, gradients = compute_gradients(loss_fn, trainable_variables)
456
+ cost = float(ops.convert_to_numpy(ops.convert_to_tensor(cost_tensor)))
457
+ grads_finite = all(
458
+ g is not None and
459
+ bool(np.all(np.isfinite(ops.convert_to_numpy(g))))
460
+ for g in gradients)
461
+ except _PROGRAMMING_ERRORS:
462
+ raise
463
+ except Exception as exc: # numerical failure -> back off
464
+ self.costs[step] = np.inf
465
+ cost = np.inf
466
+ _register_failure('exception during cost/gradient evaluation', exc)
467
+ else:
468
+ if not np.isfinite(cost) or not grads_finite:
469
+ # Do NOT apply the update: NaN gradients would poison
470
+ # the variables for every later step.
471
+ reason = ('non-finite cost' if not np.isfinite(cost)
472
+ else 'non-finite gradients')
473
+ self.costs[step] = np.inf
474
+ cost = np.inf
475
+ _register_failure(reason)
476
+ else:
477
+ consecutive_failures = 0
478
+ self.costs[step] = cost
479
+ if cost < best_cost:
480
+ # best values are the ones the cost was evaluated at
481
+ # (before this step's update is applied).
482
+ best_omega = ops.convert_to_numpy(get_omega(trainable_variables))
483
+ best_cost = cost
484
+ best_values = save_values(trainable_variables)
485
+ opt.apply_gradients(zip(gradients, trainable_variables))
486
+
487
+ if progressbar:
488
+ pbar.set_description(get_pbar_description(cost, best_cost, best_values))
489
+
490
+ if not np.isfinite(cost):
491
+ # A rolled-back step says nothing about convergence (and
492
+ # inf / previous_cost would trigger the rtol break below).
493
+ continue
494
+
495
+ previous_cost = self.costs[np.max((step - lag, 0))]
496
+
497
+ if (step > min_n_iterations) and (np.sign(previous_cost) == np.sign(cost)):
498
+ if np.sign(cost) == -1:
499
+ if (cost / previous_cost) < 1 + rtol:
500
+ break
501
+ else:
502
+ if (cost / previous_cost) > 1 - rtol:
503
+ break
504
+
505
+ if not np.isfinite(best_cost):
506
+ raise RuntimeError(
507
+ 'ResidualFitter: no optimisation step produced a finite cost '
508
+ f'({self.n_failed_steps} failed steps). Ω was never fitted.')
509
+
510
+ if self.n_failed_steps > 0:
511
+ warnings.warn(
512
+ f'ResidualFitter: {self.n_failed_steps} of {step + 1} steps '
513
+ f'failed and were rolled back (final learning rate '
514
+ f'{learning_rate:.3g}).', RuntimeWarning, stacklevel=2)
515
+
516
+ omega = best_omega
517
+
518
+ if cholesky == 'strict':
519
+ self.omega_min_eigenvalue_ = float(np.linalg.eigvalsh(
520
+ np.asarray(omega, dtype=np.float64)).min())
521
+
522
+ fitted_parameters = [ops.convert_to_numpy(ops.convert_to_tensor(v)) for v in
523
+ transform_variables(best_values)]
524
+ self.fitted_omega_parameters = dict(zip(['tau', 'rho', 'sigma2'], fitted_parameters[:3]))
525
+
526
+ if D is not None:
527
+ self.fitted_omega_parameters['alpha'] = fitted_parameters[3]
528
+ self.fitted_omega_parameters['beta'] = fitted_parameters[4]
529
+
530
+ if method == 't':
531
+ dof = float(ops.convert_to_numpy(ops.softplus(best_values[-1])))
532
+ self.fitted_omega_parameters['dof'] = dof
533
+ return omega, dof
534
+ else:
535
+ return omega, None
536
+
537
+ def _get_omega(self, tau, rho, sigma2, WWT):
538
+ return (rho * ops.transpose(tau) @ tau +
539
+ (1 - rho) * ops.diag(tau[0, :]**2) +
540
+ sigma2 * WWT)
541
+
542
+ def _get_omega_distance(self, tau, rho, sigma2, WWT, alpha, beta, D):
543
+ tautau = ops.transpose(tau) @ tau
544
+ return (rho * (alpha * (ops.exp(-beta * D) * tautau) + (1 - alpha) * tautau) +
545
+ (1 - rho) * ops.diag(tau[0, :]**2) +
546
+ sigma2 * WWT)
547
+
548
+ def _get_omega_lambda(self, tau, rho, sigma2, WWT, lambd, sample_covariance):
549
+ """Interpolate between parametric omega (lambd=0) and sample covariance (lambd=1).
550
+
551
+ Jitter is adaptive: 1e-4 × mean diagonal so Cholesky stays stable
552
+ regardless of data scale. This matters most when lambd→1 and the
553
+ sample covariance dominates (its smallest eigenvalue can be very small
554
+ when n_voxels is close to n_timepoints).
555
+ """
556
+ result = ((1 - lambd) * (rho * ops.transpose(tau) @ tau +
557
+ (1 - rho) * ops.diag(tau[0, :]**2) +
558
+ sigma2 * WWT) +
559
+ lambd * sample_covariance)
560
+ # Adaptive jitter: scales with the matrix so it's never swamped by
561
+ # the signal or invisible against large diagonal values.
562
+ mean_diag = ops.mean(ops.diag(result))
563
+ return result + ops.eye(tau.shape[1], dtype='float32') * (mean_diag * 1e-4 + 1e-9)