mne.SourceEstimate

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

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

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.

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.
__mul__(a)	Multiply source estimates.
__neg__()	Negate the source estimate.
__sub__(a)	Subtract source estimates.
apply_baseline([baseline, verbose])	Baseline correct source estimate data.
apply_function(fun[, picks, dtype, n_jobs, ...])	Apply a function to a subset of vertices.
apply_hilbert([picks, envelope, n_jobs, ...])	Compute analytic signal or envelope for a subset of channels/vertices.
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.
filter(l_freq, h_freq[, picks, ...])	Filter a subset of channels/vertices.
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.
resample(sfreq, *[, npad, method, window, ...])	Resample data.
save(fname[, ftype, overwrite, verbose])	Save the source estimates to a file.
save_as_surface(fname, src, *[, scale, scale_rr])	Save a surface source estimate (stc) as a GIFTI file.
savgol_filter(h_freq[, verbose])	Filter the data using Savitzky-Golay polynomial method.
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, scalings, ...])	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.

See also

VectorSourceEstimate

A container for vector surface source estimates.

VolSourceEstimate

A container for volume source estimates.

VolVectorSourceEstimate

A container for volume vector source estimates.

MixedSourceEstimate

A container for mixed surface + volume source estimates.

__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=(None, 0), *, verbose=None)

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

1. Calculate the mean signal of the baseline period.

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

apply_function(fun, picks=None, dtype=None, n_jobs=None, verbose=None, **kwargs)

Apply a function to a subset of vertices.

The function fun is applied to the vertices defined in picks. The source estimate object’s data is modified in-place. If the function returns a different data type (e.g. numpy.complex128) it must be specified using the dtype parameter, which causes the data type of all the data to change (even if the function is only applied to vertices in picks).

Note

If n_jobs > 1, more memory is required as len(picks) * n_times additional time points need to be temporarily stored in memory.

Note

If the data type changes (dtype != None), more memory is required since the original and the converted data needs to be stored in memory.

Parameters:

funcallable()

A function to be applied to the channels. The first argument of fun has to be a timeseries (numpy.ndarray). The function must operate on an array of shape (n_times,) because it will apply vertex-wise. The function must return an ndarray shaped like its input.

Note

If channel_wise=True, one can optionally access the index and/or the name of the currently processed channel within the applied function. This can enable tailored computations for different channels. To use this feature, add ch_idx and/or ch_name as additional argument(s) to your function definition.

picksstr | array_like | slice | None

Channels to include. Slices and lists of integers will be interpreted as channel indices. In lists, channel type strings (e.g., ['meg', 'eeg']) will pick channels of those types, channel name strings (e.g., ['MEG0111', 'MEG2623'] will pick the given channels. Can also be the string values 'all' to pick all channels, or 'data' to pick data channels. None (default) will pick all channels. Note that channels in info['bads'] will be included if their names or indices are explicitly provided.

dtypenumpy.dtype

Data type to use after applying the function. If None (default) the data type is not modified.

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_config context manager that sets another value for n_jobs. Ignored if vertice_wise=False as the workload is split across vertices.

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.

**kwargsdict

Additional keyword arguments to pass to fun.

Returns:

selfinstance of SourceEstimate

The SourceEstimate object with transformed data.

apply_hilbert(picks=None, envelope=False, n_jobs=None, n_fft='auto', *, verbose=None)

Compute analytic signal or envelope for a subset of channels/vertices.

Parameters:

picksstr | array_like | slice | None

Channels to include. Slices and lists of integers will be interpreted as channel indices. In lists, channel type strings (e.g., ['meg', 'eeg']) will pick channels of those types, channel name strings (e.g., ['MEG0111', 'MEG2623'] will pick the given channels. Can also be the string values 'all' to pick all channels, or 'data' to pick data channels. None (default) will pick all data channels (excluding reference MEG channels). Note that channels in info['bads'] will be included if their names or indices are explicitly provided.

envelopebool

Compute the envelope signal of each channel/vertex. Default False. See Notes.

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_config context manager that sets another value for n_jobs.

n_fftint | None | str

Points to use in the FFT for Hilbert transformation. The signal will be padded with zeros before computing Hilbert, then cut back to original length. If None, n == self.n_times. If ‘auto’, the next highest fast FFT length will be use.

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:

selfinstance of Raw, Epochs, Evoked or SourceEstimate

The raw object with transformed data.

Notes

Parameters

If envelope=False, the analytic signal for the channels/vertices defined in picks is computed and the data of the Raw object is converted to a complex representation (the analytic signal is complex valued).

If envelope=True, the absolute value of the analytic signal for the channels/vertices defined in picks is computed, resulting in the envelope signal.

If envelope=False, more memory is required since the original raw data as well as the analytic signal have temporarily to be stored in memory. If n_jobs > 1, more memory is required as len(picks) * n_times additional time points need to be temporarily stored in memory.

Also note that the n_fft parameter will allow you to pad the signal with zeros before performing the Hilbert transform. This padding is cut off, but it may result in a slightly different result (particularly around the edges). Use at your own risk.

Analytic signal

The analytic signal “x_a(t)” of “x(t)” is:

x_a = F^{-1}(F(x) 2U) = x + i y

where “F” is the Fourier transform, “U” the unit step function, and “y” the Hilbert transform of “x”. One usage of the analytic signal is the computation of the envelope signal, which is given by “e(t) = abs(x_a(t))”. Due to the linearity of Hilbert transform and the MNE inverse solution, the enevlope in source space can be obtained by computing the analytic signal in sensor space, applying the MNE inverse, and computing the envelope in source space.

bin(width, tstart=None, tstop=None, func=<function mean>)

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

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_dirpath-like | None

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

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

See also

mne.Label.center_of_mass

mne.vertex_to_mni

References

[1]

Eric Larson and Adrian K.C. Lee. The cortical dynamics underlying effective switching of auditory spatial attention. NeuroImage, 64:365–370, 2013. doi:10.1016/j.neuroimage.2012.09.006.

copy()

Return copy of source estimate instance.

Returns:

stcinstance of SourceEstimate

A copy of the source estimate.

crop(tmin=None, tmax=None, include_tmax=True)

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

Returns:

stcinstance of SourceEstimate

The cropped source estimate.

property data

Numpy array of source estimate data.

estimate_snr(info, fwd, cov, verbose=None)

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). See also [2].

Warning

This function currently only works properly for fixed orientation.

Parameters:

infomne.Info

The mne.Info object with information about the sensors and methods of measurement.

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

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

[2]

Daniel M. Goldenholz, Seppo P. Ahlfors, Matti S. Hämäläinen, Dahlia Sharon, Mamiko Ishitobi, Lucia M. Vaina, and Steven M. Stufflebeam. Mapping the signal-to-noise-ratios of cortical sources in magnetoencephalography and electroencephalography. Human Brain Mapping, 30(4):1077–1086, 2009. doi:10.1002/hbm.20571.

expand(vertices)

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='auto', allow_empty=False, verbose=None)

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 | tuple | str

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_emptybool | str

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

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:

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 absolute 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 90° 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.

• None

  No aggregation is performed, and an array of shape (n_vertices, n_times) is returned.

  New in v0.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'.

filter(l_freq, h_freq, picks=None, filter_length='auto', l_trans_bandwidth='auto', h_trans_bandwidth='auto', n_jobs=None, method='fir', iir_params=None, phase='zero', fir_window='hamming', fir_design='firwin', skip_by_annotation=('edge', 'bad_acq_skip'), pad='edge', *, verbose=None)

Filter a subset of channels/vertices.

Parameters:

l_freqfloat | None

For FIR filters, the lower pass-band edge; for IIR filters, the lower cutoff frequency. If None the data are only low-passed.

h_freqfloat | None

For FIR filters, the upper pass-band edge; for IIR filters, the upper cutoff frequency. If None the data are only high-passed.

picksstr | array_like | slice | None

Channels to include. Slices and lists of integers will be interpreted as channel indices. In lists, channel type strings (e.g., ['meg', 'eeg']) will pick channels of those types, channel name strings (e.g., ['MEG0111', 'MEG2623'] will pick the given channels. Can also be the string values 'all' to pick all channels, or 'data' to pick data channels. None (default) will pick all data channels. Note that channels in info['bads'] will be included if their names or indices are explicitly provided.

filter_lengthstr | int

Length of the FIR filter to use (if applicable):

• ‘auto’ (default): The filter length is chosen based on the size of the transition regions (6.6 times the reciprocal of the shortest transition band for fir_window=’hamming’ and fir_design=”firwin2”, and half that for “firwin”).

• str: A human-readable time in units of “s” or “ms” (e.g., “10s” or “5500ms”) will be converted to that number of samples if phase="zero", or the shortest power-of-two length at least that duration for phase="zero-double".

• int: Specified length in samples. For fir_design=”firwin”, this should not be used.

l_trans_bandwidthfloat | str

Width of the transition band at the low cut-off frequency in Hz (high pass or cutoff 1 in bandpass). Can be “auto” (default) to use a multiple of l_freq:

min(max(l_freq * 0.25, 2), l_freq)

Only used for method='fir'.

h_trans_bandwidthfloat | str

Width of the transition band at the high cut-off frequency in Hz (low pass or cutoff 2 in bandpass). Can be “auto” (default in 0.14) to use a multiple of h_freq:

min(max(h_freq * 0.25, 2.), info['sfreq'] / 2. - h_freq)

Only used for method='fir'.

n_jobsint | str

Number of jobs to run in parallel. Can be 'cuda' if cupy is installed properly and method='fir'.

methodstr

'fir' will use overlap-add FIR filtering, 'iir' will use IIR forward-backward filtering (via filtfilt()).

iir_paramsdict | None

Dictionary of parameters to use for IIR filtering. If iir_params=None and method="iir", 4th order Butterworth will be used. For more information, see mne.filter.construct_iir_filter().

phasestr

Phase of the filter. When method='fir', symmetric linear-phase FIR filters are constructed with the following behaviors when method="fir":

"zero" (default)

The delay of this filter is compensated for, making it non-causal.

"minimum"

A minimum-phase filter will be constructed by decomposing the zero-phase filter into a minimum-phase and all-pass systems, and then retaining only the minimum-phase system (of the same length as the original zero-phase filter) via scipy.signal.minimum_phase().

"zero-double"

This is a legacy option for compatibility with MNE <= 0.13. The filter is applied twice, once forward, and once backward (also making it non-causal).

"minimum-half"

This is a legacy option for compatibility with MNE <= 1.6. A minimum-phase filter will be reconstructed from the zero-phase filter with half the length of the original filter.

When method='iir', phase='zero' (default) or equivalently 'zero-double' constructs and applies IIR filter twice, once forward, and once backward (making it non-causal) using filtfilt(); phase='forward' will apply the filter once in the forward (causal) direction using lfilter().

New in v0.13.

Changed in version 1.7: The behavior for phase="minimum" was fixed to use a filter of the requested length and improved suppression.

fir_windowstr

The window to use in FIR design, can be “hamming” (default), “hann” (default in 0.13), or “blackman”.

New in v0.15.

fir_designstr

Can be “firwin” (default) to use scipy.signal.firwin(), or “firwin2” to use scipy.signal.firwin2(). “firwin” uses a time-domain design technique that generally gives improved attenuation using fewer samples than “firwin2”.

New in v0.15.

skip_by_annotationstr | list of str

If a string (or list of str), any annotation segment that begins with the given string will not be included in filtering, and segments on either side of the given excluded annotated segment will be filtered separately (i.e., as independent signals). The default (('edge', 'bad_acq_skip') will separately filter any segments that were concatenated by mne.concatenate_raws() or mne.io.Raw.append(), or separated during acquisition. To disable, provide an empty list. Only used if inst is raw.

New in v0.16..

padstr

The type of padding to use. Supports all numpy.pad() mode options. Can also be "reflect_limited", which pads with a reflected version of each vector mirrored on the first and last values of the vector, followed by zeros. Only used for method='fir'.

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:

instinstance of Epochs, Evoked, SourceEstimate, or Raw

The filtered data.

See also

mne.filter.create_filter

mne.Evoked.savgol_filter

mne.io.Raw.notch_filter

mne.io.Raw.resample

mne.filter.create_filter

mne.filter.filter_data

mne.filter.construct_iir_filter

Notes

Applies a zero-phase low-pass, high-pass, band-pass, or band-stop filter to the channels selected by picks. The data are modified inplace.

The object has to have the data loaded e.g. with preload=True or self.load_data().

l_freq and h_freq are the frequencies below which and above which, respectively, to filter out of the data. Thus the uses are:

• l_freq < h_freq: band-pass filter

• l_freq > h_freq: band-stop filter

• l_freq is not None and h_freq is None: high-pass filter

• l_freq is None and h_freq is not None: low-pass filter

self.info['lowpass'] and self.info['highpass'] are only updated with picks=None.

Note

If n_jobs > 1, more memory is required as len(picks) * n_times additional time points need to be temporarily stored in memory.

When working on SourceEstimates the sample rate of the original data is inferred from tstep.

For more information, see the tutorials Background information on filtering and Filtering and resampling data and mne.filter.create_filter().

New in v0.15.

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

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

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

in_label(label)

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.

property lh_data

Left hemisphere data.

property lh_vertno

Left hemisphere vertno.

mean()

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)

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 | 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 the matplotlib 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 v0.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 v0.15.0.

titlestr | None

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

New in v0.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 v0.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:

• https://surfer.nmr.mgh.harvard.edu/fswiki/FreeSurferOccipitalFlattenedPatch

• https://openwetware.org/wiki/Beauchamp:FreeSurfer

Examples using plot:

Visualize source time courses (stcs)

Visualize source time courses (stcs)

Plotting the full vector-valued MNE solution

Plotting the full vector-valued MNE solution

resample(sfreq, *, npad=100, method='fft', window='auto', pad='auto', n_jobs=None, verbose=None)

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

methodstr

Resampling method to use. Can be "fft" (default) or "polyphase" to use FFT-based on polyphase FIR resampling, respectively. These wrap to scipy.signal.resample() and scipy.signal.resample_poly(), respectively.

New in v1.7.

windowstr | tuple

When method="fft", this is the frequency-domain window to use in resampling, and should be the same length as the signal; see scipy.signal.resample() for details. When method="polyphase", this is the time-domain linear-phase window to use after upsampling the signal; see scipy.signal.resample_poly() for details. The default "auto" will use "boxcar" for method="fft" and ("kaiser", 5.0) for method="polyphase".

New in v1.7.

padstr

The type of padding to use. When method="fft", supports all numpy.pad() mode options. Can also be "reflect_limited", which pads with a reflected version of each vector mirrored on the first and last values of the vector, followed by zeros. When method="polyphase", supports all modes of scipy.signal.upfirdn(). The default (“auto”) means 'reflect_limited' for method='fft' and 'reflect' for method='polyphase'.

New in v1.7.

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

property rh_data

Right hemisphere data.

property rh_vertno

Right hemisphere vertno.

save(fname, ftype='stc', *, overwrite=False, verbose=None)

Save the source estimates to a file.

Parameters:

fnamepath-like

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.

overwritebool

If True (default False), overwrite the destination file if it exists.

New in v1.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.

save_as_surface(fname, src, *, scale=1, scale_rr=1000.0)

Save a surface source estimate (stc) as a GIFTI file.

Parameters:

fnamepath-like

Filename basename to save files as. Will write anatomical GIFTI plus time series GIFTI for both lh/rh, for example "basename" will write "basename.lh.gii", "basename.lh.time.gii", "basename.rh.gii", and "basename.rh.time.gii".

srcinstance of SourceSpaces

The source space of the forward solution.

scalefloat

Scale factor to apply to the data (functional) values.

scale_rrfloat

Scale factor for the source vertex positions. The default (1e3) will scale from meters to millimeters, which is more standard for GIFTI files.

Notes

New in v1.7.

savgol_filter(h_freq, verbose=None)

Filter the data using Savitzky-Golay polynomial method.

Parameters:

h_freqfloat

Approximate high cut-off frequency in Hz. Note that this is not an exact cutoff, since Savitzky-Golay filtering [3] is done using polynomial fits instead of FIR/IIR filtering. This parameter is thus used to determine the length of the window over which a 5th-order polynomial smoothing is used.

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:

instinstance of Epochs, Evoked or SourceEstimate

The object with the filtering applied.

See also

mne.io.Raw.filter

Notes

For Savitzky-Golay low-pass approximation, see:

https://gist.github.com/larsoner/bbac101d50176611136b

When working on SourceEstimates the sample rate of the original data is inferred from tstep.

New in v0.9.0.

References

[3]

Abraham Savitzky and Marcel J. E. Golay. Smoothing and differentiation of data by simplified least squares procedures. Analytical Chemistry, 36(8):1627–1639, 1964. doi:10.1021/ac60214a047.

Examples

>>> import mne
>>> from os import path as op
>>> evoked_fname = op.join(mne.datasets.sample.data_path(), 'MEG', 'sample', 'sample_audvis-ave.fif')  
>>> evoked = mne.read_evokeds(evoked_fname, baseline=(None, 0))[0]  
>>> evoked.savgol_filter(10.)  # low-pass at around 10 Hz 
>>> evoked.plot()  

property sfreq

Sample rate of the data.

property shape

Shape of the data.

sqrt()

Take the square root.

Returns:

stcinstance of SourceEstimate

A copy of the SourceEstimate with sqrt(data).

sum()

Make a summary stc file with sum over time points.

Returns:

stcSourceEstimate | VectorSourceEstimate

The modified stc.

time_as_index(times, use_rounding=False)

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, scalings=None, long_format=False, time_format=None, *, verbose=None)

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

to_original_src(src_orig, subject_orig=None, subjects_dir=None, verbose=None)

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_dirpath-like | None

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

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:

stcSourceEstimate | VectorSourceEstimate

The transformed source estimate.

See also

morph_source_spaces

Notes

New in v0.10.0.

transform(func, idx=None, tmin=None, tmax=None, copy=False)

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)

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

Overview of MEG/EEG analysis with MNE-Python

Overview of MEG/EEG analysis with MNE-Python

Getting started with mne.Report

Getting started with mne.Report

FreeSurfer MRI reconstruction

FreeSurfer MRI reconstruction

Visualize source time courses (stcs)

Visualize source time courses (stcs)

Corrupt known signal with point spread

Corrupt known signal with point spread

DICS for power mapping

DICS for power mapping

Decoding source space data

Decoding source space data

Display sensitivity maps for EEG and MEG sensors

Display sensitivity maps for EEG and MEG sensors

Use source space morphing

Use source space morphing

Morph surface source estimate

Morph surface source estimate