Guide¶
The simplest entry point is ncrf.fit_ncrf(), which accepts Eelbrain
NDVar objects, prepares the regression design, selects a
regularization value when needed, and returns a structured fit report:
from ncrf import fit_ncrf
result = fit_ncrf(
meg,
stim,
lead_field,
noise,
mu="auto",
tstop=1.0,
n_splits=3,
)
trf = result.model.h
training_scores = result.scores
The fitted NCRF in result.model is independent of the
optimizer that produced it. It can predict or evaluate another compatible
RegressionData dataset. Optimization diagnostics remain in
result.solver_fit, and cross-validation results can be inspected with
cv_info().
Normalization¶
The covariates that an NCRF is fit against can be centered and scaled.
RegressionData handles this normalization: the values are recorded
on its design and applied whenever the covariates are built from the
predictors, and from_data() derives them from the data.
Each predictor’s mean is subtracted, and each covariate channel is
divided by a scaling factor, determined through the scale argument:
'spectral'(the default): the average spectral norm of the channel’s covariates. This equalizes covariate scales across predictor variables, so that one regularization parameter is appropriate for all of them.'l1'/'l2': the predictor’s mean absolute deviation or standard deviation.None: leave the covariates on their raw scale, without centering.
The centering and the 'l1'/'l2' factors are properties of the predictor,
and are measured on all of its samples. The 'spectral' norm is a property of
the covariates that were built from it, and is measured on the samples that carry
a complete lag window.
Centering and scaling are a single choice because they only make sense together.
M/EEG data is high-pass filtered, so an uncentered predictor’s mean would
contribute a constant mean * sum(h) to the prediction, which the fit has to
reconcile with zero-mean data – in effect constraining the response function to
sum to zero. And the scale factors measure variation around the mean rather than
raw magnitude, since a predictor’s offset would otherwise dominate its scale and
leave its variation over-regularized.
h is in units of the normalized covariates.
h_scaled restores the original stimulus scale,
and is the appropriate representation for comparing response
functions across predictors or across models.
Applying a model to new data¶
A fitted model can only be applied to covariates on the scale it was fit on –
multiplying coefficients learned from (stim - baseline) / scaling with a raw
stimulus would silently produce wrong predictions and scores. New data therefore
has to carry the same normalization as the training data. Apply the model’s own
normalization with normalize():
test_data = RegressionData.from_data(
[test_meg],
[[test_stim]],
tstart=0.0,
tstop=1.0,
stim_is_single=True,
scale=None,
)
test_data = test_data.normalize(result.model.design)
scores = result.model.evaluate(test_data)
Note that this uses the training data’s normalization values, which is what
makes the scores comparable; values derived from the test data would put the
covariates on a different scale. The covariates are built from the raw
predictors, so a dataset can be normalized any number of times with any
compatible design; scale=None merely skips deriving values that
normalize() would replace anyway.
predict(), evaluate() and
voxelwise_explained_variance() raise an error when data
carries a different normalization, or when its design describes different
predictors, TRF timings, or a different basis.
Prediction units¶
predict() returns predictions in the units of the M/EEG data the
dataset was built from, so they can be compared with the original recording
directly.
evaluate() instead scores in whitened sensor space, where the
noise covariance is the identity and channels are therefore comparable (for a
rank-deficient noise covariance this space has only rank channels, see
ForwardModel). This is
the space the solver optimizes in and the one cross-validation compares
candidates in, which is what makes result.scores and the cross-validation
scores commensurable. Pass whitened=True to predict() to see
the predictions the metrics are computed on.