mne.gui.dipolefit

mne.gui.dipolefit(evoked, *, baseline=None, cov=None, bem=None, initial_time=None, trans=None, stc=None, subject=None, subjects_dir=None, surf_maps=None, rank='info', show_density=True, ch_type=None, show_sensors=True, n_jobs=None, show=True, block=False, verbose=None)

GUI for interactive dipole fitting, inspired by MEGIN’s XFit program.

Parameters:

evokedinstance of Evoked | path-like | None

Evoked data to show fieldmap of and fit dipoles to.

baselineNone | tuple of length 2

The time interval to consider as “baseline” when applying baseline correction. If None, do not apply baseline correction. If a tuple (a, b), the interval is between a and b (in seconds), including the endpoints. If a is None, the beginning of the data is used; and if b is None, it is set to the end of the data. If (None, None), the entire time interval is used.

Note

The baseline (a, b) includes both endpoints, i.e. all timepoints t such that a <= t <= b.

Correction is applied to each channel individually in the following way:

1. Calculate the mean signal of the baseline period.

2. Subtract this mean from the entire Evoked.

covinstance of Covariance | path-like | “baseline” | None

Noise covariance matrix. If None, an ad-hoc covariance matrix is used with default values for the diagonal elements (see Notes). If "baseline", the diagonal elements is estimated from the baseline period of the evoked data.

beminstance of ConductorModel | path-like | None

Boundary element model to use in forward calculations, or a path to the BEM solution file ("-bem-sol.fif") to read it from. If None, a spherical model is used.

initial_timefloat | None

Initial time point to show. If None, the time point of the maximum field strength is used.

transinstance of Transform | path-like | None

The transformation from head coordinates to MRI coordinates. If None, the identity matrix is used and everything will be done in head coordinates.

stcinstance of SourceEstimate | path-like | None

An optional distributed source estimate to show alongside the fieldmap. The time samples need to match those of the evoked data.

subjectstr | None

The subject name. If None, no MRI data is shown.

subjects_dirpath-like | None

The path to the directory containing the FreeSurfer subjects reconstructions. If None, defaults to the SUBJECTS_DIR environment variable.

surf_mapslist | None

The surface mapping information obtained with make_field_map. If None, one will be generated based on the given data.

rankNone | ‘info’ | ‘full’ | dict

This controls the rank computation that can be read from the measurement info or estimated from the data. When a noise covariance is used for whitening, this should reflect the rank of that covariance, otherwise amplification of noise components can occur in whitening (e.g., often during source localization).

None

The rank will be estimated from the data after proper scaling of different channel types.

'info'

The rank is inferred from info. If data have been processed with Maxwell filtering, the Maxwell filtering header is used. Otherwise, the channel counts themselves are used. In both cases, the number of projectors is subtracted from the (effective) number of channels in the data. For example, if Maxwell filtering reduces the rank to 68, with two projectors the returned value will be 66.

'full'

The rank is assumed to be full, i.e. equal to the number of good channels. If a Covariance is passed, this can make sense if it has been (possibly improperly) regularized without taking into account the true data rank.

dict

Calculate the rank only for a subset of channel types, and explicitly specify the rank for the remaining channel types. This can be extremely useful if you already know the rank of (part of) your data, for instance in case you have calculated it earlier.

This parameter must be a dictionary whose keys correspond to channel types in the data (e.g. 'meg', 'mag', 'grad', 'eeg'), and whose values are integers representing the respective ranks. For example, {'mag': 90, 'eeg': 45} will assume a rank of 90 and 45 for magnetometer data and EEG data, respectively.

The ranks for all channel types present in the data, but not specified in the dictionary will be estimated empirically. That is, if you passed a dataset containing magnetometer, gradiometer, and EEG data together with the dictionary from the previous example, only the gradiometer rank would be determined, while the specified magnetometer and EEG ranks would be taken for granted.

show_densitybool

Whether to show the density of the fieldmap.

ch_type“meg” | “eeg” | None

Type of channels to use for the dipole fitting. By default (None) both MEG and EEG channels will be used.

show_sensorsbool

Whether to show the sensors in the 3D view.

n_jobsint | None

The number of jobs to run in parallel. If -1, it is set to the number of CPU cores. Requires the joblib package. None (default) is a marker for ‘unset’ that will be interpreted as n_jobs=1 (sequential execution) unless the call is performed under a joblib.parallel_config context manager that sets another value for n_jobs.

showbool

Show the GUI if True.

blockbool

Whether to halt program execution until the figure is closed.

verbosebool | str | int | None

Control verbosity of the logging output. If None, use the default verbosity level. See the logging documentation and mne.verbose() for details. Should only be passed as a keyword argument.

Returns:

fitterinstance of DipoleFitUI

The dipole fitting GUI. The .dipoles attribute contains the fitted dipoles.

Notes

New in v1.12.

When using cov=None the default noise values are 5 fT/cm, 20 fT, and 0.2 µV for gradiometers, magnetometers, and EEG channels respectively.

Here is an incomplete comparison between the features of the MEGIN XFit™ 5.5.18 software and the MNE interactive dipole fitting GUI:

Feature	MNE	Xfit
Head model
Use spherical head model	✓	✓
Use BEM head model based on MRI	✓	✓
Use ad-hoc covariance matrix	✓	✓
Estimate covariance from baseline period	✓	✓
Dipole fitting
Fit a dipole at the current time	✓	✓
Fit a dipole by averaging the signal over a time range		✓
Fit dipoles on a subset of sensors, selected from the sensor view	✓	✓
Fit multiple dipoles and construct a multi-dipole model	✓	✓
Toggle individual dipoles on or off in the multi-dipole model	✓	✓
Give names to dipoles	✓
Save dipoles to .dip or .bdip file	✓	✓
View source timecourses	✓	✓
View total variance explained by the dipole model		✓
View detailed dipole information (coordinates, goodness of fit, etc.)		✓
Toggle dipoles to have a free or fixed orientation	✓	✓
Project-out signals from dipoles currently in the model		✓
3D view
View magnetic field patterns for Evokeds	✓	✓
Show head surface in relation to the MEG helmet	✓	✓
Show brain surfaces inside the head surface	✓
Show MNE source estimate to guide dipole fitting	✓
Show location of the dipoles in the 3D view	✓
Show dipole projected to the helmet (big arrows)	✓	✓
Show currently selected sensors in the 3D view	✓
Only show magnetic field patterns as seen by the currently selected sensors		✓
Sensor view
View sensor-level timecourses	✓	✓
Switch layouts (all, grads, mags, eeg) in the sensor display		✓
Overlay reconstructed sensor time courses from the dipole model		✓

Examples using mne.gui.dipolefit

Source localization by guided equivalent current dipole (ECD) fitting

Source localization by guided equivalent current dipole (ECD) fitting