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:

  • RegressionData holds the sensor data and predictors together with the design, and derives the arrays the solver consumes from them.

  • NCRFEstimator owns the forward model and whitening transform, selects a solver candidate through cross-validation, and runs the final fit.

  • Solver implementations, such as ChampLasso, define optimization and candidate-selection behavior.

  • NCRFFit provides access to the reusable NCRF model 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:

model

The fitted NCRF, including coefficients, forward state, TRF reconstruction, prediction, and solver-independent evaluation.

solver

The fixed solver configuration selected for the final fit.

solver_fit

Solver-specific fitted state and iteration diagnostics.

scores

Training-set prediction metrics plus any scores contributed by the solver.

voxelwise_explained_variance

Optional source-wise training diagnostic.

execution_context

When, 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.