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