ncrf.fit_ncrf

ncrf.fit_ncrf(meg, stim, lead_field, noise, tstart=0, tstop=0.5, basis_stride=1, n_iter=10, n_iterc=10, n_iterf=100, scale='spectral', mu='auto', tol=0.001, verbose=False, n_splits=3, n_workers=None, use_ES=False, basis_std=0.0085, solver=None, compute_explained_variance=False)

One shot function for cortical TRF localization.

Estimate both TRFs and source variance from the observed MEG data by solving the Bayesian optimization problem mentioned in [Das et al., 2020].

Parameters:
  • meg – Observed data. A single contiguous segment can be passed as an eelbrain.NDVar with sensor and time dimensions, equal-length trials can be packed into an NDVar with a case dimension, and unequal-length segments can be supplied as a sequence (e.g., list of eelbrain.NDVar).

  • stim – One or more predictors corresponding to each item in meg. Predictors can be supplied as one NDVar per segment or as nested sequences when each segment has multiple predictors. Individual predictors may have only a time axis or one additional feature dimension before time.

  • lead_field – Forward solution a.k.a. lead-field matrix.

  • noise – Empty-room noise covariance, either directly as mne.Covariance or as an eelbrain.NDVar from which a covariance will be estimated. Channels are matched by name: the noise channels must be a subset of the lead field’s channels, and the meg channels must in turn be covered by the noise; the model is fit on the meg channels.

  • tstart – Start of the TRF in seconds. A scalar applies to all predictors; a sequence specifies one start time per predictor.

  • tstop – Stop of the TRF in seconds. A scalar applies to all predictors; a sequence specifies one stop time per predictor.

  • basis_stride – Spacing between neighboring Gabor atoms, in samples: with the default of 1 the atoms are one sample apart, and larger values make the basis sparser. basis_stride > 2 should be used with caution.

  • n_iter – Number of outer iterations of the algorithm, by default set to 10.

  • n_iterc – Number of Champagne iterations within each outer iteration, by default set to 10.

  • n_iterf – Number of FASTA iterations within each outer iteration, by default set to 100.

  • scale – Normalization applied before model fitting: each predictor’s mean is subtracted, and the covariates are divided by the 'l2' (standard deviation of stim), 'l1' (mean absolute deviation of stim) or 'spectral' (average spectral norm of the covariates, which equalizes covariate scales across predictor variables; the default) scale. Use None to leave the covariates on their raw scale. h_scaled undoes the scaling, whichever one is used.

  • mu – Choice of regularizer parameters. Pass a single value to fit one model, a sequence to cross-validate over an explicit grid, or 'auto' to derive a search range from the data.

  • tol – Tolerance factor deciding stopping criterion for the overall algorithm. The iterations are stooped when norm(trf_new - trf_old)/norm(trf_old) < tol condition is met. By default tol=1e-3.

  • verbose – If True prints intermediate results, by default False.

  • n_splits – Number of cross-validation folds. By default it uses 3-fold cross-validation.

  • n_workers – Number of worker processes for cross-validation. If None, derive it from Eelbrain’s n_workers setting (see eelbrain.configure()). Set to 0 to run without multiprocessing, for debugging.

  • use_ES – Use estimation stability criterion [Lim and Yu, 2016] to choose the best mu. (False by default, see ChampLasso).

  • basis_std – Standard deviation of the Gaussian basis atoms in seconds (default 0.0085, approximately 20 ms FWHM). The standard deviation (std) is related to the fwmh by: \(std = fwhm / (2 * (sqrt(2 * log(2))))\).

  • solver – Solver configuration. When supplied, mu, use_ES, tol and the iteration arguments are ignored; configure them on the solver. n_splits and n_workers still configure the folds a searching solver is scored on.

  • compute_explained_variance – Compute explained variance by source/voxel.

Returns:

Fit report. The fitted, reusable model is NCRFFit.model (an NCRF); the response functions are result.model.h / result.model.h_scaled, and metrics for an arbitrary dataset are result.model.evaluate(data). Training-set metrics (scores, voxelwise_explained_variance), solver state (solver_fit, including solver_fit.history), and cv_info() live on the result itself.

Return type:

NCRFFit

Examples

MEG data y with dimensions (case, sensor, time) and predictor x with dimensions (case, time):

fit_ncrf(y, x, fwd, cov)

x can always also have an additional predictor dimension, for example, if x represents a spectrogram: (case, frequency, time). The case dimension is optional, i.e. a single contiguous data segment is also accepted, but the case dimension should always match between y and x.

Multiple distinct predictor variables can be supplied as list; e.g., when modeling simultaneous responses to an attended and an unattended stimulus with x_attended and x_unattended:

fit_ncrf(y, [x_attended, x_unattended], fwd, cov)

Multiple data segments can also be specified as list. E.g., if y1 and y2 are responses to stimuli x1 and x2, respoectively:

fit_ncrf([y1, y2], [x1, x2], fwd, cov)

And with multiple predictors:

fit_ncrf([y1, y2], [[x1_attended, x1_unattended], [x2_attended, x2_unattended]], fwd, cov)

For complete workflows, see the gallery examples Volume Source Example and Surface source Example.

References

[DBSB20]

Proloy Das, Christian Brodbeck, Jonathan Z Simon, and Behtash Babadi. Neuro-current response functions: A unified approach to MEG source analysis under the continuous stimuli paradigm. NeuroImage, pages 116528, 2020. Publisher: Elsevier. doi:10.1016/j.neuroimage.2020.116528.

[LY16]

Chinghway Lim and Bin Yu. Estimation Stability With Cross-Validation (ESCV). Journal of Computational and Graphical Statistics, 25(2):464–492, April 2016. URL: https://www.tandfonline.com/doi/full/10.1080/10618600.2015.1020159 (visited on 2025-05-13), doi:10.1080/10618600.2015.1020159.

[TBM+11]

François Tadel, Sylvain Baillet, John C. Mosher, Dimitrios Pantazis, and Richard M. Leahy. Brainstorm: a user-friendly application for meg/eeg analysis. Computational Intelligence and Neuroscience, 2011(1):879716, 2011. URL: https://onlinelibrary.wiley.com/doi/abs/10.1155/2011/879716, arXiv:https://onlinelibrary.wiley.com/doi/pdf/10.1155/2011/879716, doi:https://doi.org/10.1155/2011/879716.