mne.preprocessing.ICA¶
- class mne.preprocessing.ICA(n_components=None, *, noise_cov=None, random_state=None, method='fastica', fit_params=None, max_iter=None, allow_ref_meg=False, verbose=None)[source]¶
Data decomposition using Independent Component Analysis (ICA).
This object estimates independent components from
mne.io.Raw
,mne.Epochs
, ormne.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.
- Parameters
- n_components
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 theICA.fit()
method will be stored in the attributen_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.- noise_cov
None
| instance ofCovariance
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.
- random_state
None
|int
| instance ofRandomState
If
random_state
is anint
, it will be used as a seed forRandomState
. IfNone
, the seed will be obtained from the operating system (seeRandomState
for details). Default isNone
. As estimation can be non-deterministic it can be useful to fix the random state to have reproducible results.- method{‘fastica’, ‘infomax’, ‘picard’}
The ICA method to use in the fit method. Use the
fit_params
argument to set additional parameters. Specifically, if you want Extended Infomax, setmethod='infomax'
andfit_params=dict(extended=True)
(this also works formethod='picard'
). Defaults to'fastica'
. For reference, see 1234.- fit_params
dict
|None
Additional parameters passed to the ICA estimator as specified by
method
.- max_iter
int
| ‘auto’ Maximum number of iterations during fit. If
'auto'
, it will set maximum iterations to1000
for'fastica'
and to500
for'infomax'
or'picard'
. The actual number of iterations it tookICA.fit()
to complete will be stored in then_iter_
attribute.- allow_ref_megbool
Allow ICA on MEG reference channels. Defaults to False.
New in version 0.18.
- 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.
- n_components
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 currentmax_iter=200
.Changed in version 0.23: Warn if
Epochs
were baseline-corrected.Note
If you intend to clean 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
andica.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
andn_pca_components
.
n_pca_components
determines how many PCA components will be kept when reconstructing the data when callingapply()
. 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, usingn_components
as a float will also avoid numerical stability problems.The
n_components
parameter determines how many components out of then_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 usen_components < n_channels
. For example, full-rank 306-channel MEG data might usen_components=40
to find (and later exclude) only large, dominating artifacts in the data, but still reconstruct the data using all 306 PCA components. Settingn_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, passn_components=n
during initialization and thenn_pca_components=n
duringapply()
. The resulting reconstructed data afterapply()
will have rankn
.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 infit_params
are determined by the various algorithm implementations: seeFastICA
,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'
andfit_params
as a dictionary with the following combination of keys:dict(ortho=False, extended=False)
for Infomaxdict(ortho=False, extended=True)
for extended Infomaxdict(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 istol_fastica == tol_picard ** 2
.References
- 1
Aapo Hyvärinen. Fast and robust fixed-point algorithms for independent component analysis. IEEE Transactions on Neural Networks, 10(3):626–634, 1999. doi:10.1109/72.761722.
- 2
Anthony J. Bell and Terrence J. Sejnowski. An information-maximization approach to blind separation and blind deconvolution. Neural Computation, 7(6):1129–1159, 1995. doi:10.1162/neco.1995.7.6.1129.
- 3
Te-Won Lee, Mark Girolami, and Terrence J. Sejnowski. Independent component analysis using an extended infomax algorithm for mixed subgaussian and supergaussian sources. Neural Computation, 11(2):417–441, 1999. doi:10.1162/089976699300016719.
- 4
Pierre Ablin, Jean-Francois Cardoso, and Alexandre Gramfort. Faster Independent Component Analysis by preconditioning with hessian approximations. IEEE Transactions on Signal Processing, 66(15):4040–4049, 2018. doi:10.1109/TSP.2018.2844203.
- 5
Fiorenzo Artoni, Arnaud Delorme, and Scott Makeig. Applying dimension reduction to EEG data by Principal Component Analysis reduces the quality of its subsequent Independent Component decomposition. NeuroImage, 175:176–187, 2018. doi:10.1016/j.neuroimage.2018.03.016.
- 6
Jair Montoya-Martínez, Jean-François Cardoso, and Alexandre Gramfort. Caveats with stochastic gradient and maximum likelihood based ICA for EEG. In Petr Tichavský, Massoud Babaie-Zadeh, Olivier J.J. Michel, and Nadège Thirion-Moreau, editors, Latent Variable Analysis and Signal Separation, number 10169 in Lecture Notes in Computer Science, pages 279–289. Springer International Publishing, Cham, 2017. doi:10.1007/978-3-319-53547-0_27.
- Attributes
- current_fit
str
Flag informing about which data type (raw or epochs) was used for the fit.
- ch_nameslist-like
Channel names resulting from initial picking.
- n_components_
int
If fit, the actual number of PCA components used for ICA decomposition.
- pre_whitener_
ndarray
, shape (n_channels, 1) or (n_channels, n_channels) If fit, array used to pre-whiten the data prior to PCA.
- pca_components_
ndarray
, shape(n_channels, n_channels)
If fit, the PCA components.
- pca_mean_
ndarray
, shape (n_channels,) If fit, the mean vector used to center the data before doing the PCA.
- pca_explained_variance_
ndarray
, shape(n_channels,)
If fit, the variance explained by each PCA component.
- mixing_matrix_
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 byICA.apply()
andICA.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.- unmixing_matrix_
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 methodsICA.get_sources()
andICA.apply()
to unmix the observed data.- excludearray_like of
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 anexclude
parameter in theICA.apply()
method.) To scrap all marked components, set this attribute to an empty list.- info
None
| instance ofInfo
The measurement info copied from the object fitted.
- n_samples_
int
The number of samples used on fit.
- labels_
dict
A dictionary of independent component indices, grouped by types of independent components. This attribute is set by some of the artifact detection functions.
- n_iter_
int
If fit, the number of iterations required to complete ICA.
- current_fit
Methods
__contains__
(ch_type)Check channel type membership.
__hash__
(/)Return hash(self).
apply
(inst[, include, exclude, …])Remove selected components from the signal.
copy
()Copy the ICA object.
detect_artifacts
(raw[, start_find, …])Run ICA artifacts detection workflow.
find_bads_ecg
(inst[, ch_name, threshold, …])Detect ECG related components.
find_bads_eog
(inst[, ch_name, threshold, …])Detect EOG related components using correlation.
find_bads_ref
(inst[, ch_name, threshold, …])Detect MEG reference related components using correlation.
fit
(inst[, picks, start, stop, decim, …])Run the ICA decomposition on raw data.
get_channel_types
([picks, unique, only_data_chs])Get a list of channel type for each channel.
Get ICA topomap for components as numpy arrays.
Get a DigMontage from instance.
get_sources
(inst[, add_channels, start, stop])Estimate sources given the unmixing matrix.
plot_components
([picks, ch_type, res, vmin, …])Project mixing matrix on interpolated sensor topography.
plot_overlay
(inst[, exclude, picks, start, …])Overlay of raw and cleaned signals given the unmixing matrix.
plot_properties
(inst[, picks, axes, dB, …])Display component properties.
plot_scores
(scores[, exclude, labels, …])Plot scores related to detected components.
plot_sources
(inst[, picks, start, stop, …])Plot estimated latent sources given the unmixing matrix.
save
(fname[, verbose])Store ICA solution into a fiff file.
score_sources
(inst[, target, score_func, …])Assign score to components based on statistic or metric.
- __contains__(ch_type)[source]¶
Check channel type membership.
- Parameters
- ch_type
str
Channel type to check for. Can be e.g. ‘meg’, ‘eeg’, ‘stim’, etc.
- ch_type
- Returns
- inbool
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
- apply(inst, include=None, exclude=None, n_pca_components=None, start=None, stop=None, verbose=None)[source]¶
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.
- Parameters
- instinstance of
Raw
,Epochs
orEvoked
The data to be processed (i.e., cleaned). It will be modified in-place.
- includearray_like of
int
The indices referring to columns in the ummixing matrix. The components to be kept.
- excludearray_like of
int
The indices referring to columns in the ummixing matrix. The components to be zeroed out.
- n_pca_components
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.- start
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.
- stop
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.
- 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. Defaults to self.verbose.
- instinstance of
- Returns
Notes
Note
Applying ICA may introduce a DC shift. If you pass baseline-corrected
Epochs
orEvoked
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
:
- property compensation_grade¶
The current gradient compensation grade.
- copy()[source]¶
Copy the ICA object.
- Returns
- icainstance of
ICA
The copied object.
- icainstance of
Examples using
copy
:
- detect_artifacts(raw, start_find=None, stop_find=None, ecg_ch=None, ecg_score_func='pearsonr', ecg_criterion=0.1, eog_ch=None, eog_score_func='pearsonr', eog_criterion=0.1, skew_criterion=0, kurt_criterion=0, var_criterion=- 1, add_nodes=None)[source]¶
Run ICA artifacts detection workflow.
Note. This is still experimental and will most likely change over the next releases. For maximum control use the workflow exposed in the examples.
Hints and caveats: - It is highly recommended to bandpass filter ECG and EOG data and pass them instead of the channel names as ecg_ch and eog_ch arguments. - please check your results. Detection by kurtosis and variance may be powerful but misclassification of brain signals as noise cannot be precluded. - Consider using shorter times for start_find and stop_find than for start and stop. It can save you much time.
Example invocation (taking advantage of the defaults):
ica.detect_artifacts(ecg_channel='MEG 1531', eog_channel='EOG 061')
- Parameters
- rawinstance of
Raw
Raw object to draw sources from. No components are actually removed here, i.e. ica is not applied to raw in this function. Use
ica.apply()
for this after inspection of the identified components.- start_find
int
|float
|None
First sample to include for artifact search. If float, data will be interpreted as time in seconds. If None, data will be used from the first sample.
- stop_find
int
|float
|None
Last sample to not include for artifact search. If float, data will be interpreted as time in seconds. If None, data will be used to the last sample.
- ecg_ch
str
|ndarray
|None
The
target
argument passed to ica.find_sources_raw. Either the name of the ECG channel or the ECG time series. If None, this step will be skipped.- ecg_score_func
str
|callable()
The
score_func
argument passed to ica.find_sources_raw. Either the name of function supported by ICA or a custom function.- ecg_criterion
float
|int
| list-like |slice
The indices of the sorted ecg scores. If float, sources with absolute scores greater than the criterion will be dropped. Else, the absolute scores sorted in descending order will be indexed accordingly. E.g. range(2) would return the two sources with the highest absolute score. If None, this step will be skipped.
- eog_ch
list
|str
|ndarray
|None
The
target
argument or the list of target arguments subsequently passed to ica.find_sources_raw. Either the name of the vertical EOG channel or the corresponding EOG time series. If None, this step will be skipped.- eog_score_func
str
|callable()
The
score_func
argument passed to ica.find_sources_raw. Either the name of function supported by ICA or a custom function.- eog_criterion
float
|int
| list-like |slice
The indices of the sorted eog scores. If float, sources with absolute scores greater than the criterion will be dropped. Else, the absolute scores sorted in descending order will be indexed accordingly. E.g. range(2) would return the two sources with the highest absolute score. If None, this step will be skipped.
- skew_criterion
float
|int
| list-like |slice
The indices of the sorted skewness scores. If float, sources with absolute scores greater than the criterion will be dropped. Else, the absolute scores sorted in descending order will be indexed accordingly. E.g. range(2) would return the two sources with the highest absolute score. If None, this step will be skipped.
- kurt_criterion
float
|int
| list-like |slice
The indices of the sorted kurtosis scores. If float, sources with absolute scores greater than the criterion will be dropped. Else, the absolute scores sorted in descending order will be indexed accordingly. E.g. range(2) would return the two sources with the highest absolute score. If None, this step will be skipped.
- var_criterion
float
|int
| list-like |slice
The indices of the sorted variance scores. If float, sources with absolute scores greater than the criterion will be dropped. Else, the absolute scores sorted in descending order will be indexed accordingly. E.g. range(2) would return the two sources with the highest absolute score. If None, this step will be skipped.
- add_nodes
list
oftuple
Additional list if tuples carrying the following parameters of ica nodes: (name : str, target : str | array, score_func : callable, criterion : float | int | list-like | slice). This parameter is a generalization of the artifact specific parameters above and has the same structure. Example:
add_nodes=('ECG phase lock', ECG 01', my_phase_lock_function, 0.5)
- rawinstance of
- Returns
- selfinstance of
ICA
The ICA object with the detected artifact indices marked for exclusion.
- selfinstance of
- find_bads_ecg(inst, ch_name=None, threshold='auto', start=None, stop=None, l_freq=8, h_freq=16, method='ctps', reject_by_annotation=True, measure='zscore', verbose=None)[source]¶
Detect ECG related components.
Cross-trial phase statistics (default) 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.
- Parameters
- instinstance of
Raw
,Epochs
orEvoked
Object to compute sources from.
- ch_name
str
The name of the channel to use for ECG peak detection. The argument is mandatory if the dataset contains no ECG channels.
- threshold
float
|str
The value above which a feature is classified as outlier. If ‘auto’ and method is ‘ctps’, automatically compute the threshold. If ‘auto’ and method is ‘correlation’, defaults to 3.0. The default translates to 0.25 for ‘ctps’ and 3.0 for ‘correlation’ in version 0.21 but will change to ‘auto’ in version 0.22.
Changed in version 0.21.
- start
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.
- stop
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.
- l_freq
float
Low pass frequency.
- h_freq
float
High pass frequency.
- method{‘ctps’, ‘correlation’}
The method used for detection. If ‘ctps’, cross-trial phase statistics [1] are used to detect ECG related components. Thresholding is then based on the significance value of a Kuiper statistic. If ‘correlation’, detection is based on Pearson correlation between the filtered data and the filtered ECG channel. Thresholding is based on iterative z-scoring. The above threshold components will be masked and the z-score will be recomputed until no supra-threshold component remains. Defaults to ‘ctps’.
- reject_by_annotationbool
Whether to omit bad segments from the data before fitting. If
True
(default), annotated segments whose description begins with'bad'
are omitted. IfFalse
, no rejection based on annotations is performed.New in version 0.14.0.
- measure‘zscore’ | ‘correlation’
Which method to use for finding outliers.
'zscore'
(default) is the iterated Z-scoring method, and'correlation'
is an absolute raw correlation threshold with a range of 0 to 1.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. Defaults to self.verbose.
- instinstance of
- Returns
- ecg_idx
list
ofint
The indices of ECG-related components.
- scores
np.ndarray
offloat
, shape (n_components_
) If method is ‘ctps’, the normalized Kuiper index scores. If method is ‘correlation’, the correlation scores.
- ecg_idx
See also
References
- [1] Dammers, J., Schiek, M., Boers, F., Silex, C., Zvyagintsev,
M., Pietrzyk, U., Mathiak, K., 2008. Integration of amplitude and phase statistics for complete artifact removal in independent components of neuromagnetic recordings. Biomedical Engineering, IEEE Transactions on 55 (10), 2353-2362.
Examples using
find_bads_ecg
:
- find_bads_eog(inst, ch_name=None, threshold=3.0, start=None, stop=None, l_freq=1, h_freq=10, reject_by_annotation=True, measure='zscore', verbose=None)[source]¶
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.
- Parameters
- instinstance of
Raw
,Epochs
orEvoked
Object to compute sources from.
- ch_name
str
The name of the channel to use for EOG peak detection. The argument is mandatory if the dataset contains no EOG channels.
- threshold
int
|float
The value above which a feature is classified as outlier.
- start
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.
- stop
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.
- l_freq
float
Low pass frequency.
- h_freq
float
High pass frequency.
- reject_by_annotationbool
Whether to omit bad segments from the data before fitting. If
True
(default), annotated segments whose description begins with'bad'
are omitted. IfFalse
, no rejection based on annotations is performed.New in version 0.14.0.
- measure‘zscore’ | ‘correlation’
Which method to use for finding outliers.
'zscore'
(default) is the iterated Z-scoring method, and'correlation'
is an absolute raw correlation threshold with a range of 0 to 1.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. Defaults to self.verbose.
- instinstance of
- Returns
See also
Examples using
find_bads_eog
:
- find_bads_ref(inst, ch_name=None, threshold=3.0, start=None, stop=None, l_freq=None, h_freq=None, reject_by_annotation=True, method='together', measure='zscore', verbose=None)[source]¶
Detect MEG reference related components using correlation.
- Parameters
- instinstance of
Raw
,Epochs
orEvoked
Object to compute sources from. Should contain at least one channel i.e. component derived from MEG reference channels.
- ch_name
list
ofstr
Which MEG reference components to use. If None, then all channels that begin with REF_ICA.
- threshold
int
|float
The value above which a feature is classified as outlier.
- start
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.
- stop
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.
- l_freq
float
Low pass frequency.
- h_freq
float
High pass frequency.
- reject_by_annotationbool
Whether to omit bad segments from the data before fitting. If
True
(default), annotated segments whose description begins with'bad'
are omitted. IfFalse
, no rejection based on annotations is performed.- method‘together’ | ‘separate’
Method to use to identify reference channel related components. Defaults to
'together'
. See notes.New in version 0.21.
- measure‘zscore’ | ‘correlation’
Which method to use for finding outliers.
'zscore'
(default) is the iterated Z-scoring method, and'correlation'
is an absolute raw correlation threshold with a range of 0 to 1.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. Defaults to self.verbose.
- instinstance of
- Returns
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 prefixREF_ICA
so that they can be automatically detected.Thresholding in both cases 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.
Validation and further documentation for this technique can be found in 7.
New in version 0.18.
References
- 7
Jeff Hanna, Cora Kim, and Nadia Müller-Voggel. External noise removed from magnetoencephalographic signal using independent component analysis of reference channels. Journal of Neuroscience Methods, 2020. doi:10.1016/j.jneumeth.2020.108592.
Examples using
find_bads_ref
:
- fit(inst, picks=None, start=None, stop=None, decim=None, reject=None, flat=None, tstep=2.0, reject_by_annotation=True, verbose=None)[source]¶
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.
- Parameters
- instinstance of
Raw
orEpochs
The data to be decomposed.
- picks
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 ininfo['bads']
will be included if their names or indices are explicitly provided. This selection remains throughout the initialized ICA solution.- start
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.
- stop
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.
- decim
int
|None
Increment for selecting each nth time slice. If None, all samples within
start
andstop
are used.- reject
dict
|None
Rejection parameters based on peak-to-peak amplitude. Valid keys are ‘grad’, ‘mag’, ‘eeg’, ‘seeg’, ‘dbs’, ‘ecog’, ‘eog’, ‘ecg’, ‘hbo’, ‘hbr’. If reject is None then no rejection is done. 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) )
It only applies if
inst
is of type Raw.- flat
dict
|None
Rejection parameters based on flatness of signal. Valid keys are ‘grad’, ‘mag’, ‘eeg’, ‘seeg’, ‘dbs’, ‘ecog’, ‘eog’, ‘ecg’, ‘hbo’, ‘hbr’. Values are floats that set the minimum acceptable peak-to-peak amplitude. If flat is None then no rejection is done. It only applies if
inst
is of type Raw.- tstep
float
Length of data chunks for artifact rejection in seconds. It only applies if
inst
is of type Raw.- reject_by_annotationbool
Whether to omit bad segments from the data before fitting. If
True
(default), annotated segments whose description begins with'bad'
are omitted. IfFalse
, no rejection based on annotations is performed.Has no effect if
inst
is not amne.io.Raw
object.New in version 0.14.0.
- 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. Defaults to self.verbose.
- instinstance of
- Returns
- selfinstance of
ICA
Returns the modified instance.
- selfinstance of
Examples using
fit
:
- get_channel_types(picks=None, unique=False, only_data_chs=False)[source]¶
Get a list of channel type for each channel.
- Parameters
- picks
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 ininfo['bads']
will be included if their names or indices are explicitly provided.- uniquebool
Whether to return only unique channel types. Default is
False
.- only_data_chsbool
Whether to ignore non-data channels. Default is
False
.
- picks
- Returns
- channel_types
list
The channel types.
- channel_types
- get_components()[source]¶
Get ICA topomap for components as numpy arrays.
- Returns
- components
array
, shape (n_channels, n_components) The ICA components (maps).
- components
- get_montage()[source]¶
Get a DigMontage from instance.
- Returns
- montage
None
|str
|DigMontage
A montage containing channel positions. If str or DigMontage is specified, the channel info will be updated with the channel positions. Default is None. For valid
str
values see documentation ofmne.channels.make_standard_montage()
. See also the documentation ofmne.channels.DigMontage
for more information.
- montage
- get_sources(inst, add_channels=None, start=None, stop=None)[source]¶
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 sourcespass Epochs object to compute trial-based statistics in ICA space
pass Evoked object to investigate time-locking in ICA space
- Parameters
- instinstance of
Raw
,Epochs
orEvoked
Object to compute sources from and to represent sources in.
- add_channels
None
|list
ofstr
Additional channels to be added. Useful to e.g. compare sources with some reference. Defaults to None.
- start
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.
- stop
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.
- instinstance of
- Returns
Examples using
get_sources
:
- plot_components(picks=None, ch_type=None, res=64, vmin=None, vmax=None, cmap='RdBu_r', sensors=True, colorbar=False, title=None, show=True, outlines='head', contours=6, image_interp='bilinear', inst=None, plot_std=True, topomap_args=None, image_args=None, psd_args=None, reject='auto', sphere=None, verbose=None)[source]¶
Project mixing matrix on interpolated sensor topography.
- Parameters
- picks
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 ininfo['bads']
will be included if their names or indices are explicitly provided. If None all are plotted in batches of 20.- ch_type‘mag’ | ‘grad’ | ‘planar1’ | ‘planar2’ | ‘eeg’ |
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.
- res
int
The resolution of the topomap image (n pixels along each side).
- vmin
float
|callable()
|None
The value specifying the lower bound of the color range. If None, and vmax is None, -vmax is used. Else np.min(data). If callable, the output equals vmin(data). Defaults to None.
- vmax
float
|callable()
|None
The value specifying the upper bound of the color range. If None, the maximum absolute value is used. If callable, the output equals vmax(data). Defaults to None.
- cmapmatplotlib colormap | (colormap, bool) | ‘interactive’ |
None
Colormap to use. If tuple, the first value indicates the colormap to use and the second value is a boolean defining interactivity. In interactive mode the colors are adjustable by clicking and dragging the colorbar with left and right mouse button. Left mouse button moves the scale up and down and right mouse button adjusts the range. Hitting space bar resets the range. Up and down arrows can be used to change the colormap. If None, ‘Reds’ is used for 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.
- sensorsbool |
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.
- colorbarbool
Plot a colorbar.
- title
str
|None
Title to use.
- showbool
Show figure if True.
- outlines‘head’ | ‘skirt’ |
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’.
- contours
int
|array
offloat
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.
- image_interp
str
The image interpolation to be used. All matplotlib options are accepted.
- inst
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.
- plot_stdbool |
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.
- topomap_args
dict
|None
Dictionary of arguments to
plot_topomap
. If None, doesn’t pass any additional arguments. Defaults to None.- image_args
dict
|None
Dictionary of arguments to
plot_epochs_image
. If None, doesn’t pass any additional arguments. Defaults to None.- psd_args
dict
|None
Dictionary of arguments to
psd_multitaper
. If None, doesn’t pass any additional arguments. Defaults to None.- reject‘auto’ |
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.
- sphere
float
| array_like |str
|None
The sphere parameters to use for the cartoon head. Can be array-like of shape (4,) to give the X/Y/Z origin and radius in meters, or a single float to give the radius (origin assumed 0, 0, 0). Can also be a spherical ConductorModel, which will use the origin and radius. Can be “auto” to use a digitization-based fit. Can also be None (default) to use ‘auto’ when enough extra digitization points are available, and 0.095 otherwise. Currently the head radius does not affect plotting.
New in version 0.20.
- 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.
- picks
- Returns
- figinstance of
matplotlib.figure.Figure
orlist
The figure object(s).
- figinstance of
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 theinst
argument is supplied).Examples using
plot_components
:
- plot_overlay(inst, exclude=None, picks=None, start=None, stop=None, title=None, show=True, n_pca_components=None)[source]¶
Overlay of raw and cleaned signals given the unmixing matrix.
This method helps visualizing signal quality and artifact rejection.
- Parameters
- instinstance of
mne.io.Raw
ormne.Evoked
The signals to be compared given the ICA solution. If Raw input, The raw data are displayed before and after cleaning. In a second panel the cross channel average will be displayed. Since dipolar sources will be canceled out this display is sensitive to artifacts. If evoked input, butterfly plots for clean and raw signals will be superimposed.
- excludearray_like of
int
|None
(default) The components marked for exclusion. If None (default), ICA.exclude will be used.
- picks
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.- start
int
|None
X-axis start index. If None (default) from the beginning.
- stop
int
|None
X-axis stop index. If None (default) to 3.0s.
- title
str
The figure title.
- showbool
Show figure if True.
- n_pca_components
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.
- instinstance of
- Returns
- figinstance of
Figure
The figure.
- figinstance of
Examples using
plot_overlay
:
- plot_properties(inst, picks=None, axes=None, dB=True, plot_std=True, topomap_args=None, image_args=None, psd_args=None, figsize=None, show=True, reject='auto', reject_by_annotation=True, *, verbose=None)[source]¶
Display component properties.
Properties include the topography, epochs image, ERP/ERF, power spectrum, and epoch variance.
- Parameters
- instinstance of
Epochs
orRaw
The data to use in plotting properties.
- picks
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 the first five sources. If more than one components were chosen in the picks, each one will be plotted in a separate figure.- axes
list
ofAxes
|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.
- dBbool
Whether to plot spectrum in dB. Defaults to True.
- plot_stdbool |
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
ints_args
inimage_args
(see below).- topomap_args
dict
|None
Dictionary of arguments to
plot_topomap
. If None, doesn’t pass any additional arguments. Defaults to None.- image_args
dict
|None
Dictionary of arguments to
plot_epochs_image
. If None, doesn’t pass any additional arguments. Defaults to None.- psd_args
dict
|None
Dictionary of arguments to
psd_multitaper
. If None, doesn’t pass any additional arguments. Defaults to None.- figsizearray_like, shape (2,) |
None
Allows to control size of the figure. If None, the figure size defaults to [7., 6.].
- showbool
Show figure if True.
- reject‘auto’ |
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.
- reject_by_annotationbool
Whether to omit bad segments from the data before fitting. If
True
(default), annotated segments whose description begins with'bad'
are omitted. IfFalse
, no rejection based on annotations is performed.Has no effect if
inst
is not amne.io.Raw
object.New in version 0.21.0.
- 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.
- instinstance of
- Returns
- fig
list
List of matplotlib figures.
- fig
Notes
New in version 0.13.
Examples using
plot_properties
:
- plot_scores(scores, exclude=None, labels=None, axhline=None, title='ICA component scores', figsize=None, n_cols=None, show=True)[source]¶
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.
- Parameters
- scoresarray_like of
float
, shape (n_ica_components,) |list
ofarray
Scores based on arbitrary metric to characterize ICA components.
- excludearray_like of
int
The components marked for exclusion. If None (default), ICA.exclude will be used.
- labels
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’, thelabels_
attributes will be looked up. Note that ‘/’ is used internally for sublabels specifying ECG and EOG channels.- axhline
float
Draw horizontal line to e.g. visualize rejection threshold.
- title
str
The figure title.
- figsize
tuple
ofint
|None
The figure size. If None it gets set automatically.
- n_cols
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.
- showbool
Show figure if True.
- scoresarray_like of
- Returns
- figinstance of
Figure
The figure object.
- figinstance of
Examples using
plot_scores
:
- plot_sources(inst, picks=None, start=None, stop=None, title=None, show=True, block=False, show_first_samp=False, show_scrollbars=True)[source]¶
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)
- Parameters
- instinstance of
mne.io.Raw
,mne.Epochs
,mne.Evoked
The object to plot the sources from.
- picks
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 sources in the order as fitted.- start
int
|None
X-axis start index. If None (default), from the beginning.
- stop
int
|None
X-axis stop index. If None (default), next 20 are shown, in case of evoked to the end.
- title
str
|None
The window title. If None a default is provided.
- showbool
Show figure if True.
- blockbool
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.
- show_first_sampbool
If True, show time axis relative to the
raw.first_samp
.- show_scrollbarsbool
Whether to show scrollbars when the plot is initialized. Can be toggled after initialization by pressing z (“zen mode”) while the plot window is focused. Default is
True
.New in version 0.19.0.
- instinstance of
- Returns
- figinstance of
Figure
The figure.
- figinstance of
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
:
- save(fname, verbose=None)[source]¶
Store ICA solution into a fiff file.
- Parameters
- fname
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.
- 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. Defaults to self.verbose.
- fname
- Returns
- icainstance of
ICA
The object.
- icainstance of
See also
- score_sources(inst, target=None, score_func='pearsonr', start=None, stop=None, l_freq=None, h_freq=None, reject_by_annotation=True, verbose=None)[source]¶
Assign score to components based on statistic or metric.
- Parameters
- instinstance of
Raw
,Epochs
orEvoked
The object to reconstruct the sources from.
- targetarray_like |
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).
- score_func
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.
- start
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.
- stop
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.
- l_freq
float
Low pass frequency.
- h_freq
float
High pass frequency.
- reject_by_annotationbool
Whether to omit bad segments from the data before fitting. If
True
(default), annotated segments whose description begins with'bad'
are omitted. IfFalse
, no rejection based on annotations is performed.New in version 0.14.0.
- 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. Defaults to self.verbose.
- instinstance of
- Returns
- scores
ndarray
Scores for each source as returned from score_func.
- scores