M/EEG signal decomposition using Independent Component Analysis (ICA).
This object can be used to estimate ICA components and then remove some
from mne.io.Raw
, mne.Epochs
, or mne.Evoked
for data exploration or artifact correction.
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
Controls the number of PCA components from the pre-ICA PCA entering the
ICA decomposition in the ICA.fit() method.
If None (default), all PCA components will be used
(== max_pca_components).
If int, must be <= max_pca_components.
If float between 0 and 1, the number of components selected matches the
number of components with a cumulative explained variance below
n_components (a value of 1. resulting in max_pca_components).
The actual number of components resulting from evaluating this
parameter in the ICA.fit() method is stored in the attribute
n_components_ after fitting.
- max_pca_components : int | None
The number of components returned by the PCA decomposition in the
ICA.fit() method.
If None (default), no dimensionality reduction will be applied and
max_pca_components will equal the number of channels supplied for
decomposing the data.
If > n_components_, the additional PCA-only-components can later be
used for re-projecting the data into sensor space, additionally
controllable by the n_pca_components parameter.
- n_pca_components : int | float
The number of PCA components used by the ICA.apply() method for
re-projecting the decomposed data into sensor space. Has to be
>= n_components(_) and <= max_pca_components.
If greater than n_components_, the next n_pca_components minus
n_components PCA components will be added before restoring the sensor
space data.
If None (default), all PCA components will be used.
If float between 0 and 1, the number of components selected matches the
number of components with a cumulative explained variance below
n_pca_components. This attribute allows to balance noise reduction
against potential loss of features due to dimensionality reduction,
independently of the number of ICA components.
- noise_cov : None | instance of mne.cov.Covariance
Noise covariance used for pre-whitening. If None (default), channels
are scaled to unit variance (“z-standardized”) prior to the whitening
by PCA.
- random_state : None | int | instance of np.random.RandomState
Random state to initialize ICA estimation for reproducible results.
- method : {‘fastica’, ‘infomax’, ‘extended-infomax’, ‘picard’}
The ICA method to use in the fit() method. Defaults to ‘fastica’.
For reference, see [1], [2], [3] and [4].
- fit_params : dict | None
Additional parameters passed to the ICA estimator as specified by
method.
- max_iter : int
Maximum number of iterations during fit. Defaults to 200.
- verbose : bool | str | int | None
If not None, override default verbosity level (see mne.verbose()
and Logging documentation).
|
Notes
A trailing _
in an attribute name signifies that the attribute was
added to the object during fitting, consistent with standard scikit-learn
practice.
Prior to fitting and applying the ICA, data is whitened (de-correlated and
scaled to unit variance, also called sphering transformation) by means of
a Principle Component Analysis (PCA). In addition to the whitening, this
step introduces the option to reduce the dimensionality of the data, both
prior to fitting the ICA and prior to reverting to sensor space.
This is controllable by the two parameters max_pca_components and
n_pca_components, respectively.
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].
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 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,
Extended Infomax, and Picard. 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.
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
[1] | (1, 2) Hyvärinen, A., 1999. Fast and robust fixed-point algorithms for
independent component analysis. IEEE transactions on Neural
Networks, 10(3), pp.626-634. |
[2] | (1, 2) Bell, A.J., Sejnowski, T.J., 1995. An information-maximization
approach to blind separation and blind deconvolution. Neural
computation, 7(6), pp.1129-1159. |
[3] | (1, 2) Lee, T.W., Girolami, M., Sejnowski, T.J., 1999. Independent
component analysis using an extended infomax algorithm for mixed
subgaussian and supergaussian sources. Neural computation, 11(2),
pp.417-441. |
[4] | (1, 2) Ablin, P., Cardoso, J.F., Gramfort, A., 2017. Faster Independent
Component Analysis by preconditioning with Hessian approximations.
arXiv:1706.08171 |
[5] | (1, 2) Artoni, F., Delorme, A., und Makeig, S, 2018. Applying Dimension
Reduction to EEG Data by Principal Component Analysis Reduces the
Quality of Its Subsequent Independent Component Decomposition.
NeuroImage 175, pp.176–187.
https://sccn.ucsd.edu/%7Earno/mypapers/Artoni2018.pdf |
Attributes: |
- current_fit : str
Flag informing about which data type (raw or epochs) was used for the
fit.
- ch_names : list-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)
If fit, array used to pre-whiten the data prior to PCA.
- pca_components_ : ndarray, shape (max_pca_components, 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 (max_pca_components,)
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 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.
- 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 methods
ICA.get_sources() and ICA.apply() to unmix the observed data.
- exclude : list
List 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 to this list
(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.
- info : None | instance of Info
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.
|
Methods
__contains__ (ch_type) |
Check channel type membership. |
__hash__ ($self, /) |
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 using correlation. |
find_bads_eog (inst[, ch_name, threshold, …]) |
Detect EOG related components using correlation. |
fit (inst[, picks, start, stop, decim, …]) |
Run the ICA decomposition on raw data. |
get_components () |
Get ICA topomap for components as numpy arrays. |
get_sources (inst[, add_channels, start, stop]) |
Estimate sources given the unmixing matrix. |
plot_components ([picks, ch_type, res, …]) |
Project unmixing 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, exclude, start, …]) |
Plot estimated latent sources given the unmixing matrix. |
save (fname) |
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.
|
Returns: |
- in : bool
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
-
__hash__
($self, /)
Return hash(self).
-
apply
(inst, include=None, exclude=None, n_pca_components=None, start=None, stop=None)[source]
Remove selected components from the signal.
Given the unmixing matrix, transform data,
zero out components, and inverse transform the data.
This procedure will reconstruct M/EEG signals from which
the dynamics described by the excluded components is subtracted.
The data is processed in place.
Parameters: |
- inst : instance of Raw, Epochs or Evoked
The data to be processed. The instance is modified inplace.
- include : array_like of int.
The indices referring to columns in the ummixing matrix. The
components to be kept.
- exclude : array_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 percentage of the explained variance (float). If None (default),
all PCA 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.
|
Returns: |
- out : instance of Raw, Epochs or Evoked
The processed data.
|
-
compensation_grade
The current gradient compensation grade.
-
copy
()[source]
Copy the ICA object.
Returns: |
- ica : instance of ICA
The copied object.
|
-
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=-1, kurt_criterion=-1, var_criterion=0, 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: |
- raw : instance of Raw
Raw object to draw sources from.
- 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 skewness scores. If float, sources with
scores smaller than the criterion will be dropped. Else, the scores
sorted in descending order will be indexed accordingly.
E.g. range(2) would return the two sources with the highest 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 skewness scores. If float, sources with
scores smaller than the criterion will be dropped. Else, the scores
sorted in descending order will be indexed accordingly.
E.g. range(2) would return the two sources with the highest 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
scores smaller than the criterion will be dropped. Else, the scores
sorted in descending order will be indexed accordingly.
E.g. range(2) would return the two sources with the highest score.
If None, this step will be skipped.
- kurt_criterion : float | int | list-like | slice
The indices of the sorted skewness scores. If float, sources with
scores smaller than the criterion will be dropped. Else, the scores
sorted in descending order will be indexed accordingly.
E.g. range(2) would return the two sources with the highest score.
If None, this step will be skipped.
- var_criterion : float | int | list-like | slice
The indices of the sorted skewness scores. If float, sources with
scores smaller than the criterion will be dropped. Else, the scores
sorted in descending order will be indexed accordingly.
E.g. range(2) would return the two sources with the highest score.
If None, this step will be skipped.
- add_nodes : list of ica_nodes
Additional list if tuples carrying the following parameters:
(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)
|
Returns: |
- self : instance of ICA
The ICA object with the detected artifact indices marked for
exclusion
|
-
find_bads_ecg
(inst, ch_name=None, threshold=None, start=None, stop=None, l_freq=8, h_freq=16, method='ctps', reject_by_annotation=True, verbose=None)[source]
Detect ECG related components using correlation.
Note
If no ECG channel is available, routine attempts to create
an artificial ECG based on cross-channel averaging.
Parameters: |
- inst : instance of Raw, Epochs or Evoked
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
The value above which a feature is classified as outlier. If
method is ‘ctps’, defaults to 0.25, else defaults to 3.0.
- 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_annotation : bool
If True, data annotated as bad will be omitted. Defaults to True.
- verbose : bool, str, int, or None
If not None, override default verbose level (see
mne.verbose() and Logging documentation
for more). Defaults to self.verbose.
|
Returns: |
- ecg_idx : list of int
The indices of ECG related components.
- scores : np.ndarray of float, shape (
n_components_ )
The correlation scores.
|
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.
-
find_bads_eog
(inst, ch_name=None, threshold=3.0, start=None, stop=None, l_freq=1, h_freq=10, reject_by_annotation=True, 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: |
- inst : instance of Raw, Epochs or Evoked
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_annotation : bool
If True, data annotated as bad will be omitted. Defaults to True.
- verbose : bool, str, int, or None
If not None, override default verbose level (see
mne.verbose() and Logging documentation
for more). Defaults to self.verbose.
|
Returns: |
- eog_idx : list of int
The indices of EOG related components, sorted by score.
- scores : np.ndarray of float, shape (
n_components_ ) | list of array
The correlation scores.
|
-
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: |
- inst : instance of Raw, Epochs or Evoked
Raw measurements to be decomposed.
- picks : array-like of int
Channels to be included. This selection remains throughout the
initialized ICA solution. If None only good data channels are 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.
- decim : int | None
Increment for selecting each nth time slice. If None, all samples
within start and stop are used.
- reject : dict | None
Rejection parameters based on peak-to-peak amplitude.
Valid keys are ‘grad’, ‘mag’, ‘eeg’, ‘seeg’, ‘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’, ‘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_annotation : bool
Whether to omit bad segments from the data before fitting. If True,
annotated segments with a description that starts with ‘bad’ are
omitted. Has no effect if inst is an Epochs or Evoked object.
Defaults to True.
- verbose : bool, str, int, or None
If not None, override default verbose level (see
mne.verbose() and Logging documentation
for more). Defaults to self.verbose.
|
Returns: |
- self : instance of ICA
Returns the modified instance.
|
-
get_components
()[source]
Get ICA topomap for components as numpy arrays.
Returns: |
- components : array, shape (n_channels, n_components)
The ICA components (maps).
|
-
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 sources
- pass Epochs object to compute trial-based statistics in ICA space
- pass Evoked object to investigate time-locking in ICA space
Parameters: |
- inst : instance of Raw, Epochs or Evoked
Object to compute sources from and to represent sources in.
- add_channels : None | list of str
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.
|
Returns: |
- sources : instance of Raw, Epochs or Evoked
The ICA sources time series.
|
-
plot_components
(picks=None, ch_type=None, res=64, layout=None, vmin=None, vmax=None, cmap='RdBu_r', sensors=True, colorbar=False, title=None, show=True, outlines='head', contours=6, image_interp='bilinear', head_pos=None, inst=None)[source]
Project unmixing matrix on interpolated sensor topography.
Parameters: |
- picks : int | array-like | None
The indices of the sources to be plotted.
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).
- layout : None | Layout
Layout instance specifying sensor positions (does not need to
be specified for Neuromag data). If possible, the correct layout is
inferred from the data.
- 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.
- cmap : matplotlib 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.
- sensors : bool | 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.
- colorbar : bool
Plot a colorbar.
- title : str | None
Title to use.
- show : bool
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, and the ‘autoshrink’ (bool) field will trigger
automated shrinking of the positions due to points outside the outline.
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 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.
- image_interp : str
The image interpolation to be used. All matplotlib options are
accepted.
- head_pos : dict | None
If None (default), the sensors are positioned such that they span
the head circle. If dict, can have entries ‘center’ (tuple) and
‘scale’ (tuple) for what the center and scale of the head should be
relative to the electrode locations.
- 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.
|
Returns: |
- fig : instance of matplotlib.pyplot.Figure or list
The figure object(s).
|
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).
-
plot_overlay
(inst, exclude=None, picks=None, start=None, stop=None, title=None, show=True)[source]
Overlay of raw and cleaned signals given the unmixing matrix.
This method helps visualizing signal quality and artifact rejection.
Parameters: |
- inst : instance of mne.io.Raw or mne.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.
- exclude : array_like of int | None (default)
The components marked for exclusion. If None (default), ICA.exclude
will be used.
- picks : array-like of int | None (default)
Indices of channels to include (if None, all channels
are used that were included on fitting).
- start : int
X-axis start index. If None from the beginning.
- stop : int
X-axis stop index. If None to the end.
- title : str
The figure title.
- show : bool
Show figure if True.
|
Returns: |
- fig : instance of pyplot.Figure
The figure.
|
-
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)[source]
Display component properties.
Properties include the topography, epochs image, ERP/ERF, power
spectrum, and epoch variance.
Parameters: |
- inst: instance of Epochs or Raw
The data to use in plotting properties.
- picks : int | array-like of int | None
The components to be displayed. If None, plot will show the first
five sources. If more than one components were chosen in the picks,
each one will be plotted in a separate figure. Defaults to None.
- axes: list of matplotlib 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.
- dB: bool
Whether to plot spectrum in dB. Defaults to True.
- plot_std: bool | 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.
- figsize : array-like of size (2,) | None
Allows to control size of the figure. If None, the figure size
defaults to [7., 6.].
- show : bool
Show figure if True.
|
Returns: |
- fig : list
List of matplotlib figures.
|
Notes
-
plot_scores
(scores, exclude=None, labels=None, axhline=None, title='ICA component scores', figsize=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: |
- scores : array_like of float, shape (n ica components) | list of arrays
Scores based on arbitrary metric to characterize ICA components.
- exclude : array_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’, the labels_ 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 of int | None
The figure size. If None it gets set automatically.
- show : bool
Show figure if True.
|
Returns: |
- fig : instance of matplotlib.pyplot.Figure
The figure object
|
-
plot_sources
(inst, picks=None, exclude=None, start=None, stop=None, title=None, show=True, block=False, show_first_samp=False)[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: |
- inst : instance of mne.io.Raw, mne.Epochs, mne.Evoked
The object to plot the sources from.
- picks : int | array_like of int | None.
The components to be displayed. If None, plot will show the
sources in the order as fitted.
- exclude : array_like of int
The components marked for exclusion. If None (default), ICA.exclude
will be used.
- start : int
X-axis start index. If None, from the beginning.
- stop : int
X-axis stop index. If None, next 20 are shown, in case of evoked to the
end.
- title : str | None
The figure title. If None a default is provided.
- show : bool
Show figure if True.
- block : bool
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_samp : bool
If True, show time axis relative to the raw.first_samp .
|
Returns: |
- fig : instance of pyplot.Figure
The figure.
|
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.
-
save
(fname)[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.
|
-
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: |
- inst : instance of Raw, Epochs or Evoked
The object to reconstruct the sources from.
- target : array-like | ch_name | None
Signal to which the sources shall be compared. It has to be of
the same shape as the sources. If some string is supplied, a
routine will try to find a matching channel. If None, a score
function expecting only one input-array argument must be used,
for instance, scipy.stats.skew (default).
- score_func : callable | str label
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_annotation : bool
If True, data annotated as bad will be omitted. Defaults to True.
- verbose : bool, str, int, or None
If not None, override default verbose level (see
mne.verbose() and Logging documentation
for more). Defaults to self.verbose.
|
Returns: |
- scores : ndarray
scores for each source as returned from score_func
|