mne.VolSourceEstimate¶

class mne.VolSourceEstimate(data, vertices=None, tmin=None, tstep=None, subject=None, verbose=None)[source]¶

Container for volume source estimates.

Parameters:

Parameters:	data : array of shape (n_dipoles, n_times) \| 2-tuple (kernel, sens_data) 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. tmin : scalar Time point of the first sample in data. tstep : scalar 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. verbose : bool, str, int, or None If not None, override default verbose level (see `mne.verbose()` and Logging documentation for more).

data : array of shape (n_dipoles, n_times) | 2-tuple (kernel, sens_data): 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.
tmin : scalar: Time point of the first sample in data.
tstep : scalar: 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.
verbose : bool, str, int, or None: If not None, override default verbose level (see mne.verbose() and Logging documentation for more).

See also

SourceEstimate: A container for surface source estimates.
VectorSourceEstimate: A container for vector source estimates.
MixedSourceEstimate: A container for mixed surface + volume source estimates.

Notes

New in version 0.9.0.

Attributes:	subject : str \| None The subject name. `times` : array of shape (n_times,) A timestamp for each sample. vertices : array of shape (n_dipoles,) The indices of the dipoles in the source space. `data` : array of shape (n_dipoles, n_times) Numpy array of source estimate data. `shape` : tuple Shape of the data.

Methods

`__add__`(a)	Add source estimates.
`__div__`(a)	Divide source estimates.
`__hash__`($self, /)	Return hash(self).
`__mul__`(a)	Multiply source estimates.
`__neg__`()	Negate the source estimate.
`__sub__`(a)	Subtract source estimates.
`as_volume`(src[, dest, mri_resolution, format])	Export volume source estimate as a nifti object.
`bin`(width[, tstart, tstop, func])	Return a source estimate object with data summarized over time bins.
`copy`()	Return copy of source estimate instance.
`crop`([tmin, tmax])	Restrict SourceEstimate to a time interval.
`get_peak`([tmin, tmax, mode, vert_as_index, …])	Get location and latency of peak amplitude.
`mean`()	Make a summary stc file with mean over time points.
`plot`(src[, subject, subjects_dir, mode, …])	Plot Nutmeg style volumetric source estimates using nilearn.
`resample`(sfreq[, npad, window, n_jobs, verbose])	Resample data.
`save`(fname[, ftype, verbose])	Save the source estimates to a file.
`save_as_volume`(fname, src[, dest, …])	Save a volume source estimate in a NIfTI file.
`sqrt`()	Take the square root.
`sum`()	Make a summary stc file with sum over time points.
`time_as_index`(times[, use_rounding])	Convert time to indices.
`to_data_frame`([picks, index, scaling_time, …])	Export data in tabular structure as a pandas DataFrame.
`transform`(func[, idx, tmin, tmax, copy])	Apply linear transform.
`transform_data`(func[, idx, tmin_idx, tmax_idx])	Get data after a linear (time) transform has been applied.

__add__(a)[source]¶: Add source estimates.

__div__(a)[source]¶: Divide source estimates.

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

__mul__(a)[source]¶: Multiply source estimates.

__neg__()[source]¶: Negate the source estimate.

__sub__(a)[source]¶: Subtract source estimates.

as_volume(src, dest='mri', mri_resolution=False, format='nifti1')[source]¶

Export volume source estimate as a nifti object.

Parameters:

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’.
Returns:	img : instance Nifti1Image The image object.

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

Returns:

img : instance Nifti1Image: The image object.

Notes

New in version 0.9.0.

bin(width, tstart=None, tstop=None, func=<function mean>)[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:

Parameters:	width : scalar Width of the individual bins in seconds. tstart : scalar \| None Time point where the first bin starts. The default is the first time point of the stc. tstop : scalar \| 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.

width : scalar: Width of the individual bins in seconds.
tstart : scalar | None: Time point where the first bin starts. The default is the first time point of the stc.
tstop : scalar | 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.

copy()[source]¶: Return copy of source estimate instance.

crop(tmin=None, tmax=None)[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.

data¶: Numpy array of source estimate data.

get_peak(tmin=None, tmax=None, mode='abs', vert_as_index=False, time_as_index=False)[source]¶

Get location and latency of peak amplitude.

Parameters:

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_index : bool whether to return the vertex index instead of of its ID. Defaults to False. time_as_index : bool Whether to return the time index instead of the latency. Defaults to False.
Returns:	pos : int The vertex exhibiting the maximum response, either ID or index. latency : float The latency in seconds.

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_index : bool: whether to return the vertex index instead of of its ID. Defaults to False.
time_as_index : bool: Whether to return the time index instead of the latency. Defaults to False.

Returns:

pos : int: The vertex exhibiting the maximum response, either ID or index.
latency : float: The latency in seconds.

mean()[source]¶

Make a summary stc file with mean over time points.

Returns:	stc : SourceEstimate \| VectorSourceEstimate The modified stc.

plot(src, subject=None, subjects_dir=None, mode='stat_map', bg_img=None, colorbar=True, colormap='auto', clim='auto', transparent='auto', show=True, verbose=None)[source]¶

Plot Nutmeg style volumetric source estimates using nilearn.

Parameters:

Parameters:	src : instance of SourceSpaces The source space. 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_img : Niimg-like object \| 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. colorbar : boolean, optional If True, display a colorbar on the right of the plots. colormap : str \| np.ndarray of float, 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. Default (‘auto’) uses ‘hot’ for one-sided data and ‘mne’ for two-sided data. 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 elements Left, middle, and right bound for colormap. `pos_lims` : list \| np.ndarray \| tuple of float, 3 elements Left, middle, and right bound for colormap. Positive values will be mirrored directly across zero during colormap construction to obtain negative control points. Note Only sequential colormaps should be used with `lims`, and only divergent colormaps should be used with `pos_lims`. transparent : bool \| None If True, use a linear transparency between fmin and fmid. None will choose automatically based on colormap type. show : bool Show figures if True. Defaults to True. verbose : bool, str, int, or None If not None, override default verbose level (see `mne.verbose()` and Logging documentation for more).

src : instance of SourceSpaces

The source space.

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_img : Niimg-like object | 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.

colorbar : boolean, optional

If True, display a colorbar on the right of the plots.

colormap : str | np.ndarray of float, 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. Default (‘auto’) uses ‘hot’ for one-sided data and ‘mne’ for two-sided data.

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 elements

Left, middle, and right bound for colormap.

pos_lims : list | np.ndarray | tuple of float, 3 elements

Left, middle, and right bound for colormap. Positive values will be mirrored directly across zero during colormap construction to obtain negative control points.

Note

Only sequential colormaps should be used with lims, and only divergent colormaps should be used with pos_lims.

transparent : bool | None

If True, use a linear transparency between fmin and fmid. None will choose automatically based on colormap type.

show : bool

Show figures if True. Defaults to True.

verbose : bool, str, int, or None

If not None, override default verbose level (see mne.verbose() and Logging documentation for more).

Notes

New in version 0.17.

resample(sfreq, npad='auto', window='boxcar', n_jobs=1, verbose=None)[source]¶

Resample data.

Parameters:

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 power-of-two size (can be much faster). window : string or tuple Window to use in resampling. See scipy.signal.resample. n_jobs : int Number of jobs to run in parallel. verbose : bool, str, int, or None If not None, override default verbose level (see `mne.verbose()` and Logging documentation for more). Defaults to self.verbose.

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 power-of-two size (can be much faster).
window : string or tuple: Window to use in resampling. See scipy.signal.resample.
n_jobs : int: Number of jobs to run in parallel.
verbose : bool, str, int, or None: If not None, override default verbose level (see mne.verbose() and Logging documentation for more). Defaults to self.verbose.

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(fname, ftype='stc', verbose=None)[source]¶

Save the source estimates to a file.

Parameters:

Parameters:	fname : string The stem of the file name. The stem is extended with “-vl.stc” or “-vl.w”. ftype : string File format to use. Allowed values are “stc” (default), “w”, and “h5”. The “w” format only supports a single time point. verbose : bool, str, int, or None If not None, override default verbose level (see `mne.verbose()` and Logging documentation for more). Defaults to self.verbose.

fname : string: The stem of the file name. The stem is extended with “-vl.stc” or “-vl.w”.
ftype : string: File format to use. Allowed values are “stc” (default), “w”, and “h5”. The “w” format only supports a single time point.
verbose : bool, str, int, or None: If not None, override default verbose level (see mne.verbose() and Logging documentation for more). Defaults to self.verbose.

save_as_volume(fname, src, dest='mri', mri_resolution=False, format='nifti1')[source]¶

Save a volume source estimate in a NIfTI file.

Parameters:

Parameters:	fname : string 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.
Returns:	img : instance Nifti1Image The image object.

fname : string: 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.

Returns:

img : instance Nifti1Image: The image object.

Notes

New in version 0.9.0.

sfreq¶: Sample rate of the data.

shape¶: Shape of the data.

sqrt()[source]¶

Take the square root.

Returns:	stc : instance of SourceEstimate A copy of the SourceEstimate with sqrt(data).

sum()[source]¶

Make a summary stc file with sum over time points.

Returns:	stc : SourceEstimate \| VectorSourceEstimate The modified stc.

time_as_index(times, use_rounding=False)[source]¶

Convert time to indices.

Parameters:	times : list-like \| float \| int List of numbers or a number representing points in time. use_rounding : boolean If True, use rounding (instead of truncation) when converting times to indices. This can help avoid non-unique indices.
Returns:	index : ndarray Indices corresponding to the times supplied.

times¶: A timestamp for each sample.

tmin¶: The first timestamp.

to_data_frame(picks=None, index=None, scaling_time=1000.0, scalings=None, copy=True, start=None, stop=None)[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:

Parameters:	picks : array-like of int \| None If None only MEG and EEG channels are kept otherwise the channels indices in picks are kept. index : tuple of str \| 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)`. copy : bool 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.
Returns:	df : instance of pandas.core.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 human-readable.

picks : array-like of int | None: If None only MEG and EEG channels are kept otherwise the channels indices in picks are kept.
index : tuple of str | 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).
copy : bool: 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.

Returns:

df : instance of pandas.core.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 human-readable.

transform(func, idx=None, tmin=None, tmax=None, copy=False)[source]¶

Apply linear transform.

The transform is applied to each source time course independently.

Parameters:

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. Transforms which yield 3D output (e.g. time-frequency transforms) are valid, so long as the first two dimensions are vertices and time. In this case, the copy parameter (see below) 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. 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. copy : bool If True, return a new instance of SourceEstimate instead of modifying the input inplace.
Returns:	stcs : SourceEstimate \| VectorSourceEstimate \| list The transformed stc or, in the case of transforms which yield N-dimensional output (where N > 2), a list of stcs. For a list, copy must be True.

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. Transforms which yield 3D output (e.g. time-frequency transforms) are valid, so long as the first two dimensions are vertices and time. In this case, the copy parameter (see below) 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.
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.
copy : bool: If True, return a new instance of SourceEstimate instead of modifying the input inplace.

Returns:

stcs : SourceEstimate | VectorSourceEstimate | list: The transformed stc or, in the case of transforms which yield N-dimensional output (where N > 2), a list of stcs. For a list, copy must be True.

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

transform_data(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:

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.
Returns:	data_t : ndarray The transformed data.

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.

Returns:

data_t : ndarray: The transformed data.

Notes

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