ncrf.fit_ncrf

ncrf.fit_ncrf(meg, stim, lead_field, noise, tstart=0, tstop=0.5, nlevels=1, n_iter=10, n_iterc=10, n_iterf=100, normalize=False, in_place=False, mu='auto', tol=0.001, verbose=False, n_splits=3, n_workers=None, use_ES=False, basis_std=0.0085, do_post_normalization=True)

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, as an eelbrain.NDVar from which a covariance will be estimated, or as an already aligned covariance matrix. Covariance inputs are checked against the MEG sensor order and raise an error when sensors are missing or the shape is wrong.

  • 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.

  • nlevels – Decides the density of Gabor atoms. Bigger nlevel -> less dense basis. By default it is set to 1. nlevel > 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.

  • normalize – Scale stim before model fitting: subtract the mean and divide by the standard deviation (when normalize='l2' or normalize=True) or the mean absolute value (when normalize='l1'). By default, normalize=False leaves stim data untouched.

  • in_place – By default, meg and stim are copied to make them independent of the objects supplied to the function. Set to True to skip the copy and modify them in place, saving memory when working with large datasets.

  • 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 workers to spawn for cross-validation. If None, it will use cpu_count/2.

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

  • 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))))\).

  • do_post_normalization – Scales covariate matrices of different predictor variables by spectral norms to equalize their spectral spread (=1). (default True)

Returns:

Fitted model instance.

Return type:

NCRF

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.