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/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