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
braincoder/noise.py
ADDED
|
@@ -0,0 +1,614 @@
|
|
|
1
|
+
"""Low-rank + diagonal noise models for decoding, with cross-validated
|
|
2
|
+
rank and likelihood temperature.
|
|
3
|
+
|
|
4
|
+
Quick start
|
|
5
|
+
-----------
|
|
6
|
+
>>> from braincoder.noise import LowRankNoise
|
|
7
|
+
>>> noise = LowRankNoise.fit(model, train_data, train_paradigm, parameters,
|
|
8
|
+
... stimulus_range=grid, groups=train_runs)
|
|
9
|
+
>>> pdf = model.get_stimulus_pdf(test_data, stimulus_range=grid,
|
|
10
|
+
... parameters=parameters, noise_model=noise)
|
|
11
|
+
>>> print(noise.summary())
|
|
12
|
+
|
|
13
|
+
The noise covariance is
|
|
14
|
+
|
|
15
|
+
.. math::
|
|
16
|
+
|
|
17
|
+
\\Omega = D\\,(F F^\\top + \\Psi)\\,D,
|
|
18
|
+
|
|
19
|
+
with :math:`D = \\mathrm{diag}(s)` the per-voxel residual scale, :math:`F`
|
|
20
|
+
(``n_voxels × k``) the first ``k`` principal factors of the residual
|
|
21
|
+
*correlation* matrix and :math:`\\Psi` the diagonal uniquenesses (floored at
|
|
22
|
+
``psi_floor``). The likelihood is a multivariate Gaussian or Student-t with
|
|
23
|
+
scale :math:`\\Omega`. It is never formed as a dense ``V × V`` matrix: the
|
|
24
|
+
Mahalanobis distance and log-determinant use the Woodbury identity and the
|
|
25
|
+
matrix-determinant lemma, so cost is ``O(V k)`` per residual vector.
|
|
26
|
+
|
|
27
|
+
Decoding posteriors are *tempered*: :math:`p(s \\mid y) \\propto
|
|
28
|
+
p(y \\mid s)^{1/T}`. ``k`` and ``T`` are chosen jointly by **nested,
|
|
29
|
+
grouped cross-validation on the decoding objective** — the held-out log
|
|
30
|
+
posterior probability of the true stimulus — not by how well the
|
|
31
|
+
covariance fits the residuals. (On real 7T single-trial betas the
|
|
32
|
+
covariance likelihood keeps asking for more factors while decoding gets
|
|
33
|
+
worse; see the user guide.)
|
|
34
|
+
"""
|
|
35
|
+
from __future__ import annotations
|
|
36
|
+
|
|
37
|
+
import logging
|
|
38
|
+
import warnings
|
|
39
|
+
|
|
40
|
+
import numpy as np
|
|
41
|
+
import pandas as pd
|
|
42
|
+
from scipy.optimize import minimize_scalar
|
|
43
|
+
from scipy.special import gammaln, logsumexp
|
|
44
|
+
|
|
45
|
+
__all__ = ['LowRankNoise', 'fit_lowrank_omega', 'DEFAULT_K_GRID',
|
|
46
|
+
'DEFAULT_TEMPERATURE_GRID']
|
|
47
|
+
|
|
48
|
+
logger = logging.getLogger(__name__)
|
|
49
|
+
|
|
50
|
+
#: Default candidate ranks (capped by the number of inner-training trials
|
|
51
|
+
#: and voxels at fit time).
|
|
52
|
+
DEFAULT_K_GRID = (0, 1, 2, 5, 10, 20, 40, 80)
|
|
53
|
+
|
|
54
|
+
#: Default candidate temperatures: 2^-2 … 2^12 in steps of 2^(1/4), plus
|
|
55
|
+
#: ``inf`` (= flat posterior; chosen when the likelihood carries no usable
|
|
56
|
+
#: calibrated information).
|
|
57
|
+
DEFAULT_TEMPERATURE_GRID = tuple(np.r_[2.0 ** np.arange(-2, 12.001, 0.25), np.inf])
|
|
58
|
+
|
|
59
|
+
_DOF_BOUNDS = (2.05, 1e4)
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
# ---------------------------------------------------------------------------
|
|
63
|
+
# helpers
|
|
64
|
+
# ---------------------------------------------------------------------------
|
|
65
|
+
|
|
66
|
+
def _as_2d_array(x):
|
|
67
|
+
if hasattr(x, 'values'):
|
|
68
|
+
x = x.values
|
|
69
|
+
x = np.asarray(x, dtype=np.float64)
|
|
70
|
+
if x.ndim == 1:
|
|
71
|
+
x = x[:, None]
|
|
72
|
+
return x
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
def _standardise(R):
|
|
76
|
+
mu = R.mean(0)
|
|
77
|
+
sd = R.std(0)
|
|
78
|
+
good = sd > 0
|
|
79
|
+
fill = np.median(sd[good]) if good.any() else 1.0
|
|
80
|
+
sd = np.where(good, sd, fill)
|
|
81
|
+
return (R - mu) / sd, sd
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
def _match_to_grid(stimuli, grid, name='paradigm'):
|
|
85
|
+
"""Index of the nearest grid point for every row of ``stimuli``."""
|
|
86
|
+
stimuli = _as_2d_array(stimuli)
|
|
87
|
+
grid = _as_2d_array(grid)
|
|
88
|
+
if stimuli.shape[1] != grid.shape[1]:
|
|
89
|
+
raise ValueError(f'{name} has {stimuli.shape[1]} stimulus dimensions, '
|
|
90
|
+
f'stimulus_range has {grid.shape[1]}')
|
|
91
|
+
d2 = ((stimuli[:, None, :] - grid[None, :, :]) ** 2).sum(-1)
|
|
92
|
+
idx = d2.argmin(1)
|
|
93
|
+
if len(grid) > 1:
|
|
94
|
+
gd = ((grid[:, None, :] - grid[None, :, :]) ** 2).sum(-1)
|
|
95
|
+
gd[np.diag_indices_from(gd)] = np.inf
|
|
96
|
+
half_spacing2 = (0.5 ** 2) * gd.min(1).max()
|
|
97
|
+
if d2[np.arange(len(idx)), idx].max() > half_spacing2 * 1.0001:
|
|
98
|
+
warnings.warn(f'Some {name} stimuli lie more than half a grid step '
|
|
99
|
+
'from the nearest point of stimulus_range; their '
|
|
100
|
+
'true stimulus is approximated by the nearest grid point.',
|
|
101
|
+
RuntimeWarning, stacklevel=3)
|
|
102
|
+
return idx
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
def _mvt_logpdf(d2, logdet, V, dof):
|
|
106
|
+
if dof is None or not np.isfinite(dof):
|
|
107
|
+
return -0.5 * (V * np.log(2 * np.pi) + logdet + d2)
|
|
108
|
+
return (gammaln((dof + V) / 2.) - gammaln(dof / 2.) - 0.5 * V * np.log(dof * np.pi)
|
|
109
|
+
- 0.5 * logdet - 0.5 * (dof + V) * np.log1p(d2 / dof))
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
def _fit_scale_dof(d2, logdet, V, dof='fit'):
|
|
113
|
+
"""ML (c, ν) for residuals with Mahalanobis d2 under unit-scale Ω.
|
|
114
|
+
|
|
115
|
+
Ω_fitted = c·Ω. ``dof``: 'fit' (ML, 1-D bounded search on log ν with c
|
|
116
|
+
profiled out), ``None`` (Gaussian, closed-form c) or a fixed number.
|
|
117
|
+
Returns (c, dof, total_loglik).
|
|
118
|
+
"""
|
|
119
|
+
d2 = np.asarray(d2, dtype=np.float64)
|
|
120
|
+
n = len(d2)
|
|
121
|
+
|
|
122
|
+
if dof is None:
|
|
123
|
+
c = max(d2.mean() / V, 1e-300)
|
|
124
|
+
return c, None, float(_mvt_logpdf(d2 / c, logdet + V * np.log(c), V, None).sum())
|
|
125
|
+
|
|
126
|
+
def best_c(nu):
|
|
127
|
+
# EM fixed point for the scale of a multivariate t, started at the
|
|
128
|
+
# Gaussian estimate; converges monotonically.
|
|
129
|
+
c = max(d2.mean() / V, 1e-300)
|
|
130
|
+
for _ in range(200):
|
|
131
|
+
w = (nu + V) / (nu + d2 / c)
|
|
132
|
+
c_new = (w * d2).sum() / (n * V)
|
|
133
|
+
if abs(c_new - c) <= 1e-10 * c:
|
|
134
|
+
c = c_new
|
|
135
|
+
break
|
|
136
|
+
c = c_new
|
|
137
|
+
ll = _mvt_logpdf(d2 / c, logdet + V * np.log(c), V, nu).sum()
|
|
138
|
+
return c, ll
|
|
139
|
+
|
|
140
|
+
if dof == 'fit':
|
|
141
|
+
res = minimize_scalar(lambda lnu: -best_c(np.exp(lnu))[1],
|
|
142
|
+
bounds=np.log(_DOF_BOUNDS), method='bounded',
|
|
143
|
+
options=dict(xatol=1e-3))
|
|
144
|
+
nu = float(np.exp(res.x))
|
|
145
|
+
# also compare against the boundaries (the profile can be monotone)
|
|
146
|
+
cands = [nu, _DOF_BOUNDS[0], _DOF_BOUNDS[1]]
|
|
147
|
+
lls = [best_c(c)[1] for c in cands]
|
|
148
|
+
nu = cands[int(np.argmax(lls))]
|
|
149
|
+
else:
|
|
150
|
+
nu = float(dof)
|
|
151
|
+
c, ll = best_c(nu)
|
|
152
|
+
return float(c), nu, float(ll)
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
# ---------------------------------------------------------------------------
|
|
156
|
+
# the noise model
|
|
157
|
+
# ---------------------------------------------------------------------------
|
|
158
|
+
|
|
159
|
+
class LowRankNoise(object):
|
|
160
|
+
"""Low-rank + diagonal (Gaussian or Student-t) noise model for decoding.
|
|
161
|
+
|
|
162
|
+
Ω = D (F Fᵀ + Ψ) D, stored in factored form. Construct with
|
|
163
|
+
:meth:`fit` (recommended: chooses ``k`` and the temperature ``T`` by
|
|
164
|
+
nested grouped cross-validation on the decoding objective) or
|
|
165
|
+
:meth:`from_residuals` (covariance only, fixed ``k``).
|
|
166
|
+
|
|
167
|
+
Attributes
|
|
168
|
+
----------
|
|
169
|
+
k : int
|
|
170
|
+
Number of factors.
|
|
171
|
+
temperature : float
|
|
172
|
+
Likelihood temperature applied by ``get_stimulus_pdf`` (``inf`` =
|
|
173
|
+
flat posterior).
|
|
174
|
+
dof : float or None
|
|
175
|
+
Student-t degrees of freedom (``None`` = Gaussian).
|
|
176
|
+
scale : ndarray (V,)
|
|
177
|
+
Per-voxel scale ``s`` (includes the ML scale factor).
|
|
178
|
+
factors : ndarray (V, k)
|
|
179
|
+
``F``, loadings on the correlation scale.
|
|
180
|
+
psi : ndarray (V,)
|
|
181
|
+
Diagonal uniquenesses on the correlation scale.
|
|
182
|
+
voxels : pandas.Index or None
|
|
183
|
+
Voxel labels (columns of the training data), used to align test data.
|
|
184
|
+
cv_scores_ : pandas.DataFrame or None
|
|
185
|
+
Cross-validated decoding score for every (k, T): mean held-out log
|
|
186
|
+
posterior probability of the true stimulus per trial, **minus** that
|
|
187
|
+
of a flat posterior (nats; > 0 = better than uniform). Rows = k,
|
|
188
|
+
columns = T.
|
|
189
|
+
"""
|
|
190
|
+
|
|
191
|
+
def __init__(self, scale, factors, psi, dof=None, temperature=1.0,
|
|
192
|
+
voxels=None):
|
|
193
|
+
self.scale = np.asarray(scale, dtype=np.float64)
|
|
194
|
+
V = len(self.scale)
|
|
195
|
+
factors = np.asarray(factors, dtype=np.float64)
|
|
196
|
+
if factors.ndim == 1:
|
|
197
|
+
factors = factors[:, None]
|
|
198
|
+
if factors.size == 0:
|
|
199
|
+
factors = np.zeros((V, 0))
|
|
200
|
+
self.factors = factors
|
|
201
|
+
self.psi = np.asarray(psi, dtype=np.float64)
|
|
202
|
+
if self.factors.shape[0] != V or self.psi.shape != (V,):
|
|
203
|
+
raise ValueError('scale, factors and psi must have matching n_voxels')
|
|
204
|
+
if np.any(self.psi <= 0) or np.any(self.scale <= 0):
|
|
205
|
+
raise ValueError('psi and scale must be strictly positive')
|
|
206
|
+
self.dof = None if dof is None or not np.isfinite(dof) else float(dof)
|
|
207
|
+
self.temperature = float(temperature)
|
|
208
|
+
self.voxels = None if voxels is None else pd.Index(voxels)
|
|
209
|
+
self.cv_scores_ = None
|
|
210
|
+
self.cv_info_ = {}
|
|
211
|
+
self._precompute()
|
|
212
|
+
|
|
213
|
+
# -- factored algebra ----------------------------------------------------
|
|
214
|
+
|
|
215
|
+
def _precompute(self):
|
|
216
|
+
F, psi = self.factors, self.psi
|
|
217
|
+
k = F.shape[1]
|
|
218
|
+
FtPinv = (F / psi[:, None]).T # k x V
|
|
219
|
+
M = np.eye(k) + FtPinv @ F
|
|
220
|
+
Lm = np.linalg.cholesky(M)
|
|
221
|
+
# A = Lm^{-1} F^T Psi^{-1}; Ω_C^{-1} = Ψ^{-1} - Aᵀ A
|
|
222
|
+
self._A = np.linalg.solve(Lm, FtPinv) if k > 0 else np.zeros((0, len(psi)))
|
|
223
|
+
self._sqrt_inv_psi = 1.0 / np.sqrt(psi)
|
|
224
|
+
self.logdet = float(2 * np.log(self.scale).sum() + np.log(psi).sum()
|
|
225
|
+
+ 2 * np.log(np.diag(Lm)).sum()) if k > 0 else \
|
|
226
|
+
float(2 * np.log(self.scale).sum() + np.log(psi).sum())
|
|
227
|
+
self._tf_cache = None
|
|
228
|
+
|
|
229
|
+
@property
|
|
230
|
+
def k(self):
|
|
231
|
+
return self.factors.shape[1]
|
|
232
|
+
|
|
233
|
+
@property
|
|
234
|
+
def n_voxels(self):
|
|
235
|
+
return len(self.scale)
|
|
236
|
+
|
|
237
|
+
def _components(self, X):
|
|
238
|
+
"""(G, H) such that <a, b>_{Ω⁻¹} = G_a·G_b − H_a·H_b."""
|
|
239
|
+
Z = X / self.scale
|
|
240
|
+
return Z * self._sqrt_inv_psi, Z @ self._A.T
|
|
241
|
+
|
|
242
|
+
def mahalanobis(self, residuals):
|
|
243
|
+
"""Squared Mahalanobis distance rᵀ Ω⁻¹ r of each row (Woodbury)."""
|
|
244
|
+
R = self._align(residuals)
|
|
245
|
+
G, H = self._components(R)
|
|
246
|
+
return np.clip((G ** 2).sum(1) - (H ** 2).sum(1), 0, None)
|
|
247
|
+
|
|
248
|
+
def log_prob(self, residuals):
|
|
249
|
+
"""Log density of each row of ``residuals`` (numpy, float64)."""
|
|
250
|
+
d2 = self.mahalanobis(residuals)
|
|
251
|
+
return _mvt_logpdf(d2, self.logdet, self.n_voxels, self.dof)
|
|
252
|
+
|
|
253
|
+
def grid_log_likelihood(self, data, predictions):
|
|
254
|
+
"""Log-likelihood table ``(n_trials, n_stimuli)``.
|
|
255
|
+
|
|
256
|
+
``data``: (n_trials, V); ``predictions``: (n_stimuli, V), the model
|
|
257
|
+
prediction for every candidate stimulus. Computed as
|
|
258
|
+
d²(t, s) = q(y_t) + q(μ_s) − 2⟨y_t, μ_s⟩ with all terms in factored
|
|
259
|
+
form — one (n_trials × V) · (V × n_stimuli) product, no dense Ω and
|
|
260
|
+
no (n_stimuli × n_trials × V) residual tensor. float64 numpy.
|
|
261
|
+
"""
|
|
262
|
+
Y = self._align(data)
|
|
263
|
+
P = _as_2d_array(predictions)
|
|
264
|
+
Gy, Hy = self._components(Y)
|
|
265
|
+
Gp, Hp = self._components(P)
|
|
266
|
+
d2 = ((Gy ** 2).sum(1) - (Hy ** 2).sum(1))[:, None] \
|
|
267
|
+
+ ((Gp ** 2).sum(1) - (Hp ** 2).sum(1))[None, :] \
|
|
268
|
+
- 2 * (Gy @ Gp.T - Hy @ Hp.T)
|
|
269
|
+
d2 = np.clip(d2, 0, None)
|
|
270
|
+
return _mvt_logpdf(d2, self.logdet, self.n_voxels, self.dof)
|
|
271
|
+
|
|
272
|
+
def log_prob_backend(self, residuals):
|
|
273
|
+
"""Log density of each row, in Keras ops (float32, differentiable).
|
|
274
|
+
|
|
275
|
+
Same factored computation as :meth:`log_prob`, usable inside a
|
|
276
|
+
TensorFlow / JAX / PyTorch graph (e.g. gradient-based stimulus
|
|
277
|
+
fitting). ``residuals``: tensor (n, V).
|
|
278
|
+
"""
|
|
279
|
+
from keras import ops
|
|
280
|
+
from .utils.backend import lgamma
|
|
281
|
+
if self._tf_cache is None:
|
|
282
|
+
self._tf_cache = dict(
|
|
283
|
+
inv_s=ops.convert_to_tensor((1. / self.scale).astype(np.float32)),
|
|
284
|
+
sip=ops.convert_to_tensor(self._sqrt_inv_psi.astype(np.float32)),
|
|
285
|
+
At=ops.convert_to_tensor(self._A.T.astype(np.float32)) if self.k > 0 else None,
|
|
286
|
+
)
|
|
287
|
+
c = self._tf_cache
|
|
288
|
+
z = ops.cast(residuals, 'float32') * c['inv_s']
|
|
289
|
+
q = ops.sum((z * c['sip']) ** 2, axis=1)
|
|
290
|
+
if c['At'] is not None:
|
|
291
|
+
q = q - ops.sum(ops.matmul(z, c['At']) ** 2, axis=1)
|
|
292
|
+
q = ops.maximum(q, 0.)
|
|
293
|
+
V = float(self.n_voxels)
|
|
294
|
+
if self.dof is None:
|
|
295
|
+
return -0.5 * (V * np.log(2 * np.pi) + self.logdet + q)
|
|
296
|
+
nu = self.dof
|
|
297
|
+
const = float(gammaln((nu + V) / 2.) - gammaln(nu / 2.)
|
|
298
|
+
- 0.5 * V * np.log(nu * np.pi) - 0.5 * self.logdet)
|
|
299
|
+
return const - 0.5 * (nu + V) * ops.log1p(q / nu)
|
|
300
|
+
|
|
301
|
+
def to_dense(self):
|
|
302
|
+
"""Dense ``(omega, dof)``, drop-in for ``ResidualFitter.fit`` output.
|
|
303
|
+
|
|
304
|
+
For code paths that take ``omega=`` / ``dof=``. Note the temperature
|
|
305
|
+
is *not* part of (omega, dof); pass ``temperature=noise.temperature``
|
|
306
|
+
to ``get_stimulus_pdf`` as well.
|
|
307
|
+
"""
|
|
308
|
+
C = self.factors @ self.factors.T
|
|
309
|
+
C[np.diag_indices_from(C)] += self.psi
|
|
310
|
+
omega = C * self.scale[:, None] * self.scale[None, :]
|
|
311
|
+
return omega.astype(np.float32), self.dof
|
|
312
|
+
|
|
313
|
+
def _align(self, X):
|
|
314
|
+
if self.voxels is not None and isinstance(X, pd.DataFrame):
|
|
315
|
+
if not X.columns.equals(self.voxels):
|
|
316
|
+
missing = self.voxels.difference(X.columns)
|
|
317
|
+
if len(missing):
|
|
318
|
+
raise ValueError(f'{len(missing)} voxels of the noise model are '
|
|
319
|
+
'missing from the data')
|
|
320
|
+
X = X.loc[:, self.voxels]
|
|
321
|
+
X = _as_2d_array(X)
|
|
322
|
+
if X.shape[1] != self.n_voxels:
|
|
323
|
+
raise ValueError(f'data has {X.shape[1]} voxels, noise model {self.n_voxels}')
|
|
324
|
+
return X
|
|
325
|
+
|
|
326
|
+
# -- construction --------------------------------------------------------
|
|
327
|
+
|
|
328
|
+
@staticmethod
|
|
329
|
+
def _svd(R):
|
|
330
|
+
Z, sd = _standardise(R)
|
|
331
|
+
_, s, Vt = np.linalg.svd(Z, full_matrices=False)
|
|
332
|
+
return dict(sd=sd, s=s, Vt=Vt, n=len(R))
|
|
333
|
+
|
|
334
|
+
@staticmethod
|
|
335
|
+
def _structure(svd, k, psi_floor):
|
|
336
|
+
"""Unit-scale (sd, F, psi) for rank k from a precomputed SVD."""
|
|
337
|
+
lam = svd['s'][:k] ** 2 / svd['n']
|
|
338
|
+
F = (svd['Vt'][:k] * np.sqrt(lam)[:, None]).T # V x k
|
|
339
|
+
common = (F ** 2).sum(1)
|
|
340
|
+
psi = np.clip(1.0 - common, psi_floor, None)
|
|
341
|
+
return svd['sd'], F, psi
|
|
342
|
+
|
|
343
|
+
@classmethod
|
|
344
|
+
def from_residuals(cls, residuals, k=40, dof='fit', psi_floor=0.02,
|
|
345
|
+
temperature=1.0, _svd=None):
|
|
346
|
+
"""Fit Ω (and ν) to residuals for a fixed rank ``k``.
|
|
347
|
+
|
|
348
|
+
Principal-factor model of the residual correlation (one closed-form
|
|
349
|
+
step, no iteration): F = first k eigenvectors × √eigenvalues, Ψ =
|
|
350
|
+
1 − diag(F Fᵀ), floored at ``psi_floor``; then an overall scale c and
|
|
351
|
+
ν are fitted by maximum likelihood (Student-t; ``dof=None`` for
|
|
352
|
+
Gaussian, a number to fix ν).
|
|
353
|
+
|
|
354
|
+
Parameters
|
|
355
|
+
----------
|
|
356
|
+
residuals : DataFrame or array (n_trials, V)
|
|
357
|
+
k : int
|
|
358
|
+
Number of factors (capped at ``min(n_trials, V) − 1``).
|
|
359
|
+
"""
|
|
360
|
+
voxels = residuals.columns if isinstance(residuals, pd.DataFrame) else None
|
|
361
|
+
R = _as_2d_array(residuals)
|
|
362
|
+
n, V = R.shape
|
|
363
|
+
k = int(min(k, max(min(n, V) - 1, 0)))
|
|
364
|
+
svd = cls._svd(R) if _svd is None else _svd
|
|
365
|
+
sd, F, psi = cls._structure(svd, k, psi_floor)
|
|
366
|
+
unit = cls(sd, F, psi, dof=None, voxels=voxels)
|
|
367
|
+
d2 = unit.mahalanobis(R)
|
|
368
|
+
c, nu, ll = _fit_scale_dof(d2, unit.logdet, V, dof=dof)
|
|
369
|
+
out = cls(sd * np.sqrt(c), F, psi, dof=nu, temperature=temperature,
|
|
370
|
+
voxels=voxels)
|
|
371
|
+
out.train_loglik_ = ll
|
|
372
|
+
out.psi_floor = psi_floor
|
|
373
|
+
return out
|
|
374
|
+
|
|
375
|
+
@classmethod
|
|
376
|
+
def fit(cls, model, data, paradigm, parameters=None, stimulus_range=None,
|
|
377
|
+
groups=None, weights=None, k='cv', temperature='cv', dof='fit',
|
|
378
|
+
k_grid=DEFAULT_K_GRID, temperature_grid=DEFAULT_TEMPERATURE_GRID,
|
|
379
|
+
inner_parameters=None, psi_floor=0.02, n_folds=5,
|
|
380
|
+
progressbar=False):
|
|
381
|
+
"""Fit a low-rank noise model; choose ``k`` and ``T`` by nested CV.
|
|
382
|
+
|
|
383
|
+
Parameters
|
|
384
|
+
----------
|
|
385
|
+
model : EncodingModel
|
|
386
|
+
data : DataFrame (n_trials, V)
|
|
387
|
+
**Training** data only (the test data must never be passed here).
|
|
388
|
+
paradigm : DataFrame or array (n_trials, n_stim_dims)
|
|
389
|
+
True stimulus of every training trial.
|
|
390
|
+
parameters : DataFrame, optional
|
|
391
|
+
Encoding parameters (``None`` only for models without parameters).
|
|
392
|
+
stimulus_range : array (n_stimuli,) or (n_stimuli, n_dims)
|
|
393
|
+
The decoding grid — use the same grid as for
|
|
394
|
+
``get_stimulus_pdf``. Required when ``k`` or ``temperature`` is
|
|
395
|
+
chosen by CV. True training stimuli are matched to the nearest
|
|
396
|
+
grid point.
|
|
397
|
+
groups : array (n_trials,), optional
|
|
398
|
+
Group label per training trial (e.g. run). Inner CV leaves one
|
|
399
|
+
group out at a time. Strongly recommended: trials within a run
|
|
400
|
+
share noise. Without it, ``n_folds`` contiguous blocks are used.
|
|
401
|
+
k : 'cv' or int
|
|
402
|
+
temperature : 'cv' or float (``np.inf`` = flat posterior)
|
|
403
|
+
dof : 'fit', None or float
|
|
404
|
+
Student-t ν by ML ('fit'), Gaussian (``None``) or fixed.
|
|
405
|
+
k_grid, temperature_grid : sequences
|
|
406
|
+
Candidates for CV. ``k`` values ≥ the number of inner-training
|
|
407
|
+
trials or voxels are dropped.
|
|
408
|
+
inner_parameters : None, dict or callable
|
|
409
|
+
Encoding parameters used inside inner fold ``g``.
|
|
410
|
+
|
|
411
|
+
* ``None`` (default): ``parameters`` are **held fixed**. The
|
|
412
|
+
inner held-out trials were then part of the data the
|
|
413
|
+
encoding model was fitted on, so their predictions are
|
|
414
|
+
slightly optimistic and the chosen ``T`` is, if anything,
|
|
415
|
+
too small (posteriors a bit too sharp).
|
|
416
|
+
* ``dict`` {group: parameters}: precomputed parameters that did
|
|
417
|
+
not see group ``g`` (e.g. existing leave-one-run-out fits).
|
|
418
|
+
* callable ``f(train_data, train_paradigm, group) -> parameters``:
|
|
419
|
+
refit the encoding model on the inner-training trials.
|
|
420
|
+
|
|
421
|
+
In fold ``g``, Ω is fitted on the residuals of the inner-training
|
|
422
|
+
trials under these parameters, and the held-out trials are
|
|
423
|
+
decoded with them.
|
|
424
|
+
psi_floor : float
|
|
425
|
+
Floor on the diagonal uniquenesses (correlation scale).
|
|
426
|
+
|
|
427
|
+
Returns
|
|
428
|
+
-------
|
|
429
|
+
LowRankNoise
|
|
430
|
+
Fitted on *all* training trials with the chosen ``k``; carries
|
|
431
|
+
the chosen ``temperature``, ``cv_scores_`` and ``cv_info_``.
|
|
432
|
+
|
|
433
|
+
Notes
|
|
434
|
+
-----
|
|
435
|
+
The CV objective is the summed held-out log posterior probability of
|
|
436
|
+
the true stimulus on the grid, ``log p_T(s* | y)``, under a flat
|
|
437
|
+
prior over the grid. This is the decoding objective; it is *not* the
|
|
438
|
+
covariance likelihood (which prefers ever larger ``k`` on fMRI data
|
|
439
|
+
while decoding gets worse). For every inner fold and every ``k``,
|
|
440
|
+
Ω(k) and ν are refitted on the inner-training residuals; all ``T``
|
|
441
|
+
are evaluated on the same likelihood table at no extra cost.
|
|
442
|
+
"""
|
|
443
|
+
voxels = data.columns if isinstance(data, pd.DataFrame) else None
|
|
444
|
+
Y = _as_2d_array(data)
|
|
445
|
+
n, V = Y.shape
|
|
446
|
+
|
|
447
|
+
def residuals_for(pars, idx):
|
|
448
|
+
pred = model.predict(paradigm=_subset(paradigm, idx),
|
|
449
|
+
parameters=pars, weights=weights)
|
|
450
|
+
return Y[idx] - _as_2d_array(pred)
|
|
451
|
+
|
|
452
|
+
all_idx = np.arange(n)
|
|
453
|
+
R_all = residuals_for(parameters, all_idx)
|
|
454
|
+
|
|
455
|
+
need_cv = (isinstance(k, str) and k == 'cv') or \
|
|
456
|
+
(isinstance(temperature, str) and temperature == 'cv')
|
|
457
|
+
|
|
458
|
+
if not need_cv:
|
|
459
|
+
out = cls.from_residuals(R_all, k=int(k), dof=dof, psi_floor=psi_floor,
|
|
460
|
+
temperature=float(temperature))
|
|
461
|
+
out.voxels = None if voxels is None else pd.Index(voxels)
|
|
462
|
+
return out
|
|
463
|
+
|
|
464
|
+
if stimulus_range is None:
|
|
465
|
+
raise ValueError('stimulus_range is required to choose k / temperature '
|
|
466
|
+
'by cross-validation')
|
|
467
|
+
|
|
468
|
+
grid = _as_2d_array(stimulus_range)
|
|
469
|
+
true_idx = _match_to_grid(paradigm, grid)
|
|
470
|
+
S = len(grid)
|
|
471
|
+
|
|
472
|
+
if groups is None:
|
|
473
|
+
warnings.warn('No `groups` given: inner CV uses %d contiguous blocks of '
|
|
474
|
+
'trials. Pass run labels if trials within a run share '
|
|
475
|
+
'noise.' % n_folds, RuntimeWarning, stacklevel=2)
|
|
476
|
+
groups = np.repeat(np.arange(n_folds), int(np.ceil(n / n_folds)))[:n]
|
|
477
|
+
groups = np.asarray(groups)
|
|
478
|
+
if len(groups) != n:
|
|
479
|
+
raise ValueError('groups must have one entry per training trial')
|
|
480
|
+
ugroups = pd.unique(groups)
|
|
481
|
+
if len(ugroups) < 2:
|
|
482
|
+
raise ValueError('need at least two groups for cross-validation')
|
|
483
|
+
|
|
484
|
+
n_tr_min = min((groups != g).sum() for g in ugroups)
|
|
485
|
+
if isinstance(k, str):
|
|
486
|
+
ks = sorted({int(kk) for kk in k_grid if kk < min(n_tr_min, V)})
|
|
487
|
+
else:
|
|
488
|
+
ks = [int(k)]
|
|
489
|
+
if isinstance(temperature, str):
|
|
490
|
+
Ts = np.asarray(temperature_grid, dtype=float)
|
|
491
|
+
else:
|
|
492
|
+
Ts = np.asarray([float(temperature)])
|
|
493
|
+
|
|
494
|
+
finite_T = Ts[np.isfinite(Ts)]
|
|
495
|
+
scores = np.zeros((len(ks), len(Ts)))
|
|
496
|
+
nus = {kk: [] for kk in ks}
|
|
497
|
+
|
|
498
|
+
iterator = ugroups
|
|
499
|
+
if progressbar:
|
|
500
|
+
from tqdm.auto import tqdm
|
|
501
|
+
iterator = tqdm(ugroups, desc='inner CV')
|
|
502
|
+
|
|
503
|
+
for g in iterator:
|
|
504
|
+
te = np.where(groups == g)[0]
|
|
505
|
+
tr = np.where(groups != g)[0]
|
|
506
|
+
if inner_parameters is None:
|
|
507
|
+
pars_g = parameters
|
|
508
|
+
R_tr = R_all[tr]
|
|
509
|
+
else:
|
|
510
|
+
if callable(inner_parameters):
|
|
511
|
+
pars_g = inner_parameters(_subset(data, tr), _subset(paradigm, tr), g)
|
|
512
|
+
else:
|
|
513
|
+
pars_g = inner_parameters[g]
|
|
514
|
+
R_tr = residuals_for(pars_g, tr)
|
|
515
|
+
|
|
516
|
+
P = _grid_predictions(model, grid, pars_g, weights) # S x V
|
|
517
|
+
svd = cls._svd(R_tr)
|
|
518
|
+
for ki, kk in enumerate(ks):
|
|
519
|
+
nm = cls.from_residuals(R_tr, k=kk, dof=dof, psi_floor=psi_floor,
|
|
520
|
+
_svd=svd)
|
|
521
|
+
nus[kk].append(nm.dof)
|
|
522
|
+
ll = nm.grid_log_likelihood(Y[te], P) # n_te x S
|
|
523
|
+
ll_true = ll[np.arange(len(te)), true_idx[te]]
|
|
524
|
+
for ti, T in enumerate(Ts):
|
|
525
|
+
if np.isinf(T):
|
|
526
|
+
scores[ki, ti] += -len(te) * np.log(S)
|
|
527
|
+
else:
|
|
528
|
+
a = ll / T
|
|
529
|
+
scores[ki, ti] += (ll_true / T - logsumexp(a, axis=1)).sum()
|
|
530
|
+
|
|
531
|
+
# mean per trial, relative to the flat posterior
|
|
532
|
+
rel = scores / n + np.log(S)
|
|
533
|
+
cv = pd.DataFrame(rel, index=pd.Index(ks, name='k'),
|
|
534
|
+
columns=pd.Index(Ts, name='temperature'))
|
|
535
|
+
ki, ti = np.unravel_index(np.nanargmax(rel), rel.shape)
|
|
536
|
+
k_best, T_best = ks[ki], float(Ts[ti])
|
|
537
|
+
|
|
538
|
+
out = cls.from_residuals(R_all, k=k_best, dof=dof, psi_floor=psi_floor,
|
|
539
|
+
temperature=T_best)
|
|
540
|
+
out.voxels = None if voxels is None else pd.Index(voxels)
|
|
541
|
+
out.cv_scores_ = cv
|
|
542
|
+
out.cv_info_ = dict(n_trials=n, n_voxels=V, n_groups=len(ugroups),
|
|
543
|
+
n_stimuli=S, inner_parameters=(
|
|
544
|
+
'fixed' if inner_parameters is None else
|
|
545
|
+
'callable' if callable(inner_parameters) else 'dict'),
|
|
546
|
+
inner_dof={kk: nus[kk] for kk in ks})
|
|
547
|
+
if len(finite_T) > 1 and T_best == finite_T.max():
|
|
548
|
+
warnings.warn('Chosen temperature is the largest finite value in the '
|
|
549
|
+
'grid; consider extending temperature_grid.',
|
|
550
|
+
RuntimeWarning, stacklevel=2)
|
|
551
|
+
if isinstance(k, str) and k_best == max(ks) and len(ks) > 1:
|
|
552
|
+
warnings.warn('Chosen k is the largest value in k_grid; consider '
|
|
553
|
+
'extending it.', RuntimeWarning, stacklevel=2)
|
|
554
|
+
return out
|
|
555
|
+
|
|
556
|
+
# -- reporting -----------------------------------------------------------
|
|
557
|
+
|
|
558
|
+
def summary(self):
|
|
559
|
+
"""Human-readable summary: k, T, ν, and the CV table (if any)."""
|
|
560
|
+
lines = [f'LowRankNoise: {self.n_voxels} voxels, k = {self.k}, '
|
|
561
|
+
f'temperature T = {self.temperature:g}, '
|
|
562
|
+
f'dof = {"Gaussian" if self.dof is None else f"{self.dof:.3g}"}']
|
|
563
|
+
common = (self.factors ** 2).sum(1)
|
|
564
|
+
lines.append(f' mean shared (factor) variance fraction = '
|
|
565
|
+
f'{np.mean(common / (common + self.psi)):.3f}; '
|
|
566
|
+
f'psi at floor: {np.mean(self.psi <= getattr(self, "psi_floor", 0) + 1e-12):.1%}')
|
|
567
|
+
if self.cv_scores_ is not None:
|
|
568
|
+
cv = self.cv_scores_
|
|
569
|
+
info = self.cv_info_
|
|
570
|
+
lines.append(f' chosen by {info["n_groups"]}-group nested CV on '
|
|
571
|
+
f'{info["n_trials"]} trials, {info["n_stimuli"]} grid points; '
|
|
572
|
+
f'inner parameters: {info["inner_parameters"]}')
|
|
573
|
+
lines.append(' CV score = mean held-out log p(true stimulus) − log(1/n_stimuli), nats/trial')
|
|
574
|
+
best_T = cv.idxmax(axis=1)
|
|
575
|
+
tab = pd.DataFrame({'best_T': best_T, 'score_at_best_T': cv.max(axis=1)})
|
|
576
|
+
if 1.0 in cv.columns:
|
|
577
|
+
tab['score_at_T=1'] = cv[1.0]
|
|
578
|
+
lines.append(tab.to_string(float_format=lambda x: f'{x:.4g}'))
|
|
579
|
+
return '\n'.join(lines)
|
|
580
|
+
|
|
581
|
+
def __repr__(self):
|
|
582
|
+
return (f'LowRankNoise(n_voxels={self.n_voxels}, k={self.k}, '
|
|
583
|
+
f'temperature={self.temperature:g}, dof={self.dof})')
|
|
584
|
+
|
|
585
|
+
|
|
586
|
+
# ---------------------------------------------------------------------------
|
|
587
|
+
# module-level helpers
|
|
588
|
+
# ---------------------------------------------------------------------------
|
|
589
|
+
|
|
590
|
+
def _subset(x, idx):
|
|
591
|
+
if isinstance(x, (pd.DataFrame, pd.Series)):
|
|
592
|
+
return x.iloc[idx]
|
|
593
|
+
return np.asarray(x)[idx]
|
|
594
|
+
|
|
595
|
+
|
|
596
|
+
def _grid_predictions(model, grid, parameters, weights=None):
|
|
597
|
+
"""Model prediction for every grid stimulus, (n_stimuli, V) float64.
|
|
598
|
+
|
|
599
|
+
Same code path as ``EncodingModel.get_stimulus_pdf`` (each grid point is
|
|
600
|
+
a separate batch, so HRF models are not convolved across the grid).
|
|
601
|
+
"""
|
|
602
|
+
return model.predict_stimulus_grid(grid, parameters=parameters, weights=weights)
|
|
603
|
+
|
|
604
|
+
|
|
605
|
+
def fit_lowrank_omega(residuals, k=40, dof='fit', psi_floor=0.02):
|
|
606
|
+
"""Functional / legacy path: dense ``(omega, dof)`` of a low-rank fit.
|
|
607
|
+
|
|
608
|
+
Drop-in replacement for the ``(omega, dof)`` returned by
|
|
609
|
+
``ResidualFitter.fit`` (pass them as ``omega=`` / ``dof=``). Prefer
|
|
610
|
+
:class:`LowRankNoise` for large V (no dense matrix) and for choosing
|
|
611
|
+
``k`` and the temperature by cross-validation.
|
|
612
|
+
"""
|
|
613
|
+
return LowRankNoise.from_residuals(residuals, k=k, dof=dof,
|
|
614
|
+
psi_floor=psi_floor).to_dense()
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
from .weight_fitter import WeightFitter
|
|
2
|
+
from .parameter_fitter import ParameterFitter
|
|
3
|
+
from .residual_fitter import ResidualFitter
|
|
4
|
+
try:
|
|
5
|
+
from .stimulus_fitter import (StimulusFitter, CustomStimulusFitter,
|
|
6
|
+
SzinteStimulus, SzinteStimulus2,
|
|
7
|
+
make_aperture_stimuli)
|
|
8
|
+
_STIMULUS_FITTERS = ['StimulusFitter', 'CustomStimulusFitter', 'SzinteStimulus',
|
|
9
|
+
'SzinteStimulus2', 'make_aperture_stimuli']
|
|
10
|
+
except ImportError as _error:
|
|
11
|
+
_STIMULUS_FITTERS = []
|
|
12
|
+
_stimulus_fitter_error = _error
|
|
13
|
+
|
|
14
|
+
def __getattr__(name):
|
|
15
|
+
if name in ('StimulusFitter', 'CustomStimulusFitter', 'SzinteStimulus',
|
|
16
|
+
'SzinteStimulus2', 'make_aperture_stimuli'):
|
|
17
|
+
raise ImportError(
|
|
18
|
+
f'{name} needs TensorFlow and tensorflow-probability '
|
|
19
|
+
f'({_stimulus_fitter_error}).')
|
|
20
|
+
raise AttributeError(f'module {__name__!r} has no attribute {name!r}')
|
|
21
|
+
|
|
22
|
+
__all__ = ['WeightFitter', 'ParameterFitter', 'ResidualFitter'] + _STIMULUS_FITTERS
|