mne.VolSourceEstimate¶

class
mne.
VolSourceEstimate
(data, vertices=None, tmin=None, tstep=None, subject=None, verbose=None)[source]¶ Container for volume source estimates.
 Parameters
 data
array
of shape (n_dipoles, n_times) tuple
, shape (2,) The data in source space. The data can either be a single array or a tuple with two arrays: “kernel” shape (n_vertices, n_sensors) and “sens_data” shape (n_sensors, n_times). In this case, the source space data corresponds to “numpy.dot(kernel, sens_data)”.
 vertices
array
Vertex numbers corresponding to the data.
 tminscalar
Time point of the first sample in data.
 tstepscalar
Time step between successive samples in data.
 subject
str
None
The subject name. While not necessary, it is safer to set the subject parameter to avoid analysis errors.
 verbosebool,
str
,int
, orNone
If not None, override default verbose level (see
mne.verbose()
and Logging documentation for more).
 data
See also
SourceEstimate
A container for surface source estimates.
VolVectorSourceEstimate
A container for volume vector source estimates.
MixedSourceEstimate
A container for mixed surface + volume source estimates.
Notes
New in version 0.9.0.
 Attributes
Methods
__add__
(self, a)Add source estimates.
__div__
(self, a)Divide source estimates.
__hash__
(self, /)Return hash(self).
__mul__
(self, a)Multiply source estimates.
__neg__
(self)Negate the source estimate.
__sub__
(self, a)Subtract source estimates.
as_volume
(self, src[, dest, mri_resolution, …])Export volume source estimate as a nifti object.
bin
(self, width[, tstart, tstop, func])Return a source estimate object with data summarized over time bins.
copy
(self)Return copy of source estimate instance.
crop
(self[, tmin, tmax, include_tmax])Restrict SourceEstimate to a time interval.
get_peak
(self[, tmin, tmax, mode, …])Get location and latency of peak amplitude.
mean
(self)Make a summary stc file with mean over time points.
plot
(self, src[, subject, subjects_dir, …])Plot Nutmeg style volumetric source estimates using nilearn.
resample
(self, sfreq[, npad, window, …])Resample data.
save
(self, fname[, ftype, verbose])Save the source estimates to a file.
save_as_volume
(self, fname, src[, dest, …])Save a volume source estimate in a NIfTI file.
sqrt
(self)Take the square root.
sum
(self)Make a summary stc file with sum over time points.
time_as_index
(self, times[, use_rounding])Convert time to indices.
to_data_frame
(self[, picks, index, …])Export data in tabular structure as a pandas DataFrame.
transform
(self, func[, idx, tmin, tmax, copy])Apply linear transform.
transform_data
(self, func[, idx, tmin_idx, …])Get data after a linear (time) transform has been applied.

__hash__
(self, /)¶ Return hash(self).

as_volume
(self, src, dest='mri', mri_resolution=False, format='nifti1')[source]¶ Export volume source estimate as a nifti object.
 Parameters
 src
list
The list of source spaces (should all be of type volume).
 dest‘mri’  ‘surf’
If ‘mri’ the volume is defined in the coordinate system of the original T1 image. If ‘surf’ the coordinate system of the FreeSurfer surface is used (Surface RAS).
 mri_resolution: bool
It True the image is saved in MRI resolution. WARNING: if you have many time points the file produced can be huge.
 format
str
Either ‘nifti1’ (default) or ‘nifti2’.
 src
 Returns
 imginstance of
Nifti1Image
The image object.
 imginstance of
Notes
New in version 0.9.0.
Examples using
as_volume
:

bin
(self, width, tstart=None, tstop=None, func=<function mean at 0x7f361766b8c0>)[source]¶ Return a source estimate object with data summarized over time bins.
Time bins of
width
seconds. This method is intended for visualization only. No filter is applied to the data before binning, making the method inappropriate as a tool for downsampling data. Parameters
 widthscalar
Width of the individual bins in seconds.
 tstartscalar 
None
Time point where the first bin starts. The default is the first time point of the stc.
 tstopscalar 
None
Last possible time point contained in a bin (if the last bin would be shorter than width it is dropped). The default is the last time point of the stc.
 func
callable()
Function that is applied to summarize the data. Needs to accept a numpy.array as first input and an
axis
keyword argument.
 Returns
 stc
SourceEstimate
VectorSourceEstimate
The binned source estimate.
 stc

crop
(self, tmin=None, tmax=None, include_tmax=True)[source]¶ Restrict SourceEstimate to a time interval.
 Parameters
 tmin
float
None
The first time point in seconds. If None the first present is used.
 tmax
float
None
The last time point in seconds. If None the last present is used.
 include_tmaxbool
If True (default), include tmax. If False, exclude tmax (similar to how Python indexing typically works).
New in version 0.19.
 tmin
Examples using
crop
:

property
data
¶ Numpy array of source estimate data.

get_peak
(self, tmin=None, tmax=None, mode='abs', vert_as_index=False, time_as_index=False)[source]¶ Get location and latency of peak amplitude.
 Parameters
 tmin
float
None
The minimum point in time to be considered for peak getting.
 tmax
float
None
The maximum point in time to be considered for peak getting.
 mode{‘pos’, ‘neg’, ‘abs’}
How to deal with the sign of the data. If ‘pos’ only positive values will be considered. If ‘neg’ only negative values will be considered. If ‘abs’ absolute values will be considered. Defaults to ‘abs’.
 vert_as_indexbool
whether to return the vertex index instead of of its ID. Defaults to False.
 time_as_indexbool
Whether to return the time index instead of the latency. Defaults to False.
 tmin
 Returns

mean
(self)[source]¶ Make a summary stc file with mean over time points.
 Returns
 stc
SourceEstimate
VectorSourceEstimate
The modified stc.
 stc

plot
(self, src, subject=None, subjects_dir=None, mode='stat_map', bg_img=None, colorbar=True, colormap='auto', clim='auto', transparent='auto', show=True, initial_time=None, initial_pos=None, verbose=None)[source]¶ Plot Nutmeg style volumetric source estimates using nilearn.
 Parameters
 srcinstance of
SourceSpaces
 instance ofSourceMorph
The source space. Can also be a SourceMorph to morph the STC to a new subject (see Examples).
Changed in version 0.18: Support for
SpatialImage
. subject
str
None
The subject name corresponding to FreeSurfer environment variable SUBJECT. If None stc.subject will be used. If that is None, the environment will be used.
 subjects_dir
str
The path to the freesurfer subjects reconstructions. It corresponds to Freesurfer environment variable SUBJECTS_DIR.
 mode
str
The plotting mode to use. Either ‘stat_map’ (default) or ‘glass_brain’. For “glass_brain”, activation absolute values are displayed after being transformed to a standard MNI brain.
 bg_imginstance of
SpatialImage
None
The background image used in the nilearn plotting function. If None, it is the T1.mgz file that is found in the subjects_dir. Not used in “glass brain” plotting.
 colorbarbool, optional
If True, display a colorbar on the right of the plots.
 colormap
str
np.ndarray
offloat
, shape(n_colors, 3  4) Name of colormap to use or a custom look up table. If array, must be (n x 3) or (n x 4) array for with RGB or RGBA values between 0 and 255.
 clim
str
dict
Colorbar properties specification. If ‘auto’, set clim automatically based on data percentiles. If dict, should contain:
kind
‘value’  ‘percent’Flag to specify type of limits.
lims
list  np.ndarray  tuple of float, 3 elementsLower, middle, and upper bounds for colormap.
pos_lims
list  np.ndarray  tuple of float, 3 elementsLower, middle, and upper bound for colormap. Positive values will be mirrored directly across zero during colormap construction to obtain negative control points.
Note
Only one of
lims
orpos_lims
should be provided. Only sequential colormaps should be used withlims
, and only divergent colormaps should be used withpos_lims
. transparentbool 
None
If True, use a linear transparency between fmin and fmid. None will choose automatically based on colormap type.
 showbool
Show figures if True. Defaults to True.
 initial_time
float
None
The initial time to plot. Can be None (default) to use the time point with the maximal absolute value activation across all voxels or the
initial_pos
voxel (ifinitial_pos is None
or not, respectively).New in version 0.19.
 initial_pos
ndarray
, shape (3,) None
The initial position to use (in m). Can be None (default) to use the voxel with the maximum absolute value activation across all time points or at
initial_time
(ifinitial_time is None
or not, respectively).New in version 0.19.
 verbosebool,
str
,int
, orNone
If not None, override default verbose level (see
mne.verbose()
and Logging documentation for more).
 srcinstance of
Notes
Click on any of the anatomical slices to explore the time series. Clicking on any time point will bring up the corresponding anatomical map.
The left and right arrow keys can be used to navigate in time. To move in time by larger steps, use shift+left and shift+right.
In
'glass_brain'
mode, values are transformed to the standard MNI brain using the FreeSurfer Talairach transformation$SUBJECTS_DIR/$SUBJECT/mri/transforms/talairach.xfm
.New in version 0.17.
Changed in version 0.19: MRI volumes are automatically transformed to MNI space in
'glass_brain'
mode.Examples
Passing a
mne.SourceMorph
as thesrc
parameter can be useful for plotting in a different subject’s space (here, a'sample'
STC in'fsaverage'
’s space):>>> morph = mne.compute_source_morph(src_sample, subject_to='fsaverage') >>> fig = stc_vol_sample.plot(morph)
Examples using
plot
:

resample
(self, sfreq, npad='auto', window='boxcar', n_jobs=1, verbose=None)[source]¶ Resample data.
 Parameters
 sfreq
float
New sample rate to use.
 npad
int
str
Amount to pad the start and end of the data. Can also be “auto” to use a padding that will result in a poweroftwo size (can be much faster).
 window
str
ortuple
Window to use in resampling. See scipy.signal.resample.
 n_jobs
int
The number of jobs to run in parallel (default 1). Requires the joblib package.
 verbosebool,
str
,int
, orNone
If not None, override default verbose level (see
mne.verbose()
and Logging documentation for more). Defaults to self.verbose.
 sfreq
Notes
For some data, it may be more accurate to use npad=0 to reduce artifacts. This is dataset dependent – check your data!
Note that the sample rate of the original data is inferred from tstep.

save
(self, fname, ftype='stc', verbose=None)[source]¶ Save the source estimates to a file.
 Parameters
 fname
str
The stem of the file name. The stem is extended with “vl.stc” or “vl.w”.
 ftype
str
File format to use. Allowed values are “stc” (default), “w”, and “h5”. The “w” format only supports a single time point.
 verbosebool,
str
,int
, orNone
If not None, override default verbose level (see
mne.verbose()
and Logging documentation for more). Defaults to self.verbose.
 fname

save_as_volume
(self, fname, src, dest='mri', mri_resolution=False, format='nifti1')[source]¶ Save a volume source estimate in a NIfTI file.
 Parameters
 fname
str
The name of the generated nifti file.
 src
list
The list of source spaces (should all be of type volume).
 dest‘mri’  ‘surf’
If ‘mri’ the volume is defined in the coordinate system of the original T1 image. If ‘surf’ the coordinate system of the FreeSurfer surface is used (Surface RAS).
 mri_resolution: bool
It True the image is saved in MRI resolution. WARNING: if you have many time points the file produced can be huge.
 format
str
Either ‘nifti1’ (default) or ‘nifti2’.
New in version 0.17.
 fname
 Returns
 imginstance
Nifti1Image
The image object.
 imginstance
Notes
New in version 0.9.0.

property
sfreq
¶ Sample rate of the data.

property
shape
¶ Shape of the data.

sqrt
(self)[source]¶ Take the square root.
 Returns
 stcinstance of
SourceEstimate
A copy of the SourceEstimate with sqrt(data).
 stcinstance of

sum
(self)[source]¶ Make a summary stc file with sum over time points.
 Returns
 stc
SourceEstimate
VectorSourceEstimate
The modified stc.
 stc

property
times
¶ A timestamp for each sample.

property
tmin
¶ The first timestamp.

to_data_frame
(self, picks=None, index=None, scaling_time=1000.0, scalings=None, copy=True, start=None, stop=None, long_format=False)[source]¶ Export data in tabular structure as a pandas DataFrame.
Columns and indices will depend on the object being converted. Generally this will include as much relevant information as possible for the data type being converted. This makes it easy to convert data for use in packages that utilize dataframes, such as statsmodels or seaborn.
 Parameters
 picks
str
list
slice
None
Channels to include. Slices and lists of integers will be interpreted as channel indices. In lists, channel type strings (e.g.,
['meg', 'eeg']
) will pick channels of those types, channel name strings (e.g.,['MEG0111', 'MEG2623']
will pick the given channels. Can also be the string values “all” to pick all channels, or “data” to pick data channels. None (default) will pick all channels. index
tuple
ofstr
None
Column to be used as index for the data. Valid string options are ‘epoch’, ‘time’ and ‘condition’. If None, all three info columns will be included in the table as categorial data.
 scaling_time
float
Scaling to be applied to time units.
 scalings
dict
None
Scaling to be applied to the channels picked. If None, defaults to
scalings=dict(eeg=1e6, grad=1e13, mag=1e15, misc=1.0)
. copybool
If true, data will be copied. Else data may be modified in place.
 start
int
None
If it is a Raw object, this defines a starting index for creating the dataframe from a slice. The times will be interpolated from the index and the sampling rate of the signal.
 stop
int
None
If it is a Raw object, this defines a stop index for creating the dataframe from a slice. The times will be interpolated from the index and the sampling rate of the signal.
 long_formatbool
If True, the dataframe is returned in long format where each row is one observation of the signal at a unique coordinate of channels, time points, epochs and conditions. The number of factors depends on the data container. For convenience, a ch_type column is added when using this option that will facilitate subsetting the resulting dataframe. Defaults to False.
 picks
 Returns
 dfinstance of
pandas.DataFrame
A dataframe suitable for usage with other statistical/plotting/analysis packages. Column/Index values will depend on the object type being converted, but should be humanreadable.
 dfinstance of

transform
(self, func, idx=None, tmin=None, tmax=None, copy=False)[source]¶ Apply linear transform.
The transform is applied to each source time course independently.
 Parameters
 func
callable()
The transform to be applied, including parameters (see, e.g.,
functools.partial()
). The first parameter of the function is the input data. The first two dimensions of the transformed data should be (i) vertices and (ii) time. See Notes for details. idx
array
None
Indices of source time courses for which to compute transform. If None, all time courses are used.
 tmin
float
int
None
First time point to include (ms). If None, self.tmin is used.
 tmax
float
int
None
Last time point to include (ms). If None, self.tmax is used.
 copybool
If True, return a new instance of SourceEstimate instead of modifying the input inplace.
 func
 Returns
 stcs
SourceEstimate
VectorSourceEstimate
list
The transformed stc or, in the case of transforms which yield Ndimensional output (where N > 2), a list of stcs. For a list, copy must be True.
 stcs
Notes
Transforms which yield 3D output (e.g. timefrequency transforms) are valid, so long as the first two dimensions are vertices and time. In this case, the copy parameter must be True and a list of SourceEstimates, rather than a single instance of SourceEstimate, will be returned, one for each index of the 3rd dimension of the transformed data. In the case of transforms yielding 2D output (e.g. filtering), the user has the option of modifying the input inplace (copy = False) or returning a new instance of SourceEstimate (copy = True) with the transformed data.
Applying transforms can be significantly faster if the SourceEstimate object was created using “(kernel, sens_data)”, for the “data” parameter as the transform is applied in sensor space. Inverse methods, e.g., “apply_inverse_epochs”, or “apply_lcmv_epochs” do this automatically (if possible).

transform_data
(self, func, idx=None, tmin_idx=None, tmax_idx=None)[source]¶ Get data after a linear (time) transform has been applied.
The transform is applied to each source time course independently.
 Parameters
 func
callable()
The transform to be applied, including parameters (see, e.g.,
functools.partial()
). The first parameter of the function is the input data. The first return value is the transformed data, remaining outputs are ignored. The first dimension of the transformed data has to be the same as the first dimension of the input data. idx
array
None
Indicices of source time courses for which to compute transform. If None, all time courses are used.
 tmin_idx
int
None
Index of first time point to include. If None, the index of the first time point is used.
 tmax_idx
int
None
Index of the first time point not to include. If None, time points up to (and including) the last time point are included.
 func
 Returns
 data_t
ndarray
The transformed data.
 data_t
Notes
Applying transforms can be significantly faster if the SourceEstimate object was created using “(kernel, sens_data)”, for the “data” parameter as the transform is applied in sensor space. Inverse methods, e.g., “apply_inverse_epochs”, or “apply_lcmv_epochs” do this automatically (if possible).

property
tstep
¶ The change in time between two consecutive samples (1 / sfreq).