The raw filename to load. For files that have automatically been split,
the split part will be automatically loaded. Filenames not ending with
raw.fif, raw_sss.fif, raw_tsss.fif, _meg.fif,
_eeg.fif, or _ieeg.fif (with or without an optional additional
.gz extension) will generate a warning. If a file-like object is
provided, preloading must be used.
Changed in version 0.18: Support for file-like objects.
If True, allow loading of data that has been recorded with internal
active compensation (MaxShield). Data recorded with MaxShield should
generally not be loaded directly, but should first be processed using
SSS/tSSS to remove the compensation signals that may also affect brain
activity. Can also be “yes” to load without eliciting a warning.
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).
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.
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.
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.
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.
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.
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()).
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.
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.
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.
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.
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.
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
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'.
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.
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.
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.
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.
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.
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).
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.
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.
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.
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.
EEGFz or MISCE), 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).
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.
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.
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.
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.
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.
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.
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.
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.
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.
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']=[].
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.
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.
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.
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.
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().
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.
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”.
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'.
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.
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.
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’.
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'.
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:
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).
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.
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).
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.
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.
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.
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'.
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 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().
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.
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'.
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.
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().
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.
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.
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.
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 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_covisnotNone) 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’.
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.
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.
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.
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 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).
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 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().
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.
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'.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 [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
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()
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 is not None
(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, pandas.DatetimeIndex, 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. If 'datetime', time values will be converted to pandas.Timestamp values, relative to raw.info['meas_date'] and offset by raw.first_samp.
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.