mne.MixedSourceEstimate#

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

Container for mixed surface and 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).
verticeslist of array: Vertex numbers corresponding to the data. The list contains arrays with one array per source space.
tminscalar: Time point of the first sample in data.
tstepscalar: Time step between successive samples in data.
subjectstr: The FreeSurfer subject name. While not necessary, it is safer to set the subject parameter to avoid analysis errors.
verbosebool | str | int | None: Control verbosity of the logging output. If None, use the default verbosity level. See the logging documentation and mne.verbose() for details. Should only be passed as a keyword argument.

See also

SourceEstimate: A container for surface source estimates.
VectorSourceEstimate: A container for vector surface source estimates.
VolSourceEstimate: A container for volume source estimates.
VolVectorSourceEstimate: A container for Volume vector source estimates.

Notes

New in version 0.9.0.

Attributes:

subjectstr | None: The subject name.
timesarray of shape (n_times,): A timestamp for each sample.
verticeslist of array: Vertex numbers corresponding to the data. The list contains arrays with one array per 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.
`__mul__`(a)	Multiply source estimates.
`__neg__`()	Negate the source estimate.
`__sub__`(a)	Subtract source estimates.
`apply_baseline`([baseline, verbose])	Baseline correct source estimate data.
`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, include_tmax])	Restrict SourceEstimate to a time interval.
`decimate`(decim[, offset, verbose])	Decimate the time-series data.
`extract_label_time_course`(labels, src[, ...])	Extract label time courses for lists of labels.
`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`([subject, surface, hemi, colormap, ...])	Plot SourceEstimate.
`resample`(sfreq[, npad, window, n_jobs, verbose])	Resample data.
`save`(fname[, ftype, overwrite, verbose])	Save the full source estimate to an HDF5 file.
`shift_time`(tshift[, relative])	Shift time scale in epoched or evoked data.
`sqrt`()	Take the square root.
`sum`()	Make a summary stc file with sum over time points.
`surface`()	Return the cortical surface source estimate.
`time_as_index`(times[, use_rounding])	Convert time to indices.
`to_data_frame`([index, scalings, ...])	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.
`volume`()	Return the volume surface source estimate.

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

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

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

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

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

apply_baseline(baseline=(None, 0), *, verbose=None)[source]#

Baseline correct source estimate data.

Parameters:

baselineNone | tuple of length 2

The time interval to consider as “baseline” when applying baseline correction. If None, do not apply baseline correction. If a tuple (a, b), the interval is between a and b (in seconds), including the endpoints. If a is None, the beginning of the data is used; and if b is None, it is set to the end of the interval. If (None, None), the entire time interval is used.

Note

The baseline (a, b) includes both endpoints, i.e. all timepoints t such that a <= t <= b.

Correction is applied to each source individually in the following way:

Calculate the mean signal of the baseline period.
Subtract this mean from the entire source estimate data.

Note

Baseline correction is appropriate when signal and noise are approximately additive, and the noise level can be estimated from the baseline interval. This can be the case for non-normalized source activities (e.g. signed and unsigned MNE), but it is not the case for normalized estimates (e.g. signal-to-noise ratios, dSPM, sLORETA).

Defaults to (None, 0), i.e. beginning of the the data until time point zero.

verbosebool | str | int | None

Control verbosity of the logging output. If None, use the default verbosity level. See the logging documentation and mne.verbose() for details. Should only be passed as a keyword argument.

Returns:

stcinstance of SourceEstimate: The baseline-corrected source estimate object.

Notes

Baseline correction can be done multiple times.

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.

copy()[source]#

Return copy of source estimate instance.

Returns:

stcinstance of SourceEstimate: A copy of the source estimate.

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.

property data#: Numpy array of source estimate data.

decimate(decim, offset=0, verbose=None)[source]#

Decimate the time-series data.

Parameters:

decimint: Factor by which to subsample the data.

Warning

Low-pass filtering is not performed, this simply selects every Nth sample (where N is the value passed to decim), i.e., it compresses the signal (see Notes). If the data are not properly filtered, aliasing artifacts may occur.
offsetint: Apply an offset to where the decimation starts relative to the sample corresponding to t=0. The offset is in samples at the current sampling rate.

New in version 0.12.
verbosebool | str | int | None: Control verbosity of the logging output. If None, use the default verbosity level. See the logging documentation and mne.verbose() for details. Should only be passed as a keyword argument.

Returns:

instMNE-object: The decimated object.

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(tmin=None, tmax=None, mode='abs', vert_as_index=False, time_as_index=False)[source]#

Get location and latency of peak amplitude.

Parameters:

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

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='auto', colorbar=True, clim='auto', cortex='classic', size=800, background='black', foreground=None, initial_time=None, time_unit='s', backend='auto', spacing='oct6', title=None, show_traces='auto', src=None, volume_options=1.0, view_layout='vertical', add_data_kwargs=None, brain_kwargs=None, verbose=None)[source]#

Plot SourceEstimate.

Parameters:

subjectstr | None

The FreeSurfer subject name. If None, stc.subject 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 and make values below fmin fully transparent (symmetrically for divergent colormaps). 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_dirpath-like | None

The path to the directory containing the FreeSurfer subjects reconstructions. If None, defaults to the SUBJECTS_DIR environment variable.

figureinstance of Figure3D | 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 PyVista 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. Using multiple views (list) is not supported for mpl backend. See Brain.show_view for valid string options.

When plotting a standard SourceEstimate (not volume, mixed, or vector) and using the PyVista backend, views='flat' is also supported to plot cortex as a flatmap.

Using multiple views (list) is not supported by the matplotlib backend.

Changed in version 0.21.0: Support for flatmaps.

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 Brain cortex colorscheme (one of ‘classic’, ‘bone’, ‘low_contrast’, or ‘high_contrast’), or the name of a 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 | None

Color of the foreground of the display window. Has no effect with mpl backend. None will choose white or black based on the background color.

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’ | ‘pyvistaqt’ | ‘matplotlib’

Which backend to use. If 'auto' (default), tries to plot with pyvistaqt, but resorts to matplotlib if no 3d backend is available.

New in version 0.15.0.

spacingstr

Only affects the matplotlib backend. 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. 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 | float

If True, enable interactive picking of a point on the surface of the brain and plot its time course. This feature is only available with the PyVista 3d backend, and requires 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. If float (between zero and one), it specifies what proportion of the total window should be devoted to traces (True is equivalent to 0.25, i.e., it will occupy the bottom 1/4 of the figure).

New in version 0.20.0.

srcinstance of SourceSpaces | None

The source space corresponding to the source estimate. Only necessary if the STC is a volume or mixed source estimate.

volume_optionsfloat | dict | None

Options for volumetric source estimate plotting, with key/value pairs:

'resolution'float | None
Resolution (in mm) of volume rendering. Smaller (e.g., 1.) looks better at the cost of speed. None (default) uses the volume source space resolution, which is often something like 7 or 5 mm, without resampling.
'blending'str
Can be “mip” (default) for maximum intensity projection or “composite” for composite blending using alpha values.
'alpha'float | None
Alpha for the volumetric rendering. Defaults are 0.4 for vector source estimates and 1.0 for scalar source estimates.
'surface_alpha'float | None
Alpha for the surface enclosing the volume(s). None (default) will use half the volume alpha. Set to zero to avoid plotting the surface.
'silhouette_alpha'float | None
Alpha for a silhouette along the outside of the volume. None (default) will use 0.25 * surface_alpha.
'silhouette_linewidth'float
The line width to use for the silhouette. Default is 2.

A float input (default 1.) or None will be used for the 'resolution' entry.

view_layoutstr

Can be “vertical” (default) or “horizontal”. When using “horizontal” mode, the PyVista backend must be used and hemi cannot be “split”.

add_data_kwargsdict | None

Additional arguments to brain.add_data (e.g., dict(time_label_size=10)).

brain_kwargsdict | None

Additional arguments to the mne.viz.Brain constructor (e.g., dict(silhouette=True)).

verbosebool | str | int | None

Control verbosity of the logging output. If None, use the default verbosity level. See the logging documentation and mne.verbose() for details. Should only be passed as a keyword argument.

Returns:

figureinstance of mne.viz.Brain | matplotlib.figure.Figure: An instance of mne.viz.Brain or matplotlib figure.

Notes

Flatmaps are available by default for fsaverage but not for other subjects reconstructed by FreeSurfer. We recommend using mne.compute_source_morph() to morph source estimates to fsaverage for flatmap plotting. If you want to construct your own flatmap for a given subject, these links might help:

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

Resample data.

If appropriate, an anti-aliasing filter is applied before resampling. See Resampling and decimating data for more information.

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 | None: The number of jobs to run in parallel. If -1, it is set to the number of CPU cores. Requires the joblib package. None (default) is a marker for ‘unset’ that will be interpreted as n_jobs=1 (sequential execution) unless the call is performed under a joblib.parallel_backend() context manager that sets another value for n_jobs.
verbosebool | str | int | None: Control verbosity of the logging output. If None, use the default verbosity level. See the logging documentation and mne.verbose() for details. Should only be passed as a keyword argument.

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(fname, ftype='h5', *, overwrite=False, verbose=None)[source]#

Save the full source estimate to an HDF5 file.

Parameters:

fnamestr: The file name to write the source estimate to, should end in ‘-stc.h5’.
ftypestr: File format to use. Currently, the only allowed values is “h5”.
overwritebool: If True (default False), overwrite the destination file if it exists.

New in version 1.0.
verbosebool | str | int | None: Control verbosity of the logging output. If None, use the default verbosity level. See the logging documentation and mne.verbose() for details. Should only be passed as a keyword argument.

property sfreq#: Sample rate of the data.

property shape#: Shape of the data.

shift_time(tshift, relative=True)[source]#

Shift time scale in epoched or evoked data.

Parameters:

tshiftfloat: The (absolute or relative) time shift in seconds. If relative is True, positive tshift increases the time value associated with each sample, while negative tshift decreases it.
relativebool: If True, increase or decrease time values by tshift seconds. Otherwise, shift the time values such that the time of the first sample equals tshift.

Returns:

epochsMNE-object: The modified instance.

Notes

This method allows you to shift the time values associated with each data sample by an arbitrary amount. It does not resample the signal or change the data values in any way.

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.

surface()[source]#

Return the cortical surface source estimate.

Returns:

stcinstance of SourceEstimate or VectorSourceEstimate: The surface source estimate.

Examples using surface:

Compute MNE inverse solution on evoked data with a mixed source space

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 tmax#: Last time point.

property tmin#: The first timestamp.

to_data_frame(index=None, scalings=None, long_format=False, time_format=None, *, verbose=None)[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.
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. Default is None.

New in version 0.20.
verbosebool | str | int | None: Control verbosity of the logging output. If None, use the default verbosity level. See the logging documentation and mne.verbose() for details. Should only be passed as a keyword argument.

Returns:

dfinstance of pandas.DataFrame: A dataframe suitable for usage with other statistical/plotting/analysis packages.

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

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

volume()[source]#

Return the volume surface source estimate.

Returns:

stcinstance of VolSourceEstimate or VolVectorSourceEstimate: The volume source estimate.

Examples using volume:

Compute MNE inverse solution on evoked data with a mixed source space

Examples using `mne.MixedSourceEstimate`#

The SourceEstimate data structure

Compute MNE inverse solution on evoked data with a mixed source space

mne.MixedSourceEstimate#

Examples using mne.MixedSourceEstimate#

Examples using `mne.MixedSourceEstimate`#