Architecture¶
Neuro-currentRF separates input preparation, forward-model handling, optimization, and prediction. This keeps the fitted model reusable and allows optimization algorithms to be changed without changing the prediction API.
Pipeline¶
The most important classes are:
RegressionDataholds the sensor data and predictors together with the design, and derives the arrays the solver consumes from them.NCRFEstimatorowns the forward model and whitening transform, selects a solver candidate through cross-validation, and runs the final fit.Solverimplementations, such asChampLasso, define optimization and candidate-selection behavior.NCRFFitprovides access to the reusableNCRFmodel from the selected solver, along with solver-specific fit state, scores, and diagnostics.
The high-level data flow is:
M/EEG + stimulus + lead field + noise
|
v
fit_ncrf
|
+---------+----------+
| |
RegressionData NCRFEstimator
(M/EEG, predictors (forward model and
and TRF design) whitening)
| |
+---------+----------+
|
Solver.search
(optional cross-validation)
|
final solver run
|
v
NCRFFit
+---------+----------+
| |
NCRF SolverFit
(prediction and (optimizer state
reconstructed TRFs) and diagnostics)
fit_ncrf() is the convenience layer. It accepts the supported input
layouts, creates RegressionData, and delegates the fit to
NCRFEstimator.
Data and design¶
RegressionData holds the M/EEG segments and their predictors as
NDVars. Its design records the TRF lags, basis, predictor dimensions and names,
and the covariates’ normalization (stim_baseline and stim_scaling); the
sensor arrays and the lagged, basis-projected covariates the solver consumes are
derived from the raw data and the design on demand. The same compact metadata is stored on
the fitted model, so that NCRF.h can reconstruct labeled source-space TRFs
without retaining the training dataset, and so that the model can check that new
data is on the scale it was fit on.
NCRFEstimator holds a lead field and a sensor noise covariance,
matched by channel name: the noise channels have to be a subset of the lead
field’s channels. At fit time it derives the whitened forward model for exactly
the sensors of the data, since whitening is not separable per channel; a data
channel missing from the lead field or the noise covariance is an error. The
derived forward model is attached to the whitened RegressionData,
and the fitted NCRF retains it to apply the same transform when
predicting.
Solvers and cross-validation¶
A Solver is a configuration for estimating the coefficient
matrix (the NCRF). A solver that has more than one configuration to choose from
selects one in search(), using a CrossValidation
configuration describing the folds.
ChampLasso uses it to score its mu grid, extend the
grid when the winner is on a boundary, and apply the estimation-stability
criterion. The estimator then fits the selected configuration on all of the data.
The generic SolverFit contains the fitted coefficient matrix;
concrete solvers can add algorithm-specific state and scores. For example,
ChampLasso adds its covariance estimates and iteration history.
These details remain in ncrf.NCRFFit.solver_fit rather than becoming
part of the predictive model.
Lower-level fitting¶
Use the component API when data preparation and solver configuration need to be controlled independently:
from ncrf import ChampLasso, CrossValidation, NCRFEstimator, RegressionData
data = RegressionData.from_data(
[meg],
[[stim]],
tstart=0.0,
tstop=1.0,
stim_is_single=True,
)
estimator = NCRFEstimator.from_lead_field(lead_field, noise_covariance)
solver = ChampLasso(mu="auto", n_iter=30, n_iterc=10, n_iterf=100)
result = estimator.fit(
data,
solver,
cv=CrossValidation(n_splits=3),
)
With a numeric mu, ChampLasso exposes a single candidate and
the cross-validation step is skipped.
Model and fit report¶
NCRFFit is the report for one fit. Its main attributes have
deliberately separate lifetimes and responsibilities:
modelThe fitted
NCRF, including coefficients, forward state, TRF reconstruction, prediction, and solver-independent evaluation.solverThe fixed solver configuration selected for the final fit.
solver_fitSolver-specific fitted state and iteration diagnostics.
scoresTraining-set prediction metrics plus any scores contributed by the solver.
voxelwise_explained_varianceOptional source-wise training diagnostic.
execution_contextWhen, how long and in which environment the fit ran (
NCRFExecutionContext).
To evaluate new data, prepare it with the same predictor layout, time step, and TRF settings, and apply the training-data normalization to it (see Guide):
test_data = test_data.normalize(result.model.design)
predictions = result.model.predict(test_data)
scores = result.model.evaluate(test_data)
ncrf.NCRF.predict() returns predictions in the units of the M/EEG data
(pass whitened=True for the space the model is fit in), whereas metrics are
computed in whitened sensor space (see Guide). Calling
ncrf.NCRF.evaluate() with several metrics predicts the dataset only once.