Data decomposition using Independent Component Analysis (ICA).
This object estimates independent components from mne.io.Raw
,
mne.Epochs
, or mne.Evoked
objects. Components can
optionally be removed (for artifact repair) prior to signal reconstruction.
Warning
ICA is sensitive to low-frequency drifts and therefore requires the data to be high-pass filtered prior to fitting. Typically, a cutoff frequency of 1 Hz is recommended.
int
| float
| None
Number of principal components (from the pre-whitening PCA step) that are passed to the ICA algorithm during fitting:
int
Must be greater than 1 and less than or equal to the number of channels.
float
between 0 and 1 (exclusive)Will select the smallest number of components required to explain
the cumulative variance of the data greater than n_components
.
Consider this hypothetical example: we have 3 components, the first
explaining 70%, the second 20%, and the third the remaining 10%
of the variance. Passing 0.8 here (corresponding to 80% of
explained variance) would yield the first two components,
explaining 90% of the variance: only by using both components the
requested threshold of 80% explained variance can be exceeded. The
third component, on the other hand, would be excluded.
None
0.999999
will be used. This is done to avoid numerical
stability problems when whitening, particularly when working with
rank-deficient data.
Defaults to None
. The actual number used when executing the
ICA.fit()
method will be stored in the attribute
n_components_
(note the trailing underscore).
Changed in version 0.22: For a float
, the number of components will account
for greater than the given variance level instead of less than or
equal to it. The default (None) will also take into account the
rank deficiency of the data.
None
| instance of Covariance
Noise covariance used for pre-whitening. If None (default), channels are scaled to unit variance (“z-standardized”) as a group by channel type prior to the whitening by PCA.
None
| int
| instance of RandomState
A seed for the NumPy random number generator (RNG). If None
(default),
the seed will be obtained from the operating system
(see RandomState
for details), meaning it will most
likely produce different output every time this function or method is run.
To achieve reproducible results, pass a value here to explicitly initialize
the RNG with a defined state.
The ICA method to use in the fit method. Use the fit_params
argument
to set additional parameters. Specifically, if you want Extended
Infomax, set method='infomax'
and fit_params=dict(extended=True)
(this also works for method='picard'
). Defaults to 'fastica'
.
For reference, see [1][2][3][4].
dict
| None
Additional parameters passed to the ICA estimator as specified by
method
. Allowed entries are determined by the various algorithm
implementations: see FastICA
,
picard()
, infomax()
.
int
| ‘auto’Maximum number of iterations during fit. If 'auto'
, it
will set maximum iterations to 1000
for 'fastica'
and to 500
for 'infomax'
or 'picard'
. The actual number of
iterations it took ICA.fit()
to complete will be stored in the
n_iter_
attribute.
Allow ICA on MEG reference channels. Defaults to False.
New in version 0.18.
str
| int
| None
Control verbosity of the logging output. If None
, use the default
verbosity level. See the logging documentation and
mne.verbose()
for details. Should only be passed as a keyword
argument.
Notes
Changed in version 0.23: Version 0.23 introduced the max_iter='auto'
settings for maximum
iterations. With version 0.24 'auto'
will be the new
default, replacing the current max_iter=200
.
Changed in version 0.23: Warn if Epochs
were baseline-corrected.
Note
If you intend to fit ICA on Epochs
, it is recommended to
high-pass filter, but not baseline correct the data for good
ICA performance. A warning will be emitted otherwise.
A trailing _
in an attribute name signifies that the attribute was
added to the object during fitting, consistent with standard scikit-learn
practice.
ICA fit()
in MNE proceeds in two steps:
Whitening the data by means of a pre-whitening step
(using noise_cov
if provided, or the standard deviation of each
channel type) and then principal component analysis (PCA).
Passing the n_components
largest-variance components to the ICA
algorithm to obtain the unmixing matrix (and by pseudoinversion, the
mixing matrix).
ICA apply()
then:
Unmixes the data with the unmixing_matrix_
.
Includes ICA components based on ica.include
and ica.exclude
.
Re-mixes the data with mixing_matrix_
.
Restores any data not passed to the ICA algorithm, i.e., the PCA
components between n_components
and n_pca_components
.
n_pca_components
determines how many PCA components will be kept when
reconstructing the data when calling apply()
. This parameter can be
used for dimensionality reduction of the data, or dealing with low-rank
data (such as those with projections, or MEG data processed by SSS). It is
important to remove any numerically-zero-variance components in the data,
otherwise numerical instability causes problems when computing the mixing
matrix. Alternatively, using n_components
as a float will also avoid
numerical stability problems.
The n_components
parameter determines how many components out of
the n_channels
PCA components the ICA algorithm will actually fit.
This is not typically used for EEG data, but for MEG data, it’s common to
use n_components < n_channels
. For example, full-rank
306-channel MEG data might use n_components=40
to find (and
later exclude) only large, dominating artifacts in the data, but still
reconstruct the data using all 306 PCA components. Setting
n_pca_components=40
, on the other hand, would actually reduce the
rank of the reconstructed data to 40, which is typically undesirable.
If you are migrating from EEGLAB and intend to reduce dimensionality via
PCA, similarly to EEGLAB’s runica(..., 'pca', n)
functionality,
pass n_components=n
during initialization and then
n_pca_components=n
during apply()
. The resulting reconstructed
data after apply()
will have rank n
.
Note
Commonly used for reasons of i) computational efficiency and ii) additional noise reduction, it is a matter of current debate whether pre-ICA dimensionality reduction could decrease the reliability and stability of the ICA, at least for EEG data and especially during preprocessing [5]. (But see also [6] for a possibly confounding effect of the different whitening/sphering methods used in this paper (ZCA vs. PCA).) On the other hand, for rank-deficient data such as EEG data after average reference or interpolation, it is recommended to reduce the dimensionality (by 1 for average reference and 1 for each interpolated channel) for optimal ICA performance (see the EEGLAB wiki).
Caveat! If supplying a noise covariance, keep track of the projections available in the cov or in the raw object. For example, if you are interested in EOG or ECG artifacts, EOG and ECG projections should be temporally removed before fitting ICA, for example:
>> projs, raw.info['projs'] = raw.info['projs'], []
>> ica.fit(raw)
>> raw.info['projs'] = projs
Methods currently implemented are FastICA (default), Infomax, and Picard.
Standard Infomax can be quite sensitive to differences in floating point
arithmetic. Extended Infomax seems to be more stable in this respect,
enhancing reproducibility and stability of results; use Extended Infomax
via method='infomax', fit_params=dict(extended=True)
. Allowed entries
in fit_params
are determined by the various algorithm implementations:
see FastICA
, picard()
,
infomax()
.
Note
Picard can be used to solve the same problems as FastICA,
Infomax, and extended Infomax, but typically converges faster
than either of those methods. To make use of Picard’s speed while
still obtaining the same solution as with other algorithms, you
need to specify method='picard'
and fit_params
as a
dictionary with the following combination of keys:
dict(ortho=False, extended=False)
for Infomax
dict(ortho=False, extended=True)
for extended Infomax
dict(ortho=True, extended=True)
for FastICA
Reducing the tolerance (set in fit_params
) speeds up estimation at the
cost of consistency of the obtained results. It is difficult to directly
compare tolerance levels between Infomax and Picard, but for Picard and
FastICA a good rule of thumb is tol_fastica == tol_picard ** 2
.
References
str
Flag informing about which data type (raw or epochs) was used for the fit.
Channel names resulting from initial picking.
int
If fit, the actual number of PCA components used for ICA decomposition.
ndarray
, shape (n_channels, 1) or (n_channels, n_channels)If fit, array used to pre-whiten the data prior to PCA.
ndarray
, shape (n_channels, n_channels)
If fit, the PCA components.
ndarray
, shape (n_channels,)If fit, the mean vector used to center the data before doing the PCA.
ndarray
, shape (n_channels,)
If fit, the variance explained by each PCA component.
ndarray
, shape (n_components_, n_components_)
If fit, the whitened mixing matrix to go back from ICA space to PCA
space.
It is, in combination with the pca_components_
, used by
ICA.apply()
and ICA.get_components()
to re-mix/project
a subset of the ICA components into the observed channel space.
The former method also removes the pre-whitening (z-scaling) and the
de-meaning.
ndarray
, shape (n_components_, n_components_)
If fit, the whitened matrix to go from PCA space to ICA space.
Used, in combination with the pca_components_
, by the methods
ICA.get_sources()
and ICA.apply()
to unmix the observed
data.
int
List or np.array of sources indices to exclude when re-mixing the data
in the ICA.apply()
method, i.e. artifactual ICA components.
The components identified manually and by the various automatic
artifact detection methods should be (manually) appended
(e.g. ica.exclude.extend(eog_inds)
).
(There is also an exclude
parameter in the ICA.apply()
method.) To scrap all marked components, set this attribute to an empty
list.
mne.Info
| None
The mne.Info
object with information about the sensors and methods of measurement.
int
The number of samples used on fit.
dict
A dictionary of independent component indices, grouped by types of independent components. This attribute is set by some of the artifact detection functions.
int
If fit, the number of iterations required to complete ICA.
Methods
|
Check channel type membership. |
|
Remove selected components from the signal. |
|
Copy the ICA object. |
|
Detect ECG related components. |
|
Detect EOG related components using correlation. |
|
Detect muscle related components. |
|
Detect MEG reference related components using correlation. |
|
Run the ICA decomposition on raw data. |
|
Get a list of channel type for each channel. |
Get ICA topomap for components as numpy arrays. |
|
|
Estimate sources given the unmixing matrix. |
|
Project mixing matrix on interpolated sensor topography. |
|
Overlay of raw and cleaned signals given the unmixing matrix. |
|
Display component properties. |
|
Plot scores related to detected components. |
|
Plot estimated latent sources given the unmixing matrix. |
|
Store ICA solution into a fiff file. |
|
Assign score to components based on statistic or metric. |
Check channel type membership.
str
Channel type to check for. Can be e.g. ‘meg’, ‘eeg’, ‘stim’, etc.
Whether or not the instance contains the given channel type.
Examples
Channel type membership can be tested as:
>>> 'meg' in inst
True
>>> 'seeg' in inst
False
Remove selected components from the signal.
Given the unmixing matrix, transform the data, zero out all excluded components, and inverse-transform the data. This procedure will reconstruct M/EEG signals from which the dynamics described by the excluded components is subtracted.
Raw
, Epochs
or Evoked
The data to be processed (i.e., cleaned). It will be modified in-place.
int
The indices referring to columns in the ummixing matrix. The
components to be kept. If None
(default), all components
will be included (minus those defined in ica.exclude
and the exclude
parameter, see below).
int
The indices referring to columns in the ummixing matrix. The
components to be zeroed out. If None
(default) or an
empty list, only components from ica.exclude
will be
excluded. Else, the union of exclude
and ica.exclude
will be excluded.
int
| float
| None
The number of PCA components to be kept, either absolute (int)
or fraction of the explained variance (float). If None (default),
the ica.n_pca_components
from initialization will be used in 0.22;
in 0.23 all components will be used.
int
| float
| None
First sample to include. If float, data will be interpreted as time in seconds. If None, data will be used from the first sample.
int
| float
| None
Last sample to not include. If float, data will be interpreted as time in seconds. If None, data will be used to the last sample.
str
| int
| None
Control verbosity of the logging output. If None
, use the default
verbosity level. See the logging documentation and
mne.verbose()
for details. Should only be passed as a keyword
argument.
Notes
Note
Applying ICA may introduce a DC shift. If you pass
baseline-corrected Epochs
or Evoked
data,
the baseline period of the cleaned data may not be of
zero mean anymore. If you require baseline-corrected
data, apply baseline correction again after cleaning
via ICA. A warning will be emitted to remind you of this
fact if you pass baseline-corrected data.
Changed in version 0.23: Warn if instance was baseline-corrected.
Examples using apply
:
Overview of MEG/EEG analysis with MNE-Python
Find MEG reference channel artifacts
Removing muscle ICA components
The current gradient compensation grade.
Copy the ICA object.
ICA
The copied object.
Examples using copy
:
Find MEG reference channel artifacts
Detect ECG related components.
Cross-trial phase statistics [7] or Pearson correlation can be used for detection.
Note
If no ECG channel is available, routine attempts to create an artificial ECG based on cross-channel averaging.
Raw
, Epochs
or Evoked
Object to compute sources from.
str
The name of the channel to use for ECG peak detection. The argument is mandatory if the dataset contains no ECG channels.
float
| ‘auto’Value above which a feature is classified as outlier. See Notes.
Changed in version 0.21.
int
| float
| None
First sample to include. If float, data will be interpreted as time in seconds. If None, data will be used from the first sample. When working with Epochs or Evoked objects, must be float or None.
int
| float
| None
Last sample to not include. If float, data will be interpreted as time in seconds. If None, data will be used to the last sample. When working with Epochs or Evoked objects, must be float or None.
float
Low pass frequency.
float
High pass frequency.
The method used for detection. If 'ctps'
, cross-trial phase
statistics [7] are used to detect
ECG-related components. See Notes.
Whether to omit bad segments from the data before fitting. If True
(default), annotated segments whose description begins with 'bad'
are
omitted. If False
, no rejection based on annotations is performed.
New in version 0.14.0.
Which method to use for finding outliers among the components:
'zscore'
(default) is the iterative z-scoring method. This method
computes the z-score of the component’s scores and masks the components
with a z-score above threshold. This process is repeated until no
supra-threshold component remains.
'correlation'
is an absolute raw correlation threshold ranging from 0
to 1.
New in version 0.21.
str
| int
| None
Control verbosity of the logging output. If None
, use the default
verbosity level. See the logging documentation and
mne.verbose()
for details. Should only be passed as a keyword
argument.
list
of int
The indices of ECG-related components.
np.ndarray
of float
, shape (n_components_
)If method is ‘ctps’, the normalized Kuiper index scores. If method is ‘correlation’, the correlation scores.
See also
Notes
The threshold
, method
, and measure
parameters interact in
the following ways:
If method='ctps'
, threshold
refers to the significance value
of a Kuiper statistic, and threshold='auto'
will compute the
threshold automatically based on the sampling frequency.
If method='correlation'
and measure='correlation'
,
threshold
refers to the Pearson correlation value, and
threshold='auto'
sets the threshold to 0.9.
If method='correlation'
and measure='zscore'
, threshold
refers to the z-score value (i.e., standard deviations) used in the
iterative z-scoring method, and threshold='auto'
sets the
threshold to 3.0.
References
Examples using find_bads_ecg
:
Getting started with mne.Report
Detect EOG related components using correlation.
Detection is based on Pearson correlation between the filtered data and the filtered EOG channel. Thresholding is based on adaptive z-scoring. The above threshold components will be masked and the z-score will be recomputed until no supra-threshold component remains.
Raw
, Epochs
or Evoked
Object to compute sources from.
str
The name of the channel to use for EOG peak detection. The argument is mandatory if the dataset contains no EOG channels.
float
| str
Value above which a feature is classified as outlier.
If measure
is 'zscore'
, defines the threshold on the
z-score used in the iterative z-scoring method.
If measure
is 'correlation'
, defines the absolute
threshold on the correlation between 0 and 1.
If 'auto'
, defaults to 3.0 if measure
is 'zscore'
and
0.9 if measure
is 'correlation'
.
int
| float
| None
First sample to include. If float, data will be interpreted as time in seconds. If None, data will be used from the first sample.
int
| float
| None
Last sample to not include. If float, data will be interpreted as time in seconds. If None, data will be used to the last sample.
float
Low pass frequency.
float
High pass frequency.
Whether to omit bad segments from the data before fitting. If True
(default), annotated segments whose description begins with 'bad'
are
omitted. If False
, no rejection based on annotations is performed.
New in version 0.14.0.
Which method to use for finding outliers among the components:
'zscore'
(default) is the iterative z-scoring method. This method
computes the z-score of the component’s scores and masks the components
with a z-score above threshold. This process is repeated until no
supra-threshold component remains.
'correlation'
is an absolute raw correlation threshold ranging from 0
to 1.
New in version 0.21.
str
| int
| None
Control verbosity of the logging output. If None
, use the default
verbosity level. See the logging documentation and
mne.verbose()
for details. Should only be passed as a keyword
argument.
See also
Examples using find_bads_eog
:
Getting started with mne.Report
Detect muscle related components.
Detection is based on [8] which uses data from a subject who has been temporarily paralyzed [9]. The criteria are threefold: 1) Positive log-log spectral slope from 7 to 45 Hz 2) Peripheral component power (farthest away from the vertex) 3) A single focal point measured by low spatial smoothness
The threshold is relative to the slope, focal point and smoothness of a typical muscle-related ICA component. Note the high frequency of the power spectral density slope was 75 Hz in the reference but has been modified to 45 Hz as a default based on the criteria being more accurate in practice.
Raw
, Epochs
or Evoked
Object to compute sources from.
float
| str
Value above which a component should be marked as muscle-related, relative to a typical muscle component.
int
| float
| None
First sample to include. If float, data will be interpreted as time in seconds. If None, data will be used from the first sample.
int
| float
| None
Last sample to not include. If float, data will be interpreted as time in seconds. If None, data will be used to the last sample.
float
Low frequency for muscle-related power.
float
High frequency for msucle related power.
float
| array-like | instance of ConductorModel
| None
| ‘auto’ | ‘eeglab’The sphere parameters to use for the head outline. Can be array-like of
shape (4,) to give the X/Y/Z origin and radius in meters, or a single float
to give just the radius (origin assumed 0, 0, 0). Can also be an instance
of a spherical ConductorModel
to use the origin and
radius from that object. If 'auto'
the sphere is fit to digitization
points. If 'eeglab'
the head circle is defined by EEG electrodes
'Fpz'
, 'Oz'
, 'T7'
, and 'T8'
(if 'Fpz'
is not present,
it will be approximated from the coordinates of 'Oz'
). None
(the
default) is equivalent to 'auto'
when enough extra digitization points
are available, and (0, 0, 0, 0.095) otherwise. Currently the head radius
does not affect plotting.
New in version 0.20.
Changed in version 1.1: Added 'eeglab'
option.
str
| int
| None
Control verbosity of the logging output. If None
, use the default
verbosity level. See the logging documentation and
mne.verbose()
for details. Should only be passed as a keyword
argument.
See also
Notes
New in version 1.1.
Examples using find_bads_muscle
:
Removing muscle ICA components
Detect MEG reference related components using correlation.
Raw
, Epochs
or Evoked
Object to compute sources from. Should contain at least one channel i.e. component derived from MEG reference channels.
list
of str
Which MEG reference components to use. If None, then all channels that begin with REF_ICA.
float
| str
Value above which a feature is classified as outlier.
If measure
is 'zscore'
, defines the threshold on the
z-score used in the iterative z-scoring method.
If measure
is 'correlation'
, defines the absolute
threshold on the correlation between 0 and 1.
If 'auto'
, defaults to 3.0 if measure
is 'zscore'
and
0.9 if measure
is 'correlation'
.
Warning
If
method
is'together'
, the iterative z-score method is always used.
int
| float
| None
First sample to include. If float, data will be interpreted as time in seconds. If None, data will be used from the first sample.
int
| float
| None
Last sample to not include. If float, data will be interpreted as time in seconds. If None, data will be used to the last sample.
float
Low pass frequency.
float
High pass frequency.
Whether to omit bad segments from the data before fitting. If True
(default), annotated segments whose description begins with 'bad'
are
omitted. If False
, no rejection based on annotations is performed.
Method to use to identify reference channel related components.
Defaults to 'together'
. See notes.
New in version 0.21.
Which method to use for finding outliers among the components:
'zscore'
(default) is the iterative z-scoring method. This method
computes the z-score of the component’s scores and masks the components
with a z-score above threshold. This process is repeated until no
supra-threshold component remains.
'correlation'
is an absolute raw correlation threshold ranging from 0
to 1.
New in version 0.21.
str
| int
| None
Control verbosity of the logging output. If None
, use the default
verbosity level. See the logging documentation and
mne.verbose()
for details. Should only be passed as a keyword
argument.
See also
Notes
ICA decomposition on MEG reference channels is used to assess external magnetic noise and remove it from the MEG. Two methods are supported:
With the 'together'
method, only one ICA fit is used, which
encompasses both MEG and reference channels together. Components which
have particularly strong weights on the reference channels may be
thresholded and marked for removal.
With 'separate'
selected components from a separate ICA
decomposition on the reference channels are used as a ground truth for
identifying bad components in an ICA fit done on MEG channels only. The
logic here is similar to an EOG/ECG, with reference components
replacing the EOG/ECG channels. Recommended procedure is to perform ICA
separately on reference channels, extract them using
get_sources()
, and then append them to the
inst using add_channels()
, preferably with the prefix
REF_ICA
so that they can be automatically detected.
With 'together'
, thresholding is based on adaptative z-scoring.
With 'separate'
:
If measure
is 'zscore'
, thresholding is based on adaptative
z-scoring.
If measure
is 'correlation'
, threshold defines the absolute
threshold on the correlation between 0 and 1.
Validation and further documentation for this technique can be found in [10].
New in version 0.18.
References
Examples using find_bads_ref
:
Find MEG reference channel artifacts
Run the ICA decomposition on raw data.
Caveat! If supplying a noise covariance keep track of the projections available in the cov, the raw or the epochs object. For example, if you are interested in EOG or ECG artifacts, EOG and ECG projections should be temporally removed before fitting the ICA.
Raw
or Epochs
The data to be decomposed.
str
| list
| slice
| None
Channels to include. Slices and lists of integers will be interpreted as
channel indices. In lists, channel type strings (e.g., ['meg',
'eeg']
) will pick channels of those types, channel name strings (e.g.,
['MEG0111', 'MEG2623']
will pick the given channels. Can also be the
string values “all” to pick all channels, or “data” to pick data
channels. None (default) will pick good data channels (excluding reference
MEG channels). Note that channels in info['bads']
will be included if
their names or indices are explicitly provided.
This selection remains throughout the initialized ICA solution.
int
| float
| None
First and last sample to include. If float, data will be
interpreted as time in seconds. If None
, data will be used from
the first sample and to the last sample, respectively.
Note
These parameters only have an effect if inst
is
Raw
data.
int
| None
Increment for selecting only each n-th sampling point. If None
,
all samples between start
and stop
(inclusive) are used.
dict
| None
Rejection parameters based on peak-to-peak amplitude (PTP)
in the continuous data. Signal periods exceeding the thresholds
in reject
or less than the thresholds in flat
will be
removed before fitting the ICA.
Note
These parameters only have an effect if inst
is
Raw
data. For Epochs
, perform PTP
rejection via drop_bad()
.
Valid keys are all channel types present in the data. Values must be integers or floats.
If None
, no PTP-based rejection will be performed. Example:
reject = dict(
grad=4000e-13, # T / m (gradiometers)
mag=4e-12, # T (magnetometers)
eeg=40e-6, # V (EEG channels)
eog=250e-6 # V (EOG channels)
)
flat = None # no rejection based on flatness
float
Length of data chunks for artifact rejection in seconds.
Note
This parameter only has an effect if inst
is
Raw
data.
Whether to omit bad segments from the data before fitting. If True
(default), annotated segments whose description begins with 'bad'
are
omitted. If False
, no rejection based on annotations is performed.
Has no effect if inst
is not a mne.io.Raw
object.
New in version 0.14.0.
str
| int
| None
Control verbosity of the logging output. If None
, use the default
verbosity level. See the logging documentation and
mne.verbose()
for details. Should only be passed as a keyword
argument.
ICA
Returns the modified instance.
Examples using fit
:
Overview of MEG/EEG analysis with MNE-Python
Getting started with mne.Report
Find MEG reference channel artifacts
Removing muscle ICA components
Get a list of channel type for each channel.
str
| list
| slice
| None
Channels to include. Slices and lists of integers will be interpreted as
channel indices. In lists, channel type strings (e.g., ['meg',
'eeg']
) will pick channels of those types, channel name strings (e.g.,
['MEG0111', 'MEG2623']
will pick the given channels. Can also be the
string values “all” to pick all channels, or “data” to pick data
channels. None (default) will pick all channels. Note that channels in
info['bads']
will be included if their names or indices are
explicitly provided.
Whether to return only unique channel types. Default is False
.
Whether to ignore non-data channels. Default is False
.
list
The channel types.
Get ICA topomap for components as numpy arrays.
array
, shape (n_channels, n_components)The ICA components (maps).
Estimate sources given the unmixing matrix.
This method will return the sources in the container format passed. Typical usecases:
pass Raw object to use raw.plot
for ICA sources
pass Epochs object to compute trial-based statistics in ICA space
pass Evoked object to investigate time-locking in ICA space
Raw
, Epochs
or Evoked
Object to compute sources from and to represent sources in.
None
| list
of str
Additional channels to be added. Useful to e.g. compare sources with some reference. Defaults to None.
int
| float
| None
First sample to include. If float, data will be interpreted as time in seconds. If None, the entire data will be used.
int
| float
| None
Last sample to not include. If float, data will be interpreted as time in seconds. If None, the entire data will be used.
Examples using get_sources
:
Find MEG reference channel artifacts
Project mixing matrix on interpolated sensor topography.
int
| list
of int
| slice
| None
Indices of the independent components (ICs) to visualize.
If an integer, represents the index of the IC to pick.
Multiple ICs can be selected using a list of int or a slice.
The indices are 0-indexed, so picks=1
will
pick the second IC: ICA001
. If None
, all components are plotted in batches of 20.
None
The channel type to plot. For ‘grad’, the gradiometers are collected in pairs and the RMS for each pair is plotted. If None, then channels are chosen in the order given above.
int
The resolution of the topomap image (n pixels along each side).
float
| callable()
| None
Lower and upper bounds of the colormap, in the same units as the data.
If vmin
and vmax
are both None
, they are set at ± the
maximum absolute value of the data (yielding a colormap with midpoint
at 0). If only one of vmin
, vmax
is None
, will use
min(data)
or max(data)
, respectively. If callable, should
accept a NumPy array
of data and return a
float.
None
Colormap to use. If tuple, the first value indicates the colormap to use and the second value is a boolean defining interactivity. In interactive mode the colors are adjustable by clicking and dragging the colorbar with left and right mouse button. Left mouse button moves the scale up and down and right mouse button adjusts the range. Hitting space bar resets the range. Up and down arrows can be used to change the colormap. If None, ‘Reds’ is used for all positive data, otherwise defaults to ‘RdBu_r’. If ‘interactive’, translates to (None, True). Defaults to ‘RdBu_r’.
Warning
Interactive mode works smoothly only for a small amount of topomaps.
str
Add markers for sensor locations to the plot. Accepts matplotlib plot format string (e.g., ‘r+’ for red plusses). If True (default), circles will be used.
Plot a colorbar.
str
| None
Title to use.
Show figure if True.
dict
| None
The outlines to be drawn. If ‘head’, the default head scheme will be drawn. If ‘skirt’ the head scheme will be drawn, but sensors are allowed to be plotted outside of the head circle. If dict, each key refers to a tuple of x and y positions, the values in ‘mask_pos’ will serve as image mask. Alternatively, a matplotlib patch object can be passed for advanced masking options, either directly or as a function that returns patches (required for multi-axis plots). If None, nothing will be drawn. Defaults to ‘head’.
int
| array
of float
The number of contour lines to draw. If 0, no contours will be drawn. When an integer, matplotlib ticker locator is used to find suitable values for the contour thresholds (may sometimes be inaccurate, use array for accuracy). If an array, the values represent the levels for the contours. Defaults to 6.
str
The image interpolation to be used. Options are 'cubic'
(default)
to use scipy.interpolate.CloughTocher2DInterpolator
,
'nearest'
to use scipy.spatial.Voronoi
or
'linear'
to use scipy.interpolate.LinearNDInterpolator
.
Raw
| Epochs
| None
To be able to see component properties after clicking on component topomap you need to pass relevant data - instances of Raw or Epochs (for example the data that ICA was trained on). This takes effect only when running matplotlib in interactive mode.
float
Whether to plot standard deviation in ERP/ERF and spectrum plots. Defaults to True, which plots one standard deviation above/below. If set to float allows to control how many standard deviations are plotted. For example 2.5 will plot 2.5 standard deviation above/below.
dict
| None
Dictionary of arguments to plot_topomap
. If None, doesn’t pass any
additional arguments. Defaults to None.
dict
| None
Dictionary of arguments to plot_epochs_image
. If None, doesn’t pass
any additional arguments. Defaults to None.
dict
| None
Dictionary of arguments to psd_multitaper
. If None, doesn’t pass
any additional arguments. Defaults to None.
dict
| None
Allows to specify rejection parameters used to drop epochs (or segments if continuous signal is passed as inst). If None, no rejection is applied. The default is ‘auto’, which applies the rejection parameters used when fitting the ICA object.
float
| array-like | instance of ConductorModel
| None
| ‘auto’ | ‘eeglab’The sphere parameters to use for the head outline. Can be array-like of
shape (4,) to give the X/Y/Z origin and radius in meters, or a single float
to give just the radius (origin assumed 0, 0, 0). Can also be an instance
of a spherical ConductorModel
to use the origin and
radius from that object. If 'auto'
the sphere is fit to digitization
points. If 'eeglab'
the head circle is defined by EEG electrodes
'Fpz'
, 'Oz'
, 'T7'
, and 'T8'
(if 'Fpz'
is not present,
it will be approximated from the coordinates of 'Oz'
). None
(the
default) is equivalent to 'auto'
when enough extra digitization points
are available, and (0, 0, 0, 0.095) otherwise. Currently the head radius
does not affect plotting.
New in version 0.20.
Changed in version 1.1: Added 'eeglab'
option.
str
| int
| None
Control verbosity of the logging output. If None
, use the default
verbosity level. See the logging documentation and
mne.verbose()
for details. Should only be passed as a keyword
argument.
matplotlib.figure.Figure
| list
of matplotlib.figure.Figure
The figure object(s). Components are plotted on a grid with maximum dimensions of 5⨉4. If more than 20 components are plotted, a new figure will be created for each batch of 20, and a list of those figures will be returned.
Notes
When run in interactive mode, plot_ica_components
allows to reject
components by clicking on their title label. The state of each component
is indicated by its label color (gray: rejected; black: retained). It is
also possible to open component properties by clicking on the component
topomap (this option is only available when the inst
argument is
supplied).
Examples using plot_components
:
Overlay of raw and cleaned signals given the unmixing matrix.
This method helps visualizing signal quality and artifact rejection.
mne.io.Raw
or mne.Evoked
The signal to plot. If Raw
, the raw data is displayed before
and after cleaning. In a second panel, the cross-channel average will
be displayed. Since dipolar sources will be canceled out, this
representation is sensitive to artifacts. If Evoked
, butterfly
traces for signals before and after cleaning will be superimposed.
int
| None
(default)The components marked for exclusion. If None
(default), ICA.exclude
will be used.
str
| list
| slice
| None
Channels to include. Slices and lists of integers will be interpreted as
channel indices. In lists, channel type strings (e.g., ['meg',
'eeg']
) will pick channels of those types, channel name strings (e.g.,
['MEG0111', 'MEG2623']
will pick the given channels. Can also be the
string values “all” to pick all channels, or “data” to pick data
channels. None (default) will pick all channels that were included during fitting.
float
| None
The first and last time point (in seconds) of the data to plot. If
inst
is a Raw
object, start=None
and stop=None
will be translated into start=0.
and stop=3.
, respectively. For
Evoked
, None
refers to the beginning and end of the evoked
signal.
str
| None
The title of the generated figure. If None
(default), no title is
displayed.
Show the figure if True
.
int
| float
| None
The number of PCA components to be kept, either absolute (int)
or fraction of the explained variance (float). If None (default),
the ica.n_pca_components
from initialization will be used in 0.22;
in 0.23 all components will be used.
New in version 0.22.
Figure
The figure.
Examples using plot_overlay
:
Removing muscle ICA components
Display component properties.
Properties include the topography, epochs image, ERP/ERF, power spectrum, and epoch variance.
Epochs
or Raw
The data to use in plotting properties.
Note
You can interactively cycle through topographic maps for different channel types by pressing T.
str
| list
| slice
| None
Components to include. Slices and lists of integers will be interpreted
as component indices. None
(default) will use the first five
components. Each component will be plotted in a separate figure.
list
of Axes
| None
List of five matplotlib axes to use in plotting: [topomap_axis, image_axis, erp_axis, spectrum_axis, variance_axis]. If None a new figure with relevant axes is created. Defaults to None.
Whether to plot spectrum in dB. Defaults to True.
float
Whether to plot standard deviation/confidence intervals in ERP/ERF and
spectrum plots.
Defaults to True, which plots one standard deviation above/below for
the spectrum. If set to float allows to control how many standard
deviations are plotted for the spectrum. For example 2.5 will plot 2.5
standard deviation above/below.
For the ERP/ERF, by default, plot the 95 percent parametric confidence
interval is calculated. To change this, use ci
in ts_args
in
image_args
(see below).
Whether to use a logarithmic frequency axis to plot the spectrum.
Defaults to False
.
Note
You can interactively toggle this setting by pressing L.
New in version 1.1.
dict
| None
Dictionary of arguments to plot_topomap
. If None, doesn’t pass any
additional arguments. Defaults to None.
dict
| None
Dictionary of arguments to plot_epochs_image
. If None, doesn’t pass
any additional arguments. Defaults to None.
dict
| None
Dictionary of arguments to psd_multitaper
. If None, doesn’t pass
any additional arguments. Defaults to None.
None
Allows to control size of the figure. If None, the figure size defaults to [7., 6.].
Show figure if True.
dict
| None
Allows to specify rejection parameters used to drop epochs (or segments if continuous signal is passed as inst). If None, no rejection is applied. The default is ‘auto’, which applies the rejection parameters used when fitting the ICA object.
Whether to omit bad segments from the data before fitting. If True
(default), annotated segments whose description begins with 'bad'
are
omitted. If False
, no rejection based on annotations is performed.
Has no effect if inst
is not a mne.io.Raw
object.
New in version 0.21.0.
str
| int
| None
Control verbosity of the logging output. If None
, use the default
verbosity level. See the logging documentation and
mne.verbose()
for details. Should only be passed as a keyword
argument.
list
List of matplotlib figures.
Notes
New in version 0.13.
Examples using plot_properties
:
Overview of MEG/EEG analysis with MNE-Python
Find MEG reference channel artifacts
Removing muscle ICA components
Plot scores related to detected components.
Use this function to asses how well your score describes outlier sources and how well you were detecting them.
float
, shape (n_ica_components,) | list
of array
Scores based on arbitrary metric to characterize ICA components.
int
The components marked for exclusion. If None (default), ICA.exclude will be used.
str
| list
| ‘ecg’ | ‘eog’ | None
The labels to consider for the axes tests. Defaults to None.
If list, should match the outer shape of scores
.
If ‘ecg’ or ‘eog’, the labels_
attributes will be looked up.
Note that ‘/’ is used internally for sublabels specifying ECG and
EOG channels.
float
Draw horizontal line to e.g. visualize rejection threshold.
str
The figure title.
tuple
of int
| None
The figure size. If None it gets set automatically.
int
| None
Scores are plotted in a grid. This parameter controls how many to plot side by side before starting a new row. By default, a number will be chosen to make the grid as square as possible.
Show figure if True.
Figure
The figure object.
Examples using plot_scores
:
Find MEG reference channel artifacts
Removing muscle ICA components
Plot estimated latent sources given the unmixing matrix.
Typical usecases:
plot evolution of latent sources over time based on (Raw input)
plot latent source around event related time windows (Epochs input)
plot time-locking in ICA space (Evoked input)
mne.io.Raw
, mne.Epochs
, mne.Evoked
The object to plot the sources from.
int
| list
of int
| slice
| None
Indices of the independent components (ICs) to visualize.
If an integer, represents the index of the IC to pick.
Multiple ICs can be selected using a list of int or a slice.
The indices are 0-indexed, so picks=1
will
pick the second IC: ICA001
. None
(default) will pick all sources in the order fitted.
float
| int
| None
If inst
is a Raw
or an Evoked
object, the first and
last time point (in seconds) of the data to plot. If inst
is a
Raw
object, start=None
and stop=None
will be
translated into start=0.
and stop=3.
, respectively. For
Evoked
, None
refers to the beginning and end of the evoked
signal. If inst
is an Epochs
object, specifies the index of
the first and last epoch to show.
str
| None
The window title. If None a default is provided.
Show figure if True.
Whether to halt program execution until the figure is closed. Useful for interactive selection of components in raw and epoch plotter. For evoked, this parameter has no effect. Defaults to False.
If True, show time axis relative to the raw.first_samp
.
Whether to show scrollbars when the plot is initialized. Can be toggled
after initialization by pressing z (“zen mode”) while the plot
window is focused. Default is True
.
New in version 0.19.0.
Style of time labels on the horizontal axis. If 'float'
, labels will be
number of seconds from the start of the recording. If 'clock'
,
labels will show “clock time” (hours/minutes/seconds) inferred from
raw.info['meas_date']
. Default is 'float'
.
New in version 0.24.
str
Whether to load all data (not just the visible portion) into RAM and
apply preprocessing (e.g., projectors) to the full data array in a separate
processor thread, instead of window-by-window during scrolling. The default
None uses the MNE_BROWSER_PRECOMPUTE
variable, which defaults to
'auto'
. 'auto'
compares available RAM space to the expected size of
the precomputed data, and precomputes only if enough RAM is available.
This is only used with the Qt backend.
New in version 0.24.
Changed in version 1.0: Support for the MNE_BROWSER_PRECOMPUTE config variable.
None
Whether to use OpenGL when rendering the plot (requires pyopengl
).
May increase performance, but effect is dependent on system CPU and
graphics hardware. Only works if using the Qt backend. Default is
None, which will use False unless the user configuration variable
MNE_BROWSER_USE_OPENGL
is set to 'true'
,
see mne.set_config()
.
New in version 0.24.
str
| path-likeCan be “auto”, “light”, or “dark” or a path-like to a
custom stylesheet. For Dark-Mode and automatic Dark-Mode-Detection,
qdarkstyle
and
darkdetect,
respectively, are required. If None (default), the config option MNE_BROWSER_THEME will be used,
defaulting to “auto” if it’s not found.
Only supported by the 'qt'
backend.
New in version 1.0.
str
| None
Can be “channels”, “empty”, or “hidden” to set the overview bar mode
for the 'qt'
backend. If None (default), the config option
MNE_BROWSER_OVERVIEW_MODE
will be used, defaulting to “channels”
if it’s not found.
New in version 1.1.
matplotlib.figure.Figure
| mne_qt_browser.figure.MNEQtBrowserBrowser instance.
Notes
For raw and epoch instances, it is possible to select components for
exclusion by clicking on the line. The selected components are added to
ica.exclude
on close.
New in version 0.10.0.
Examples using plot_sources
:
Removing muscle ICA components
Store ICA solution into a fiff file.
str
The absolute path of the file name to save the ICA solution into. The file name should end with -ica.fif or -ica.fif.gz.
If True (default False), overwrite the destination file if it exists.
New in version 1.0.
str
| int
| None
Control verbosity of the logging output. If None
, use the default
verbosity level. See the logging documentation and
mne.verbose()
for details. Should only be passed as a keyword
argument.
ICA
The object.
See also
Assign score to components based on statistic or metric.
Raw
, Epochs
or Evoked
The object to reconstruct the sources from.
str
| None
Signal to which the sources shall be compared. It has to be of the same shape as the sources. If str, a routine will try to find a matching channel name. If None, a score function expecting only one input-array argument must be used, for instance, scipy.stats.skew (default).
callable()
| str
Callable taking as arguments either two input arrays (e.g. Pearson correlation) or one input array (e. g. skewness) and returns a float. For convenience the most common score_funcs are available via string labels: Currently, all distance metrics from scipy.spatial and All functions from scipy.stats taking compatible input arguments are supported. These function have been modified to support iteration over the rows of a 2D array.
int
| float
| None
First sample to include. If float, data will be interpreted as time in seconds. If None, data will be used from the first sample.
int
| float
| None
Last sample to not include. If float, data will be interpreted as time in seconds. If None, data will be used to the last sample.
float
Low pass frequency.
float
High pass frequency.
Whether to omit bad segments from the data before fitting. If True
(default), annotated segments whose description begins with 'bad'
are
omitted. If False
, no rejection based on annotations is performed.
New in version 0.14.0.
str
| int
| None
Control verbosity of the logging output. If None
, use the default
verbosity level. See the logging documentation and
mne.verbose()
for details. Should only be passed as a keyword
argument.
ndarray
Scores for each source as returned from score_func.
mne.preprocessing.ICA
#Overview of MEG/EEG analysis with MNE-Python
Getting started with mne.Report
Rejecting bad data spans and breaks
Find MEG reference channel artifacts
Compare the different ICA algorithms in MNE
Removing muscle ICA components
From raw data to dSPM on SPM Faces dataset