Changes¶
0.5¶
Bug fixes¶
Free-orientation fits used a broken convergence check. A bug in the group sparsity penalty pinned one of the inner solver’s two convergence measures at a constant value, so the inner iterations could only ever stop on the other one. TRF estimates from free-orientation source spaces therefore change; fixed-orientation fits are unaffected.
Source-wise explained variance was wrong for data with more than one segment.
voxelwise_explained_variance()reused onethetascratch buffer across segments without resetting it, so from the second segment on the baseline residual was computed with the last source’s weights still zeroed, corrupting every per-source value.``use_ES=True`` depended on the order in which workers returned. The guard for “the cross-fit winner is already the largest
mu” compared it with the last element of the unordered result list instead of the largestmu, so estimation-stability refinement was skipped or applied inconsistently from run to run. Selection is now order-independent, and themugrid is extended before the criterion is applied, so it sees the complete search range.:attr:`ncrf.NCRF.h_scaled` undid the covariate scaling in the wrong direction. The covariates are divided by the scale, so restoring stimulus units requires dividing
hby it as well, buth_scaledmultiplied instead. Values obtained withnormalize='l1'ornormalize='l2'were therefore off by the square of the scale factor.Data whose sensors do not match the lead field is now rejected. The whitening filter and the lead field are indexed by channel position, so data with the same channels in a different order was silently attributed to the wrong channels.
fit_ncrf()aligned the lead field itself, but the component API did not.
Major API changes¶
Fitting and the fitted model¶
Fitting is separated into a reusable fitted model, an estimator that owns the forward model, and a pluggable optimization algorithm (see Architecture).
fit_ncrf()returns anNCRFFitreport rather than a fittedNCRF. The reusable model ismodel.NCRFis now the fitted model: coefficients, forward state and design, withpredict(),evaluate()andvoxelwise_explained_variance(). Fitting moved toNCRFEstimator, which is constructed from the lead field and noise covariance. Code doingNCRF(lead_field, noise_covariance).fit(data)becomesNCRFEstimator.from_lead_field(lead_field, noise_covariance).fit(data, solver).The optimization algorithm is a
Solver, configured independently of the data and the forward model.ChampLassoimplements the published algorithm and carriesmu, the iteration counts,tolanduse_es. It also owns themusearch, son_iter,n_iterc,n_iterf,tol,muanduse_ESonfit_ncrf()are ignored when asolveris passed.Cross-validation folds are configured with
CrossValidation, and each candidate’s held-out scores are returned asCVResult.The model metadata that used to live on the fitted object is now a
TRFDesign, and the forward state aForwardModel.
Attributes of the old fitted model map onto the fit report as follows:
0.4 |
0.5 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Because the fitted object was restructured, models pickled with earlier versions can no longer be loaded.
Sensor handling¶
Channels are now matched strictly by name, and the three channel sets must be
nested: lead field ⊇ noise covariance ⊇ data. The estimator stores the lead
field and noise covariance in full and derives the whitened forward model for
exactly the data’s channels when fitting; a data channel missing from the
noise covariance or the lead field, or a noise channel without a lead field,
is an error naming the offending input. Because channel identity is required
for this matching, noise must be an mne.Covariance or an
eelbrain.NDVar; a plain numpy.ndarray is no longer accepted.
Applying a model to new data¶
A fitted NCRF can be applied to any compatible dataset:
predict() returns predictions in the units of the M/EEG data,
and evaluate() scores them in whitened sensor space with one or
more metrics (explained_variance(), l2_error(), or a
custom one). The new data has to carry the training data’s normalization; apply
normalize() with the model’s design (see
Guide).
Normalization¶
Normalization is now owned by RegressionData and checked when a
fitted model is applied to new data (see Guide).
fit_ncrf()andfrom_data()take a singlescaleargument instead ofnormalizeanddo_post_normalization/post_normalize, which were not independent (post-normalization cancelled out'l1'/'l2'scaling):normalizedo_post_normalizationnow
False(default)True(default)scale='spectral'(default)'l1'/'l2'Truescale='spectral''l1'/'l2'Falsescale='l1'/'l2'FalseFalsescale=NoneEvery
scalealso subtracts each predictor’s mean. Previously the mean was only subtracted withnormalize, so the default fit scaled the covariates without centering the predictors; it now centers them.Normalization is applied to the covariates rather than to
stim, which is never modified.The
in_placeargument offit_ncrf()is removed.megandstimare neither modified nor copied:RegressionDatakeeps references to the NDVars and derives the arrays the solver consumes from them (so they must not be modified in place while it is in use).ncrf.NCRF.h_scalednow also undoes spectral scaling; previouslyhfrom a post-normalized fit was not in stimulus units. (The direction of the correction was also wrong; see Bug fixes.)Spectral scaling is now also applied to data with a single covariate channel, which changes the scale of
h(but not ofh_scaled) for such fits. Sincemuregularizes coefficients on the covariate scale, values tuned before this change are not comparable for those fits.The
'spectral'norm is measured on centered covariates, so its value differs slightly from the post-normalization factor of earlier versions.With
pad_stim=True, the zero-padded edge rows now represent a raw stimulus of 0: normalization subtracts the same constant offset from every covariate row, including rows whose lag window extends beyond the data. Previously the stimulus itself was centered before padding, so the padding represented the mean stimulus; edge-row covariates, and hence the fitted TRFs, differ for such fits.
The TRF basis¶
nlevels/nlevelis renamed tobasis_strideonfit_ncrf()andfrom_data(). The meaning is unchanged: it is the spacing between neighboring Gabor atoms, in samples.The value is recorded as
ncrf.TRFDesign.basis_stride; it isNonefor a design constructed directly with a custombasis, which no single stride describes.
Implementation¶
NCRF no longer contains compiled extensions and installs without a compiler. The free-orientation proximal operator and the Champagne covariance update, previously per-source loops over Cython kernels, are vectorized over sources with NumPy; the Champagne iterations are about four times faster.
ncrf.ChampLassoFit.gammaholds one array of shape(n_sources, dc, dc)per segment instead of a list of per-source matrices.