mne.VectorSourceEstimate¶

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

Container for vector surface source estimates.

For each vertex, the magnitude of the current is defined in the X, Y and Z directions.

Parameters:

Parameters:	data : array of shape (n_dipoles, 3, n_times) The data in source space. Each dipole contains three vectors that denote the dipole strength in X, Y and Z directions over time. vertices : array \| list of two arrays Vertex numbers corresponding to the data. tmin : float Time point of the first sample in data. tstep : float 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).

data : array of shape (n_dipoles, 3, n_times): The data in source space. Each dipole contains three vectors that denote the dipole strength in X, Y and Z directions over time.
vertices : array | list of two arrays: Vertex numbers corresponding to the data.
tmin : float: Time point of the first sample in data.
tstep : float: 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).

See also

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

Notes

New in version 0.15.

Attributes:	subject : str \| None The subject name. `times` : array of shape (n_times,) A timestamp for each sample. `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.
`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.
`expand`(vertices)	Expand SourceEstimate to include more vertices.
`in_label`(label)	Get a source estimate object restricted to a label.
`magnitude`()	Compute magnitude of activity without directionality.
`mean`()	Make a summary stc file with mean over time points.
`morph`(subject_to[, grade, smooth, …])	Warning DEPRECATED: This function is deprecated and will be removed in version 0.18. Use morph = mne.compute_source_morph(…) and morph(stc)
`morph_precomputed`(**kwargs)	Warning DEPRECATED: This function is deprecated and will be removed in version 0.18. Use morph = mne.compute_source_morph(…) and morph(stc)
`normal`(src)	Compute activity orthogonal to the cortex.
`plot`([subject, hemi, colormap, time_label, …])	Plot VectorSourceEstimates with PySurfer.
`resample`(sfreq[, npad, window, n_jobs, verbose])	Resample data.
`save`(fname[, ftype, verbose])	Save the full source estimate to an HDF5 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.
`to_original_src`(src_orig[, subject_orig, …])	Get a source estimate from morphed source to the original subject.
`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.

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.

expand(vertices)[source]¶

Expand SourceEstimate to include more vertices.

This will add rows to stc.data (zero-filled) and modify stc.vertices to include all vertices in stc.vertices and the input vertices.

Parameters:	vertices : list of array New vertices to add. Can also contain old values.
Returns:	stc : SourceEstimate \| VectorSourceEstimate The modified stc (note: method operates inplace).

in_label(label)[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 : Label \| BiHemiLabel The label (as created for example by mne.read_label). If the label does not match any sources in the SourceEstimate, a ValueError is raised.
Returns:	stc : SourceEstimate \| VectorSourceEstimate The source estimate restricted to the given label.

lh_data¶: Left hemisphere data.

lh_vertno¶: Left hemisphere vertno.

magnitude()[source]¶

Compute magnitude of activity without directionality.

Returns:	stc : instance of SourceEstimate The source estimate without directionality information.

mean()[source]¶

Make a summary stc file with mean over time points.

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

morph(subject_to, grade=5, smooth=None, subjects_dir=None, buffer_size=64, n_jobs=1, subject_from=None, sparse=False, verbose=None)[source]¶

Warning

DEPRECATED: This function is deprecated and will be removed in version 0.18. Use morph = mne.compute_source_morph(…) and morph(stc)

Morph a source estimate from one subject to another.

Parameters:

Parameters:	subject_to : string Name of the subject on which to morph as named in the SUBJECTS_DIR grade : int, list (of two arrays), or None Resolution of the icosahedral mesh (typically 5). If None, all vertices will be used (potentially filling the surface). If a list, then values will be morphed to the set of vertices specified in in grade[0] and grade[1]. Note that specifying the vertices (e.g., grade=[np.arange(10242), np.arange(10242)] for fsaverage on a standard grade 5 source space) can be substantially faster than computing vertex locations. Note that if subject=’fsaverage’ and ‘grade=5’, this set of vertices will automatically be used (instead of computed) for speed, since this is a common morph. .. note :: If sparse=True, grade has to be set to None. smooth : int or None Number of iterations for the smoothing of the surface data. If None, smooth is automatically defined to fill the surface with non-zero values. subjects_dir : string, or None Path to SUBJECTS_DIR if it is not set in the environment. buffer_size : int Deprecated. Will be ignored. n_jobs : int Deprecated. Will be ignored. subject_from : string Name of the original subject as named in the SUBJECTS_DIR. If None, self.subject will be used. sparse : bool Morph as a sparse source estimate. If True the only parameters used are subject_to and subject_from, and grade has to be None. verbose : bool, str, int, or None If not None, override default verbose level (see `mne.verbose()` and Logging documentation for more).
Returns:	stc_to : SourceEstimate \| VectorSourceEstimate Source estimate for the destination subject.

subject_to : string: Name of the subject on which to morph as named in the SUBJECTS_DIR
grade : int, list (of two arrays), or None: Resolution of the icosahedral mesh (typically 5). If None, all vertices will be used (potentially filling the surface). If a list, then values will be morphed to the set of vertices specified in in grade[0] and grade[1]. Note that specifying the vertices (e.g., grade=[np.arange(10242), np.arange(10242)] for fsaverage on a standard grade 5 source space) can be substantially faster than computing vertex locations. Note that if subject=’fsaverage’ and ‘grade=5’, this set of vertices will automatically be used (instead of computed) for speed, since this is a common morph. .. note :: If sparse=True, grade has to be set to None.
smooth : int or None: Number of iterations for the smoothing of the surface data. If None, smooth is automatically defined to fill the surface with non-zero values.
subjects_dir : string, or None: Path to SUBJECTS_DIR if it is not set in the environment.
buffer_size : int: Deprecated. Will be ignored.
n_jobs : int: Deprecated. Will be ignored.
subject_from : string: Name of the original subject as named in the SUBJECTS_DIR. If None, self.subject will be used.
sparse : bool: Morph as a sparse source estimate. If True the only parameters used are subject_to and subject_from, and grade has to be None.
verbose : bool, str, int, or None: If not None, override default verbose level (see mne.verbose() and Logging documentation for more).

Returns:

stc_to : SourceEstimate | VectorSourceEstimate: Source estimate for the destination subject.

morph_precomputed(**kwargs)[source]¶

Warning

DEPRECATED: This function is deprecated and will be removed in version 0.18. Use morph = mne.compute_source_morph(…) and morph(stc)

Morph source estimate between subjects using a precomputed matrix.

Parameters:	subject_to : string Name of the subject on which to morph as named in the SUBJECTS_DIR. vertices_to : list of array of int The vertices on the destination subject’s brain. morph_mat : sparse matrix Deprecated. subject_from : string \| None Name of the original subject as named in the SUBJECTS_DIR. If None, self.subject will be used.
Returns:	stc_to : SourceEstimate \| VectorSourceEstimate Source estimate for the destination subject.

normal(src)[source]¶

Compute activity orthogonal to the cortex.

Parameters:	src : instance of SourceSpaces The source space for which this source estimate is specified.
Returns:	stc : instance of SourceEstimate The source estimate only retaining the activity orthogonal to the cortex.

plot(subject=None, hemi='lh', colormap='hot', time_label='auto', smoothing_steps=10, transparent=True, brain_alpha=0.4, overlay_alpha=None, vector_alpha=1.0, scale_factor=None, time_viewer=False, subjects_dir=None, figure=None, views='lat', colorbar=True, clim='auto', cortex='classic', size=800, background='black', foreground='white', initial_time=None, time_unit='s')[source]¶

Plot VectorSourceEstimates with PySurfer.

A “glass brain” is drawn and all dipoles defined in the source estimate are shown using arrows, depicting the direction and magnitude of the current moment at the dipole. Additionally, an overlay is plotted on top of the cortex with the magnitude of the current.

Parameters:

Parameters:	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. hemi : str, ‘lh’ \| ‘rh’ \| ‘split’ \| ‘both’ The hemisphere to display. 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. This should be a sequential colormap. time_label : str \| callable \| None Format of the time label (a format string, a function that maps floating point time values to strings, or None for no label). The default is `time=%0.2f ms`. smoothing_steps : int The amount of smoothing transparent : bool If True, use a linear transparency between fmin and fmid. brain_alpha : float Alpha value to apply globally to the surface meshes. Defaults to 0.4. overlay_alpha : float Alpha value to apply globally to the overlay. Defaults to `brain_alpha`. vector_alpha : float Alpha value to apply globally to the vector glyphs. Defaults to 1. scale_factor : float \| None Scaling factor for the vector glyphs. By default, an attempt is made to automatically determine a sane value. time_viewer : bool Display time viewer GUI. subjects_dir : str The path to the freesurfer subjects reconstructions. It corresponds to Freesurfer environment variable SUBJECTS_DIR. figure : instance of mayavi.core.scene.Scene \| list \| int \| None If None, a new figure will be created. If multiple views or a split view is requested, this must be a list of the appropriate length. If int is provided it will be used to identify the Mayavi figure by it’s id or create a new figure with the given id. views : str \| list View to use. See surfer.Brain(). colorbar : bool If True, display colorbar on scene. 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. Unlike `stc.plot`, it cannot use `pos_lims`, as the surface plot must show the magnitude. cortex : str or tuple specifies how binarized curvature values are rendered. either the name of a preset PySurfer cortex colorscheme (one of ‘classic’, ‘bone’, ‘low_contrast’, or ‘high_contrast’), or the name of mayavi colormap, or a tuple with values (colormap, min, max, reverse) to fully specify the curvature colors. size : float or pair of floats The size of the window, in pixels. can be one number to specify a square window, or the (width, height) of a rectangular window. background : matplotlib color Color of the background of the display window. foreground : matplotlib color Color of the foreground of the display window. initial_time : float \| None The time to display on the plot initially. `None` to display the first time sample (default). time_unit : ‘s’ \| ‘ms’ Whether time is represented in seconds (“s”, default) or milliseconds (“ms”).
Returns:	brain : Brain A instance of `surfer.Brain` from PySurfer.

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.

hemi : str, ‘lh’ | ‘rh’ | ‘split’ | ‘both’

The hemisphere to display.

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. This should be a sequential colormap.

time_label : str | callable | None

Format of the time label (a format string, a function that maps floating point time values to strings, or None for no label). The default is time=%0.2f ms.

smoothing_steps : int

The amount of smoothing

transparent : bool

If True, use a linear transparency between fmin and fmid.

brain_alpha : float

Alpha value to apply globally to the surface meshes. Defaults to 0.4.

overlay_alpha : float

Alpha value to apply globally to the overlay. Defaults to brain_alpha.

vector_alpha : float

Alpha value to apply globally to the vector glyphs. Defaults to 1.

scale_factor : float | None

Scaling factor for the vector glyphs. By default, an attempt is made to automatically determine a sane value.

time_viewer : bool

Display time viewer GUI.

subjects_dir : str

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

figure : instance of mayavi.core.scene.Scene | list | int | None

If None, a new figure will be created. If multiple views or a split view is requested, this must be a list of the appropriate length. If int is provided it will be used to identify the Mayavi figure by it’s id or create a new figure with the given id.

views : str | list

View to use. See surfer.Brain().

colorbar : bool

If True, display colorbar on scene.

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.

Unlike stc.plot, it cannot use pos_lims, as the surface plot must show the magnitude.

cortex : str or tuple

specifies how binarized curvature values are rendered. either the name of a preset PySurfer cortex colorscheme (one of ‘classic’, ‘bone’, ‘low_contrast’, or ‘high_contrast’), or the name of mayavi colormap, or a tuple with values (colormap, min, max, reverse) to fully specify the curvature colors.

size : float or pair of floats

The size of the window, in pixels. can be one number to specify a square window, or the (width, height) of a rectangular window.

background : matplotlib color

Color of the background of the display window.

foreground : matplotlib color

Color of the foreground of the display window.

initial_time : float | None

The time to display on the plot initially. None to display the first time sample (default).

time_unit : ‘s’ | ‘ms’

Whether time is represented in seconds (“s”, default) or milliseconds (“ms”).

Returns:

brain : Brain: A instance of surfer.Brain from PySurfer.

Notes

New in version 0.15.

If the current magnitude overlay is not desired, set overlay_alpha=0 and smoothing_steps=1.

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.

rh_data¶: Right hemisphere data.

rh_vertno¶: Right hemisphere vertno.

save(fname, ftype='h5', verbose=None)[source]¶

Save the full source estimate to an HDF5 file.

Parameters:	fname : string The file name to write the source estimate to, should end in ‘-stc.h5’. ftype : string File format to use. Currently, the only allowed values is “h5”. verbose : bool, str, int, or None If not None, override default verbose level (see mne.verbose). Defaults to self.verbose.

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.

to_original_src(src_orig, subject_orig=None, subjects_dir=None, verbose=None)[source]¶

Get a source estimate from morphed source to the original subject.

Parameters:

Parameters:	src_orig : instance of SourceSpaces The original source spaces that were morphed to the current subject. subject_orig : str \| None The original subject. For most source spaces this shouldn’t need to be provided, since it is stored in the source space itself. subjects_dir : string, or None Path to SUBJECTS_DIR if it is not set in the environment. verbose : bool, str, int, or None If not None, override default verbose level (see `mne.verbose()` and Logging documentation for more).
Returns:	stc : SourceEstimate \| VectorSourceEstimate The transformed source estimate.

src_orig : instance of SourceSpaces: The original source spaces that were morphed to the current subject.
subject_orig : str | None: The original subject. For most source spaces this shouldn’t need to be provided, since it is stored in the source space itself.
subjects_dir : string, or None: Path to SUBJECTS_DIR if it is not set in the environment.
verbose : bool, str, int, or None: If not None, override default verbose level (see mne.verbose() and Logging documentation for more).

Returns:

stc : SourceEstimate | VectorSourceEstimate: The transformed source estimate.