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.NDVarwithsensorandtimedimensions, equal-length trials can be packed into an NDVar with acasedimension, and unequal-length segments can be supplied as a sequence (e.g.,listofeelbrain.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 atimeaxis or one additional feature dimension beforetime.lead_field – Forward solution a.k.a. lead-field matrix.
noise – Empty-room noise covariance, either directly as
mne.Covarianceor as aneelbrain.NDVarfrom 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 themegchannels must in turn be covered by the noise; the model is fit on themegchannels.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
1the atoms are one sample apart, and larger values make the basis sparser.basis_stride > 2should 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 ofstim),'l1'(mean absolute deviation ofstim) or'spectral'(average spectral norm of the covariates, which equalizes covariate scales across predictor variables; the default) scale. UseNoneto leave the covariates on their raw scale.h_scaledundoes 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) < tolcondition is met. By defaulttol=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’sn_workerssetting (seeeelbrain.configure()). Set to0to run withoutmultiprocessing, for debugging.use_ES – Use estimation stability criterion [Lim and Yu, 2016] to choose the best
mu. (Falseby default, seeChampLasso).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,toland the iteration arguments are ignored; configure them on the solver.n_splitsandn_workersstill 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(anNCRF); the response functions areresult.model.h/result.model.h_scaled, and metrics for an arbitrary dataset areresult.model.evaluate(data). Training-set metrics (scores,voxelwise_explained_variance), solver state (solver_fit, includingsolver_fit.history), andcv_info()live on the result itself.- Return type:
Examples
MEG data
ywith dimensions (case, sensor, time) and predictorxwith dimensions (case, time):fit_ncrf(y, x, fwd, cov)
xcan always also have an additional predictor dimension, for example, ifxrepresents 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 betweenyandx.Multiple distinct predictor variables can be supplied as list; e.g., when modeling simultaneous responses to an attended and an unattended stimulus with
x_attendedandx_unattended:fit_ncrf(y, [x_attended, x_unattended], fwd, cov)
Multiple data segments can also be specified as list. E.g., if
y1andy2are responses to stimulix1andx2, 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.