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