Module reference¶
SIFT Functions¶
-
emd.sift.
sift
(X, sift_thresh=1e-08, max_imfs=None, imf_opts={}, envelope_opts={}, extrema_opts={})[source]¶ Compute Intrinsic Mode Functions from an input data vector using the original sift algorithm [1].
Parameters: - X : ndarray
1D input array containing the time-series data to be decomposed
- sift_thresh : scalar
The threshold at which the overall sifting process will stop. (Default value = 1e-8)
- max_imfs : int
The maximum number of IMFs to compute. (Default value = None)
Returns: - imf: ndarray
2D array [samples x nimfs] containing he Intrisic Mode Functions from the decomposition of X.
Other Parameters: - imf_opts : dict
Optional dictionary of keyword options to be passed to emd.get_next_imf
- envelope_opts : dict
Optional dictionary of keyword options to be passed to emd.interp_envelope
- extrema_opts : dict
Optional dictionary of keyword options to be passed to emd.get_padded_extrema
See also
References
[1] Huang, N. E., Shen, Z., Long, S. R., Wu, M. C., Shih, H. H., Zheng, Q., … Liu, H. H. (1998). The empirical mode decomposition and the Hilbert spectrum for nonlinear and non-stationary time series analysis. Proceedings of the Royal Society of London. Series A: Mathematical, Physical and Engineering Sciences, 454(1971), 903–995. https://doi.org/10.1098/rspa.1998.0193
-
emd.sift.
ensemble_sift
(X, nensembles=4, ensemble_noise=0.2, noise_mode='single', nprocesses=1, sift_thresh=1e-08, max_imfs=None, imf_opts={}, envelope_opts={}, extrema_opts={})[source]¶ Compute Intrinsic Mode Functions from an input data vector using the ensemble empirical model decomposition algorithm [1]. This approach sifts an ensemble of signals with white-noise added and treats the mean IMFs as the result.
The resulting IMFs from the ensemble sift resembles a dyadic filter [2].
Parameters: - X : ndarray
1D input array containing the time-series data to be decomposed
- nensembles : int
Integer number of different ensembles to compute the sift across.
- ensemble_noise : scalar
Standard deviation of noise to add to each ensemble (Default value = .2)
- noise_mode : {‘single’,’flip’}
Flag indicating whether to compute each ensemble with noise once or twice with the noise and sign-flipped noise (Default value = ‘single’)
- nprocesses : integer
Integer number of parallel processes to compute. Each process computes a single realisation of the total ensemble (Default value = 1)
- sift_thresh : scalar
The threshold at which the overall sifting process will stop. (Default value = 1e-8)
- max_imfs : int
The maximum number of IMFs to compute. (Default value = None)
Returns: - imf : ndarray
2D array [samples x nimfs] containing he Intrisic Mode Functions from the decomposition of X.
Other Parameters: - imf_opts : dict
Optional dictionary of keyword options to be passed to emd.get_next_imf.
- envelope_opts : dict
Optional dictionary of keyword options to be passed to emd.interp_envelope
- extrema_opts : dict
Optional dictionary of keyword options to be passed to emd.get_padded_extrema
See also
References
[1] Wu, Z., & Huang, N. E. (2009). Ensemble Empirical Mode Decomposition: A Noise-Assisted Data Analysis Method. Advances in Adaptive Data Analysis, 1(1), 1–41. https://doi.org/10.1142/s1793536909000047 [2] Wu, Z., & Huang, N. E. (2004). A study of the characteristics of white noise using the empirical mode decomposition method. Proceedings of the Royal Society of London. Series A: Mathematical, Physical and Engineering Sciences, 460(2046), 1597–1611. https://doi.org/10.1098/rspa.2003.1221
-
emd.sift.
complete_ensemble_sift
(X, nensembles=4, ensemble_noise=0.2, noise_mode='single', nprocesses=1, sift_thresh=1e-08, max_imfs=None, imf_opts={}, envelope_opts={}, extrema_opts={})[source]¶ Compute Intrinsic Mode Functions from an input data vector using the complete ensemble empirical model decomposition algorithm [1]. This approach sifts an ensemble of signals with white-noise added taking a single IMF across all ensembles at before moving to the next IMF.
Parameters: - X : ndarray
1D input array containing the time-series data to be decomposed
- nensembles : int
Integer number of different ensembles to compute the sift across.
- ensemble_noise : scalar
Standard deviation of noise to add to each ensemble (Default value = .2)
- noise_mode : {‘single’,’flip’}
Flag indicating whether to compute each ensemble with noise once or twice with the noise and sign-flipped noise (Default value = ‘single’)
- nprocesses : integer
Integer number of parallel processes to compute. Each process computes a single realisation of the total ensemble (Default value = 1)
- sift_thresh : scalar
The threshold at which the overall sifting process will stop. (Default value = 1e-8)
- max_imfs : int
The maximum number of IMFs to compute. (Default value = None)
Returns: - imf: ndarray
2D array [samples x nimfs] containing he Intrisic Mode Functions from the decomposition of X.
- noise: array_like
The Intrisic Mode Functions from the decomposition of X.
Other Parameters: - imf_opts : dict
Optional dictionary of keyword options to be passed to emd.get_next_imf.
- envelope_opts : dict
Optional dictionary of keyword options to be passed to emd.interp_envelope
- extrema_opts : dict
Optional dictionary of keyword options to be passed to emd.get_padded_extrema
See also
References
[1] Torres, M. E., Colominas, M. A., Schlotthauer, G., & Flandrin, P. (2011). A complete ensemble empirical mode decomposition with adaptive noise. In 2011 IEEE International Conference on Acoustics, Speech and Signal Processing (ICASSP). IEEE. https://doi.org/10.1109/icassp.2011.5947265
-
emd.sift.
mask_sift_adaptive
(X, sift_thresh=1e-08, max_imfs=None, mask_amp=1, mask_amp_mode='ratio_imf', mask_step_factor=2, ret_mask_freq=False, first_mask_mode='if', imf_opts={}, envelope_opts={}, extrema_opts={})[source]¶ Compute Intrinsic Mode Functions from a dataset using a set of masking signals to reduce mixing of components between modes.
The simplest masking signal approach uses single mask for each IMF after the first is computed as normal [1]. This has since been expanded to the complete mask sift which uses a set of positive and negative sign sine and cosine signals as masks for each IMF. The mean of the four is taken as the IMF.
Parameters: - X : ndarray
1D input array containing the time-series data to be decomposed
- sd_thresh : scalar
The threshold at which the sift of each IMF will be stopped. (Default value = .1)
- sift_thresh : scalar
The threshold at which the overall sifting process will stop. (Default value = 1e-8)
- max_imfs : int
The maximum number of IMFs to compute. (Default value = None)
- mask_amp : scalar or array_like
Amplitude of mask signals as specified by mask_amp_mode. If scalar the same value is applied to all IMFs, if an array is passed each value is applied to each IMF in turn (Default value = 1)
- mask_amp_mode : {‘abs’,’imf_ratio’,’sig_ratio’}
Method for computing mask amplitude. Either in absolute units (‘abs’), or as a ratio of the amplitude of the input signal (‘ratio_signal’) or previous imf (‘ratio_imf’) (Default value = ‘ratio_imf’)
- mask_step_factor : scalar
Step in frequency between successive masks (Default value = 2)
- ret_mask_freq : bool
Boolean flag indicating whether mask frequencies are returned (Default value = False)
- mask_initial_freq : scalar
Frequency of initial mask as a proportion of the sampling frequency (Default value = None)
- interp_method : {‘mono_pchip’,’splrep’,’pchip’}
The interpolation method used when computing upper and lower envelopes (Default value = ‘mono_pchip’)
Returns: - imf : ndarray
2D array [samples x nimfs] containing he Intrisic Mode Functions from the decomposition of X.
- mask_freqs : ndarray
1D array of mask frequencies, if ret_mask_freq is set to True.
Other Parameters: - imf_opts : dict
Optional dictionary of keyword arguments to be passed to emd.get_next_imf
- envelope_opts : dict
Optional dictionary of keyword options to be passed to emd.interp_envelope
- extrema_opts : dict
Optional dictionary of keyword options to be passed to emd.get_padded_extrema
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
-
emd.sift.
mask_sift_specified
(X, sd_thresh=0.1, max_imfs=None, mask_amp=1, mask_amp_mode='ratio_imf', mask_step_factor=2, ret_mask_freq=False, mask_initial_freq=None, mask_freqs=None, mask_amps=None, imf_opts={}, envelope_opts={}, extrema_opts={})[source]¶ Compute Intrinsic Mode Functions from a dataset using a set of masking signals to reduce mixing of components between modes.
The simplest masking signal approach uses single mask for each IMF after the first is computed as normal [1]. This has since been expanded to the complete mask sift which uses a set of positive and negative sign sine and cosine signals as masks for each IMF. The mean of the four is taken as the IMF.
Parameters: - X : ndarray
1D input array containing the time-series data to be decomposed
- sd_thresh : scalar
The threshold at which the sift of each IMF will be stopped. (Default value = .1)
- sift_thresh : scalar
The threshold at which the overall sifting process will stop. (Default value = 1e-8)
- max_imfs : int
The maximum number of IMFs to compute. (Default value = None)
- mask_amp : scalar or array_like
Amplitude of mask signals as specified by mask_amp_mode. If scalar the same value is applied to all IMFs, if an array is passed each value is applied to each IMF in turn (Default value = 1)
- mask_amp_mode : {‘abs’,’imf_ratio’,’sig_ratio’}
Method for computing mask amplitude. Either in absolute units (‘abs’), or as a ratio of the amplitude of the input signal (‘ratio_signal’) or previous imf (‘ratio_imf’) (Default value = ‘ratio_imf’)
- mask_step_factor : scalar
Step in frequency between successive masks (Default value = 2)
- ret_mask_freq : bool
Boolean flag indicating whether mask frequencies are returned (Default value = False)
- mask_initial_freq : scalar
Frequency of initial mask as a proportion of the sampling frequency (Default value = None)
- mask_freqs : array_like
1D array, list or tuple of mask frequencies as a proportion of the sampling frequency (Default value = None)
- interp_method : {‘mono_pchip’,’splrep’,’pchip’}
The interpolation method used when computing upper and lower envelopes (Default value = ‘mono_pchip’)
Returns: - imf : ndarray
2D array [samples x nimfs] containing he Intrisic Mode Functions from the decomposition of X.
- mask_freqs : ndarray
1D array of mask frequencies, if ret_mask_freq is set to True.
Other Parameters: - imf_opts : dict
Optional dictionary of keyword arguments to be passed to emd.get_next_imf
- envelope_opts : dict
Optional dictionary of keyword options to be passed to emd.interp_envelope
- extrema_opts : dict
Optional dictionary of keyword options to be passed to emd.get_padded_extrema
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
-
emd.sift.
get_next_imf
(X, sd_thresh=0.1, env_step_size=1, envelope_opts={}, extrema_opts={})[source]¶ Compute the next IMF from a data set. This is a helper function used within the more general sifting functions.
Parameters: - X : ndarray [nsamples x 1]
1D input array containing the time-series data to be decomposed
- sd_thresh : scalar
The threshold at which the sift of each IMF will be stopped. (Default value = .1)
- env_step_size : float
Scaling of envelope prior to removal at each iteration of sift. The average of the upper and lower envelope is muliplied by this value before being subtracted from the data. Values should be between 0 > x >= 1 (Default value = 1)
Returns: - proto_imf : ndarray
1D vector containing the next IMF extracted from X
- continue_flag : bool
Boolean indicating whether the sift can be continued beyond this IMF
Other Parameters: - envelope_opts : dict
Optional dictionary of keyword arguments to be passed to emd.interp_envelope
- extrema_opts : dict
Optional dictionary of keyword options to be passed to emd.get_padded_extrema
See also
emd.sift.sift
emd.sift.interp_envelope
-
emd.sift.
get_next_imf_mask
(X, z, amp, mask_type='all', imf_opts={}, envelope_opts={}, extrema_opts={})[source]¶ Compute the next IMF from a data set using the mask sift appraoch. This is a helper function used within the more general sifting functions.
Parameters: - X : ndarray
1D input array containing the time-series data to be decomposed
- z : scalar
Mask frequency as a proportion of the sampling rate, values between 0->z->.5
- amp : scalar
Mask amplitude
- mask_type : {‘all’,’sine’,’cosine’}
Flag indicating whether to apply sine, cosine or all masks (Default value = ‘all’)
Returns: - proto_imf : ndarray
1D vector containing the next IMF extracted from X
Other Parameters: - imf_opts : dict
Optional dictionary of keyword arguments to be passed to emd.get_next_imf
- envelope_opts : dict
Optional dictionary of keyword options to be passed to emd.interp_envelope
- extrema_opts : dict
Optional dictionary of keyword options to be passed to emd.get_padded_extrema
See also
emd.sift.mask_sift
emd.sift.get_next_imf
Frequency Functions¶
-
emd.spectra.
frequency_stats
(imf, sample_rate, method, smooth_phase=31)[source]¶ Compute instantaneous phase, frequency and amplitude from a set of IMFs. Several approaches are implemented from [1] and [2].
Parameters: - imf : ndarray
Input array of IMFs.
- sample_rate : scalar
Sampling frequency of the signal in Hz
- method : {‘hilbert’,’quad’,’direct_quad’,’nht’}
The method for computing the frequency stats
- smooth_phase : integer
Length of window when smoothing the unwrapped phase (Default value = 31)
Returns: - IP : ndarray
Array of instantaneous phase estimates
- IF : ndarray
Array of instantaneous frequency estimates
- IA : ndarray
Array of instantaneous amplitude estimates
References
[1] Huang, N. E., Shen, Z., Long, S. R., Wu, M. C., Shih, H. H., Zheng, Q., … Liu, H. H. (1998). The empirical mode decomposition and the Hilbert spectrum for nonlinear and non-stationary time series analysis. Proceedings of the Royal Society of London. Series A: Mathematical, Physical and Engineering Sciences, 454(1971), 903–995. https://doi.org/10.1098/rspa.1998.0193 [2] Huang, N. E., Wu, Z., Long, S. R., Arnold, K. C., Chen, X., & Blank, K. (2009). On Instantaneous Frequency. Advances in Adaptive Data Analysis, 1(2), 177–229. https://doi.org/10.1142/s1793536909000096
-
emd.spectra.
quadrature_transform
(X)[source]¶ Compute the quadrature transform on a set of time-series as defined in equation 34 of [1]. The return is a complex array with the input data as the real part and the quadrature transform as the imaginary part.
Parameters: - X : ndarray
Array containing time-series to transform
Returns: - quad_signal : ndarray
Complex valued array containing the quadrature transformed signal
References
[1] Huang, N. E., Wu, Z., Long, S. R., Arnold, K. C., Chen, X., & Blank, K. (2009). On Instantaneous Frequency. Advances in Adaptive Data Analysis, 1(2), 177–229. https://doi.org/10.1142/s1793536909000096
-
emd.spectra.
phase_from_complex_signal
(complex_signal, smoothing=None, ret_phase='wrapped', phase_jump='ascending')[source]¶ Compute the instantaneous phase from a complex signal obtained from either the Hilbert Transform or by Direct Quadrature.
Parameters: - complex_signal : complex ndarray
Complex valued input array
- smoothing : int
Integer window length used in phase smoothing (Default value = None)
- ret_phase : {‘wrapped’,’unwrapped’}
Flag indicating whether to return the wrapped or unwrapped phase (Default value = ‘wrapped’)
- phase_jump : {‘ascending’,’peak’,’descending’,’trough’}
Flag indicating where in the cycle the phase jump should be (Default value = ‘ascending’)
Returns: - IP : ndarray
Array of instantaneous phase values
-
emd.spectra.
freq_from_phase
(iphase, sample_rate)[source]¶ Compute the instantaneous frequency from the differential of the instantaneous phase.
Parameters: - iphase : ndarray
Input array containing the unwrapped instantaneous phase time-course
- sample_rate : scalar
The sampling frequency of the data
Returns: - IF : ndarray
Array containing the instantaneous frequencies
-
emd.spectra.
phase_from_freq
(ifrequency, sample_rate, phase_start=-3.141592653589793)[source]¶ Compute the instantaneous phase of a signal from its instantaneous phase.
Parameters: - ifrequency : ndarray
Input array containing the instantaneous frequencies of a signal
- sample_rate : scalar
The sampling frequency of the data
- phase_start : scalar
Start value of the phase output (Default value = -np.pi)
Returns: - IP : ndarray
The instantaneous phase of the signal
-
emd.spectra.
direct_quadrature
(fm)[source]¶ Section 3.2 of ‘on instantaneous frequency’ Compute the quadrature transform on a set of time-series as defined in equation 35 of [1].
THIS IS IN DEVELOPMENT
Parameters: - fm :
References
[1] Huang, N. E., Wu, Z., Long, S. R., Arnold, K. C., Chen, X., & Blank, K. (2009). On Instantaneous Frequency. Advances in Adaptive Data Analysis, 1(2), 177–229. https://doi.org/10.1142/s1793536909000096
-
emd.spectra.
phase_angle
(fm)[source]¶ Compute the quadrature transform on a set of time-series as defined in equation 35 of [1].
THIS IS IN DEVELOPMENT
Parameters: - X : ndarray
Array containing time-series to transform
Returns: - quad_signal : ndarray
Complex valued array containing the quadrature transformed signal
References
[1] Huang, N. E., Wu, Z., Long, S. R., Arnold, K. C., Chen, X., & Blank, K. (2009). On Instantaneous Frequency. Advances in Adaptive Data Analysis, 1(2), 177–229. https://doi.org/10.1142/s1793536909000096
Spectrum Functions¶
-
emd.spectra.
hilberthuang_1d
(infr, inam, freq_edges, mode='energy')[source]¶ Compute the Hilbert-Huang transform from the instataneous frequency statistics of a dataset. The 1D Hilbert-Huang Transform represents the energy in a signal across frequencies and IMFs [1].
Parameters: - infr : ndarray
2D first level instantaneous frequencies
- inam : ndarray
2D first level instantaneous amplitudes
- freq_edges : ndarray
Vector of frequency bins for carrier frequencies
- mode : {‘energy’,’amplitude’}
Flag indicating whether to sum the energy or amplitudes (Default value = ‘energy’)
Returns: - specs : ndarray
2D array containing Hilbert-Huang Spectrum [ frequencies x imfs ]
References
[1] Huang, N. E., Shen, Z., Long, S. R., Wu, M. C., Shih, H. H., Zheng, Q., … Liu, H. H. (1998). The empirical mode decomposition and the Hilbert spectrum for nonlinear and non-stationary time series analysis. Proceedings of the Royal Society of London. Series A: Mathematical, Physical and Engineering Sciences, 454(1971), 903–995. https://doi.org/10.1098/rspa.1998.0193
-
emd.spectra.
hilberthuang
(infr, inam, freq_edges, mode='energy', return_sparse=False)[source]¶ Compute the Hilbert-Huang transform from the instataneous frequency statistics of a dataset. The Hilbert-Huang Transform represents the energy of a signal across time and frequency [1].
Parameters: - infr : ndarray
2D first level instantaneous frequencies
- inam : ndarray
2D first level instantaneous amplitudes
- freq_edges : ndarray
Vector of frequency bins for carrier frequencies
- mode : {‘energy’,’amplitude’}
Flag indicating whether to sum the energy or amplitudes (Default value = ‘energy’)
- return_sparse : bool
Flag indicating whether to return the full or sparse form(Default value = True)
Returns: - hht : ndarray
2D array containing the Hilbert-Huang Transform
Notes
If return_sparse is set to True the returned array is a sparse matrix in COOrdinate form (scipy.sparse.coo_matrix), also known as ‘ijv’ or ‘triplet’ form. This is much more memory efficient than the full form but may not behave as expected in functions expecting full arrays.
References
[1] Huang, N. E., Shen, Z., Long, S. R., Wu, M. C., Shih, H. H., Zheng, Q., … Liu, H. H. (1998). The empirical mode decomposition and the Hilbert spectrum for nonlinear and non-stationary time series analysis. Proceedings of the Royal Society of London. Series A: Mathematical, Physical and Engineering Sciences, 454(1971), 903–995. https://doi.org/10.1098/rspa.1998.0193
-
emd.spectra.
holospectrum
(infr, infr2, inam2, freq_edges, freq_edges2, mode='energy', squash_time='sum')[source]¶ Compute the Holospectrum from the first and second layer frequecy statistics of a dataset. The Holospectrum represents the energy of a signal across time, carrier frequency and amplitude-modulation frequency [1].
Parameters: - infr : ndarray
2D first level instantaneous frequencies
- infr2 : ndarray
3D second level instantaneous frequencies
- inam2 : ndarray
3D second level instantaneous amplitudes
- freq_edges : ndarray
Vector of frequency bins for carrier frequencies
- freq_edges2 :
Vector of frequency bins for amplitude-modulation frequencies
- mode : {‘energy’,’amplitude’}
Flag indicating whether to sum the energy or amplitudes (Default value = ‘energy’)
- squash_time : {‘sum’,’mean’,False}
Flag indicating whether to marginalise over the time dimension (Default value = ‘sum’)
Returns: - holo : ndarray
Holospectrum of input data.
Notes
Output will be a 3D [samples x am_freq x carrier_freq] array if squash_time is False and a 2D [ am_freq x carrier_freq ] array if squash_time is true.
References
[1] Huang, N. E., Hu, K., Yang, A. C. C., Chang, H.-C., Jia, D., Liang, W.-K., … Wu, Z. (2016). On Holo-Hilbert spectral analysis: a full informational spectral representation for nonlinear and non-stationary data. Philosophical Transactions of the Royal Society A: Mathematical, Physical and Engineering Sciences, 374(2065), 20150206. https://doi.org/10.1098/rsta.2015.0206
Spectrum Utils¶
-
emd.spectra.
define_hist_bins
(data_min, data_max, nbins, scale='linear')[source]¶ Define the bin edges and centre values for use in a histogram
Parameters: - data_min : scalar
Value for minimum edge
- data_max : scalar
Value for maximum edge
- nbins : integer
Number of bins to create
- scale : {‘linear’,’log’}
Flag indicating whether to use a linear or log spacing between bins (Default value = ‘linear’)
Returns: - edges : ndarray
1D array of bin edges
- centres : ndarray
1D array of bin centres
- Notes
- >> edges,centres = emd.spectra.define_hist_bins( 1, 5, 3 )
- >> print(edges)
- [1. 2. 3. 4. 5.]
- >> print(centres)
- [1.5 2.5 3.5 4.5]
-
emd.spectra.
define_hist_bins_from_data
(X, nbins=None, mode='sqrt', scale='linear')[source]¶ Find the bin edges and centre frequencies for use in a histogram
if nbins is defined, mode is ignored
Parameters: - X : ndarray
Dataset whose summary stats will define the histogram
- nbins : int
Number of bins to create, if undefined this is derived from the data (Default value = None)
- mode : {‘sqrt’}
Method for deriving number of bins if nbins is undefined (Default value = ‘sqrt’)
- scale : {‘linear’,’log’}
(Default value = ‘linear’)
Returns: - edges : ndarray
1D array of bin edges
- centres : ndarray
1D array of bin centres