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.
array
, shape (n_dipoles,)The time instants at which each dipole was fitted (sec).
array
, shape (n_dipoles, 3)The dipoles positions (m) in head coordinates.
array
, shape (n_dipoles,)The amplitude of the dipoles (Am).
array
, shape (n_dipoles, 3)The dipole orientations (normalized to unit length).
array
, shape (n_dipoles,)The goodness of fit.
str
| None
Name of the dipole.
dict
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.
array
, shape (n_dipoles,)The χ^2 values for the fits.
New in version 0.15.
array
, shape (n_dipoles,)The number of free parameters for each fit.
New in version 0.15.
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
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
.
Methods
|
Get a time slice. |
|
Return the number of dipoles. |
|
Copy the Dipoles object. |
|
Crop data to a given time interval. |
|
Decimate the time-series data. |
|
Plot the dipole amplitudes as a function of time. |
|
Plot dipole locations. |
|
Save dipole in a .dip or .bdip file. |
|
Shift time scale in epoched or evoked data. |
|
Convert time to indices. |
|
Convert dipole location from head to MNI coordinates. |
|
Convert dipole location from head to MRI surface RAS coordinates. |
|
Find an ROI in atlas for the dipole positions. |
Get a time slice.
slice
The slice of time points to use.
Dipole
The sliced dipole.
Return the number of dipoles.
int
The number of dipoles.
Examples
This can be used as:
>>> len(dipoles)
10
Crop data to a given time interval.
float
| None
Start time of selection in seconds.
float
| None
End time of selection in seconds.
If True (default), include tmax. If False, exclude tmax (similar to how Python indexing typically works).
New in version 0.19.
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.
Dipole
The cropped instance.
Examples using crop
:
Compute MxNE with time-frequency sparse prior
Decimate the time-series data.
int
Factor by which to subsample the data.
Warning
Low-pass filtering is not performed, this simply selects
every Nth sample (where N is the value passed to
decim
), i.e., it compresses the signal (see Notes).
If the data are not properly filtered, aliasing artifacts
may occur.
int
Apply an offset to where the decimation starts relative to the sample corresponding to t=0. The offset is in samples at the current sampling rate.
New in version 0.12.
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.
The decimated object.
See also
Notes
For historical reasons, decim
/ “decimation” refers to simply subselecting
samples from a given signal. This contrasts with the broader signal processing
literature, where decimation is defined as (quoting
[1], p. 172; which cites
[2]):
“… a general system for downsampling by a factor of M is the one shown in Figure 4.23. Such a system is called a decimator, and downsampling by lowpass filtering followed by compression [i.e, subselecting samples] has been termed decimation (Crochiere and Rabiner, 1983).”
Hence “decimation” in MNE is what is considered “compression” in the signal processing community.
Decimation can be done multiple times. For example,
inst.decimate(2).decimate(2)
will be the same as
inst.decimate(4)
.
If decim
is 1, this method does not copy the underlying data.
New in version 0.10.0.
References
Plot the dipole amplitudes as a function of time.
matplotlib.figure.Figure
The figure object containing the plot.
Plot dipole locations.
If mode is set to ‘arrow’ or ‘sphere’, only the location of the first time point of each dipole is shown else use the show_all parameter.
dict
| None
The mri to head trans. Can be None with mode set to ‘3d’.
str
| None
The FreeSurfer subject name (will be used to set the FreeSurfer
environment variable SUBJECT
).
Can be None
with mode set to '3d'
.
None
The path to the directory containing the FreeSurfer subjects
reconstructions. If None
, defaults to the SUBJECTS_DIR
environment
variable.
str
Can be:
'arrow'
or 'sphere'
Plot in 3D mode using PyVista with the given glyph type.
'orthoview'
Plot in matplotlib Axes3D
using matplotlib with MRI slices
shown on the sides of a cube, with the dipole(s) shown as arrows
extending outward from a dot (i.e., the arrows pivot on the tail).
'outlines'
Plot in matplotlib Axes
using a quiver of arrows for the
dipoles in three axes (axial, coronal, and sagittal views),
with the arrow pivoting in the middle of the arrow.
Changed in version 1.1: Added support for 'outlines'
.
str
Coordinate frame to use: ‘head’ or ‘mri’. Can also be ‘mri_rotated’
when mode equals 'outlines'
. Defaults to ‘mri’.
New in version 0.14.0.
Changed in version 1.1: Added support for 'mri_rotated'
.
int
| ‘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.
Whether to always plot all the dipoles. If True
(default), the
active dipole is plotted as a red dot and its location determines the
shown MRI slices. The non-active dipoles are plotted as small blue
dots. If False
, only the active dipole is plotted.
Only used if mode='orthoview'
.
New in version 0.14.0.
Axes3D
| list
of matplotlib Axes
| None
Axes to plot into. If None (default), axes will be created.
If mode equals 'orthoview'
, must be a single Axes3D
.
If mode equals 'outlines'
, must be a list of three Axes
.
New in version 0.14.0.
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.
Show figure if True. Defaults to True. Only used if mode equals ‘orthoview’.
float
The scale (size in meters) of the dipoles if mode
is not
'orthoview'
. The default is 0.03 when mode is 'outlines'
and
0.005 otherwise.
tuple
The color of the dipoles.
The default (None) will use 'y'
if mode is 'orthoview'
and
show_all
is True, else ‘r’. Can also be a list of colors to use
when mode is 'outlines'
.
Changed in version 0.19.0: Color is now passed in orthoview mode.
The highlight color. Only used in orthoview mode with
show_all=True
.
New in version 0.19.0.
Figure3D
| None
3D figure in which to plot the alignment.
If None
, creates a new 600x600 pixel figure with black background.
Only used when mode is 'arrow'
or 'sphere'
.
New in version 0.19.0.
str
| 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.
str
| list
of str
Head source(s) to use. See the source
option of
mne.get_head_surf()
for more information.
Only used when mode equals 'outlines'
.
New in version 1.1.
str
| None
Brain surface to show outlines for, can be 'white'
, 'pial'
, or
None
. Only used when mode is 'outlines'
.
New in version 1.1.
float
| None
Width of the matplotlib quiver arrow, see
matplotlib.axes.Axes.quiver()
. If None (default),
when mode is 'outlines'
0.015 will be used, and when mode is
'orthoview'
the matplotlib default is used.
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.
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 dipole in a .dip or .bdip file.
str
The name of the .dip or .bdip file.
If True (default False), overwrite the destination file if it exists.
New in version 0.20.
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.
Shift time scale in epoched or evoked data.
float
The (absolute or relative) time shift in seconds. If relative
is True, positive tshift increases the time value associated with
each sample, while negative tshift decreases it.
If True, increase or decrease time values by tshift
seconds.
Otherwise, shift the time values such that the time of the first
sample equals tshift
.
The modified instance.
Notes
This method allows you to shift the time values associated with each data sample by an arbitrary amount. It does not resample the signal or change the data values in any way.
Time vector in seconds.
Last time point.
First time point.
Convert dipole location from head to MNI coordinates.
str
The FreeSurfer subject name.
str
| 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.
None
The path to the directory containing the FreeSurfer subjects
reconstructions. If None
, defaults to the SUBJECTS_DIR
environment
variable.
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.
array
, shape (n_pos, 3)The MNI coordinates (in mm) of pos.
Examples using to_mni
:
Source localization with equivalent current dipole (ECD) fit
Convert dipole location from head to MRI surface RAS coordinates.
str
The FreeSurfer subject name.
str
| 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.
None
The path to the directory containing the FreeSurfer subjects
reconstructions. If None
, defaults to the SUBJECTS_DIR
environment
variable.
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.
array
, 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
Find an ROI in atlas for the dipole positions.
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.
str
The FreeSurfer subject name.
str
The anatomical segmentation file. Default aparc+aseg
. This may
be any anatomical segmentation file in the mri subdirectory of the
Freesurfer subject directory.
None
The path to the directory containing the FreeSurfer subjects
reconstructions. If None
, defaults to the SUBJECTS_DIR
environment
variable.
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.
list
List of anatomical region names from anatomical segmentation atlas.
Notes
New in version 0.24.
Examples using to_volume_labels
:
Source localization with equivalent current dipole (ECD) fit
mne.Dipole
#Source localization with equivalent current dipole (ECD) fit
The role of dipole orientations in distributed source localization
Visualize source time courses (stcs)
Brainstorm Elekta phantom dataset tutorial
Brainstorm CTF phantom dataset tutorial
4D Neuroimaging/BTi phantom dataset tutorial
Compute sparse inverse solution with mixed norm: MxNE and irMxNE
Computing source timecourses with an XFit-like multi-dipole model
Compute MxNE with time-frequency sparse prior
Optically pumped magnetometer (OPM) data