mne.Dipole#

class mne.Dipole(times, pos, amplitude, ori, gof, name=None, conf=None, khi2=None, nfree=None, *, verbose=None)[source]#

Dipole class for sequential dipole fits.

Note

This class should usually not be instantiated directly, instead mne.read_dipole() should be used.

Used to store positions, orientations, amplitudes, times, goodness of fit of dipoles, typically obtained with Neuromag/xfit, mne_dipole_fit or certain inverse solvers. Note that dipole position vectors are given in the head coordinate frame.

Parameters

timesarray, shape (n_dipoles,): The time instants at which each dipole was fitted (sec).
posarray, shape (n_dipoles, 3): The dipoles positions (m) in head coordinates.
amplitudearray, shape (n_dipoles,): The amplitude of the dipoles (Am).
oriarray, shape (n_dipoles, 3): The dipole orientations (normalized to unit length).
gofarray, shape (n_dipoles,): The goodness of fit.
namestr | None: Name of the dipole.
confdict: Confidence limits in dipole orientation for “vol” in m^3 (volume), “depth” in m (along the depth axis), “long” in m (longitudinal axis), “trans” in m (transverse axis), “qlong” in Am, and “qtrans” in Am (currents). The current confidence limit in the depth direction is assumed to be zero (although it can be non-zero when a BEM is used).

New in version 0.15.
khi2array, shape (n_dipoles,): The χ^2 values for the fits.

New in version 0.15.
nfreearray, shape (n_dipoles,): The number of free parameters for each fit.

New in version 0.15.
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.

See also

fit_dipole
DipoleFixed
read_dipole

Notes

This class is for sequential dipole fits, where the position changes as a function of time. For fixed dipole fits, where the position is fixed as a function of time, use mne.DipoleFixed.

Attributes

verbose

Methods

`__getitem__`(item)	Get a time slice.
`__len__`()	Return the number of dipoles.
`copy`()	Copy the Dipoles object.
`crop`([tmin, tmax, include_tmax])	Crop data to a given time interval.
`plot_amplitudes`([color, show])	Plot the dipole amplitudes as a function of time.
`plot_locations`(trans, subject[, ...])	Plot dipole locations in 3d.
`save`(fname[, overwrite, verbose])	Save dipole in a .dip or .bdip file.
`to_mni`(subject, trans[, subjects_dir, verbose])	Convert dipole location from head to MNI coordinates.
`to_mri`(subject, trans[, subjects_dir, verbose])	Convert dipole location from head to MRI surface RAS coordinates.
`to_volume_labels`(trans[, subject, aseg, ...])	Find an ROI in atlas for the dipole positions.

__getitem__(item)[source]#

Get a time slice.

Parameters

itemarray-like or slice: The slice of time points to use.

Returns

dipinstance of Dipole: The sliced dipole.

__len__()[source]#

Return the number of dipoles.

Returns

lenint: The number of dipoles.

Examples

This can be used as:

>>> len(dipoles)  
10

copy()[source]#

Copy the Dipoles object.

Returns

dipinstance of Dipole: The copied dipole instance.

crop(tmin=None, tmax=None, include_tmax=True)[source]#

Crop data to a given time interval.

Parameters

tminfloat | None: Start time of selection in seconds.
tmaxfloat | None: End time of selection in seconds.
include_tmaxbool: If True (default), include tmax. If False, exclude tmax (similar to how Python indexing typically works).

New in version 0.19.

Returns

selfinstance of Dipole: The cropped instance.

Examples using crop:

Compute MxNE with time-frequency sparse prior

plot_amplitudes(color='k', show=True)[source]#

Plot the dipole amplitudes as a function of time.

Parameters

colormatplotlib color: Color to use for the trace.
showbool: Show figure if True.

Returns

figmatplotlib.figure.Figure: The figure object containing the plot.

plot_locations(trans, subject, subjects_dir=None, mode='orthoview', coord_frame='mri', idx='gof', show_all=True, ax=None, block=False, show=True, scale=0.005, color=(1.0, 0.0, 0.0), fig=None, verbose=None, title=None)[source]#

Plot dipole locations in 3d.

Parameters

transdict: The mri to head trans.
subjectstr: The subject name corresponding to FreeSurfer environment variable SUBJECT.
subjects_dirpath-like | None: The path to the directory containing the FreeSurfer subjects reconstructions. If None, defaults to the SUBJECTS_DIR environment variable.
modestr: Can be 'arrow', 'sphere' or 'orthoview'.

New in version 0.14.0.
coord_framestr: Coordinate frame to use, ‘head’ or ‘mri’. Defaults to ‘mri’.

New in version 0.14.0.
idxint | ‘gof’ | ‘amplitude’: Index of the initially plotted dipole. Can also be ‘gof’ to plot the dipole with highest goodness of fit value or ‘amplitude’ to plot the dipole with the highest amplitude. The dipoles can also be browsed through using up/down arrow keys or mouse scroll. Defaults to ‘gof’. Only used if mode equals ‘orthoview’.

New in version 0.14.0.
show_allbool: Whether to always plot all the dipoles. If True (default), the active dipole is plotted as a red dot and it’s location determines the shown MRI slices. The the non-active dipoles are plotted as small blue dots. If False, only the active dipole is plotted. Only used if mode equals ‘orthoview’.

New in version 0.14.0.
axinstance of matplotlib Axes3D | None: Axes to plot into. If None (default), axes will be created. Only used if mode equals ‘orthoview’.

New in version 0.14.0.
blockbool: Whether to halt program execution until the figure is closed. Defaults to False. Only used if mode equals ‘orthoview’.

New in version 0.14.0.
showbool: Show figure if True. Defaults to True. Only used if mode equals ‘orthoview’.
scalefloat: The scale of the dipoles if mode is ‘arrow’ or ‘sphere’.
colortuple: The color of the dipoles if mode is ‘arrow’ or ‘sphere’.
figinstance of Figure3D | None: PyVista figure in which to plot the alignment. If None, creates a new 600x600 pixel figure with black background.

New in version 0.14.0.
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.
titlestr | None: The title of the figure if mode='orthoview' (ignored for all other modes). If None, dipole number and its properties (amplitude, orientation etc.) will be shown. Defaults to None.

New in version 0.21.0.

Returns

figinstance of Figure3D or matplotlib.figure.Figure: The PyVista figure or matplotlib Figure.

Notes

New in version 0.9.0.

Examples using plot_locations:

Source localization with equivalent current dipole (ECD) fit

Visualize source time courses (stcs)

Optically pumped magnetometer (OPM) data

save(fname, overwrite=False, *, verbose=None)[source]#

Save dipole in a .dip or .bdip file.

Parameters

fnamestr: The name of the .dip or .bdip file.
overwritebool: If True (default False), overwrite the destination file if it exists.

New in version 0.20.
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.

Notes

Changed in version 0.20: Support for writing bdip (Xfit binary) files.

to_mni(subject, trans, subjects_dir=None, verbose=None)[source]#

Convert dipole location from head to MNI coordinates.

Parameters

subjectstr: The FreeSurfer subject name.
transstr | dict | instance of Transform: If str, the path to the head<->MRI transform *-trans.fif file produced during coregistration. Can also be 'fsaverage' to use the built-in fsaverage transformation.
subjects_dirpath-like | None: The path to the directory containing the FreeSurfer subjects reconstructions. If None, defaults to the SUBJECTS_DIR environment variable.
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

pos_mniarray, shape (n_pos, 3): The MNI coordinates (in mm) of pos.

Examples using to_mni:

Source localization with equivalent current dipole (ECD) fit

to_mri(subject, trans, subjects_dir=None, verbose=None)[source]#

Convert dipole location from head to MRI surface RAS coordinates.

Parameters

subjectstr: The FreeSurfer subject name.
transstr | dict | instance of Transform: If str, the path to the head<->MRI transform *-trans.fif file produced during coregistration. Can also be 'fsaverage' to use the built-in fsaverage transformation.
subjects_dirpath-like | None: The path to the directory containing the FreeSurfer subjects reconstructions. If None, defaults to the SUBJECTS_DIR environment variable.
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

pos_mriarray, shape (n_pos, 3): The Freesurfer surface RAS coordinates (in mm) of pos.

Examples using to_mri:

Source localization with equivalent current dipole (ECD) fit

to_volume_labels(trans, subject='fsaverage', aseg='aparc+aseg', subjects_dir=None, verbose=None)[source]#

Find an ROI in atlas for the dipole positions.

Parameters

transstr | dict | instance of Transform | None: If str, the path to the head<->MRI transform *-trans.fif file produced during coregistration. Can also be 'fsaverage' to use the built-in fsaverage transformation. If trans is None, an identity matrix is assumed.

Changed in version 0.19: Support for ‘fsaverage’ argument.
subjectstr: The FreeSurfer subject name.
asegstr: The anatomical segmentation file. Default aparc+aseg. This may be any anatomical segmentation file in the mri subdirectory of the Freesurfer subject directory.
subjects_dirpath-like | None: The path to the directory containing the FreeSurfer subjects reconstructions. If None, defaults to the SUBJECTS_DIR environment variable.
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