mne.SourceEstimate

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

Container for surface source estimates.

Parameters
dataarray of shape (n_dipoles, n_times) | tuple, shape (2,)

The data in source space. When it is a single array, the left hemisphere is stored in data[:len(vertices[0])] and the right hemisphere is stored in data[-len(vertices[1]):]. When data is a tuple, it contains 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).

verticeslist of array, shape (2,)

Vertex numbers corresponding to the data. The first element of the list contains vertices of left hemisphere and the second element contains vertices of right hemisphere.

tminscalar

Time point of the first sample in data.

tstepscalar

Time step between successive samples in data.

subjectstr | None

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

verbosebool, str, int, or None

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

See also

VectorSourceEstimate

A container for vector source estimates.

VolSourceEstimate

A container for volume source estimates.

MixedSourceEstimate

A container for mixed surface + volume source estimates.

Attributes
subjectstr | None

The subject name.

timesarray of shape (n_times,)

A timestamp for each sample.

verticeslist of array, shape (2,)

The indices of the dipoles in the left and right source space.

dataarray of shape (n_dipoles, n_times)

Numpy array of source estimate data.

shapetuple

Shape of the data.

Methods

__add__(a)

Add source estimates.

__div__(a)

Divide source estimates.

__hash__(/)

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.

center_of_mass([subject, hemi, …])

Compute the center of mass of activity.

copy()

Return copy of source estimate instance.

crop([tmin, tmax, include_tmax])

Restrict SourceEstimate to a time interval.

estimate_snr(info, fwd, cov[, verbose])

Compute time-varying SNR in the source space.

expand(vertices)

Expand SourceEstimate to include more vertices.

extract_label_time_course(labels, src[, …])

Extract label time courses for lists of labels.

get_peak([hemi, tmin, tmax, mode, …])

Get location and latency of peak amplitude.

in_label(label)

Get a source estimate object restricted to a label.

mean()

Make a summary stc file with mean over time points.

plot([subject, surface, hemi, colormap, …])

Plot SourceEstimate with PySurfer.

resample(sfreq[, npad, window, n_jobs, verbose])

Resample data.

save(fname[, ftype, verbose])

Save the source estimates to a 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([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__(/)

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

funccallable()

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

Returns
stcSourceEstimate | VectorSourceEstimate

The binned source estimate.

center_of_mass(subject=None, hemi=None, restrict_vertices=False, subjects_dir=None, surf='sphere')[source]

Compute the center of mass of activity.

This function computes the spatial center of mass on the surface as well as the temporal center of mass as in [1].

Note

All activity must occur in a single hemisphere, otherwise an error is raised. The “mass” of each point in space for computing the spatial center of mass is computed by summing across time, and vice-versa for each point in time in computing the temporal center of mass. This is useful for quantifying spatio-temporal cluster locations, especially when combined with mne.vertex_to_mni().

Parameters
subjectstr | None

The subject the stc is defined for.

hemiint, or None

Calculate the center of mass for the left (0) or right (1) hemisphere. If None, one of the hemispheres must be all zeroes, and the center of mass will be calculated for the other hemisphere (useful for getting COM for clusters).

restrict_verticesbool | array of int | instance of SourceSpaces

If True, returned vertex will be one from stc. Otherwise, it could be any vertex from surf. If an array of int, the returned vertex will come from that array. If instance of SourceSpaces (as of 0.13), the returned vertex will be from the given source space. For most accuruate estimates, do not restrict vertices.

subjects_dirstr | None

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

surfstr

The surface to use for Euclidean distance center of mass finding. The default here is “sphere”, which finds the center of mass on the spherical surface to help avoid potential issues with cortical folding.

Returns
vertexint

Vertex of the spatial center of mass for the inferred hemisphere, with each vertex weighted by the sum of the stc across time. For a boolean stc, then, this would be weighted purely by the duration each vertex was active.

hemiint

Hemisphere the vertex was taken from.

tfloat

Time of the temporal center of mass (weighted by the sum across source vertices).

References

1

Larson and Lee, “The cortical dynamics underlying effective switching of auditory spatial attention”, NeuroImage 2012.

Examples using center_of_mass:

copy()[source]

Return copy of source estimate instance.

Returns
stcinstance of SourceEstimate

A copy of the source estimate.

Examples using copy:

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

Restrict SourceEstimate to a time interval.

Parameters
tminfloat | None

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

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

Returns
stcinstance of SourceEstimate

The cropped source estimate.

Examples using crop:

property data

Numpy array of source estimate data.

estimate_snr(info, fwd, cov, verbose=None)[source]

Compute time-varying SNR in the source space.

This function should only be used with source estimates with units nanoAmperes (i.e., MNE-like solutions, not dSPM or sLORETA).

Warning

This function currently only works properly for fixed orientation.

Parameters
infoinstance Info

The measurement info.

fwdinstance of Forward

The forward solution used to create the source estimate.

covinstance of Covariance

The noise covariance used to estimate the resting cortical activations. Should be an evoked covariance, not empty room.

verbosebool, str, int, or None

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

Returns
snr_stcinstance of SourceEstimate

The source estimate with the SNR computed.

Notes

We define the SNR in decibels for each source location at each time point as:

\[{\rm SNR} = 10\log_10[\frac{a^2}{N}\sum_k\frac{b_k^2}{s_k^2}]\]

where \(\\b_k\) is the signal on sensor \(k\) provided by the forward model for a source with unit amplitude, \(a\) is the source amplitude, \(N\) is the number of sensors, and \(s_k^2\) is the noise variance on sensor \(k\).

References

1

Goldenholz, D. M., Ahlfors, S. P., Hämäläinen, M. S., Sharon, D., Ishitobi, M., Vaina, L. M., & Stufflebeam, S. M. (2009). Mapping the Signal-To-Noise-Ratios of Cortical Sources in Magnetoencephalography and Electroencephalography. Human Brain Mapping, 30(4), 1077–1086. doi:10.1002/hbm.20571

Examples using estimate_snr:

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
verticeslist of array

New vertices to add. Can also contain old values.

Returns
stcSourceEstimate | VectorSourceEstimate

The modified stc (note: method operates inplace).

extract_label_time_course(labels, src, mode='mean_flip', allow_empty=False, 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
labelsLabel | BiHemiLabel | list of Label or BiHemiLabel

The labels for which to extract the time course.

srclist

Source spaces for left and right hemisphere.

modestr

Extraction mode, see Notes.

allow_emptybool

Instead of emitting an error, return all-zero time courses for labels that do not have any vertices in the source estimate. Default is False.

verbosebool, str, int, or None

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

Returns
label_tcarray, shape=(n_labels, n_times)

Extracted time course for each label.

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.

  • '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.

Examples using extract_label_time_course:

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

Get location and latency of peak amplitude.

Parameters
hemi{‘lh’, ‘rh’, None}

The hemi to be considered. If None, the entire source space is considered.

tminfloat | None

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

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

Returns
posint

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

latencyfloat | int

The time point of the maximum response, either latency in seconds or index.

Examples using get_peak:

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
labelLabel | 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
stcSourceEstimate | VectorSourceEstimate

The source estimate restricted to the given label.

Examples using in_label:

property lh_data

Left hemisphere data.

property lh_vertno

Left hemisphere vertno.

mean()[source]

Make a summary stc file with mean over time points.

Returns
stcSourceEstimate | VectorSourceEstimate

The modified stc.

plot(subject=None, surface='inflated', hemi='lh', colormap='auto', time_label='auto', smoothing_steps=10, transparent=True, alpha=1.0, time_viewer='auto', 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', backend='auto', spacing='oct6', title=None, show_traces='auto', verbose=None)[source]

Plot SourceEstimate with PySurfer.

By default this function uses mayavi.mlab to plot the source estimates. If Mayavi is not installed, the plotting is done with matplotlib.pyplot (much slower, decimated source space by default).

Parameters
subjectstr | 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.

surfacestr

The type of surface (inflated, white etc.).

hemistr

Hemisphere id (ie ‘lh’, ‘rh’, ‘both’, or ‘split’). In the case of ‘both’, both hemispheres are shown in the same window. In the case of ‘split’ hemispheres are displayed side-by-side in different viewing panes.

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. The default (‘auto’) uses ‘hot’ for one-sided data and ‘mne’ for two-sided data.

time_labelstr | 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 'auto', which will use time=%%0.2f ms if there is more than one time point.

smoothing_stepsint

The amount of smoothing.

transparentbool | None

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

alphafloat

Alpha value to apply globally to the overlay. Has no effect with mpl backend.

time_viewerbool | str

Display time viewer GUI. Can also be ‘auto’, which will mean True for the PyVista backend and False otherwise.

Changed in version 0.20.0: “auto” mode added.

subjects_dirstr | None

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

figureinstance of mayavi.core.api.Scene | instance of matplotlib.figure.Figure | 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. If an instance of matplotlib figure, mpl backend is used for plotting.

viewsstr | list

View to use. See surfer.Brain. Supported views: [‘lat’, ‘med’, ‘ros’, ‘cau’, ‘dor’ ‘ven’, ‘fro’, ‘par’]. Using multiple views is not supported for mpl backend.

colorbarbool

If True, display colorbar on scene.

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

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.

cortexstr 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. Has no effect with mpl backend.

sizefloat or tuple of float

The size of the window, in pixels. can be one number to specify a square window, or the (width, height) of a rectangular window. Has no effect with mpl backend.

backgroundmatplotlib color

Color of the background of the display window.

foregroundmatplotlib color

Color of the foreground of the display window. Has no effect with mpl backend.

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

backend‘auto’ | ‘mayavi’ | ‘matplotlib’

Which backend to use. If 'auto' (default), tries to plot with mayavi, but resorts to matplotlib if mayavi is not available.

New in version 0.15.0.

spacingstr

The spacing to use for the source space. Can be 'ico#' for a recursively subdivided icosahedron, 'oct#' for a recursively subdivided octahedron, or 'all' for all points. In general, you can speed up the plotting by selecting a sparser source space. Has no effect with mayavi backend. Defaults to ‘oct6’.

New in version 0.15.0.

titlestr | None

Title for the figure. If None, the subject name will be used.

New in version 0.17.0.

show_tracesbool | str

If True, enable interactive picking of a point on the surface of the brain and plot it’s time course using the bottom 1/3 of the figure. This feature is only available with the PyVista 3d backend when time_viewer=True. Defaults to ‘auto’, which will use True if and only if time_viewer=True, the backend is PyVista, and there is more than one time point.

New in version 0.20.0.

verbosebool, str, int, or None

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

Returns
figureinstance of surfer.Brain | matplotlib.figure.Figure

An instance of surfer.Brain from PySurfer or matplotlib figure.

Examples using plot:

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

Resample data.

Parameters
sfreqfloat

New sample rate to use.

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

windowstr | tuple

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.

verbosebool, str, int, or None

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.

Examples using resample:

property rh_data

Right hemisphere data.

property rh_vertno

Right hemisphere vertno.

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

Save the source estimates to a file.

Parameters
fnamestr

The stem of the file name. The file names used for surface source spaces are obtained by adding “-lh.stc” and “-rh.stc” (or “-lh.w” and “-rh.w”) to the stem provided, for the left and the right hemisphere, respectively.

ftypestr

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

verbosebool, str, int, or None

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

Examples using save:

property sfreq

Sample rate of the data.

property shape

Shape of the data.

sqrt()[source]

Take the square root.

Returns
stcinstance of SourceEstimate

A copy of the SourceEstimate with sqrt(data).

sum()[source]

Make a summary stc file with sum over time points.

Returns
stcSourceEstimate | VectorSourceEstimate

The modified stc.

Examples using sum:

time_as_index(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(index=None, scaling_time=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.

scaling_timeNone

Deprecated; use time_format instead. If you need to scale time values by a factor other than 1000 (seconds → milliseconds), create the DataFrame first, then scale its time column afterwards.

scalingsdict | None

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_formatstr | None

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.

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
src_originstance of SourceSpaces

The original source spaces that were morphed to the current subject.

subject_origstr | 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_dirstr | None

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

verbosebool, str, int, or None

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

Returns
stcSourceEstimate | VectorSourceEstimate

The transformed source estimate.

Notes

New in version 0.10.0.

Examples using to_original_src:

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

idxarray | None

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

tminfloat | int | None

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

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

Returns
stcsSourceEstimate | 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

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

idxarray | None

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

tmin_idxint | None

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

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

Examples using mne.SourceEstimate