mne.preprocessing.find_bad_channels_maxwell¶
- mne.preprocessing.find_bad_channels_maxwell(raw, limit=7.0, duration=5.0, min_count=5, return_scores=False, origin='auto', int_order=8, ext_order=3, calibration=None, cross_talk=None, coord_frame='head', regularize='in', ignore_ref=False, bad_condition='error', head_pos=None, mag_scale=100.0, skip_by_annotation=('edge', 'bad_acq_skip'), h_freq=40.0, extended_proj=(), verbose=None)[source]¶
Find bad channels using Maxwell filtering.
- Parameters
- rawinstance of
Raw
Raw data to process.
- limit
float
Detection limit for noisy segments (default is 7.). Smaller values will find more bad channels at increased risk of including good ones. This value can be interpreted as the standard score of differences between the original and Maxwell-filtered data. See the
Notes
section for details.Note
This setting only concerns noisy channel detection. The limit for flat channel detection currently cannot be controlled by the user. Flat channel detection is always run before noisy channel detection.
- duration
float
Duration of the segments into which to slice the data for processing, in seconds. Default is 5.
- min_count
int
Minimum number of times a channel must show up as bad in a chunk. Default is 5.
- return_scoresbool
If
True
, return a dictionary with scoring information for each evaluated segment of the data. Default isFalse
.Warning
This feature is experimental and may change in a future version of MNE-Python without prior notice. Please report any problems and enhancement proposals to the developers.
New in version 0.21.
- originarray_like, shape (3,) |
str
Origin of internal and external multipolar moment space in meters. The default is
'auto'
, which means(0., 0., 0.)
whencoord_frame='meg'
, and a head-digitization-based origin fit usingfit_sphere_to_headshape()
whencoord_frame='head'
. If automatic fitting fails (e.g., due to having too few digitization points), consider separately calling the fitting function with different options or specifying the origin manually.- int_order
int
Order of internal component of spherical expansion.
- ext_order
int
Order of external component of spherical expansion.
- calibration
str
|None
Path to the
'.dat'
file with fine calibration coefficients. File can have 1D or 3D gradiometer imbalance correction. This file is machine/site-specific.- cross_talk
str
|None
Path to the FIF file with cross-talk correction information.
- coord_frame
str
The coordinate frame that the
origin
is specified in, either'meg'
or'head'
. For empty-room recordings that do not have a head<->meg transforminfo['dev_head_t']
, the MEG coordinate frame should be used.- regularize
str
|None
Basis regularization type, must be “in” or None. “in” is the same algorithm as the “-regularize in” option in MaxFilter™.
- ignore_refbool
If True, do not include reference channels in compensation. This option should be True for KIT files, since Maxwell filtering with reference channels is not currently supported.
- bad_condition
str
How to deal with ill-conditioned SSS matrices. Can be “error” (default), “warning”, “info”, or “ignore”.
- head_pos
array
|None
If array, movement compensation will be performed. The array should be of shape (N, 10), holding the position parameters as returned by e.g.
read_head_pos
.- mag_scale
float
|str
The magenetometer scale-factor used to bring the magnetometers to approximately the same order of magnitude as the gradiometers (default 100.), as they have different units (T vs T/m). Can be
'auto'
to use the reciprocal of the physical distance between the gradiometer pickup loops (e.g., 0.0168 m yields 59.5 for VectorView).- skip_by_annotation
str
|list
ofstr
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 bymne.concatenate_raws()
ormne.io.Raw.append()
, or separated during acquisition. To disable, provide an empty list.- h_freq
float
|None
The cutoff frequency (in Hz) of the low-pass filter that will be applied before processing the data. This defaults to
40.
, which should provide similar results to MaxFilter. If you do not wish to apply a filter, set this toNone
.- extended_proj
list
The empty-room projection vectors used to extend the external SSS basis (i.e., use eSSS).
New in version 0.21.
- verbosebool,
str
,int
, orNone
If not None, override default verbose level (see
mne.verbose()
and Logging documentation for more). If used, it should be passed as a keyword-argument only.
- rawinstance of
- Returns
- noisy_chs
list
List of bad MEG channels that were automatically detected as being noisy among the good MEG channels.
- flat_chs
list
List of MEG channels that were detected as being flat in at least
min_count
segments.- scores
dict
A dictionary with information produced by the scoring algorithms. Only returned when
return_scores
isTrue
. It contains the following keys:ch_names
ndarray, shape (n_meg,)The names of the MEG channels. Their order corresponds to the order of rows in the
scores
andlimits
arrays.
ch_types
ndarray, shape (n_meg,)The types of the MEG channels in
ch_names
('mag'
,'grad'
).
bins
ndarray, shape (n_windows, 2)The inclusive window boundaries (start and stop; in seconds) used to calculate the scores.
scores_flat
ndarray, shape (n_meg, n_windows)The scores for testing whether MEG channels are flat. These values correspond to the standard deviation of a segment. See the
Notes
section for details.
limits_flat
ndarray, shape (n_meg, 1)The score thresholds (in standard deviation) above which a segment was classified as “flat”.
scores_noisy
ndarray, shape (n_meg, n_windows)The scores for testing whether MEG channels are noisy. These values correspond to the standard score of a segment. See the
Notes
section for details.
limits_noisy
ndarray, shape (n_meg, 1)The score thresholds (in standard scores) above which a segment was classified as “noisy”.
Note
The scores and limits for channels marked as
bad
in the input data will be set tonp.nan
.
- noisy_chs
See also
Notes
All arguments after
raw
,limit
,duration
,min_count
, andreturn_scores
are the same asmaxwell_filter()
, except that the following are not allowed in this function because they are unused:st_duration
,st_correlation
,destination
,st_fixed
, andst_only
.This algorithm, for a given chunk of data:
Runs SSS on the data, without removing external components.
Excludes channels as flat that have had low variability (standard deviation < 0.01 fT or fT/cm in a 30 ms window) in the given or any previous chunk.
For each channel \(k\), computes the range or peak-to-peak \(d_k\) of the difference between the reconstructed and original data.
Computes the average \(\mu_d\) and standard deviation \(\sigma_d\) of the differences (after scaling magnetometer data to roughly match the scale of the gradiometer data using
mag_scale
).Marks channels as bad for the chunk when \(d_k > \mu_d + \textrm{limit} \times \sigma_d\). Note that this expression can be easily transformed into \((d_k - \mu_d) / \sigma_d > \textrm{limit}\), which is equivalent to \(z(d_k) > \textrm{limit}\), with \(z(d_k)\) being the standard or z-score of the difference.
Data are processed in chunks of the given
duration
, and channels that are bad for at leastmin_count
chunks are returned.Channels marked as flat in step 2 are excluded from all subsequent steps of noisy channel detection.
This algorithm gives results similar to, but not identical with, MaxFilter. Differences arise because MaxFilter processes on a buffer-by-buffer basis (using buffer-size-dependent downsampling logic), uses different filtering characteristics, and possibly other factors. Channels that are near the
limit
for a givenmin_count
are particularly susceptible to being different between the two implementations.New in version 0.20.