mne.io.Raw #

add_events(events, stim_channel=None, replace=False)[source]#

Add events to stim channel.

Parameters:

eventsndarray, shape (n_events, 3): Events to add. The first column specifies the sample number of each event, the second column is ignored, and the third column provides the event value. If events already exist in the Raw instance at the given sample numbers, the event values will be added together.
stim_channelstr | None: Name of the stim channel to add to. If None, the config variable ‘MNE_STIM_CHANNEL’ is used. If this is not found, it will default to 'STI 014'.
replacebool: If True the old events on the stim channel are removed before adding the new ones.

Notes

Data must be preloaded in order to add events.

Examples using add_events:

Show EOG artifact timing

add_proj(projs, remove_existing=False, verbose=None)[source]#

Add SSP projection vectors.

Parameters:

projslist: List with projection vectors.
remove_existingbool: Remove the projection vectors currently in the file.
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: The data container.

Examples using add_proj:

Divide continuous data into equally-spaced epochs

Computing a covariance matrix

Generate simulated evoked data

Temporal whitening with AR model

add_reference_channels(ref_channels)[source]#

Add reference channels to data that consists of all zeros.

Adds reference channels to data that were not included during recording. This is useful when you need to re-reference your data to different channels. These added channels will consist of all zeros.

Parameters:

ref_channelsstr | list of str: Name of the electrode(s) which served as the reference in the recording. If a name is provided, a corresponding channel is added and its data is set to 0. This is useful for later re-referencing.

Returns:

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

property annotations#: Annotations for marking segments of data.

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

append(raws, preload=None)[source]#

Concatenate raw instances as if they were continuous.

Note

Boundaries of the raw files are annotated bad. If you wish to use the data as continuous recording, you can remove the boundary annotations after concatenation (see mne.Annotations.delete()).

Parameters:

rawslist, or Raw instance: List of Raw instances to concatenate to the current instance (in order), or a single raw instance to concatenate.
preloadbool, str, or None (default None): Preload data into memory for data manipulation and faster indexing. If True, the data will be preloaded into memory (fast, requires large amount of memory). If preload is a string, preload is the file name of a memory-mapped file which is used to store the data on the hard drive (slower, requires less memory). If preload is None, preload=True or False is inferred using the preload status of the instances passed in.

Examples using append:

apply_function(fun, picks=None, dtype=None, n_jobs=None, channel_wise=True, verbose=None, **kwargs)[source]#

Apply a function to a subset of channels.

The function fun is applied to the channels defined in picks. The raw 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 channels in picks). The object has to have the data loaded e.g. with preload=True or self.load_data().

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,) if channel_wise=True and (len(picks), n_times) otherwise. 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 data channels (excluding reference MEG 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 channel_wise=False as the workload is split across channels.
channel_wisebool: Whether to apply the function to each channel individually. If False, the function will be applied to all channels at once. Default True.

New in v0.18.
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 Raw: The raw object with transformed data.

Examples using apply_function:

apply_gradient_compensation(grade, verbose=None)[source]#

Apply CTF gradient compensation.

Warning

The compensation matrices are stored with single precision, so repeatedly switching between different of compensation (e.g., 0->1->3->2) can increase numerical noise, especially if data are saved to disk in between changing grades. It is thus best to only use a single gradient compensation level in final analyses.

Parameters:

gradeint: CTF gradient compensation level.
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:

rawinstance of Raw: The modified Raw instance. Works in-place.

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

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.

Examples using apply_hilbert:

apply_proj(verbose=None)[source]#

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

Parameters:

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

Divide continuous data into equally-spaced epochs

property ch_names#: Channel names.

close()[source]#

Clean up the object.

Does nothing for objects that close their file descriptors. Things like Raw will override this method.

property compensation_grade#: The current gradient compensation grade.

compute_psd(method='welch', fmin=0, fmax=inf, tmin=None, tmax=None, picks=None, exclude=(), proj=False, remove_dc=True, reject_by_annotation=True, *, n_jobs=1, verbose=None, **method_kw)[source]#

Perform spectral analysis on sensor data.

Parameters:

method'welch' | 'multitaper': Spectral estimation method. 'welch' uses Welch’s method [1], 'multitaper' uses DPSS tapers [2]. Note that "multitaper" cannot be used if reject_by_annotation=True and there are "bad_*" annotations in the Raw data; in such cases use "welch". Default is 'welch'.
fmin, fmaxfloat: The lower- and upper-bound on frequencies of interest. Default is fmin=0, fmax=np.inf (spans all frequencies present in the data).
tmin, tmaxfloat | None: First and last times to include, in seconds. None uses the first or last time present in the data. Default is tmin=None, tmax=None (all times).
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 good data channels (excluding reference MEG channels). Note that channels in info['bads'] will be included if their names or indices are explicitly provided.
excludelist of str | ‘bads’: Channel names to exclude. If 'bads', channels in info['bads'] are excluded; pass an empty list to include all channels (including “bad” channels, if any).
projbool: Whether to apply SSP projection vectors before spectral estimation. Default is False.
remove_dcbool: If True, the mean is subtracted from each segment before computing its spectrum.
reject_by_annotationbool: Whether to omit bad spans of data before spectral estimation. If True, spans with annotations whose description begins with bad will be omitted.
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.
**method_kw: Additional keyword arguments passed to the spectral estimation function (e.g., n_fft, n_overlap, n_per_seg, average, window for Welch method, or bandwidth, adaptive, low_bias, normalization for multitaper method). See psd_array_welch() and psd_array_multitaper() for details. Note that for Welch method if n_fft is unspecified its default will be the smaller of 2048 or the number of available time samples (taking into account tmin and tmax), not 256 as in psd_array_welch().

Returns:

spectruminstance of Spectrum: The spectral representation of the data.

Notes

New in v1.2.

References

Examples using compute_psd:

Overview of MEG/EEG analysis with MNE-Python

Extracting and visualizing subject head movement

The Spectrum and EpochsSpectrum classes: frequency-domain data

Brainstorm Elekta phantom dataset tutorial

Transform EEG data using current source density (CSD)

Plot custom topographies for MEG sensors

compute_tfr(method, freqs, *, tmin=None, tmax=None, picks=None, proj=False, output='power', reject_by_annotation=True, decim=1, n_jobs=None, verbose=None, **method_kw)[source]#

Compute a time-frequency representation of sensor data.

Parameters:

method'morlet' | 'multitaper' | None

Spectrotemporal power estimation method. 'morlet' uses Morlet wavelets, 'multitaper' uses DPSS tapers [2]. None (the default) only works when using __setstate__ and will raise an error otherwise.

freqsarray_like | None

The frequencies at which to compute the power estimates. Must be an array of shape (n_freqs,). None (the default) only works when using __setstate__ and will raise an error otherwise.

tmin, tmaxfloat | None

First and last times to include, in seconds. None uses the first or last time present in the data. Default is tmin=None, tmax=None (all times).

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 good data channels (excluding reference MEG channels). Note that channels in info['bads'] will be included if their names or indices are explicitly provided.

projbool

Whether to apply SSP projection vectors before spectral estimation. Default is False.

outputstr

What kind of estimate to return. Allowed values are "complex", "phase", and "power". Default is "power".

reject_by_annotationbool

Whether to omit bad spans of data before spectrotemporal power estimation. If True, spans with annotations whose description begins with bad will be represented with np.nan in the time-frequency representation.

decimint | slice

Decimation factor, applied after time-frequency decomposition.

if int, returns tfr[..., ::decim] (keep only every Nth sample along the time axis).
if slice, returns tfr[..., decim] (keep only the specified slice along the time axis).

Note

Decimation is done after convolutions and may create aliasing artifacts.

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.

**method_kw

Additional keyword arguments passed to the spectrotemporal estimation function (e.g., n_cycles, use_fft, zero_mean for Morlet method or n_cycles, use_fft, zero_mean, time_bandwidth for multitaper method). See tfr_array_morlet() and tfr_array_multitaper() for additional details.

Returns:

tfrinstance of RawTFR: The time-frequency-resolved power estimates of the data.

Notes

New in v1.7.

References

copy()[source]#

Return copy of Raw instance.

Returns:

instinstance of Raw: A copy of the instance.

Examples using copy:

Handling bad channels

Signal-space separation (SSS) and Maxwell filtering

Regression-based baseline correction

Make figures more publication ready

Plot sensor denoising using oversampled temporal projection

crop(tmin=0.0, tmax=None, include_tmax=True, *, verbose=None)[source]#

Crop raw data file.

Limit the data from the raw file to go between specific times. Note that the new tmin is assumed to be t=0 for all subsequently called functions (e.g., time_as_index(), or Epochs). New first_samp and last_samp are set accordingly.

Thus function operates in-place on the instance. Use mne.io.Raw.copy() if operation on a copy is desired.

Parameters:

tminfloat: Start time of the raw data to use in seconds (must be >= 0).
tmaxfloat | None: End time of the raw data to use in seconds (cannot exceed data duration). If None (default), the current end of the data is used.
include_tmaxbool: If True (default), include tmax. If False, exclude tmax (similar to how Python indexing typically works).

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

rawinstance of Raw: The cropped raw object, modified in-place.

Examples using crop:

Working with events

Handling bad channels

Extracting and visualizing subject head movement

Signal-space separation (SSS) and Maxwell filtering

Divide continuous data into equally-spaced epochs

Frequency and time-frequency sensor analysis

Automated epochs metadata generation with variable time windows

Plot sensor denoising using oversampled temporal projection

crop_by_annotations(annotations=None, *, verbose=None)[source]#

Get crops of raw data file for selected annotations.

Parameters:

annotationsinstance of Annotations | None: The annotations to use for cropping the raw file. If None, the annotations from the instance are 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:

rawslist: The cropped raw objects.

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:

describe(data_frame=False)[source]#

Describe channels (name, type, descriptive statistics).

Parameters:

data_framebool: If True, return results in a pandas.DataFrame. If False, only print results. Columns ‘ch’, ‘type’, and ‘unit’ indicate channel index, channel type, and unit of the remaining five columns. These columns are ‘min’ (minimum), ‘Q1’ (first quartile or 25% percentile), ‘median’, ‘Q3’ (third quartile or 75% percentile), and ‘max’ (maximum).

Returns:

resultNone | pandas.DataFrame: If data_frame=False, returns None. If data_frame=True, returns results in a pandas.DataFrame (requires pandas).

drop_channels(ch_names, on_missing='raise')[source]#

Drop channel(s).

Parameters:

ch_namesiterable or str: Iterable (e.g. list) of channel name(s) or channel name to remove.
on_missing‘raise’ | ‘warn’ | ‘ignore’: Can be 'raise' (default) to raise an error, 'warn' to emit a warning, or 'ignore' to ignore when entries in ch_names are not present in the raw instance.

New in v0.23.0.

Returns:

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

See also

reorder_channels
pick_channels
pick_types

Notes

New in v0.9.0.

Examples using drop_channels:

property duration#: Duration of the data in seconds.

New in v1.9.

export(fname, fmt='auto', physical_range='auto', add_ch_type=False, *, overwrite=False, verbose=None)[source]#

Export Raw to external formats.

Supported formats:

BrainVision (.vhdr, .vmrk, .eeg, uses pybv)
EEGLAB (.set, uses eeglabio)
EDF (.edf, uses edfio)

Warning

Since we are exporting to external formats, there’s no guarantee that all the info will be preserved in the external format. See Notes for details.

Parameters:

fnamestr: Name of the output file.
fmt‘auto’ | ‘brainvision’ | ‘edf’ | ‘eeglab’: Format of the export. Defaults to 'auto', which will infer the format from the filename extension. See supported formats above for more information.
physical_rangestr | tuple: The physical range of the data. If ‘auto’ (default), the physical range is inferred from the data, taking the minimum and maximum values per channel type. If ‘channelwise’, the range will be defined per channel. If a tuple of minimum and maximum, this manual physical range will be used. Only used for exporting EDF files.
add_ch_typebool: Whether to incorporate the channel type into the signal label (e.g. whether to store channel “Fz” as “EEG Fz”). Only used for EDF format. Default is False.
overwritebool: If True (default False), overwrite the destination file if it exists.

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

Notes

New in v0.24.

Export to external format may not preserve all the information from the instance. To save in native MNE format (.fif) without information loss, use mne.io.Raw.save() instead. Export does not apply projector(s). Unapplied projector(s) will be lost. Consider applying projector(s) before exporting with mne.io.Raw.apply_proj().

For EEGLAB exports, channel locations are expanded to full EEGLAB format. For more details see eeglabio.utils.cart_to_eeglab().

Although this function supports storing channel types in the signal label (e.g. EEG Fz or MISC E), other software may not support this (optional) feature of the EDF standard.

If add_ch_type is True, then channel types are written based on what they are currently set in MNE-Python. One should double check that all their channels are set correctly. You can call mne.io.Raw.set_channel_types() to set channel types.

In addition, EDF does not support storing a montage. You will need to store the montage separately and call mne.io.Raw.set_montage().

The physical range of the signals is determined by signal type by default (physical_range="auto"). However, if individual channel ranges vary significantly due to the presence of e.g. drifts/offsets/biases, setting physical_range="channelwise" might be more appropriate. This will ensure a maximum resolution for each individual channel, but some tools might not be able to handle this appropriately (even though channel-wise ranges are covered by the EDF standard).

property filenames: tuple[Path | None, ...]#

The filenames used.

Type:: tuple of pathlib.Path | None

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='reflect_limited', verbose=None)[source]#

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.

Examples using filter:

Background information on filtering

Repairing artifacts with ICA

Auto-generating Epochs metadata

Spatiotemporal permutation F-test on full sensor data

Reduce EOG artifacts through regression

Compare the different ICA algorithms in MNE

Plot sensor denoising using oversampled temporal projection

XDAWN Denoising

How to convert 3D electrode positions to a 2D image

Whitening evoked data with a noise covariance

Plot custom topographies for MEG sensors

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

Decoding source space data

Decoding sensor space data with generalization across time and conditions

Analysis of evoked response using ICA and PCA reduction techniques

XDAWN Decoding From EEG data

Compute effect-matched-spatial filtering (EMS)

property first_samp#

The first data sample.

See first_samp.

property first_time#: The first time point (including first_samp but not meas_date).

fix_mag_coil_types()[source]#

Fix Elekta magnetometer coil types.

Returns:

rawinstance of Raw: The raw object. Operates in place.

Notes

This function changes magnetometer coil types 3022 (T1: SQ20483N) and 3023 (T2: SQ20483-A) to 3024 (T3: SQ20950N) in the channel definition records in the info structure.

Neuromag Vectorview systems can contain magnetometers with two different coil sizes (3022 and 3023 vs. 3024). The systems incorporating coils of type 3024 were introduced last and are used at the majority of MEG sites. At some sites with 3024 magnetometers, the data files have still defined the magnetometers to be of type 3022 to ensure compatibility with older versions of Neuromag software. In the MNE software as well as in the present version of Neuromag software coil type 3024 is fully supported. Therefore, it is now safe to upgrade the data files to use the true coil type.

Note

The effect of the difference between the coil sizes on the current estimates computed by the MNE software is very small. Therefore the use of mne_fix_mag_coil_types is not mandatory.

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

Get a list of channel type for each channel.

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 channels. Note that channels in info['bads'] will be included if their names or indices are explicitly provided.
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.

Examples using get_channel_types:

The Info data structure

get_data(picks=None, start=0, stop=None, reject_by_annotation=None, return_times=False, units=None, *, tmin=None, tmax=None, verbose=None)[source]#

Get data in the given range.

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 channels. Note that channels in info['bads'] will be included if their names or indices are explicitly provided.
startint: The first sample to include. Defaults to 0.
stopint | None: End sample (first not to include). If None (default), the end of the data is used.
reject_by_annotationNone | ‘omit’ | ‘NaN’: Whether to reject by annotation. If None (default), no rejection is done. If ‘omit’, segments annotated with description starting with ‘bad’ are omitted. If ‘NaN’, the bad samples are filled with NaNs.
return_timesbool: Whether to return times as well. Defaults to False.
unitsstr | dict | None: Specify the unit(s) that the data should be returned in. If None (default), the data is returned in the channel-type-specific default units, which are SI units (see Internal representation (units) and data channels). If a string, must be a sub-multiple of SI units that will be used to scale the data from all channels of the type associated with that unit. This only works if the data contains one channel type that has a unit (unitless channel types are left unchanged). For example if there are only EEG and STIM channels, units='uV' will scale EEG channels to micro-Volts while STIM channels will be unchanged. Finally, if a dictionary is provided, keys must be channel types, and values must be units to scale the data of that channel type to. For example dict(grad='fT/cm', mag='fT') will scale the corresponding types accordingly, but all other channel types will remain in their channel-type-specific default unit.
tminint | float | None: Start time of data to get in seconds. The tmin parameter is ignored if the start parameter is bigger than 0.

New in v0.24.0.
tmaxint | float | None: End time of data to get in seconds. The tmax parameter is ignored if the stop parameter is defined.

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

Returns:

datandarray, shape (n_channels, n_times): Copy of the data in the given range.
timesndarray, shape (n_times,): Times associated with the data samples. Only returned if return_times=True.

Notes

New in v0.14.0.

Examples using get_data:

Make figures more publication ready

get_montage()[source]#

Get a DigMontage from instance.

Returns:

montageNone | DigMontage: A copy of the channel positions, if available, otherwise None.

Examples using get_montage:

How to convert 3D electrode positions to a 2D image

interpolate_bads(reset_bads=True, mode='accurate', origin='auto', method=None, exclude=(), 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 v0.17.

methoddict | str | None

Method to use for each channel type.

"meg" channels support "MNE" (default) and "nan"
"eeg" channels support "spline" (default), "MNE" and "nan"
"fnirs" channels support "nearest" (default) and "nan"
"ecog" channels support "spline" (default) and "nan"
"seeg" channels support "spline" (default) and "nan"

None is an alias for:

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

If a str is provided, the method will be applied to all channel types supported and available in the instance. The method "nan" will replace the channel data with np.nan.

Warning

Be careful when using method="nan"; the default value reset_bads=True may not be what you want.

New in v0.21.

excludelist | tuple

The channels to exclude from interpolation. If excluded a bad channel will stay in bads.

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 Raw, Epochs, or Evoked: The modified instance.

Notes

The "MNE" method uses minimum-norm projection to a sphere and back.

New in v0.9.0.

property last_samp#: The last data sample.

load_bad_channels(bad_file=None, force=False, verbose=None)[source]#

Mark channels as bad from a text file.

This function operates mostly in the style of the C function mne_mark_bad_channels. Each line in the text file will be interpreted as a name of a bad channel.

Parameters:

bad_filepath-like | None: File name of the text file containing bad channels. If None (default), bad channels are cleared, but this is more easily done directly with raw.info['bads'] = [].
forcebool: Whether or not to force bad channel marking (of those that exist) if channels are not found, instead of raising an error. Defaults to False.
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.

load_data(verbose=None)[source]#

Load raw data.

Parameters:

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:

rawinstance of Raw: The raw object with data.

Notes

This function will load raw data if it was not already preloaded. If data were already preloaded, it will do nothing.

New in v0.10.0.

Examples using load_data:

Overview of MEG/EEG analysis with MNE-Python

How to convert 3D electrode positions to a 2D image

Compute evoked ERS source power using DICS, LCMV beamformer, and dSPM

property n_times#: Number of time points.

notch_filter(freqs, picks=None, filter_length='auto', notch_widths=None, trans_bandwidth=1.0, n_jobs=None, method='fir', iir_params=None, mt_bandwidth=None, p_value=0.05, phase='zero', fir_window='hamming', fir_design='firwin', pad='reflect_limited', skip_by_annotation=('edge', 'bad_acq_skip'), verbose=None)[source]#

Notch filter a subset of channels.

Parameters:

freqsfloat | array of float | None

Specific frequencies to filter out from data, e.g., np.arange(60, 241, 60) in the US or np.arange(50, 251, 50) in Europe. None can only be used with the mode 'spectrum_fit', where an F test is used to find sinusoidal components.

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.

When method=='spectrum_fit', this sets the effective window duration over which fits are computed. See mne.filter.create_filter() for options. Longer window lengths will give more stable frequency estimates, but require (potentially much) more processing and are not able to adapt as well to non-stationarities.

The default in 0.21 is None, but this will change to '10s' in 0.22.

notch_widthsfloat | array of float | None

Width of each stop band (centred at each freq in freqs) in Hz. If None, freqs / 200 is used.

trans_bandwidthfloat

Width of the transition band in Hz. Only used for method='fir' and method='iir'.

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

mt_bandwidthfloat | None

The bandwidth of the multitaper windowing function in Hz. Only used in ‘spectrum_fit’ mode.

p_valuefloat

P-value to use in F-test thresholding to determine significant sinusoidal components to remove when method='spectrum_fit' and freqs=None. Note that this will be Bonferroni corrected for the number of frequencies, so large p-values may be justified.

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.

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

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.

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:

rawinstance of Raw: The raw instance with filtered data.

See also

mne.filter.notch_filter
mne.io.Raw.filter

Notes

Applies a zero-phase notch filter to the channels selected by “picks”. By default the data of the Raw object is modified inplace.

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

Note

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

For details, see mne.filter.notch_filter().

Examples using notch_filter:

pick(picks, exclude=(), *, verbose=None)[source]#

Pick a subset of channels.

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 channels. Note that channels in info['bads'] will be included if their names or indices are explicitly provided.
excludelist | str: Set of channels to exclude, only used when picking based on types (e.g., exclude=”bads” when picks=”meg”).
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.

New in v0.24.0.

Returns:

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

Examples using pick:

Getting started with mne.Report

Repairing artifacts with ICA

Signal-space separation (SSS) and Maxwell filtering

Regression-based baseline correction

EEG source localization given electrode locations on an MRI

Make figures more publication ready

Transform EEG data using current source density (CSD)

How to convert 3D electrode positions to a 2D image

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

Compute effect-matched-spatial filtering (EMS)

Computing source timecourses with an XFit-like multi-dipole model

Overview of MEG/EEG analysis with MNE-Python

pick_channels(ch_names, ordered=True, *, verbose=None)[source]#

Warning

LEGACY: New code should use inst.pick(…).

Pick some channels.

Parameters:

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

New in v0.20.0.

Changed in version 1.7: The default changed from False in 1.6 to True in 1.7.
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.

New in v1.1.

Returns:

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

See also

drop_channels
pick_types
reorder_channels

Notes

If ordered is False, the channel names given via ch_names are assumed to be a set, that is, their order does not matter. In that case, the original order of the channels in the data is preserved. Apart from using ordered=True, you may also use reorder_channels to set channel order, if necessary.

New in v0.9.0.

pick_types(meg=False, 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, dbs=False, temperature=False, gsr=False, eyetrack=False, include=(), exclude='bads', selection=None, verbose=None)[source]#

Warning

LEGACY: New code should use inst.pick(…).

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 respiratory channels.
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.
dbsbool: Deep brain stimulation channels.
temperaturebool: Temperature channels.
gsrbool: Galvanic skin response channels.
eyetrackbool | str: Eyetracking channels. If True include all eyetracking channels. If False (default) include none. If string it can be ‘eyegaze’ (to include eye position channels) or ‘pupil’ (to include pupil-size 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, etc.) to this list of channel names.
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 Raw, Epochs, or Evoked: The modified instance.

See also

pick_channels

Notes

New in v0.9.0.

plot(events=None, duration=10.0, start=0.0, n_channels=20, bgcolor='w', color=None, bad_color='lightgray', event_color='cyan', scalings=None, remove_dc=True, order=None, show_options=False, title=None, show=True, block=False, highpass=None, lowpass=None, filtorder=4, clipping=1.5, show_first_samp=False, proj=True, group_by='type', butterfly=False, decim='auto', noise_cov=None, event_id=None, show_scrollbars=True, show_scalebars=True, time_format='float', precompute=None, use_opengl=None, *, picks=None, theme=None, overview_mode=None, splash=True, verbose=None)[source]#

Plot raw data.

Parameters:

eventsarray | None

Events to show with vertical bars.

durationfloat

Time window (s) to plot. The lesser of this value and the duration of the raw file will be used.

startfloat

Initial time to show (can be changed dynamically once plotted). If show_first_samp is True, then it is taken relative to raw.first_samp.

n_channelsint

Number of channels to plot at once. Defaults to 20. The lesser of n_channels and len(raw.ch_names) will be shown. Has no effect if order is ‘position’, ‘selection’ or ‘butterfly’.

bgcolorcolor object

Color of the background.

colordict | color object | None

Color for the data traces. If None, defaults to:

dict(mag='darkblue', grad='b', eeg='k', eog='k', ecg='m',
     emg='k', ref_meg='steelblue', misc='k', stim='k',
     resp='k', chpi='k')

bad_colorcolor object

Color to make bad channels.

event_colorcolor object | dict | None

Color(s) to use for events. To show all events in the same color, pass any matplotlib-compatible color. To color events differently, pass a dict that maps event names or integer event numbers to colors (must include entries for all events, or include a “fallback” entry with key -1). If None, colors are chosen from the current Matplotlib color cycle. Defaults to 'cyan'.

scalings‘auto’ | dict | None

Scaling factors for the traces. If a dictionary where any value is 'auto', the scaling factor is set to match the 99.5th percentile of the respective data. If 'auto', all scalings (for all channel types) are set to 'auto'. If any values are 'auto' and the data is not preloaded, a subset up to 100 MB will be loaded. If None, defaults to:

dict(mag=1e-12, grad=4e-11, eeg=20e-6, eog=150e-6, ecg=5e-4,
     emg=1e-3, ref_meg=1e-12, misc=1e-3, stim=1,
     resp=1, chpi=1e-4, whitened=1e2)

Note

A particular scaling value s corresponds to half of the visualized signal range around zero (i.e. from 0 to +s or from 0 to -s). For example, the default scaling of 20e-6 (20µV) for EEG signals means that the visualized range will be 40 µV (20 µV in the positive direction and 20 µV in the negative direction).

remove_dcbool

If True remove DC component when plotting data.

orderarray of int | None

Order in which to plot data. If the array is shorter than the number of channels, only the given channels are plotted. If None (default), all channels are plotted. If group_by is 'position' or 'selection', the order parameter is used only for selecting the channels to be plotted.

show_optionsbool

If True, a dialog for options related to projection is shown.

titlestr | None

The title of the window. If None, and either the filename of the raw object or ‘<unknown>’ will be displayed as title.

showbool

Show figure if True.

blockbool

Whether to halt program execution until the figure is closed. Useful for setting bad channels on the fly by clicking on a line. May not work on all systems / platforms. (Only Qt) If you run from a script, this needs to be True or a Qt-eventloop needs to be started somewhere else in the script (e.g. if you want to implement the browser inside another Qt-Application).

highpassfloat | None

Highpass to apply when displaying data.

lowpassfloat | None

Lowpass to apply when displaying data. If highpass > lowpass, a bandstop rather than bandpass filter will be applied.

filtorderint

Filtering order. 0 will use FIR filtering with MNE defaults. Other values will construct an IIR filter of the given order and apply it with filtfilt() (making the effective order twice filtorder). Filtering may produce some edge artifacts (at the left and right edges) of the signals during display.

Changed in version 0.18: Support for filtorder=0 to use FIR filtering.

clippingstr | float | None

If None, channels are allowed to exceed their designated bounds in the plot. If “clamp”, then values are clamped to the appropriate range for display, creating step-like artifacts. If “transparent”, then excessive values are not shown, creating gaps in the traces. If float, clipping occurs for values beyond the clipping multiple of their dedicated range, so clipping=1. is an alias for clipping='transparent'.

Changed in version 0.21: Support for float, and default changed from None to 1.5.

show_first_sampbool

If True, show time axis relative to the raw.first_samp.

projbool

Whether to apply projectors prior to plotting (default is True). Individual projectors can be enabled/disabled interactively (see Notes). This argument only affects the plot; use raw.apply_proj() to modify the data stored in the Raw object.

group_bystr

How to group channels. 'type' groups by channel type, 'original' plots in the order of ch_names, 'selection' uses Elekta’s channel groupings (only works for Neuromag data), 'position' groups the channels by the positions of the sensors. 'selection' and 'position' modes allow custom selections by using a lasso selector on the topomap. In butterfly mode, 'type' and 'original' group the channels by type, whereas 'selection' and 'position' use regional grouping. 'type' and 'original' modes are ignored when order is not None. Defaults to 'type'.

butterflybool

Whether to start in butterfly mode. Defaults to False.

decimint | ‘auto’

Amount to decimate the data during display for speed purposes. You should only decimate if the data are sufficiently low-passed, otherwise aliasing can occur. The ‘auto’ mode (default) uses the decimation that results in a sampling rate least three times larger than min(info['lowpass'], lowpass) (e.g., a 40 Hz lowpass will result in at least a 120 Hz displayed sample rate).

noise_covinstance of Covariance | str | None

Noise covariance used to whiten the data while plotting. Whitened data channels are scaled by scalings['whitened'], and their 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 v0.16.0.

event_iddict | None

Event IDs used to show at event markers (default None shows the event numbers).

New in v0.16.0.

show_scrollbarsbool

Whether to show scrollbars when the plot is initialized. Can be toggled after initialization by pressing z (“zen mode”) while the plot window is focused. Default is True.

New in v0.19.0.

show_scalebarsbool

Whether to show scale bars when the plot is initialized. Can be toggled after initialization by pressing s while the plot window is focused. Default is True.

New in v0.20.0.

time_format‘float’ | ‘clock’

Style of time labels on the horizontal axis. If 'float', labels will be number of seconds from the start of the recording. If 'clock', labels will show “clock time” (hours/minutes/seconds) inferred from raw.info['meas_date']. Default is 'float'.

New in v0.24.

precomputebool | str

Whether to load all data (not just the visible portion) into RAM and apply preprocessing (e.g., projectors) to the full data array in a separate processor thread, instead of window-by-window during scrolling. The default None uses the MNE_BROWSER_PRECOMPUTE variable, which defaults to 'auto'. 'auto' compares available RAM space to the expected size of the precomputed data, and precomputes only if enough RAM is available. This is only used with the Qt backend.

New in v0.24.

Changed in version 1.0: Support for the MNE_BROWSER_PRECOMPUTE config variable.

use_openglbool | None

Whether to use OpenGL when rendering the plot (requires pyopengl). May increase performance, but effect is dependent on system CPU and graphics hardware. Only works if using the Qt backend. Default is None, which will use False unless the user configuration variable MNE_BROWSER_USE_OPENGL is set to 'true', see mne.set_config().

New in v0.24.

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.

themestr | path-like

Can be “auto”, “light”, or “dark” or a path-like to a custom stylesheet. For Dark-Mode and automatic Dark-Mode-Detection, qdarkstyle and darkdetect, respectively, are required. If None (default), the config option MNE_BROWSER_THEME will be used, defaulting to “auto” if it’s not found. Only supported by the 'qt' backend.

New in v1.0.

overview_modestr | None

Can be “channels”, “empty”, or “hidden” to set the overview bar mode for the 'qt' backend. If None (default), the config option MNE_BROWSER_OVERVIEW_MODE will be used, defaulting to “channels” if it’s not found.

New in v1.1.

splashbool

If True (default), a splash screen is shown during the application startup. Only applicable to the qt backend.

New in v1.6.

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:

figmatplotlib.figure.Figure | mne_qt_browser.figure.MNEQtBrowser: Browser instance.

Notes

The arrow keys (up/down/left/right) can typically be used to navigate between channels and time ranges, but this depends on the backend matplotlib is configured to use (e.g., mpl.use(‘TkAgg’) should work). The left/right arrows will scroll by 25% of duration, whereas shift+left/shift+right will scroll by 100% of duration. The scaling can be adjusted with - and + (or =) keys. The viewport dimensions can be adjusted with page up/page down and home/end keys. Full screen mode can be toggled with the F11 key, and scrollbars can be hidden/shown by pressing ‘z’. Right-click a channel label to view its location. To mark or un-mark a channel as bad, click on a channel label or a channel trace. The changes will be reflected immediately in the raw object’s raw.info['bads'] entry.

If projectors are present, a button labelled “Prj” in the lower right corner of the plot window opens a secondary control window, which allows enabling/disabling specific projectors individually. This provides a means of interactively observing how each projector would affect the raw data if it were applied.

Annotation mode is toggled by pressing ‘a’, butterfly mode by pressing ‘b’, and whitening mode (when noise_cov is not None) by pressing ‘w’. By default, the channel means are removed when remove_dc is set to True. This flag can be toggled by pressing ‘d’.

MNE-Python provides two different backends for browsing plots (i.e., raw.plot(), epochs.plot(), and ica.plot_sources()). One is based on matplotlib, and the other is based on PyQtGraph. You can set the backend temporarily with the context manager mne.viz.use_browser_backend(), you can set it for the duration of a Python session using mne.viz.set_browser_backend(), and you can set the default for your computer via mne.set_config('MNE_BROWSER_BACKEND', 'matplotlib') (or 'qt').

Note

For the PyQtGraph backend to run in IPython with block=False you must run the magic command %gui qt5 first.

Note

To report issues with the PyQtGraph backend, please use the issues of mne-qt-browser.

Examples using plot:

Importing Data from Eyetracking devices

Working with events

Handling bad channels

Auto-generating Epochs metadata

Brainstorm Elekta phantom dataset tutorial

Plotting whitened data

Transform EEG data using current source density (CSD)

Maxwell filter data with movement compensation

Plot sensor denoising using oversampled temporal projection

plot_projs_topomap(ch_type=None, *, sensors=True, show_names=False, contours=6, outlines='head', sphere=None, image_interp='cubic', extrapolate='auto', border='mean', res=64, size=1, cmap=None, vlim=(None, None), cnorm=None, colorbar=False, cbar_fmt='%3.1f', units=None, axes=None, show=True)[source]#

Plot SSP vector.

Parameters:

The channel type to plot. For 'grad', the gradiometers are collected in pairs and the RMS for each pair is plotted. If None it will return all channel types present.. If a list of ch_types is provided, it will return multiple figures. Defaults to None.

sensorsbool | str

Whether to add markers for sensor locations. If str, should be a valid matplotlib format string (e.g., 'r+' for red plusses, see the Notes section of plot()). If True (the default), black circles will be used.

show_namesbool | callable()

If True, show channel names next to each sensor marker. If callable, 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 non-masked sensor names will be shown.

New in v1.2.

contoursint | array_like

The number of contour lines to draw. If 0, no contours will be drawn. If a positive integer, that number of contour levels are chosen using the matplotlib tick locator (may sometimes be inaccurate, use array for accuracy). If array-like, the array values are used as the contour levels. The values should be in µV for EEG, fT for magnetometers and fT/m for gradiometers. If colorbar=True, the colorbar will have ticks corresponding to the contour levels. Default is 6.

outlines‘head’ | dict | None

The outlines to be drawn. If ‘head’, the default head scheme will be drawn. 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’.

The sphere parameters to use for the head outline. Can be array-like of shape (4,) to give the X/Y/Z origin and radius in meters, or a single float to give just the radius (origin assumed 0, 0, 0). Can also be an instance of a spherical ConductorModel to use the origin and radius from that object. If 'auto' the sphere is fit to digitization points. If 'eeglab' the head circle is defined by EEG electrodes 'Fpz', 'Oz', 'T7', and 'T8' (if 'Fpz' is not present, it will be approximated from the coordinates of 'Oz'). None (the default) is equivalent to 'auto' when enough extra digitization points are available, and (0, 0, 0, 0.095) otherwise.

New in v0.20.

Changed in version 1.1: Added 'eeglab' option.

image_interpstr

The image interpolation to be used. Options are 'cubic' (default) to use scipy.interpolate.CloughTocher2DInterpolator, 'nearest' to use scipy.spatial.Voronoi or 'linear' to use scipy.interpolate.LinearNDInterpolator.

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 for MEG sensors)
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' (default for non-MEG sensors)
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.

New in v0.20.

Changed in version 0.21:

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

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

resint

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

sizefloat

Side length of each subplot in inches. Only applies when plotting multiple topomaps at a time.

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. Hitting space bar resets the range. Up and down arrows can be used to change the colormap. If None, 'Reds' is used for data that is either all-positive or all-negative, and 'RdBu_r' is used otherwise. 'interactive' is equivalent to (None, True). Defaults to None.

Warning

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

vlimtuple of length 2 | “joint”

Lower and upper bounds of the colormap, typically a numeric value in the same units as the data. Elements of the tuple may also be callable functions which take in a NumPy array and return a scalar.

If both entries are None, the bounds are set at ± the maximum absolute value of the data (yielding a colormap with midpoint at 0), or (0, max(abs(data))) if the (possibly baselined) data are all-positive. Providing None for just one entry will set the corresponding boundary at the min/max of the data. If vlim="joint", will compute the colormap limits jointly across all projectors of the same channel type (instead of separately for each projector), using the min/max of the data for that channel type. If vlim is "joint", info must not be None. Defaults to (None, None).

cnormmatplotlib.colors.Normalize | None

How to normalize the colormap. If None, standard linear normalization is performed. If not None, vmin and vmax will be ignored. See Matplotlib docs for more details on colormap normalization, and the ERDs example for an example of its use.

New in v1.2.

colorbarbool

Plot a colorbar in the rightmost column of the figure.

cbar_fmtstr

Formatting string for colorbar tick labels. See Format Specification Mini-Language for details.

New in v1.2.

unitsstr | None

The units to use for the colorbar label. Ignored if colorbar=False. If None the label will be “AU” indicating arbitrary units. Default is None.

New in v1.2.

axesinstance of Axes | list of Axes | None

The axes to plot into. If None, a new Figure will be created with the correct number of axes. If Axes are provided (either as a single instance or a list of axes), the number of axes provided must match the number of projectors. Default is None.

showbool

Show the figure if True.

Returns:

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

Examples using plot_projs_topomap:

Working with sensor locations

plot_psd(fmin=0, fmax=inf, tmin=None, tmax=None, picks=None, proj=False, reject_by_annotation=True, *, method='auto', average=False, dB=True, estimate='power', xscale='linear', area_mode='std', area_alpha=0.33, color='black', line_alpha=None, spatial_colors=True, sphere=None, exclude='bads', ax=None, show=True, n_jobs=1, verbose=None, **method_kw)[source]#

Warning

LEGACY: New code should use .compute_psd().plot().

Plot power or amplitude spectra.

Separate plots are drawn for each channel type. When the data have been processed with a bandpass, lowpass or highpass filter, dashed lines (╎) indicate the boundaries of the filter. The line noise frequency is also indicated with a dashed line (⋮). If average=False, the plot will be interactive, and click-dragging on the spectrum will generate a scalp topography plot for the chosen frequency range in a new figure.

Parameters:

fmin, fmaxfloat: The lower- and upper-bound on frequencies of interest. Default is fmin=0, fmax=np.inf (spans all frequencies present in the data).
tmin, tmaxfloat | None: First and last times to include, in seconds. None uses the first or last time present in the data. Default is tmin=None, tmax=None (all times).
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 good data channels (excluding reference MEG channels). Note that channels in info['bads'] will be included if their names or indices are explicitly provided.
projbool: Whether to apply SSP projection vectors before spectral estimation. Default is False.
reject_by_annotationbool: Whether to omit bad spans of data before spectral estimation. If True, spans with annotations whose description begins with bad will be omitted.
method'welch' | 'multitaper' | 'auto': Spectral estimation method. 'welch' uses Welch’s method [1], 'multitaper' uses DPSS tapers [2]. 'auto' (default) uses Welch’s method for continuous data and multitaper for Epochs or Evoked data.
averagebool: If False, the PSDs of all channels is displayed. No averaging is done and parameters area_mode and area_alpha are ignored. When False, it is possible to paint an area (hold left mouse button and drag) to plot a topomap.
dBbool: Plot Power Spectral Density (PSD), in units (amplitude**2/Hz (dB)) if dB=True, and estimate='power' or estimate='auto'. Plot PSD in units (amplitude**2/Hz) if dB=False and, estimate='power'. Plot Amplitude Spectral Density (ASD), in units (amplitude/sqrt(Hz)), if dB=False and estimate='amplitude' or estimate='auto'. Plot ASD, in units (amplitude/sqrt(Hz) (dB)), if dB=True and estimate='amplitude'.
estimatestr, {‘power’, ‘amplitude’}: Can be “power” for power spectral density (PSD; default), “amplitude” for amplitude spectrum density (ASD).
xscale‘linear’ | ‘log’: Scale of the frequency axis. Default is 'linear'.
area_modestr | None: Mode for plotting area. If ‘std’, the mean +/- 1 STD (across channels) will be plotted. If ‘range’, the min and max (across channels) will be plotted. Bad channels will be excluded from these calculations. If None, no area will be plotted. If average=False, no area is plotted.
area_alphafloat: Alpha for the area.
colorstr | tuple: A matplotlib-compatible color to use. Has no effect when spatial_colors=True.
line_alphafloat | None: Alpha for the PSD line. Can be None (default) to use 1.0 when average=True and 0.1 when average=False.
spatial_colorsbool: Whether to color spectrum lines by channel location. Ignored if average=True.
spherefloat | array_like | instance of ConductorModel | None | ‘auto’ | ‘eeglab’: The sphere parameters to use for the head outline. Can be array-like of shape (4,) to give the X/Y/Z origin and radius in meters, or a single float to give just the radius (origin assumed 0, 0, 0). Can also be an instance of a spherical ConductorModel to use the origin and radius from that object. If 'auto' the sphere is fit to digitization points. If 'eeglab' the head circle is defined by EEG electrodes 'Fpz', 'Oz', 'T7', and 'T8' (if 'Fpz' is not present, it will be approximated from the coordinates of 'Oz'). None (the default) is equivalent to 'auto' when enough extra digitization points are available, and (0, 0, 0, 0.095) otherwise.

New in v0.20.

Changed in version 1.1: Added 'eeglab' option.

New in v0.22.0.
excludelist of str | ‘bads’: Channels names to exclude from being shown. If ‘bads’, the bad channels are excluded. Pass an empty list to plot all channels (including channels marked “bad”, if any).

New in v0.24.0.
axinstance of Axes | list of Axes | None: The axes to plot into. If None, a new Figure will be created with the correct number of axes. If Axes are provided (either as a single instance or a list of axes), the number of axes provided must match the number of channel types present in the object.. Default is None.
showbool: Show the figure if True.
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.
**method_kw: Additional keyword arguments passed to the spectral estimation function (e.g., n_fft, n_overlap, n_per_seg, average, window for Welch method, or bandwidth, adaptive, low_bias, normalization for multitaper method). See psd_array_welch() and psd_array_multitaper() for details. Note that for Welch method if n_fft is unspecified its default will be the smaller of 2048 or the number of available time samples (taking into account tmin and tmax), not 256 as in psd_array_welch().

Returns:

figinstance of Figure: Figure with frequency spectra of the data channels.

Notes

This method exists to support legacy code; for new code the preferred idiom is inst.compute_psd().plot() (where inst is an instance of Raw, Epochs, or Evoked).

plot_psd_topo(tmin=None, tmax=None, fmin=0, fmax=100, proj=False, *, method='auto', dB=True, layout=None, color='w', fig_facecolor='k', axis_facecolor='k', axes=None, block=False, show=True, n_jobs=None, verbose=None, **method_kw)[source]#

Warning

LEGACY: New code should use .compute_psd().plot_topo().

Plot power spectral density, separately for each channel.

Parameters:

tmin, tmaxfloat | None: First and last times to include, in seconds. None uses the first or last time present in the data. Default is tmin=None, tmax=None (all times).
fmin, fmaxfloat: The lower- and upper-bound on frequencies of interest. Default is fmin=0, fmax=100.
projbool: Whether to apply SSP projection vectors before spectral estimation. Default is False.
method'welch' | 'multitaper' | 'auto': Spectral estimation method. 'welch' uses Welch’s method [1], 'multitaper' uses DPSS tapers [2]. 'auto' (default) uses Welch’s method for continuous data and multitaper for Epochs or Evoked data.
dBbool: Whether to plot on a decibel-like scale. If True, plots 10 × log₁₀(spectral power). Ignored if normalize=True.
layoutinstance of Layout | None: Layout instance specifying sensor positions (does not need to be specified for Neuromag data). If None (default), the layout is inferred from the data (if possible).
colorstr | tuple: A matplotlib-compatible color to use for the curves. Defaults to white.
fig_facecolorstr | tuple: A matplotlib-compatible color to use for the figure background. Defaults to black.
axis_facecolorstr | tuple: A matplotlib-compatible color to use for the axis background. Defaults to black.
axesinstance of Axes | list of Axes | None: The axes to plot into. If None, a new Figure will be created with the correct number of axes. If Axes are provided (either as a single instance or a list of axes), the number of axes provided must be length 1 (for efficiency, subplots for each channel are simulated within a single Axes object). Default is None.
blockbool: Whether to halt program execution until the figure is closed. May not work on all systems / platforms. Defaults to False.
showbool: Show the figure if True.
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.
**method_kw: Additional keyword arguments passed to the spectral estimation function (e.g., n_fft, n_overlap, n_per_seg, average, window for Welch method, or bandwidth, adaptive, low_bias, normalization for multitaper method). See psd_array_welch() and psd_array_multitaper() for details. Note that for Welch method if n_fft is unspecified its default will be the smaller of 2048 or the number of available time samples (taking into account tmin and tmax), not 256 as in psd_array_welch(). Defaults to dict(n_fft=2048).

Returns:

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

plot_psd_topomap(bands=None, tmin=None, tmax=None, ch_type=None, *, proj=False, method='auto', normalize=False, agg_fun=None, dB=False, sensors=True, show_names=False, mask=None, mask_params=None, contours=0, outlines='head', sphere=None, image_interp='cubic', extrapolate='auto', border='mean', res=64, size=1, cmap=None, vlim=(None, None), cnorm=None, colorbar=True, cbar_fmt='auto', units=None, axes=None, show=True, n_jobs=None, verbose=None, **method_kw)[source]#

Warning

LEGACY: New code should use .compute_psd().plot_topomap().

Plot scalp topography of PSD for chosen frequency bands.

Parameters:

bandsNone | dict | list of tuple

The frequencies or frequency ranges to plot. If a dict, keys will be used as subplot titles and values should be either a single frequency (e.g., {'presentation rate': 6.5}) or a length-two sequence of lower and upper frequency band edges (e.g., {'theta': (4, 8)}). If a single frequency is provided, the plot will show the frequency bin that is closest to the requested value. If None (the default), expands to:

bands = {'Delta (0-4 Hz)': (0, 4), 'Theta (4-8 Hz)': (4, 8),
         'Alpha (8-12 Hz)': (8, 12), 'Beta (12-30 Hz)': (12, 30),
         'Gamma (30-45 Hz)': (30, 45)}

Note

For backwards compatibility, tuples of length 2 or 3 are also accepted, where the last element of the tuple is the subplot title and the other entries are frequency values (a single value or band edges). New code should use dict or None.

Changed in version 1.2: Allow passing a dict and discourage passing tuples.

tmin, tmaxfloat | None

First and last times to include, in seconds. None uses the first or last time present in the data. Default is tmin=None, tmax=None (all times).

The channel type to plot. For 'grad', the gradiometers are collected in pairs and the mean for each pair is plotted. If None the first available channel type from order shown above is used. Defaults to None.

projbool

Whether to apply SSP projection vectors before spectral estimation. Default is False.

method'welch' | 'multitaper' | 'auto'

Spectral estimation method. 'welch' uses Welch’s method [1], 'multitaper' uses DPSS tapers [2]. 'auto' (default) uses Welch’s method for continuous data and multitaper for Epochs or Evoked data.

normalizebool

If True, each band will be divided by the total power. Defaults to False.

agg_funcallable()

The function used to aggregate over frequencies. Defaults to numpy.sum() if normalize=True, else numpy.mean().

dBbool

Whether to plot on a decibel-like scale. If True, plots 10 × log₁₀(spectral power) following the application of agg_fun. Ignored if normalize=True.

sensorsbool | str

Whether to add markers for sensor locations. If str, should be a valid matplotlib format string (e.g., 'r+' for red plusses, see the Notes section of plot()). If True (the default), black circles will be used.

show_namesbool | callable()

If True, show channel names next to each sensor marker. If callable, 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 non-masked sensor names will be shown.

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

Array indicating channel-time combinations to highlight with a distinct plotting style (useful for, e.g. marking which channels at which times a statistical test of the data reaches significance). Array elements set to True will be plotted with the parameters given in mask_params. Defaults to None, equivalent to an array of all False elements.

mask_paramsdict | None

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

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

contoursint | array_like

The number of contour lines to draw. If 0, no contours will be drawn. If a positive integer, that number of contour levels are chosen using the matplotlib tick locator (may sometimes be inaccurate, use array for accuracy). If array-like, the array values are used as the contour levels. The values should be in µV for EEG, fT for magnetometers and fT/m for gradiometers. If colorbar=True, the colorbar will have ticks corresponding to the contour levels. Default is 6.

outlines‘head’ | dict | None

The outlines to be drawn. If ‘head’, the default head scheme will be drawn. 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’.

The sphere parameters to use for the head outline. Can be array-like of shape (4,) to give the X/Y/Z origin and radius in meters, or a single float to give just the radius (origin assumed 0, 0, 0). Can also be an instance of a spherical ConductorModel to use the origin and radius from that object. If 'auto' the sphere is fit to digitization points. If 'eeglab' the head circle is defined by EEG electrodes 'Fpz', 'Oz', 'T7', and 'T8' (if 'Fpz' is not present, it will be approximated from the coordinates of 'Oz'). None (the default) is equivalent to 'auto' when enough extra digitization points are available, and (0, 0, 0, 0.095) otherwise.

New in v0.20.

Changed in version 1.1: Added 'eeglab' option.

image_interpstr

The image interpolation to be used. Options are 'cubic' (default) to use scipy.interpolate.CloughTocher2DInterpolator, 'nearest' to use scipy.spatial.Voronoi or 'linear' to use scipy.interpolate.LinearNDInterpolator.

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 for MEG sensors)
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' (default for non-MEG sensors)
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.

borderfloat | ‘mean’

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

resint

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

sizefloat

Side length of each subplot in inches.

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. Hitting space bar resets the range. Up and down arrows can be used to change the colormap. If None, 'Reds' is used for data that is either all-positive or all-negative, and 'RdBu_r' is used otherwise. 'interactive' is equivalent to (None, True). Defaults to None.

Warning

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

vlimtuple of length 2 | “joint”

Lower and upper bounds of the colormap, typically a numeric value in the same units as the data. Elements of the tuple may also be callable functions which take in a NumPy array and return a scalar.

If both entries are None, the bounds are set at ± the maximum absolute value of the data (yielding a colormap with midpoint at 0), or (0, max(abs(data))) if the (possibly baselined) data are all-positive. Providing None for just one entry will set the corresponding boundary at the min/max of the data. If vlim="joint", will compute the colormap limits jointly across all topomaps of the same channel type (instead of separately for each topomap), using the min/max of the data for that channel type. Defaults to (None, None).

cnormmatplotlib.colors.Normalize | None

How to normalize the colormap. If None, standard linear normalization is performed. If not None, vmin and vmax will be ignored. See Matplotlib docs for more details on colormap normalization, and the ERDs example for an example of its use.

New in v1.2.

colorbarbool

Plot a colorbar in the rightmost column of the figure.

cbar_fmtstr

Formatting string for colorbar tick labels. See Format Specification Mini-Language for details. If 'auto', is equivalent to ‘%0.3f’ if dB=False and ‘%0.1f’ if dB=True. Defaults to 'auto'.

unitsstr | None

The units to use for the colorbar label. Ignored if colorbar=False. If None the label will be “AU” indicating arbitrary units. Default is None.

axesinstance of Axes | list of Axes | None

The axes to plot into. If None, a new Figure will be created with the correct number of axes. If Axes are provided (either as a single instance or a list of axes), the number of axes provided must match the length of bands. Default is None.

showbool

Show the figure if True.

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.

**method_kw

Additional keyword arguments passed to the spectral estimation function (e.g., n_fft, n_overlap, n_per_seg, average, window for Welch method, or bandwidth, adaptive, low_bias, normalization for multitaper method). See psd_array_welch() and psd_array_multitaper() for details. Note that for Welch method if n_fft is unspecified its default will be the smaller of 2048 or the number of available time samples (taking into account tmin and tmax), not 256 as in psd_array_welch().

Returns:

figinstance of Figure: Figure showing one scalp topography per frequency band.

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', 'dbs', 'ecog', 'all'. If 'all', all the available mag, grad, eeg, seeg, dbs, 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 v0.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 v0.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 v0.13.0.
blockbool: Whether to halt program execution until the figure is closed. Defaults to False.

New in v0.13.0.
showbool: Show figure if True. Defaults to True.
spherefloat | array_like | instance of ConductorModel | None | ‘auto’ | ‘eeglab’: The sphere parameters to use for the head outline. Can be array-like of shape (4,) to give the X/Y/Z origin and radius in meters, or a single float to give just the radius (origin assumed 0, 0, 0). Can also be an instance of a spherical ConductorModel to use the origin and radius from that object. If 'auto' the sphere is fit to digitization points. If 'eeglab' the head circle is defined by EEG electrodes 'Fpz', 'Oz', 'T7', and 'T8' (if 'Fpz' is not present, it will be approximated from the coordinates of 'Oz'). None (the default) is equivalent to 'auto' when enough extra digitization points are available, and (0, 0, 0, 0.095) otherwise.

New in v0.20.

Changed in version 1.1: Added 'eeglab' option.
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:

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 PyVista see mne.viz.plot_alignment().

New in v0.12.0.

Examples using plot_sensors:

EEG source localization given electrode locations on an MRI

property proj#: Whether or not projections are active.

rename_channels(mapping, allow_duplicates=False, *, verbose=None)[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.
allow_duplicatesbool: If True (default False), allow duplicates, which will automatically be renamed with -N at the end.

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

Returns:

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

Changed in version 0.20: Return the instance.

Notes

New in v0.9.0.

Examples using rename_channels:

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

resample(sfreq, *, npad='auto', window='auto', stim_picks=None, n_jobs=None, events=None, pad='auto', method='fft', verbose=None)[source]#

Resample all channels.

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

Warning

The intended purpose of this function is primarily to speed up computations (e.g., projection calculation) when precise timing of events is not required, as downsampling raw data effectively jitters trigger timings. It is generally recommended not to epoch downsampled data, but instead epoch and then downsample, as epoching downsampled data jitters triggers. For more, see this illustrative gist.

If resampling the continuous data is desired, it is recommended to construct events using the original data. The event onsets can be jointly resampled with the raw data using the ‘events’ parameter (a resampled copy is returned).

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

Only used when method="fft".

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

stim_pickslist of int | None

Stim channels. These channels are simply subsampled or supersampled (without applying any filtering). This reduces resampling artifacts in stim channels, but may lead to missing triggers. If None, stim channels are automatically chosen using mne.pick_types().

n_jobsint | str

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

events2D array, shape (n_events, 3) | None

An optional event matrix. When specified, the onsets of the events are resampled jointly with the data. NB: The input events are not modified, but a new array is returned with the raw instead.

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

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.

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:

rawinstance of Raw: The resampled version of the raw object.
eventsarray, shape (n_events, 3) | None: If events are jointly resampled, these are returned with the raw.

See also

mne.io.Raw.filter
mne.Epochs.resample

Notes

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

For optimum performance and to make use of n_jobs > 1, the raw object has to have the data loaded e.g. with preload=True or self.load_data(), but this increases memory requirements. The resulting raw object will have the data loaded into memory.

Examples using resample:

save(fname, picks=None, tmin=0, tmax=None, buffer_size_sec=None, drop_small_buffer=False, proj=False, fmt='single', overwrite=False, split_size='2GB', split_naming='neuromag', verbose=None)[source]#

Save raw data to file.

Parameters:

fnamepath-like: File name of the new dataset. This has to be a new filename unless data have been preloaded. Filenames should end with raw.fif (common raw data), raw_sss.fif (Maxwell-filtered continuous data), raw_tsss.fif (temporally signal-space-separated data), _meg.fif (common MEG data), _eeg.fif (common EEG data), or _ieeg.fif (common intracranial EEG data). You may also append an additional .gz suffix to enable gzip compression.
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.
tminfloat: Start time of the raw data to use in seconds (must be >= 0).
tmaxfloat | None: End time of the raw data to use in seconds (cannot exceed data duration). If None (default), the current end of the data is used.
buffer_size_secfloat | None: Size of data chunks in seconds. If None (default), the buffer size of the original file is used.
drop_small_bufferbool: Drop or not the last buffer. It is required by maxfilter (SSS) that only accepts raw files with buffers of the same size.
projbool: If True the data is saved with the projections applied (active).

Note

If apply_proj() was used to apply the projections, the projectons will be active even if proj is False.
fmt‘single’ | ‘double’ | ‘int’ | ‘short’: Format to use to save raw data. Valid options are ‘double’, ‘single’, ‘int’, and ‘short’ for 64- or 32-bit float, or 32- or 16-bit integers, respectively. It is strongly recommended to use ‘single’, as this is backward-compatible, and is standard for maintaining precision. Note that using ‘short’ or ‘int’ may result in loss of precision, complex data cannot be saved as ‘short’, and neither complex data types nor real data stored as ‘double’ can be loaded with the MNE command-line tools. See raw.orig_format to determine the format the original data were stored in.
overwritebool: If True (default False), overwrite the destination file if it exists. To overwrite original file (the same one that was loaded), data must be preloaded upon reading.
split_sizestr | int: Large raw files are automatically split into multiple pieces. This parameter specifies the maximum size of each piece. If the parameter is an integer, it specifies the size in Bytes. It is also possible to pass a human-readable string, e.g., 100MB.

Note

Due to FIFF file limitations, the maximum split size is 2GB.
split_naming‘neuromag’ | ‘bids’: When splitting files, append a filename partition with the appropriate naming schema. For 'neuromag', a split file fname.fif will be named fname.fif, fname-1.fif, fname-2.fif, and so on. For 'bids', a filename is expected to consist of parts separated by underscores, like <part-1>_<part-N>_<suffix>.fif, and the according split naming will return filenames like <part-1>_<part-N>_split-01_<suffix>.fif, <part-1>_<part-N>_split-02_<suffix>.fif, and so on.

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

fnamesList of path-like: List of path-like objects containing the path to each file split. .. versionadded:: 1.9

Notes

If Raw is a concatenation of several raw files, be warned that only the measurement information from the first raw file is stored. This likely means that certain operations with external tools may not work properly on a saved concatenated file (e.g., probably some or all forms of SSS). It is recommended not to concatenate and then save raw files for this reason.

Samples annotated BAD_ACQ_SKIP are not stored in order to optimize memory. Whatever values, they will be loaded as 0s when reading 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 | 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

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_annotations(annotations, emit_warning=True, on_missing='raise', *, verbose=None)[source]#

Setter for annotations.

This setter checks if they are inside the data range.

Parameters:

annotationsinstance of mne.Annotations | None: Annotations to set. If None, the annotations is defined but empty.
emit_warningbool: Whether to emit warnings when cropping or omitting annotations. The default is True.
on_missing‘raise’ | ‘warn’ | ‘ignore’: Can be 'raise' (default) to raise an error, 'warn' to emit a warning, or 'ignore' to ignore when entries in ch_names are not present in the raw instance.

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

Returns:

selfinstance of Raw: The raw object with annotations.

Examples using set_annotations:

set_channel_types(mapping, *, on_unit_change='warn', verbose=None)[source]#

Specify the sensor types of channels.

Parameters:

mappingdict: A dictionary mapping channel names to sensor types, e.g., {'EEG061': 'eog'}.
on_unit_change'raise' | 'warn' | 'ignore': What to do if the measurement unit of a channel is changed automatically to match the new sensor type.

New in v1.4.
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 Raw | Epochs | Evoked: The instance (modified in place).

Changed in version 0.20: Return the instance.

Notes

The following sensor types are accepted:

bio, chpi, csd, dbs, dipole, ecg, ecog, eeg, emg, eog, exci, eyegaze, fnirs_cw_amplitude, fnirs_fd_ac_amplitude, fnirs_fd_phase, fnirs_od, gof, gsr, hbo, hbr, ias, misc, pupil, ref_meg, resp, seeg, stim, syst, temperature.

When working with eye-tracking data, see mne.preprocessing.eyetracking.set_channel_types_eyetrack().

New in v0.9.0.

Examples using set_channel_types:

Importing data from EEG devices

set_eeg_reference(ref_channels='average', projection=False, ch_type='auto', forward=None, *, joint=False, 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 | dict

Can be:

The name(s) of the channel(s) used to construct the reference for every channel of ch_type.
'average' to apply an average reference (default)
'REST' to use the Reference Electrode Standardization Technique infinity reference [4].
A dictionary mapping names of data channels to (lists of) names of reference channels. For example, {‘A1’: ‘A3’} would replace the data in channel ‘A1’ with the difference between ‘A1’ and ‘A3’. To take the average of multiple channels as reference, supply a list of channel names as the dictionary value, e.g. {‘A1’: [‘A2’, ‘A3’]} would replace channel A1 with A1 - mean(A2, A3).
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_typelist of str | str

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

New in v0.19.

Changed in version 1.2: list-of-str is now supported with projection=True.

forwardinstance of Forward | None

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

New in v0.21.

jointbool

How to handle list-of-str ch_type. If False (default), one projector is created per channel type. If True, one projector is created across all channel types. This is only used when projection=True.

New in v1.2.

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 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.
Different references for different channels
Set ref_channels to a dictionary mapping source channel names (str) to the reference channel names (str or list of str). Unlike the other approaches where the same reference is applied globally, you can set different references for different channels with this method. For example, to re-reference channel ‘A1’ to ‘A2’ and ‘B1’ to the average of ‘B2’ and ‘B3’, set ref_channels={'A1': 'A2', 'B1': ['B2', 'B3']}. Warnings are issued when a mapping involves bad channels or channels of different types.

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

References

Examples using set_eeg_reference:

Computing a covariance matrix

EEG source localization given electrode locations on an MRI

Corrupt known signal with point spread

Generate simulated raw data

Transform EEG data using current source density (CSD)

Compute sLORETA inverse solution on raw data

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

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

Set EEG/sEEG/ECoG/DBS/fNIRS channel positions and digitization points.

Parameters:

montageNone | str | DigMontage: A montage containing channel positions. If a string or DigMontage is specified, the existing channel information will be updated with the channel positions from the montage. Valid strings are the names of the built-in montages that ship with MNE-Python; you can list those via mne.channels.get_builtin_montages(). If None (default), the channel positions will be removed from the Info.
match_casebool: If True (default), channel name matching will be case sensitive.

New in v0.20.
match_aliasbool | dict: Whether to use a lookup table to match unrecognized channel location names to their known aliases. If True, uses the mapping in mne.io.constants.CHANNEL_LOC_ALIASES. If a dict is passed, it will be used instead, and should map from non-standard channel names to names in the specified montage. Default is False.

New in v0.23.
on_missing‘raise’ | ‘warn’ | ‘ignore’: Can be 'raise' (default) to raise an error, 'warn' to emit a warning, or 'ignore' to ignore when channels have missing coordinates.

New in v0.20.1.
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 Raw | Epochs | Evoked: The instance, modified in-place.

See also

mne.channels.make_standard_montage
mne.channels.make_dig_montage
mne.channels.read_custom_montage

Notes

Warning

Only EEG/sEEG/ECoG/DBS/fNIRS channels can have their positions set using a montage. Other channel types (e.g., MEG channels) should have their positions defined properly using their data reading functions.

Warning

Applying a montage will only set locations of channels that exist at the time it is applied. This means when re-referencing make sure to apply the montage only after calling mne.add_reference_channels()

Examples using set_montage:

Working with sensor locations

Importing data from EEG devices

EEG source localization given electrode locations on an MRI

time_as_index(times, use_rounding=False, origin=None)[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.
origindatetime | float | int | None: Time reference for times. If None, times are assumed to be relative to first_samp.

New in v0.17.0.

Returns:

indexndarray: Indices relative to first_samp corresponding to the times supplied.

Examples using time_as_index: