mne.Evoked ¶

Plotting topographic maps of evoked data¶

animate_topomap(ch_type=None, times=None, frame_rate=None, butterfly=False, blit=True, show=True, time_unit='s', sphere=None)[source]¶

Make animation of evoked data as topomap timeseries.

The animation can be paused/resumed with left mouse button. Left and right arrow keys can be used to move backward or forward in time.

Parameters

ch_typestr | None: Channel type to plot. Accepted data types: ‘mag’, ‘grad’, ‘eeg’, ‘hbo’, ‘hbr’, ‘fnirs_od, and ‘fnirs_cw_amplitude’. If None, first available channel type from (‘mag’, ‘grad’, ‘eeg’, ‘hbo’, ‘hbr’, ‘fnirs_od, ‘fnirs_cw_amplitude’) is used. Defaults to None.
timesarray of float | None: The time points to plot. If None, 10 evenly spaced samples are calculated over the evoked time series. Defaults to None.
frame_rateint | None: Frame rate for the animation in Hz. If None, frame rate = sfreq / 10. Defaults to None.
butterflybool: Whether to plot the data as butterfly plot under the topomap. Defaults to False.
blitbool: Whether to use blit to optimize drawing. In general, it is recommended to use blit in combination with show=True. If you intend to save the animation it is better to disable blit. Defaults to True.
showbool: Whether to show the animation. Defaults to True.
time_unitstr: The units for the time axis, can be “ms” (default in 0.16) or “s” (will become the default in 0.17).

New in version 0.16.
spherefloat | array_like | str | None: The sphere parameters to use for the cartoon head. Can be array-like of shape (4,) to give the X/Y/Z origin and radius in meters, or a single float to give the radius (origin assumed 0, 0, 0). Can also be a spherical ConductorModel, which will use the origin and radius. Can be “auto” to use a digitization-based fit. Can also be None (default) to use ‘auto’ when enough extra digitization points are available, and 0.095 otherwise. Currently the head radius does not affect plotting.

New in version 0.20.

Returns

figinstance of matplotlib.figure.Figure: The figure.
animinstance of matplotlib.animation.FuncAnimation: Animation of the topomap.

Notes

New in version 0.12.0.

Examples using animate_topomap:

anonymize(daysback=None, keep_his=False, verbose=None)[source]¶

Anonymize measurement information in place.

Parameters

daysbackint | None: Number of days to subtract from all dates. If None (default), the acquisition date, info['meas_date'], will be set to January 1ˢᵗ, 2000. This parameter is ignored if info['meas_date'] is None (i.e., no acquisition date has been set).
keep_hisbool: If True, his_id of subject_info will not be overwritten. Defaults to False.

Warning

This could mean that info is not fully anonymized. Use with caution.
verbosebool, str, int, or None: If not None, override default verbose level (see mne.verbose() and Logging documentation for more). If used, it should be passed as a keyword-argument only.

Returns

instinstance of Raw | Epochs | Evoked: The modified instance.

Notes

Removes potentially identifying information if it exists in info. Specifically for each of the following we use:

meas_date, file_id, meas_id
A default value, or as specified by daysback.
subject_info
Default values, except for ‘birthday’ which is adjusted to maintain the subject age.
experimenter, proj_name, description
Default strings.
utc_offset
None.
proj_id
Zeros.
proc_history
Dates use the meas_date logic, and experimenter a default string.
helium_info, device_info
Dates use the meas_date logic, meta info uses defaults.

If info['meas_date'] is None, it will remain None during processing the above fields.

Operates in place.

New in version 0.13.0.

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

Baseline correct evoked 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 channel individually in the following way:

Calculate the mean signal of the baseline period.
Subtract this mean from the entire Evoked.

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

verbosebool, str, int, or None

If not None, override default verbose level (see mne.verbose() and Logging documentation for more). If used, it should be passed as a keyword-argument only. Defaults to self.verbose.

Returns

evokedinstance of Evoked: The baseline-corrected Evoked object.

Notes

Baseline correction can be done multiple times.

New in version 0.13.0.

Examples using apply_baseline:

Repairing artifacts with ICA¶

apply_hilbert(picks=None, envelope=False, n_jobs=1, n_fft='auto', verbose=None)[source]¶

Compute analytic signal or envelope for a subset of channels.

Parameters

picksstr | list | 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).
envelopebool: Compute the envelope signal of each channel. Default False. See Notes.
n_jobsint: The number of jobs to run in parallel (default 1). Requires the joblib package.
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, or None: If not None, override default verbose level (see mne.verbose() and Logging documentation for more). If used, it should be passed as a keyword-argument only. Defaults to self.verbose.

Returns

selfinstance of Raw, Epochs, or Evoked: The raw object with transformed data.

Notes

Parameters

If envelope=False, the analytic signal for the channels 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 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 temporaily 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.

apply_proj(verbose=None)[source]¶

Apply the signal space projection (SSP) operators to the data.

Parameters

verbosebool, str, int, or None: If not None, override default verbose level (see mne.verbose() and Logging documentation for more). If used, it should be passed as a keyword-argument only. Defaults to self.verbose.

Returns

selfinstance of Raw | Epochs | Evoked: The instance.

Notes

Once the projectors have been applied, they can no longer be removed. It is usually not recommended to apply the projectors at too early stages, as they are applied automatically later on (e.g. when computing inverse solutions). Hint: using the copy method individual projection vectors can be tested without affecting the original data. With evoked data, consider the following example:

projs_a = mne.read_proj('proj_a.fif')
projs_b = mne.read_proj('proj_b.fif')
# add the first, copy, apply and see ...
evoked.add_proj(a).copy().apply_proj().plot()
# add the second, copy, apply and see ...
evoked.add_proj(b).copy().apply_proj().plot()
# drop the first and see again
evoked.copy().del_proj(0).apply_proj().plot()
evoked.apply_proj()  # finally keep both

Examples using apply_proj:

Interpolate bad channels for MEG/EEG channels¶

as_type(ch_type='grad', mode='fast')[source]¶

Compute virtual evoked using interpolated fields.

Warning

Using virtual evoked to compute inverse can yield unexpected results. The virtual channels have '_v' appended at the end of the names to emphasize that the data contained in them are interpolated.

Parameters

ch_typestr: The destination channel type. It can be ‘mag’ or ‘grad’.
modestr: Either 'accurate' or 'fast', determines the quality of the Legendre polynomial expansion used. 'fast' should be sufficient for most applications.

Returns

evokedinstance of mne.Evoked: The transformed evoked object containing only virtual channels.

Notes

This method returns a copy and does not modify the data it operates on. It also returns an EvokedArray instance.

New in version 0.9.0.

Examples using as_type:

Remap MEG channel types¶

property ch_names¶: Channel names.

property compensation_grade¶: The current gradient compensation grade.

copy()[source]¶

Copy the instance of evoked.

Returns

evokedinstance of Evoked: A copy of the object.

Examples using copy:

Plotting topographic arrowmaps of evoked data¶

Compute source power spectral density (PSD) of VectorView and OPM data¶

Computing source space SNR¶

Optically pumped magnetometer (OPM) data¶

HF-SEF dataset¶

Computing a covariance matrix¶

Source localization with equivalent current dipole (ECD) fit¶

4D Neuroimaging/BTi phantom dataset tutorial¶

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

Crop data to a given time interval.

Parameters

tminfloat | None: Start time of selection in seconds.
tmaxfloat | None: End time of selection in seconds.
include_tmaxbool: If True (default), include tmax. If False, exclude tmax (similar to how Python indexing typically works).

New in version 0.19.
verbosebool, str, int, or None: If not None, override default verbose level (see mne.verbose() and Logging documentation for more). If used, it should be passed as a keyword-argument only. Defaults to self.verbose.

Returns

evokedinstance of Evoked: The cropped Evoked object, modified in-place.

Notes

Unlike Python slices, MNE time intervals by default include both their end points; crop(tmin, tmax) returns the interval tmin <= t <= tmax. Pass include_tmax=False to specify the half-open interval tmin <= t < tmax instead.

Examples using crop:

Make an MNE-Report with a Slider¶

Source localization with a custom inverse solver¶

Compute a sparse inverse solution using the Gamma-MAP empirical Bayesian method¶

Compute sparse inverse solution with mixed norm: MxNE and irMxNE¶

Compute iterative reweighted TF-MxNE with multiscale time-frequency dictionary¶

Compute Rap-Music on evoked data¶

Compute MxNE with time-frequency sparse prior¶

Source localization with equivalent current dipole (ECD) fit¶

Computing various MNE solutions¶

Visualize source time courses (stcs)¶

Non-parametric 1 sample cluster statistic on single trial power¶

Brainstorm CTF phantom dataset tutorial¶

property data¶: The data matrix.

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

Decimate the evoked 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, or None: If not None, override default verbose level (see mne.verbose() and Logging documentation for more). If used, it should be passed as a keyword-argument only. Defaults to self.verbose.

Returns

evokedinstance of Evoked: The decimated Evoked object.

See also

Epochs.decimate
Epochs.resample
mne.io.Raw.resample

Notes

For historical reasons, decim / “decimation” refers to simply subselecting samples from a given signal. This contrasts with the broader signal processing literature, where decimation is defined as (quoting 1, p. 172; which cites 2):

“… a general system for downsampling by a factor of M is the one shown in Figure 4.23. Such a system is called a decimator, and downsampling by lowpass filtering followed by compression [i.e, subselecting samples] has been termed decimation (Crochiere and Rabiner, 1983).”

Hence “decimation” in MNE is what is considered “compression” in the signal processing community.

Decimation can be done multiple times. For example, inst.decimate(2).decimate(2) will be the same as inst.decimate(4).

New in version 0.13.0.

Examples using decimate:

Visualize source time courses (stcs)¶

del_proj(idx='all')[source]¶

Remove SSP projection vector.

Note

The projection vector can only be removed if it is inactive (has not been applied to the data).

Parameters

idxint | list of int | str: Index of the projector to remove. Can also be “all” (default) to remove all projectors.

Returns

selfinstance of Raw | Epochs | Evoked: The instance.

Examples using del_proj:

Compute source power estimate by projecting the covariance with MNE¶

detrend(order=1, picks=None)[source]¶

Detrend data.

This function operates in-place.

Parameters

orderint: Either 0 or 1, the order of the detrending. 0 is a constant (DC) detrend, 1 is a linear detrend.
picksstr | list | 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 good data channels.

Returns

evokedinstance of Evoked: The detrended evoked object.

drop_channels(ch_names)[source]¶

Drop channel(s).

Parameters

ch_namesiterable or str: Iterable (e.g. list) of channel name(s) or channel name to remove.

Returns

instinstance of Raw, Epochs, or Evoked: The modified instance.

See also

reorder_channels
pick_channels
pick_types

Notes

New in version 0.9.0.

Examples using drop_channels:

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

Filter a subset of channels.

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

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 is None and method=”iir”, 4th order Butterworth will be used. For more information, see mne.filter.construct_iir_filter().

phasestr

Phase of the filter, only used if method='fir'. Symmetric linear-phase FIR filters are constructed, and if phase='zero' (default), the delay of this filter is compensated for, making it non-causal. If phase=='zero-double', then this filter is applied twice, once forward, and once backward (also making it non-causal). If ‘minimum’, then a minimum-phase filter will be constricted and applied, which is causal but has weaker stop-band suppression.

New in version 0.13.

fir_windowstr

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

New in version 0.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 version 0.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 version 0.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, or None

If not None, override default verbose level (see mne.verbose() and Logging documentation for more). If used, it should be passed as a keyword-argument only. Defaults to self.verbose.

Returns

instinstance of Epochs, Evoked, 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 temporaily stored in memory.

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

New in version 0.15.

Examples using filter:

HF-SEF dataset¶

Brainstorm auditory tutorial dataset¶

get_channel_types(picks=None, unique=False, only_data_chs=False)[source]¶

Get a list of channel type for each channel.

Parameters

picksstr | list | 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.
uniquebool: Whether to return only unique channel types. Default is False.
only_data_chsbool: Whether to ignore non-data channels. Default is False.

Returns

channel_typeslist: The channel types.

get_montage()[source]¶

Get a DigMontage from instance.

Returns

montageNone | str | DigMontage: A montage containing channel positions. If str or DigMontage is specified, the channel info will be updated with the channel positions. Default is None. See also the documentation of mne.channels.DigMontage for more information.

get_peak(ch_type=None, tmin=None, tmax=None, mode='abs', time_as_index=False, merge_grads=False, return_amplitude=False)[source]¶

Get location and latency of peak amplitude.

Parameters

ch_type‘mag’, ‘grad’, ‘eeg’, ‘seeg’, ‘ecog’, ‘hbo’, hbr’, ‘misc’, None: The channel type to use. Defaults to None. If more than one sensor Type is present in the data the channel type has to be explicitly set.
tminfloat | None: The minimum point in time to be considered for peak getting. If None (default), the beginning of the data is used.
tmaxfloat | None: The maximum point in time to be considered for peak getting. If None (default), the end of the data is used.
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’.
time_as_indexbool: Whether to return the time index instead of the latency in seconds.
merge_gradsbool: If True, compute peak from merged gradiometer data.
return_amplitudebool: If True, return also the amplitude at the maximum response.

New in version 0.16.

Returns

ch_namestr: The channel exhibiting the maximum response.
latencyfloat | int: The time point of the maximum response, either latency in seconds or index.
amplitudefloat: The amplitude of the maximum response. Only returned if return_amplitude is True.

New in version 0.16.

Examples using get_peak:

Make figures more publication ready¶

interpolate_bads(reset_bads=True, mode='accurate', origin='auto', method=None, verbose=None)[source]¶

Interpolate bad MEG and EEG channels.

Operates in place.

Parameters

reset_badsbool

If True, remove the bads from info.

modestr

Either 'accurate' or 'fast', determines the quality of the Legendre polynomial expansion used for interpolation of channels using the minimum-norm method.

originarray_like, shape (3,) | str

Origin of the sphere in the head coordinate frame and in meters. Can be 'auto' (default), which means a head-digitization-based origin fit.

New in version 0.17.

methoddict

Method to use for each channel type. Currently only the key “eeg” has multiple options:

"spline" (default)
Use spherical spline interpolation.
"MNE"
Use minimum-norm projection to a sphere and back. This is the method used for MEG channels.

The value for “meg” is “MNE”, and the value for “fnirs” is “nearest”. The default (None) is thus an alias for:

method=dict(meg="MNE", eeg="spline", fnirs="nearest")

New in version 0.21.

verbosebool, str, int, or None

If not None, override default verbose level (see mne.verbose() and Logging documentation for more). If used, it should be passed as a keyword-argument only. Defaults to self.verbose.

Returns

instinstance of Raw, Epochs, or Evoked: The modified instance.

Notes

New in version 0.9.0.

property kind¶: The data kind.

pick(picks, exclude=())[source]¶

Pick a subset of channels.

Parameters

picksstr | list | 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.
excludelist | str: Set of channels to exclude, only used when picking based on types (e.g., exclude=”bads” when picks=”meg”).

Returns

instinstance of Raw, Epochs, or Evoked: The modified instance.

Examples using pick:

pick_channels(ch_names, ordered=False)[source]¶

Pick some channels.

Parameters

ch_nameslist: The list of channels to select.
orderedbool: If True (default False), ensure that the order of the channels in the modified instance matches the order of ch_names.

New in version 0.20.0.

Returns

instinstance of Raw, Epochs, or Evoked: The modified instance.

See also

drop_channels
pick_types
reorder_channels

Notes

The channel names given are assumed to be a set, i.e. the order does not matter. The original order of the channels is preserved. You can use reorder_channels to set channel order if necessary.

New in version 0.9.0.

Examples using pick_channels:

Make figures more publication ready¶

pick_types(meg=None, eeg=False, stim=False, eog=False, ecg=False, emg=False, ref_meg='auto', misc=False, resp=False, chpi=False, exci=False, ias=False, syst=False, seeg=False, dipole=False, gof=False, bio=False, ecog=False, fnirs=False, csd=False, include=(), exclude='bads', selection=None, verbose=None)[source]¶

Pick some channels by type and names.

Parameters

megbool | str: If True include MEG channels. If string it can be ‘mag’, ‘grad’, ‘planar1’ or ‘planar2’ to select only magnetometers, all gradiometers, or a specific type of gradiometer.
eegbool: If True include EEG channels.
stimbool: If True include stimulus channels.
eogbool: If True include EOG channels.
ecgbool: If True include ECG channels.
emgbool: If True include EMG channels.
ref_megbool | str: If True include CTF / 4D reference channels. If ‘auto’, reference channels are included if compensations are present and meg is not False. Can also be the string options for the meg parameter.
miscbool: If True include miscellaneous analog channels.
respbool: If True include response-trigger channel. For some MEG systems this is separate from the stim channel.
chpibool: If True include continuous HPI coil channels.
excibool: Flux excitation channel used to be a stimulus channel.
iasbool: Internal Active Shielding data (maybe on Triux only).
systbool: System status channel information (on Triux systems only).
seegbool: Stereotactic EEG channels.
dipolebool: Dipole time course channels.
gofbool: Dipole goodness of fit channels.
biobool: Bio channels.
ecogbool: Electrocorticography channels.
fnirsbool | str: Functional near-infrared spectroscopy channels. If True include all fNIRS channels. If False (default) include none. If string it can be ‘hbo’ (to include channels measuring oxyhemoglobin) or ‘hbr’ (to include channels measuring deoxyhemoglobin).
csdbool: EEG-CSD channels.
includelist of str: List of additional channels to include. If empty do not include any.
excludelist of str | str: List of channels to exclude. If ‘bads’ (default), exclude channels in info['bads'].
selectionlist of str: Restrict sensor channels (MEG, EEG) to this list of channel names.
verbosebool, str, int, or None: If not None, override default verbose level (see mne.verbose() and Logging documentation for more). If used, it should be passed as a keyword-argument only. Defaults to self.verbose.

Returns

instinstance of Raw, Epochs, or Evoked: The modified instance.

See also

pick_channels

Notes

New in version 0.9.0.

Examples using pick_types:

Source localization with a custom inverse solver¶

Compute a sparse inverse solution using the Gamma-MAP empirical Bayesian method¶

Compute sparse inverse solution with mixed norm: MxNE and irMxNE¶

Compute iterative reweighted TF-MxNE with multiscale time-frequency dictionary¶

Compute Rap-Music on evoked data¶

Compute MxNE with time-frequency sparse prior¶

Overview of MEG/EEG analysis with MNE-Python¶

Source localization with equivalent current dipole (ECD) fit¶

Visualize source time courses (stcs)¶

plot(picks=None, exclude='bads', unit=True, show=True, ylim=None, xlim='tight', proj=False, hline=None, units=None, scalings=None, titles=None, axes=None, gfp=False, window_title=None, spatial_colors=False, zorder='unsorted', selectable=True, noise_cov=None, time_unit='s', sphere=None, verbose=None)[source]¶

Plot evoked data using butterfly plots.

Left click to a line shows the channel name. Selecting an area by clicking and holding left mouse button plots a topographic map of the painted area.

Note

If bad channels are not excluded they are shown in red.

Parameters

picksstr | list | 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.
excludelist of str | ‘bads’: Channels names to exclude from being shown. If ‘bads’, the bad channels are excluded.
unitbool: Scale plot with channel (SI) unit.
showbool: Show figure if True.
ylimdict | None: Y limits for plots (after scaling has been applied). e.g. ylim = dict(eeg=[-20, 20]) Valid keys are eeg, mag, grad, misc. If None, the ylim parameter for each channel equals the pyplot default.
xlim‘tight’ | tuple | None: X limits for plots.
projbool | ‘interactive’ | ‘reconstruct’: If true SSP projections are applied before display. If ‘interactive’, a check box for reversible selection of SSP projection vectors will be shown. If ‘reconstruct’, projection vectors will be applied and then M/EEG data will be reconstructed via field mapping to reduce the signal bias caused by projection.

Changed in version 0.21: Support for ‘reconstruct’ was added.
hlinelist of float | None: The values at which to show an horizontal line.
unitsdict | None: The units of the channel types used for axes labels. If None, defaults to dict(eeg='µV', grad='fT/cm', mag='fT').
scalingsdict | None: The scalings of the channel types to be applied for plotting. If None, defaults to dict(eeg=1e6, grad=1e13, mag=1e15).
titlesdict | None: The titles associated with the channels. If None, defaults to dict(eeg='EEG', grad='Gradiometers', mag='Magnetometers').
axesinstance of Axes | list | None: The axes to plot to. If list, the list must be a list of Axes of the same length as the number of channel types. If instance of Axes, there must be only one channel type plotted.
gfpbool | ‘only’: Plot GFP in green if True or “only”. If “only”, then the individual channel traces will not be shown.
window_titlestr | None: The title to put at the top of the figure.
spatial_colorsbool: If True, the lines are color coded by mapping physical sensor coordinates into color values. Spatially similar channels will have similar colors. Bad channels will be dotted. If False, the good channels are plotted black and bad channels red. Defaults to False.
zorderstr | callable(): Which channels to put in the front or back. Only matters if spatial_colors is used. If str, must be std or unsorted (defaults to unsorted). If std, data with the lowest standard deviation (weakest effects) will be put in front so that they are not obscured by those with stronger effects. If unsorted, channels are z-sorted as in the evoked instance. If callable, must take one argument: a numpy array of the same dimensionality as the evoked raw data; and return a list of unique integers corresponding to the number of channels.

New in version 0.13.0.
selectablebool: Whether to use interactive features. If True (default), it is possible to paint an area to draw topomaps. When False, the interactive features are disabled. Disabling interactive features reduces memory consumption and is useful when using axes parameter to draw multiaxes figures.

New in version 0.13.0.
noise_covinstance of Covariance | str | None: Noise covariance used to whiten the data while plotting. Whitened data channel names are shown in italic. Can be a string to load a covariance from disk. See also mne.Evoked.plot_white() for additional inspection of noise covariance properties when whitening evoked data. For data processed with SSS, the effective dependence between magnetometers and gradiometers may introduce differences in scaling, consider using mne.Evoked.plot_white().

New in version 0.16.0.
time_unitstr: The units for the time axis, can be “ms” or “s” (default).

New in version 0.16.
spherefloat | array_like | str | None: The sphere parameters to use for the cartoon head. Can be array-like of shape (4,) to give the X/Y/Z origin and radius in meters, or a single float to give the radius (origin assumed 0, 0, 0). Can also be a spherical ConductorModel, which will use the origin and radius. Can be “auto” to use a digitization-based fit. Can also be None (default) to use ‘auto’ when enough extra digitization points are available, and 0.095 otherwise. Currently the head radius does not affect plotting.

New in version 0.20.
verbosebool, str, int, or None: If not None, override default verbose level (see mne.verbose() and Logging documentation for more). If used, it should be passed as a keyword-argument only.

Returns

figinstance of matplotlib.figure.Figure: Figure containing the butterfly plots.

See also

mne.viz.plot_evoked_white

Examples using plot:

Creating MNE objects from data arrays¶

Reading epochs from a raw FIF file¶

Reading and writing an evoked file¶

Generate simulated evoked data¶

Simulate raw data using subject anatomy¶

Generate simulated source data¶

Define target events based on time lag, plot evoked response¶

Interpolate bad channels for MEG/EEG channels¶

Re-referencing the EEG signal¶

Shifting time-scale in evoked data¶

Whitening evoked data with a noise covariance¶

Make figures more publication ready¶

Regression on continuous data (rER[P/F])¶

Analysis of evoked response using ICA and PCA reduction techniques¶

Compute a sparse inverse solution using the Gamma-MAP empirical Bayesian method¶

Compute sparse inverse solution with mixed norm: MxNE and irMxNE¶

Compute source power estimate by projecting the covariance with MNE¶

Compute iterative reweighted TF-MxNE with multiscale time-frequency dictionary¶

Compute Rap-Music on evoked data¶

Compute MxNE with time-frequency sparse prior¶

Optically pumped magnetometer (OPM) data¶

Overview of artifact detection¶

EEG processing and Event Related Potentials (ERPs)¶

Plotting whitened data¶

Source localization with MNE/dSPM/sLORETA/eLORETA¶

Non-parametric 1 sample cluster statistic on single trial power¶

Non-parametric between conditions cluster statistic on single trial power¶

Creating MNE’s data structures from scratch¶

Brainstorm auditory tutorial dataset¶

Brainstorm CTF phantom dataset tutorial¶

Brainstorm Elekta phantom dataset tutorial¶

4D Neuroimaging/BTi phantom dataset tutorial¶

Getting started with mne.Report¶

plot_field(surf_maps, time=None, time_label='t = %0.0f ms', n_jobs=1, fig=None, vmax=None, n_contours=21, verbose=None)[source]¶

Plot MEG/EEG fields on head surface and helmet in 3D.

Parameters

surf_mapslist: The surface mapping information obtained with make_field_map.
timefloat | None: The time point at which the field map shall be displayed. If None, the average peak latency (across sensor types) is used.
time_labelstr | None: How to print info about the time instant visualized.
n_jobsint: The number of jobs to run in parallel (default 1). Requires the joblib package.
figinstance of mayavi.core.api.Scene | None: If None (default), a new figure will be created, otherwise it will plot into the given figure.

New in version 0.20.
vmaxfloat | None: Maximum intensity. Can be None to use the max(abs(data)).

New in version 0.21.
n_contoursint: The number of contours.

New in version 0.21.
verbosebool, str, int, or None: If not None, override default verbose level (see mne.verbose() and Logging documentation for more). If used, it should be passed as a keyword-argument only.

Returns

figinstance of mayavi.mlab.Figure: The mayavi figure.

Examples using plot_field:

Plot the MNE brain and helmet¶

Reading and writing an evoked file¶

plot_image(picks=None, exclude='bads', unit=True, show=True, clim=None, xlim='tight', proj=False, units=None, scalings=None, titles=None, axes=None, cmap='RdBu_r', colorbar=True, mask=None, mask_style=None, mask_cmap='Greys', mask_alpha=0.25, time_unit='s', show_names=None, group_by=None, sphere=None)[source]¶

Plot evoked data as images.

Parameters

picksstr | list | slice | None

excludelist of str | ‘bads’

Channels names to exclude from being shown. If ‘bads’, the bad channels are excluded.

unitbool

Scale plot with channel (SI) unit.

showbool

Show figure if True.

climdict | None

Color limits for plots (after scaling has been applied). e.g. clim = dict(eeg=[-20, 20]). Valid keys are eeg, mag, grad, misc. If None, the clim parameter for each channel equals the pyplot default.

xlim‘tight’ | tuple | None

X limits for plots.

projbool | ‘interactive’

If true SSP projections are applied before display. If ‘interactive’, a check box for reversible selection of SSP projection vectors will be shown.

unitsdict | None

The units of the channel types used for axes labels. If None, defaults to dict(eeg='µV', grad='fT/cm', mag='fT').

scalingsdict | None

The scalings of the channel types to be applied for plotting. If None,` defaults to dict(eeg=1e6, grad=1e13, mag=1e15).

titlesdict | None

The titles associated with the channels. If None, defaults to dict(eeg='EEG', grad='Gradiometers', mag='Magnetometers').

axesinstance of Axes | list | dict | None

The axes to plot to. If list, the list must be a list of Axes of the same length as the number of channel types. If instance of Axes, there must be only one channel type plotted. If group_by is a dict, this cannot be a list, but it can be a dict of lists of axes, with the keys matching those of group_by. In that case, the provided axes will be used for the corresponding groups. Defaults to None.

cmapmatplotlib colormap | (colormap, bool) | ‘interactive’

Colormap. If tuple, the first value indicates the colormap to use and the second value is a boolean defining interactivity. In interactive mode the colors are adjustable by clicking and dragging the colorbar with left and right mouse button. Left mouse button moves the scale up and down and right mouse button adjusts the range. Hitting space bar resets the scale. Up and down arrows can be used to change the colormap. If ‘interactive’, translates to ('RdBu_r', True). Defaults to 'RdBu_r'.

colorbarbool

If True, plot a colorbar. Defaults to True.

New in version 0.16.

maskndarray | None

An array of booleans of the same shape as the data. Entries of the data that correspond to False in the mask are masked (see do_mask below). Useful for, e.g., masking for statistical significance.

New in version 0.16.

mask_styleNone | ‘both’ | ‘contour’ | ‘mask’

If mask is not None: if ‘contour’, a contour line is drawn around the masked areas (True in mask). If ‘mask’, entries not True in mask are shown transparently. If ‘both’, both a contour and transparency are used. If None, defaults to ‘both’ if mask is not None, and is ignored otherwise.

New in version 0.16.

mask_cmapmatplotlib colormap | (colormap, bool) | ‘interactive’

The colormap chosen for masked parts of the image (see below), if mask is not None. If None, cmap is reused. Defaults to Greys. Not interactive. Otherwise, as cmap.

mask_alphafloat

A float between 0 and 1. If mask is not None, this sets the alpha level (degree of transparency) for the masked-out segments. I.e., if 0, masked-out segments are not visible at all. Defaults to .25.

New in version 0.16.

time_unitstr

The units for the time axis, can be “ms” or “s” (default).

New in version 0.16.

show_namesbool | ‘auto’ | ‘all’

Determines if channel names should be plotted on the y axis. If False, no names are shown. If True, ticks are set automatically by matplotlib and the corresponding channel names are shown. If “all”, all channel names are shown. If “auto”, is set to False if picks is None, to True if picks contains 25 or more entries, or to “all” if picks contains fewer than 25 entries.

group_byNone | dict

If a dict, the values must be picks, and axes must also be a dict with matching keys, or None. If axes is None, one figure and one axis will be created for each entry in group_by.Then, for each entry, the picked channels will be plotted to the corresponding axis. If titles are None, keys will become plot titles. This is useful for e.g. ROIs. Each entry must contain only one channel type. For example:

group_by=dict(Left_ROI=[1, 2, 3, 4], Right_ROI=[5, 6, 7, 8])

If None, all picked channels are plotted to the same axis.

spherefloat | array_like | str | None

The sphere parameters to use for the cartoon head. Can be array-like of shape (4,) to give the X/Y/Z origin and radius in meters, or a single float to give the radius (origin assumed 0, 0, 0). Can also be a spherical ConductorModel, which will use the origin and radius. Can be “auto” to use a digitization-based fit. Can also be None (default) to use ‘auto’ when enough extra digitization points are available, and 0.095 otherwise. Currently the head radius does not affect plotting.

New in version 0.20.

Returns

figinstance of matplotlib.figure.Figure: Figure containing the images.

Examples using plot_image:

Analysing continuous features with binning and regression in sensor space¶

Visualising statistical significance thresholds on EEG data¶

plot_joint(times='peaks', title='', picks=None, exclude='bads', show=True, ts_args=None, topomap_args=None)[source]¶

Plot evoked data as butterfly plot and add topomaps for time points.

Note

Axes to plot in can be passed by the user through ts_args or topomap_args. In that case both ts_args and topomap_args axes have to be used. Be aware that when the axes are provided, their position may be slightly modified.

Parameters

timesfloat | array of float | “auto” | “peaks”: The time point(s) to plot. If "auto", 5 evenly spaced topographies between the first and last time instant will be shown. If "peaks", finds time points automatically by checking for 3 local maxima in Global Field Power. Defaults to "peaks".
titlestr | None: The title. If None, suppress printing channel type title. If an empty string, a default title is created. Defaults to ‘’. If custom axes are passed make sure to set title=None, otherwise some of your axes may be removed during placement of the title axis.
picksstr | list | 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.
excludeNone | list of str | ‘bads’: Channels names to exclude from being shown. If 'bads', the bad channels are excluded. Defaults to None.
showbool: Show figure if True. Defaults to True.
ts_argsNone | dict: A dict of kwargs that are forwarded to mne.Evoked.plot() to style the butterfly plot. If they are not in this dict, the following defaults are passed: spatial_colors=True, zorder='std'. show and exclude are illegal. If None, no customizable arguments will be passed. Defaults to None.
topomap_argsNone | dict: A dict of kwargs that are forwarded to mne.Evoked.plot_topomap() to style the topomaps. If it is not in this dict, outlines='skirt' will be passed. show, times, colorbar are illegal. If None, no customizable arguments will be passed. Defaults to None.

Returns

figinstance of matplotlib.figure.Figure | list: The figure object containing the plot. If evoked has multiple channel types, a list of figures, one for each channel type, is returned.

Notes

New in version 0.12.0.

Examples using plot_joint:

Transform EEG data using current source density (CSD)¶

Single trial linear regression analysis with the LIMO dataset¶

Overview of MEG/EEG analysis with MNE-Python¶

Overview of artifact detection¶

Repairing artifacts with ICA¶

Source reconstruction using an LCMV beamformer¶

EEG source localization given electrode locations on an MRI¶

Visualising statistical significance thresholds on EEG data¶

Decoding (MVPA)¶

plot_projs_topomap(ch_type=None, cmap=None, sensors=True, colorbar=False, res=64, size=1, show=True, outlines='head', contours=6, image_interp='bilinear', axes=None, vlim=(None, None), sphere=None, extrapolate='auto', border='mean')[source]¶

Plot SSP vector.

Parameters

The channel type to plot. For ‘grad’, the gradiometers are collec- ted in pairs and the RMS for each pair is plotted. If None (default), it will return all channel types present. If a list of ch_types is provided, it will return multiple figures.

cmapmatplotlib colormap | (colormap, bool) | ‘interactive’ | None

Colormap to use. If tuple, the first value indicates the colormap to use and the second value is a boolean defining interactivity. In interactive mode (only works if colorbar=True) the colors are adjustable by clicking and dragging the colorbar with left and right mouse button. Left mouse button moves the scale up and down and right mouse button adjusts the range. Hitting space bar resets the range. Up and down arrows can be used to change the colormap. If None (default), ‘Reds’ is used for all positive data, otherwise defaults to ‘RdBu_r’. If ‘interactive’, translates to (None, True).

sensorsbool | str

Add markers for sensor locations to the plot. Accepts matplotlib plot format string (e.g., ‘r+’ for red plusses). If True, a circle will be used (via .add_artist). Defaults to True.

colorbarbool

Plot a colorbar.

resint

The resolution of the topomap image (n pixels along each side).

sizescalar

Side length of the topomaps in inches (only applies when plotting multiple topomaps at a time).

showbool

Show figure if True.

outlines‘head’ | ‘skirt’ | dict | None

The outlines to be drawn. If ‘head’, the default head scheme will be drawn. If ‘skirt’ the head scheme will be drawn, but sensors are allowed to be plotted outside of the head circle. If dict, each key refers to a tuple of x and y positions, the values in ‘mask_pos’ will serve as image mask. Alternatively, a matplotlib patch object can be passed for advanced masking options, either directly or as a function that returns patches (required for multi-axis plots). If None, nothing will be drawn. Defaults to ‘head’.

contoursint | array of float

image_interpstr

The image interpolation to be used. All matplotlib options are accepted.

axesinstance of Axes | list | None

The axes to plot to. If list, the list must be a list of Axes of the same length as the number of projectors. If instance of Axes, there must be only one projector. Defaults to None.

vlimtuple of length 2 | ‘joint’

Colormap limits to use. If tuple, specifies the lower and upper bounds of the colormap (in that order); providing None for either of these will set the corresponding boundary at the min/max of the data (separately for each projector). The keyword value 'joint' will compute the colormap limits jointly across all provided projectors of the same channel type, using the min/max of the projector data. If vlim is 'joint', info must not be None. Defaults to (None, None).

spherefloat | array_like | str | None

New in version 0.20.

extrapolatestr

Options:

'box'
Extrapolate to four points placed to form a square encompassing all data points, where each side of the square is three times the range of the data in the respective dimension.
'local' (default)
Extrapolate only to nearby points (approximately to points closer than median inter-electrode distance). This will also set the mask to be polygonal based on the convex hull of the sensors.
'head'
Extrapolate out to the edges of the clipping circle. This will be on the head circle when the sensors are contained within the head circle, but it can extend beyond the head when sensors are plotted outside the head circle.

Changed in version 0.21:

The default was changed to 'local'
'local' was changed to use a convex hull mask
'head' was changed to extrapolate out to the clipping circle.

New in version 0.20.

borderfloat | ‘mean’

Value to extrapolate to on the topomap borders. If 'mean' (default), then each extrapolated point has the average value of its neighbours.

New in version 0.20.

Returns

figinstance of Figure: Figure distributing one image per channel across sensor topography.

Examples using plot_projs_topomap:

How to plot topomaps the way EEGLAB does¶

plot_sensors(kind='topomap', ch_type=None, title=None, show_names=False, ch_groups=None, to_sphere=True, axes=None, block=False, show=True, sphere=None, verbose=None)[source]¶

Plot sensor positions.

Parameters

kindstr: Whether to plot the sensors as 3d, topomap or as an interactive sensor selection dialog. Available options ‘topomap’, ‘3d’, ‘select’. If ‘select’, a set of channels can be selected interactively by using lasso selector or clicking while holding control key. The selected channels are returned along with the figure instance. Defaults to ‘topomap’.
ch_typeNone | str: The channel type to plot. Available options ‘mag’, ‘grad’, ‘eeg’, ‘seeg’, ‘ecog’, ‘all’. If 'all', all the available mag, grad, eeg, seeg and ecog channels are plotted. If None (default), then channels are chosen in the order given above.
titlestr | None: Title for the figure. If None (default), equals to 'Sensor positions (%s)' % ch_type.
show_namesbool | array of str: Whether to display all channel names. If an array, only the channel names in the array are shown. Defaults to False.
ch_groups‘position’ | array of shape (n_ch_groups, n_picks) | None: Channel groups for coloring the sensors. If None (default), default coloring scheme is used. If ‘position’, the sensors are divided into 8 regions. See order kwarg of mne.viz.plot_raw(). If array, the channels are divided by picks given in the array.

New in version 0.13.0.
to_spherebool: Whether to project the 3d locations to a sphere. When False, the sensor array appears similar as to looking downwards straight above the subject’s head. Has no effect when kind=’3d’. Defaults to True.

New in version 0.14.0.
axesinstance of Axes | instance of Axes3D | None: Axes to draw the sensors to. If kind='3d', axes must be an instance of Axes3D. If None (default), a new axes will be created.

New in version 0.13.0.
blockbool: Whether to halt program execution until the figure is closed. Defaults to False.

New in version 0.13.0.
showbool: Show figure if True. Defaults to True.
spherefloat | array_like | str | None: The sphere parameters to use for the cartoon head. Can be array-like of shape (4,) to give the X/Y/Z origin and radius in meters, or a single float to give the radius (origin assumed 0, 0, 0). Can also be a spherical ConductorModel, which will use the origin and radius. Can be “auto” to use a digitization-based fit. Can also be None (default) to use ‘auto’ when enough extra digitization points are available, and 0.095 otherwise. Currently the head radius does not affect plotting.

New in version 0.20.
verbosebool, str, int, or None: If not None, override default verbose level (see mne.verbose() and Logging documentation for more). If used, it should be passed as a keyword-argument only. Defaults to self.verbose.

Returns

figinstance of Figure: Figure containing the sensor topography.
selectionlist: A list of selected channels. Only returned if kind=='select'.

See also

mne.viz.plot_layout

Notes

This function plots the sensor locations from the info structure using matplotlib. For drawing the sensors using mayavi see mne.viz.plot_alignment().

New in version 0.12.0.

Examples using plot_sensors:

plot_topo(layout=None, layout_scale=0.945, color=None, border='none', ylim=None, scalings=None, title=None, proj=False, vline=[0.0], fig_background=None, merge_grads=False, legend=True, axes=None, background_color='w', noise_cov=None, show=True)[source]¶

Plot 2D topography of evoked responses.

Clicking on the plot of an individual sensor opens a new figure showing the evoked response for the selected sensor.

Parameters

layoutinstance of Layout | None: Layout instance specifying sensor positions (does not need to be specified for Neuromag data). If possible, the correct layout is inferred from the data.
layout_scalefloat: Scaling factor for adjusting the relative size of the layout on the canvas.
colorlist of color | color | None: Everything matplotlib accepts to specify colors. If not list-like, the color specified will be repeated. If None, colors are automatically drawn.
borderstr: Matplotlib borders style to be used for each sensor plot.
ylimdict | None: Y limits for plots (after scaling has been applied). The value determines the upper and lower subplot limits. e.g. ylim = dict(eeg=[-20, 20]). Valid keys are eeg, mag, grad, misc. If None, the ylim parameter for each channel is determined by the maximum absolute peak.
scalingsdict | None: The scalings of the channel types to be applied for plotting. If None,` defaults to dict(eeg=1e6, grad=1e13, mag=1e15).
titlestr: Title of the figure.
projbool | ‘interactive’: If true SSP projections are applied before display. If ‘interactive’, a check box for reversible selection of SSP projection vectors will be shown.
vlinelist of float | None: The values at which to show a vertical line.
fig_backgroundNone | ndarray: A background image for the figure. This must work with a call to plt.imshow. Defaults to None.
merge_gradsbool: Whether to use RMS value of gradiometer pairs. Only works for Neuromag data. Defaults to False.
legendbool | int | str | tuple: If True, create a legend based on evoked.comment. If False, disable the legend. Otherwise, the legend is created and the parameter value is passed as the location parameter to the matplotlib legend call. It can be an integer (e.g. 0 corresponds to upper right corner of the plot), a string (e.g. ‘upper right’), or a tuple (x, y coordinates of the lower left corner of the legend in the axes coordinate system). See matplotlib documentation for more details.
axesinstance of matplotlib Axes | None: Axes to plot into. If None, axes will be created.
background_colorcolor: Background color. Typically ‘k’ (black) or ‘w’ (white; default).

New in version 0.15.0.
noise_covinstance of Covariance | str | None: Noise covariance used to whiten the data while plotting. Whitened data channel names are shown in italic. Can be a string to load a covariance from disk.

New in version 0.16.0.
showbool: Show figure if True.

Returns

figinstance of matplotlib.figure.Figure: Images of evoked responses at sensor locations.

Notes

New in version 0.10.0.

Examples using plot_topo:

Transform EEG data using current source density (CSD)¶

Plotting whitened data¶

plot_topomap(times='auto', ch_type=None, vmin=None, vmax=None, cmap=None, sensors=True, colorbar=True, scalings=None, units=None, res=64, size=1, cbar_fmt='%3.1f', time_unit='s', time_format=None, proj=False, show=True, show_names=False, title=None, mask=None, mask_params=None, outlines='head', contours=6, image_interp='bilinear', average=None, axes=None, extrapolate='auto', sphere=None, border='mean', nrows=1, ncols='auto')[source]¶

Plot topographic maps of specific time points of evoked data.

Parameters

timesfloat | array of float | “auto” | “peaks” | “interactive”

The time point(s) to plot. If “auto”, the number of axes determines the amount of time point(s). If axes is also None, at most 10 topographies will be shown with a regular time spacing between the first and last time instant. If “peaks”, finds time points automatically by checking for local maxima in global field power. If “interactive”, the time can be set interactively at run-time by using a slider.

ch_typestr

The channel type being plotted. Determines the 'auto' extrapolation mode.

New in version 0.21.

vmin, vmaxfloat | callable() | None

Lower and upper bounds of the colormap, in the same units as the data. If vmin and vmax are both None, they are set at ± the maximum absolute value of the data (yielding a colormap with midpoint at 0). If only one of vmin, vmax is None, will use min(data) or max(data), respectively. If callable, should accept a NumPy array of data and return a float.

cmapmatplotlib colormap | (colormap, bool) | ‘interactive’ | None

Colormap to use. If tuple, the first value indicates the colormap to use and the second value is a boolean defining interactivity. In interactive mode the colors are adjustable by clicking and dragging the colorbar with left and right mouse button. Left mouse button moves the scale up and down and right mouse button adjusts the range (zoom). The mouse scroll can also be used to adjust the range. Hitting space bar resets the range. Up and down arrows can be used to change the colormap. If None (default), ‘Reds’ is used for all positive data, otherwise defaults to ‘RdBu_r’. If ‘interactive’, translates to (None, True).

Warning

Interactive mode works smoothly only for a small amount of topomaps. Interactive mode is disabled by default for more than 2 topomaps.

sensorsbool | str

Add markers for sensor locations to the plot. Accepts matplotlib plot format string (e.g., ‘r+’ for red plusses). If True (default), circles will be used.

colorbarbool

Plot a colorbar in the rightmost column of the figure.

scalingsdict | float | None

The scalings of the channel types to be applied for plotting. If None, defaults to dict(eeg=1e6, grad=1e13, mag=1e15).

unitsdict | str | None

The unit of the channel type used for colorbar label. If scale is None the unit is automatically determined.

resint

The resolution of the topomap image (n pixels along each side).

sizefloat

Side length per topomap in inches.

cbar_fmtstr

String format for colorbar values.

time_unitstr

The units for the time axis, can be “ms” or “s” (default).

New in version 0.16.

time_formatstr | None

String format for topomap values. Defaults (None) to “%01d ms” if time_unit='ms', “%0.3f s” if time_unit='s', and “%g” otherwise. Can be an empty string to omit the time label.

projbool | ‘interactive’ | ‘reconstruct’

If true SSP projections are applied before display. If ‘interactive’, a check box for reversible selection of SSP projection vectors will be shown. If ‘reconstruct’, projection vectors will be applied and then M/EEG data will be reconstructed via field mapping to reduce the signal bias caused by projection.

Changed in version 0.21: Support for ‘reconstruct’ was added.

showbool

Show figure if True.

show_namesbool | callable()

If True, show channel names on top of the map. If a callable is passed, channel names will be formatted using the callable; e.g., to delete the prefix ‘MEG ‘ from all channel names, pass the function lambda x: x.replace('MEG ', ''). If mask is not None, only significant sensors will be shown.

titlestr | None

Title. If None (default), no title is displayed.

maskndarray of bool, shape (n_channels, n_times) | None

The channels to be marked as significant at a given time point. Indices set to True will be considered. Defaults to None.

mask_paramsdict | None

Additional plotting parameters for plotting significant sensors. Default (None) equals:

dict(marker='o', markerfacecolor='w', markeredgecolor='k',
        linewidth=0, markersize=4)

outlines‘head’ | ‘skirt’ | dict | None

contoursint | array of float

The number of contour lines to draw. If 0, no contours will be drawn. When an integer, matplotlib ticker locator is used to find suitable values for the contour thresholds (may sometimes be inaccurate, use array for accuracy). If an array, the values represent the levels for the contours. The values are in µV for EEG, fT for magnetometers and fT/m for gradiometers. If colorbar=True, the ticks in colorbar correspond to the contour levels. Defaults to 6.

image_interpstr

The image interpolation to be used. All matplotlib options are accepted.

averagefloat | None

The time window around a given time to be used for averaging (seconds). For example, 0.01 would translate into window that starts 5 ms before and ends 5 ms after a given time point. Defaults to None, which means no averaging.

axesinstance of Axes | list | None

The axes to plot to. If list, the list must be a list of Axes of the same length as times (unless times is None). If instance of Axes, times must be a float or a list of one float. Defaults to None.

extrapolatestr

Options:

'box'
Extrapolate to four points placed to form a square encompassing all data points, where each side of the square is three times the range of the data in the respective dimension.
'local' (default)
Extrapolate only to nearby points (approximately to points closer than median inter-electrode distance). This will also set the mask to be polygonal based on the convex hull of the sensors.
'head'
Extrapolate out to the edges of the clipping circle. This will be on the head circle when the sensors are contained within the head circle, but it can extend beyond the head when sensors are plotted outside the head circle.

Changed in version 0.21:

The default was changed to 'local'
'local' was changed to use a convex hull mask
'head' was changed to extrapolate out to the clipping circle.

New in version 0.18.

spherefloat | array_like | str | None

New in version 0.20.

borderfloat | ‘mean’

Value to extrapolate to on the topomap borders. If 'mean' (default), then each extrapolated point has the average value of its neighbours.

New in version 0.20.

nrowsint | ‘auto’

The number of rows of topographies to plot. Defaults to 1. If ‘auto’, obtains the number of rows depending on the amount of times to plot and the number of cols. Not valid when times == ‘interactive’.

New in version 0.20.

ncolsint | ‘auto’

The number of columns of topographies to plot. If ‘auto’ (default), obtains the number of columns depending on the amount of times to plot and the number of rows. Not valid when times == ‘interactive’.

New in version 0.20.

Returns

figinstance of matplotlib.figure.Figure: The figure.

Notes

When existing axes are provided and colorbar=True, note that the colorbar scale will only accurately reflect topomaps that are generated in the same call as the colorbar. Note also that the colorbar will not be resized automatically when axes are provided; use matplotlib’s axes.set_position() method or gridspec interface to adjust the colorbar size yourself.

Examples using plot_topomap:

Maxwell filter data with movement compensation¶

Remap MEG channel types¶

Plotting topographic maps of evoked data¶

Make an MNE-Report with a Slider¶

Permutation T-test on sensor data¶

XDAWN Decoding From EEG data¶

Compute effect-matched-spatial filtering (EMS)¶

Linear classifier on sensor data with plot patterns and filters¶

Compute source power estimate by projecting the covariance with MNE¶

Overview of MEG/EEG analysis with MNE-Python¶

Overview of artifact detection¶

Preprocessing functional near-infrared spectroscopy (fNIRS) data¶

EEG processing and Event Related Potentials (ERPs)¶

Source localization with equivalent current dipole (ECD) fit¶

Source localization with MNE/dSPM/sLORETA/eLORETA¶

Spatiotemporal permutation F-test on full sensor data¶

Brainstorm auditory tutorial dataset¶

plot_white(noise_cov, show=True, rank=None, time_unit='s', sphere=None, axes=None, verbose=None)[source]¶

Plot whitened evoked response.

Plots the whitened evoked response and the whitened GFP as described in [1]. This function is especially useful for investigating noise covariance properties to determine if data are properly whitened (e.g., achieving expected values in line with model assumptions, see Notes below).

Parameters

noise_covlist | instance of Covariance | str: The noise covariance. Can be a string to load a covariance from disk.
showbool: Show figure if True.
rankNone | dict | ‘info’ | ‘full’: This controls the rank computation that can be read from the measurement info or estimated from the data. See Notes of mne.compute_rank() for details.The default is None.
time_unitstr: The units for the time axis, can be “ms” or “s” (default).

New in version 0.16.
spherefloat | array_like | str | None: The sphere parameters to use for the cartoon head. Can be array-like of shape (4,) to give the X/Y/Z origin and radius in meters, or a single float to give the radius (origin assumed 0, 0, 0). Can also be a spherical ConductorModel, which will use the origin and radius. Can be “auto” to use a digitization-based fit. Can also be None (default) to use ‘auto’ when enough extra digitization points are available, and 0.095 otherwise. Currently the head radius does not affect plotting.

New in version 0.20.
axeslist | None: List of axes to plot into.

New in version 0.21.0.
verbosebool, str, int, or None: If not None, override default verbose level (see mne.verbose() and Logging documentation for more). If used, it should be passed as a keyword-argument only.

Returns

figinstance of matplotlib.figure.Figure: The figure object containing the plot.

See also

mne.Evoked.plot

Notes

If baseline signals match the assumption of Gaussian white noise, values should be centered at 0, and be within 2 standard deviations (±1.96) for 95% of the time points. For the global field power (GFP), we expect it to fluctuate around a value of 1.

If one single covariance object is passed, the GFP panel (bottom) will depict different sensor types. If multiple covariance objects are passed as a list, the left column will display the whitened evoked responses for each channel based on the whitener from the noise covariance that has the highest log-likelihood. The left column will depict the whitened GFPs based on each estimator separately for each sensor type. Instead of numbers of channels the GFP display shows the estimated rank. Note. The rank estimation will be printed by the logger (if verbose=True) for each noise covariance estimator that is passed.

References

1: Engemann D. and Gramfort A. (2015) Automated model selection in covariance estimation and spatial whitening of MEG and EEG signals, vol. 108, 328-342, NeuroImage.

Examples using plot_white:

Generate simulated raw data¶

Whitening evoked data with a noise covariance¶

Plotting whitened data¶

Computing a covariance matrix¶

Source localization with MNE/dSPM/sLORETA/eLORETA¶

property proj¶: Whether or not projections are active.

rename_channels(mapping)[source]¶

Rename channels.

Parameters

mappingdict | callable(): A dictionary mapping the old channel to a new channel name e.g. {‘EEG061’ : ‘EEG161’}. Can also be a callable function that takes and returns a string.

Changed in version 0.10.0: Support for a callable function.

Returns

instinstance of Raw | Epochs | Evoked: The instance (modified in place).

Changed in version 0.20: Return the instance.

Notes

New in version 0.9.0.

reorder_channels(ch_names)[source]¶

Reorder channels.

Parameters

ch_nameslist: The desired channel order.

Returns

instinstance of Raw, Epochs, or Evoked: The modified instance.

See also

drop_channels
pick_types
pick_channels

Notes

Channel names must be unique. Channels that are not in ch_names are dropped.

New in version 0.16.0.

Examples using reorder_channels:

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

Resample data.

Note

Data must be loaded.

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: Frequency-domain window to use in resampling. See scipy.signal.resample().
n_jobsint | str: Number of jobs to run in parallel. Can be ‘cuda’ if cupy is installed properly.
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'. The default is 'edge', which pads with the edge values of each vector.

New in version 0.15.
verbosebool, str, int, or None: If not None, override default verbose level (see mne.verbose() and Logging documentation for more). If used, it should be passed as a keyword-argument only. Defaults to self.verbose.

Returns

instinstance of Epochs or Evoked: The resampled object.

See also

mne.io.Raw.resample

Notes

For some data, it may be more accurate to use npad=0 to reduce artifacts. This is dataset dependent – check your data!

Examples using resample:

Permutation t-test on source data with spatio-temporal clustering¶

Repeated measures ANOVA on source data with spatio-temporal clustering¶

save(fname)[source]¶

Save dataset to file.

Parameters

fnamestr: The name of the file, which should end with -ave.fif or -ave.fif.gz.

Notes

To write multiple conditions into a single file, use mne.write_evokeds().

Examples using save:

Reading and writing an evoked file¶

savgol_filter(h_freq, verbose=None)[source]¶

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, or None: If not None, override default verbose level (see mne.verbose() and Logging documentation for more). If used, it should be passed as a keyword-argument only. Defaults to self.verbose.

Returns

instinstance of Epochs or Evoked: 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

New in version 0.9.0.

References

1: Alan V. Oppenheim, Ronald W. Schafer, and John R. Buck. Discrete-Time Signal Processing. Prentice Hall, Upper Saddle River, NJ, 2 edition edition, January 1999. ISBN 978-0-13-754920-7.
2: Ronald E. Crochiere and Lawrence R. Rabiner. Multirate Digital Signal Processing. Pearson, Englewood Cliffs, NJ, 1 edition edition, December 1983. ISBN 978-0-13-605162-6.
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()  

set_channel_types(mapping, verbose=None)[source]¶

Define the sensor type of channels.

Parameters

mappingdict: A dictionary mapping a channel to a sensor type (str), e.g., {'EEG061': 'eog'}.
verbosebool, str, int, or None: If not None, override default verbose level (see mne.verbose() and Logging documentation for more). If used, it should be passed as a keyword-argument only. Defaults to self.verbose.

Returns

instinstance of Raw | Epochs | Evoked: The instance (modified in place).

Changed in version 0.20: Return the instance.

Notes

The following sensor types are accepted:

ecg, eeg, emg, eog, exci, ias, misc, resp, seeg, stim, syst, ecog, hbo, hbr, fnirs_cw_amplitude, fnirs_od

New in version 0.9.0.

set_eeg_reference(ref_channels='average', projection=False, ch_type='auto', forward=None, verbose=None)[source]¶

Specify which reference to use for EEG data.

Use this function to explicitly specify the desired reference for EEG. This can be either an existing electrode or a new virtual channel. This function will re-reference the data according to the desired reference.

Parameters

ref_channelslist of str | str

Can be:

The name(s) of the channel(s) used to construct the reference.
'average' to apply an average reference (default)
'REST' to use the Reference Electrode Standardization Technique infinity reference 4.
An empty list, in which case MNE will not attempt any re-referencing of the data

projectionbool

If ref_channels='average' this argument specifies if the average reference should be computed as a projection (True) or not (False; default). If projection=True, the average reference is added as a projection and is not applied to the data (it can be applied afterwards with the apply_proj method). If projection=False, the average reference is directly applied to the data. If ref_channels is not 'average', projection must be set to False (the default in this case).

ch_type‘auto’ | ‘eeg’ | ‘ecog’ | ‘seeg’

The name of the channel type to apply the reference to. If ‘auto’, the first channel type of eeg, ecog or seeg that is found (in that order) will be selected.

New in version 0.19.

forwardinstance of Forward | None

Forward solution to use. Only used with ref_channels='REST'.

New in version 0.21.

verbosebool, str, int, or None

If not None, override default verbose level (see mne.verbose() and Logging documentation for more). If used, it should be passed as a keyword-argument only. Defaults to self.verbose.

Returns

instinstance of Raw | Epochs | Evoked: Data with EEG channels re-referenced. If ref_channels='average' and projection=True a projection will be added instead of directly re-referencing the data.

See also

mne.set_bipolar_reference: Convenience function for creating bipolar references.

Notes

Some common referencing schemes and the corresponding value for the ref_channels parameter:

Average reference:
A new virtual reference electrode is created by averaging the current EEG signal by setting ref_channels='average'. Bad EEG channels are automatically excluded if they are properly set in info['bads'].
A single electrode:
Set ref_channels to a list containing the name of the channel that will act as the new reference, for example ref_channels=['Cz'].
The mean of multiple electrodes:
A new virtual reference electrode is created by computing the average of the current EEG signal recorded from two or more selected channels. Set ref_channels to a list of channel names, indicating which channels to use. For example, to apply an average mastoid reference, when using the 10-20 naming scheme, set ref_channels=['M1', 'M2'].
REST
The given EEG electrodes are referenced to a point at infinity using the lead fields in forward, which helps standardize the signals.

If a reference is requested that is not the average reference, this function removes any pre-existing average reference projections.
During source localization, the EEG signal should have an average reference.
In order to apply a reference, the data must be preloaded. This is not necessary if ref_channels='average' and projection=True.
For an average or REST reference, bad EEG channels are automatically excluded if they are properly set in info['bads'].

New in version 0.9.0.

References

4: D. Yao. A method to standardize a reference of scalp EEG recordings to a point at infinity. Physiological Measurement, 22(4):693–711, November 2001. doi:10.1088/0967-3334/22/4/305.

set_meas_date(meas_date)[source]¶

Set the measurement start date.

Parameters

meas_datedatetime | float | tuple | None: The new measurement date. If datetime object, it must be timezone-aware and in UTC. A tuple of (seconds, microseconds) or float (alias for (meas_date, 0)) can also be passed and a datetime object will be automatically created. If None, will remove the time reference.

Returns

instinstance of Raw | Epochs | Evoked: The modified raw instance. Operates in place.

See also

mne.io.Raw.anonymize

Notes

If you want to remove all time references in the file, call mne.io.anonymize_info(inst.info) after calling inst.set_meas_date(None).

New in version 0.20.

set_montage(montage, match_case=True, on_missing='raise', verbose=None)[source]¶

Set EEG sensor configuration and head digitization.

Parameters

montageNone | str | DigMontage: A montage containing channel positions. If str or DigMontage is specified, the channel info will be updated with the channel positions. Default is None. See also the documentation of mne.channels.DigMontage for more information.
match_casebool: If True (default), channel name matching will be case sensitive.

New in version 0.20.
on_missingstr: Can be 'raise' (default) to raise an error, 'warn' to emit a warning, or 'ignore' to ignore when channels have missing coordinates.

New in version 0.20.1.
verbosebool, str, int, or None: If not None, override default verbose level (see mne.verbose() and Logging documentation for more). If used, it should be passed as a keyword-argument only. Defaults to self.verbose.

Returns

instinstance of Raw | Epochs | Evoked: The instance.

Notes

Operates in place.

Examples using set_montage:

How to plot topomaps the way EEGLAB does¶

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

epochsinstance of Epochs: The modified Epochs 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.

Examples using shift_time:

Shifting time-scale in evoked data¶

Compute sparse inverse solution with mixed norm: MxNE and irMxNE¶

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.

Examples using time_as_index: