# mne.VolSourceEstimate¶

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

Container for volume source estimates.

Parameters
dataarray 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 np.dot(kernel, sens_data).

verticesarray of shape (n_dipoles,)

The indices of the dipoles in the source space.

tminscalar

Time point of the first sample in data.

tstepscalar

Time step between successive samples in data.

subject

The subject name. While not necessary, it is safer to set the subject parameter to avoid analysis errors.

verbose

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

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
subject

The subject name.

timesarray of shape (n_times,)

A timestamp for each sample.

verticesarray of shape (n_dipoles,)

The indices of the dipoles in the source space.

dataarray of shape (n_dipoles, n_times)

Numpy array of source estimate data.

shapetuple

Shape of the data.

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. extract_label_time_course(self, labels, src) Extract label time courses for lists of labels. get_peak(self[, tmin, tmax, mode, …]) Get location and latency of peak amplitude. in_label(self, label, mri, src[, trans]) Get a source estimate object restricted to a label. 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[, index, scalings, …]) 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.
__add__(self, a)[source]

Add source estimates.

__div__(self, a)[source]

Divide source estimates.

__hash__(self, /)

Return hash(self).

__mul__(self, a)[source]

Multiply source estimates.

__neg__(self)[source]

Negate the source estimate.

__sub__(self, a)[source]

Subtract source estimates.

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

Export volume source estimate as a nifti object.

Parameters
srcinstance of SourceSpaces

The source spaces (should all be of type volume, or part of a mixed source space).

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_resolutionbool

It True the image is saved in MRI resolution.

Warning

If you have many time points, the file produced can be huge.

formatstr

Either ‘nifti1’ (default) or ‘nifti2’.

Returns
imginstance of Nifti1Image

The image object.

Notes

New in version 0.9.0.

Examples using as_volume:

bin(self, width, tstart=None, tstop=None, func=<function mean at 0x7f66b61534c0>)[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.

tstart

Time point where the first bin starts. The default is the first time point of the stc.

tstop

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.

funccallable()

Function that is applied to summarize the data. Needs to accept a numpy.array as first input and an axis keyword argument.

Returns
stc

The binned source estimate.

copy(self)[source]

Return copy of source estimate instance.

Returns
stcinstance of SourceEstimate

A copy of the source estimate.

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

Restrict SourceEstimate to a time interval.

Parameters
tmin

The first time point in seconds. If None the first present is used.

tmax

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.

Returns
stcinstance of SourceEstimate

The cropped source estimate.

Examples using crop:

property data

Numpy array of source estimate data.

extract_label_time_course(self, labels, src, mode='auto', allow_empty=False, trans=None, mri_resolution=True, verbose=None)[source]

Extract label time courses for lists of labels.

This function will extract one time course for each label. The way the time courses are extracted depends on the mode parameter.

Parameters
labels

If using a surface or mixed source space, this should be the Label’s for which to extract the time course. If working with whole-brain volume source estimates, this must be one of:

• a string path to a FreeSurfer atlas for the subject (e.g., their ‘aparc.a2009s+aseg.mgz’) to extract time courses for all volumes in the atlas

• a two-element list or tuple, the first element being a path to an atlas, and the second being a list or dict of volume_labels to extract (see mne.setup_volume_source_space() for details).

Changed in version 0.21.0: Support for volume source estimates.

srcinstance of SourceSpaces

The source spaces for the source time courses.

modestr

Extraction mode, see Notes.

allow_empty

False (default) will emit an error if there are labels that have no vertices in the source estimate. True and 'ignore' will return all-zero time courses for labels that do not have any vertices in the source estimate, and True will emit a warning while and “ignore” will just log a message.

Changed in version 0.21.0: Support for “ignore”.

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.

Only needed when using a volume atlas and src is in head coordinates (i.e., comes from a forward or inverse).

New in version 0.21.0.

mri_resolutionbool

If True (default), the volume source space will be upsampled to the original MRI resolution via trilinear interpolation before the atlas values are extracted. This ensnures that each atlas label will contain source activations. When False, only the original source space points are used, and some atlas labels thus may not contain any source space vertices.

New in version 0.21.0.

verbose

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

Returns
label_tcarray | list (or generator) of array, shape (n_labels[, n_orient], n_times)

Extracted time course for each label and source estimate.

See also

extract_label_time_course

Extract time courses for multiple STCs.

Notes

Valid values for mode are:

• 'max'

Maximum value across vertices at each time point within each label.

• 'mean'

Average across vertices at each time point within each label. Ignores orientation of sources for standard source estimates, which varies across the cortical surface, which can lead to cancellation. Vector source estimates are always in XYZ / RAS orientation, and are thus already geometrically aligned.

• 'mean_flip'

Finds the dominant direction of source space normal vector orientations within each label, applies a sign-flip to time series at vertices whose orientation is more than 180° different from the dominant direction, and then averages across vertices at each time point within each label.

• 'pca_flip'

Applies singular value decomposition to the time courses within each label, and uses the first right-singular vector as the representative label time course. This signal is scaled so that its power matches the average (per-vertex) power within the label, and sign-flipped by multiplying by np.sign(u @ flip), where u is the first left-singular vector and flip is the same sign-flip vector used when mode='mean_flip'. This sign-flip ensures that extracting time courses from the same label in similar STCs does not result in 180° direction/phase changes.

• 'auto' (default)

Uses 'mean_flip' when a standard source estimate is applied, and 'mean' when a vector source estimate is supplied.

New in version 0.21: Support for 'auto', vector, and volume source estimates.

The only modes that work for vector and volume source estimates are 'mean', 'max', and 'auto'.

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

The minimum point in time to be considered for peak getting.

tmax

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 (True) instead of of its ID (False, default).

time_as_indexbool

Whether to return the time index (True) instead of the latency (False, default).

Returns
posint

The vertex exhibiting the maximum response, either ID or index.

latencyfloat

The latency in seconds.

in_label(self, label, mri, src, trans=None)[source]

Get a source estimate object restricted to a label.

SourceEstimate contains the time course of activation of all sources inside the label.

Parameters
label

The label to use. Can be the name of a label if using a standard FreeSurfer atlas, or an integer value to extract from the mri.

mristr

Path to the atlas to use.

srcinstance of SourceSpaces

The volumetric source space. It must be a single, whole-brain volume.

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.

Returns
stc

The source estimate restricted to the given label.

Notes

New in version 0.21.0.

mean(self)[source]

Make a summary stc file with mean over time points.

Returns
stc

The modified 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 of SourceMorph

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

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

The path to the freesurfer subjects reconstructions. It corresponds to Freesurfer environment variable SUBJECTS_DIR.

modestr

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.

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

clim

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.

limslist | np.ndarray | tuple of float, 3 elements

Lower, middle, and upper bounds for colormap.

pos_limslist | np.ndarray | tuple of float, 3 elements

Lower, 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 or pos_lims should be provided. Only sequential colormaps should be used with lims, and only divergent colormaps should be used with pos_lims.

transparent

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

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 (if initial_pos is None or not, respectively).

New in version 0.19.

initial_posndarray, 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 (if initial_time is None or not, respectively).

New in version 0.19.

verbose

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

Returns
figinstance of Figure

The figure.

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 the src 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
sfreqfloat

New sample rate to use.

npad

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

Window to use in resampling. See scipy.signal.resample().

n_jobsint

The number of jobs to run in parallel (default 1). Requires the joblib package.

verbose

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

Returns
stcinstance of SourceEstimate

The resampled source estimate.

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
fnamestr

The stem of the file name. The stem is extended with “-vl.stc” or “-vl.w”.

ftypestr

File format to use. Allowed values are “stc” (default), “w”, and “h5”. The “w” format only supports a single time point.

verbose

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

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

Save a volume source estimate in a NIfTI file.

Parameters
fnamestr

The name of the generated nifti file.

srclist

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_resolutionbool

It True the image is saved in MRI resolution.

Warning

If you have many time points, the file produced can be huge.

formatstr

Either ‘nifti1’ (default) or ‘nifti2’.

New in version 0.17.

Returns
imginstance Nifti1Image

The image object.

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

sum(self)[source]

Make a summary stc file with sum over time points.

Returns
stc

The modified stc.

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

Convert time to indices.

Parameters
timeslist-like | float | int

List of numbers or a number representing points in time.

use_roundingbool

If True, use rounding (instead of truncation) when converting times to indices. This can help avoid non-unique indices.

Returns
indexndarray

Indices corresponding to the times supplied.

property times

A timestamp for each sample.

property tmin

The first timestamp.

to_data_frame(self, index=None, scalings=None, long_format=False, time_format='ms')[source]

Export data in tabular structure as a pandas DataFrame.

Vertices are converted to columns in the DataFrame. By default, an additional column “time” is added, unless index='time' (in which case time values form the DataFrame’s index).

Parameters
index‘time’ | None

Kind of index to use for the DataFrame. If None, a sequential integer index (pandas.RangeIndex) will be used. If 'time', a pandas.Float64Index, pandas.Int64Index, or pandas.TimedeltaIndex will be used (depending on the value of time_format). Defaults to None.

scalings

Scaling factor applied to the channels picked. If None, defaults to dict(eeg=1e6, mag=1e15, grad=1e13) — i.e., converts EEG to µV, magnetometers to fT, and gradiometers to fT/cm.

long_formatbool

If True, the DataFrame is returned in long format where each row is one observation of the signal at a unique combination of time point and vertex. Defaults to False.

time_format

Desired time format. If None, no conversion is applied, and time values remain as float values in seconds. If 'ms', time values will be rounded to the nearest millisecond and converted to integers. If 'timedelta', time values will be converted to pandas.Timedelta values. Defaults to 'ms'.

New in version 0.20.

Returns
dfinstance of pandas.DataFrame

A dataframe suitable for usage with other statistical/plotting/analysis packages.

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
funccallable()

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

Indices of source time courses for which to compute transform. If None, all time courses are used.

tmin

First time point to include (ms). If None, self.tmin is used.

tmax

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.

Returns
stcs

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

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 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
funccallable()

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

Indicices of source time courses for which to compute transform. If None, all time courses are used.

tmin_idx

Index of first time point to include. If None, the index of the first time point is used.

tmax_idx

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_tndarray

The transformed data.

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