mne.gui.dipolefit#

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

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.

Defaults to (None, 0), i.e. beginning of the the data until time point zero.

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

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.

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

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.

Examples using mne.gui.dipolefit#

Source localization by guided equivalent current dipole (ECD) fitting

Source localization by guided equivalent current dipole (ECD) fitting