The time interval to consider as “baseline” when applying baseline
correction. If None, do not apply baseline correction.
If a tuple (a,b), the interval is between a and b
(in seconds), including the endpoints.
If a is None, the beginning of the data is used; and if b
is None, it is set to the end of the data.
If (None,None), the entire time interval is used.
Note
The baseline (a,b) includes both endpoints, i.e. all timepoints t
such that a<=t<=b.
Correction is applied to each channel individually in the following
way:
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.
If True, force the info for objects to be appended to match the
values in self. This should generally only be used when adding
stim channels for which important metadata won’t be overwritten.
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.
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.
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.
Channel type to plot. Accepted data types: ‘mag’, ‘grad’, ‘eeg’,
‘hbo’, ‘hbr’, ‘fnirs_cw_amplitude’,
‘fnirs_fd_ac_amplitude’, ‘fnirs_fd_phase’, and ‘fnirs_od’.
If None, first available channel type from the above list is used.
Defaults to None.
Whether to use blit to optimize drawing. In general, it is
recommended to use blit in combination with show=True. If you
intend to save the animation it is better to disable blit.
Defaults to True.
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.
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.
Lower and upper bounds of the colormap, in the same units as the data.
If vmin and vmax are both None, the bounds are set at
± the maximum absolute value
of the data (yielding a colormap with midpoint at 0). If only one of vmin, vmax is None, will use
min(data) or max(data), respectively. If callable, should accept
a NumPyarray of data and return a float.
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.
Number of days to subtract from all dates.
If None (default), the acquisition date, info['meas_date'],
will be set to January1ˢᵗ,2000. This parameter is ignored if
info['meas_date'] is None (i.e., no acquisition date has been set).
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.
The time interval to consider as “baseline” when applying baseline
correction. If None, do not apply baseline correction.
If a tuple (a,b), the interval is between a and b
(in seconds), including the endpoints.
If a is None, the beginning of the data is used; and if b
is None, it is set to the end of the data.
If (None,None), the entire time interval is used.
Note
The baseline (a,b) includes both endpoints, i.e. all timepoints t
such that a<=t<=b.
Correction is applied to each channel individually in the following
way:
Calculate the mean signal of the baseline period.
Subtract this mean from the entireEvoked.
Defaults to (None,0), i.e. beginning of the the data until
time point zero.
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.
The function fun is applied to the channels defined in picks.
The evoked 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).
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.
A function to be applied to the channels. The first argument of
fun has to be a timeseries (numpy.ndarray). The function must
operate on an array of shape (n_times,) because it will apply channel-wise.
The function must return an ndarray shaped like its input.
Note
If channel_wise=True, one can optionally access the index and/or the
name of the currently processed channel within the applied function.
This can enable tailored computations for different channels.
To use this feature, add ch_idx and/or ch_name as
additional argument(s) to your function definition.
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.
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.
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.
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.
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.
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.
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.
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+iy
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.
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.
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 againevoked.copy().del_proj(0).apply_proj().plot()evoked.apply_proj()# finally keep both
Using virtual evoked to compute inverse can yield
unexpected results. The virtual channels have '_v' appended
at the end of the names to emphasize that the data contained in
them are interpolated.
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.
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).
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.
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().
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.
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.
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.
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.
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.
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.
The cropped time-series object, modified in-place.
Notes
Unlike Python slices, MNE time intervals by default include both
their end points; crop(tmin,tmax) returns the interval
tmin<=t<=tmax. Pass include_tmax=False to specify the half-open
interval tmin<=t<tmax instead.
Low-pass filtering is not performed, this simply selects
every Nth sample (where N is the value passed to
decim), i.e., it compresses the signal (see Notes).
If the data are not properly filtered, aliasing artifacts
may occur.
See Resampling and decimating data for more information.
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.
For historical reasons, decim / “decimation” refers to simply subselecting
samples from a given signal. This contrasts with the broader signal processing
literature, where decimation is defined as (quoting
[3], p. 172; which cites
[4]):
“… a general system for downsampling by a factor of M is the one shown
in Figure 4.23. Such a system is called a decimator, and downsampling
by lowpass filtering followed by compression [i.e, subselecting samples]
has been termed decimation (Crochiere and Rabiner, 1983).”
Hence “decimation” in MNE is what is considered “compression” in the signal
processing community.
Decimation can be done multiple times. For example,
inst.decimate(2).decimate(2) will be the same as
inst.decimate(4).
If decim is 1, this method does not copy the underlying data.
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. Note
that channels in info['bads']will be included if their names or
indices are explicitly provided.
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.
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 v1.1.
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.Evoked.save() instead.
Export does not apply projector(s). Unapplied projector(s) will be lost.
Consider applying projector(s) before exporting with
mne.Evoked.apply_proj().
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.
‘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.
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:
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:
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().
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.
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”.
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.
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'.
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.
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.
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.
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.
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.
The maximum point in time to be considered for peak getting.
If None (default), the end of the data is used.
mode‘pos’ | ‘neg’ | ‘abs’
How to deal with the sign of the data. If ‘pos’ only positive
values will be considered. If ‘neg’ only negative values will
be considered. If ‘abs’ absolute values will be considered.
Defaults to ‘abs’.
If True, raise an error if values are all positive when detecting
a minimum (mode=’neg’), or all negative when detecting a maximum
(mode=’pos’). Defaults to True.
Either 'accurate' or 'fast', determines the quality of the
Legendre polynomial expansion used for interpolation of channels
using the minimum-norm method.
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.
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.
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.
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.
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.
The channel names given are assumed to be a set, i.e. the order
does not matter. The original order of the channels is preserved.
You can use reorder_channels to set channel order if necessary.
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.
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.
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).
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).
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.
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.
Y-axis limits for plots (after scaling has been applied). dict
keys should match channel types; valid keys are for instance eeg, mag,
grad, misc, csd, .. (example: ylim=dict(eeg=[-20,20])). If
None, the y-axis limits will be set automatically by matplotlib. Defaults to
None.
If true SSP projections are applied before display. If 'interactive',
a check box for reversible selection of SSP projection vectors will
be shown. If 'reconstruct', projection vectors will be applied and then
M/EEG data will be reconstructed via field mapping to reduce the signal
bias caused by projection.
Changed in version 0.21: Support for ‘reconstruct’ was added.
The axes to plot to. If list, the list must be a list of Axes of
the same length as the number of channel types. If instance of
Axes, there must be only one channel type plotted.
Plot the global field power (GFP) or the root mean square (RMS) of the
data. For MEG data, this will plot the RMS. For EEG, it plots GFP,
i.e. the standard deviation of the signal across channels. The GFP is
equivalent to the RMS of an average-referenced signal.
True
Plot GFP or RMS (for EEG and MEG, respectively) and traces for all
channels.
'only'
Plot GFP or RMS (for EEG and MEG, respectively), and omit the
traces for individual channels.
The color of the GFP/RMS trace will be green if
spatial_colors=False, and black otherwise.
Changed in version 0.23: Plot GFP for EEG instead of RMS. Label RMS traces correctly as such.
If True, the lines are color coded by mapping physical sensor
coordinates into color values. Spatially similar channels will have
similar colors. Bad channels will be dotted. If False, the good
channels are plotted black and bad channels red. If 'auto', uses
True if channel locations are present, and False if channel locations
are missing or if the data contains only a single channel. Defaults to
'auto'.
Which channels to put in the front or back. Only matters if
spatial_colors is used.
If str, must be std or unsorted (defaults to unsorted). If
std, data with the lowest standard deviation (weakest effects) will
be put in front so that they are not obscured by those with stronger
effects. If unsorted, channels are z-sorted as in the evoked
instance.
If callable, must take one argument: a numpy array of the same
dimensionality as the evoked raw data; and return a list of
unique integers corresponding to the number of channels.
Whether to use interactive features. If True (default), it is possible
to paint an area to draw topomaps. When False, the interactive features
are disabled. Disabling interactive features reduces memory consumption
and is useful when using axes parameter to draw multiaxes figures.
Noise covariance used to whiten the data while plotting.
Whitened data channel names are shown in italic.
Can be a string to load a covariance from disk.
See also mne.Evoked.plot_white() for additional inspection
of noise covariance properties when whitening evoked data.
For data processed with SSS, the effective dependence between
magnetometers and gradiometers may introduce differences in scaling,
consider using mne.Evoked.plot_white().
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.
Segments of the data to highlight by means of a light-yellow
background color. Can be used to put visual emphasis on certain
time periods. The time periods must be specified as array-like
objects in the form of (t_start,t_end) in the unit given by the
time_unit parameter.
Multiple time periods can be specified by passing an array-like
object of individual time periods (e.g., for 3 time periods, the shape
of the passed object would be (3,2). If None, no highlighting
is applied.
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.
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.
Maximum intensity. Can be a dictionary with two entries "eeg" and "meg"
to specify separate values for EEG and MEG fields respectively. Can be
None to use the maximum value of the data.
New in v0.21.
New in v1.4: vmax can be a dictionary to specify separate values for EEG and
MEG fields.
Opacity of the meshes (between 0 and 1). Can be a dictionary with two
entries "eeg" and "meg" to specify separate values for EEG and
MEG fields respectively. Can be None to use 1.0 when a single field
map is shown, or dict(eeg=1.0,meg=0.5) when both field maps are shown.
Interpolation method (scipy.interpolate.interp1d parameter).
Must be one of 'linear', 'nearest', 'zero', 'slinear',
'quadratic' or 'cubic'.
New in v1.6.
interaction‘trackball’ | ‘terrain’
How interactions with the scene via an input device (e.g., mouse or
trackpad) modify the camera position. If 'terrain', one axis is
fixed, enabling “turntable-style” rotations. If 'trackball',
movement along all axes is possible, which provides more freedom of
movement, but you may incidentally perform unintentional rotations along
some axes.
Defaults to 'terrain'.
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.
Without the time viewer active, the figure is returned. With the time
viewer active, an object is returned that can be used to control
different aspects of the figure.
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.
This parameter can also be used to set the order the channels
are shown in, as the channel image is sorted by the order of picks.
Color limits for plots (after scaling has been applied). e.g.
clim=dict(eeg=[-20,20]).
Valid keys are eeg, mag, grad, misc. If None, the clim parameter
for each channel equals the pyplot default.
The axes to plot to. If list, the list must be a list of Axes of
the same length as the number of channel types. If instance of
Axes, there must be only one channel type plotted.
If group_by is a dict, this cannot be a list, but it can be a dict
of lists of axes, with the keys matching those of group_by. In that
case, the provided axes will be used for the corresponding groups.
Defaults to None.
Colormap. If tuple, the first value indicates the colormap to use and
the second value is a boolean defining interactivity. In interactive
mode the colors are adjustable by clicking and dragging the colorbar
with left and right mouse button. Left mouse button moves the scale up
and down and right mouse button adjusts the range. Hitting space bar
resets the scale. Up and down arrows can be used to change the
colormap. If ‘interactive’, translates to ('RdBu_r',True).
Defaults to 'RdBu_r'.
An array of booleans of the same shape as the data. Entries of the
data that correspond to False in the mask are masked (see
do_mask below). Useful for, e.g., masking for statistical
significance.
If mask is not None: if ‘contour’, a contour line is drawn around
the masked areas (True in mask). If ‘mask’, entries not
True in mask are shown transparently. If ‘both’, both a contour
and transparency are used.
If None, defaults to ‘both’ if mask is not None, and is ignored
otherwise.
The colormap chosen for masked parts of the image (see below), if
mask is not None. If None, cmap is reused. Defaults to
Greys. Not interactive. Otherwise, as cmap.
A float between 0 and 1. If mask is not None, this sets the
alpha level (degree of transparency) for the masked-out segments.
I.e., if 0, masked-out segments are not visible at all.
Defaults to .25.
Determines if channel names should be plotted on the y axis. If False,
no names are shown. If True, ticks are set automatically by matplotlib
and the corresponding channel names are shown. If “all”, all channel
names are shown. If “auto”, is set to False if picks is None,
to True if picks contains 25 or more entries, or to “all”
if picks contains fewer than 25 entries.
If a dict, the values must be picks, and axes must also be a dict
with matching keys, or None. If axes is None, one figure and one
axis will be created for each entry in group_by.Then, for each
entry, the picked channels will be plotted to the corresponding axis.
If titles are None, keys will become plot titles. This is useful
for e.g. ROIs. Each entry must contain only one channel type.
For example:
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.
Plot evoked data as butterfly plot and add topomaps for time points.
Note
Axes to plot in can be passed by the user through ts_args or
topomap_args. In that case both ts_args and
topomap_args axes have to be used. Be aware that when the
axes are provided, their position may be slightly modified.
The time point(s) to plot. If "auto", 5 evenly spaced topographies
between the first and last time instant will be shown. If "peaks",
finds time points automatically by checking for 3 local maxima in
Global Field Power. Defaults to "peaks".
The title. If None, suppress printing channel type title. If an
empty string, a default title is created. Defaults to ‘’. If custom
axes are passed make sure to set title=None, otherwise some of your
axes may be removed during placement of the title axis.
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.
A dict of kwargs that are forwarded to mne.Evoked.plot() to
style the butterfly plot. If they are not in this dict, the following
defaults are passed: spatial_colors=True, zorder='std'.
show and exclude are illegal.
If None, no customizable arguments will be passed.
Defaults to None.
A dict of kwargs that are forwarded to
mne.Evoked.plot_topomap() to style the topomaps.
If it is not in this dict, outlines='head' will be passed.
show, times, colorbar are illegal.
If None, no customizable arguments will be passed.
Defaults to None.
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.
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.
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
lambdax:x.replace('MEG',''). If mask is not None, only
non-masked sensor names will be shown.
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.
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.
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.
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.
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 NumPyarray 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).
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.
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.
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.
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.
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.
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'.
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.
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.
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).
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.
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.
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().
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).
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).
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.
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.
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).
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., {'presentationrate':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:
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.
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.
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.
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
lambdax:x.replace('MEG',''). If mask is not None, only
non-masked sensor names will be shown.
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.
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.
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.
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.
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.
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 NumPyarray 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).
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.
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'.
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.
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.
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().
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’.
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.
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.
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.
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.
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.
Layout instance specifying sensor positions (does not need to
be specified for Neuromag data). If possible, the correct layout is
inferred from the data.
Y-axis limits for plots (after scaling has been applied). dict
keys should match channel types; valid keys are for instance eeg, mag,
grad, misc, csd, .. (example: ylim=dict(eeg=[-20,20])). If
None, the y-axis limits will be set automatically by matplotlib. Defaults to
None.
If True, create a legend based on evoked.comment. If False, disable the
legend. Otherwise, the legend is created and the parameter value is
passed as the location parameter to the matplotlib legend call. It can
be an integer (e.g. 0 corresponds to upper right corner of the plot),
a string (e.g. 'upperright'), or a tuple (x, y coordinates of the
lower left corner of the legend in the axes coordinate system).
See matplotlib documentation for more details.
Noise covariance used to whiten the data while plotting.
Whitened data channel names are shown in italic.
Can be a string to load a covariance from disk.
The time point(s) to plot. If “auto”, the number of axes determines
the amount of time point(s). If axes is also None, at most 10
topographies will be shown with a regular time spacing between the
first and last time instant. If “peaks”, finds time points
automatically by checking for local maxima in global field power. If
“interactive”, the time can be set interactively at run-time by using a
slider.
The time window (in seconds) around a given time point to be used for
averaging. For example, 0.2 would translate into a time window that
starts 0.1 s before and ends 0.1 s after the given time point. If the
time window exceeds the duration of the data, it will be clipped.
Different time windows (one per time point) can be provided by
passing an array-like object (e.g., [0.1,0.2,0.3]). If
None (default), no averaging will take place.
Changed in version 1.1: Support for array-like input.
The channel type to plot. For 'grad', the gradiometers are
collected in pairs and the RMS for each pair is plotted. If
None the first available channel type from order shown above is used. Defaults to None.
If true SSP projections are applied before display. If 'interactive',
a check box for reversible selection of SSP projection vectors will
be shown. If 'reconstruct', projection vectors will be applied and then
M/EEG data will be reconstructed via field mapping to reduce the signal
bias caused by projection.
Changed in version 0.21: Support for ‘reconstruct’ was added.
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.
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
lambdax:x.replace('MEG',''). If mask is not None, only
non-masked sensor names will be shown.
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.
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.
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.
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.18.
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.
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.
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 NumPyarray 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).
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.
The units to use for the colorbar label. Ignored if colorbar=False.
If None and scalings=None the unit is automatically determined, otherwise the label will be “AU” indicating arbitrary units.
Default is 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 times provided (unless times is None). Default is None.
String format for topomap values. Defaults (None) to “%01d ms” if
time_unit='ms', “%0.3f s” if time_unit='s', and
“%g” otherwise. Can be an empty string to omit the time label.
The number of rows and columns of topographies to plot. If either nrows
or ncols is 'auto', the necessary number will be inferred. Defaults
to nrows=1,ncols='auto'. Ignored when times == ‘interactive’.
When existing axes are provided and colorbar=True, note that the
colorbar scale will only accurately reflect topomaps that are generated in
the same call as the colorbar. Note also that the colorbar will not be
resized automatically when axes are provided; use Matplotlib’s
axes.set_position() method or
gridspec interface to adjust the colorbar
size yourself.
When time=="interactive", the figure will publish and subscribe to the
following UI events:
Plots the whitened evoked response and the whitened GFP as described in
[5]. This function is especially useful for
investigating noise covariance properties to determine if data are
properly whitened (e.g., achieving expected values in line with model
assumptions, see Notes below).
This controls the rank computation that can be read from the
measurement info or estimated from the data. When a noise covariance
is used for whitening, this should reflect the rank of that covariance,
otherwise amplification of noise components can occur in whitening (e.g.,
often during source localization).
The rank will be estimated from the data after proper scaling of
different channel types.
'info'
The rank is inferred from info. If data have been processed
with Maxwell filtering, the Maxwell filtering header is used.
Otherwise, the channel counts themselves are used.
In both cases, the number of projectors is subtracted from
the (effective) number of channels in the data.
For example, if Maxwell filtering reduces the rank to 68, with
two projectors the returned value will be 66.
'full'
The rank is assumed to be full, i.e. equal to the
number of good channels. If a Covariance is passed, this can
make sense if it has been (possibly improperly) regularized without
taking into account the true data rank.
Calculate the rank only for a subset of channel types, and explicitly
specify the rank for the remaining channel types. This can be
extremely useful if you already know the rank of (part of) your
data, for instance in case you have calculated it earlier.
This parameter must be a dictionary whose keys correspond to
channel types in the data (e.g. 'meg', 'mag', 'grad',
'eeg'), and whose values are integers representing the
respective ranks. For example, {'mag':90,'eeg':45} will assume
a rank of 90 and 45 for magnetometer data and EEG data,
respectively.
The ranks for all channel types present in the data, but
not specified in the dictionary will be estimated empirically.
That is, if you passed a dataset containing magnetometer, gradiometer,
and EEG data together with the dictionary from the previous example,
only the gradiometer rank would be determined, while the specified
magnetometer and EEG ranks would be taken for granted.
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.
If True, the lines are color coded by mapping physical sensor
coordinates into color values. Spatially similar channels will have
similar colors. Bad channels will be dotted. If False, the good
channels are plotted black and bad channels red. If 'auto', uses
True if channel locations are present, and False if channel locations
are missing or if the data contains only a single channel. Defaults to
'auto'.
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.
If baseline signals match the assumption of Gaussian white noise,
values should be centered at 0, and be within 2 standard deviations
(±1.96) for 95% of the time points. For the global field power (GFP),
we expect it to fluctuate around a value of 1.
If one single covariance object is passed, the GFP panel (bottom)
will depict different sensor types. If multiple covariance objects are
passed as a list, the left column will display the whitened evoked
responses for each channel based on the whitener from the noise covariance
that has the highest log-likelihood. The left column will depict the
whitened GFPs based on each estimator separately for each sensor type.
Instead of numbers of channels the GFP display shows the estimated rank.
Note. The rank estimation will be printed by the logger
(if verbose=True) for each noise covariance estimator that is passed.
References
[1]
Engemann D. and Gramfort A. (2015) Automated model selection in
covariance estimation and spatial whitening of MEG and EEG
signals, vol. 108, 328-342, NeuroImage.
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.
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".
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().
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.
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.
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
To write multiple conditions into a single file, use
mne.write_evokeds.
Changed in version 0.23: Information on baseline correction will be stored with the data,
and will be restored when reading again via mne.read_evokeds.
Approximate high cut-off frequency in Hz. Note that this
is not an exact cutoff, since Savitzky-Golay filtering
[6] 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.
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.
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.
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.
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 [7].
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
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).
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.
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.
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.
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.
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'].
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.
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.
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.
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.
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()
The (absolute or relative) time shift in seconds. If relative
is True, positive tshift increases the time value associated with
each sample, while negative tshift decreases it.
If True, increase or decrease time values by tshift seconds.
Otherwise, shift the time values such that the time of the first
sample equals tshift.
Returns:
epochsMNE-object
The modified instance.
Notes
This method allows you to shift the time values associated with each
data sample by an arbitrary amount. It does not resample the signal
or change the data values in any way.
Export data in tabular structure as a pandas DataFrame.
Channels are converted to columns in the DataFrame. By default,
an additional column “time” is added, unless index='time'
(in which case time values form the DataFrame’s index).
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.
Kind of index to use for the DataFrame. If None, a sequential
integer index (pandas.RangeIndex) will be used. If 'time', a
pandas.Index or pandas.TimedeltaIndex will be used
(depending on the value of time_format).
Defaults to None.
Scaling factor applied to the channels picked. If None, defaults to
dict(eeg=1e6,mag=1e15,grad=1e13) — i.e., converts EEG to µV,
magnetometers to fT, and gradiometers to fT/cm.
If True, the DataFrame is returned in long format where each row is one
observation of the signal at a unique combination of time point and channel.
For convenience, a ch_type column is added to facilitate subsetting the resulting DataFrame. Defaults to False.
Desired time format. If None, no conversion is applied, and time values
remain as float values in seconds. If 'ms', time values will be rounded
to the nearest millisecond and converted to integers. If 'timedelta',
time values will be converted to pandas.Timedelta values.
Default is None.
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.