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, gaussian_fwhm=20.0, 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:

megNDVar ([case,] sensor, time) | list[NDVar]

If multiple trials are the same length they can be specified as eelbrain.NDVar with case dimension, if they are different length they can be supplied as list.

stimeelbrain.NDVar ([case, dim,] time) | list[NDVar]

One or multiple predictors corresponding to each item in meg.

lead_fieldNDVar

forward solution a.k.a. lead field matrix.

noisemne.Covariance | NDVar | np.ndarray

The empty room noise covariance as mne.Covariance, or data from which to compute it as eelbrain.NDVar or numpy.ndarray. If supplied as a covariance matrix, the sensors are cross-checked to ensure all the sensors in meg are also present in covaraince matrix, else the check is skipped. Raises error if any sensor is missing in noise covaraince, or in case of shape mismatch.

tstartfloat | list[float]

Start of the TRF in seconds. Can define multiple tstarts for more than 1 predictor.

tstopfloat | list[float]

Stop of the TRF in seconds. Can define multiple tstops for more than 1 predictor.

nlevelsint

Decides the density of Gabor atoms. Bigger nlevel -> less dense basis. By default it is set to 1. nlevesl > 2 should be used with caution.

n_iterint

Number of out iterations of the algorithm, by default set to 10.

n_itercint

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

n_iterfint

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

normalizebool | ‘l2’ | ‘l1’

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

in_place: bool

With in_place=False (default) the original meg and stims are left untouched; use in_place=True to save memory by using the original meg and stim.

mu‘auto’ | float | sequence[float]

Choice of regularizer parameters. Specify a single value to fit a model corresponding to that value. Alternatively, specify a range over which cross-validation will be done. By default (mu='auto') a range of values for cross-validation is chosen based on the data.

tolfloat

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.

verbosebool

If True prints intermediate results, by default False.

n_splitsint

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

n_workersint (optional)

Number of workers to spawn for cross-validation. If None, it will use cpu_count/2.

use_ESbool (optional)

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

gaussian_fwhmfloat (optional)

Specifies the full width half maximum (fwmh) for the Gaussian kernel (used as elements of the time basis), the default is 20 ms. The standard deviation (std) is related to the fwmh as following: \(std = fwhm / (2 * (sqrt(2 * log(2))))\).

do_post_normalizationbool (optional)

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

Returns:

trfNCRF

The result of the model fit.

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.

Examples

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

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:

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:

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

And with multiple predictors:

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