emd.sift.iterated_mask_sift#

emd.sift.iterated_mask_sift(X, mask_0='zc', w_method='power', max_iter=15, iter_th=0.1, N_avg=1, exclude_edges=False, sample_rate=1.0, seed=None, max_imfs=6, ret_mask_freq=False, mask_amp_mode='ratio_imf', **kwargs)[source]#

Compute Intrinsic Mode Functions using an iterated mask sift.

This function implements a masked sift from a dataset using a set of masking signals to reduce mixing of components between modes [1], multiple masks of different phases can be applied when isolating each IMF [2].

Mask frequencies are determined automatically by an iterative process [3]. The iteration can be started with either a random mask, a mask based on the fastest dynamics (same as ‘zc’ in mask_sift), or a pre-specified mask.

Parameters:

Xndarray

1D input array containing the time-series data to be decomposed

mask_0{array_like, ‘zc’, ‘random’}

Initial mask for the iteration process, can be one of:

‘zc’ or ‘if’ initialises with the masks chosen by the zero-crossing

count or instantaneous frequency method in the standard mask sift.

‘random’ chooses random integers between 0 and sample_rate/4 as the starting mask.

seed=int can be optionally passed to control the random seed in numpy.

array-like needs to be in normalised units, i.e. divided by the sample rate.

(Default value = ‘zc’)

w_method{‘amplitude’, ‘power’, float, None}

Weighting method to use in the iteration process. ‘amplitude’ weights frequencies by the instantaneous amplitude, ‘power’ by its square. If a float is passed, the amplitude is raised to that exponent before averaging. None performs a simple average without weighting. (Default value = ‘power’)

max_imfsint

The maximum number of IMFs to compute. (Default value = 6)

max_iterint

The maximum number of iterations to compute. (Default value = 15)

iter_thfloat

Relative mask variability threshold below which iteration is stopped. (Default value = 0.1)

N_avgint

Number of iterations to average after convergence is reached. (Default value = 1)

exlude_edgesbool

If True, excludes first and last 2.5% of frequency data during the iteration process to avoid edge effects. (Default value = False)

sample_ratefloat

Sampling rate of the data in Hz (Default value = 1.0)

seedint or None

Random seed to use for random initial mask selection when mask_0 = ‘random’

**kwargs

Any additional arguments for the standard emd.sift.mask_sift can be specified - see the documentation for emd.sift.mask_sift for more details.

Returns:

imfndarray: 2D array [samples x nimfs] containing he Intrisic Mode Functions from the decomposition of X.
mask_freqsndarray: 1D array of mask frequencies, if ret_mask_freq is set to True.

See also

emd.sift.mask_sift
emd.sift.get_next_imf_mask

Notes

Here are some example iterated_mask_sift variants you can run:

An iterated mask sift in which the mask frequencies are determined with zero-crossings and iteration stop at 15 iterations or if masks stabilize to within 10% (note - this is also the default):

>>> imf = emd.sift.iterated_mask_sift(X, sample_rate, mask_0='zc',
                                      max_iter=15, iter_th=0.1)

An iterated mask sift in which a custom initial mask is used and after convergence 5 further iterations are averaged:

>>> imf = emd.sift.iterated_mask_sift(X, sample_rate,
                                      mask_0=[10, 5, 3, 1]/sample_rate,
                                      N_avg=5)

An iterated mask sift weighted by instantaneous amplitude that also returns the automatically determined mask and excludes 5% of edge data to avoid edge effectd:

>>> imf, mask = emd.sift.iterated_mask_sift(X, sample_rate, w_method='amplitude',
                                            exclude_edges=True, ret_mask_freq=True)

References

[1]

Ryan Deering, & James F. Kaiser. (2005). The Use of a Masking Signal to Improve Empirical Mode Decomposition. In Proceedings. (ICASSP ’05). IEEE International Conference on Acoustics, Speech, and Signal Processing, 2005. IEEE. https://doi.org/10.1109/icassp.2005.1416051

[2]

Tsai, F.-F., Fan, S.-Z., Lin, Y.-S., Huang, N. E., & Yeh, J.-R. (2016). Investigating Power Density and the Degree of Nonlinearity in Intrinsic Components of Anesthesia EEG by the Hilbert-Huang Transform: An Example Using Ketamine and Alfentanil. PLOS ONE, 11(12), e0168108. https://doi.org/10.1371/journal.pone.0168108

[3]

Marco S. Fabus, Andrew J. Quinn, Catherine E. Warnaby, and Mark W. Woolrich (2021). Automatic decomposition of electrophysiological data into distinct nonsinusoidal oscillatory modes. Journal of Neurophysiology 2021 126:5, 1670-1684. https://doi.org/10.1152/jn.00315.2021